# Configuring External Collaboration Management (QMS)

<!--QMS Audit Management Admin section-->
<!--Source File, original slug /76844/-->



<a href="/en/gr/78610/">QualityOne Vaults</a> allow users to efficiently <a href="/en/gr/713483/">manage</a> temporary, short-term access to your Vault for external collaborators by eliminating manual Vault account creation, activation, and inactivation. Setting up external collaborators with temporary access allows external users to respond to your organization's collaboration requests using an external license from a dedicated pool of external licenses. You can give users the ability to request responses from recognized external contacts, collaborate with those individuals in Vault, and finish with minimal or no need to manage user account provisioning for those external collaborators.

When users request collaboration from external contacts on [supported object records][14], Vault automates the provisioning of _External Collaborator_ accounts for those contacts and invites them to collaborate by sending specialized email notifications. When external contacts respond to all requests assigned to them, Vault automatically inactivates external user accounts, freeing up external licenses for other new external contacts with collaboration requests to use.

<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>: This feature enables external users to collaborate on QMS objects. If you need External Collaboration for document review and approval, see <a href="/en/gr/679760/">Configuring External Collaboration for Document Review &amp; Approval</a> for more details.</p>
    </div>
  </div>
</div>



## External Collaboration Target Objects {#target-objects}

You can configure supported QMS objects as [target objects][13] for External Collaboration Management. When configured, target object records display the relevant fields needed for users to assign external contacts.

* **CAR** (`car__v`): This object represents corrective action requests.
* **NCR** (`ncr__v`): This object represents nonconformances.
* **Audit** (`audit__qdm`): This object represents audits.
* **Audit Finding** (`audit_finding__v`): This object represents a finding in an audit.
* **Action Item** (`action_item__qdm`): This object represents an action item associated with a quality process.
* **Change Control** (`change_control__v`): This object represents change requests.
* **Inspection** (`inspection__v`): This object represents inspections.

## Configuration Overview {#overview}

Configuring your Vault to use External Collaboration Management involves the following steps:

1. Set up a _[Security Profile][1]_ for use with external collaborators
2. Define an [External Collaborator User Template][2] for _External Collaborators_
3. Configure _[Object Notification Templates][3]_
4. Configure the [_Person_, _Organization_, and target objects][4]
5. Configure the [target object lifecycle][5]
6. Configure the [target object actions][6]
7. Optionally, configure the relevant target object [workflows][7]

<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>: Depending on your Vault’s creation date and which features are currently enabled and configured, some of the steps described in this article may be unavailable or already complete in your Vault.</p>
    </div>
  </div>
</div>



## Setting Up User Security Profile {#setup-security-profile}

When [Vault automatically][6] creates _Users_, Vault determines a specific _Security Profile_ to use for the external collaborator via an [External Collaborator User Template][2]. Ensure you <a href="/en/gr/23647/">set up an appropriate Security Profile</a> to use for the _External Collaborator User Template_. Setting up an appropriate _Security Profile_ tailors the experience for the external user within your Vault to be as robust or simplified as necessary. We recommend "External Collaborator" as the label for the new _Security Profile_.

<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>: The Security Profile you set up for External Collaborators cannot grant any permissions that the internal users who invite External Collaborators to collaborate on object records do not also have.</p>
    </div>
  </div>
</div>



## Defining External Collaborator User Templates {#define-user-template}

You can configure your Vault to automate the creation and activation of _External Collaborators_. See <a href="/en/gr/76845/">Defining External Collaborator User Templates</a> for more details.

## Configuring Object Notification Templates {#message-template}

There are three (3) email notification templates for each [target object][14] you can <a href="/en/gr/2157/">configure</a> to which Vault automatically sends to third-party contacts based on the way the external user is collaborating with your organization. When Vault automatically creates a _User_ account, Vault sends a _Welcome_ email to that third-party contact. When an external collaborator is activated again to collaborate, Vault reactivates the _User_ account and sends a _Welcome Back_ email to that third-party contact.

