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, discuss with your Veeva team.

Supported Objects

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

  • Quality Events (quality_event__qdm): External Finding object type
  • SCARs (qms_scar__v)
  • CAPA Actions (capa_action__qdm)
  • Supplier Change Notification (supplier_change_notification__v)
  • Effectiveness Check (effectiveness_check__qdm)
  • Investigation (investigation__qdm)
  • Change Control (change_control__v)
  • Change Plan (change_plan__v)
  • Deviation (deviation__v)
  • Finding (finding__v)
  • Nonconformance (nonconformance__v)
  • MedTech CAPA (medtech_capa__v)
  • Health Hazard Evaluation (health_hazard_evaluation__v)

About the 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 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:

Setting Up User Security Profile

When Vault automatically creates Users, the system determines a specific Security Profile to use for the external collaborator via a Quality External User Template. 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.

Object Message Template Configuration

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, 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, 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. Note that the external collaborator can still reset their password via the standard method.

Person Object Configuration

On the Person object, activate the Organization object reference field, and add it to the Person object page layout.

Organization Object Configuration

Optionally, you can configure the Organization object to simplify the management of a contact list of Persons. This configuration is not required, but is strongly recommended.

Person records have a field linking them to Organizations, and Organization records can list the Persons that your own organization interacts with. This allows for easier identification of contacts to whom you can elect to assign records to collaborate on, such as Audit Findings (Quality Events), CAPAs or SCARs. 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 the Organization object to display contact lists, add a Person related object section to the object page layout of the Organization object. It may be helpful to define section level help for this contact list such that its purpose is clear.

Collaborating Object Field Configuration

When deploying External Collaboration for an object, you must make several modifications to the Collaborating Object object configuration to set up external collaboration.

External Collaborator Field Configuration

On the Collaborating Object, activate the External Collaborator field. You can optionally use the Constrain Records in Referenced Object field option to limit selection of the External Collaborator to only persons within a related Organization.

For example, see the following VQL statement:

organization__v = {{this.supplier__v}}

This statement limits selection of External Collaborators to the Organization referenced in the Supplier field of the Quality Event, to support selection of external collaborators for finding responses from the External Finding’s Supplier. This type of configuration is recommended and helps ensure that users choose appropriate collaborators for each process.

Add the External Collaborator field to the applicable Collaborating Object object type, and to its corresponding object page layout. If you configured a constraining statement as described above, the constraining field should be listed before the External Collaborator field, such that the constraints take effect prior to choosing an External Collaborator.

Supplier Field Configuration

While not required, you can establish a default value for the organization an Collaborating Object record is against, based on the associated parent process’ object. To do so, add a default value to the Collaborating Object record’s Supplier field. For example, in the case of Audit Finding Response collaboration, you’d set the default value for the External Finding (Quality Event object type) Supplier field to be inherited from the parent Audit: Audit > Auditee. The specific configurations will vary based on your processes and configurations.

Collaborating Object Lifecycle Configuration

Determine in which lifecycle state of the Collaborating Object 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.

External Collaboration Application Role

Add the External Collaborator (Audit) 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 (External Finding (Quality Event), CAPA, SCAR), you can change the label of the application role to best represent your business processes and Vault configuration.

Configuring the QMS: Activate Ext. Collaborator 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. 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. 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

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, 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, the system 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 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 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.

Removing Assignments from the External Collaborator Person Field

Whenever a Person assignment in the External Collaborator field of a Collaborating Object record is removed or changed, Vault evaluates if the Person’s associated user account should be deactivated following the same logic as the QMS: Inactivate Ext. Collaborator entry action, with the following added function: The Person’s associated user account will be removed from the External Collaborator application role.

User Action Configuration

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. It is recommended that you restrict access to this action via Atomic Security. 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 and any relevant workflows or tasks are , the collaboration process may be re-started as normal. Both types of process are supported by Vault QMS configuration.

Collaborating Object Workflow Configuration

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.