Custom Components

This technical design describes implementation and API for Custom Components.

Implementation details can be found in external document: Custom Components - Technical Design.

Permissions

To manage Custom Component a new permission resource custom_component will be used.

Following actions will be available for resource:

list
view
create
edit

Actions will be not manageable, and only super admin users will get those permissions.

POST /api/custom-components/repository/

Creates Custom Components Repository.

Permissions

Requires authentication and custom_component.create permission.

Request example

Headers

Request Method: POST
Content-Type: application/json
Authorization: JWT access_token

Body

Key	Type	Required
repository_url	url	True
username	string	True
token	string	True

Validations

User is validated by account type, one_time_completion account cannot be owner.
Custom component repository field name repository_url is required.
Custom component repository field name repository_url max length is 2048.
Custom component repository field name username is required.
Custom component repository field name username max length is 100.
Custom component repository field name token is required.
Custom component repository field name token max length is 150.

Sample request body

POST /api/custom-components/repository/

json

{
   "repository_url": "https://repo.git",
   "username": "alx.dev@autologyx.com",
   "token": "sample token",
}

Response

Successful status 201 Created
Response body:

json

{
   "id": "1",
   "repository_url": "https://git.com/p.git",
   "username": "alx.dev@autologyx.com",
   "created_at": "2023-07-10T09:28:27.679165+02:00",
   "created_by": {
     "id": 256,
     "first_name": "John",
     "last_name": "Smith",
     "username": "j.smith@autologyx.com",
     "company_name": "Autologyx",
     "is_deleted": false
   }
}

GET /api/custom-components/repository/`repository_id`/

Retrieves the Custom Component Repository details.

Permissions

Requires authentication and custom_component.view permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

GET /api/custom-components/repository/repository_id/

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
repository_url	string
username	string
status	enum
errors	Object
version	string
publisher	string
publisher_url	url
logo	url
imported_at	datetime
created_at	datetime
created_by	user
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

Response errors

For statuses different from failed, errors will be null. For status failed the errors can return:

Error	Value
Required file is missing	"{missing_file}": "This file is required."
config.json has > 100000 chars	"config.json": "Ensure this file has no more than 100000 characters."
config.json structure is different than expected	"config.json": "A valid file structure is required."
User has not perm to given resource's instance or Resource's instance with {repository_url} does not exist	"repository_url": "The requested Git resource is either inaccessible or not found."
{attribute} is missing	"{attribute}": ["This field is required."]
{attribute} is blank	"{attribute}": ["This field may not be blank."]
{value} for {attribute} is out of choices	"{attribute}": [""{value}" is not a valid choice."]
Value of different type than an array of objects for `parameters`	"parameters": [{"non_field_errors": ["Expected a list of items but got type "str"."]}]
Nested error for item in `parameters`	"parameters": [{"parameter_{field}": [{error}]}]@
Wrong type for `parameters.parameter_options`	"parameters": [{"parameter_options": ["Expected a list of items but got type "str"."]}]

json

