Autologyx Docs

Appearance

Object Classes Document Template ​

This technical design describes implementation and API for Object Classes Document Template.

POST /api/object-classes/object_class_id/document-templates/ ​

Creates document template.

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
  • Body parameters
KeyTypeNotes
namestring
descriptionstring
template_filestringFile token
allow_on_demand_generationbool
  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
POST /api/object-classes/1/document-templates/

{
    "name": "Test Document Template",
    "description": "",
    "template_file": "9d1b16dc-db37-4631-8469-804c7d4048b2",
    "allow_on_demand_generation": true
}

Validations ​

  • name
    • is string
    • is required
    • unique (case insensitive) for the given Object Class
    • max length is 100
    • must be trimmed of white spaces
  • description
    • is string
    • is optional
    • max length is 500
  • template_file
    • is a file type (accepts uploaded file token, see doc)
    • is required
    • only " .docx " files allowed
    • only 1 file is allowed
    • validate Jinja template syntax
    • validate merge tags:
      • related classes
  • allow_on_demand_generation
    • is bool

Restrictions ​

  • Up to 1000 Document Templates per Object Class can be added, limit is configurable per build.

Response ​

KeyTypeNotes
idpkAutomatically generated by the backend.
namestringName of the document template
descriptionstringDescription of the document template
template_fileintegerId of the template file
allow_on_demand_generationbool
created_atdatetime
warningstring
created_byuser
modified_atdatetime
modified_byuser
_meta.labels.filesObjectObject containing template files details

Response _meta.labels.files object ​

KeyTypeNotes
namestringTemplate file name with extension
urlstringTemplate file download URL
sizestringTemplate file size in bytes
typestringTemplate file extension
  • Successful status 201 Created
  • Response body:
json
{
    "id": 1,
    "name": "Test Document Template",
    "description": "",
    "template_file": 27,
    "allow_on_demand_generation" : true,
    "warning" : "",
    "created_at": "2022-10-13T10:22:33.344172+02:00",
    "created_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "modified_at": "2022-10-13T10:22:33.344193+02:00",
    "modified_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "_meta": {
        "labels": {
            "files": {
                "27": {
                    "name": "test.docx",
                    "url": "http://client.testserve/api/object-classes/1/document-templates/1/download/",
                    "size": "8085",
                    "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
                }
            }
        }
    }
}

Errors ​

CauseResponse status codeResponse message
Invalid object_class_id in URL403 Forbidden"detail": "You do not have permission to perform this action."
name missing400 Bad Request"name": ["This field is required."]
name is empty400 Bad Request"name": [ "This field may not be blank." ]
name is null400 Bad Request"name": [ "This field may not be null." ]
name not unique400 Bad Request"name": ["This field must be unique."]
name too long400 Bad Request"name": ["Ensure this field has no more than 100 characters."]
description too long400 Bad Request"description": ["Ensure this field has no more than 500 characters."]
template_file missing400 Bad Request"template_file": ["This field is required."]
template_file is null400 Bad Request"template_file": [ "This field may not be null." ]
template_file not docx400 Bad Request"template_file": ["Invalid file type."]
allow_on_demand_generation invalid value400 Bad Request"allow_on_demand_generation": ["Must be a valid boolean."]
Exceeded max number of templates400 Bad Request"detail": "Limit of 1000 Document Templates has been exceeded.", "error_code": "ERR_LIMIT_EXCEEDED"
Document can't be parsed400 Bad Request"error": ["Error while parsing document. Please check the syntax."]
Class not related400 Bad Request"error": ["Merge field { name } refers to a Class ID={id} which is not related with Class ID={id}."]
Insufficient permissions403 Forbidden"detail": "You do not have permission to perform this action."

GET /api/object-classes/object_class_id/document-templates/ ​

Returns list of document templates.

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
GET /api/object-classes/`object_class_id`/document-templates/

Response ​

KeyTypeNotes
limitint
offsetint
total_countintTotal number of results visible to the user (based on permissions).
filtered_countintNumber of results visible to the user (based on permissions) with filters applied.
nexturlNext page URL (null if there is no next page)
previousurlPrevious page URL (null if there is no previous page)
resultsArrayList of results. Described in the next table.

Response results array ​

