# Configuring Reason for Change (QMS)

Health authorities may require your organization to capture a reason for change when a user corrects fields on records associated with certain key processes. Veeva QMS supports the ability for Admins to require users to provide a _Reason for Change_ upon updating one or more fields when the object record is in a particular lifecycle state. Additionally, Admins can require users to provide a clarifying comment when selecting a particular reason. Upon saving, Vault captures the reason for the change, the affected fields, the user who made the change, and when the change was made.

For example, if an _Internal Audit_ record is in the _In Audit_ lifecycle state and a user needs to update the _Starting Date_ field, an Admin can configure Vault to prompt them to provide a reason for the change and comments before saving the record.

This article provides guidance on configuring this in your Vault in addition to limitations to using this feature.

## Supported Objects {#supported-objects}

Reason for Change is a feature of the Veeva QMS application. In QMS Vaults, you can create a _Reason for Change_ configuration for any custom object, as well as the following standard objects and their object types:

<table>
  <tr>
    <td><ul><li><em>Adverse Event Report</em></li><li><em>APQR</em></li><li><em>APQR Item</em></li><li><em>APQR Program</em></li><li><em>Assessment Risk</em></li><li><em>Assessment Risk Mitigation</em></li><li><em>Assessments</em></li><li><em>Audit</em></li><li><em>Audit Program</em></li><li><em>Auditor Profile</em></li><li><em>Auditor Role</em></li><li><em>Batch/Lot</em></li><li><em>CAPA</em></li><li><em>CAPA-Quality Event</em></li><li><em>CAPA Action</em></li><li><em>Change Action</em></li><li><em>Change Control</em></li><li><em>Change Plan</em></li><li><em>Complaint</em></li><li><em>Complaint-Batch</em></li></ul></td>
    <td><ul><li><em>Context</em></li><li><em>Continuous Improvement</em></li><li><em>Criticality</em></li><li><em>Detectability</em></li><li><em>Deviation</em></li><li><em>Deviation-Batch</em></li><li><em>Finding</em></li><li><em>Health Authority</em></li><li><em>Hospital</em></li><li><em>Hospital Location</em></li><li><em>Impact Assessment</em></li><li><em>Investigation</em></li><li><em>Issue Escalation</em></li><li><em>Lab Investigation</em></li><li><em>Lab Investigation-Batch</em></li><li><em>Material</em></li><li><em>MedTech CAPA</em></li><li><em>MedTech Complaint Details</em></li><li><em>Mitigation Action</em></li><li><em>Nonconformance</em></li></ul></td>
    <td><ul><li><em>Occurrence</em></li><li><em>Organization</em></li><li><em>Organization Business Function</em></li><li><em>Organization Location</em></li><li><em>Product</em></li><li><em>Product Return</em></li><li><em>Quality Event</em></li><li><em>Quality Event-Batch</em></li><li><em>Quality Incident</em></li><li><em>Risk Level</em></li><li><em>Risk Matrix</em></li><li><em>Root Cause</em></li><li><em>Root Cause Analysis</em></li><li><em>SCAR</em></li><li><em>SCN Impact Assessment</em></li><li><em>Severity</em></li><li><em>Supplier Change Notification</em></li><li><em>Third Party</em></li></ul></td>
  </tr>
</table>

## Configuration Overview

