Introduction
Checkpoints primarily consist of:
-
A name for the checkpoint (55 characters max)
-
Instructions for who will interact with it (500 characters max)
-
The account ID where the checkpoint is/belongs to
-
A position (many different employees can work the same position, so it can’t be linked to employee)
-
An active status or not
-
A scan action type (report, scan only, message, report or any number of exception types)
-
A few different extra options for questions, answers and exceptions.
-
Monitoring option and type
-
An exception category
-
Optionally points to a site location
-
And some last scan data
Scan Action Types
Scan Action Types
In the TrackTik web application are dynamic show/hide elements for the Checkpoint Scan Action Type. The /checkpoint entity’s endpoint aims to follow the interface where each scan type shows different fields, by accepting or rejecting information (quietly, without validation feedback current 2022-11-18).
It’s therefore necessary that you understand the Checkpoint Scan Types more intimately before using /checkpoints.
REPORT
When a checkpoint scan’s required action is to create a report, the REPORT scan action type must be defined, along with the ID of the Report Template.
"scanActionType": "REPORT",
"scanReportTemplate": int ID number,Do not provide a scanActionMessage nor scanActionQuestion in the same payload as a REPORT scan action type, otherwise the scanReportTemplate value will not be captured (2022-11-18)
MESSAGE
Message scanActionType of MESSAGE only requires a message to be displayed to the person on tour at that checkpoint.
"scanActionType": "MESSAGE",
"scanActionMessage": "Hello this is a msg",Do not provide a scanActionQuestion nor scanReportTemplate, to avoid any problems with persisting scanActionMessage. (2022-11-18)
EXCEPTION_(YES|NO|RANGE|MULTIPLE)
Exceptions are interactions with checkpoints that fall outside of a positive outcome. They signal the creation of pre-defined reports and notifications.
The most common types of exceptions are “yes” or “no” answers to a status prompt. Depending on the type of exception defined as positive or negative (and therefore necessitating an exception event), a different scanActionType will be defined.
EXCEPTION_YES : Answering No to the prompt is the exception.
"scanActionType": "EXCEPTION_NO",
"scanActionQuestion": "Is the door locked?",EXCEPTION_NO : Answering Yes to the prompt is the exception.
"scanActionType": "EXCEPTION_YES",
"scanActionQuestion": "Has the door been left open?",Notice how scanActionMessage and scanReportTemplate fields are being omitted entirely to not overwrite scanActionQuestion.
EXCEPTION_MULTIPLE : * each prompt has their own exception and report parameters
A scan action type of EXCEPTION_MULTIPLE allows the asking of multiple scan action types as part of a sub-object of type/question|range values. In the API these appear as an on-demand array of objects that must be included when retrieved or posted as a complete set.
[GET] /checkpoints/522?include=scanActionMultiple
{
"name": "Heater #1",
"instructions": "Check the status and instrumentation",
"account": 687,
"position": null,
"active": true,
"scanActionType": "EXCEPTION_MULTIPLE",
"scanActionMessage": "",
"scanReportTemplate": null,
"scanActionQuestion": "",
"monitoringOption": "PART_OF_TOUR",
"monitorType": "PART_OF_TOUR",
"exceptionCategory": 26,
"siteLocation": null,
"lastScan": 7337,
"id": 522,
"scanActionMultiple": [
{
"label": "Temperature range",
"type": "exception_range",
"min": "15",
"max": "25",
"index": 0,
"name": "q_0",
"category": {
"id": 27,
"name": "Maintenance / Heating or Air Conditioning",
"details": "",
"showInDefaultGroup": true,
"severityLevel": "LOW",
"customId": "300-B",
"category": 10,
"alias": null,
"isGlobal": true,
"region": 2,
"reportFlagTemplate": 1744,
"defaultLanguage": "",
"translatable": false
},
"required": "1"
},
{
"label": "Is the gauge in the red?",
"type": "exception_yes",
"min": "",
"max": "",
"index": 1,
"name": "q_1",
"category": {
"id": 27,
"name": "Maintenance / Heating or Air Conditioning",
"details": "",
"showInDefaultGroup": true,
"severityLevel": "LOW",
"customId": "300-B",
"category": 10,
"alias": null,
"isGlobal": true,
"region": 2,
"reportFlagTemplate": 1744,
"defaultLanguage": "",
"translatable": false
},
"required": "1"
}
EXCEPTION_MULTIPLE doesn’t offer the following types within its array (so plan on using the REPORT scanActionType, and have these in the report template fields list):
-
signature
-
exception_picture
-
exception_high_quality_picture
EXCEPTION_RANGE : A data read or measurement should be within a range
Be sure to include the two values of the range as rangeMin and rangeMax along with the scanActionType. The values for the ranges can include precision and there is validation on the max value being greater than the min value:
{
"name": "Checkpoint-1682447616",
"account": 463,
"scanActionType": "EXCEPTION_RANGE",
"scanActionQuestion": "aut quia quia?",
"rangeMin": 1,
"rangeMax": 100
}Checkpoint Monitoring Options
For checkpoints that have a monitoringOption value of “TIME_INTERVAL” (and only for this value), you can define the scanRequestInterval in minutes.