Object Records

This technical design describes implementation and API for Object Records.

Object Records API

POST /api/object-records/

Creates a new Object Record.

Creator (user) of Object Record becomes an owner.

Permissions

Requires authentication and Object Class Ownership or has Object Record create permissions by any permission_set.

Request

• Headers

Request Method: POST
Authorization: JWT access_token

• Body

Key	Type	Required	Notes
object_name	string	false
object_class	pk	true	Relations between object classes
field_<field_alias>	any	false	Fields based on Object Class configuration

Validations

• object_name

  • Ensure this field has no more than 255 characters.

• object_class

  • This field is required.
  • Invalid pk "value" - object does not exist.
  • This field may not be null.
  • The object class "value" might be given only once.

• field_<field_alias>:

  • This field is required.
  • Check if field is valid
  • Depending on field type a various validation errors are raised for invalid value.
    • String:
      • Ensure this field has no more than {max} characters.
    • Integer:
      • A valid integer is required.
      • Ensure this value is greater than or equal to {min_value}.
      • Ensure this value is less than or equal to {max_value}.
    • Decimal:
      • A valid number is required.
      • Ensure this value is greater than or equal to {min_value}.
      • Ensure this value is less than or equal to {max_value}.
    • Bool:
      • Must be a valid boolean.
      • Field contains a value other than required.
    • Enum:
      • /value/ is not a valid choice.
    • Email:
      • Enter a valid email address.
      • Ensure this field has no more than /max/ characters.
    • Phone:
      • Ensure this field has no more than 100 characters.
    • Date:
      • Date has wrong format. Use one of these formats instead: YYYY-MM-DD.
    • Time:
      • Time has wrong format. Use one of these formats instead: hh:mm[:ss[.uuuuuu]].
    • Datetime:
      • Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z].
    • Enum
      • "{value}" is not a valid choice.
    • Url
      • Enter a valid URL.
      • Ensure this field has no more than {max} characters."
    • JSON
      • Value must be valid JSON.
      • Ensure this field has no more than {max} characters.
    • Set
      • Value must be valid Set.
      • The number of elements must be less than or equal to {max_items}.
      • The number of elements must be greater than or equal to {min_items}.
    • Document
      • Value must be valid tokens list.
      • The number of elements must be less than or equal to {max_items}.
    • User
      • Value must be a valid object with key users or user_groups.
      • An users must be a valid set of users IDs.
      • An user_groups must be a valid set of groups IDs
      • User IDs must be an ID of existing not deleted users, limited to list defined in Object Class Field options.
      • Groups IDs ust be an ID of existing users group, limited to list defined in Object Class Field options.
      • The number of users elements must be less than or equal to {max_users_items}.
      • The number of users elements must be greater than or equal to {min_users_items}.
      • The number of user_groups elements must be less than or equal to {max_groups_items}.
      • The number of user_groups elements must be less than or equal to 10.
      • The number of user_groups elements must be greater than or equal to {min_groups_items}.

Sample request body

POST /api/object-records/

{
  "object_name": "Object Record",
  "object_class": 1,
  "field_first_name": "John",  
  "field_last_name": "Doe", 
  "field_email": "john-doe@nwc.xxx", 
  "field_age": 33, 
  "field_dob": "2022-11-17", 
  ... 
  "field_<field_alias>": <field_specific_type>
}

Sample users field body

POST /api/object-records/

{
  ...
  "field_<field_alias>": {"users": [323, 4345], "user_groups": [2, 23]}
}

Response

Key	Type	Notes
id	int
object_name	string
object_class	int
status	enum	The only option is: "initiated"
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta	Object	_meta result
field_<field_alias>	any	Fields based on Object Class configuration

For fields with type:

• email
• phone
• url
• json

When user creates a record using with request body shown below.

{
    "field_<type>_field": "" 
}

The field value is set to null.

Expected response with this field is:

{
    "field_<type>_field": null
}

Response _meta object

Key	Type	Notes
permissions	Object
labels	Object
users	Object
user_groups	Object

Response _meta.users object

Key	Type	Notes
<user_id>	user

_meta.users contains max 50 user objects for first 50 unique items from user type fields.

Response _meta.user_groups object

Key	Type	Notes
<users_group_id>	Object	Contains group id and name

_meta.user_groups contains max 50 user group objects for first 50 unique items from user type fields.

• Successful status 201 Created
• Response body schema

{
  "id": 20,
  "object_name": "Object Record",
  "object_class": 1,
  "status": "initiated",
  "created_at": "2022-08-18T12:21:35.921861+02:00",
  "created_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "modified_at": "2022-08-18T13:43:42.874876+02:00",
  "modified_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "field_first_name": "John",
  "field_last_name": "Doe",
  "field_email": "john-doe@nwc.xxx",
  "field_age": 33,
  "field_dob": "2022-11-17", 
  "field_documents": null,
  "field_user": {"users": [23], "user_groups": [2]},
  "_meta": {
    "labels": {
      "object_class": "MareK Test #1",
      "files": null
    },
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true,
      "edit_owners": true,
      "view_owners": true,
      "tasks": {
        "list": true,
        "view": true,
        "edit": true,
        "delete": true,
        "create": true,
        "complete": true,
        "assign": true
      }
    },
    "users": {
        "23": {
            "id": 23,
            "first_name": "John",
            "last_name": "Smith",
            "username": "j.smith@autologyx.com",
            "company_name": "Autologyx",
            "is_deleted": false,
            "account_type": "super_admin"
        }
    },
     "user_groups": {
        "2": {
            "id": 2,
            "name": "Group2"
        }
    },
    "allowed_status_transitions": [],
    "forbidden_actions": []
  }
}

Restriction

• Max 500 000 Object Records in one Object Class

Errors

Cause	Response code	Message
object_class is required	400 Bad Request	"object_class": [ "This field is required."]
object_class is empty	400 Bad Request	"object_class": [ "This field may not be blank."]
object_class is null	400 Bad Request	"object_class": [ "This field may not be null."]
object_class is invalid	400 Bad Request	"object_class": [ "'Invalid pk "{object_class_id}" - object does not exist.'"]
object_name to long	400 Bad Request	"object_name": ["Ensure this field has no more than 255 characters."]
Exceeded max number of Object Record fields	400 Bad Request	"detail": "Limit of 500 000 Object Records in this Object Class has been exceeded."
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

Field type Errors

