Consume and Submit an Activity

Overview

Normally it would be expected that users will use the TilliT Desktop or Mobile application to check and complete activities. In advanced scenarios where all the data required to complete the activity is located somehwere digitally, the TilliT API can be used to consume the activity and fill it out with the relevant information.

Find an Active Activity

The TilliT API has the GET:/activity/activity-instances/user endpoint to find all activities that are valid for the current logged in user. It uses the Authorization header to identify who the user is and limit what activtiies they have been allocated to see. An example of the query can be seen below

GET:/activity/activity-instance/user?status.in=ACTIVE&site.equals=1&size=100&sort=createdAt,DESC

The response object will be an array of activity instances available for the user. Identify the activity you want to complete via the activityKey field and continue.

Claim an Activity

An activity must be claimed before it can be submitted. To claim, use the claim endpoint below with the example body. The response includes the updated activity instance.

POST:/activity/activity-manager/claim
body: {
  "activityInstanceId": 52
}

Now that the activity is claimed, we need to find the items that the activity instance wants us to complete. Using the id of the instance, use the following endpoint

GET:/activity/activity-manager/form/52

This will return the activity-instance again, but this time a new field called formItems is available. Inside this field is an array of all activity-items that have been create for the activity instance.

Submit an Activity

To complete an activity, update each formItem with the appropriate value for each ItemType. Each item is submitted as a flat structure as per below. Here is a guide

name: string,
itemKey: string,
stringValue: string,
numericValue: number,
booleanValue: boolean,
dateValue: string,
datetimeValue: Date,
toleranceValue: any,
upperLimit: string,
lowerLimit: string,
target: string,
pass: boolean,
toleranceType: ActivityItemToleranceType,
processVariable: ProcessVariableEntity,
attribute: AttributeEntity,
itemType: ActivityItemType,
images: string[],
eventReason1: string,
eventReason2: string,
eventReason3: string,
eventReason4: string,
downtimeType: 'PLANNED' | 'UNPLANNED'

The required fields change depending on the Item Data Type you are providing information for, below is another guide for what each Item Data Type needs.

stringValue - DATE, DATETIME, BARCODE, CALCULATED, STRING, OPTION, MATERIAL

booleanValue - BOOLEAN,

numericValue - CALCULATED, NUMBER, EDGE_DATA

dateValue - DATE

datetimeValue - DATETIME

eventReason - EVENT_REASON

Now it is time to submit the activity to the API. To do this, we will use a POST:/activity/activity-manager/submit request with the payload body structure as per the following

{
  id: number,                 //ID of activity instance
  skipped: boolean,           //True if activity is skipped (will not save formItems)
  comments: string,           //Attach any comments from the user
  instanceItems: formItem[]   //An array of formItems, structured as shown above
}