Skip to content

Workflow

Overview

The Workflow API is designed to manage the creation and updating of documents within a specific schema. It combines several steps, involving checks, validation, and saving processes, to ensure the integrity and proper handling of documents.

Steps Overview:

  1. Check Document ID: Verify if the document ID exists. This step also ensures that the document is not locked.

  2. Create Securities: If the document ID is valid, securities are created.

  3. Validate Document: The document is validated against a specific.

  4. Save Draft: After validation, the document draft is saved.

  5. Initiate Workflow: Finally, the workflow is initiated.

The API allows the creation or updating of documents. The request body must include a valid document parameter. If there are any validation errors, the system will return detailed error messages based on the content of the document.

Endpoint

Create a Document

To create a new document, use the POST method with one of the following endpoints:

POST /api/v2023/documents/schemas/:schema
POST /api/v2023/documents/schemas/:schema/:identifier?

Update a Document

To update an existing document, use the PUT method with the following endpoint:

PUT /api/v2023/documents/schemas/:schema/:identifier

Headers

The request must include the following headers:

FieldTypeDescription
Content-TypeStringSpecifies the media type of the request body. This header indicates the format of the data being sent to the server. The allowed value is application/json, which means the request body is formatted as JSON. This helps the server understand how to parse and process the incoming data.
AuthorizationStringProvides the token used to authenticate the request. This header is essential for identifying and verifying the client making the request. The token should be included in the header to gain access to protected resources or services. Ensure that the token is kept secure and is valid for the requested operation.
RealmStringDefines the specific context or environment in which the Clearing-House request is being made. The allowed values are abs, chm, and bch, each representing different operational contexts. This helps the server route the request appropriately based on the specified realm.
AcceptStringSpecifies the format in which the client expects the server to return the response data. The allowed value is application/json, indicating that the client prefers the response in JSON format. This informs the server of the desired response format, ensuring that the client receives data in a readable and expected format.

Realm Values for Development:

  • abs-dev: Represents the development environment for ABS (Access and Benefit-sharing Clearing-House). Use this value when testing or developing features related to ABS in a non-production setting.
  • bch-dev: Indicates the development environment for BCH (Biosafety Clearing-House). This value is used for testing or development purposes related to BCH functionalities.
  • chm-dev: Specifies the development environment for CHM (Central Clearing-House Mechanism). This realm is used when working on features or testing in the CHM context within a development environment.

Headers required to authenticate and define the context and format of the request and response. The Authorization header must contain a valid token, while the Content-Type and Accept headers specify the format of the document and response, respectively. Here are the steps to get the Authorization token.

URL Parameters

The following query parameters can be used to refine the request:

FieldTypeDescription
schemaStringDefines the schema or format of the document being posted. This field specifies the type of document and the structure it adheres to. The schema value helps the system understand how to interpret and validate the incoming data. It ensures that the document conforms to a predefined format or standard, facilitating consistency and compatibility across different parts of the system. The schema value typically corresponds to a specific schema definition or type that dictates the required fields, data types, and constraints for the document.
identifierStringSpecifies the unique identifier for the document. This identifier is used to locate, retrieve, update, or delete the document within the system. It ensures that each document can be uniquely referenced, supporting precise operations on specific records and avoiding conflicts with other documents.

Query Parameters

The request must include the following query parameters:

FieldTypeDescription
RealmStringDefines the specific context or domain within which the Clearing-House request is being made. This header determines the environment or operational scope for the request. Allowed values include abs (Access and Benefit-sharing Clearing-House), chm (Central Clearing-House Mechanism), and bch (Biosafety Clearing-House). Each value represents a different area of functionality or service.

Realm Values for Development:

  • abs-dev: Represents the development environment for ABS (Access and Benefit-sharing Clearing-House). Use this value when testing or developing features related to ABS in a non-production setting.
  • bch-dev: Indicates the development environment for BCH (Biosafety Clearing-House). This value is used for testing or development purposes related to BCH functionalities.
  • chm-dev: Specifies the development environment for CHM (Central Clearing-House Mechanism). This realm is used when working on features or testing in the CHM context within a development environment.

Request Body

The request body should be a JSON object containing the following fields:

FieldTypeDescriptionRequired
documentObjectThe schema object that represents the body of the record type. For example, the IRCC schema.Yes
additionalInfoStringAdditional information related to the document. This field can hold a maximum of 1000 characters.

Note: This field is available only when a user with the NAU role is submitting a request to the PA to publish a record.
No
batchIdStringAn optional identifier for batching multiple records together for publishing. Maximum of 100 characters.No

Validation Error

POST Request Error

When using the POST method, If a record with the unique identifier already exists, a 400 Bad Request error will be returned. To update an existing record, please use the HTTP PUT method instead.

Status CodeError Message
400A document with the identifier exists, please use a different 'identifier'.

PUT Request Error

When using the PUT method, If a record with the unique identifier does not exists, a 400 Bad Request error will be returned. To create a record, please use the HTTP POST method instead.

Status CodeError Message
400A document with the identifier does not exist, please provide correct 'identifier' to update.

The following error conditions may occur while interacting with the API. Each entry describes a specific error status code, along with an error message explaining the issue and any additional requirements for successful execution.

Status CodeDescription
400realm param is missing, please provide valid realm in querystring or httpHeaders
400Realm is not configured, please provide valid realm.
400Schema not configured for the given realm ${realm}.
400A document with the identifier exists, please use a different 'identifier'.
400A document with the identifier does not exist, please provide correct 'identifier' to update.
400The record is locked for workflow, cannot proceed.
403Insufficient rights to update the draft record.
403Insufficient rights to create a draft record.
403Authorization required, user is anonymous.

When the document parameter is included in the request body, any issues with the document’s content will be detailed in the "errors" property of the response. Each error in this property is represented by an object containing the specific error code and the related field or property. Below is an example response showing the structure of the "errors" property, followed by a table describing the possible error types and their meanings.

Example Error Response:
json
{
    "identifier": "DECLARE-ORGANISATION_5885_20241031144831187",
    // Additional properties may be included based on the request.
    "errors": [
        {
            "code": "Error.Mandatory",
            "property": "government"
        }
    ]
}

The table below provides descriptions for each error type that may appear in the "errors" property. These errors are intended to help identify missing or incorrect fields and values within the document parameter, enabling precise adjustments to meet validation requirements.

Error TypeDescription
Error.MandatoryIndicates a required field is missing.
Error.MandatoryAnyOfIndicates at least one field from a set of mandatory fields is missing.
Error.InvalidValueIndicates the provided value is not valid according to the specified
schema.
Error.InvalidPropertyIndicates an invalid property or field name.
Error.UnspecifiedLocaleIndicates a locale or language code is missing or invalid.
Error.UnexpectedTermIndicates an unexpected term or parameter.
Error.InvalidTypeIndicates the provided data type is not valid.

Playground

Swagger playground is loading, please wait...