Multi-row task execution

Indicium offers support for executing tasks for multiple rows. This means that when a task is executed via Indicium's API and this tasks needs to be executed for more than just one row, Indicium will still go through the process of Resource Staging for the task. But when in the SF is indicated that only one popup needs to be shown when multiple rows are selected, it follows that all parameters that are entered by the user are the same for all tasks. So to avoid having to execute multiple patch and commit requests with the same values, Indicium makes it possible to perform all patches and commits for all selected rows in one go and thereby makes the execution of one task for multiple rows a really fast and easy process.

1. Creating the main task resource

Multi-row task execution starts by staging a task in the context of a table record. The new resource that is created, will serve as the main task resource to which one or more child task resources can be added to execute the task for multiple records.

Request template

POST
/iam/appl/{table}({key})/{task_id}/stage

Request example

POST
/iam/appl/project(1)/task_create_subproject/stage

Response

If the request is successful, Indicium will respond with an HTTP status code 201 and a Location header that points to the newly created task resource.

201 Created
Location: /iam/appl/staged_create_subproject(#)

note

For more information about creating a resource using a context filter, see Resource Staging.

2. Adding records to the main task resource

To execute a task for multiple records, a child task resource has to be added to the main task resource for each selected record. Adding a record to the main task resource can be done by sending a POST request to the add_context endpoint of the task resource provided with the primary key value(s) of that selected record in the body of the request.

note

Records cannot be added to task resources that were staged outside the context of a table record or on an 'empty' record, e.g. through an empty_detail_ navigation property. Furthermore, although a task can be linked to multiple tables, it is not possible to add records from a different table than the context table the task is staged from.

Request template

POST 
/iam/appl/{main task resource}/add_context
{
    "pk_col1": 'abc',
    "pk_col2": 123,
    ...
}

Request example

POST
/iam/appl/staged_create_subproject(#)/add_context
{
    "project_id": 2
}

Response

If the request is successful and all validations pass, the child task resource will be added to the main task resource and the response will contain a Location header that points to the previously created main task resource.

201 Created
Location: /iam/appl/staged_create_subproject(#)

If the user is not allowed to execute the task for the selected record or if the record has already been added to the resource, the child resource will not be created and the response will contain a 4xx Client Error.

3. Patching the main task resource

Before committing the main task resource and thereby executing the task for multiple rows, it is possible to modify the created task resource by submitting one or more PATCH requests. Always keep in mind that all patched properties will be patched on both main and child task resources, just like the final commit will be done for all child resources as well.

note

After a PATCH is done, it is not possible to add more child resources to the main task resource.

Request template

PATCH 
/iam/appl/{main task resource}
{
    "col1": 1,
    "col2": 'abc',
    ...
}

Request example

PATCH
/iam/appl/staged_create_subproject(#)
{
    "name": "Subproject",
    "description": "Multi-row task execution"
}

Response

If the request is successful, Indicium will return the regular response to a PATCH request.

200 OK

note

For more information about patching a resource, see Resource Staging.

4. Committing the main task resource

When one or more child resources are added to the main task resource, the task can be executed for these multiple records by sending a POST request to the commit endpoint of the main task resource.
Indicium will check if the task can be executed for each selected record and then executes the task for each permitted row.

Request template

POST 
/iam/appl/{main task resource}/commit

Request example

POST
/iam/appl/staged_create_subproject(#)/commit

Response

If the request is successful, Indicium will respond with the regular commit response.

204 No Content

note

For more information about committing a resource, see Resource Staging.

5. Error handling

When an error occurs in one of the last stages of multi-row task execution, the process will be handled in one of the following ways:

• If the patch or commit fails on the record on which the original stage was done to create the main task resource, the response will contain a 4xx Client Error and the main task resource will remain intact. In this way the user can fix the error and try again.
• If the patch or commit fails on a record that is added to the main task resource as a child resource, the child resource in question will be removed from the task resource so the task will not be executed for that record anymore.

Let's illustrate this with an example. Consider a task is linked to the Project table. In order to execute this task for multiple records, the task is staged in the context of a specific project (say, project record with id 1), the main task resource, and two project records (with id's 2 and 3) are added as child resources to the main task resource.

Now consider that a Patch request is done on the task resource and with this request a layout procedure is triggered that changes one of the optional task parameters into a mandatory task parameter. So in this case, when a Commit request is performed before the mandatory task parameter is patched, the commit request will fail on the main task resource with a 422 Unprocessable Entity. The task resource will remain intact and the user can fix the error by patching the mandatory task parameter and try to commit the resource again.

Now consider that the Patch request that is done on the task resource triggers a layout procedure that changes one of the optional task parameters into a mandatory task parameter for the project record with id 2 only. In this case, when a Commit request is performed before the mandatory task parameter is patched, the commit request will fail on one of the child task resources (namely, project with id 2). This means that the child resource will be removed from the task resource and the task will be executed for all project records except for project record with id 2.

So, when patching and committing a multi-row task, the main task resource will always be handled first and only when an error occurs on this main resource, the process will stop and the error will be shown. In all other cases, the task will be executed for each selected record that passes all validations.

6. Multi-row tasks and process flows

A task that is being executed as a multi-row task can be linked to a process flow and can thereby trigger the start of that process flow automatically. In this case, the started process flow will always continue based on the result of the last task that has been executed. This means that if the last task is executed successfully, Indicium will follow the green arrow of the table task process action to the subsequent action (if present). If the last task is not executed successfully, Indicium will follow the red arrow of the table task process action to the subsequent action (if present).

note

For more information about starting and continuing a process flow with an API process action, see Indicium's Process flow API.