# Configuring External Response Collaboration (QMS)

The External Response Collaboration feature set streamlines temporary, short-term access to your Vault for suppliers, partners, contractors, or other external parties to respond to your organization's audit findings, CAPAs, SCARs, SCNs, Effectiveness Checks, or Investigation requests on behalf of their company.

You can give users the ability to request responses from recognized external contacts, stored in Vault as _Person_ records. Users can then collaborate with those individuals in Vault, and close out activities or tasks with minimal or no need to manage user account provisioning. Vault invites these users to collaborate with specialized email messages, and can terminate access for their user accounts when the collaboration is complete.

This feature set is not intended to replace long-term or regular day-to-day interaction with external parties within your Vault. To understand whether your use case is best served with External Collaboration or [External Users](/en/lr/5721/), discuss with your Veeva team.

##  Supported Objects {#supported-objects}

The External Response Collaboration feature set supports inviting external participants to work on records of the following objects:

* _Audit_ (`audit__qdm`)
* _CAPA Action_ (`capa_action__qdm`)
* _Change Action_ (`change_action__qdm`)
* _Change Control_ (`change_control__v`)
* _Change Plan_ (`change_plan__v`)
* _Deviation_ (`deviation__v`)
* _Effectiveness Check_ (`effectiveness_check__qdm`)
* _Finding_ (`finding__v`)
* _Health Hazard Evaluation_ (`health_hazard_evaluation__v`)
* _Impact Assessment_ (`change_control_impact_assessment__v`)
* _Investigation_ (`investigation__qdm`)
* _Nonconformance_ (`nonconformance__v`)
* _Organization_ (`qms_organization__qdm`)
* _Qualification_ (`qms_org_qualification__v`)
* _Quality Event_ (`quality_event__qdm`): _External Finding_ object type
* _SCAR_ (`qms_scar__v`)
* _Supplier Change Notification_ (`supplier_change_notification__v`)

## About the Collaborating Object {#collaborating-object}

The object whose records the external collaborator will be expected to edit is described in this article as a _Collaborating Object_. This is the object whose lifecycle will contain the triggers and configurations to begin and end collaboration. While the _Collaborating Object_ is not a real Vault object, references to this object refer to any one of the [objects][17] described above.

## Configuration Overview

While the workflow specifics of each process that has External Collaboration enabled for it will differ at the workflow or lifecycle level, the configuration approach for all eligible processes is as follows:

  * Set up a [_Security Profile_][1] for use with external collaborators
  * Create a [_Quality External User Template_](/en/lr/64944/) for external collaborators
  * Configure the special [_Object Message Templates_][3]
  * Configure the [_Person_ object][4]
  * Configure the [_Organization_ object][5]
  * Configure the [_Collaborating Object_][6]
  * Configure the [_Collaborating Object_ lifecycle][7]
  * If necessary, configure the relevant [_Collaborating Object_ workflows][8]

## Setting Up User Security Profiles {#security-profile}

When Vault [automatically creates][9] _Users_, the system determines a specific _Security Profile_ to use for the external collaborator via a [_Quality External User Template_](/en/lr/64944/). Selecting an appropriate _Security Profile_ allows you to tailor the experience for the external party within your Vault to be as robust or simplified as necessary. While the specific permissions required will vary based on your organization's Vault configuration, a restricted set of permissions is recommended, such that minimal, if any, training is required for your external collaborators.

