1. TrackTik Help Center
  2. Developer Tools
  3. API How Tos / Best Practices
  4. Site Tasks

Site Tasks : Schedules / Occurrences / Sessions

Updated

API Endpoints Explained

site-task-schedules is a template, saying execute this task every Monday and Friday.

site-task-occurrences is the occurrence of that template in specific dates, example: 2024-024-15, 2024-04-19, ....

site-task-occurrence-sessions is created when a task is taken, assigned to a user to perform it, all the work being done is executed on the session.

site-task-occurrence-session-logs are steps performed during the session

NB:
  
    *-occurrences endpoints across the TrackTik API are a query (view) on
    the back-end that pulls dates from a data table with all dates of the
    Gregorian calendar up to a number of future years. It’s universal and
    shared as constants.
  
  
    You will therefore only work with the *-schedules entities for configuring
    recurrence patterns of activities, which then modifies the view into
    the universal and shared calendar data.
   

Site Task Scheduling Types

Recurrent site task are used when you know you have to do something on a specific schedule. These tasks have multiple occurrences created when the schedule is created: One occurrence for each day based on the frequency/day of the week, etc.

I need to check the oil tank every Monday of every 2nd week.

One time task is a task that happens only once and/or that you don't expect to happen often. It is used for special and/or non recurring events. These task have a single occurrence that is created the moment the schedule is created.

A VIP is visiting my site on April 26th so I'll create a one time task to have a mobile user there can make sure everything is safe and tidy.

An Adhoc task is a task that does not necessarily happen on a schedule but its something you know will have to be performed often during a specific period (or the whole year around). These tasks don't have a site-task-occurrence created until a mobile user uses the Add Occurrence action on it.

Shovel the snow -> It does not always snow, but I don't want to monitor the snowfall across all my sites so I’ll create an adhock task when its needed. I expect the mobile user to pickup the task if they see it needs to be done.

Web/Mobile UI Site Task Statuses

Scheduled - Assigned to a mobile user but not Started (also when UnAssigned)
In Progress - Guard is performing the site task (aka Started)
Converting - This Site Task is being converted into a Runsheet Event
Completed - Site Task has been completed/converted.
Missed - Nobody took this Site Task on the scheduled day
Incomplete - Stopped by the mobile user/admin
Pending - Site Task has been Offered to another Guard and Pending acceptance

 

API Site Task Occurrence Session Logs Statuses (“type” field)

  • SCHEDULED
  • UNASSIGNED
  • ASSIGNED
  • STARTED
  • POSTPONED
  • COMPLETE
  • REPORT_COMPLETE
  • TAKEN
  • OFFERED
  • ACCEPTED
  • DECLINED
  • CANCELLED
  • RE-OPENED
  • CONVERTED
  • CONVERSION_CANCELLED
  • CONVERSION_DECLINED
  • CONVERSION_AUTO-DECLINED

Create a Site Task Schedule

To create a Site Task Schedules requires a bunch of ID numbers for the relations to link to and contextualize them.

E.g.

[POST] /site-task-schedules

{
   "customId": "",
   "taskType": 4,
   "description": "",
   "instructions": "Write a report",
   "client": 687,
   "priceTier": 4,
   "position": 382,
   "checkpointTour": 131,
   "reportTemplate": 1143,
   "type": "RECURRING",
   "beginServiceDate": "2024-01-15T00:00:00+00:00",
   "endServiceDate": null,
   "rangeStartTime": "09:32:00",
   "rangeEndTime": "10:32:00",
   "durationMinutes": 5,
   "dayOfWeekStart": [
      "SATURDAY",
      "THURSDAY",
      "WEDNESDAY",
      "TUESDAY",
      "FRIDAY",
      "MONDAY"
   ],
   "dayOfWeekEnd": [
      "SATURDAY",
      "THURSDAY",
      "WEDNESDAY",
      "TUESDAY",
      "FRIDAY",
      "MONDAY"
   ],
   "frequency": "WEEKLY",
   "status": "ACTIVE",
   "taskSiteInstruction": null
}

If the taskSiteInsturction is submitted as NULL, it will instead pick up one of the existing site task instructions for the client site identified by its integer id.

Site Task Occurrence Session Logs

This is the endpoint for site task completions/activities that were performed on schedule

[GET] /site-task-occurrence-session-logs/6634?include=session,occurrence,session.report.reportFields