{
    "id": 87, 
    "repository_url": "https://test.com/repo/project0.git",
    "username": "user0",
    "status": "processing",
    "errors": null,
    "version": "1.2",
    "publisher": "Test Publisher",
    "publisher_url": "https:/test.test",
    "logo": "https:/test.test/logo.png",
    "imported_at": "2023-08-02T09:41:44.203051Z",
    "created_at": "2023-08-02T09:41:44.203383Z",
    "created_by": {
        "id":41,
        "first_name": "first name",
        "last_name": "last name",
        "username": "test.autologyx@autologyx.com",
        "company_name": "autologyx",
        "is_deleted": false,
        "account_type": "full"
    },
    "_meta": {
        "permissions": {
            "create": true,
            "edit": true,
            "list": true,
            "view": true
        }
    }
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Repository for `repository_id` not found.	404 Not Found

OPTIONS /api/custom-components/repository/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/custom-components/repository/

Response

Successful status 200 OK
Response body:

json

{
   "details": {
      "schema": [
         {
            "alias": "repository_url",
            "type": "url",
            "required": true,
            "validators": [
               {
                  "type": "max_length",
                  "length": 2048
               }
            ]
         },
         {
            "alias": "username",
            "type": "string",
            "required": true,
            "validators": [
               {  
                  "type": "max_length",
                  "length": 100
               } 
            ] 
         },
         {
            "alias": "token",
            "type": "string",
            "required": true,
            "validators": [
               {
                  "type": "max_length",
                  "length": 150 
               }
            ]
         }
      ]
   }
}

PATCH /api/custom-components/repository/`repository_id`/

Response example

Status 405 Method Not Allowed

POST /api/custom-components/

Creates Custom Components and if repository status imported the task with the installing repository is running in the background.

If repository status is imported the component status is processing
If repository status is processing the component status is processing
created_by and modified_by is the user who executed the POST.
created_at and modified_at is the timestamp when the component was created.

Permissions

Requires authentication and custom_component.create permission.

Request example

Headers

Request Method: POST
Content-Type: application/json
Authorization: JWT access_token

Body

Key	Type	Required
name	string	True
description	string	False
repository	int	True
is_enabled	bool	False
available_use	Object	True

Response available_use Object

Key	Type	Notes
landing_page	bool
object_class_create_form	bool
object_class_summary_form	bool
object_class_standalone_form	bool
task_template_form	bool

Validations

At most custom components can be created: 100.
Repository status if is failed during importing.
User is validated by account type, one_time_completion account cannot be owner.
Custom component field name name is unique.
Custom component field name name is required.
Custom component field name name max length is 100.
Custom component field name description max length is 500.
Custom component field name repository is required.
Custom component field name repository must be repository ID.
Custom component field name repository cannot be associated with any other custom component.
Custom component field name available_use is required.
Custom component field name available_use field name landing_page is required.
Custom component field name available_use field name object_class_create_form is required.
Custom component field name available_use field name object_class_summary_form is required.
Custom component field name available_use field name object_class_standalone_form is required.
Custom component field name available_use field name task_template_form is required.
Custom component field name available_use must be an object with keys listed above.

Sample request body

POST /api/custom-components/

json

{
   "name": "Component 1"",
   "description": "Test description",
   "repository": 1,
   "is_enabled": true,
   "available_use": {
      "landing_page": true,
      "object_class_create_form": false,
      "object_class_summary_form": false,
      "object_class_standalone_form": false,
      "task_template_form": false
   }
}

Response

Successful status 201 Created
Response body:

json

{
   "name": "Component 1",
   "description": "Test description",
   "repository": 1,
   "is_enabled": true,
   "status": "processing",
   "created_at": "2023-07-10T09:28:27.679165+02:00",
   "created_by": "some name (test.autologyx@autologyx.com)",
   "modified_at": "2023-07-10T09:28:27.679165+02:00",
   "modified_by": "some name (test.autologyx@autologyx.com)",
   "available_use": {
      "landing_page": true,
      "object_class_create_form": false,
      "object_class_summary_form": false,
      "object_class_standalone_form": false,
      "task_template_form": false
   }
}

GET /api/custom-components/

Returns list of Custom Components.

Permissions

Requires authentication and custom_component.view permission.

Request example

Headers

Request Method: GET
Content-Type: application/json
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
id	int	Automatically generated by the backend.
name	str
repository	int
repository_url	string
is_enabled	bool
status	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
available_use	Object
index_url	string
version	string
publisher	str
publisher_url	url
_meta.permissions	Object	Object describing permissions.

Response `available_use` Object

Key	Type	Notes
landing_page	bool
object_class_create_form	bool
object_class_summary_form	bool
object_class_standalone_form	bool
task_template_form	bool

json

{
  "limit": 10,
  "filtered_count": 9,
  "total_count": 9,
  "next": null,
  "previous": null,
  "offset": 0,
  "results": [
    {
      "id":5,
      "name":"16 08 2023 component",
      "repository":13,
      "repository_url":"https://github.com/repository",
      "is_enabled":true,
      "status":"installed",
      "created_at":"2023-08-16T10:38:12.476104+02:00",
      "created_by": {
        "id":28,
        "first_name":"John",
        "last_name":".",
        "username":"john@autologyx.com",
        "company_name":"",
        "is_deleted":false,
        "account_type":"super_admin"
      },
      "modified_at":"2023-08-16T10:38:15.858505+02:00",
      "modified_by": {
        "id":28,
        "first_name":"John",
        "last_name":".",
        "username":"john@autologyx.com",
        "company_name":"",
        "is_deleted":false,
        "account_type":"super_admin"
      },
      "available_use": {
        "landing_page":true,
        "object_class_create_form":true,
        "object_class_summary_form":true,
        "object_class_standalone_form":true,
        "task_template_form":true
      },
      "index_url":"https://autologyx.com/alx_release_candidate_next_version_qa/85f1b0cd-b112-499b-9f0d-32131232313/index.html",
      "version":"1.1.0",
      "publisher":"acme",
      "publisher_url":"https://example.com",
      "_meta": {
        "permissions": {
          "list":true,
          "view":true,
          "create":true,
          "edit":true
        }
      }
    }]
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

GET /api/custom-components/`custom_component_id`/

Retrieves the Custom Component details.

Permissions

Requires authentication and custom_component.view permission.

URL parameters

Key	Type	Notes
custom_component_id	int

Request example

Headers

Request Method: GET
Content-Type: application/json
Authorization: JWT access_token

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	str
description	str
repository	int
is_enabled	bool
status	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
available_use	Object
index_url	string
version	string
parameters	Object
publisher	str
publisher_url	url
_meta.permissions	Object	Object describing permissions.

Response `parameters` Object

Key	Type	Notes
parameter_description	str
parameter_name	str
parameter_type	str
parametr_limit	int
parameter_options	list

Response example

Status 200 OK
Body

json

{
  "id":5,
  "name":"16 08 2023 component",
  "description": "description",
  "repository":13,
  "is_enabled":true,
  "status":"installed",
  "created_at":"2023-08-16T10:38:12.476104+02:00",
  "created_by": {
    "id":28,
    "first_name":"John",
    "last_name":".",
    "username":"john@autologyx.com",
    "company_name":"",
    "is_deleted":false,
    "account_type":"super_admin"
  },
  "modified_at":"2023-08-16T10:38:15.858505+02:00",
  "modified_by": {
    "id":28,
    "first_name":"John",
    "last_name":".",
    "username":"john@autologyx.com",
    "company_name":"",
    "is_deleted":false,
    "account_type":"super_admin"
  },
  "available_use": {
    "landing_page":true,
    "object_class_create_form":true,
    "object_class_summary_form":true,
    "object_class_standalone_form":true,
    "task_template_form":true
  },
  "index_url":"https://autologyx.com/alx_release_candidate_next_version_qa/85f1b0cd-b112-499b-9f0d-32131232313/index.html",
  "version":"1.1.0",
  "parameters": [
    {
      "parameter_description": "description",
      "parameter_name": "name",
      "parameter_type": "type",
      "parameter_limit": 5,
      "parameter_options": []
    }
  ],
  "publisher":"acme",
  "publisher_url":"https://example.com",
  "_meta": {
    "permissions": {
      "list":true,
      "view":true,
      "create":true,
      "edit":true
    }
  }
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Custom Component with "id " does not exists	404 Not Found	"detail": "Not found."

OPTIONS /api/custom-components/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/custom-components/

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": "status",
            "type": "enum",
            "predicates": [ 
               "exact",
               "in" 
             ],
            "sort_ok": false,
            "values": [
               {
                  "value": "processing",
                  "text": "Processing" 
               },
              {
                  "value": "failed",
                  "text": "Failed" 
               }, 
               {  
                  "value": "Installed",
                  "text": "Installed" 
              }
            ]
         },
         {
            "alias": "version",
            "type": "string",
            "predicates": [ ],
            "sort_ok": false
         },
         {
            "alias": "publisher",
            "type": "string",
            "predicates": [
               "exact",
               "iexact",
               "contains",
               "icontains",
               "startswith",
               "istartswith",
               "endswith",
               "iendswith" 
            ],
            "sort_ok": true
         },
         {
            "alias": "repository_url",
            "type": "url",
            "predicates": [ ],
            "sort_ok": false
         },
         {
            "alias": "is_enabled",
            "type": "bool",
            "predicates": [
               "exact" 
            ],
            "sort_ok": false
         },
         {
            "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": "is_enabled",
            "type": "bool",
            "required": false
         },
         {
            "alias": "available_use",
            "required": false,
            "schema": [
               { 
                  "alias": "landing_page",
                  "type": "bool",
                  "required": true
               },
               {
                  "alias": "object_class_create_form",
                  "type": "bool",
                  "required": true
               },
               { 
                  "alias": "object_class_summary_form",
                  "type": "bool",
                  "required": true
               },
               {
                  "alias": "object_class_standalone_form",
                  "type": "bool",
                  "required": true
               },
               {  
                  "alias": "task_template_form",
                  "type": "bool",
                  "required": true
               }
           ]
         }
      ]
   },
   "restrictions": {
      "limit_items": 100
   }
}