Vault sends a _Goodbye_ email to third-party contacts when their work is complete. Depending on your configuration, an external collaborator's work may be complete at <a href="/en/gr/30683/">various lifecycle states</a> on a given request. Vault sends the _Goodbye_ email when the external collaborator's response is accepted, and no more requests are waiting for the collaborator's response in the Vault.

### Notification Templates {#notif-template}

The relevant notification templates are:

* <em>External Collaboration Welcome - [target_object_label]</em> (<code>ext_collab_welcome_[target_object_name]__v</code>)
* <em>External Collaboration Welcome Back - [target_object_label]</em> (<code>ext_collab_welcome_back_[target_object_name]__v</code>)
* <em>External Collaboration Goodbye - [target_object_label]</em> (<code>ext_collab_goodbye_[target_object_name]__v</code>)

You can update the notification templates to include information about the request, the request's parent object record (for example, _SCAR_), and if configured, the parent object record's <a href="/en/gr/70761/">Team</a> members from your organization. Configuring the notification templates ensures that the recipient knows what actions are required and receives any additional relevant information about collaborating with your organization.

### External Collaboration Notification Template Tokens {#template-token}

You can configure additional token support using standard <a href="/en/gr/2157/">object notification configurations</a>. <a href="/en/gr/6382/">Tokens</a> are pieces of text that are replaced at the time the notification template is used. You can use the following tokens within the email content for document notification templates:

* `firstName`: The recipient's first name.
* `lastName`: The recipient's last name.
* `authServiceExtUrl`: The authorized URL to login page.
* `staticContentBaseUrl`: This displays images.
* `userName`: The user's username.
* `userEmail`: The user's email address.
* `vaultName`: The name of the internal user's Vault.
* `userLanguage`: This displays the recipient's language. This is part of the one-time password reset link.
* `userPassword`: This displays the recipient's automated password.
* `utp?url`:  This is part of the one-time password reset link.

You can also include the special `${creator}` and `$($creatorEmail)` tokens in these notification templates. Use of these special tokens in the object notification template allows you to add the name and email of the object record creator.


<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>: External collaborators can still <a href="/en/gr/7239/#how-to-reset-your-forgotten-password-or-retrieve-user-name">reset their password</a> via the standard method.</p>
    </div>
  </div>
</div>



## Configuring External Collaborator Objects {#config-objects}

Configure the _Person_, _Organization_, and applicable [target objects][14] needed to configure automated Vault account creation, activation, and inactivation.

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

On the _Person_ object, activate the _Organization_ object reference field and add it to the _Person_ <a href="/en/gr/26387/">object layout</a>.

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

We recommend you configure the _Organization_ object to simplify the management of a contact list of _Persons_. _Person_ records have a field linking them to _Organizations_, and _Organization_ records can list the _Persons_ that your organization interacts with. This allows for easier identification of contacts listed in the _External Collaborator_ field that users can choose from to assign records to collaborate on, such as _SCARs_. You can manage these contacts centrally or you can enable requestors or other internal users to manage these persons independently for the _Organizations_ they work with.

To configure the _Organization_ object to display contact lists, insert a _Related Object_ section with the _Person_ object into the layout of the _Organization_ object. We recommend defining <a href="/en/gr/26387/#related-object">_Section Help_</a> for this contact list so that its purpose is clear to users.

### Configuring the Target Object {#config-target}

You must make the following modifications to any [target objects][14] that you plan to use for external collaboration.

#### Enabling Custom Sharing Rules {#enable-custom-sharing-rules}

You must enable <a href="/en/gr/25494/">Custom Sharing Rules</a> on the target object so that Vault can assign the correct application role to the external collaborator when the _Activate External Collaborator_ action runs. To do this:
1. Navigate to **Admin > Configuration > Objects > [target object] > Details**.
2. Click **Edit**.
3. In the _Options_ section under _Dynamic Access Control_, select the **Enable Custom Sharing Rules** checkbox. 
4. Click **Save**.

#### Configuring External Collaborator Field {#config-external-collab-field}