Cause	Response code	Message
string is too long	400 Bad Request	"field_{string}": ["Ensure this field has no more than {max} characters."]
string is required	400 Bad Request	"field_{string}": ["This field is required."]
string is not unique	400 Bad Request	"field_{string}": ["This field must be unique."]
integer value is invalid	400 Bad Request	"field_{integer}": ["A valid integer is required."]
integer is required	400 Bad Request	"field_{integer}": ["This field is required."]
integer value is below the limit	400 Bad Request	"field_{integer}": ["Ensure this value is greater than or equal to {min}."]
integer value is above the limit	400 Bad Request	"field_{integer}": ["Ensure this value is less than or equal to {max}."]
integer is not unique	400 Bad Request	"field_{integer}": ["This field must be unique."]
float value is invalid	400 Bad Request	"field_{float}": ["A valid number is required."]
float is required	400 Bad Request	"field_{float}": ["This field is required."]
float value is below the limit	400 Bad Request	"field_{float}": ["Ensure this value is greater than or equal to {min}."]
float value is above the limit	400 Bad Request	"field_{float}": ["Ensure this value is less than or equal to {max}."]
float is not unique	400 Bad Request	"field_{float}": ["This field must be unique."]
bool value is invalid	400 Bad Request	"field_{bool}": ["Must be a valid boolean."]
bool value different than required	400 Bad Request	"field_{bool}": ["Field contains a value other than required."]
email value is invalid	400 Bad Request	"field_{email}": ["Enter a valid email address."]
email is required	400 Bad Request	"field_{email}": ["This field is required."]
email value is above the limit	400 Bad Request	"field_{email}": ["Ensure this field has no more than {max} characters."]
email is not unique	400 Bad Request	"field_{email}": ["This field must be unique."]
phone value is invalid	400 Bad Request	"field_{phone}": ["Enter a valid email address."]
phone is required	400 Bad Request	"field_{phone}": ["This field is required."]
phone value is above the limit	400 Bad Request	"field_{phone}": ["Ensure this field has no more than {max} characters."]
phone is not unique	400 Bad Request	"field_{phone}": ["This field must be unique."]
date value is in wrong format	400 Bad Request	"field_{date}": ["Date has wrong format. Use one of these formats instead: YYYY-MM-DD."]
date is required	400 Bad Request	"field_{date}": ["This field is required."]
date is not unique	400 Bad Request	"field_{date}": ["This field must be unique."]
time value is in wrong format	400 Bad Request	"field_{time}": ["Time has wrong format. Use one of these formats instead: hh:mm[:ss[.uuuuuu]]."]
time is required	400 Bad Request	"field_{time}": ["This field is required."]
time is not unique	400 Bad Request	"field_{time}": ["This field must be unique."]
datetime value is in wrong format	400 Bad Request	"field_{datetime}": ["Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM
datetime is required	400 Bad Request	"field_{datetime}": ["This field is required."]
datetime is not unique	400 Bad Request	"field_{datetime}": ["This field must be unique."]
enum value is invalid	400 Bad Request	"field_{enum}": ["{value} is not a valid choice.]
enum is required	400 Bad Request	"field_{enum}": ["This field is required."]
enum is not unique	400 Bad Request	"field_{enum}": ["This field must be unique."]
set value is invalid	400 Bad Request	"field_{set}": ["Value must be valid Set."]
set is not a list	400 Bad Request	"field_{set}": ["Value must be valid Set."]
set value is below the limit	400 Bad Request	"field_{set}": ["The number of elements must be greater than or equal to {min}."]
set value is above the limit	400 Bad Request	"field_{set}": ["The number of elements must be less than or equal to {max}."]
url value is invalid	400 Bad Request	"field_{url}": ["Enter a valid URL."]
url is required	400 Bad Request	"field_{url}": ["This field is required."]
url value is above the limit	400 Bad Request	"field_{url}": ["Ensure this field has no more than {max} characters."]
url is not unique	400 Bad Request	"field_{url}": ["This field must be unique."]
json value is invalid	400 Bad Request	"field_{json}": ["Value must be valid JSON."]
json is required	400 Bad Request	"field_{json}": ["This field is required."]
json value is above the limit	400 Bad Request	"field_{json}": ["Ensure this field has no more than {max} characters."]
json is not unique	400 Bad Request	"field_{json}": ["This field must be unique."]
document value is invalid	400 Bad Request	"field_{document}": ["Value must be valid list."]
document token is invalid	400 Bad Request	"field_{document}": ["Invalid token {token}."]
document number files is above the limit	400 Bad Request	"field_{document}": ["The number of elements must be less than or equal to {max}."]
user is not a object	400 Bad Request	"field_{user}": ["Expected a dictionary of items but got type "{type}"."]
user value not in the class field definition or not existing user ID (users)	400 Bad Request	"field_{user}": [""{value}" is not a valid choice."]
user value is below the limit (users)	400 Bad Request	"field_{user}": ["The number of users elements must be greater than or equal to {min}."]
user value is above the limit (users)	400 Bad Request	"field_{user}": ["The number of users elements must be less than or equal to {max}."]
user value is not an array of integers (users)	400 Bad Request	"field_{user}": {"users": ["The value must be an array of integers."]}
user value not in the class field definition or not existing users group ID (user_groups)	400 Bad Request	"field_{user}": [""{value}" is not a valid choice."]
user value is below the limit (user_groups)	400 Bad Request	"field_{user}": ["The number of user_groups elements must be greater than or equal to {min}."]
user value is above the limit (user_groups)	400 Bad Request	"field_{user}": ["The number of user_groups elements must be less than or equal to {max}."]
user value is not an array of integers (user_groups)	400 Bad Request	"field_{user}": {"user_groups": ["The value must be an array of integers."]}
user field - attempted to pass values in the user_groups field when it was not permitted	400 Bad Request	"field_{user}": ["user_groups field is not allowed."]
user field - attempted to pass values in the users field when it was not permitted	400 Bad Request	"field_{user}": ["users field is not allowed."]

PATCH /api/object-records/record_id/

Update Object Record.

Default value is omitted for PATCH

Permissions

Requires authentication and Object Class Ownership or Object Record Ownership or has Object Record edit permissions by any permission_set.

Request

• Headers

Request Method: POST
Authorization: JWT access_token

• Body

Key	Type	Required	Notes
object_name	string	false
object_class	pk	true	Relations between object classes
field_<field_alias>	any	false	Fields based on Object Class configuration

Validations

• object_name

  • Ensure this field has no more than 255 characters.

• object_class

  • This field is required.
  • Invalid pk "value" - object does not exist.
  • This field may not be null.
  • The object class "value" might be given only once.

• field_<field_alias>:

  • This field is required.
  • Check if field is valid
  • Depending on field type a various validation errors are raised for invalid value.
    • String:
      • Ensure this field has no more than {max} characters.
    • Integer:
      • A valid integer is required.
      • Ensure this value is greater than or equal to {min_value}.
      • Ensure this value is less than or equal to {max_value}.
    • Decimal:
      • A valid number is required.
      • Ensure this value is greater than or equal to {min_value}.
      • Ensure this value is less than or equal to {max_value}.
    • Bool:
      • Must be a valid boolean.
      • Field contains a value other than required.
    • Enum:
      • /value/ is not a valid choice.
    • Email:
      • Enter a valid email address.
      • Ensure this field has no more than /max/ characters.
    • Phone:
      • Ensure this field has no more than 100 characters.
    • Date:
      • Date has wrong format. Use one of these formats instead: YYYY-MM-DD.
    • Time:
      • Time has wrong format. Use one of these formats instead: hh:mm[:ss[.uuuuuu]].
    • Datetime:
      • Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z].
    • Enum
      • "{value}" is not a valid choice.
    • Url
      • Enter a valid URL.
      • Ensure this field has no more than {max} characters."
    • JSON
      • Value must be valid JSON.
      • Ensure this field has no more than {max} characters.
    • Set
      • Value must be valid Set.
      • The number of elements must be less than or equal to {max_items}.
      • The number of elements must be greater than or equal to {min_items}.
    • Document
      • Value must be valid tokens list.
      • The number of elements must be less than or equal to {max_items}.
    • User
      • Value must be a valid object with key users or user_groups.
      • An users must be a valid set of users IDs.
      • An user_groups must be a valid set of groups IDs
      • User IDs must be an ID of existing not deleted users, limited to list defined in Object Class Field options.
      • Groups IDs ust be an ID of existing users group, limited to list defined in Object Class Field options.
      • The number of users elements must be less than or equal to {max_users_items}.
      • The number of users elements must be greater than or equal to {min_users_items}.
      • The number of user_groups elements must be less than or equal to {max_groups_items}.
      • The number of user_groups elements must be less than or equal to 10.
      • The number of user_groups elements must be greater than or equal to {min_groups_items}.

Sample request body

PATCH /api/object-records/1/

{
  "object_name": "Object Record",
  "object_class": 1,
  "field_first_name": "John",  
  "field_last_name": "Doe", 
  "field_email": "john-doe@nwc.xxx", 
  "field_age": 33, 
  "field_dob": "2022-11-17", 
  ... 
  "field_<field_alias>": <field_specific_type>, 
}

Response

Key	Type	Notes
id	int
object_name	string
object_class	int
status	enum	The only option is: "initiated"
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta	Object	_meta result
field_<field_alias>	any	Fields based on Object Class configuration

For fields with type:

• email
• phone
• url
• json

When user updates a record using with request body shown below.

{
    "field_<type>_field": "" 
}

And for fields type:

• user

When user updates a record using with request body with empty dict or empty value for keys.

{
    "field_<type>_field": {},
    "field_<type>_field": {"user":  []},
    "field_<type>_field": {"user":  [], "users_groups":  null}
}

The field value is set to null.

Expected response with this field is:

{
    "field_<type>_field": null
}

Response _meta object

Key	Type	Notes
permissions	Object
labels	Object
users	Object
user_groups	Object

Response _meta.users object

Key	Type	Notes
<user_id>	user

_meta.users contains max 50 user objects for first 50 unique items from user type fields.

Response _meta.user_groups object

Key	Type	Notes
<users_group_id>	Object	Contains group id and name

_meta.user_groups contains max 50 user group objects for first 50 unique items from user type fields.

• Successful status 200 Ok
• Response body schema

{
  "id": 20,
  "object_name": "Object Record",
  "object_class": 1,
  "status": "initiated",
  "created_at": "2022-08-18T12:21:35.921861+02:00",
  "created_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "modified_at": "2022-08-18T13:43:42.874876+02:00",
  "modified_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "field_first_name": "John",
  "field_last_name": "Doe",
  "field_email": "john-doe@nwc.xxx",
  "field_age": 33,
  "field_dob": "2022-11-17", 
  "field_documents": null,
  "field_user": {"users": [23], "user_groups": [2]},
  "_meta": {
    "labels": {
      "object_class": "MareK Test #1",
      "files": null
    },
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true,
      "edit_owners": true,
      "view_owners": true,
      "tasks": {
        "list": true,
        "view": true,
        "edit": true,
        "delete": true,
        "create": true,
        "complete": true,
        "assign": true
      }
    },
    "users": {
        "23": {
            "id": 23,
            "first_name": "John",
            "last_name": "Smith",
            "username": "j.smith@autologyx.com",
            "company_name": "Autologyx",
            "is_deleted": false,
            "account_type": "super_admin"
        }
    },
     "user_groups": {
        "2": {
            "id": 2,
            "name": "Group2"
        }
    },
    "allowed_status_transitions": [],
    "forbidden_actions": []
  }
}