{
    "employee": 376561,
    "type": "REPORT_COMPLETE",
    "comments": "",
    "id": 6634,
    "occurrence": {
        "id": 2024021689,
        "occurrenceDate": "2024-02-16T00:00:00+00:00",
        "customId": "",
        "schedule": 89,
        "taskType": 43,
        "description": "C2 Data Center Patrol",
        "instructions": "Patrol C2",
        "status": "COMPLETED",
        "client": {
            "id": 4463,
            "id{timezoneProviderIdPath}": 4463
        },
        "priceTier": null,
        "position": 4822,
        "checkpointTour": 15758,
        "reportTemplate": 2015718,
        "type": "RECURRING",
        "beginServiceDate": "2024-01-25T00:00:00+00:00",
        "endServiceDate": null,
        "rangeStartTime": "22:00:00",
        "rangeEndTime": "02:00:00",
        "durationMinutes": 10,
        "dayOfWeekStart": [
            "SUNDAY",
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY",
            "SATURDAY"
        ],
        "dayOfWeekEnd": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY",
            "SATURDAY",
            "SUNDAY"
        ],
        "frequency": "WEEKLY",
        "timeZone": "America/Chicago",
        "rangeStartedDateTime": "2024-02-16T22:00:00-06:00",
        "rangeEndedDateTime": "2024-02-17T02:00:00-06:00",
        "session": 1906,
        "taskSiteInstruction": null,
        "exception": null
    },
    "session": {
        "status": "COMPLETED",
        "startedOn": "2024-02-17T04:21:15+00:00",
        "endedOn": "2024-02-17T04:24:22+00:00",
        "effectiveDuration": 3,
        "id": 1906,
        "report": {
            "reportTemplate": 1,
            "timeZone": "America/Chicago",
            "reportDateTime": "2024-02-16T22:20:54-06:00",
            "submitTime": 1708143859,
            "submittedOn": "2024-02-17T04:24:19+00:00",
            "account": {
                "id": 4463,
                "id{timezoneProviderIdPath}": 4463
            },
            "position": 4822,
            "approvedOn": null,
            "approvalDateTime": null,
            "status": "NEW",
            "approvedBy": null,
            "checkpoint": null,
            "reportFlag": null,
            "siteLocation": null,
            "id": 132771364,
            "custom": 132771364,
            "reportFields": [
                {
                    "fieldTag": "details",
                    "report": 132771364,
                    "templateField": 2,
                    "value": {
                        "type": "text",
                        "value": "No issues"
                    },
                    "archived": false,
                    "id": 465313523
                }
            ]
        }
    }
}

Site Task Sessions and Periodic Assignments

Site Task Sessions represent individual executions of a site task. Normally, a site task has only one session per occurrence date, but this changes when Periodic Assignments are enabled.
Periodic Assignments are a feature that allows tasks to be performed multiple times within a single day or period. When a site task is configured with periodic assignments and has "multiple execution" enabled, it can generate multiple sessions for the same occurrence date.

API Structure Changes

The API has evolved to support this functionality:

  1. session: deprecated (singular) - Returns the most recent session or the only session for non-periodic tasks. This field is now.
  2. sessions: current (plural) - Returns all sessions from the same occurrence date. For non-periodic tasks, this contains the same data as the deprecated session field.

Session Sequencing

To track the sequence of multiple sessions, the system uses:

  • first_visit_id - Points to where the sequence began (NULL for standalone sessions)
  • previous_visit_id - Links to the immediately preceding session (0 for standalone sessions). This attribute defaults to 0 instead of NULL because of MySQL indexing limitations.

sessions1.png

Configuration Requirements

For a site task to have multiple sessions, it must be:

  • Configured as a periodic assignment
  • Have "multiple execution" enabled

The sessions[] array will only contain multiple items when the task is executed multiple times on the same occurrence date, which is only possible with periodic assignments that have multiple execution capability enabled.

An example:

session 2.png

This periodic Site Task is configured to be executed multiple times. The label PERIODIC: 3/5 indicates that this was executed 3 times on Thursday the 30th.

It can still be performed 2 more times either the same day or until the end of the Month.

If we look at this occurrence and then compare session and sessions relations to understand the difference.

GET /rest/v1/site-task-occurrences/20251030149?include=sessions

