Phase Locked Software logoDocument Control Doc

Document Control Logo Document Control Documentation

Revision: 2024-07-09

User Documentation

Creating a controlled document

A controlled document can be a page in a space. When you create a new controlled document in a restricted space or document, make sure the user "Electronic Signing for Confluence Cloud" has permissions on the new page. If you are creating a new page from scratch, the best practice is to choose the "Controlled document" template from the Create dialog:

Choosing the Controlled Document template.

This template sets up the page with everything needed for use with the Document Control add-on.

If you want to use a different template, or if you want to take an existing page and convert it to a controlled document, it's a simple two-step process:

1. Add the "Document Control" macro somewhere in the body of the page (typically at the bottom):

Inserting the Document Control macro.

Inserting the Document Control macro.

2. Add the "controlled-document" label to the page:

Adding the Document Control label.

Assigning reviewers

There are two ways to add reviewers to a page:

1. Click the Document Control byline on the page (the link under the page title)
2. From the page menu (the three-dot icon with links to Move, Copy, Delete, etc.), click "Manage Reviewers".

Once the "Manage Reviewers" dialog is open, you can add a reviewer to a page by searching by name.

Adding a reviewer.

When the "reviewer meaning / role" configuration setting is enabled, you can add a signature meaning / role in the reviewers dialog:

Adding a reviewer with meaning.

You can also use this dialog to remove a reviewer by clicking the small "x" next to each reviewer's name.

If you have the Email notification setting enabled, the new reviewer will receive an email inviting them to review the page:

Email notification for new reviewer.

The page's document control status will change to Needs Review until all reviewers have added a signature to the page. External collaborators or guest users can be assigned as a reviewer by a regular user. However external collaborators can't change the reviewers.

Signing a page

From the page menu, click "Add Signature" or click the "Add Signature" button (if enabled by your Confluence administrator):

Opening the Add Signature dialog.

Fill out the form and click Submit to sign the page.

External collaborators or guest users can sign a document if they have been selected as a reviewer by a regular Confluence user. Due to Confluence restrictions, guest users can only view and sign documents in a single space.

If the Authentication setting is enabled, the user is required to authenticate with Document Control with one of the following methods:

If multiple methods are enabled, the user must choose an authentication method.

Choose an authentication method.

Signature Authentication Information

Personal token: When using a personal token, a user needs to set a secret token and validate the token through a validation code received by email. The validation code is only valid for a short time. The token can be revoked on demand. If the secure token does not match, it will be revoked after several failures.

Signing a page with personal token.

The email for the validation code must be the email address used for Confluence login. You can find your login email at your Atlassian profile page. The personal token can be reset by going to the Document Control General page and clicking on the setup button.

2FA: For 2FA authentication, a user needs to install and pair an authenticator app. Compatible apps are:

When using 2FA authentication for the first time, a user needs to pair their authenticator app with Document Control.

Pair authenticator app with Document Control.

The 2FA codes are unique to each user, and can be revoked on demand using a user-specific API token. When signing, the signature dialog ask you to enter a 6 digit code called 2FA token. This token is generated by your authenticator app. The token is refreshed regularly. If the token does not match, an error message is shown to indicate a problem:

Signing a page with 2FA.

Authentication through SSO/OpenID: SSO/OpenID is configured by your Confluence administrator. The user interface depends on the authentication provider.

API key: When using API key authentication, a user needs to generate a secure token once by using the Atlassian provided secure token management page at the Atlassian API token page. The token is unique to each user, and can be revoked on demand. If the email and the secure token do not match, an error message is shown under the email and token fields to indicate a problem:

Signing a page with API key.

The email for the signature must be the email address used for Confluence login. You can find your login email at your Atlassian profile page.

Document Control Status

All pages set up for document control will have one of three statuses:

  1. Not reviewed - No reviewers have been added to this page.
  2. Needs review - One or more reviewers have been added to this page, but not all reviewers have signed the most recent version of the page.
  3. Reviewed - All reviewers have signed the most recent version of the page.

