Configuring Multi-Document Change Control (Document Control)

QualityOne Vaults allow 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 the Multi-Document Change Control feature are entirely configurable, allowing your organization to model many different business processes. This article provides some suggested configurations. Vaults created after the 16.0.0 release will 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

Configuring your Vault to use Multi-Document Change Control involves the following steps:

Configure the object lifecycles for Document Change Control and Document Change Request
Apply the shared document fields to all applicable document types
Enable change control on any document lifecycles for applicable document types
Configure user permissions

Note: 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.

Configuring Document Types & Lifecycles

Before beginning, determine which document types, subtypes, and classifications will use change control and which lifecycles correspond to those document types. Document types, subtypes, and classifications that 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. 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 on 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 Vault is currently routing the document 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 remove 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 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 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 (2) documents with the same lifecycle. For this lifecycle, Vault links the Pending Change Control Approval state type 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.

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 Complete.

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: 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 (2) standard objects:

Document Change Request: Users can create Document Change Request records to request and track changes 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. Vault links requests to change controls through the Governing Change Control field.
Document Change Control: Change Managers can link a Document Change Control record to one (1) or more documents 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.

You can modify both 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 including this in at least the Steady state of the relevant document lifecycles.
Update the access control settings for the Document Change Request object to ensure 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 quickly view and work with requests.
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 (such as Owner) as notification recipients. This allows you to notify the user who created the request.
Optional: Configure the Document Change Control object lifecycle to include the CC: Update Related Change Request entry action. This configuration triggers Vault to automatically mark Change Request records as Approved when the related Change Control moves into an Approved state.

Document Change Control Object

We recommend that you do the following:

Configure the Document Change Control object lifecycle to include the CC: Update Related Change Request entry action on the Approved state. This configuration triggers Vault to automatically mark Document Change Request records as Completed when their related Document Change Control record moves into an Approved state. Without this entry action, Vault doesn’t update change requests automatically. We strongly recommend leveraging this entry action.
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 can also populate 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 enter 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 enabled on the Approved state. When enabled, the action populates certain fields on the documents. If you select this option, you can configure which shared document fields Vault populates in Admin > Settings > Application Settings in the QualityDocs section. You must add the selected field to any document types that use change control. The following fields are available:
  - Planned Effective Date: When the entry action runs, Vault copies the value of the Proposed Implementation Date field on the Document Change Control to the selected document field on the documents to be released. We recommend selecting Proposed Effective Date.
  - Planned Obsolescence Date: When the entry action runs, Vault copies the value of the Proposed Implementation Date field on the Document Change Control to the selected document field on the documents to be obsolesced. We recommend using Proposed Obsolescence Date.
  - Obsolescence Approval: When the entry action runs, Vault updates the value of the selected field to Yes on the documents to be obsolesced. We recommend using Obsolescence Approved.
Configure the terminal lifecycle states (Closed/Completed and Closed/Cancelled) in the Document Change Control object lifecycle. Verify that the Records in this state become inactive checkbox is selected for these states. This 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.
Update the access control settings for the Document Change Control object to ensure that the right users (Change Managers and Change Approvers) can create and manage change controls. Change Managers and Change Approvers will also need View Document permission on any documents linked to a Document Change Control record.
Create a custom tab so users can quickly view and work with change controls.

Configuring Document Change Control Object Workflows

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

There are two (2) common ways to configure object workflows to ensure that workflow participants can 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 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. We recommend repeating the Check participant access to related documents step after the task before continuing the workflow.

Cascading eSignatures to Change Controlled Documents

When using Multi-Document Change Control, you 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 in the documents’ generated signature pages, if configured. To do this, include one (1) 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.

You can use the Include Purpose in Cascade Verdicts option by selecting its checkbox and fill in both the Purpose for Release and Purpose for Obsolescence fields. Configured purpose values will cascade along with eSignatures to documents and are 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, you can configure Document Change Control object workflows so that certain document lifecycle role assignments “cascade” down to the governed documents. This includes any documents 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. This step is part of the default workflows.

Roles

Vault automatically adds the following two (2) 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, you 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 applicable lifecycle states 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 (1) 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 more details on setting up this workflow option.

Scheduled Jobs

For some business processes, you must configure a scheduled job that moves documents into 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	Change State 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 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 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 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.

Hiding Single-Document Change Control

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

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

Configuring User Permissions

Vault provides two (2) security profiles that include the required permissions through permission sets:

Document User with Change Management is appropriate for Change Managers
Document User with Change Request is intended for any full user allowed to submit change requests.

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 permissions and document role permissions:

Type	Permission	Controls
Security Profile	Objects: Document Change Control: Read, Create, Edit	Ability to view, create, and modify Document Change Control records.
Security Profile	Objects: Document Change Request: Read, Create, Edit	Ability to view, create, and modify Document Change Request records. Allows users to include or exclude change requests in change controls.
Document Role	Document Lifecycles: States: Security Settings: Edit Fields	Allows users to associate a change request with a document. Change Managers must have this permission on all documents related to their change controls.
Document Role	Document Lifecycles: States: Security Settings: View Content	Allows users to see the Viewable Rendition for a document; users responsible for reviewing and approving changes should have View Content permission on every document included in the change control. Admins can ensure correct permissions by including the System Action: Cascade Document Roles step in change control workflows.