Add Collaborators

Purpose

This subtopic addresses the need to programmatically add collaborators to specific Qualtrics surveys with precise permission settings. Within the broader context of managing survey collaboration, it enables automation of what is usually a manual process—inviting users to access and work on surveys by specifying their email addresses and granting appropriate permissions. This removes the dependency on manual UI interactions and expedites collaborative workflows, especially useful in bulk or scripted environments.

Functionality

The core workflow centers on the `add_collaborator` method of the `CollaborationClient` class. This method:

• Constructs an authenticated POST request targeting the Qualtrics survey collaboration API endpoint specific to a survey ID.

• Assembles a detailed payload that specifies the collaborator's username (generally an email) alongside a comprehensive set of permissions. These permissions control what actions the collaborator can perform on the survey, such as editing questions, viewing results, activating surveys, and more.

• Generates custom HTTP headers, including unique request and transaction IDs and security tokens, to conform with Qualtrics API requirements.

• Sends the request within an authenticated session that maintains cookies and headers obtained during the automated login phase.

This approach encapsulates the complexity of the API's expected data structure and headers, ensuring a seamless addition of collaborators with full control over their permission scope.

Key snippet illustrating collaborator addition:

def add_collaborator(self, survey_id: str, collaboration_username: str) -> dict[str, str]:
    url = f'https://{self.subdomain}.qualtrics.com/survey-collaboration/v1/shares/{survey_id}'

    payload = {
        'shareStatus': f'{{"{collaboration_username}":"added"}}',
        'shareType': f'{{"{collaboration_username}":"Invitation"}}',
        'inviteDetails': f'{{"{collaboration_username}":{{}}}}',
        'inviteMessages': '{}',
        'permissions': f'{{"{collaboration_username}":{{"viewSurveys":true,"editSurveys":true, ... }}}}',
        'SurveyID': survey_id
    }

    headers = self._generate_qualtrics_headers(content_type='application/x-www-form-urlencoded; charset=utf-8')

    resp = self.session.post(url, headers=headers, data=payload)
    return resp.text

This method abstracts the detailed permission settings into a JSON-like string format embedded in the form-encoded payload, aligning with Qualtrics' API expectations.

Integration

The `add_collaborator` subtopic tightly integrates with the parent topic of Survey Collaboration Management by implementing one of its fundamental collaborative actions—adding collaborators. It leverages session state and authentication established through the automated login subtopic (handled by Selenium automation and stored in a `requests.Session` with cookies and tokens).

Furthermore, it complements the "Accept Collaboration Codes" subtopic by focusing on the outbound invitation process, whereas accepting collaboration codes handles inbound access. Together, these subtopics provide a full collaboration lifecycle: inviting collaborators and accepting invitations.

The method also depends on internal helpers like `_generate_qualtrics_headers` to ensure requests are properly authenticated and formatted, which ties into the session and API request management subtopic. This coordination ensures consistent header generation and session continuity across various collaboration-related API calls.

Diagram

sequenceDiagram
    participant Client as CollaborationClient
    participant Login as Selenium Login
    participant Session as Requests Session
    participant API as Qualtrics Collaboration API

    Client->>Login: Perform automated login
    Login-->>Session: Set authenticated cookies and tokens
    Client->>Session: Prepare POST request with collaborator data
    Session->>API: Send add collaborator request (survey_id, collaborator_username, permissions)
    API-->>Session: Respond with status
    Session-->>Client: Return response text

This sequence diagram visualizes the process flow of adding a collaborator: starting with authentication, continuing with session preparation, and culminating in the API request to add the collaborator with the specified permissions. It highlights how the subtopic orchestrates interactions across components to fulfill its purpose.