The document control status is reflected in the byline (the link under the page title) of each page. It's also reflected in the Document Control macro. For example, in the following screenshot, Jason Wright and Lucille Bluth have been assigned as reviewers, but only Lucille Bluth has signed:

Page that needs review.

Once Jason Wright signs the page, the page looks like this:

Page that has been fully reviewed.

If the page is edited, all reviewers will need to sign the page again to maintain the "Reviewed" status; see Page versioning for more details.

Using the space view

New 2024-05-22 An alternative version of the space view is available as a new macro. Type "/document" into the editor, and a completion for "Document Control -- Space View" will appear. Choose this macro, and a table of the pages with the Document Control macro will be rendered. The display is slightly different than the older Space View, however it serves the same purpose.

To see the document control status of all pages in a space at a glance, you can use the "Space View" setting of the Document Control macro. Typically, you might want to add the macro to the top-level page in a space. To do this, start editing a page. Then choose from the menu "+" and "View more" to insert the Document Control macro. Choose the "Space View" setting:

Insert the Space View macro.

You can use the shortcut "/dccc" to insert the Document Control macro. Below you can see an example of the macro with "Space View" setting.

Example of the Space View macro.

Space view allows you to display additional information on the document state by checking the option "Show signature information in space view":

Show signature information in space view.

Space view by default shows all pages with the label "controlled-document". If you have the Document Control macro on pages without this label, you can list them also by using the option "Show all documents containing the Document Control macro in space view".

List documents for a reviewer

You can list all documents where you are a reviewer by going to the General Page and clicking on the button "Load Documents". The resulting table can be sorted by clicking on the column headers.

General Page

You can access the Document Control general page directly from the top menu. This page provides links to the documentation and signature authentication setup if enabled.

Document Control overview page.

Automation and webhook events

Document Control automation allows you to connect Document Control to an automation tool like Confluence Automation or ScriptRunner from Adaptavist.
Confluence Automation can query the Document Control status by using a web request ( Confluence Automation actions). The web request needs authentication information and can look similar to:
https://YOUR-SITE.atlassian.net/wiki/rest/api/content/search?cql=type=page+and+label="dc-review-change"+order+by+lastmodified,+title&expand=metadata.properties.dccc-state. Crafting this web request to your specific situation needs knowledge of CQL.


Document Control can add a label to a document if the review status changes. On the configuration page, you need to check the option "Use a label as a flag when document state changes."

When Document Control detects a change in the document review status, it will add a label to the document. The label acts like a flag. The default label is "dc-review-change". Adding a label generates a webhook event if you have set up a webhook listener. For example, ScriptRunner by Adaptavist lets you listen to such events and run automatic actions in response to such an event.

Once you have received the webhook event, you should remove the label from the document with your automation tool. If the label is not removed, subsequent changes to the document review state will not add a new label.

After receiving a webhook event, you can check the document review status and run an automation with e.g. ScriptRunner. The document review status can be queried by checking the content property "dccc-byline" of the document.


Document Control can send a webhook to a HTTPS URL. This webhook will send a POST request. For this request you can choose a payload, containing information about the document and its state. A webhook can be used to integrate with Confluence Automation. Usually the webhook is uses as a trigger/condition for Confluence Automation.
Warning Please make sure to only send a webhook and/or payload to a secure and trusted URL. It is your responsibility to make sure the URL is safe and the recipient is authorized to receive the information.

Automation information / payload

Confluence Automation allows you to receive a payload and/or to check Confluence page properties for the document state. When you receive a payload, the content of the payload is usually available as {{webhookData.body}} (see Triggers in Confluence automation - Integrations).
The value of the content property "dccc-byline" contains the property "documentStatus" with these possible values:

  1. "not-reviewed" A document is in this state if no reviewers are added to the document.
  2. "needs-review" If a document has reviewers, and not all reviewers have signed, a document is in this state.
  3. "reviewed" Once all reviewers have signed, a document is in the "reviewed" state.