On the target object, activate the _External Collaborator_ field. We recommend you use the _Constrain Records in Referenced Object_ field option to limit the selection of the _External Collaborator_ to only persons within a related _Organization_. For example, you can add the following VQL statement:

<code>organization__v = {{this.supplier__v}}</code>

This statement limits the selection of _External Collaborators_ to the _Organization_ referenced in the _Supplier_ field of the target object. We recommend this configuration to ensure users choose appropriate collaborators for each request.

You can add the _External Collaborator_ field to the applicable target object type (for example, _SCAR_) and its corresponding <a href="/en/gr/26387/">layout</a>. The constraining field should be listed before the _External Collaborator_ field on the layout so that the constraints take effect prior to choosing an _External Collaborator_.

#### Configuring Organization Field {#config-supplier-field}

Optionally, you can establish a default value for the organization the request is against, based on the associated parent process' object. To do this, add the default organization value to the target object record's _Organization_ field.

On the target object, ensure there is at least one (1) active field that references the _Organization_ object. The following table shows the default target fields for _Organization_ for various target objects; field names and labels might be different depending on the object and your organization's configuration.

| Target Object | Target Field for Organization |
| ------------- | ----------------- |
| Audit (`audit_qdm`) | `external_auditor_organization__v` |
| Audit Finding (`audit_finding__v`) | `audited_organization__v` |
| CAR (`car__v`) | `organization__v` |
| Change Control (`change_control__v`) | `organization__v` |
| Inspection (`inspection__v`) | `supplier_name__v` OR `supplier_manufacturing_site_name__v` |
| NCR (`ncr__v`) | `organization__v` |

The _Audited Organization_ (`audited_organization__v`) field on the _Audit Findings_ object inherits the _Target Organization_ (`target_organization__qdm`) field value from the parent _Audit_ record, and cannot be updated manually.

## Configuring the Target Object Lifecycle {#lifecycle}

To configure your target object's lifecycle, you must first determine which lifecycle state of the target object you want to bring an external collaborator into your Vault (entry state) and the state in which their _User_ account should be removed from your Vault (exit state). The "entry" state should be the state that you want external collaborators to start giving responses and the "exit" state should be the state that you want external collaborators to stop responding, after accepting their responses. After determining your "entry" and "exit" states, configure your target object's lifecycle by adding the [application role][8] and [your object actions][6] for your two (2) states.

### External Collaborator Application Role {#external-collaborator-role}

Add the _External Collaborator_ <a href="/en/gr/36440/">application role</a> to the target object's lifecycle. As this is the role that external collaborators will be added to or removed from using the configuration from _[External Collaborator User Templates][2]_, ensure that the role has appropriate permissions for each lifecycle state utilized with the target object's object type.


<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 target object’s fields during the collaboration process, you must configure <a href="/en/gr/47850/">Atomic Security</a> for the <em>External Collaborator</em> application role’s access to the desired fields.</p>
    </div>
  </div>
</div>



## Configuring the Target Object Actions {#target-object-action}

The target object's lifecycle contains _Create & Activate External Collaborator_ and _Inactivate External Collaborator_ actions to configure for your "entry" and "exit" lifecycle states. The _Reassign External Collaborator_ action is also available to configure on states in which an external collaborator is active and may need to be reassigned.

Depending on your business needs, you can:

* Add these actions as <a href="/en/gr/59885/#entry-actions">entry actions</a> on any target object's lifecycle state:
  * [Create & Activate External Collaborator][10]
  * [Inactivate External Collaborator][11]
* Add the [Create & Activate External Collaborator][12] action as a <a href="/en/gr/59885/#user-actions">user action</a> on any target object's lifecycle state.
* Add the [_Reassign External Collaborator_][16] action as a <a href="/en/gr/59885/#user-actions">user action</a> on any state in the target object’s lifecycle.


