2. Retrieving changed tasks
In many cases, you will want to get the latest information of iCL Portal tasks and inspections in your legacy system. A naive approach would be to use the task get endpoint to poll for changes of every task that is not yet marked as completed or cancelled in your system.
While this may technically work, it does not scale well. Imagine the number of unnecessary requests you would have to make to the iCL Portal API to get the latest information of all your tasks.
Instead, you can use the task changes endpoint to get a list of all tasks that have changed since a given timestamp.
This API is specifically designed to be used for incremental updates.
For this, every time you ask it for changes, you need to provide a changeToken.
1. Getting the first page of tasks/inspections
The first time you call this endpoint, you will not yet have a changeToken.
In this case, it will give you all tasks/inspections since day 1.
GET https://dev.iclportal.com/api/services/custom/externalTask/GetChanges HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
However, in order to not overwhelm the database, it only returns 500 changes at a time.
To get the next 500 changes, you need to provide the nextChangeToken that you got in the response.
Response gives us the tasks (as expected) but includes a nextChangeToken and nextLink.
{
"result": {
"results": [
{
"id": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
"inspectionId": null,
"externalId": "TSK___000001",
"title": "Task 000000",
"workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
"workbookTitle": "test iWorkbook",
"workbookVersionCode": 52,
"assignedUserId": 4,
"assignedUserName": "antoine gadget",
"description": null,
"startDate": null,
"dueDate": null,
"state": 1,
"isSelfAssignable": true,
"workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
"workAreaTitle": "test",
"isPublished": true,
"actualStart": null,
"actualEnd": null,
"sentDate": null,
"hasTask": true,
"lastModificationTime": "2022-10-21T13:16:23.583Z",
"inspectedItems": null,
"isDeleted": false // <-- you also get deleted tasks/inspections!
},
... many many more... (500 total)
],
"nextChangeToken": "AAAAAAAFpYA",
"nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYA"
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
As this endpoint is for getting any incremental changes, it also returns deleted tasks, so that you can remove them from your system accordingly.
2. Getting the next page of changed tasks/inspections
So the request to get the next changes, just uses the change token provided by the previous response.
GET https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYA HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
... which gives us the next page.
{
"result": {
"results": [
{
"id": "71c8fc87-31da-4989-9662-3faf95ce893b",
"inspectionId": null,
"externalId": "TSK___000501",
"title": "Task 000010",
"workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
"workbookTitle": "test iWorkbook",
"workbookVersionCode": 52,
"assignedUserId": 4,
"assignedUserName": "antoine gadget",
"description": null,
"startDate": null,
"dueDate": null,
"state": 1,
"isSelfAssignable": true,
"workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
"workAreaTitle": "test",
"isPublished": true,
"actualStart": null,
"actualEnd": null,
"sentDate": null,
"hasTask": true,
"lastModificationTime": "2022-10-21T13:16:23.593Z",
"inspectedItems": null,
"isDeleted": false // <-- you also get deleted tasks/inspections!
},
{
"id": "fcb40e9c-1ee2-4c94-af49-7978e0f23214",
"inspectionId": null,
"externalId": "TSK___000502",
"title": "Task 000011",
"workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
"workbookTitle": "test iWorkbook",
"workbookVersionCode": 52,
"assignedUserId": 4,
"assignedUserName": "antoine gadget",
"description": null,
"startDate": null,
"dueDate": null,
"state": 1,
"isSelfAssignable": true,
"workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
"workAreaTitle": "test",
"isPublished": true,
"actualStart": null,
"actualEnd": null,
"sentDate": null,
"hasTask": true,
"lastModificationTime": "2022-10-21T13:16:23.593Z",
"inspectedItems": null,
"isDeleted": false // <-- you also get deleted tasks/inspections!
}
],
"nextChangeToken": "AAAAAAAFpYg",
"nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYg"
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
This time, there are only 2 results - so not the full page size of 500. That already indicates, that this is the last page (i.e. there are no more changes)
3. Detecting the last page (no more changed inspections/tasks)
However, we can still query using the latest changeToken AAAAAAAFpYg
GET https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYg HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
... which will give us an empty results array in the response
{
"result": {
"results": [],
"nextChangeToken": "AAAAAAAFpYg",
"nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYg"
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
As there are no more changes, the system simply returns the latest change available, which is usually the very same change token we just used in the request.
However, you can use this mechanism to get straight to the last page of changed inspections/tasks by using the highest possible change token __________8
This comes in handy, if you only want to start for getting changes from now on and do not wish to go through all the historical changes.