Tasks

In iCL, whenever you need to inform a user, that (s)he has to perform an inspection/check/activity, you can create a task. A task defines which user (or team) is assigned, what workbook is to be used and can carry along custom data. Should any workbook of the inspection contain a field with the same name and a suitable type, the custom data will be used to fill it in once the inspection starts. Therefore, tasks are a powerful way to plan your teams activities.

• For an in-depth explanation of tasks, see the documentation.
• For a first walkthrough on how to use the task API, see the walkthrough here

In order to create, update or delete a task in iCL Portal, the following REST service can be used. Endpoint: /api/services/custom/externaltask

Task states

During its lifetime, a task goes through different states (see the task lifecycle). The endpoints /get and /getall / /getchanges return the state differently:

State	state returned by /get	state returned by /getall and /getchanges
New (no user assigned yet)	"New"	0
Assigned	"Assigned"	1
Active (the user started the inspection)	"Active"	2
Completed	"Closed"	3
Canceled	"Canceled"	4
Removed	"Removed"	5

1. Querying tasks

Url: /getall HTTP method: GET Example:

GET https://dev.iclportal.com/api/services/custom/externaltask/getall HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Example 2: querying all tasks that were modified since a specific point in time, sorts them by their modification and returns only the first 20 of them:

GET https://dev.iclportal.com/api/services/custom/externaltask/getall?$filter=LastModificationTime+ge+datetime%272016-06-19T01:00:00%27&$inlinecount=allpages&$orderby=LastModificationTime+desc&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Parameters: This is an ODATA 3.0 Endpoint allowing you to query the tasks in the system.

The response is not wrapped in a result object. It contains the tasks in results, the total number of matching tasks in __count and, only if there are more tasks, a link to the next page in __next. A page contains at most 500 tasks.

{
  "results": [
    {
      "id": "7cddb148-c113-4b23-9263-25cc479c88d8",
      "externalId": "<ID_PROVIDED_BY_EXTERNAL_APPLICATION>",
      "title": "New Task",
      "workbookId": "6f9df8f3-1f69-4258-99ad-c1144219bc7c",
      "workbookTemplateId": "0d5b2a7e-3c55-4f1b-9a8e-2f6f1c0f4b11",
      "workbookTitle": "physical_inspection",
      "workbookVersionCode": 1,
      "assignedUserId": 4,
      "assignedUserName": "Alexander Marek",
      "description": "Description",
      "startDate": "2015-12-28T23:00:00Z",
      "dueDate": "2015-12-29T23:00:00Z",
      "state": 1,
      "isSelfAssignable": false,
      "workAreaId": "58b6081a-1154-4ec2-a5a8-271a245eb4e0",
      "workAreaTitle": "team01",
      "isPublished": true,
      "actualStart": null,
      "actualEnd": null,
      "sentDate": null,
      "hasTask": true,
      "inspectionId": null,
      "lastModificationTime": "2016-06-19T09:42:18.93Z",
      "inspectedItems": null,
      "category": "severe_defects"
    }
  ],
  "__count": 1
}

• state is returned as a number (see task states).
• assignedUserName contains the display name (first and last name) of the assigned user, whereas /get returns the user name.
• The result contains only the tasks you are allowed to see: published tasks with the permission Tasks.View, also unpublished tasks with Tasks.ViewUnpublished, and the published tasks that are assigned to you or (with Tasks.ViewAssigned) self-assignable in your team.

tip

you can use all the attributes of the returned json objects to create a query. However, due to the ODATA specification, you must uppercase them in the query. As this is a convention in JSON and the JavaScript world, our results are returned with the attribute names lowercased.

Example: You get a task like:

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task", …}

As you can see, the "externalId" attribute is starting with a lowercased letter. If you, however, query the ODATA endpoint using "externalId", you need to uppercase its first letter:

/getall?$filter=ExternalId+eq+….

note

dynamic properties are not available in this interface

2. Creating a new task

Url: /post HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externaltask/Post HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00.000Z","dueDate":"2015-12-29T23:00:00.000Z","category":"severe_defects", "itemsToInspect":["<ID_OR_EXTERNALID_OF_EXISTING_ITEM>"]}

Parameters: The parameters are provided in the HTTP request body using a JSON object.

The externalTask object has the following fields:

Name	Type	Required?	Description
externalId	string	required	Has to be a unique identifier provided by the external application (max. 200 characters)
title	string	required	The title of the task (max. 200 characters)
teamName	string		The name (or id) of the team to associate the task with. For this to work, team names must be unique. If omitted, the team is determined from the workbook: if the workbook belongs to exactly one team, that team is used. Otherwise, the teams in which the assigned user is an inspector are considered and finally the default team of the assigned user. If no unique team can be determined, the request fails.
workbookName	string	required	The name or title of the workbook that belongs to this task. For this to work, workbook names must be unique. The workbook must be associated with the team.
assignedUserName	string	required unless isSelfAssignable is true	The unique username of the user, which has to perform this task. (i.e. the inspectors username) You can also specify the inspectors e-mail address. The user must be an inspector of the team.
isSelfAssignable	boolean		Default: false. If true, the task does not need an assigned user: any inspector of the team can start it.
isPublished	boolean		Default: true. If false, the task is created unpublished and is not visible to the assigned user until it is published.
description	string		An optional description of the task
startDate	string		An optional startdate for the task. Note: dates must be provided as UTC and as valid ISO 8601 date string. Format: yyyy-MM-ddTHH:mm:ss.fffZ Example: 2015-12-29T23:00:00.000Z
dueDate	string		An optional duedate for the task. Must not be earlier than startDate. Note: dates must be provided as UTC and as valid ISO 8601 date string. Format: yyyy-MM-ddTHH:mm:ss.fffZ Example: 2015-12-29T23:00:00.000Z
itemsToInspect	string[]		If a workbook is created to inspect a specific content type (e.g. a building), then you can specify the task which building has to be inspected. Provide an array of strings, where each value can be either the externalid of a content item or its internal contentitemid (the id that you get from the api/content/<contenttypename> api)
itemToInspect	string		Alternative to itemsToInspect for exactly one item. Specify either itemToInspect or itemsToInspect, not both.
any other property	string/number/boolean		If a field does not match any of the previously defined names, it is considered a custom property of the task and stored in iCL Portal (see field "category" in the following example) Note: 1) dates must be provided as UTC and as valid ISO 8601 date string. Format: yyyy-MM-ddTHH:mm:ss.fffZ Example: 2015-12-29T23:00:00.000Z 2) Numbers must be provided as valid JSON numbers: Example: { "numberfield":33.2 } 3) Booleans must be provided as valid JSON boolean values Example: { "istrue" : true }

Remarks:

• Unless you set isPublished to false, all tasks added via this interface will automatically be published.
• The json object can contain any other field which will be stored by iCL Portal as custom property of the given task. (see field "category" in the example above)
• A task with the same externalId must not exist yet. Use /put to change an existing task.
• Required permission: Tasks.Create for the team of the task.

