# Configuring External Notifications (QMS)

Organizations often need to send emails to internal and external recipients for various processes in QMS. Using the _Quality External Notifications_ configuration component, you can define distribution groups and notification templates, send emails, and share documents. This addresses several scenarios that your organization may encounter:

  * When an _Audit_ report is completed, that report often needs to be sent to an external recipient, such as the supplier contact, as well as persons associated with the _Audit_ or supplier.
  * In _Complaint_ and _Medtech Complaint_ processes, customers often need to send correspondence letters and forms to the complainant or the reporter associated with the complaint at various times during the event lifecycle.
  * If a serious issue is encountered, such as a critical deviation, and an _Issue Escalation_ process is initiated, upper management external to Vault may need to be notified of the serious event.
  * In _Field Corrective Action_ processes, external parties may need to be notified of _Product Action_ developments.

This article provides basic configuration information to get started using _Quality External Notifications_ in your Vault. The External Notifications feature supports standard and custom object types on the _Quality Event_, _Complaint_, _Audit_, and _Issue Escalations_ objects, as well as the _Change Control_, _Change Plan_, _Deviation_, _Finding_, _Lab Investigation_, _Continuous Improvement_, _Nonconformance_, _Product Action_, and _MedTech CAPA_ objects. These are collectively referred to as the "supported object" in this article.

## Configuration Overview

  * [Set up supported objects][1] for use with external notifications.
  * Create [object message templates][6] as needed to suit your processes.
  * Create [_Quality External Notifications_][2] to suit your processes.
  * Add the [_Send External Notification_][3] user action or entry action to the applicable object lifecycle state.

## Setting Up Objects for External Notifications {#object-setup}

To enable external notification functionality you must update object configurations.

### Add the Send External Notification Action to a Supported Object