Querying the content property "dccc-byline" returns a JSON object containing:

    "documentStatus": {
      "value": "not-reviewed"

In addition to listening to webhook events, you can check for the presence of the label "dc-review-change" on a regular schedule with e.g. a cron expression.

Document Control State

After adding a reviewer or a signature to a document, Document Control updates the content property "dccc-state". This content property encodes the current document state. You can read this property or receive it as the payload on a webhook and get information on reviewers, signatures, and document state. You should not modify this content property, as Document Control will rewrite the content property regularly.

Querying the content property "dccc-state" returns a JSON object. The example JSON object below contains comments (after //) explaining the field just before the comment. If you write code using the Document Control State, please check the field "stateFormatVersion". If this version is incremented, the format has changed.

"value": {
    "example": false,
    "stateFormatVersion": 2,
    "status": {
      "name": {
        "value": "Reviewed"
      "documentStatus": {
        "value": "reviewed"
    "documentVersion": 7,  // The Confluence assigned document version.
    "documentDt": "2021-06-28T14:26:03.593Z", // The timestamp of the last document edit.
    "documentId": "123456789",  // The Confluence Id of the document.
    "lastMeaning": "Review",  // The meaning of the last signature (if a meaning was given).
    "lastSigDt": "2021-06-28T14:26:22.700Z", // The timestamp of the last signature.
    "reviewersDt": "2021-06-28T14:26:22.700Z", // The timestamp of the last reviewers change.
    "reviewersVersion": 5,  // The version of the reviewers.
    "signaturesVersion": 2, // The version of the signatures.
    "signaturesDt": "2021-06-28T14:26:22.700Z", // The timestamp of the last signatures change.
    "signatures": [  // A list of signatures applied to the document in reverse chronological order.
        "most_recent": true,  // A property which is "true" if the signature was applied to the most recent document version.
        "version_known": true,
        "documentVersion": 7, // The document version the signature was applied to.
        "accountId": "XXXXXXXXXXXXXX", // The identifier of the user who signed.
        "timestamp": "2021-06-28T14:26:22.700Z", // The timestamp of the signature.
        "comment": "signature comment", // Signature comment, if present.
        "signature_version": 2,
        "meaning": "Review",  // The meaning of the signature (if a meaning was given).
        "name": "Jane Example", // The name of the signer.
        "documentId": "123456789", // The Confluence Id of the document to which the signature was applied.
        "documentDt": "2021-06-28T14:26:03.593Z" // The timestamp of the last document edit.
      {  // Another signature, it was applied to a previous document version.
        "most_recent": false,
        "version_known": true,
        "documentVersion": 6,
        "accountId": "XXXXXXXXXXXXXX",
        "timestamp": "2021-06-28T13:23:43.983Z",
        "comment": "old signature",
        "signature_version": 2,
        "meaning": "Other",
        "name": "John Example"
    "reviewers": [  // List of reviewers for the current document.
        "accountId": "XXXXXXXXXXXXXX", // The identifier of the reviewer.
        "name": "Jane Example", // The name of the reviewer.
        "signed": true,  // "true" if the reviewer signed the last document version, "false" if not.
        "meaning": "",
        "reviewerFormatVersion": 4

The "status" field describes the current document status as described above about the "dccc-byline" field.

The "signatures" list contains the most recent signatures with a limit of up to 50 signatures. The "reviewers" list contains the current document reviewers. If no signatures or reviewers are present, these lists will be empty.

Document Control State Format Information

The Document Control State content property is available from 2021-07-01. Documents produced before this date will not have a "dccc-state" content property. If a signature and/or reviewer is added to an older document, the "dccc-state" will be added with the information available. Documents produced before 2021-07-01 might not contain all information documented above. The content property might contain additional fields not documented here.


Page/space restrictions

If you have view/edit restrictions enforced either on a space or a page and wish to use the Document Control add-on, you'll need to ensure that the add-on user has both view and edit privileges (the add-on user is "Electronic Signing for Confluence Cloud"). You can change page restrictions by clicking on the lock symbol in top right of the Confluence page. This lock symbol will not be accessible if you don't have permission to change page restrictions.

Add the "Electronic Signing for Confluence Cloud" user:

Giving privileges to the add-on user.

Page versioning

The Document Control add-on uses Confluence's built-in versioning system to ensure that signatures are linked to a specific version of a page. For example, if a page has been signed by all reviewers, but is then edited, the Document Control macro will show that those signatures were for previous versions of the page:

Signatures for a previous version of the page.

You can click the link in the macro to see the full version history of the page:

Viewing a page's version history.

Note: Restoring a page to a previous version does not resolve the need to re-sign the page. This is because Confluence actually creates a new version that duplicates the restored version.

Signature visibility

As an option you can restrict signature visibility to show only signatures for the current document version. In order to apply this setting you need to edit the document (and thus create a new document version in this process). To change the setting you need to edit the Document Control macro and check the checkbox "Show signatures applied to the most recent document version only."

Viewing all signatures.

After checking the checkbox, only the most recent signatures are visible:

Viewing current document version signatures only.

If you later to decide to unchecked the checkbox, the earlier signatures will be visible again. Please note that this change also creates a new document version.

Page copying

The Document Control add-on stores information in each page's content properties. This is essentially a form of metadata stored in the page without being directly visible in the page's body.

The way Confluence handles content properties:

As a result, copies of controlled documents will not preserve signatures or reviewers. You should make sure to keep the original page intact and move it around your Confluence instance instead of making copies.
If you move a space containing signatures to another Confluence instance, it is necessary to disable the setting another Confluence instance automatically results in changes to the pages and content properties. You should add a new signature to each page, e.g. with a custom meaning of "document/space import approved", and then enable the setting again.

Outdated signatures error

If you get an error saying that there are outdated signatures, this is most likely caused by an older document template. Document templates created before 2022-07-19 might cause this error. A possible solution is to update the document template by creating a new document template and deleting the old one.


If you use SAML single sign-on to authenticate with Confluence, it's highly likely that the API Token Authentication setting will not work. Your users need to have an Atlassian account and password for the add-on's API authentication process to work. The other authentication methods will work.
The addon also offers SSO for signature authentication. This is described in the Set up section.

Set up

Installing the add-on

You can install Document Control LogoDocument Control for Confluence Cloud from the Atlassian Marketplace. Click the "Try it free" button to get started.

Configuration and settings

Once the add-on is installed, expand the Document Control for Confluence Cloud add-on in the Universal Plugin Manager and click "Configure".

The Universal Plugin Manager view of the add-on

The "Get started" page helps you with considering the configuration options.

The add-on "Get started" page.

The configuration page provides these settings:

The add-on configuration page.

Regulatory compliance setting

Authentication requires users to authenticate using their Confluence login before signing a page. (If your intent is to comply with 21 CFR 11, you should enable this setting.) If your approval flow is lightweight, you can disable this setting and allow users to review/approve a document with a click.

Document Control supports authentication with a secret key provided by Atlassian (API Key), authentication through a personal token or code, through a 2FA (two-factor authentication) process using an authenticator app, and using SSO with OpenID.

21 CFR 11 requires the signer to authenticate for each signature. Bulk signatures, i.e. a single electronic signature for multiple documents, are not conformant. Document Control offers both two-factor authentication and authentication using a secret key. Please contact us if you need additional authentication methods.

The "require signatures to match pages" ensures that signatures match the page where they were applied to. Troubleshooting / Page copying describes the usage of this setting when moving data to a new Confluence instance.

Authentication Settings documentation

Signature settings

The Signature Button setting enables a button with click to sign functionality in the Document Control macro.
The Meanings settings allow the configuration of meanings associated with each signature added to a controlled document. You can customize the available Meaning options (the default options are based on the language of 21 CFR §11.50), or disable Meanings entirely. Optionally you can define up to ten custom signature meaning types.
Once you have configured the meanings, these meanings show up during the signing flow and allow a signer to indicate the signature meaning.
The configuration option "Add a meaning/role to reviewers" allows adding a meaning when a reviewer is added to a document. If the option is enabled, you can pre-define a meaning for a reviewer. The reviewer has the option to change this at signature time. When the setting is "Locked to reviewer", only a signature with the pre-defined meaning is possible.

Reviewer settings

Notification: The Email notification setting will trigger automatic emails to reviewers whenever they are added to a page.

Restrictions: The restrictions settings allows to restrict editing, signing, and changing reviewers on a page. Restrictions will only be applied to a page after reviewers are updated.

Document Control can only adjust the restrictions if the user "Electronic Signing for Confluence Cloud" has the permissions to add/delete restrictions in the space. If the user "Electronic Signing for Confluence Cloud" does not have these permissions, the setting has no effect.

  1. Restrict page edits to reviewers, and give reviewers edit rights. This allows only reviewers to edit a page. When this setting is selected, a new reviewer automatically gets edit rights on the document. The final edit permission also depends on the group permissions of the reviewer.
  2. Restrict signatures to reviewers allows only reviewers to sign a page.
  3. Restrict changing reviewers to document editors allows only users with document edit rights to change the reviewers. As a document editor, you can add reviewers. These reviewers can sign documents, even if they have no edit rights.

Timestamp display: You can choose to display signature timestamps in either the ISO 8601 format (e.g. 2021-04-26T10:15:41Z), or in a US date format. The US format shows the abbreviated month and full weekday (e.g. Monday, Apr 26, 2021, 06:15 AM EDT). This display format prevents possible confusion about dates like 03/04/2021 in international settings.
The timezone for display of the timestamp can be set to either UTC or an IANA Time Zone Database listed time zone.

Automation settings

These settings are described at Automation and webhook events.


The Document Control changelog is available at Changelog.

Data security statement


The Document Control add-on helps with review and 21 CFR 11 compliant document signing on Confluence Cloud, including the ability to ensure that all signatures are authenticated at the time of signature. All transactions with Confluence Cloud are secured using Atlassian Connect Express / JWT. Data transport is secured using TLS (Transport Layer Security).

Data storage

The add-on server stores your configuration settings. It does not store any data from your Confluence instance, including users, pages, reviewers, signatures, or anything else. All of the data generated by the add-on is stored in your Confluence instance, not the add-on server. The Confluence instance is managed by you and Atlassian, and it is your and Atlassian's responsibility to ensure data integrity and access controls. As a user of Document Control, it is your responsibility to keep Confluence backups. These backups will allow you to restore lost documents and signatures. As we do not store your Confluence data, we do not have backups of those and can't restore lost documents and/or signatures.
If you opt in to secondary authentication (2FA, personal token), Document Control stores an identifier and cryptographic information to secure the secondary authentication process in your Confluence instance.


The add-on is not certified by any authority. 21 CFR 11 compliance is a complex process, and this add-on is merely a small part. Full compliance will depend on Confluence settings, user management, and other operational processes.


The add-on server, which stores your configuration settings, is automatically backed up by Heroku. In addition we keep offsite backups for disaster recovery. These backups do not contain your data from your Confluence instance.


All transactions are secured using HTTPS/JWT. Because no personal data is stored, there is no long-term privacy risk to using this add-on.

The add-on will request email addresses for your users if you enable the "Send email notification to new reviewers" option in the add-on configuration, and if you use an authentication method which uses email. Email addresses are only used to send one-time notifications to users who are added as reviewers for a page, and to users who use an authentication method requiring email. Email address are not stored in the add-on, shared, or used for any other purpose.

Secondary authentication (2FA) is based on TOTP,a fixed personal token or SSO through OpenID.


We keep logs in order to audit for possible security incidents and other errors.

21 CFR 11 compliance guidance


Confluence Cloud ("Confluence")See Atlassian documentation.
Document Control for Confluence Cloud ("Add-on")A Confluence add-on providing a technical solution for document review and electronic signing.

Subpart B - Electronic Records

§11.10(a)Validation of systemsThe organization is responsible for validating their Confluence installation and the add-on.
§11.10(b)Record generationConfluence has the ability to export documents in PDF or Word format.The add-on's macros will appear in exported records.The organization is responsible for keeping an immutable record (for example using a document management system). It is the organization's responsibility to ascertain Confluence pages do not contain dynamic content and/or embedded foreign content. For example, if a page contains an embedded live view of a Jira issue, the content of the Jira issue can change after signing the Confluence page. The reason is that the Confluence page does not contain the Jira issue, and the Jira issue is a separate entity.
§11.10(c)Protection of recordsConfluence provides the ability to backup or transfer pages.The add-on stores all data within Confluence pages.The organization is responsible for archiving, long term storage, and backups. Pages in Confluence can be modified and deleted, and Confluence is not an archival system.
§11.10(d)Limiting system accessConfluence provides the ability to manage users and groups, and to restrict privileges to particular users or content.The organization is responsible for managing access.
§11.10(e)Audit trailsConfluence keeps changes in a timestamped, secure audit log and in the page history. When a page is modified, the old version of the page is preserved by Confluence.The add-on links signatures to particular versions of a page, which will be reflected in the page history log. Signatures for older versions are preserved and visible via the Document Control macro.The organization is responsible for archiving, long term storage, and backups.
§11.10(f)SequencingThe add-on ensures all steps happen in the proper order.
§11.10(g)Authority checksSee Confluence Cloud data security policies.The add-on is only available to authenticated Confluence users, and can be configured to require additional authentication at time of signing.
§11.10(h)ValidityThe organization should ensure this for all devices that use Confluence/the add-on.
§11.10(i)Education and trainingThe organization should ensure that all users are properly educated, trained, and experienced.
§11.10(j)Written policiesThe organization should write and distribute policies related to electronic signatures.
§11.10(k)Controls documentationThe organization is responsible for maintaining controls documentation.
§11.50(a)Signature manifestationsThe add-on ensures that signatures include the printed name of the signer and the data and time when the signature was executed. The add-on can be configured to include a signature meaning.The organization is repsonsible for correct user enrollment and accounts.
§11.50(b)Signature recordsThe add-on ensures signature manifestations are part of the electronic record by storing them within the Confluence page.The organization is responsible for keeping an immutable record (for example using a document management system).
§11.70Signature/record linkingThe add-on does not move signatures between records, and copied records do not retain electronic signatures. See Page copying for more detail.The organization is responsible for records moving in and out of a specific Confluence instance.

Subpart C - Electronic Signatures

§11.100(a)UniquenessThe add-on ensures electronic signatures are unique to one Confluence account.The organization should ensure that Confluence accounts are unique to one individual, and that Confluence accounts shall not be reused by, or reassigned to, anyone else.
§11.100(b)Identify verificationThe organization should verify the identity of individuals before assigning a Confluence account.
§11.100(c)Agency certificationThe organization should certify their use of electronic signatures in writing as per §11.100(c), and persons within the organization should provide any additional certification or testimony as required.
§11.200(a)(1)Identification componentsThe add-on can be configured to require users to provide their email address (i.e. identification code) and/or a secure token before signing. Multiple authentication methods are available, and the organization is responsible for the validation of the chosen method.The organization should enable authentication for all signatures in the add-on's configuration.
§11.200(a)(1)(i)Single sessionThe add-on can be configured to require authentication for all signatures.The organization should enable authentication for all signatures in the add-on's configuration.
§11.200(a)(1)(ii)Multiple sessionsThe add-on can be configured to require authentication for all signatures.The organization should enable authentication for all signatures in the add-on's configuration.
§11.200(a)(2)Genuine ownersThe add-on can be configured to require authentication for all signatures.The organization should ensure authentication information for Confluence accounts is only known, or can only be used, by the account's genuine owners.
§11.200(a)(3)Unauthorized attemptsThe organization should take steps to ensure that use of an individual's Confluence account by anyone other than its genuine owner requires collaboration of two or more individuals.
§11.300Controls for identification codes/passwordsThe organization is responsible for maintaining controls for Confluence authentication information.

Document Control Logo Document Control for Confluence Cloud



© 2024  Phase Locked Software