Skip to main content

Creating a new task

Intended Use

Create a task offline - this is for very advanced scenarios only.

Normally, all the tasks for your users will already exist beforehand, having been created on iCL Portal by using the excel import, the user interface, or the REST interface. However, there may be some rare cases, where a task does not yet exist, and you want to create it on iCL Filler offline. One example would be: Your inspectors manage their work in an external app. While they are at a customers site, they spot an asset/equipment/item which needs to be inspected, but they do not find a suitable task. So once they have created it in their external app, they would like to open it on iCL Filler. But, of course, it does not yet exist in iCL Filler. So to overcome this, you just prepare a “create task link” in the external app. Once the user clicks this link, iCL Filler opens and creates the task automatically.

The URL has the following format:

https://filler.opti-q.com/api/tasks/openorcreate?p=<url_encoded_json_document>

or

https://filler.opti-q.com?$action=openorcreatetask&p=<url_encoded_json_document>

Basically, this API functionally equivalent to the Create Task API of the iCL Portal REST interface: You can create a task and pass along items that need to be inspected and also custom data, which should be used to prefill checklists for the user. The main difference is, that we need to pack this information (represented by a JSON document) into this URL as this is the only information that iCL Filler will receive. In order to do so, we url encode the JSON document and pass it as query string parameter p of the URL.

NameTypeRequired?Description
externalIdstringrequiredHas to be a unique identifier provided by the external application.
titlestringrequiredThe title of the task.
teamNamestringrequiredThe name of the team to associate the task with. In order for this to work, team names have to be unique.
workbookNamestringrequiredThe name of the workbook that belongs to this task. In order for this to work, workbook names must be unique.
assignedUserNamestringrequiredThe 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.
descriptionstringAn optional description of the task.
startDatestringAn 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
duedatestringAn optional duedate 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
itemsToInspectstring[]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)
<any other property>string/number/booleanIf 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:

  • 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)

An example JSON would look like this:

{
"externalId": "TASK_0001",
"title": "New Task",
"teamName": "team01",
"workbookName": "physical_inspection",
"assignedUserName": "Peter Parker",
"description": "Description",
"startDate": "2015-12-28T23:00:00.000Z",
"dueDate": "2015-12-29T23:00:00.000Z",
"category": "severe_defects",
"itemsToInspect": []
}

Notice the custom field “category”. Whenever iCL Filler creates an inspection based on that task (or a new checklist within that inspection), it will try to find a checklist field “category” and if it encounters one, prefill it with “severe_defects”. Also notice, that we did not pass along any “itemsToInspect”. The main difference between this API and the iCL Portal REST interface that if we would do this here, and those items do not exist, iCL Filler would actually create them. Now in order to pass this information along with the url, you need to url-encode it first. If you are not a programmer, you can use the following useful website: https://meyerweb.com/eric/tools/dencoder/

In our case, it would look like this:

%7B%0A%09%22externalId%22%3A%20%22TASK_0001%22%2C%0A%09%22title%22%3A%20%22New%20Task%22%2C%0A%09%22teamName%22%3A%20%22team01%22%2C%0A%09%22workbookName%22%3A%20%22physical_inspection%22%2C%0A%09%22assignedUserName%22%3A%20%22Perter%20Parker%22%2C%0A%09%22description%22%3A%20%22Description%22%2C%0A%09%22startDate%22%3A%20%222015-12-28T23%3A00%3A00.000Z%22%2C%0A%09%22dueDate%22%3A%20%222015-12-29T23%3A00%3A00.000Z%22%2C%0A%09%22category%22%3A%20%22severe_defects%22%2C%0A%09%22itemsToInspect%22%3A%20%5B%5D%0A%7D%0A

So the resulting link looks like the following:

https://filler.opti-q.com?$action=openorcreatetask&=%7B%0A%09%22externalId%22%3A%20%22TASK_0001%22%2C%0A%09%22title%22%3A%20%22New%20Task%22%2C%0A%09%22teamName%22%3A%20%22team01%22%2C%0A%09%22workbookName%22%3A%20%22physical_inspection%22%2C%0A%09%22assignedUserName%22%3A%20%22Perter%20Parker%22%2C%0A%09%22description%22%3A%20%22Description%22%2C%0A%09%22startDate%22%3A%20%222015-12-28T23%3A00%3A00.000Z%22%2C%0A%09%22dueDate%22%3A%20%222015-12-29T23%3A00%3A00.00Z%22%2C%0A%09%22category%22%3A%20%22severe_defects%22%2C%0A%09%22itemsToInspect%22%3A%20%5B%5D%0A%7D%0A

