• Register

Controlled Document Management API

The Controlled Document Management API allows you to import documents and training assignments. These APIs require the Egnyte.controlleddocs scope.

Import a Document

This endpoint is used to import a new document or a new version of an existing document in the Controlled Document Management app. When executed as an admin, it will allow importing documents to all the categories of the Controlled Docs. Executing as a Category Manager will only allow importing documents to the categories they manage.

POST/pubapi/v1/controlled-docs/documents/import

Request Parameters in the Request Body

Parameter Description Required Possible Values
docId Document Identifier to be used within Controlled Document Management Yes string
example: SOP-1
name Name of the Document to be used within Controlled Document Management Yes string
example: Change Management SOP
version Specific version of the document to be used within Controlled Document Management Yes string
example: 1.0, 1.1
entryId Unique ID of the version of the file to be imported to Controlled Document Management Yes string
example: f450227d-044c-45b5-9dbb-c1120a856b81
responsibleDepartment The department/personnel responsible to maintain the document No string
example: Clinical
effectiveFromDate The date document becomes effective Yes string in YYYY-MM-DD format
example: 2023-01-22
effectiveToDate The date document effective period ends Yes string in YYYY-MM-DD format
example: 2024-01-21
approvedOn The date document is approved Yes string in YYYY-MM-DD format
example: 2022-12-17

Request Examples

  POST /pubapi/v1/controlled-docs/documents/import HTTP/1.1
  Host: apidemo.egnyte.com
  Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
  Content-Type: application/json
  {
      "docId": "SOP-1",
      "name": "Change Management SOP",
      "version": "1.0",
      "entryId": "f450227d-044c-45b5-9dbb-c1120a856b81",
      "responsibleDepartment": "Clinical",
      "effectiveFromDate": "2023-01-22",
      "effectiveToDate": "2024-01-21",
      "approvedOn": "2022-12-17"
  }

Response

A successful request will return an HTTP 201 status code with the Controlled Document Management internal identifier for the imported document.

  {
      "id": "f450227d-044c-45b5-9dbb-c1120a856b81"
  }

A failed request will include a response body in the following format:

{
    "msg": "Detailed error message"
}

The following HTTP status codes may be returned in the case of a failed request:

Status Code Error Details
400 One of the following issues:
  • Docuemnt migration is not enabled for this category
  • Document version is not the next major or minor version
  • Approval date cannot be in the future
  • Approval date cannot be after the effective on date
  • Document version number does not match the effective time period
403 User cannot add new documents to the category
404 Entry id does not exist
409 One of the following issues:
  • Document version already exists for this document
  • Document identifier conflicts with an existing document

Import Training Assignments

This endpoint is used to import training assignment records into the Controlled Document Management app. When executed as an admin, it will allow importing training records of users from all the categories of the Controlled Docs. When executed as a Category Manager, it will only allow importing training records of users from the categories they manage. The Training assignment status will automatically be calculated by the system based on the dueDate, completedDate and canceledDate.

POST/pubapi/v1/controlled-docs/assignments/import

Request Parameters in the Request Body

Parameter Description Required Possible Values
assigneeId ID of the user who is assigned the training Yes Integer
example: 11
docId Document ID of a document for which training is assigned Yes string
example: SOP-1
version Document Version of a document for which training is assigned Yes string
example: 1.0, 1.1
assignedDate The date on which training assignment gets created
Note: When the assignedDate is not set, the system will use the current date		 No string in ISO-8601 format
example: 2023-01-22T14:00:00Z
dueDate The due date of training assignment Yes string in YYYY-MM-DD format
example: 2023-02-22
completedDate The training assignment completion date
Note: You need to set completedDate only for importing completed training assignments.		 No string in ISO-8601 format
example: 2023-01-27T16:22:07Z
canceledDate The date when training assignment gets canceled
Note: You need to set cancedDate only for importing canceled training assignments		 No string in ISO-8601 format
example: 2023-01-22T14:38:32Z
assignedById ID of the user who assigns the training
Note: When the assignedById is not set, the system will use the ID of the requesting user.		 No Integer
example: 22

Request Examples

    POST /pubapi/v1/controlled-docs/assignments/import HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Type: application/json
    {
        "assigneeId": 11,
        "docId": "SOP-1",
        "version": "1.0",
        "assignedDate": "2023-01-22T14:00:00Z",
        "dueDate": "2023-02-22",
        "completedDate": "2023-01-27T16:22:07Z",
        "assignedById": 22
    }

Sample Response

A successful request will return an HTTP 201 status code with the Controlled Document Management training assignemnt identifier.

  {
      "id": "e250227d-044c-45b5-9dbb-c1120a856b84"
  }

A failed request will include a response body in the following format:

{
    "msg": "Detailed error message"
}

The following HTTP status codes may be returned in the case of a failed request:

Status Code Error Details
400 Assignee does not have permission to view the category
403 One of the following issues:
  • Caller doesn't have permission to manage assignments for the category
  • Assignee doesn't have permissions to the document
404 Referenced document not found
409 Operation not allowed for an obsolete document

version 3 as of 10 months ago by Greg Neustaetter