Configuring Multi-Document Change Control (QualityDocs)

Multi-Document Change Control allows you to use the Document Change Request and Document Change Control objects to execute document release and obsolescence in a programmatic, controlled manner.

The individual components that support this feature are entirely configurable, allowing your organization to model many different business processes. This article provides some suggested configurations. New Vaults include a best practice configuration by default.

Note: The Working with Multi-Document Change Control article assumes that you’ve followed the recommended processes here. If your configuration is different, your organization’s users may require additional help.

Configuration Overview

To set up Multi-Document Change Control:

Configure the object lifecycles for Document Change Control, Document Change Request, and Change Authorization.
Apply the shared document fields Document Change Request, Document Change Control, and Change Authorization Change Control to all document types that will use this functionality.
Add the Change Authorization section to the Document Change Control object page layout.
Optionally, add the special Documents to be made Effective with Workflows and Documents to be made Obsolete with Workflows sections to the Document Change Control object page layout.
Enable change control on any document lifecycles for document types that will use this functionality.
Optional: Configure automated periodic review options for your document lifecycles.
Select an appropriate Document Change Control object lifecycle state for the Implementation state type.

Configuring Document Types & Lifecycles

Before beginning, determine which document types, subtypes, and classifications will use change control and which lifecycles are tied to those document types. Document types, subtypes and classifications which require change control may share a lifecycle with documents that do not.

Within the document lifecycles, you must identify specific lifecycle states that serve as “document review complete” and “document has an approved change control.” These may be existing states in the lifecycle, or you may need to create new lifecycle states.

How to Configure Document Fields

Making a document type, subtype, or classification ready for change control requires that you add various fields to it:

Navigate to Admin > Configuration > Document Fields.
Add the shared document fields from Multi-Document Change Control settings to the document type, subtype, or classification. If you’re following the recommended setup, use the Proposed Effective Date, Proposed Obsolescence Date, and Obsolescence Approved fields.
Add the Obsolete Change Control and Release Change Control shared document fields to the document type, subtype, or classification. Vault uses these fields to create a relationship between the document and a specific change control. By default, these fields have security overrides to hide them because users do not need to interact with the fields directly through the Doc Info page field panel. You can remove or change these security overrides if needed.

Document Lifecycles

For any document lifecycles that should use change control, navigate to Admin > Configuration > Document Lifecycles and click into the lifecycle. Click Edit and select the Document Change Control checkbox. Click Save.

This setting enables Multi-Document Change Control for the document lifecycle.

Document Lifecycle States

When you enable Document Change Control on a document lifecycle, you must select specific lifecycle state for these state types:

Pending Change Control Approval State: This state should indicate that the document is ready to be routed with a change control for approval.
In Change Control Approval State: This state should indicate that the document is currently being routed for approval with a change control.
Change Control Approved State: This state should indicate that the document has an approved change control and is ready for release.

Vault includes entry action functionality based on these state types to inform the related Document Change Control record that a document is ready for approval, in approval, or approved. When setting up the document lifecycle, make sure that neither of the states specified for these state types allows users to route a document for approval or release directly. You can do this by removing workflow or state change-type user actions from the lifecycle state. Users should only be able to progress documents out of the Pending Change Control Approval State or into the Change Control Approved State through the related Document Change Control record.

Document Workflows

If you want Vault to automatically change the state of the associated Document Change Control to the state indicated as its Implementation state type at the appropriate time, you should include the Update Document Change Control State system action step in all applicable workflows on documents.

Document Lifecycle State Entry Actions

For Multi-Document Change Control, you can set up special entry actions on document lifecycle states. These document lifecycle state entry actions can streamline your process for complicated changes, but you can choose to configure Multi-Document Change Control without these.

Entry Action: CC: Set Change Control to Ready for Approval

Add this entry action to the lifecycle state specified for the state type Pending Change Control Approval.

This entry action attempts to perform a state change on the related Document Change Control record. However, this state change only succeeds if all of the change control’s related documents are in the appropriate state.

For example, a change control includes two documents with the same lifecycle. For this lifecycle, the Pending Change Control Approval state type is linked to the Reviewed state. When the Document Author moves the first document into Reviewed, Vault tries to move the change control to Ready for Approval but finds that the second document is still in the In Review state. The next day, the second document enters the Reviewed state and Vault again tries to move the change control. This time, the state change succeeds because all documents are in the correct state.

Note: Known issue: Vault may display a server error if an action, such as rejecting a Document Change Control approval task, triggers both the CC: Update Change Controlled Documents object state entry action and the CC: Set Change Control to Ready for Approval document state entry action at the same time.

Entry Action: Check and Close Multi-Document Change Control

When a document in a Document Change Control enters the configured state, this entry action does the following:

Checks the states of the documents associated with a Document Change Control, and verifies whether the Document Change Control should be closed.
If all of the Documents to be Released are in their Steady state, and all of the Documents to be made Obsolete are in their Obsolete state, the entry action automatically changes the Document Change Control’s state to its Complete state type.

To use this entry action, configure the document lifecycle to include this entry action for lifecycle states in both the Steady and Obsolete state types. The Document Change Control object lifecycle must have a state assigned to the Complete state type.

The automatic state change occurs just after the entry action is triggered. If the state change fails, details about the failure appear in the Closure System Details field on the Document Change Control record.

Note that this entry action can take up to 30 seconds to complete for Document Change Controls with many Documents to be Released.

Configuring the Default Objects

Enabling Multi-Document Change Control creates two standard objects:

Document Change Control: Change Managers will link a Document Change Control record to one or more documents in order to control the change process. You may also configure this object to link to the Document Change Request object, which lets users provide further detail for complex changes.
Document Change Request: Users can create Document Change Request records to track changes they’d like to see on a document. A change request is only linked to a single document, but a single document may have many change requests. The Document Change Request object includes a document reference field: Target Document. Change Managers can choose to include specific change requests in a change control. Requests are linked to change controls through the Governing Change Control field.

You can modify both of these objects by adding new fields to track additional details. We also recommend setting up object lifecycles.

Document Change Request Object

We recommend that you do the following. Many of the following steps are optional.

Optional: Configure the Create Related Record user action on specific document lifecycle states that allow document viewers to create a Document Change Request record without navigating away from the relevant document. We recommend that you include this in at least the Steady state of these document lifecycles.
Update the access control settings for the Document Change Request object to ensure that the right users can create requests. Users will also need the View Document permission on a document to create a related change request.
Create a custom tab so that users can view and work with requests outside of the Admin area.
Optional: Configure user actions for the Document Change Request object lifecycle. Your configuration should include actions that move the request to Closed or Rejected status.
Optional: Configure notifications for the Document Change Request object lifecycle. You should set these up as Send a notification entry actions for the Accepted, Closed, and Rejected lifecycle states. If you chose to use Matching Sharing Rules for access control on object records, you may use the object roles (Owner, etc.) as notification recipients. This allows you to notify the user who created the request. You can also define the Send Notification to Document Owner event action to trigger under certain conditions which will send a notification to the document owner if a Document Change Request record is created for the document. This event action utilizes the Doc Owner Change Request notification template.
Optional: Add the Exclude from DCC Auto-Linking field to the Document Change Request object page layout. Alternatively, you can configure this field to be populated via workflow record update steps or other automated data updates.
Optional: Configure the Document Change Control object lifecycle to include the CC: Update Related Change Request entry action. This configuration allows the Change Control to automatically mark its related Change Request records as Approved.

Document Change Control Object

We recommend that you do the following, but none of these steps are required:

This allows the Document Change Control record to trigger a state change on related Document Change Request object records to their Completed state. Without this entry action, Vault doesn’t update change requests automatically. We strongly encourage you to leverage this entry action.

2. Configure the Document Change Control object lifecycle to include the CC: Update Change Controlled Documents entry action on the Ready for Approval, In Approval, and Approved states.

This entry action changes states of related documents to synchronize state changes between the Document Change Control and the documents to be released, and optionally sets certain fields on the documents. When configuring this entry action, you choose:

Which document state type to target with the Document State Type drop-down. When the entry action runs, the documents to be released are transitioned to this state type. We recommend using the Pending Change Control Approval document lifecycle state for the Ready for Approval state, the In Change Control Approval document lifecycle state type for the In Approval state, and the Change Control Approved document lifecycle state type for the Approved state.
Whether you want to Copy Fields to Documents. Typically, this option is only checked on the Approved state. When the entry action runs, this option sets certain field values on the documents. The document fields are configured in Admin > Settings > Application Settings:
- Planned Effective Date: When the entry action runs, the value of the Proposed Implementation Date field on the Document Change Control is copied to the selected document field on the documents to be released. We recommend using Proposed Effective Date. This is included in the delivered application as a shared date field that you’ll need to add to any document types that use change control.
- Planned Obsolescence Date: When the entry action runs, the value of the Proposed Implementation Date field on the Document Change Control is copied to the selected document field on the documents to be obsolesced. We recommend using Proposed Obsolescence Date. This is included in the delivered application as a shared date field that you’ll need to add to any document types that use change control.
- Obsolescence Approval: When the entry action runs, the value of the selected field is set to Yes on the documents to be obsolesced. We recommend using Obsolescence Approved. This is included in the delivered application as a shared yes/no field that you’ll need to add to any document types that use change control.

3. Configure the Document Change Control object lifecycle to include the Link Available Document Change Requests entry action or user action on an appropriate state.