{
    "meta": {
        "request": [
            "site-task-occurrences",
            "20251030149"
        ],
        "security": {
            "granted": true,
            "requested": "admin:site-task-occurrences:view",
            "grantedBy": "admin:*",
            "scope": null
        },
        "debug": null,
        "resource": "site-task-occurrences"
    },
    "data": {
        "id": 20251030149,
        "occurrenceDate": "2025-10-30T00:00:00+00:00",
        "customId": "GW-PERIODIC-MULTI-MONTHLY",
        "schedule": 149,
        "taskType": 3,
        "description": "GW-PERIODIC-MULTI-MONTHLY",
        "instructions": "",
        "status": "COMPLETED",
        "client": 17,
        "priceTier": null,
        "position": 2140917757,
        "checkpointTour": null,
        "reportTemplate": 2725,
        "type": "RECURRING",
        "beginServiceDate": "2025-10-01T00:00:00+00:00",
        "endServiceDate": null,
        "rangeStartTime": "14:00:00",
        "rangeEndTime": "18:00:00",
        "durationMinutes": 30,
        "dayOfWeekStart": null,
        "dayOfWeekEnd": null,
        "frequency": "WEEKLY",
        "timeZone": "America/Toronto",
        "rangeStartedDateTime": "2025-10-30T14:00:00-04:00",
        "rangeEndedDateTime": "2025-10-30T18:00:00-04:00",
        "session": 102,
        "taskSiteInstruction": null,
        "exception": null,
        "isPeriodic": true,
        "isPeriodicOptional": false,
        "isPeriodicMultipleExecution": true,
        "periodicCompleted": 3,
        "periodicTotal": 5,
        "sessions": [
            {
                "report": 4032,
                "status": "COMPLETED",
                "startedOn": "2025-10-30T19:59:01+00:00",
                "endedOn": "2025-10-30T19:59:26+00:00",
                "effectiveDuration": 0,
                "id": 100
            },
            {
                "report": 4033,
                "status": "COMPLETED",
                "startedOn": "2025-10-30T20:00:32+00:00",
                "endedOn": "2025-10-30T20:01:09+00:00",
                "effectiveDuration": 1,
                "id": 101
            },
            {
                "report": 4034,
                "status": "COMPLETED",
                "startedOn": "2025-10-30T20:01:17+00:00",
                "endedOn": "2025-10-30T20:01:50+00:00",
                "effectiveDuration": 1,
                "id": 102
            }
        ]
    }
}

GET /rest/v1/site-task-occurrences/20251030149?include=session
(Only emits the most recent of the 3 sessions)

{
    "meta": {
        "request": [
            "site-task-occurrences",
            "20251030149"
        ],
        "security": {
            "granted": true,
            "requested": "admin:site-task-occurrences:view",
            "grantedBy": "admin:*",
            "scope": null
        },
        "debug": null,
        "resource": "site-task-occurrences"
    },
    "data": {
        "id": 20251030149,
        "occurrenceDate": "2025-10-30T00:00:00+00:00",
        "customId": "GW-PERIODIC-MULTI-MONTHLY",
        "schedule": 149,
        "taskType": 3,
        "description": "GW-PERIODIC-MULTI-MONTHLY",
        "instructions": "",
        "status": "COMPLETED",
        "client": 17,
        "priceTier": null,
        "position": 2140917757,
        "checkpointTour": null,
        "reportTemplate": 2725,
        "type": "RECURRING",
        "beginServiceDate": "2025-10-01T00:00:00+00:00",
        "endServiceDate": null,
        "rangeStartTime": "14:00:00",
        "rangeEndTime": "18:00:00",
        "durationMinutes": 30,
        "dayOfWeekStart": null,
        "dayOfWeekEnd": null,
        "frequency": "WEEKLY",
        "timeZone": "America/Toronto",
        "rangeStartedDateTime": "2025-10-30T14:00:00-04:00",
        "rangeEndedDateTime": "2025-10-30T18:00:00-04:00",
        "taskSiteInstruction": null,
        "exception": null,
        "isPeriodic": true,
        "isPeriodicOptional": false,
        "isPeriodicMultipleExecution": true,
        "periodicCompleted": 3,
        "periodicTotal": 5,
        "session": {
            "report": 4034,
            "status": "COMPLETED",
            "startedOn": "2025-10-30T20:01:17+00:00",
            "endedOn": "2025-10-30T20:01:50+00:00",
            "effectiveDuration": 1,
            "id": 102
        }
    }
}

 

Was this article helpful?
0 out of 0 found this helpful

Articles in this section