<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>: In Vaults with <a href="/en/gr/627671/">Object Application Security</a> configured, Vault automatically creates <em>Record Matching Rule</em> records when users activate <em>External Collaborators</em> on an <em>Inspection</em> record and deletes <em>Record Matching Rule</em> records when users inactivate <em>External Collaborators</em>. This allows Vault to grant the correct application role on the <em>Inspection Sample Test Result</em> raw object, which cannot use <a href="/en/gr/33946/">Dynamic Access Control</a> for record-level access control. See <a href="/en/gr/63414/#app-sec">Setting Up Inspections</a> for more information.</p>
    </div>
  </div>
</div>



### Configuring the Create & Activate External Collaborator Entry Action {#create-activate-entry-action}

Add the _Create & Activate External Collaborator_ entry action to an ["entry" lifecycle state][5]. You must select an _[External Collaborator User Template][2]_ for Vault to use during automated _User_ account creation. This entry action attempts to activate a user account for the _Person_ record referenced in the _External Collaborator_ field.

If Vault determines that a _User_ account already exists with the exact details as the _Person_, Vault actions the following:

* Assigns that user account to the _Person_.
* Activates that _User_ account.
* Sends the named _External Collaborator_ a _[Welcome Back][3]_ notification.

If Vault determines that there is no existing _User_ account, Vault actions the following:

* Creates a new _User_ account.
* Activates the _User_ account.
* Sends the named _External Collaborator_ a _[Welcome][3]_ notification.

_User_ records created by this action have their _Managed by QMS Automation_ field set to _True_. Setting this field to _False_ manually stops the access management automation for the user: access is managed manually by you.

### Configuring the Inactivate External Collaborator Entry Action {#inactivate-entry-action}

Add the _Inactivate External Collaborator_ entry action to an ["exit" lifecycle state][5]. This entry action allows Vault to find the _Person_ in the _External Collaborator_ field, identify the _User_ account associated with the _Person_, and to check if the _User_ account can be inactivated. Vault checks for any requests assigned to the _User_ account that was granted by the _Create & Activate External Collaborator_ actions and have not yet had the _Inactivate External Collaborator_ entry action triggered.

If Vault determines that the _User_ account has completed all requests assigned for an external response, Vault actions the following:

* Inactivates the _User_ account.
* Sends the named _External Collaborator_ a _[Goodbye][3]_ notification.

Vault does not remove inactivated users from _Sharing Settings_ on individual records by default. To limit external collaborators' access to certain records in the event that their _User_ account is reactivated, you must add an <a href="/en/gr/33550/#how-to-define-an-update-sharing-settings-step">_Update Sharing Settings_ step in your target object's workflow</a>. 

You can also mirror the same effect that the _Inactivate External Collaborator_ action triggers by manually [removing assignments][9] from the _External Collaborator_ field or deleting a target record with an active assignment. Removing or changing the _External Collaborator_ value on the target object's record removes the _User_ from _Sharing Settings_.

### Configuring the Create & Activate External Collaborator User Action {#create-activate-user-action}

Add the _Create & Activate External Collaborator_ user action to lifecycle states that users may need to replace an inactivated external collaborator, such as when an external user is removed from a target object's _External Collaborator_ field. We recommend you restrict access to this action using <a href="/en/gr/47850/#Atomic_Security_Actions">Atomic Security</a>.

Optionally, you can also choose to prevent changes to the _External Collaborator_ field in an "exit" lifecycle state using <a href="/en/gr/39108/">field-level Atomic Security</a>, or use <a href="/en/gr/33550/">workflow steps</a> or <a href="/en/gr/59885/">lifecycle action</a> configurations to move the target object into a "pre-response" state to "restart" the collaboration process again.

### Configuring the Reassign External Collaborator User Action {#reassign}

You can configure the _Reassign External Collaborator_ user action to let users reassign an object record, including any tasks, to a different external collaborator. This is helpful in scenarios where the original external collaborator is no longer available, but users still need to collaborate on a record with a contact from an external organization.

<a href="/en/gr/59885/#define-actions">Add</a> the _Reassign External Collaborator_ user action to any [supported object][14] lifecycle state in which an active external collaborator may need to be reassigned.

When the _Reassign External Collaborator_ action runs:

* If the new external collaborator has an inactive user account, Vault activates the account.
* If the new external collaborator does not have a user account, Vault creates and activates an account for them.
* Once activated, the external collaborator receives a _Welcome_ or _Welcome Back_ email and a task notification associated with the relevant record.
* Vault evaluates if the previous external collaborator’s user account should be inactivated following the same actions taken by the [_Inactivate External Collaborator_ entry action][11]. 

<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>: The action fails if the <em>Person</em> records associated with the previous and new external collaborators are deactivated or deleted while reassignment is in progress.</p>
    </div>
  </div>
</div>



### Removing Assignments from the External Collaborator Field {#remove-assignments}

Whenever a _Person_ assignment in the _External Collaborator_ field of a target object's record is removed or changed, Vault evaluates if the _Person's_ associated _User_ account should be inactivated following the same actions taken in the [_Inactivate External Collaborator_ entry action][11], with the following added action: the _Person's_ associated _User_ account is removed from the _External Collaborator_ application role.

## Configuring the Target Object Workflow {#workflow}

Collaboration with external users may result in cases where an internal user needs to respond on behalf of the external collaborator, or abandon a collaboration on a specific request or any requests with specific partners. Ensure you account for the internal users' ability to take over assignments or bypass collaboration when necessary when configuring your target object's lifecycles and <a href="/en/gr/33550/">workflows</a>.

## About Assignment Tracking {#about-assignment-tracking}

External Collaboration Management tracks and stores data when [Vault activates or inactivates][6] a _User_ for a _Person_ referenced on an _External Collaborator_ field. Every time a _User_ is active, Vault creates a new record that references the matching target object's record and sets the new record's _Assignment Activity_ field as "Active"; for example, the _CAR_ target object's matching _External Collaborator CAR Assignment_ object.

Every time a _User_ is inactive, Vault updates the relevant existing object record's _Assignment Activity_ field to "Inactive". Tracking the assignments of a _Person_ via the _Managed by QMS Automation_ field allows Vault to verify whether an _External Collaborator_ has any active assignments on other object records or documents before automatically [inactivating][11] the _User_ account of the _Person_. If the _Managed by QMS Automation_ field is set to "False" on the _User_ record, Vault stops automatically tracking and managing assignments.

## Related Permissions {#permissions}

You can complete all the steps in this article with the standard _System Administrator_ or _Vault Owner_ security profile. If your Vault uses custom security profiles, your profile must grant the following <a href="/en/gr/22824/">permissions</a>:

<table>
  <tr>
    <th><strong>Type</strong></th>
    <th><strong>Permission</strong></th>
    <th><strong>Controls</strong></th>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Admin: Configuration: Object Lifecycles: Edit</td>
    <td>Ability to modify object lifecycles.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Admin: Configuration: Object Workflows: Edit</td>
    <td>Ability to modify object workflows.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Admin: Configuration: Objects: Create, Edit</td>
    <td>Ability to create and modify Vault objects.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Admin: Security: Permission Sets: Create, Edit, Delete</td>
    <td>Ability to make changes to permission sets for users.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: Audit (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>Audit</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: CAR (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>CAR</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: Change Control (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>Change Control</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: Inspection (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>Inspection</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: NCR (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>NCR</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: Audit Finding (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>Audit Finding</em>.</td>
  </tr>
  <tr>
    <td>Security Profile</td>
    <td>Objects: Action Item (all object types): Create, Edit, Delete</td>
    <td>Ability to make changes to <em>Action Item</em>.</td>
  </tr>
</table>

[1]: #setup-security-profile
[2]: #define-user-template
[3]: #message-template
[4]: #config-objects
[5]: #lifecycle
[6]: #target-object-action
[7]: #workflow
[8]: #external-collaborator-role
[9]: #remove-assignments
[10]: #create-activate-entry-action
[11]: #inactivate-entry-action
[12]: #create-activate-user-action
[13]: #config-target
[14]: #target-objects
[15]: #ecm-objects
[16]: #reassign