KeyTypeNotes
idpkAutomatically generated by the backend.
namestringName of the document template
descriptionstringDescription of the document template
template_fileintegerId of the template file
template_file_namestringName of the template file without extension
allow_on_demand_generationbool
warningstring
created_atdatetime
created_byuser
modified_atdatetime
modified_byuser
_meta.labels.filesObjectObject containing template files details
  • Successful status 200 OK
  • Response body schema
json
{
  "limit": 100,
  "offset": 0,
  "filtered_count": 1,
  "total_count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 3,
      "name": "Document Templates Test",
      "description": "",
      "template_file": 29,
      "template_file_name": "test",
      "allow_on_demand_generation": true,
      "warning": "",
      "created_at": "2022-10-17T11:29:01.694549+02:00",
      "created_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
      },
      "modified_at": "2022-10-17T11:29:01.694569+02:00",
      "modified_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
      },
      "_meta": {
        "labels": {
          "files": {
            "29": {
              "name": "test.docx",
              "url": "/api/object-classes/1/document-templates/3/download/",
              "size": "152199",
              "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
            }
          }
        }
      }
    }
  ]
}

Sorting ​

ParameterExampleNotes
id{build}/api/object-classes/id/document-templates/?ordering=idAscending
id{build}/api/object-classes/id/document-templates/?ordering=-idDescending (-)
name{build}/api/object-classes/id/document-templates/?ordering=nameAscending
name{build}/api/object-classes/id/document-templates/?ordering=-nameDescending (-)
allow_on_demand_generation{build}/api/object-classes/id/document-templates/?ordering=allow_on_demand_generationAscending
allow_on_demand_generation{build}/api/object-classes/id/document-templates/?ordering=-allow_on_demand_generationDescending (-)
created_at{build}/api/object-classes/id/document-templates/?ordering=created_atAscending
created_at{build}/api/object-classes/id/document-templates/?ordering=-created_atDescending (-)
modified_at{build}/api/object-classes/id/document-templates/?ordering=modified_atAscending
modified_at{build}/api/object-classes/id/document-templates/?ordering=-modified_atDescending (-)

Filtering ​

Please check ALX API standards for predicates available per type.

ParameterType
uuiduuid
namestring
template_file_namestring
allow_on_demand_generationbool
warningstring
created_atdatetime
created_byuser
modified_atdatetime
modified_byuser

Errors ​

ErrorResponse codeMessage
Wrong ordering value400 Bad Request"ordering": ["Select a valid choice. {value} is not one of the available choices."]

GET /api/object-classes/object_class_id/document-templates/document_template_id/ ​

Permissions ​

Requires authentication and document-templates.edit permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idid
document_template_idid
  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
GET /api/object-classes/`task_group_templates_id`/document-templates/`document_template_id`

Response ​

KeyTypeNotes
idpkAutomatically generated by the backend.
namestringName of the document template
descriptionstringDescription of the document template
template_fileintegerId of the template file
allow_on_demand_generationboolId of the template file
warningstringId of the template file
created_atdatetime
created_byuser
modified_atdatetime
modified_byuser
_meta.labels.filesObjectObject containing template files details

Response example ​

  • Status 200 OK
  • Body
json
{
    "id": 1,
    "name": "Test Document Template",
    "description": "",
    "template_file": 1,
    "allow_on_demand_generation" : true,
    "warning" : "",
    "created_at": "2022-10-13T10:22:33.344172+02:00",
    "created_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "modified_at": "2022-10-13T10:22:33.344193+02:00",
    "modified_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "_meta": {
        "labels": {
            "files": {
                "27": {
                    "name": "test.docx",
                    "url": "http://client.testserve/api/object-classes/1/document-templates/1/download/",
                    "size": "8085",
                    "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
                }
            }
        }
    }
}

Sorting ​

Not supported

Filtering ​

Not supported

Errors ​

ErrorResponse codeMessage
A non-existent document_template_id was given404 Not Found"detail": "Not found."
A non-existent object_class_id was given404 Not Found"detail": "Not found."
Insufficient permissions403 Forbidden"detail": "You do not have permission to perform this action."

PATCH /api/object-classes/object_class_id/document-templates/document_template_id/ ​

Updates single document template.

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
document_template_idpk
allow_on_demand_generationbool
  • Body parameters
KeyTypeNotes
namestring
descriptionstring
template_filestringFile token
  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
PATCH /api/object-classes/1/document-templates/1/

{
    "name": "Test Document Template",
    "description": "",
    "template_file": "9d1b16dc-db37-4631-8469-804c7d4048b2",
    "allow_on_demand_generation" : true
}

