Querying tasks

Intended Use

You may use another app to plan your inspections. When offline, you'd like to get the latest states of tasks from iCL Filler.

Let us assume we know that several tasks already exist in iCL Filler that belong to some purchase order PO_1234. As you marked each of their tasks with a description of PO_1234 you can now easily query their current State (0..new, 1..assigned, 2..active, 3..completed, 4..cancelled) and their ExternalId(the unique identifier you assigned them). The url has the following format: https://filler.opti-q.com/api/tasks?$filter=<some-filter>&$orderby=<some-sort>&$select=<fields-to-return>&responseUlr=<response-URL> For example, to retrieve the ExternalId and State of the first 2 tasks that have a description containing PO_1234 ordering them by their ExternalId, the url would look like this: https://filler.opti-q.com/api/tasks?$filter=startswith(Description,'PO_12345')&$inlinecount=allpages&$orderby=ExternalId+asc&$top=30&$skip=0&$select=ExternalId,State&responseUrl=myexternalapp%3A%2F%2Fsomedomain%3Fresult%3D__response__"

Available fields

Name	Type	Description
Id	text	the unique id of the task
ExternalId	text	the externalid/reference
Title	text	the title shown to the user
WorkbookId	text	unique identity of the workbook
WorkbookDefinitionId	text	template id of the workbook (does not change between versions)
WorkbookVersionCode	text	the version number of the workbook
AssignedUserId	text	the id of the user that this task is assigned to
Description	text	a description of the task shown to the user
StartDate	text	when the task can be started
DueDate	text	the due date for the task.
State	number	0..new, 1..assigned, 2..active, 3..completed, 4..cancelled
IsSelfAssingnable	boolean	true if any user from the team can accept this task, false if only the assigned user can
WorkAreaId	text	the unique id of the team this task belongs to
LastModificationTime	date	the last time this task was modified (UTC)
LastModifierUserId	number	the identity of the last user that changed the task
CreationTime	date	the time this task was created
CreatorUserId	number	the identity of the user that created the task
Completed	Date	the point in time when the user/inspector completed the task (Note, this is not the sent-date which specifies when the final reports were created after completing the task.)

Handling responses

Note, that the most important parameter is the responseUrl. This must be the url-encoded deep link to your external app. Without it, iCL Filler does not know where to send the results. The response URL should specify a placeholder called __response__ for the response data so iCL Filler knows how to provide it. myexternalapp://<some-funny-name-here>?<some-parameter-name>=__response__ iCL Filler will then simply find __response__ and replace it with the url-encoded JSON response. If no placeholder is found, the response is simply appended to the response url: myexternalapp://<some-funny-name-here>?response=<url-encoded-JSON-response-data>

In case our query was successfully executed, the resulting JSON document will look like this:

{
    "result":{
        "__count":1441,
        "results":[
            {"ExternalId":"{6bcb7276-8339-42d0-8bac-96a1cfdfa96a}", "State": 1}
            {"ExternalId":"{43678ca2-ea73-4938-af04-95646eec7e93}", "State": 2}
        ]
    }
}

As you can see, it contains the data of 2 tasks (as we specified $top=2 in the url.) Furthermore, the __count field indicates how many tasks in total match your request.

In case of an error, the resulting document will just contain the error message:

{
   "error": " there was an error xyz"
}

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/api/tasks?\$filter=startswith(Description,'PO_12345')\&$inlinecount=allpages\&$orderby=ExternalId+asc\&$top=30\&$skip=0\&$select=ExternalId,State\&responseUrl=myexternalapp%3A%2F%2Fsomedomain%3Fresult%3D__response__""

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

On UWP, simply save your link in OneNote and open it from there. iCL Filler UWP should then start up and process your link.