Restriction

• Max 500 000 Object Records in one Object Class

Errors

Cause	Response code	Message
object_class is required	400 Bad Request	"object_class": [ "This field is required."]
object_class is empty	400 Bad Request	"object_class": [ "This field may not be blank."]
object_class is null	400 Bad Request	"object_class": [ "This field may not be null."]
object_class is invalid	400 Bad Request	"object_class": [ "'Invalid pk "{object_class_id}" - object does not exist.'"]
object_name to long	400 Bad Request	"object_name": ["Ensure this field has no more than 255 characters."]
Exceeded max number of Object Record fields	400 Bad Request	"detail": "Limit of 500 000 Object Records in this Object Class has been exceeded."
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

Field type Errors

Cause	Response code	Message
string is too long	400 Bad Request	"field_{string}": [ "Ensure this field has no more than {max} characters."]
string is required	400 Bad Request	"field_{string}": [ "This field is required."]
string is not unique	400 Bad Request	"field_{string}": [ "This field must be unique."]
integer value is invalid	400 Bad Request	"field_{integer}": [ "A valid integer is required."]
integer is required	400 Bad Request	"field_{integer}": [ "This field is required."]
integer value is below the limit	400 Bad Request	"field_{integer}": [ "Ensure this value is greater than or equal to {min}."]
integer value is above the limit	400 Bad Request	"field_{integer}": [ "Ensure this value is less than or equal to {max}."]
integer is not unique	400 Bad Request	"field_{integer}": [ "This field must be unique."]
float value is invalid	400 Bad Request	"field_{float}": [ "A valid number is required."]
float is required	400 Bad Request	"field_{float}": [ "This field is required."]
float value is below the limit	400 Bad Request	"field_{float}": [ "Ensure this value is greater than or equal to {min}."]
float value is above the limit	400 Bad Request	"field_{float}": [ "Ensure this value is less than or equal to {max}."]
float is not unique	400 Bad Request	"field_{float}": [ "This field must be unique."]
bool value is invalid	400 Bad Request	"field_{bool}": [ "Must be a valid boolean."]
bool value different than required	400 Bad Request	"field_{bool}": [ "Field contains a value other than required."]
email value is invalid	400 Bad Request	"field_{email}": [ "Enter a valid email address."]
email is required	400 Bad Request	"field_{email}": [ "This field is required."]
email value is above the limit	400 Bad Request	"field_{email}": [ "Ensure this field has no more than {max} characters."]
email is not unique	400 Bad Request	"field_{email}": [ "This field must be unique."]
phone value is invalid	400 Bad Request	"field_{phone}": [ "Enter a valid email address."]
phone is required	400 Bad Request	"field_{phone}": [ "This field is required."]
phone value is above the limit	400 Bad Request	"field_{phone}": [ "Ensure this field has no more than {max} characters."]
phone is not unique	400 Bad Request	"field_{phone}": [ "This field must be unique."]
date value is in wrong format	400 Bad Request	"field_{date}": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD."]
date is required	400 Bad Request	"field_{date}": [ "This field is required."]
date is not unique	400 Bad Request	"field_{date}": [ "This field must be unique."]
time value is in wrong format	400 Bad Request	"field_{time}": [ "Time has wrong format. Use one of these formats instead: hh:mm[:ss[.uuuuuu]]."]
time is required	400 Bad Request	"field_{time}": [ "This field is required."]
time is not unique	400 Bad Request	"field_{time}": [ "This field must be unique."]
datetime value is in wrong format	400 Bad Request	"field_{datetime}": [ "Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM
datetime is required	400 Bad Request	"field_{datetime}": [ "This field is required."]
datetime is not unique	400 Bad Request	"field_{datetime}": [ "This field must be unique."]
enum value is invalid	400 Bad Request	"field_{enum}": [ "{value} is not a valid choice.]
enum is required	400 Bad Request	"field_{enum}": [ "This field is required."]
enum is not unique	400 Bad Request	"field_{enum}": [ "This field must be unique."]
set value is invalid	400 Bad Request	"field_{set}": [ "Value must be valid Set."]
set is not a list	400 Bad Request	"field_{set}": [ "Value must be valid Set."]
set value is below the limit	400 Bad Request	"field_{set}": [ "The number of elements must be greater than or equal to {min}."]
set value is above the limit	400 Bad Request	"field_{set}": [ "The number of elements must be less than or equal to {max}."]
url value is invalid	400 Bad Request	"field_{url}": [ "Enter a valid URL."]
url is required	400 Bad Request	"field_{url}": [ "This field is required."]
url value is above the limit	400 Bad Request	"field_{url}": [ "Ensure this field has no more than {max} characters."]
url is not unique	400 Bad Request	"field_{url}": [ "This field must be unique."]
json value is invalid	400 Bad Request	"field_{json}": [ "Value must be valid JSON."]
json is required	400 Bad Request	"field_{json}": [ "This field is required."]
json value is above the limit	400 Bad Request	"field_{json}": [ "Ensure this field has no more than {max} characters."]
json is not unique	400 Bad Request	"field_{json}": [ "This field must be unique."]
document value is invalid	400 Bad Request	"field_{document}": [ "Value must be valid list."]
document token is invalid	400 Bad Request	"field_{document}": [ "Invalid token {token}."]
document number files is above the limit	400 Bad Request	"field_{document}": [ "The number of elements must be less than or equal to {max}."]
user is not a object	400 Bad Request	"field_{user}": ["Expected a dictionary of items but got type "{type}"."]
user value not in the class field definition or not existing user ID (users)	400 Bad Request	"field_{user}": [""{value}" is not a valid choice."]
user value is below the limit (users)	400 Bad Request	"field_{user}": ["The number of users elements must be greater than or equal to {min}."]
user value is above the limit (users)	400 Bad Request	"field_{user}": ["The number of users elements must be less than or equal to {max}."]
user value is not an array of integers (users)	400 Bad Request	"field_{user}": {"users": ["The value must be an array of integers."]}
user value not in the class field definition or not existing users group ID (user_groups)	400 Bad Request	"field_{user}": [""{value}" is not a valid choice."]
user value is below the limit (user_groups)	400 Bad Request	"field_{user}": ["The number of user_groups elements must be greater than or equal to {min}."]
user value is above the limit (user_groups)	400 Bad Request	"field_{user}": ["The number of user_groups elements must be less than or equal to {max}."]
user value is not an array of integers (user_groups)	400 Bad Request	"field_{user}": {"user_groups": ["The value must be an array of integers."]}
user field - attempted to pass values in the user_groups field when it was not permitted	400 Bad Request	"field_{user}": ["user_groups field is not allowed."]
user field - attempted to pass values in the users field when it was not permitted	400 Bad Request	"field_{user}": ["users field is not allowed."]

DELETE api/object-records/id/

Deletes single Object Record.

Permissions

Requires authentication and Object Class Ownership or Object Record Ownership or has Object Record delete permissions by any permission_set.

Request example

• Headers

Request Method: DELETE
Location: /api/object-records/1/
Authorization: JWT access_token

Response example

• Status 204 No Content
• Body

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Object Record does not exist	404 Forbidden	"detail": "Not found"

GET /api/object-records/

List Object Records based on query parameters and caller permissions.

Important

Access to endpoint require passing Object Class filter /api/object-records/?object_class=<object_class_id>

Permissions

Requires authentication and any of

1. object_records.list permission
2. Object Record Ownership
3. Object Class Ownership
4. Object Record Permission Set permission
5. Object Class Permission Set permission

Request example

• Headers

Request Method: GET
Location: /api/object-records/
Authorization: JWT access_token

Response

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

Response results array

Key	Type	Notes
id	id
object_name	string
object_class	int
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta	Object	_meta result

Response _meta object

Key	Type	Notes
permissions	Object
labels	Object
users	Object	Optional, added only if show_fields is passed.
user_groups	Object	Optional, added only if show_fields is passed.

Response _meta.users object

Key	Type	Notes
<user_id>	user

_meta.users contains max 50 user objects for first 50 unique items from user type fields.

Response _meta.user_groups object

Key	Type	Notes
<users_group_id>	Object	Contains group id, name and num_of_members

_meta.user_groups contains max 50 user group objects for first 50 unique items from user type fields.

Response example

• Status 200 OK
• Body

{
  "limit": 100,
  "offset": 0,
  "filtered_count": 21,
  "total_count": 21,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 21,
      "object_name": "21",
      "object_class": 2,
      "status": "initiated",
      "created_at": "2022-08-18T12:23:25.927304+02:00",
      "created_by": {
        "id": 2,
        "first_name": "ALX",
        "last_name": "Developer",
        "username": "alx.dev@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
      },
      "modified_at": "2022-08-18T12:23:25.927359+02:00",
      "modified_by": {
        "id": 2,
        "first_name": "ALX",
        "last_name": "Developer",
        "username": "alx.dev@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
      },
      "field_usertype": {"users": [23]},
      "_meta": {
        "permissions": {
          "list": true,
          "view": true,
          "edit": true,
          "create": true,
          "delete": true,
          "edit_owners": true,
          "view_owners": true,
          "tasks": {
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "create": true,
            "complete": true,
            "assign": true
          }
        },
        "labels": {
          "object_class": "MareK Test #1"
        },
        "users": {
            "23": {
                "id": 23,
                "first_name": "John",
                "last_name": "Smith",
                "username": "j.smith@autologyx.com",
                "company_name": "Autologyx",
                "is_deleted": false,
                "account_type": "super_admin"
            }
        },
        "allowed_status_transitions": [],
        "forbidden_actions": []
      }
    },
    {
      "id": 20,
      "object_name": "20",
      "object_class": 2,
      "status": "initiated",
      "created_at": "2022-08-18T12:21:35.921861+02:00",
      "created_by": {
        "id": 2,
        "first_name": "ALX",
        "last_name": "Developer",
        "username": "alx.dev@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
      },
      "modified_at": "2022-08-18T13:43:42.874876+02:00",
      "modified_by": {
        "id": 2,
        "first_name": "ALX",
        "last_name": "Developer",
        "username": "alx.dev@autologyx.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
      },
      "_meta": {
        "permissions": {
          "list": true,
          "view": true,
          "edit": true,
          "create": true,
          "delete": true,
          "edit_owners": true,
          "view_owners": true,
          "tasks": {
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "create": true,
            "complete": true,
            "assign": true
          }
        },
        "labels": {
          "object_class": "MareK Test #1"
        },
        "allowed_status_transitions": [],
        "forbidden_actions": []
      }
    },
  ]
}