Response ​

KeyTypeNotes
idpkAutomatically generated by the backend.
namestringName of the document template
descriptionstringDescription of the document template
template_fileintegerId of the template file
allow_on_demand_generationbool
warningstring
created_atdatetime
created_byuser
modified_atdatetime
modified_byuser
_meta.labels.filesObjectObject containing template files details
  • Successful status 200 OK
  • Response body schema:
json
{
    "id": 1,
    "name": "Test Document Template",
    "description": "",
    "template_file": 27,
    "allow_on_demand_generation" : true,
    "warning" : "",
    "created_at": "2022-10-13T10:22:33.344172+02:00",
    "created_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "modified_at": "2022-10-13T10:22:33.344193+02:00",
    "modified_by": {
        "id": 2,
        "first_name": "John",
        "last_name": "Kovalsky",
        "username": "john.kovalsky@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
    },
    "_meta": {
        "labels": {
            "files": {
                "27": {
                    "name": "test.docx",
                    "url": "http://client.testserve/api/object-classes/1/document-templates/1/download/",
                    "size": "8085",
                    "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
                }
            }
        }
    }
}

Errors ​

CauseResponse status codeResponse message
Invalid object_class_id in URL403 Forbidden"detail": "You do not have permission to perform this action."
Invalid id in URL404 Not Found"detail": ["Not found."]
name missing400 Bad Request"name": ["This field is required."]
name is empty400 Bad Request"name": [ "This field may not be blank." ]
name is null400 Bad Request"name": [ "This field may not be null." ]
name not unique400 Bad Request"name": ["This field must be unique."]
name to long400 Bad Request"name": ["Ensure this field has no more than 100 characters."]
description to long400 Bad Request"description": ["Ensure this field has no more than 500 characters."]
template_file missing400 Bad Request"template_file": ["This field is required."]
template_file is null400 Bad Request"template_file": [ "This field may not be null." ]
template_file not docx400 Bad Request"template_file": ["Invalid file type."]
allow_on_demand_generation invalid value400 Bad Request"allow_on_demand_generation": ["Must be a valid boolean."]
Exceeded max number of templates400 Bad Request"detail": "Limit of 1000 Document Templates has been exceeded.", "error_code": "ERR_LIMIT_EXCEEDED"
Document can't be parsed400 Bad Request"error": ["Error while parsing document. Please check the syntax."]
Class not related400 Bad Request"error": ["Merge field { name } refers to a Class ID={id} which is not related with Class ID={id}."]
Insufficient permissions403 Forbidden"detail": "You do not have permission to perform this action."

DELETE /api/object-classes/object_class_id/document-templates/document_template_id/ ​

Deletes single document template.

Important

During deletion, the use of Document Template in Sequences is checking.

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
document_template_idpk
  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
DELETE /api/object-classes/1/document-templates/1/

Response ​

  • Successful status 204 No Content

Errors ​

ErrorResponse codeMessage
object_class_id is invalid404 Bad Request"detail": "Not found."
document_template_id is invalid404 Bad Request"detail": "Not found."
Unauthorized API call403 Bad Request"detail": "You do not have permission to perform this action."
Document Template is in use400 Bad Request"detail": "Document Template is in use by Sequences."

GET /api/object-classes/object_class_id/document-templates/document_template_id/usage/ ​

Permissions ​

Requires authentication and object_classes.view permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
document_template_idpk
  • Headers
Content-Type: application/json
Authorization: JWT access_token

Response ​

KeyTypeNotes
num_of_sequencesint
sequencesArray

Response sequences array ​

KeyTypeNotes
idintSequence id
namestringName of sequence

Response ​

  • Successful status 200 OK
  • Response body:
json
{
    "num_of_sequences": 1, 
    "sequences": [
        {
            "id": 1,
            "name": "Sample sequence"
        }
    ]
}

Errors ​

ErrorResponse codeMessage
object_class_id is invalid404 Bad Request'detail': "Not found."
document_template_id is invalid404 Bad Request'detail': "Not found."
Unauthorized API call403 Bad Request'detail': "You do not have permission to perform this action."

OPTIONS /api/object-classes/object_class_id/document-templates/ ​

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
OPTIONS /api/object-classes/1/document-templates/

Response ​

  • Successful status 200 OK
  • Response body:
json
{
    "list": {
        "columns": [
            {
                "alias": "id",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "name",
                "type": "string",
                "predicates": [
                    "exact",
                    "iexact",
                    "contains",
                    "icontains",
                    "startswith",
                    "istartswith",
                    "endswith",
                    "iendswith"
                ],
                "sort_ok": true
            },
            {
                "alias": "description",
                "type": "string",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "template_file_name",
                "type": "string",
                "predicates": [
                    "exact",
                    "iexact",
                    "contains",
                    "icontains",
                    "startswith",
                    "istartswith",
                    "endswith",
                    "iendswith"
                ],
                "sort_ok": false
            },
            {
                "alias": "allow_on_demand_generation",
                "type": "bool",
                "predicates": [
                    "exact"
                ],
                "sort_ok": true
            },
            {
                "alias": "created_at",
                "type": "datetime",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "created_by",
                "type": "user",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false,
                "autocomplete": "/api/users/autocomplete/?text__icontains="
            },
            {
                "alias": "modified_at",
                "type": "datetime",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "modified_by",
                "type": "user",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false,
                "autocomplete": "/api/users/autocomplete/?text__icontains="
            }
        ]
    },
    "details": {
        "schema": [
            {
                "alias": "name",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "min_length",
                        "length": 1
                    },
                    {
                        "type": "max_length",
                        "length": 100
                    }
                ]
            },
            {
                "alias": "description",
                "type": "string",
                "required": false,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 500
                    }
                ]
            },
            {
                "alias": "template_file",
                "type": "file",
                "required": true,
                "validators": [
                    {
                        "type": "allowed_extensions",
                        "extensions": [
                            "docx"
                        ]
                    },
                    {
                        "type": "max_size",
                        "size": 1
                    }
                ]
            }
        ]
    },
    "restrictions": {
        "limit_items_in_object_class": 1000
    }
}

POST /api/object-classes/object_class_id/document-templates/verify/ ​

Creates document template.

Permissions ​

Requires authentication and object_classes.edit permission.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
  • Body parameters
KeyTypeNotes
template_filestringTemporary File token or ID of Object Class Document File
  • Headers
Content-Type: application/json
Authorization: JWT access_token
  • Schema
json
POST /api/object-classes/1/document-templates/verify/

{
    "template_file": "9d1b16dc-db37-4631-8469-804c7d4048b2"
}

Validations ​

  • template_file
    • is required
    • is Temporary file token or Object Class Document File ID
    • validate Jinja template syntax
    • validate merge tags:
      • related classes
      • class fields

Response ​

For valid template ​

  • Successful status 204 No Content

For invalid template ​

KeyTypeNotes
errorArray[string]List of found issues.

For invalid class fields ​

KeyTypeNotes
warningArray[string]List of found issues.

Responses ​

CauseResponse status codeResponse message
Document can't be parsed200 OK"error": ["Error while parsing document. Please check the syntax."]
Class not related200 OK"error": ["Merge field { name } refers to a Class ID={id} which is not related with Class ID={id}."]
Class field not valid200 OK"warning": ["Merge field { record.field_unknown } refers to a Field field_unknown which is not available in Class ID={id}."]
  • Successful status 200 OK
  • Response body:
json
{
  "error": ["Merge field record refers to a Class ID=999 which is not related with Class ID=1."]
}

Errors ​

CauseResponse status codeResponse message
Invalid object_class_id in URL403 Forbidden"detail": "You do not have permission to perform this action."
Wrong file ID of object class document template or not related file to passed object class400 Bad Request"template_file": ["Invalid file_id {file_id}."]
Wrong file token400 Bad Request"template_file": ["Invalid token {token}."]
Insufficient permissions403 Forbidden"detail": "You do not have permission to perform this action."

GET /api/object-classes/object_class_id/document-templates/document_template_id/download/ ​

Download a given document template.

Permissions ​

Requires authentication and object_classes.view permission for object class related to a given file.

Request ​

  • URL parameters
KeyTypeNotes
object_class_idpk
document_template_idpk
  • Headers
Content-Type: <MIME type>
Content-Disposition: <disposition>; filename="<filename>"
Content-Length: <file size in bytes>
Authorization: JWT access_token

Response ​

  • Successful status 200 OK
  • Response body:

The body will be the raw contents of the file.

Errors ​

ErrorResponse codeMessage
object_class_id is invalid404 Bad Request'detail': "Not found."
document_template_id is invalid404 Bad Request'detail': "Not found."
Unauthorized API call403 Bad Request'detail': "You do not have permission to perform this action."