Managing documents

After a document is submitted from the Frontend, the Frontend plug-in receives it and it is then added to the Preconfirmation queue. The document must get required number of approvals from Auditors before it can be moved into a signing iteration.

When a document is signed during a signing iteration, it is moved into the Postconfirmation queue. It must get required number of approvals from Auditors before it can be moved back to the Frontend plug-in.

The Preconfirmation or Postconfirmation queue receives the document list from Frontend or Backend plug-in. Each document contains a id, signature, content, and metadata. For more information about the API specification, see the frontend_plugin.yaml file that is located under openapi/public in the downloaded package. The document is OpenAPI formatted and any API tools, such as Swagger UI can be used to test with.

The following example shows the contents that are provided by the GET {UI_ENDPOINT}/api/{pre|post}/v1alpha1/audit/documents API endpoint on the confirmation queues. Auditors can use this information to decide on whether to approve or deny a document.

{
   "documents":[
     {
        "id": "b2257774-6914-44d9-a07f-62de6ce130d6", 
        "num_of_approvers": 2, 
        "num_of_deniers": 0,
        "approvers": ["CN=user2,O=EXAMPLE,C=US", "CN=user1,O=EXAMPLE,C=US"],
        "deniers": [], 
        "doc_age": 2463.573837152, 
        "confirm_age": 1800.7083304450002, 
        "time_to_release": 0, 
        "status": "moved", 
        "required_approvals": 2, 
        "pending_approvals": 0, 
        "metadata": ""
     },
    {
        "id": "12e7d613-be15-4617-a115-551ecb1f58d2", 
        "num_of_approvers": 0, 
        "num_of_deniers": 0,
        "approvers": [], 
        "deniers": [], 
        "doc_age": 2463.570601507, 
        "confirm_age": null, 
        "time_to_release": null, 
        "status": "queued", 
        "required_approvals": 2, 
        "pending_approvals": 2, 
        "metadata": ""
    }
  ],
   "trace_id": "0064df36-9c3e-5904-c1aa-0801d8f510d7"
}  
 

The parameter descriptions are listed below:

• id: The unique ID of a transaction document after it's submitted to the Offline Signing Orchestrator.
• num_of_approvers: The number of approvals that a document receives from Auditors.
• num_of_deniers: The number of denials that a document receives from Auditors.
• approvers: A list of Auditors who approved the document.
• deniers: A list of Auditors who denied the document.
• doc_age: The length of time in seconds after the document is added to the queue.
• confirm_age: The length of time in seconds after the document is approved with required number of approvals.
• time_to_release: The length of time that an approved document needs to wait for before it can be added to a signing iteration. For more information, see Time based security.
• status: The document status in the queue includes:
  • Queued : The document is added to the queue.
  • Approved : The document is approved with the required number of approvals from Auditors.
  • Denied : The document is denied by at least one Auditor.
  • Moved : The document is moved out of the queue to the next component successfully.
  • Timed out : The document does not get the required approvals within the preconfigured time duration.
• required_approvals: The required number of approvals that a document must get before it can be added to a signing iteration.
• pending_approvals: The number of approvals that a document still needs before it is approved.
• metadata: When confirmation queues receive documents from the plugins, the plugins can provide any necessary information to help Auditors decide whether to approve or deny a document. The metadata is a required field but can be populated with an empty object. Ensure that the metadata does not contain any sensitive or confidential personal information.
• trace_id: The trace ID of the request.

An Auditor can approve a document that is in the Queued state.

When required number of Auditors approve a document, the document is changed to Approved status and the Release time starts to count down. After the preconfigured Release time passes, the document can be added to a signing iteration and the document is then changed to Moved status.

POST {UI_ENDPOINT}/api/pre/v1alpha1/audit/{document_id}/approve
POST {UI_ENDPOINT}/api/post/v1alpha1/audit/{document_id}/approve
 

An Auditor can approve multiple documents that are in the Queued state.

When the required number of Auditors approve the documents, the documents are changed to Approved state and the Release time starts to count down. After the preconfigured Release time passes, the documents can be added to a signing iteration and the documents are then changed to Moved status.

POST {UI_ENDPOINT}/api/pre/v1alpha1/audit/documents/approve
**Headers:**
Content-Type: application/json
(mTLS authentication via client certificate)

**Body:**
{
  "document_ids": [
    "caee9a3c-066d-4be6-9bdb-71a8288c952d",
    "2b7a7c45-3a52-4f6f-98b9-6394aea04761"
  ]
}
POST {UI_ENDPOINT}/api/post/v1alpha1/audit/documents/approve
**Headers:**
Content-Type: application/json
(mTLS authentication via client certificate)

**Body:**
{
  "document_ids": [
    "caee9a3c-066d-4be6-9bdb-71a8288c952d",
    "2b7a7c45-3a52-4f6f-98b9-6394aea04761"
  ]
}
 

An Auditor can deny a document that is in the Queued or Approved status.

When any Auditor denies a document, the document is changed to Denied status. An approved document can be denied but a denied document cannot be approved. Denied documents cannot be added to a signing iteration.

POST {UI_ENDPOINT}/api/pre/v1alpha1/audit/{document_id}/deny
POST {UI_ENDPOINT}/api/post/v1alpha1/audit/{document_id}/deny
 

An Auditor can deny multiple documents that are in the Queued or Approved status.

When any Auditor denies the documents, the documents are changed to Denied status. Approved documents can be denied. However, denied documents cannot be approved. Denied documents cannot be added to a signing iteration.

POST {UI_ENDPOINT}/api/pre/v1alpha1/audit/documents/deny

**Headers:**
Content-Type: application/json
(mTLS authentication via client certificate:
  --cert {CLIENT_CERT_PATH}
  --key  {CLIENT_KEY_PATH}
)

**Body:**
{
  "documentIds": [
    "0c10ef9b-f47d-4189-bbc7-90050e10a174",
    "b722aed6-5209-48b-a9cb-b63be8e4c0a8"
  ]
}

POST {UI_ENDPOINT}/api/post/v1alpha1/audit/documents/deny

**Headers:**
Content-Type: application/json

Authentication:
mTLS authentication via client certificate:
  --cert {CLIENT_CERT_PATH}
  --key  {CLIENT_KEY_PATH}

**Body:**
{
  "documentIds": [
    "0c10ef9b-f47d-4189-bbc7-90050e10a174",
    "b722aed6-5209-48b1-a9cb-b63be8e4c0a8"
  ]
}