Sorting

Parameter	Example	Notes
id	{build}/api/object-records/?ordering=id	Ascending
id	{build}/api/object-records/?ordering=-id	Descending (-)
created_at	{build}/api/object-records/?ordering=created_at	Ascending
created_at	{build}/api/object-records/?ordering=-created_at	Descending (-)
modified_at	{build}/api/object-records/?ordering=modified_at	Ascending
modified_at	{build}/api/object-records/?ordering=-modified_at	Descending (-)
object_name	{build}/api/object-records/?ordering=object_name	Ascending
object_name	{build}/api/object-records/?ordering=-object_name	Descending (-)
field_<field_alias>	{build}/api/object-records/?object_class=12&show_fields=field_alias&ordering=field_alias	Ascending
field_<field_alias>	{build}/api/object-records/?object_class=12&show_fields=field_alias&ordering=-field_alias	Descending (-)

Ordering by related Object Class Fields

Object Class Fields Query String parameters are included in Object Classes - GET /api/object-classes/{object_class_id}/fields/autocomplete/ endpoint.

The fields types / columns available for Ordering :

string
int
float
date
datetime
email
enum

At most, 10 total fields of any type from the object class are allowed for filtering. For best performance, use the most selective fields first. Recommended is ordering by only one field. The custom field from ordering should also be included in show_fields parameter only then ordering by this field will be enabled.

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Filtering by Object Record related fields

