Create a queue of tasks

Queues allow you to perform a series of tasks as a batch process without any user input. Queues are useful when you want to perform the same activity on a number of cases, such as splitting each customer's postal address into multiple separate fields or generating multiple related cases to represent different versions of a product.

The tasks in a queue are performed in sequence. When you add tasks to a queue, each task is completed independently of the other items in that queue. This means that if a single task fails, the previous tasks are not rolled back. You can also specify whether you want to continue with the remaining tasks in the queue if a failure occurs.

To create a queue of tasks you need to:

1. Create a task queue in your Studio. You can also define the rate limit and behavior on failure.
2. Create one or more Queued task event activities. These are the tasks that are added to the queue and performed in sequence. A queued task can trigger other activities, including casetype activities (to create new cases) and form activities (to edit details of existing cases).
3. Create a parent activity that triggers the queued task(s) using an Execute and submit trigger. You can trigger a queued task for all cases in a dataset or use a For each loop to trigger the task for cases in a multivalue attribute.

You can also split a queue into separate queues based on a related case. Once you have created a queue, you can monitor progress and pause or skip tasks using Developer Tools.

Tip:

Using a timed activity, you can trigger a queue to run out of normal working hours. This can be useful when you want to perform changes to your application that could disrupt users.

Create a queue

Before you can create a Queued task activity, you must create the queue that the tasks will be added to. To create a queue, from your Studio, navigate to Platform > Queues. Click Create task queue and enter a name to identify the queue.

By default, if a task fails, Grexx Platform will proceed to the next task in the queue. To prevent the queue from continuing if a task fails, enable Block queue on failure. This is useful if subsequent tasks depend on successful completion of earlier tasks in the queue. However, be careful not to make an earlier task dependent on a later task, as this will create a deadlock.

You can also specify a Rate limit for the queue. This controls the maximum number of tasks that can be performed each hour. The rate limit is set using an attribute on a page casetype (or the case used to split queues, if applicable). Setting the rate limit to 0 prevents any tasks from being performed.

Tip:

You can configure a dedicated page for initiating queues and include a form activity so that users can set the rate limit before initiating the queue. You can also set a default value for a rate limit attribute to avoid having to set the value manually.

Create a queued task

Once you have created a queue, you can create a Queued task activity. When this activity is triggered, a queued task is generated for the relevant case(s) and added to the queue. Each task on the queue is then performed in sequence.

To create a Queued task activity:

1. Open the casetype that the activity relates to and open the Activities tab.
2. Click Create activity and enter a name to identify the queued task.
3. From the Type list select Event.
4. From the Event type list select Queued task.
5. From the Queue list select the relevant queue. Note that once tasks have been added to a queue, changing this setting will not change the queue of those existing tasks.
6. Configure other activity options as required:
   • You can use the Queue based on case option to split the queue based on a related case, as described below. As with the Queue setting, changing this setting does not change the queue of tasks that have already been added to a case queue.
   • You can set a timeout to prevent long-running tasks from blocking the queue. If an individual task in the queue is started but does not complete within the specified timeout period (for example, one hour) then the task is marked as Timed-out and Grexx Platform moves on to the next task in the queue.
   • As queued tasks should be initiated using an Execute and submit trigger, there is no user interaction and no need to add supporting text.
7. Click Create activity. The activity is created and the activity designer is displayed.

Use the activity designer to add triggers and/or mappings to the When done stage. When the task reaches the top of the queue, the triggers are fired and the values of the case attributes are updated as appropriate. For example:

• To populate multiple new Address line attributes from an existing Address attribute, add a mapping that uses an inline template to extract data from the existing attribute and split it into dedicated fields.
• To recalculate all cached computed attributes and the case reference of a case, add an Execute and submit trigger to perform a Recalculate process block activity.
• To create a new related case (such as adding a Version case to a Product case) add an Execute and submit trigger to perform the casetype activity. Use mappings to populate attributes on the new case automatically.
• To close or reopen the current case or a related case, add an Execute and submit trigger to perform a Close case or Reopen case process block activity
• To initiate a mandatory task so that it is available for a user to perform manually, add an Execute trigger for the relevant activity.

If you want to trigger another queued task, ensure the second queued task is added to a different queue. Adding the second queued task to the same queue as the first can create a deadlock, as the first task cannot complete until the second is performed.

For more information about triggering one activity from another, see Chain activities together.

Note:

Any triggers or mappings that you add to the On trigger, On start or On submit stages of a Queued task activity are performed as soon as the activity is triggered, rather than when the task reaches the top of the queue.

Use a parent activity to add tasks to the queue

To generate queued tasks and add them to the queue, you need to create a parent activity that triggers the Queued task activity. The parent activity can be any type of activity. For example, you could use a Dummy process block activity with Request rights so that users (with appropriate permissions) can initiate the queue manually. You could also use a timed event to initiate the queue at a specific time.

Once you have created the parent activity, use the activity designer to add a trigger for the Queued task activity:

1. Add an Execute and submit trigger to the relevant stage of the parent activity. (In most cases, the When done stage is appropriate.)
2. Configure the trigger to identify the case(s) on which the queued task is performed. Most of the time you will want to trigger queued tasks for multiple cases. You can identify cases using either a dataset or a multivalue attribute on the parent case:
   • To identify cases using a dataset, set the To type to Cases in dataset and then select the relevant dataset.
   • To identify cases from a multivalue attribute on the current case, add a For each loop to the activity designer and select the relevant multivalue attribute. Nest the Execute and submit trigger within the For each loop. Then, set the To type to Current foreach caseid and select the For each loop.
3. From the Activity to section, select the Queued task activity.
4. When you have finished, click the "Save" icon.

Grant the appropriate user roles permission to perform the activity as required. Depending on your use case, you may want to make the activity available to users from a widget, or create another activity that triggers this activity.

When the parent activity is performed and the trigger fires, a queued task is generated for each case in the dataset or multivalue attribute. Each queued task is automatically submitted to move it to the Done stage and then added to the queue. You cannot change the queue of a task after the task has been generated.

Tip:

You can trigger several different Queued task activities from the same parent activity. These can be added to the same queue or to different queues, as per each activity's settings.

Split a queue

You can create different queues for queued tasks based on a related case. For example, if you are using a queued task to update all Employee cases, you might want to divide tasks into separate queues based on the employee's country of residence or department.

To do this, edit the Queued task activity and from the Queue based on cases list, select the attribute containing the case ID that you want to use to group cases into a queue. In the example above, this would be the Country of residence or Department attribute. When the parent activity triggers the queued task, separate queues are created for each country or department and the tasks are added to the appropriate queue.

Manage a queue

You can check the status of a queue and of the tasks in a queue using Developer Tools. From any of your DTAP environments, press CTRL + ALT + S or CMD + ALT + S, and then select the Queue tab.

Queue status

The status of each queue is based on the status of the first task in the queue. If the queue does not contain any tasks, the queue status is Empty. If the queue status is Running, the server is actively working on one of the tasks on the queue.

In some cases the status of the queue may be Unknown. This may arise if:

• The first task in the queue has the status Started or Running, but the active request cannot be found.
  • If this is because the first task has not yet started, the problem will resolve itself in less than a minute.
  • This can also happen if the task is being performed by another server, as may occur if your release ring has changed, your application runs on multiple servers, or your application has been moved to a different server.
• An error has occurred but the task was not able to set its status to Error (for example, due to problems with the database itself).
• The server running the task has crashed.

When the status of the queue is Unknown or Error, the queue will pause and not continue until the problem is resolved. Depending on the cause of the issue, you may choose to skip, retry, or delete the first task in the queue.

Note that you should only delete a queue from your Studio once you have ensured that:

• Any queued task activities no longer use that queue.
• There are no existing queues in progress in any of your DTAP environments.

Task status

To view the remaining tasks in a queue and their current state, open the relevant queue from the Queues tab. Actions are available for each task according to the state, such as pause, skip, resume, and delete.

State number	Technical name	Name	Description
0	UNSTARTED	Queued	Task is queued, waiting to be started.
30	MANUALLY_STOP_HERE	Paused	Queue was manually paused on reaching this task (via Developer Tools). You can resume the task manually via Developer Tools.
100	SEND_TO_START	Started	A server has been told to start processing this task.
200	STARTED	Running	A server is currently processing this task.
900	ERROR_BLOCKING	Error	The task has failed causing the queue to stop.* You can retry the task manually.**
1050	MANUALLY_SKIPPED	Skipped	Task was manually skipped from the queue (via Developer Tools).
1150	MANUALLY_DELETED	Deleted	Task was manually deleted from the queue (via Developer Tools).
1200	ERROR_CONTINUE	Skipped after error	Task failed but the queue continued to run (as opposed to state 900).
1300	TIME-OUT	Time-out	Task timed out before it was finished.**
1600	REMOVED_FROM_QUEUE	Removed	Canceled from the queue. (This state is not currently in use.)
1800	TASK_NOT_OPEN	Task not open	Task was no longer open when the processing started.
2000	FINISHED_OK	Done	Task was successfully executed.

* This state is reached if a task has failed and the queue has been configured to block on failure. In this case, any subsequent tasks will remain queued but will not start. To move on to the next task, use Developer Tools to skip the failed task. Note that changing the Block queue on failure setting in the queue properties will not cause the queue to move to the next task.

** You can retry a failed or timed-out task. Before retrying, ensure that the queue is not currently being processed by an API server. Depending on the task, retrying may also result in certain aspects of the task (such as posting data to an external web service or sending an email) being performed more than once. Alternatively you can delete the task to remove it from the queue. Deleting a task does not undo or stop any aspects of the task that are already in progress.

To view details of a queued task that has executed successfully, open the relevant case and from Developer Tools open the Task history. For more information, see Developer Tools.