Vault provides tools to allow you to invite external users with security profiles specific to a given process, or wide enough to support any process the user might be invited for. It is important to note that a user's access does not change if they are invited to collaborate on two different processes. Thus, if you're supporting external collaboration, you should design your security configuration for external users to support all cases in which a given external party may be asked to participate within a single security profile. You can be permissive in this approach, as the external users will not be granted access (outside of what's described in the security profile) to any records that they're not invited to collaborate upon.

## Configuring Object Message Templates {#object-message-template}

External users may have varying degrees of familiarity with your Vault, or with Vault in general. This feature set includes specific email templates that you can [configure](/en/lr/2157/), which Vault automatically sends to third-party contacts based on how the contact is collaborating with your organization.

Vault sends a _Welcome Collaborator_ email to any third-party contact for which a Vault _User_ account has been automatically created. A _Welcome Back Collaborator_ email is provided for external collaborators who have had _User_ accounts in the past, but are being activated again to collaborate.

Vault sends a _Goodbye Collaborator_ email to third-party contacts when all of their assigned work is complete. A collaborator's work may complete at various times on a given process based on your Vault's configuration, but in principle, a collaborator's work is complete when their response is accepted by a member of your organization, and the _Goodbye Collaborator_ email is only sent when there are no more activities assigned to that collaborator across any external-collaboration-enabled process waiting for that collaborator's response in the Vault.

### Message Templates

Each supported object has three associated message templates:

  * _QMS External Collab Welcome_
  * _QMS External Collab Welcome Back_
  * _QMS External Collab Goodbye_

You can update the message templates to include information about the record, its parent _Audit_, and, if configured, the record's Quality Team members from your organization to ensure that the recipient knows what activities are required of them, as well as any additional information about collaboration with your organization.

### External Collaboration Message Template Tokens

While you can configure these messages as you would other [object messages](/en/lr/2157/), these templates have some special additional token functionality. These templates can include tokens for fields on the collaborating record, the collaborating record's related parent process object (_Audit_ or _Quality Event_) fields `${QMS.extcollab.[object name].[field name]}` and, if your processes utilize Quality Teams, _Quality Team Role_ `${QMS.extcollab.QTeam.[role name]}`. These tokens resolve via the _System_ _User_ account, thus an external collaborator receiving the message will be able to see the resolved token values regardless of whether their newly created _User_ account has access. Non-specialized Vault tokens resolving to the collaborating record's data are resolved via the external collaborator's security profile.

The _QMS External Collab Welcome_ message template can also include the special `${userName}` and `${userPassword}` tokens. Use of these tokens in the object message template functions similarly to a Vault automated [password reset email](/en/lr/7239/). Note that the external collaborator can still reset their password via the standard method.

## Configuring the Person Object {#person-object}

On the _Person_ object, activate one or more of the following object reference fields and add them to the _Person_ [object layout](/en/lr/26387/):

* _Health Authority_
* _Hospital_
* _Hospital Location_
* _Organization_
* _Organization Location_
* _Third Party_

## Configuring the Organization Objects {#organization-object}

Optionally, you can configure the following objects that represent different types of organizations to simplify the management of a contact list of _Persons_:

* _Health Authority_
* _Hospital_
* _Hospital Location_
* _Organization_
* _Organization Location_
* _Third Party_

_Person_ records have a [field][4] linking them to different types of organizations, and records representing these organizations can list the _Persons_ that your own organization interacts with. This allows for easier identification of contacts to whom you can assign records to collaborate on. You can manage these contacts centrally, or you can enable internal users to manage these persons independently for the organizations they work with.

To configure an organization object to display contact lists, add a _Person_ related object section to the object page layout of the organization objects listed above. It may be helpful to define [section level help](/en/lr/26387/#related-object) for this contact list such that its purpose is clear.

## Configuring the Collaborating Object {#quality-event-object}

You must make the following changes to the [_Collaborating Object_][16] object configuration to set up External Response Collaboration:

* Ensure the _Collaborate Externally?_ (`collaborate_externally__v`) and _External Collaborator_ (`external_collaborator__v`) fields are active and add them to the relevant object types.
* Add the _Collaborate Externally?_ field to the _Collaborating Object_ layout.
* <a id="ec-control"></a>Add the _External Collaborator Object Control_ to the _Collaborating Object_ layout. You can configure the object control to filter the External Collaborators available to select by any [organization object][5] referenced in an object field on the _Collaborating Object_, and by the _Contact_ object type or any custom object type on the _Person_ object. With this configuration, only external contacts associated with the specific organization referenced in the relevant organization object fields on a _Collaborating Object_ record are available to select from the _External Collaborator Object Control_. When adding the _External Collaborator Object Control_ to the _Organization_ object layout, only _Organization_ is available to select as the _Organization Object_. 
* If your organization uses custom security profiles and permission sets, ensure users have _View_ permission for the _External Collaborator Object Control_ on the relevant _Collaborating Object_.

### About the External Collaborator Field {#ec-field}

When users select an external contact from the _External Collaborator Object Control_ on a record, Vault automatically populates the _External Collaborator_ (`external_collaborator__v`) object field upon saving the record. Vault uses this field to activate, reassign, and deactivate External Collaborators. There is no need to add the _External Collaborator_ object field to the layout. If your configuration uses the _External Collaborator Object Control_, we do not recommend configuring VQL criteria on the _External Collaborator_ object field. The _External Collaborator Object Control_ filters external contacts based on the [organization][5] specified in the relevant object fields of a _Collaborating Object_ record without the need to configure VQL criteria for this purpose.

## Configuring the Collaborating Object Lifecycle {#quality-event-lifecycle}

Determine in which lifecycle state of the [_Collaborating Object_][16] you wish to bring an external collaborator into your Vault, and the state in which their _User_ account should be removed from your Vault. In general, the entry state should be the state that you wish to start getting responses from external collaborators, and the exit states should be the state in which you are done getting responses from external collaborators, and have accepted their response, or which indicate that the response is no longer required.

For the purposes of this configuration explanation, we will use the Audit Finding Response process' _External Finding (Quality Event)_'s _Issued_ lifecycle state as the entry state, and the _Response Approved_ state as the exit state.

### Configuring the External Collaborator Application Role

Add the _External Collaborator_ application role to the _Quality Event Lifecycle_. As this is the role that external collaborators will be added to or removed from via QMS automation, ensure that the role has appropriate permissions for each lifecycle state utilized with the applicable object type. While this role must be added to the lifecycle for any collaboration-enabled object (for instance, _External Finding (Quality Event)_, _CAPA Action_, or _SCAR_), you can change the label of the application role to best represent your business processes and Vault configuration.


<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: To restrict an external collaborator’s ability to edit a <em>Collaborating Object</em>’s fields during the collaboration process, configure Atomic Security for the <em>External Collaborator</em> application role’s access to desired fields.</p>
    </div>
  </div>
</div>



### Configuring the QMS: Activate Ext. Collaborator Entry Action {#activate-ext-collaborators-entry-action}

This entry action indicates the beginning of the collaboration experience within a given process' lifecycle and workflow. Configure in the appropriate state per your process' lifecycle configuration. For our configuration example, add the _QMS: Activate Ext. Collaborator_ entry action to the _Issued_ state, with the following condition: **Quality Event Type** > **equals** > **External Finding**. Note that for all collaboration-enabled objects, select the appropriate object type for which you wish to enable collaboration, as applicable to your Vault's configured processes. You must select a _QMS User Template_ for the system to use when creating the _User_ account.

This entry action attempts to activate a user account for the _Person_ record referenced in the [_External Collaborator_ field][2]. If Vault finds that a user account already exists with the same details as the _Person_, the system assigns that user account to the _Person,_ activates that user account and sends them a _QMS External Collab Welcome Back_ [message][14]. If there is no existing _User_, the system will create a new one, activate it, and send the _QMS External Collab Welcome_ message configured for the object upon which the _Person/User_ is being invited to collaborate.

_User_ records created by this action will have their _Managed by QMS Automation_ field set to _True_. Vault's External Collaboration framework will only perform automated actions, including activation or inactivation, on _Users_ who have this flag set to _True_.

### Configuring the QMS: Inactivate Ext. Collaborator Entry Action {#inactivate-entry-action}

This action indicates the end of collaboration within a given process. When executed, Vault will verify if there are additional collaboration tasks across all processes for this external user, and will inactivate the user if appropriate. Following our configuration example, add the _QMS: Inactivate Ext. Collaborator_ entry action to the _Response Approved_ state and _Cancelled_ state with the following condition (using the Audit Finding example use case): **Quality Event Type** > **equals** > **External Finding**. This entry action finds the person in the [_External Collaborator_ field][2], identifies the user account associated with them, and then checks to see if this user account can be deactivated.

To accomplish this, Vault checks to see if the user account has any role assignments on any collaboration-enabled object records, granted by either of the _QMS: Activate Ext. Collaborator_ actions, which have not yet had the _QMS: Inactivate Ext. Collaborator_ entry action triggered. If the user account is not found to be working in the Vault on other processes, for example, responding to other _Quality Events_, _CAPAs_ or _SCARs_, Vault deactivates the _User_ account and sends the _QMS External Collab Goodbye_ message based upon whichever type of collaboration-enabled object record triggered the inactivation.

In complex configurations with collaboration spanning multiple processes, this means that which "goodbye" email message template is used may not be predictable. We recommend configuring your message templates generically enough to make sense for a collaborator regardless of which process triggers the end of collaboration.

Note that deactivated users are not removed from _Sharing Settings_ on individual records by default. If you wish to limit external collaborators' access to these records in the event that their _User_ account is reactivated, you must add an _Update Sharing Settings_ step in the applicable object workflow to do so.

Optionally, removing or changing the _External Collaborator_ value on the [_Collaborating Object_][16] record will trigger inactivation for that user, as if the _QMS: Inactivate Ext. Collaborator_ entry action had been invoked. Additionally, this action removes the _User_ from _Sharing Settings_ on that record automatically. If the collaborator is changed, the collaborating record will need to have the _QMS: Activate Ext. Collaborator_ action performed on it again with the new _Person_ in the [_External Collaborator_ field][2] before the new _Person/User_ will be invited to the Vault. We recommend prohibiting changes to the _External Collaborator_ field in lifecycle states where collaboration is expected, requiring users to navigate the record to a pre-collaboration state in order to change collaborators, so that record or content access and task assignment is as simple as possible.

### Configuring the Reassign External Collaborator User Action

Add the _Reassign External Collaborator_ user action to any object lifecycle that utilizes External Collaboration, such as the _In Audit Preparation_ state of the _Audit Lifecycle_. Be sure to select a _User Template_, which will set up the _User_ record if the _Person_ does not have an existing _User_ record in Vault. Select the **Include Checklist Reassignment** checkbox to reassign any associated checklists when the external collaborator on a [_Collaborating Object_][16] record is replaced. Vault does not reassign completed checklists.

If you configured the [_External Collaborator Object Control_][10] to filter external collaborators by organization object and _Person_ object type, you must select those same **Organization Objects** and **Person Object Types** when configuring the _Reassign External Collaborator_ action.

Whenever an external collaborator is removed or changed via the _Reassign External Collaborator_ user action, Vault evaluates if the associated user account should be deactivated following the same logic as the _QMS: Inactivate Ext. Collaborator_ entry action, with the following added function: The associated user account will be removed from the External Collaborator application role.

### Configuring the QMS: Activate Ext. Collaborator User Action

Add the _QMS: Activate Ext. Collaborator_ user action to states in which users may need to replace a deactivated external collaborator, such as when an external user is removed from the *Quality Event*'s [_External Collaborator_ field][2]. It is recommended that you restrict access to this action via [Atomic Security](/en/lr/47850/#Atomic_Security_Actions). Most configurations will not need to use the user action, as the entry action is more appropriate to ensure the right process is followed when changing collaborators.

Alternatively, your organization can choose to prevent changes to the _External Collaborator_ field in a state where a collaboration response is expected via field-level Atomic Security, and instead use workflow steps or lifecycle action configurations to move the record into a pre-response state. In such a process flow, after an internal user changes the state, indicating that a new collaborator should be assigned any relevant workflow tasks, the collaboration process may be restarted as normal.

## Configuring the Collaborating Object Workflow {#quality-event-object-workflows}

Collaboration with external contacts may result in cases where an internal user needs to provide a response on behalf of the external collaborator, or to forgo collaboration on a specific finding, or any findings with specific partners. Be sure to account for internal users' ability to take these operations or bypass collaboration when necessary when configuring your lifecycles and workflows.

 [1]: #security-profile
 [2]: #ec-field
 [3]: #object-message-template
 [4]: #person-object
 [5]: #organization-object
 [6]: #quality-event-object
 [7]: #quality-event-lifecycle
 [8]: #quality-event-object-workflows
 [9]: #activate-ext-collaborators-entry-action
 [10]: #ec-control
 [14]: #object-message-template-configuration
 [16]: #collaborating-object
 [17]: #supported-objects