Introduction

Custom Fields is a new feature to be able to add up to 25 additional custom fields per entity, to extend their data model. The three entities are: employees, clients, and positions. This feature can extend data record attributes to add depth to TrackTik data, and to more easily integrate with external systems.

While each entity endpoint (/employees, /clients, /positions) is used to work with the values of their respective Custom Fields (post/patch/put), the underlying definition of the custom fields is done through a NEW API endpoint: /custom-fields.

Enablement and Permissions

Custom Fields API endpoints and GUI elements of the TrackTik web application can be enabled via Release Toggle and Regional feature settings. These enablement switches can only be set by internal TrackTik resources so you'll have to ask for the feature.

Web application and API Service Accounts must have the "superuser" escalation set for their employee records before they can use Custom Fields.

A Warning About “required” Custom Fields

Any existing integrations creating or updating employees, positions or clients data may break since they will likely not be including Custom Fields data in their payloads, and not designed to meet the data validation rules of “required” Custom Fields.

E.g. If a Custom Field of the Employees data entity is configured as required, and an existing integration is not writing to the Custom Field to meet the new added requirement, it will begin to fail.

Therefore you’re encouraged to NOT use the “required” property when learning to work with Custom Fields, nor until you’ve fully assessed any existing integrations and if they can be updated to meet the new requirement by including those extra fields in any and all POST/PATCH operations of the data entity. Since Clients are a type of Account, this means Accounts too by extension.

Setting Custom Fields as required without an impact analysis can immediately break:

• POST/PATCH Integrations on employees, clients and positions
• SSO + SCIM configurations
• ADP and Paycor (and any others that can write to employees data)

Custom Fields Definition

Every Custom Field is based on a datatype, and each can have their own validation rules (to help keep the data integral to the datatype, and respect the field definitions of the underlying database storage.) You have some control over these limits and can tweak them to more specifically meet business and system needs.

Here’s an overview of the possible datatypes of Custom Fields, and how you can protect their data integrity with validation rules:

NOTES

• INT: has a range of -2,147,483,648 to 2,147,483,647
• TINYINT: has a range of -128 to 127
• NUMBER: has a range of -99,999,999,999,999.999999 to 99,999,999,999,999.999999
• DATE: has a format of YYYY-MM-DD
• DATETIME: has a format and range of ‘1000-01-01 00:00:00:000' to '9999-12-31 23:59:59:999' and is stored as provided. It won’t be the timezone of the server, nor calculated/changed and has a precision up to 6 microseconds.

Creating a Custom Field

Up to 25 Custom Fields can be created for an entity record (positions, employees, clients), and they’re created by POSTing to the /custom-fields endpoint. 

Minimum Required Details

There’s a minimum number of key:value pairs hat you need to provide in the JSON payload:

entity : clients, employees or positions (enum)

type : This is the datatype, as defined in the Definitions section table from earlier in this document (string, int, number, bool, date, datetime)

name :

• This is the “key” value that will be referred to in the custom JSON object, like “legacyUid”.
• This key cannot contain any spaces, and must start with a lower case character (i.e. use camelCase)
• This key name cannot exceed 64 characters in length.
• You also can’t use reserved names like: id, custom, uri, type, status, links or meta.

label : This is the label to display in TrackTik’s UI based applications, like Guarding Suite.

POST /custom-fields 

{
  "entity" : "employees",
  "type" : "string",
  "name" : "eyeColour",
  "label" : "Eye Colour"
}

Additional Optional Custom Fields Attributes

description : If the label doesn’t make the purpose of the field self-evident, you can provide a longer description to explain it.

indexed : true, false. This tells the database to create an index for the Custom Field to increase the performance of searches/filters on it.

required : If you need to enforce that a particular Custom Field is defined during POST/PATCH operations to employees, positions, or clients data (not just the “custom” sub-object), then you can set this to “true”. The default is “false”. WARNING: any existing integrations creating or updating employees, positions or clients data may break since they will likely not be including Custom Fields data in their payloads, and not designed to meet the data validation rules of “required” Custom Fields.

piiFlag : If a Custom Field will hold personal identification data that should be hidden from unauthorized users, set this to “true”. The default is “false”.

validations : A validation rule allows you to define limits for certain data types. The possible validations are:

• string: minLength, maxLength, pattern (regex, max 500 chars), enum
• int / number: minimum, maximum, enum
• bool / date / datetime: No validation rules are supported

The possibilities are expressed as a JSON object, and are all evaluated as AND operations with possible keys and values like:

string
       "minLength": 3, 
       "maxLength": 10,
       "pattern": "^[A-Z][a-z]+$",  //regex to check if a proper noun
       "enum": ["Mike", "Kennedy", "Mentos"]
integer
       "minimum": 1, 
       "maximum": 10,
       "enum": [1,2,3]
number
       "minimum": 1.1,
       "maximum": 10.1, 
       "enum": [1.1,2.1,3.1]