note

When using this offline API, you cannot create a task for any other user but only the one that is currently logged in.

Example

Peter is logged in on iCL Filler, but the link tries to create a task for Sabrina. iCL Filler will simply ignore the assigned user Sabrina and create the task for Peter anyways.

note

In case you specify one or more item ids in itemsToInspect, iCL Filler tries to find these first, before it actually creates them. If it needs to create them, it has to somehow choose a content type. As this is not deducable from a simple ID, it will use the first inspectable content type that it finds in the workbook.

note

If you have the Android SDK installed on your computer, and set up developer mode on your device, you can use the ADB command shell to test this feature.

For this, simply start ADB and run the command like so:

adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://filler.opti-q.com?\$action=openorcreatetask\&p=%7B%0A%09%22externalId%22%3A%20%22TASK_0001%22%2C%0A%09%22title%22%3A%20%22New%20Task%22%2C%0A%09%22teamName%22%3A%20%22team01%22%2C%0A%09%22workbookName%22%3A%20%22physical_inspection%22%2C%0A%09%22assignedUserName%22%3A%20%22Perter%20Parker%22%2C%0A%09%22description%22%3A%20%22Description%22%2C%0A%09%22startDate%22%3A%20%222015-12-28T23%3A00%3A00.000Z%22%2C%0A%09%22dueDate%22%3A%20%222015-12-29T23%3A00%3A00.00Z%22%2C%0A%09%22category%22%3A%20%22severe_defects%22%2C%0A%09%22itemsToInspect%22%3A%20%5B%5D%0A%7D%0A"

Notice that we had to escape the special characters $ and & with a backslash \ as this is required by ADB unfortunately.

Bypass the contentitem-creation since the filtered synchronization feature​

Since the filtered synchronization feature, not all contentitems are stored locally. When the contentitems are not stored locally yet, then the contentitems are created when we specify some itemsToInspect.

When the contentitems already exist on the iCL.Portal, then we would have duplicate items.

It is possible to bypass the creation of the duplicate and blank contentitems by appending an action to the deeplink: &createContentItems=false. Instead of creating duplicate items, the Filler shows a message which tells the inspector to sync again and that some contentitem-ids are not synchronized yet. When the action is not specified then the value defaults to true. The action does not have to be encoded or decoded.

The URL with the action has the following format:

https://filler.opti-q.com/api/tasks/openorcreate?p=<url_encoded_json_document>&createContentItems=false

or

https://filler.opti-q.com?$action=openorcreatetask&p=<url_encoded_json_document>&createContentItems=false

An example JSON with itemsToInspect would look like this:

{
    "externalId": "TASK_0001",
    "title": "New Task",
    "teamName": "team01",
    "workbookName": "physical_inspection",
    "assignedUserName": "Perter Parker",
    "description": "Description",
    "startDate": "2015-12-28T23:00:00.000Z",
    "dueDate": "2015-12-29T23:00:00.000Z",
    "category": "severe_defects",
    "itemsToInspect": ["externalId1", "externalId2"]
}

So the resulting link with the action looks like the following:

https://filler.opti-q.com?\$action=openorcreatetask\&p=%7B%0A%22externalId%22%3A%20%22TASK_0001%22%2C%0A%22title%22%3A%20%22New%20Task%22%2C%0A%22teamName%22%3A%20%22team01%22%2C%0A%22workbookName%22%3A%20%22physical_inspection%22%2C%0A%22assignedUserName%22%3A%20%22Perter%20Parker%22%2C%0A%22description%22%3A%20%22Description%22%2C%0A%22startDate%22%3A%20%222015-12-28T23%3A00%3A00.000Z%22%2C%0A%22dueDate%22%3A%20%222015-12-29T23%3A00%3A00.000Z%22%2C%0A%22category%22%3A%20%22severe_defects%22%2C%0A%22itemsToInspect%22%3A%20%5B%22externalId1%22%2C%20%22externalId2%22%5D%0A%7D&createContentItems=false