Parameter	Type	Example
id	int + enum	{build}/api/object-records/?id=1
created_at	datetime	{build}/api/object-records/?created_at__gte=2022-01-01
created_by	set	{build}/api/object-records/?created_by__in=123,234,345
modified_at	datetime	{build}/api/object-records/?modified_at__range=2022-01-01,2022-01-31
modified_by	set	{build}/api/object-records/?modified_by=123
object_name	string	{build}/api/object-records/?object_name__icontains=foobar
show_fields	string	{build}/api/object-records/?object_class=12&show_fields=field_alias
object_class	enum	{build}/api/object-records/?object_class__in=12,34

object_class is required

show_fields is required to attach fields with their value to the response each object record. It is possible to specify multiple fields by separating them with a comma. Max 10 fields.

Filtering by related Object Class Fields

Object Class Fields Query String parameters are included in Object Classes - GET /api/object-classes/{object_class_id}/fields/autocomplete/ endpoint.

This endpoint contains also predicates assigned for each type.

The fields types / columns available for filtering :

bool
string
int
float
date
datetime
email
phone
url
set
enum
user
document

At most, 10 total fields of any type from the object class are allowed for filtering.

For predicates in, containssome, containsall values must be separated by comma ,. If single value contains comma inside, char must be escaped by \,.

?field_set__in=first\,text,second

The User type field is unique because it stores both a list of users and groups. Therefore, filtering by this field requires specifying which of these values will be filtered.

?field_user__users__containsall=1,2,3

?field_user__user_groups__containssome=21,42,54

The Document type field supports only isempty predicate. It checks whether the field contains any files or not.

?field_document__isempty=true

Parameter	Type	Example
field_<bool_type_alias>	bool	{build}/api/object-records/?field_bool_alias=false
field_<text_type_alias>	string	{build}/api/object-records/?field_string_alias__contains=test
field_<integer_type_alias>	int	{build}/api/object-records/?field_integer__gt=1
field_<decimal_type_alias>	int	{build}/api/object-records/?field_decimal__gt=1.5
field_<date_type_alias>	date	{build}/api/object-records/?field_date=2000-09-23
field_<datetime_type_alias>	datetime	{build}/api/object-records/?field_datetime=2000-09-23 10:00:00
field_<email_type_alias>	string	{build}/api/object-records/?field_email__contains=test
field_<phone_type_alias>	string	{build}/api/object-records/?field_phone__contains=123
field_<url_type_alias>	url	{build}/api/object-records/?field_url__iexact=http://website.sample
field_<set_type_alias>	set	{build}/api/object-records/?field_set__containsall=abc,some,text,cde
field_<enum_type_alias>	enum	{build}/api/object-records/?field_enum__in=abc,some,text,cde
field_<user_type_alias>	user	{build}/api/object-records/?field_user__users__containsall=1,2,3
field_<user_type_alias>	user	{build}/api/object-records/?field_user__user_groups__containssome=21,42,54
field_<document_type_alias>	document	{build}/api/object-records/?field_document__isempty=false

