Rejecting an existing task

Intended Use

Send an e-mail to a user with a link to a task that should be rejected directly - e.g. from some workflow system.

You also have the opportunity to cancel a task directly via a link without opening the iCL Filler and searching for it. For this, you can use the “canceltask” deep link API. To use that, you need to provide the external ID of the task that must be rejected.

The URL with the cancel action has the following format:

https://filler.opti-q.com?$action=canceltask&externalId=<externalid_of_task>

Furthermore you can specify two optional parameters:

• Normally, you cannot reject a task if the workbook settings restrict that. However, you can force the rejection by appending the force parameter (without value) to the deep link.

  https://filler.opti-q.com?$action=canceltask&externalId=<externalid_of_task>&force

• With responseUrl you can specify a URL where the user will be redirected after the rejection attempt. If you specify a responseUrl, the result of the cancel action will be forwarded there. The result is always a URL-encoded JSON that contains either an empty result, if the rejection was successful, or an error message if the task could not be canceled - this can happen if the provided external ID was not found, or when the rejection of the task was not allowed in the workbook settings and the action was not forced.

  The result will look like this if the reject attempt returned with an error: { "error": " Error message." }

  And in case of success: { "result": "" }

  The URL with the cancel action and a response URL has the following format:

  https://filler.opti-q.com?$action=canceltask&externalId=<externalid_of_task>&force&responseUrl=<response_url>

  There are two ways to receive the result of the rejection. If the provided response URL contains the placeholder __response__, then this will be replaced by the encoded JSON. If that is not the case, so the placeholder is not provided in the URL, a new parameter will be appended to the responseURL named response: the value of this parameter is the URL-encoded JSON.

  For example, if the response URL is: example://cancelresult=__response__ and the rejection was successful, then the response will be: example://cancelresult=%7B%20%22result%22%3A%20%22%22%20%7D. If the response URL has the following format: example://something=some_value and the task cannot be rejected, the response will be: example://something=some_value&response=%20%7B%20%22error%22%3A%20%22%20Error%20message.%22%20%7D.

For example, to cancel the task TASK_0001, the URL would look like one of these:

https://filler.opti-q.com?$action=canceltask&externalId=TASK_0001

https://filler.opti-q.com?$action=canceltask&externalId=TASK_0001&force

https://filler.opti-q.com?$action=canceltask&externalId=TASK_0001&responseUrl=example%3A%2F%2Fsomething%3D__response__

https://filler.opti-q.com?$action=canceltask&externalId=TASK_0001&force&responseUrl=example%3A%2F%2Fsomething%3D__response__

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=canceltask\&externalId=TASK_0001&force&responseUrl=test%3A%2F%2Fsomething%3D__response__"

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