If all goes well, the server will return a 200 OK response containing the id of the new task:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{"result":{"id":"7cddb148-c113-4b23-9263-25cc479c88d8"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

The result object

Name	Type	Description
success	boolean	Specifies, if the request was successful. If "false" is returned, some error has occurred.
result	string/number/boolean/object	Contains an arbitrary result object given the service returns any result.
error	object	If any error has occurred, such as validation errors, the success field will indicate "false" and the error field will contain a JSON object containing further details.
unAuthorizedRequest	Boolean	Returns "true" if the user did not have enough permissions to execute the service method.

If the task is not valid, the server responds with 400 Bad Request along with an error object, encoded as JSON in the response body. In this example, the server complains, that the task did not have a title specified, although it is a required field:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1

{"success":false,"result":null,"error":{"code":0,"message":"Your request is not valid!","details":"The following errors were detected during validation.\r\n - 'Title' should not be empty.\r\n","validationErrors":[{"message":"'Title' should not be empty.","members":["title"]}]},"unAuthorizedRequest":false}

Other errors, such as a workbook, team or user that cannot be found or a task with the same externalId that already exists, are returned with HTTP status 500 and an error object containing a message:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{"success":false,"result":null,"error":{"code":0,"message":"No workbook with the name or title 'EN-ContainerInspection' could be found","details":null,"validationErrors":null},"unAuthorizedRequest":false}

If you do not have the required permission, the server responds with 403 Forbidden (401 Unauthorized if the access token is missing or invalid).

The error object

Name	Type	Description
code	number	For future use
message	string	A general user-readable error message title
details	string	A general user-readable error message
validationErrors	array	Contains validationError objects for each invalid field.

The validationError object

Name	Type	Description
code	number	For future use
message	string	A user-readable message explaining why a field was not valid.
members	string	A list of fields that this error message belongs to.

3. Reading a task

Url: /get

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externaltask/get HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"}

The server will respond with a 200 OK containing a result object in the response body:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"result":{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","workbookVersionCode":1,"workbookTemplateId":"0d5b2a7e-3c55-4f1b-9a8e-2f6f1c0f4b11","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00Z","dueDate":"2015-12-29T23:00:00Z","completedDate":null,"sentDate":null,"finalReportCount":null,"state":"Active","inspectionId":"<some uuid>","itemsToInspect":["building01"],"category":"severe_defects"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

The returned fields are the same ones that are sent when creating or updating a task, with these exceptions:

Name	Type	Description
state	string	The current state of the task. This can be either: "New", "Assigned", "Active", "Closed", "Canceled" or "Removed". A task is "New" while it has no assigned user (e.g. a self-assignable task), and "Assigned" as soon as a user is assigned. See task states.
inspectionId	string	Once a user actually starts to perform the task, an inspection is created which all collected data (answers, pictures, reports, …) is associated with.
workbookVersionCode	number	The version of the workbook that is used by the task.
workbookTemplateId	string	The id of the workbook template (identical for all versions of a workbook).
completedDate	string	The date the inspection was completed. null as long as it is not completed.
sentDate	string	The date the inspection was sent, i.e. completed and all its final reports were generated. null as long as it has not been sent.
finalReportCount	number	The number of final (non-draft, non-deleted) reports that existed at the moment the inspection was sent. It is null while the inspection has no sentDate (i.e. as long as it has not been sent). Use it as a completeness check when retrieving the final reports of a sent inspection.

assignedUserName contains the user name of the assigned user.

Required permission: Tasks.View (Tasks.ViewUnpublished for unpublished tasks) for the team of the task. If no task with the given externalId exists, the server responds with HTTP status 500 and an error object.

4. Editing a task

Url: /put

HTTP method: PUT

Editing a task works the same way as creating a task. Only the HTTP method and URL differ. The task is identified by its externalId.

Note the following differences:

• teamName is required.
• A task can only be edited while its state is "New" or "Assigned". Otherwise, the server responds with an error.
• The request replaces the task: fields you omit are reset. For example, an omitted description or dueDate is cleared, omitted custom properties and items to inspect are removed and an omitted isPublished is set to true. Therefore, always send all fields of the task.
• Required permission: Tasks.Edit for the team of the task.

Example:

PUT https://dev.iclportal.com/api/services/custom/externaltask/Put HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/plain, */*
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00.000Z","dueDate":"2015-12-29T23:00:00.000Z","category":"severe_defects", "itemsToInspect":["building01"]}

The server will respond with a 200 OK containing an empty result object ("result":{}).

5. Deleting a task

Allows to delete tasks whose state is "New", "Assigned" or "Canceled". As soon as a user starts to perform a given task ("Active"), it is not deletable anymore. If a task is deleted, its inspection (if any) is deleted as well.

Url: /delete

HTTP method: DELETE

Example:

DELETE https://dev.iclportal.com/api/services/custom/externaltask/delete  HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

the deleteTaskRequest object

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be deleted.

The server will respond with a 200 OK containing a result object in the response body. It lists the external IDs of the deleted tasks:

{"result":{"externalTaskIds":["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"]},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

Required permission: Tasks.Delete for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the tasks is in a state that does not allow deleting, the server responds with HTTP status 500 and no task is deleted.

6. Cancelling a task

When a user has already started to perform a task, it will transition to the "Active" state and not be deletable anymore. Instead it has to be cancelled.

Only "Active" tasks can be cancelled. A task that is still "New" or "Assigned" can be edited or deleted instead.

Url: /cancel

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externaltask/cancel HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

The cancelTaskRequest object

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be cancelled.

The server will respond with a 200 OK containing a result object in the response body. It lists the external IDs of the cancelled tasks in externalTaskIds.

Required permission: Tasks.Edit for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the tasks is not "Active", the server responds with HTTP status 500 and no task is cancelled.

7. Restarting a Task

When a task has been cancelled, you can re-activate it by restarting this task. (in iCL Portal, we call it "re-publish")

Note: You can only restart a "cancelled" task, otherwise the server will return an error. To also change the assigned user of a cancelled task, use /assign instead.

As soon as a task has been "restarted", it transitions from "cancelled" to the state "assigned". In this state the task can be modified and deleted.

Url: /restart

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externaltask/restart HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

The restartTaskRequest object:

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be restarted.

The server will respond with a 200 OK containing a result object in the response body

Required permission: Tasks.Publish for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the tasks is not cancelled, the server responds with HTTP status 500 and no task is restarted.

Sample request and response

Request:

POST https://dev.iclportal.com/api/services/custom/externalTask/restart HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...
Content-Type: application/json;charset=UTF-8

{
  "externalIds" : ["20160201_EN_1223"]
}

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1

{"result":{"externalTaskIds":["20160201_EN_1223"]},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

8. Getting changes of 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 this endpoint to get a list of all tasks that have changed since a given timestamp.

For a more in-depth example, see the incremental changes walkthrough.

Omit the changeToken parameter (or provide 0) to get the first page. Required permission: Tasks.View.

GET https://dev.iclportal.com/api/services/custom/externalTask/GetChanges HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....

Response gives us the tasks (as expected) but includes a nextChangeToken and nextLink that can be used to get the next 500 changed tasks/inspections. In addition to the fields returned by /getall, each entry contains isDeleted, reopenCount (how often the inspection was reopened), lastReopenDate and finalReportCount.

{
    "result": {
        "results": [
            {
                "id": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
                "inspectionId": null,
                "externalId": "TSK___000001",
                "title": "Task 000000",
                "workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
                "workbookTemplateId": "4b7c2e0a-5d1f-4f7e-8f63-1a2b3c4d5e6f",
                "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,
                "finalReportCount": null,
                "hasTask": true,
                "lastModificationTime": "2022-10-21T13:16:23.583Z",
                "inspectedItems": null,
                "reopenCount": 0,
                "lastReopenDate": 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
}

this endpoint also returns deleted tasks

As this endpoint is for getting any incremental changes, it also returns deleted tasks, so that you can remove them from your system accordingly.

Directly get to the last page

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.

9. Reopening a Task

Once a task is completed, the inspection with all its data cannot be edited by the user anymore. Reopening a task sets its state back to "Active", so the user can change the contents of the inspection again.

Note: You can only reopen completed tasks ("Closed"), otherwise the server will return an error. When a task is reopened, its completed and sent dates are cleared, the reports of its inspection are deleted (they are generated again when the inspection is completed the next time) and its reopenCount is increased.

Url: /reopen

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/Reopen HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

The reopenTaskRequest object

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be reopened.
skipReopenCountFieldEvaluation	boolean		Default: false. By default, reopening re-evaluates the fields of the workbook that count the reopenings. Set this to true to skip that re-evaluation.

The server will respond with a 200 OK containing a result object that lists the external IDs of the reopened tasks in externalTaskIds.

Required permission: Tasks.Reopen for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the tasks is not completed, the server responds with HTTP status 500 and no task is reopened.

10. Assigning a Task

Allows to assign a task to another user or to move it to another team. Unlike /put, this also works for "Active" and "Canceled" tasks. This is useful, for example, to delegate an active task to another inspector.

Url: /assign

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/Assign HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalId": "<ID_PROVIDED_BY_EXTERNAL_APPLICATION>", "assignedUserName": "alexander.marek"}

The assignTaskRequest object

Name	Type	Required?	Description
externalId	string	required	The external ID of the task.
assignedUserName	string	required unless isSelfAssignable is given	The username or e-mail address of the new assigned user. The user must be an inspector of the (new) team.
isSelfAssignable	boolean	required unless assignedUserName is given	Set to true to make the task self-assignable, so any inspector of the team can start it. If you do not specify assignedUserName at the same time, the currently assigned user is removed (not possible once an inspection was started for the task, e.g. for "Active" tasks).
teamName	string		The name of the team to move the task to. The workbook of the task must be associated with that team. If omitted, the task stays in its team.

Remarks:

• If the task was "Canceled", its state is set back to "Assigned" (or "New" if it has no assigned user). The state of an "Active" task does not change.
• A published task must either have an assigned user or be self-assignable.
• Required permission: Tasks.Edit for the team of the task. If the task cannot be found (or you lack the permission), the server responds with 403 Forbidden. Other errors (e.g. a completed task or an unknown user) are returned with HTTP status 500.

The server will respond with a 200 OK containing the external ID of the task:

{"result":{"externalTaskId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

11. Publishing a Task

Tasks that are created with isPublished set to false are not visible to the assigned user. Publishing makes them visible.

Url: /publish

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/Publish HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

The publishTaskRequest object

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be published.

Only unpublished tasks in the state "New" or "Assigned" can be published. Tasks that are already published are ignored. The server will respond with a 200 OK containing a result object that lists the external IDs of the published tasks in externalTaskIds.

Required permission: Tasks.Publish for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the unpublished tasks is not "New" or "Assigned", the server responds with HTTP status 500 and no task is published.

12. Unpublishing a Task

Unpublishing tasks makes them invisible to their assigned users.

Url: /unpublish

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/UnPublish HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

The unpublishTaskRequest object

Name	Type	Required?	Description
externalIds	array	Required, min-length:1	Contains the external IDs of the tasks that should be unpublished.

Only published tasks in the state "New" or "Assigned" can be unpublished. Tasks that are already unpublished are ignored. The server will respond with a 200 OK containing a result object that lists the external IDs of the unpublished tasks in externalTaskIds.

Required permission: Tasks.Publish for the team of the task. If none of the tasks can be found (or you lack the permission), the server responds with 403 Forbidden. If any of the published tasks is not "New" or "Assigned", the server responds with HTTP status 500 and no task is unpublished.

13. Adding/Updating multiple Tasks at once

Allows to add or update multiple tasks with a single request. The tasks are identified by their externalId: if a task with this externalId exists, it is updated (like /put), otherwise it is created (like /post).

The whole batch is performed in a single transaction. If any of the tasks has an error, none of the tasks is added or updated.

Url: /postbatch

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/PostBatch HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

[
  {"externalId":"TASK-001","title":"Inspect building 1","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek"},
  {"externalId":"TASK-002","title":"Inspect building 2","teamName":"team01","workbookName":"physical_inspection","isSelfAssignable":true}
]

The request body is an array of task objects with the same fields as in /post. However, teamName is required. Updating a task is only possible while its state is "New" or "Assigned", and like /put, it replaces the task.

If all tasks were added or updated, the server responds with 200 OK and lists the tasks in Succeeded:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"Errored":[],"Succeeded":[{"ExternalId":"TASK-001","Id":"7cddb148-c113-4b23-9263-25cc479c88d8"},{"ExternalId":"TASK-002","Id":"0b7e6a3c-2d5f-4c1e-9a8b-3f4e5d6c7b8a"}]}

If any task has an error, the server responds with 400 Bad Request and lists the failed tasks along with the error message in Errored. As no task was saved, Succeeded is empty. For example, if the second task referenced the team team02, which does not exist:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{"Errored":[{"ExternalId":"TASK-002","Error":"The team 'team02' does not exist."}],"Succeeded":[]}

note

Unlike the other endpoints of this API, the response of this endpoint is not wrapped in a result object and its attribute names start with an uppercase letter.

Required permissions: Tasks.Create (new tasks) and Tasks.Edit (existing tasks) for the team of the task.

14. Adding/Updating multiple Tasks at once ignoring errors

Works like /postbatch, but if one or more tasks have an error, the valid tasks are added or updated nevertheless.

This endpoint is intended for integration scenarios with tools such as SSIS or Azure Data Factory: you can, for example, send the errors of the failed tasks per e-mail to the user in the source system, so (s)he can fix them.

Url: /postbatchforce

HTTP method: POST

Example:

POST https://dev.iclportal.com/api/services/custom/externalTask/PostBatchForce HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

[
  {"externalId":"TASK-001","title":"Inspect building 1","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek"},
  {"externalId":"TASK-002","title":"Inspect building 2","teamName":"team02","workbookName":"physical_inspection","isSelfAssignable":true}
]

If all tasks were added or updated, the server responds with 200 OK and lists the tasks in Succeeded. If any task has an error, the server responds with 400 Bad Request. Succeeded lists the tasks that were saved, Errored lists the failed ones:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{"Errored":[{"ExternalId":"TASK-002","Error":"The team 'team02' does not exist."}],"Succeeded":[{"ExternalId":"TASK-001","Id":"7cddb148-c113-4b23-9263-25cc479c88d8"}]}

Required permissions: Tasks.Create (new tasks) and Tasks.Edit (existing tasks) for the team of the task.