PATCH /api/custom-components/`custom_component_id`/

Update the form.

Permissions

Requires authentication and custom_component.edit permissions.

Allowed parameters

Key	Type	Notes
name	string
description	strin
is_enabled	bool
available_use	json

available_use json

Key	Type	Notes
landing_page	bool
object_class_create_form	bool
object_class_summary_form	bool
object_class_standalone_form	bool
task_template_form	bool

Any parameter not listed above are silently ignored if passed.

Request example

Headers

Request Method: PATCH
Location: /api/custom-components/1/
Authorization: JWT access_token

Body

json


{
    "name": "name",
    "description": "description",
    "is_enabled": true,
    "available_use": {
        "landing_page": false, 
        "object_class_create_form": true, 
        "object_class_summary_form": true, 
        "object_class_standalone_form": true, 
        "task_template_form": true
    }
}

Response

Key	Type	Notes
id	uuid
name	string
description	int
repository	enum
is_enabled	bool
status	str
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
available_use	json

Response example

Status 200 OK
Body

json

{
    "id": 1,
    "name": "name",
    "description": "description",
    "repository": 1,
    "is_enabled": true,
    "status": "installed",
    "created_at": "2023-08-09T07:24:42.621472Z",
    "created_by": {
        "id": 1,
        "first_name": "ALX",
        "last_name": "Master",
        "username": "username@test.pl",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_at": "2023-08-10T11:20:13.312085Z",
    "modified_by": {
        "id": 1,
        "first_name": "ALX",
        "last_name": "Master",
        "username": "username@test.pl",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "available_use": {
        "landing_page": false,
        "object_class_create_form": true,
        "object_class_summary_form": true,
        "object_class_standalone_form": true,
        "task_template_form": true
    }
}

DELETE /api/custom-components/`custom_component_id`/

Deletes single Custom Component.

Permissions

Requires authentication and custom_component.delete permission.

Request

URL parameters

Key	Type	Notes
custom_component_id	int

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

DELETE /api/custom-components/custom_component_id/

json

Response

Successful status 204 No Content

Errors

Error	Response code	Message
Custom Component in use	400 Forbidden	"detail": "Custom component is in use by {used_by}."
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Custom Component with "id" does not exist	404 Not Found	"detail": "Not found."

GET /api/custom-components/`custom_component_id`/usage/

Request example

Headers

Request Method: GET
Location: /api/custom-components/1/usage/
Authorization: JWT access_token

Response

Key	Type	Notes
object_class_summary_forms	array
object_class_create_forms	array
object_class_standalone_forms	array
num_of_object_class_summary_forms	int
num_of_object_class_create_forms	int
num_of_landing_pages	int
num_of_object_class_standalone_forms	int

Response `object_class_summary_forms` array

Key	Type	Notes
id	int	Object class id
name	str	Name of the Object class

Response `object_class_create_forms` array

Key	Type	Notes
id	int	Object class id
name	str	Name of the Object class

Response `object_class_standalone_forms` array

Key	Type	Notes
id	int	Object class id
name	str	Name of the Object class
standalone_form_name	str	Name of the Object class standalone form

Response example

Status 200 OK
Body

json

{
  "object_class_summary_forms": [
    {
      "id": 1,
      "name": "Object class 1"
    }
  ],
  "object_class_create_forms": [
    {
      "id": 2,
      "name": "Object class 2"
    }
  ],
  "object_class_standalone_forms": [
    {
      "id": 3,
      "name": "Object class 3",
      "standalone_form_name": "Standalone Form" 
    }
  ],
  "num_of_object_class_summary_forms": 1,
  "num_of_object_class_create_forms": 1,
  "num_of_landing_pages": 1
  "num_of_object_class_standalone_forms": 1
}

Errors

Error	Response code	Message
`id` is invalid	404 Bad Request	'detail': "Not found."
Unauthorized API call	403 Bad Request	'detail': "You do not have permission to perform this action."

Custom Components ​

Permissions ​

POST /api/custom-components/repository/ ​

Permissions ​

Request example ​

Body ​

Validations ​

Sample request body ​

Response ​

GET /api/custom-components/repository/repository_id/ ​

Permissions ​

Request ​

Response ​

Errors ​

OPTIONS /api/custom-components/repository/ ​

Permissions ​

Request ​

Response ​

PATCH /api/custom-components/repository/repository_id/ ​

Response example ​

POST /api/custom-components/ ​

Permissions ​

Request example ​

Body ​

Validations ​

Sample request body ​

Response ​

GET /api/custom-components/ ​

Permissions ​

Request example ​

Response ​

Response results array ​

Response available_use Object ​

Errors ​

GET /api/custom-components/custom_component_id/ ​

Permissions ​

URL parameters ​

Request example ​

Response ​

Response parameters Object ​

Response example ​

Errors ​

OPTIONS /api/custom-components/ ​

Permissions ​

Request ​

Response ​

PATCH /api/custom-components/custom_component_id/ ​

Permissions ​

Allowed parameters ​

Request example ​

Response ​

Response example ​

DELETE /api/custom-components/custom_component_id/ ​

Permissions ​

Request ​

Response ​

Errors ​

GET /api/custom-components/custom_component_id/usage/ ​

Request example ​

Response ​

Response object_class_summary_forms array ​

Response object_class_create_forms array ​

Response object_class_standalone_forms array ​

Response example ​

Errors ​

Custom Components

Permissions

POST /api/custom-components/repository/

Permissions

Request example

Body

Validations

Sample request body

Response

GET /api/custom-components/repository/`repository_id`/

Permissions

Request

Response

Errors

OPTIONS /api/custom-components/repository/

Permissions

Request

Response

PATCH /api/custom-components/repository/`repository_id`/

Response example

POST /api/custom-components/

Permissions

Request example

Body

Validations

Sample request body

Response

GET /api/custom-components/

Permissions

Request example

Response

Response `results` array

Response `available_use` Object

Errors

GET /api/custom-components/`custom_component_id`/

Permissions

URL parameters

Request example

Response

Response `parameters` Object

Response example

Errors

OPTIONS /api/custom-components/

Permissions

Request

Response

PATCH /api/custom-components/`custom_component_id`/

Permissions

Allowed parameters

Request example

Response

Response example

DELETE /api/custom-components/`custom_component_id`/

Permissions

Request

Response

Errors

GET /api/custom-components/`custom_component_id`/usage/

Request example

Response

Response `object_class_summary_forms` array

Response `object_class_create_forms` array

Response `object_class_standalone_forms` array

Response example

Errors