Errors

Error	Response code	Message
Filter created_by with wrong user id	400 Bad Request	"detail": {"created_by": ["Select a valid choice. That choice is not one of the available choices."]}
Filter modified_by with wrong user id	400 Bad Request	"detail": {"modified_by": ['Select a valid choice. That choice is not one of the available choices."]}
Missing object_class parameter	400 Bad request	"detail": { "object_class": ["This field is required"] }
Invalid object_class parameter	400 Bad request	"detail": { "object_class": ["Invalid pk "{object_class}" - object does not exist."] }
More that 10 fields in filtering	400 Bad Request	"detail": "At most 10 fields from object class are allowed for filtering."
Wrong class field type int value	400 Bad Request	"detail": { "field_integer": ["A valid integer is required."] }
Wrong class field type decimal value	400 Bad Request	"detail": { "field_decimal": ["A valid number is required."] }
Range filter for class field of int type must include exact 2 numbers	400 Bad Request	"detail": { "field_integer": ["Range query expects two values."] }
Wrong class field type string value	400 Bad Request	"detail": { "field_text": ["Field "field_text" expected a string but got ""number"" ] }
Wrong datetime format for datetime field type	400 Bad Request	"detail": { "field_datetime": ["Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM-HH:MM Z]."]}
Wrong date format for date field type	400 Bad Request	"detail": { "field_date": ["Date has wrong format. Use one of these formats instead: YYYY-MM-DD."]}
Wrong value for choice/multichoice field type	400 Bad Request	"detail": { "field_set": [" "{value}" is not a valid choice."]}
Wrong value for user field type	400 Bad Request	"detail": { "field_user": [" "{value}" is not a valid choice."]}
Wrong value type for user field type	400 Bad Request	"detail": { "field_user": ["The value must be an array of integers."]}
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."

Cannot encode None for key 'field_country__startswith' in a query string. Did you mean to pass an empty string or omit the value

GET /api/object-records/record_id/

Permissions

Requires authentication and any of

1. object_records.view permission
2. Object Record Ownership
3. Object Class Ownership
4. Object Record Permission Set permission
5. Object Class Permission Set permission

Request example

• Headers

Request Method: GET
Location: /api/object-records/20/
Authorization: JWT access_token

Response

Key	Type	Notes
id	int
object_name	string
object_class	int
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta	Object	_meta result
field_<field_alias>	any	Fields based on Object Class configuration

Response _meta object

Key	Type	Notes
permissions	Object
labels	Object
users	Object
user_groups	Object

Response _meta.users object

Key	Type	Notes
<user_id>	user

_meta.users contains max 50 user objects for first 50 unique items from user type fields.

Response _meta.user_groups object

Key	Type	Notes
<users_group_id>	Object	Contains group id, name and num_of_members

_meta.user_groups contains max 50 user group objects for first 50 unique items from user type fields.

Response example

• Status 200 OK
• Body

{
  "id": 20,
  "object_name": "20",
  "object_class": 2,
  "status": "initiated",
  "created_at": "2022-08-18T12:21:35.921861+02:00",
  "created_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "modified_at": "2022-08-18T13:43:42.874876+02:00",
  "modified_by": {
    "id": 2,
    "first_name": "ALX",
    "last_name": "Developer",
    "username": "alx.dev@autologyx.com",
    "company_name": "",
    "is_deleted": false,
    "account_type": "super_admin"
  },
  "field_first_name": "John",
  "field_last_name": "Doe",
  "field_email": "john-doe@nwc.xxx",
  "field_documents": null,
  "field_usertype": {
    "users": [23],
    "user_groups": [2]
  }
  "_meta": {
    "labels": {
      "object_class": "MareK Test #1",
      "files": null
    },
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true,
      "edit_owners": true,
      "view_owners": true,
      "tasks": {
        "list": true,
        "view": true,
        "edit": true,
        "delete": true,
        "create": true,
        "complete": true,
        "assign": true
      },
    },
     "users": {
        "23": {
            "id": 23,
            "first_name": "John",
            "last_name": "Smith",
            "username": "j.smith@autologyx.com",
            "company_name": "Autologyx",
            "is_deleted": false,
            "account_type": "super_admin"
        }
    },
     "user_groups": {
        "2": {
            "id": 2,
            "name": "Group2",
            "num_of_members": 3
        }
    },
    "allowed_status_transitions": [],
    "forbidden_actions": []
  }
}

Errors

Error	Response code	Message
A non-existent record_id was given	404 Not Found	"detail": "Not found."
Requesting user is authorized but without view perm for tasks resource	403 Forbidden	"detail": "You do not have permission to perform this action."
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."

OPTIONS /api/object-records/

Permissions

Requires authentication only.

Request example

• Headers

Request Method: OPTIONS
Location: /api/object-records/

Response example

• Status 200 OK
• Body

{
    "list": {
        "columns": [
            {
                "alias": "id",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range",
                    "in"
                ],
                "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": {},
    "restrictions": {
        "limit_items_in_object_class": 500000
    }
}

GET /api/object-records/autocomplete/

List Object Records based on query parameters and caller permissions.

Important

Access to endpoint require passing Object Class filter /api/object-records/autocomplete/?object_class=<object_class_id>

Permissions

Requires authentication and object_records.list permission.

Request example

• Headers

Request Method: GET
Location: /api/object-records/autocomplete/
Authorization: JWT access_token

Response

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

Response results array

Key	Type	Notes
value	id
text	string

Response example

• Status 200 OK
• Body

{
  "limit": 100,
  "offset": 0,
  "filtered_count": 2,
  "total_count": 21,
  "next": null,
  "previous": null,
  "results": [
    {
      "value": 21,
      "text": "21",
      "status": "initiated",
      "_meta": {
        "allowed_status_transitions": [],
        "forbidden_actions": []
      }
    },
    {
      "value": 20,
      "text": "20",
      "status": "initiated",
      "_meta": {
        "allowed_status_transitions": [],
        "forbidden_actions": []
      }
    }
  ]
}

Sorting

Parameter	Example	Notes
value	{build}/api/object-records/autocomplete/?ordering=value	Ascending
value	{build}/api/object-records/autocomplete/?ordering=-value	Descending (-)
text	{build}/api/object-records/autocomplete//?ordering=text	Ascending
text	{build}/api/object-records/autocomplete/?ordering=-text	Descending (-)

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Filtering by Object Record related fields

Parameter	Type	Example
text	string	{build}/api/object-records/autocomplete/?text__icontains=foobar
object_class	enum	{build}/api/object-records/?object_class=12

object_class is required

Error	Response code	Message
Missing object_class parameter	400 Bad request	"object_class": ["This field with predicate "exact" is required."]
Invalid object_class parameter	400 Bad request	"object_class": ["Select a valid choice. That choice is not one of the available choices."]
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Unauthorized API call	403 Forbidden	"detail": "You do not have permission to perform this action."

POST /api/object-records/id/field-files/alias/

Uploads additional files to specific object record.

Permissions

Requires authentication and Object Class Ownership or Object Record Ownership or has Object Record edit permissions by any permission_set.

Request

• Headers

Content-Type: application/json
Authorization: JWT access_token

• Schema

POST /api/object-records/1/field-files/field_alias/

["token_1", "token_2"]

Validations

• data must be valid tokens list
• data must be not null

Response |

• Successful status 201 Created
• Response body is null

Errors

Cause	Response status code	Response message
len(existing documents + newly uploaded) > max_num_of_files	400 Bad Request	"field_alias": ["The number of elements must be less than or equal to "max_num_of_files"."]
not valid list	400 Bad Request	"field_alias": ["Value must be valid List."]
value is null	400 Bad Request	"field_alias": ["This field may not be null."]
invalid value	400 Bad Request	"field_alias": ["Invalid token "token"."]
invalid alias in url	404 Not Found
alias in url is different type than document	404 Not Found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

DELETE /api/object-records/id/field-files/alias/

Removes files from existing Object Record’s field of document type.

Permissions

Requires authentication and Object Class Ownership or Object Record Ownership or has Object Record edit permissions by any permission_set.

Request example

• Headers

Request Method: DELETE
Location: /api/object-records/1/field-files/field_alias/
Authorization: JWT access_token

• Schema

POST /api/object-records/1/field-files/field_alias/

[1, 54]

Response example

• Status 204 No Content
• Body

Errors

Cause	Response status code	Response message
not valid list	400 Bad Request	"detail": ["Expected a list of items but got type "{type}"."]
value is null	400 Bad Request	"detail": ["This field may not be null."]
invalid value	400 Bad Request	"detail": ["A valid integer is required."]
len(sent list) > max_num_of_files	400 Bad Request	"detail": ["The number of elements must be less than or equal to "max_num_of_files"."]
Required field will be NULL (all files could be deleted)	400 Bad Request	"field_alias": ["This field may not be null."]
invalid alias in url	404 Not Found
alias in url is different type than document	404 Not Found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

GET /api/object-records/record_id/fields/field_alias/

Field details based on query parameters and caller permissions.

Permissions

Requires authentication and view for a specific object record.

Request

• URL parameters

Key	Type	Notes
record_id	id
field_alias	any	Fields based on Object Class configuration

• Headers

Content-Type: application/json
Authorization: JWT access_token

• Schema

GET /api/object-records/1/fields/field_user

Response

Key	Type	Notes
id	id	id of an object record
name	string	the object records name (ID or identifier)
object_class	int	the ID of an object class
_meta	Object	_meta result
field_<field_alias>	any	Fields based on Object Class configuration

Response _meta object may contain various fields based on the field type.

Key	Type	Notes
files	Array	Returned only for Document field type
users	Object	Returned only for User field type
user_groups	Object	Returned only for User field type
is_min_users_fulfilled	bool	Returned only for User field type

Response examples

• Status 200 OK
• Body

{
  "id": 1,
  "object_name": "Test",
  "object_class": 1,
  "field_user": {
    "users": [520, 642],
    "user_groups": [761]
  },
  "_meta": {
    "is_min_users_fulfilled": true,
    "users": {
      "520": {
        "id": 520,
        "first_name": "Kamille",
        "last_name": "Kohler",
        "username": "kamille.kohler11@example.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
      },
      "642": {
        "id": 642,
        "first_name": "a",
        "last_name": "b",
        "username": "ab@example.test",
        "company_name": "",
        "is_deleted": false,
        "account_type": "full"
      }
    }
  },
  "user_groups": {
    "761": {
      "id": 761,
      "name": "54fd57",
      "num_of_members": 3
    }
  }
}

• Status 200 OK
• Body

{
  "id": 1,
  "object_name": "Test",
  "object_class": 1,
  "field_document":  [
       55513,
       55514,
       55515
     ]
   },
  "_meta": {
    "files": {
      "55513": {
        "name": "sample3.docx",
        "url": "https://file_url.autologyx.com",
        "size": "34375",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      },
      "55514": {
        "name": "Invoice template.docx",
        "url": "https://file_url.autologyx.com",
        "size": "79533",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      },
      "55515": {
        "name": "ABC_2024-06-13.docx",
        "url": "https://file_url.autologyx.com",
        "size": "14105376",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    }
  }
}

Errors

Error	Response code	Message
A non-existent record ID was given	404 Not Found
Given {field_alias} is not a class field	404 Not Found
Given {field_alias} is not used in object record configuration	404 Not Found
Given {field_alias} is not exists	404 Not Found
No permission to view the record	403 Forbidden	"detail": "You do not have permission to perform this action."
Requesting user is not authenticated	401 Unauthorized

GET /api/object-records/files/

Retrieve the details of selected documents by providing their file IDs. The returned objects for each file match the existing Document-type field metadata returned in Record Details.

Important

Access to endpoint require passing Object Class filter /api/object-records/files/?object_class=<object_class_id>

Permissions

Requires authentication and view for a specific object record that contains the requested files. Only files from records the user has permission to view are returned.

Request

• URL parameters

Key	Type	Notes
object_class	id
id__in	id	File id list, comma separated

• Headers

Content-Type: application/json
Authorization: JWT access_token

• Schema

GET /api/object-records/files/?object_class=1&id__in=10,20,30

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
id__in	set
object_class	enum

Validations

• id__in
  • This field is required.
  • parameter can contain up to 50 file IDs.
• object_class
  • This field is required.
  • Invalid pk "value" - object does not exist.

Response

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

Response results array

Key	Type	Notes
id	id	ID of an file object.
name	string	File name.
url	url	Link to file's content.
size	string	File size.
type	string	File mime type.

Response examples

• Status 200 OK
• Body

{
    "limit": 100,
    "offset": 0,
    "filtered_count": 3,
    "total_count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
        "id": 10,
        "name": "sample3.docx",
        "url": "https://file_url.autologyx.com",
        "size": "34375",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        },
        {
        "id": 20,
        "name": "Invoice template.docx",
        "url": "https://file_url.autologyx.com",
        "size": "79533",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        },
        {
        "id": 30,
        "name": "ABC_2024-06-13.docx",
        "url": "https://file_url.autologyx.com",
        "size": "14105376",
        "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }
    ]
}

• Status 200 OK
• Body

Errors

Error	Response code	Message
A non-existent record ID was given	404 Not Found
Missing object_class parameter	400 Bad Request	"detail": { "object_class": ["This field is required."] }
Invalid object_class parameter	400 Bad Request	{ "object_class": ["Invalid pk "{object_class}" - object does not exist."] }
Missing id__in	400 Bad Request	"detail": { "id__in": ["This field is required."] }
Invalid id__in parameter	400 Bad Request	"detail": { "id__in": ["Invalid value. Must be valid file ids."] }
Too many IDs (>50)	400 Bad Request
Requesting user is not authenticated	401 Unauthorized

GET /api/object-records/transactions/transaction_id/

An authenticated user can retrieve the status of the record update transaction.

Permissions

Requires authentication only.

Request

• URL parameters

Key	Type	Notes
id	uuid

• Headers

Content-Type: application/json
Authorization: JWT access_token

• Schema

GET /api/object-records/transactions/7fa04f22-xxxx-xxxx-xxxx-5087d9d224e5/

Response

Key	Type	Notes
id	uuid	Automatically generated by the backend.
status	string
error_message	string
updated_records	Array	list of all records updated in the transaction, grouped by their object class

Response examples

{
  "id": 7fa04f22-xxxx-xxxx-xxxx-5087d9d224e5,
  "status": "processing",
  "error_message" "",
  "updated_records": [1, 2, 3, ...]
}

• Status 200 OK
• Body

"error_message" details:

• Errors for Object Records.

Error	error_message
All errors follow the same pattern	{"object_class": {"id": {class_id}, "errors": {"field_slug1": [Object Record Errors ...]}}}

• Errors for each type of Object Record Field.

Error	error_message
All errors follow the same pattern	{"object_class": {"id": {class_id}, "errors": {"field_slug1": [Object Record Field Errors ...]}}}

Errors

Error	Response code	Message
Requesting user is not authenticated	401 Unauthorized	"detail": "You do not have permission to perform this action."
Transaction ID does not exist	404 Not Found	"detail": "Not found."

PATCH /api/object-records/update-by-filter/object_class_id/?

Updating records based on filter conditions.

Important

1. The update transaction is created and can be retrieved using the GET /api/object-records/transactions/transaction_id/ endpoint.
2. The update transaction is created asynchronously and the response will be returned immediately.
3. The update transaction will be processed in the background.
4. The IDs of the records that will be updated are the records that match filtering results at the moment of the request.
5. Transaction details are retained for 7 days after processing is complete.

Permissions

Requires authentication.

Important

1. Only the records that match the filter results and for which the user has the Object Record edit permission will be updated.
2. Records for which the user doesn't have permissions to edit are not updated.

Request

• Headers

Request Method: PATCH
Authorization: JWT access_token

• Query parameters

Key	Type	Notes
object_class_id	int

• Body

The field_<field_alias> (all allowed types of fields) can be included in the request body: the fields and values to be updated in the matching records.

Important

If the field passed in the request body does not exist, it's silently ignored.

Validations

Fields validation works the same way as for the Object Record Update API.

Sample request body

PATCH /api/object-records/update-by-filter/12/?status__exact=initiated

{
  "field_<field_alias>": <any_allowed>,
  ...
  "field_<field_alias>": <any_allowed>,
}

Filtering works the same way as in GET /api/object-records/ endpoint.

For the full description of standard predicates see ALX API standards - Developers guide.

Filtering by Object Record-related fields

Parameter	Type	Example
id	int + enum	{build}/api/object-models/1/object-records/descendants/?id=1
created_at	datetime	{build}/api/object-models/1/object-records/descendants/?created_at__gte=2022-01-01
created_by	set	{build}/api/object-models/1/object-records/descendants/?created_by__in=123,234,345
modified_at	datetime	{build}/api/object-models/1/object-records/descendants/?modified_at__range=2022-01-01,2022-01-31
modified_by	set	{build}/api/object-models/1/object-records/descendants/?modified_by=123
object_name	string	{build}/api/object-models/1/object-records/descendants/?object_name__icontains=foobar

Filtering by related Object Class Fields

1. At most, 10 total fields of any type from the object class are allowed for filtering.
2. Filter conditions must follow the standard Object records supported format and field filtering.
3. Filters can be combined, allowing multiple conditions to be applied simultaneously, as already implemented for the Records list.
4. Each filter can only be used once as already implemented for the Records list. (When duplicate fields are passed in the filter conditions, only the last one is applied).
5. The same field types and predicates are supported as in the GET /api/object-records/ endpoint.

Response

Key	Type	Notes
id	uuid
status	string
url	string

• Successful status 200 Created
• Response body schema

{
  "id": "7fa04f22-xxxx-xxxx-xxxx-5087d9d224e5",
  "status": "queued",
  "url": "https://test.com/api/object-records/12/transactions/7fa04f22-xxxx-xxxx-xxxx-5087d9d224e5/" 
}

Important

1. The update transaction will be marked as "processing" until all records are updated.
2. The update transaction will be marked as "completed" once all records are processed successfully.
3. The update transaction will be marked as "failed" only if an error occurs during the enqueuing of the transaction.
4. If the error occurs during the processing of the transaction, for single records, it will be skipped and only logged in system logs.

Errors

Cause	Response code	Message
Incorect object class	404 Bad Request	"detail": "Not found"
Previous update transaction for this object_class is still in progress	404 Bad Request	"detail": ["Previous update transaction for this object_class is still in progress."]
Previous update transaction for this object_class is still in progress	404 Bad Request	"detail": ["Previous update transaction for this object_class is still in progress."]
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."