To add this [user action](/en/lr/43127/#assign-actions) to a supported object:
  1. Navigate to the object that you want to enable for External Notifications.
  2. Navigate to **Actions >** **Create.**
  3. Select **Send External Notification.**
  4. Click **Continue**. Review the action's details and make any adjustments, however do **not** select the _Available in All Lifecycle States_ option. The action does not properly function with this configuration.
  5. Click **Save**.

Once created, you can configure the _Send External Notification_ action in the object's corresponding object lifecycle.

### Add the Create Distribution Group Memberships Action to a Supported Object

The **Create Distribution Group Memberships** action can automatically populate distribution groups based on matching field data. To add this action to a supported object:

1. Navigate to the object that you want to enable for External Notifications.
2. Navigate to **Actions > Create**.
3. Select **Create Distribution Group Memberships**.
4. Click **Continue**. This will enable you to configure the _Create Distribution Group Memberships_ action in the object's corresponding object lifecycle.

### Supported Object {#supported-object}

Make the following changes to the supported object for which you are setting up external notifications:

  * Add the _Notification Recipients_ object control section on the supported object page layout. Adding this section to a non-supported object results in a non-functional section.
  * If your external notifications will include documents, you must add _Document_ object reference fields to the supported object. You must also add a _Text_ field to the supported object to contain the external link URL for use by your notification template. The external link URL must have a text field length of at least 320.
  * Optional: Add the _Sent Notification_ object as a related object to the page layout of the object you are configuring for external notifications. This will allow you to see the notifications that were sent out for the record in this object. For example, for _Audits_, you can add the _Audit Sent Notifications_ object to the _Audit_ page layout.

Make the following changes to the _Complaint_ or _Medtech Complaint_ object types on the _Quality Event_ object, or the _Complaint_ object, for which you are setting up external notifications:

  * Optional: Add the _Reply To_ field to the page layout of the object you are configuring for external notification. The person in this field will receive email replies from the recipient of the external notification.
  * Optional: Add the _From_ field to the page layout of the object you are configuring for external notification. The person in this field will appear as the sender of the external notification. To use this feature, you must ensure that you have configured and verified [Outbound Email Domains](/en/lr/78114/) and _From Email Address Persons_ appropriate for your organization.

<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>: Some email clients may ignore the email address specified in the <em>Reply To</em> field. In these cases, notification recipients may need to replace the auto-populated reply-to email address with the correct address when responding to external notifications.</p>
    </div>
  </div>
</div>



## Creating Object Message Templates for External Notifications {#object-message-templates}

You can create message templates for external notifications like standard [object message templates](/en/lr/2157/) except as follows:

  * After selecting the token, replace the `Object` prefix manually in each token with `Custom`. For example, update the token `${Object.name_v}` to `${Custom.name_v}`.
  * Formula fields are not supported for external notifications.
  * Text tokens in external notifications are always displayed as rich text.

## Creating Quality External Notifications {#quality-external-notifications}

The core component of external notification setup is the _Quality External Notification_ configuration component. You must create one, then add [_Distribution Groups_][4] and [_Notification Templates_][5] for each supported object you wish to use.

To create _Quality External Notifications_:

  1. Navigate to **Admin > Configuration > Quality External Notifications**.
  2. Click **Create**.
  3. Fill in the required details.
  4. Select the supported object from the **Object** drop-down. For the Quality Event object, Vault only supports external notifications for the Complaint and Medtech Complaint object types.
  5. If necessary, select an **Object Type**.
  6. Optional: If you selected the _Complaint_ or _Medtech Complaint_ object type, you can select the **Do Not Include Headers and Footers** checkbox if you do not want the notification email to include the standard Vault header or footer.
  7. Click **Save**.

### Adding Distribution Groups {#distribution-groups}

To add a _Distribution Group_:

1. From a _Quality External Notification_ configuration, click **Add Distribution Group**.
2. Fill in the required details.
3. Select a value for **Maximum Recipients**, up to 50. You can optionally select a value for **Minimum Recipients**.
4. If you want Vault to automatically populate the distribution group via either an entry or user action, select the **Populated by Distribution Group Management action** checkbox.
5. If you do not want users to be able to make modifications to the distribution group in the _Notification Recipients_ section of the applicable object record, select the **Prevent users from adding persons to distribution group** checkbox.
6. Optional: You can limit the _Persons_ available for inclusion in the distribution group via _Person_ record data. In the **Match Persons on the Following Fields** section, click **Add Filter Field** and select an **External Notification Enabled Object** and a corresponding **Person Field**. This option only supports fields with a data type of _Object_ or _Picklist_, and Vault automatically filters _Person_ fields based on the data type of the External Notification-enabled object field. Whether the group is automatically or manually populated, Vault only includes _Persons_ whose field values match. To add additional filters, click the plus (**+**) icon. You can configure up to 10 matching pairs.
7. Click **Save**.

_Distribution Groups_ appear in the _Notification Recipients_ section on the supported object details page, and in the _Distribution Groups Label_ field on any resulting external notification records.

### Adding Notification Templates {#notification-templates}

_Notification Templates_ defined in a _Quality External Notification_ configuration have several options to suit your processes.

To add a _Notification Template_:

  1. From a _Quality External Notification_ configuration, click **Add Notification Template**.
  2. Fill in the required details.
  3. Select _Person_ object reference fields on the supported object in the **Recipients** drop-down. These will be the default recipients when the _Send External Notification_ action is triggered or performed by a user.
  4. Optional: Add one or more defined groups from the **Included Distribution Groups** drop-down. These will be the default groups when the _Send External Notification_ action is triggered or performed by a user.
  5. Optional: Select **Include users associated to application roles on object lifecycle** if you additionally want the notification sent to Vault users in specified roles. If checked, select one or more **Application Roles** from the drop-down.
  6. Optional: Select **Include Documents in Notification** if you want your notification to include links to view Vault documents in a special external viewer. If checked:
     1. Select at least one (1) **Document Reference Field on this Object**. Vault includes all referenced documents in a single package, accessible via a single URL linked in the notification.
     2. Optional: Select at least one (1) **Field on Document Referencing this Object** if you want to add a document from the library that references the record in the notification. Populating this field allows an end user to manually select a document from the library that is associated to the record.
     3. Select a value from the **Allow Download** drop-down. You can optionally make the document URL time-limited to a number of days selected in the **Expiry Period (days)** field. When _Download Source Document_ is enabled, recipients can download the source file even if a viewable rendition does not exist. 
     4. Select a _Text_ field on the supported object to contain the URL to the document package.
  7. Optional: Select **Allow user to Add/Remove Recipients** to allow users to change recipients when performing the _Send External Notification_ user action.  With this release, users will only be able to remove recipients if this is selected.
  8. Optional: Select **Allow user to Add/Remove Documents** to allow users to add or remove documents from the notification before it is sent.
  9. Select an object message template in the **Object Message** drop-down. See this article for information on creating object messages.

## Configuring Object Lifecycles & Workflows for External Notifications {#object-lifecycles}

### Send External Notification Action

Add the _Send External Notification_ user action or entry action to a state in the supported object lifecycle in which external contacts need to be notified. When configuring the entry action, you must select one _External Notification Template_ defined in the _Quality External Notification_ component for the action to use. When configuring the user action, you can select one or more of the _External Notification Templates_, and the user can choose from these when executing the action.

If configured as an event action, you should include the _Create Distribution Group Memberships_ action to execute before the _Send External Notification_ action, as the _Send External Notification_ action may fail if no recipients are identified when sending the notification.

### Create Distribution Group Memberships Action

Add the _Create Distribution Group Memberships_ user action, entry action, or event action to a state in the supported object lifecycle in which you want to populate distribution groups.

## Limitations {#limitations}

  * You can define up to five (5) distribution groups per _Quality External Notification_ configuration, and up to 50 persons per distribution group.
  * Up to 400 recipients can receive a notification.
  * For _Complaints_ and _Medtech Complaints_, delivery is only tracked for the _Recipient_, not the additional recipients (bcc).
  * For _Complaints_ and _Medtech Complaints_, delivery tracking is "best effort", based on the responses received from the receiving email server configuration. For example, some email servers are configured to always send back "Delivered" status events, even if the email address doesn't exist. In this case, the status of the email will be set to _Delivered_ and not _Email Bounced_.
  * If you include lifecycle roles in the external notification template, only users that are manually assigned will receive a notification.
  * Object message templates created for External Notifications have [additional limitations][6].

## Related Permissions {#permissions}

You must have a security profile with the following permissions to configure _Quality External Notifications_:

|Type|Permission Label|Controls|
|--- |--- |--- |
|Security Profile|Admin: Quality External Notifications|Ability to view, create, edit, or delete _Quality External Notifications_ configuration components.|

  [1]: #object-setup
  [2]: #quality-external-notifications
  [3]: #object-lifecycles
  [4]: #distribution-groups
  [5]: #notification-templates
  [6]: #object-message-templates
  [7]: #supported-object