Creating a Report Template and Report Template Fields
Creating a Report Template requires two steps of first creating the template’s metadata and then its fields.
Report Template metadata
POST /report-templates
{
"name": "AB Florist Template",
"details": "API testing",
"adminOnly": true,
"account": 2,
"type": "REGULAR_REPORT",
"approveAutomatically": true,
"notifyAlertQueue": false,
"reportShouldBeLinkedToASiteNotAZone": true,
"excludeFromShiftReport": true,
"defaultLanguage": "EN-US",
"translatable": false
}name and details : user generated, whichever you prefer. Name is capped at 255 characters and details is longer.
adminOnly : true or false, depending on if only Administrator Portal users should use it.
account : this is the region’s ID (can look this up via GET /regions )
type : this is one of many constants that can affect which Sections are available when creating Report Template Fields (E.g. type DISPATCHABLE_TASK enables Section “Dispatch Center” in the web application, whereas REGULAR_REPORT won’t have it, but the API won’t care about that so when working with a “List of Incident Categories”, the report-template-field datatype will still be LIST_FLAG)
approveAutomatically : true or false, if reports created using this template should be auto-approved when created, or left in a status like “NEW”
notifyAlertQueue : new report creations can be configured to trigger notifications. This is just a master switch for participating in that configuration
reportShouldBeLinkedToASiteNotAZone : true or false, and like the name suggests, helps control what reports belong to
excludeFromShiftReport : true or false, and decides if a Shift Report should mention reports of this template. E.g. if this is a disciplinary report and the client isn’t interested in those when looking at shifts data
defaultLanguage : one of many constants for language settings.
As of 2025-03-18 the current list is (look at the codes between quotes on the left)
translatable : there can be sub-forms with multiple languages. This sets if the template will participate in that or not.
Report Template Fields
Each field in the form of a report that a guard works with or an integration seeks to populate, should be defined as a Report Template Field with a parent Report Template.
Most Report Template Fields should be understood as having a name, and a type of data. Most types are just one name, and one type of value like a line of text or a date like yyyy-mm-dd. A line of text can be 255 characters but a description/block/area of text is 65k characters. A “list” or “drop down” type datatype will require an array of strings for the names of the items. There are many datatypes to choose from and this first documentation effort won’t cover them all, but you can always query a history of reports and their reportFields to inspect what kind of “value” keyed data is being captured and derive from there.
Lists based Datatype Fields
POST /report-template-fields
{
"parent" : {
"type" : "report-templates",
"object" : 2866
},
"label": "LIST",
"type" : "LIST",
"listItems" : ["item 1", "item 2"],
"required" : false
}parent object (report template) : To reference the parent Report Template, you have a sub-object called “parent” that requires the type of “report-templates” and an object that is the report-templates.id value of the parent Report Template.
label : this is the title of the field that will display on the form. The above example is overly simplistic. Be more creative. slightly smiling face
type : This is the most important value to define, the actual name of the datatype. There are many to choose from.
E.g.
listItems : OPTIONAL. Only include this field if the “type” is one of:
- LIST (List Picker)
- LIST_MULTIPLE (List Picker Multiple)
Many datatypes are called “list” items, but they’re actually data lookups that return a single value, and the lookups come from other data sources, so they don’t need to be redefined as listItems in the template field. Examples of those are: Incident Categories, Patrol Vehicles, Tenants List, Employee List, Site Locations etc.
String or Numeric Values Fields
These are very simple and include anything that is a looked up value, a date, label or body text. In the list of Report Template Fields below, you can see how listItems isn't required, so your payload to POST a new Report Template Field can be like the previous example, but while omitting the listItems definition:
POST /report-template-fields
{
"parent" : {
"type" : "report-templates",
"object" : 1212
},
"label": "Date of incident",
"type" : "DATE",
"required" : false
}
Examples of Various Created Report Template Fields
(look at the "type" value in the list below to know which datatype of the Report Template Field is being shown):
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1217,
"label": "client list",
"name": "f_1217",
==> "type": "LIST_CLIENT",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1218,
"label": "client list (relink)",
"name": "f_1218",
==> "type": "LIST_CLIENT_RELINK",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1219,
"label": "employee list",
"name": "f_1219",
==> "type": "LIST_EMPLOYEE",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1220,
"label": "patrol vehicle list",
"name": "f_1220",
==> "type": "LIST_PATROL_VEHICLE",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1221,
"label": "tenant list",
"name": "f_1221",
==> "type": "LIST_RESIDENT",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1222,
"label": "date picker",
"name": "f_1222",
==> "type": "DATE",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1213,
"label": "incident category",
"name": "f_1213",
==> "type": "LIST_FLAG",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
},
{
"reportTemplate": 1212,
"parent": {
"type": "report-templates",
"object": 1212
},
"id": 1214,
"label": "list site location",
"name": "f_1214",
==> "type": "LIST_SITE_LOCATION",
"required": false,
"adminOnly": false,
"displayOrder": 0,
"extra": "",
"list": null,
"listItems": null,
"isDispatcherField": false,
"fieldTag": "",
"confidential": false
}
Archiving Report Templates (single, or in bulk)
The report-templates endpoint has an action for archiving. You can archive Report Templates one at a time, or as a /batch/file bulk operation. In both cases you should specify to archive any children Report Templates or not.
Single Archival
You need to know the id of the Report Template to archive and specify it in the API endpoint path:
[POST] /report-templates/{id}/actions/archive
With payload:
{
"childExtension": "ARCHIVE_CHILDREN"
}Batch Archival
[POST] /batch/file
With payload of one or more operations. Two operations are in the example below, where the lookup values are the ids of the Report Templates to archive:
{
"onFailure": "CONTINUE",
"operations": [
{
"action": "EXECUTE",
"resource": "report-templates",
"actionName": "archive",
"lookup": {
"id": 2887
},
"data": {"childExtension": "ARCHIVE_CHILDREN"}
},
{
"action": "EXECUTE",
"resource": "report-templates",
"actionName": "archive",
"lookup": {
"id": 2886
},
"data": {"childExtension": "ARCHIVE_CHILDREN"}
}
]
}