A note on status:

status : You won’t be setting this value yourself, not directly as payload data anyway. A new Custom Field will have status of “ACTIVE” and should you archive the Custom Field via its /archive API action, it will become “ARCHIVED. How to archive Custom Fields is elsewhere in this documentation.

Examples

Example 1:

A Custom Field of type string, named customFieldString1779304371, that at minimum must contain at least 3 characters, and at most 10. Min and Max validations are >= and <=.

{
    "entity": "clients",
    "type": "string",
    "name": "customFieldString1779304371",
    "label": "Custom Field String 1779304371",
    "description": "Custom Field String Description 1779304371",
    "indexed": false,
    "required": false,
    "piiFlag": false,
    "validations": {
        "minLength": 3,
        "maxLength": 10
    }
}

Example 2:

A Custom Field of type string, named customFieldString1779304371, that can only be one of the values Mike, Kennedy or Mentos.

{
    "entity": "clients",
    "type": "string",
    "name": "customFieldString1779304371",
    "label": "Custom Field String 1779304371",
    "description": "Custom Field String Description 1779304371",
    "indexed": false,
    "required": false,
    "piiFlag": false,
    "validations": {
        "minLength": 3,
        "maxLength": 10,
        "pattern": "^[A-Z][a-z]+$",
        "enum": [
            "Mike",
            "Kennedy",
            "Mentos"
        ]
    }
}

Example 3:

A Custom Field of type string, named customFieldString1779304371, that is at minimum 3 characters, at most 10 characters, and is a word that begins with an upper case letter followed by a number of lower case characters (like a first name: Mike).

{
    "entity": "clients",
    "type": "string",
    "name": "customFieldString1779304371",
    "label": "Custom Field String 1779304371",
    "description": "Custom Field String Description 1779304371",
    "indexed": false,
    "required": false,
    "piiFlag": false,
    "validations": {
        "minLength": 3,
        "maxLength": 10,
        "pattern": "^[A-Z][a-z]+$",
    }
}

NB: Validations that are not appropriate to the datatype (like a minLength for an INT datatype) will be rejected with error response.

Viewing/Searching the Custom Fields of Entity Records

By Full Object

For employees, clients and positions, you can view their Custom Fields through a single “include” parameter:

GET /clients?include=custom

GET /employees?include=custom

GET /positions?include=custom

E.g. in the below there are 19 definitions for Clients entities (so 19 entries in /custom-fields related to clients)

One or More Custom Fields and Optional Filter

The 1:1 relation list of the Custom Fields JSON object can be filtered on and added to a fields parameter if you want to lift out a single Custom Field in the API response based on a search pattern (like :contains, =, etc.) You can do this directly for Clients, Employees and Positions, but also when one of those three is a relation list inside another entity.

A simpler more direct search could be achieved with:

GET /clients?fields=custom.legacyUid:contains=ABC

So this is a conditional display of custom.legacyUid. If it didn’t contain ABC, then no records would be returned even though a Custom Field of legacyUid still exists and holds some other value. 

ACTIVE vs ARCHIVED

Custom Fields defined in /custom-fields have a status, either ACTIVE or ARCHIVED. For ARCHIVED records you need to use the usual filter includeInactive=true to include them in responses.

Updating Custom Field Values for an Entity Record

To update the value of one or more Custom Fields of an Entity Record, you have to PATCH to the id of the record, and include a JSON object of “custom”, calling out only the Custom Fields you wish to update.

You may only update:

• label
• description
• indexed
• required
• piiFlag
• validations

If you need to change datatype (type), or the entity, you should archive the Custom Field and create a new one. This will require you do a data migration/recreation of the new Custom Field values. The Custom Fields solution currently doesn’t have the means of performing its own datatype transformations, like going from INT to STRING.

For example, to update two Custom Fields, one Boolean named “securitasActive” and one String named “legacyUid“, of a Client Site who’s id is 14, you would:

PATCH /clients/14?include=custom

{
  "custom" : {
     "securitasActive" : true,
     "legacyUid" : "TEST-ABC"
  }
}

Archiving Custom Fields

To archive a Custom Field, you need to use the dedicated API action for it via its ID, and it will set its status to ARCHIVED.

POST /custom-fields/{id}/actions/archive

Past values assigned to a Custom Field (via the sub objects off of employees, positions, clients) that’s been archived will be frozen/preserved.

Names/keys of Custom Fields in an ARCHIVED state cannot be reused in other new/active Custom Fields. This is to enable the Unarchiving feature and to prevent duplication collisions. 

Unarchiving Custom Fields

To unarchive a Custom Field, you need to use the dedicated API action for it via its ID, and it will set its status to ACTIVE.

POST /custom-fields/{id}/actions/unarchive

Any previously assigned values (via the sub objects off of employees, positions, clients) will become available and editable again.