This action, when executed, adds any Document Change Request records which target the document or documents to be made effective to the Document Change Control as related records. If the Document Change Request has the Exclude from DCC Auto-Linking checkbox selected, Vault does not add that Document Change Request when executing this action.

4. Configure the Document Change Control object lifecycle to indicate a state as the Implementation state type

If you have configured the Update Document Change Control State system action step into your document workflows, Vault automatically changes the Document Change Control record to this state once all the documents in the Documents to be made Effective section are in the Approved state and all the documents in the Documents to be made Obsolete sections have the Obsolescence Approved field set to Yes.

5. Configure the terminal lifecycle states (Closed/Completed and Closed/Cancelled) in the Document Change Control object lifecycle.

Verify that the setting Records in this state become inactive is ON for these states. Making the Document Change Control record inactive when it is complete ensures that the document is released from any restrictions associated with change control, and makes the document eligible to be part of a future change control. Alternatively, you can configure independent approval workflows for the documents. If you use the enhanced Documents to be Made Effective/Obsolete with Workflows sections, users can initiate these document workflows directly from the Document Change Control record.

6. Define workflows for the Document Change Control object that moves records from Ready for Approval to Approved and Closed/Completed or to Closed/Cancelled.

To ensure that workflow participants are able to see all documents they approve, include workflow steps before each task assignment step in the workflow.

7. Update the access control settings for the Document Change Control object to ensure that the right users (Change Managers/Change Approvers) can create and manage change controls.

Change Managers/Change Approvers will also need View Document permission on any documents linked to a Document Change Control record.

8. Create a custom tab so that users can view and work with change controls outside of the Admin area.

Document Status & Workflow Initiation Sections

The following special sections, available to configure on the Document Change Control object page layout, allow users reviewing the Document Change Control to view the status of included documents and to start workflows on them directly from the Document Change Control record details page:

Documents to be Made Effective with Workflows: Displays documents with the current Document Change Control identified in the document’s Release Change Control field.
Documents to be Made Obsolete with Workflows: Displays documents with the current Document Change Control identified in the document’s Obsolete Change Control field.

Users can select documents with the checkboxes on the left side of the section, then start workflows that are valid for the selected documents by clicking Start Workflow. This functionality does not support legacy workflows.

These sections are useful if you use an approach in which users start document workflows on individual documents in the Document Change Control, driving the Document Change Control to move forward once all documents are in an appropriate state. One advantage is that you can now easily send sets of documents to different groups of workflow participants.

While the legacy Documents to be Made Effective and Documents to be Made Obsolete sections cannot be removed from the Document Change Control layout by the standard method, you can create a simple layout rule to hide them. Configure the layout rule expression to always return TRUE, and to hide these sections:

Documents to be made Effective
Documents to be made Obsolete

Configuring Document Change Control Object Workflows

There are two common ways to configure object workflows to ensure that workflow participants are able to see all documents they approve:

Add a Cascade Document Roles step before any task. This step grants the task participants necessary document permissions, allowing your organization to manually resolve access issues.
Add a Check participant access to related documents step and a subsequent decision step using the Participant Access Check Results workflow variable to track which users lack membership to appropriate roles on which documents. Include Notification and Workflow Task steps to the appropriate user or group to resolve any role membership issues if the Participant Access Check Results workflow variable is not blank. After the Workflow task is completed, we recommend repeating the Check participant access to related documents step before continuing the workflow.

Configuring the Change Authorization Object Lifecycle

To allow users to provide verdicts on documents in the Change Authorization section of the control, add Change State To user actions to the Created lifecycle state for both the Approved and Rejected states.

The Change Authorization section on the DCC does not support inline editing for Change Authorization record fields. Thus, in order to mark a Change Authorization as Needs Revision or Make Obsolete, you must click into the record, then edit the Revise or Obsolete field. To streamline this process, we recommend configuring object workflows for Change Authorizations that allow you to set the Revise or Obsolete field, and to expose them as user actions on the Created state of the Change Authorization object lifecycle.

Cascading eSignatures to Change Controlled Documents

When using Multi-Document Change Control, your organization can configure Document Change Control object workflows so that eSignatures “cascade” down to the change controlled documents. The cascaded signatures appear in the document audit trails and (if configured) in the documents’ generated signature pages. To do this, include one or more tasks with eSignatures in the object workflow. Then, add a System Action: Cascade eSignatures workflow step to the object workflow. Within this step, you should select each verdict that should cascade and select the Manifest eSignature on documents checkbox for each. Selecting the Cascade only current eSignatures checkbox in the Cascade Verdicts section ensures that Vault only cascades current, non-obsolete signatures from the change control to the documents. If necessary for your process, use the following option:

Include Purpose in Cascade Verdicts: Select this checkbox and fill in both the Purpose for Release and Purpose for Obsolescence fields. Configured purpose values will be cascaded along with eSignatures to documents and captured in documents’ audit trails. To manifest purposes in your eSignature pages, you need to add a token (dcc_signature_purpose__v) to your eSignature template.

Cascading Document Roles

When using Multi-Document Change Control, your organization can configure Document Change Control object workflows so that certain document lifecycle role assignments “cascade” down to the governed documents. This includes any documents included in Documents to be Released, Documents to be Made Obsolete, and any documents with a custom relationship to the Document Change Control record. Cascading document roles prevents a situation where a workflow participant has permission to access only some of the governed documents but approves the change control, causing impacts to unreviewed documents.

We recommend including a System Action: Cascade Document Role step before each task assignment in a workflow for Document Change Control records. If you use the default workflows, this step is automatically included.

Roles

Vault automatically adds the following two document lifecycle roles to all document lifecycles. The Cascade Document Role step can only assign users to these roles.

Document Change Control Approver
Document Change Control Reviewer
Viewer (details for custom relationships)

By default, the Document Change Control Approver and Document Change Control Reviewer roles grant the View Document and View Content permissions for all lifecycle states. You can edit the permissions as needed, but removing these permissions prevents the feature from working as intended.

By default, Vault does not include any override rules for these roles.

How to Set Up Cascade Role Steps

Cascade Document Roles is a type of system action in the Document Change Control object workflow configuration. To configure it:

Add a System Action step to the workflow. This step should occur before any task assignments in the workflow.
Select Cascade Document Roles in the System Action drop-down.
Select the Access Role to assign workflow participants on all related documents.
From the Grant Document Access To drop-down, select the workflow participant group to assign to the selected document lifecycle role. You can choose multiple participant groups if needed.

Custom Relationships

If your Vault uses custom relationships (other than Documents to be Released and Documents to be Made Obsolete) between documents and Document Change Control records, Vault assigns users to the Viewer document lifecycle role, rather than the roles described above. This occurs for every workflow participant group mapped to either Document Change Control Approver or Document Change Control Reviewer via the Cascade Document Roles step.

When using Multi-Document Change Control, your organization can configure Document Change Control object workflows to verify that all users in a workflow participant group are members of desired Application Roles on every document related to a Document Change Control record. These roles should have at least View Content permissions on all lifecycle states applicable while documents are linked to the Document Change Control. This includes any documents with a Documents to be Released or Documents to be Made Obsolete, or any custom relationship to the Document Change Control record to which workflow participants may need access.

If any user lacks access to one or more documents, Vault populates the workflow variable with the value is not blank. If the workflow variable is blank, all users have necessary access to all related documents. In some cases, is blank could also mean that the workflow configuration is incorrect.

See Configuring Object Workflows for information on setting up this workflow option.

Scheduled Jobs

In some business processes, you must configure a scheduled job that moves documents into to the next lifecycle state based on what happened with the change control. Because this state varies by lifecycle, you must create this set of jobs for each document lifecycle that uses change control.

Most organizations will need the following jobs:

Job Description	Document Conditions	State Change To
Post Change Control Sorting: Locate all documents associated with an approved Document Change Control record. If they require training, move them to the issued state.	Approval Date is today or earlier Requires training In lifecycle's Change Control Approved state	Issued for Training or equivalent state
Auto-Effective Release: Locate all documents which are in an approved but not-yet-effective state, and make those documents effective on the planned date.	Proposed Effective Date is today or earlier Requires training In Issued for Training or equivalent state	Document lifecycle's Steady state
Auto-Effective Release: Locate all documents which are in an approved but not-yet-effective state, and make it effective on its proposed effective date	Proposed Effective Date is today or earlier Training not required In lifecycle's Change Control Approved state	Document lifecycle's Steady state
Auto-Obsolescence: Locate all documents which are in an effective state, but have been approved for obsolescence. Automatically set them to an obsolete state on the planned date.	Proposed Obsolescence Date is today or earlier Obsolescence Approved is Yes In lifecycle's Steady state	Document lifecycle's Obsolete state

Note: You can use Multi-Document Change Control without scheduled jobs if all documents released by a change control go directly into their lifecycle’s Steady State.

Note: Running both an auto-effectivity job and an auto-obsolescence job at the same time may cause conflicts. To avoid such issues, ensure your configuration runs these jobs at different times.

How to Hide Single-Document Change Control

If your organization wishes to use Multi-Document Change Control but is currently using Single-Document Change Control (SDCC), we recommend these actions to hide the SDCC options:

Inactivate the Document Change Control document type.
Clear the Use Document Change Control checkbox within document type details for all document types.
Set the Document Change Control Lifecycle status to Inactive.