Complete the following configuration steps to use the Reason for Change feature in your Vault:

  * Add the valid reasons for changing fields to the _Reason for Change_ picklist.
  * Configure a field on objects that will be used by the Reason for Change feature to capture a user's changes. This field is not displayed to users.
  * Create [_Reason for Change_ configurations][1] for the desired objects and object types.
  * [Update permission sets][2] assigned to users who edit records for the desired objects.
  * Modify the [page layout][3] for the desired objects or object types to accommodate the Reason for Change feature.
  * Optional: [Update](/en/lr/72016/#fo-action) Word formatted output templates to include the _Reason for Change History_ section in generated documents.

## Configuring a Reason for Change Capture Field {#capture-field}

The Reason for Change feature requires a _Long Text_ field on the objects that use the feature. Some standard objects already have a standard _Reason for Change Capture_ field; you may need to activate the field on those objects. Admins must configure a similar _Long Text_ field with a 32,000 character limit on all other standard or custom objects. If the object uses object types, ensure that the field is added to each object type that will use the Reason for Change feature. This field cannot be [required](/en/lr/15057/#required).

## Creating Reason for Change Configurations {#creating-configurations}

Complete the following steps in your Vault to create _Reason for Change_ configurations for the desired objects and object types.

To create a _Reason for Change_ configuration:

  1. Navigate to **Admin > Configuration > Reason for Change Configurations**.
  2. Click **Create**.
  3. Provide a **Label**, **Status**, and optional **Description**.
  4. Select an **Object** from the drop-down and an **Object Type** if applicable. You are required to select an **Object Type** if the selected object has two (2) or more object types.
  5. Select the appropriate _Reason for Change Capture_ field in the **Capture Field**.
  6. Under the _Field Criteria_ section, select up to 30 standard or custom fields that should require a reason for change. Inactive, formula, and lookup fields are not available for selection. Select which lifecycle states should require a reason for change for the chosen fields. Click the plus (**+**) icon to add field and lifecycle state combinations or the minus (**-**) icon to remove field and lifecycle state combinations.
  7. Optional: Under the _Picklist Comment Criteria_ section, select the _Reason for Change_ picklist values that should require the user to provide a free text _Comment_.
  8. Click **Save**.

### Limitations

The following limitations apply when you create _Reason for Change_ configurations:

  * You can define a single _Reason for Change_ configuration for each specific object and object type.
  * The drop-down in the _Field Criteria_ section only displays fields that are editable through the UI and active for the selected object type. If you update a _Reason for Change_ configuration and a selected field has become inactive, Vault clears the field upon saving.
  * Once a field is included in a _Reason for Change_ configuration, you cannot remove it from an object type.

### Updating Permission Sets for Reason for Change Configurations {#update-permissions}

For each permission set that enables users to edit the objects or object types in a _Reason for Change_ configuration, do the following:

* Assign _Read_ permission for the _Reason for Change_ object. 
* Within the _Reason for Change_ object, assign the following permissions:
  * _Read_ permission for the _Audit Group ID_ field
  * _View_ permission for the _Audit Trail_ object control
  * _View_ permission for the _Reason for Change Source Record_ object control
* For each object in the permission set that uses the Reason for Change feature, click into the object and assign the following permissions:
  * _View_ permission for the _Reason for Change History_ object control
  * _View_ permission for the _Reason for Change_ object control
  * _View_ permission for the _Reason for Change Capture_ object control
  * _Edit_ permission for the _Reason for Change Capture_ field, or the equivalent field for custom objects

## Configuring Object Page Layouts {#page-layouts}

To accommodate the Reason for Change feature, you must add the _Reason for Change Capture_ application control to the object or object type's page layout. This control is not visible to an end user, but it must be in the page layout in order to display the _Reason for Change_ dialog when a user saves a record.

The [_Reason for Change Capture_ long text field][4] specified in a _Reason for Change_ configuration's **Capture Field** is not intended to be viewed or edited by users, so you should not include it in object page layouts.

Add the _Reason for Change History_ section to the layout for the objects or object types. If your organization previously implemented this feature and used the _Reason for Change_ related object section, you must replace it with the _Reason for Change History_ section to ensure users can see all the reasons for changes made to a record.

## Related Permissions

You must have a security profile with the following permissions to configure Reason for Change:

|Type|Permission Label|Controls|
|--- |--- |--- |
|Security Profile|Admin: Configuration: Reason for Change: Create, Edit, Delete|Ability to view, create, edit, or delete _Reason for Change_ configuration components.|

  [1]: #creating-configurations
  [2]: #update-permissions
  [3]: #page-layouts
  [4]: #capture-field