| The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
In Appian RPA, process queues are a set of grouped items to be processed by one or several robotic tasks.
A queue represents a container of items. Each item represents an element that the robotic task will interact with. Using Excel as an example, a queue can be considered the entire spreadsheet, while each row would be an item. Each item contains two sets of attributes: data about the state of an item in the queue, and functional data.
The com.novayre.jidoka.client.api.queue package contains several interfaces involved in process queue management. The three primary interfaces you will interact with are:
You can choose to configure your process queues using the Appian RPA Console or directly in your robotic task. Navigate to the Monitoring tab to create queues in the console. The following sections describe how to create a queue within your source code.
The IQueueManager interface contains all the methods an Appian RPA robotic task needs to use queues. To initialize the interface, you must first declare an attribute of type IQueueManager in your robotic task. For example:
1
2
/** The qmanager. */
private IQueueManager qmanager;
Then, in one of the first methods of your robotic task, like the startUp() method, use the following code snippet to get an instance of IQueueManager:
1
2
3
4
5
// IJidokaServer instance
server = (IJidokaServer<?>) JidokaFactory.getServer();
// initialize the QueueManager
qmanager = server.getQueueManager();
Once the interface is initialized, you can create a queue and its items.
To have your robotic task create a queue, use the createQueue() method. This method receives CreateQueueParameters, where you can set the queue name, its description, attempts by default, and permission tags.
Permission tags determine which queues can be accessed by a robotic task. Whichever permission tags you assign to your queue, you must also assign them to your corresponding robotic task. If needed, you can associate a queue with several different robotic tasks. If you want each robotic task to access different items, you can assign permissions at the item level. If an item doesn't have any permission, it inherits the permissions from the queue it belongs to.
1
2
3
4
5
6
7
8
9
10
CreateQueueParameters qParam = new CreateQueueParameters();
qParam.setName("myQueueName");
qParam.setDescription("Description of the queue");
qParam.setPriority(EPriority.HIGH);
String[] labels = {"label_1", "label_2"};
qParam.setLabels(Arrays.asList(labels));
qParam.setAttemptsByDefault(1);
String queueId qmanager.createQueue(qParam);
For more information on this method, consult the Javadocs in the Appian RPA Console. In the console, click Help > Javadoc in the left menu.
You can have your robotic task search for queues based on the queue's name or description. To search for a queue, use the findQueues() method.
The findQueues() method receives FindQueuesParameters, where you can search for a queue using the following attributes:
This method returns a list of queues that match the search parameters. The search will only look for queues that share the same permissions as the robotic task. If no queue is found, an empty list is returned.
The following code snippet illustrates the results of a search looking for queues containing the string 14052019 in their name.
1
2
3
4
5
6
7
8
9
10
11
String queueName = "*_14052019_*";
FindQueuesParameters fqp = new FindQueuesParameters();
fqp.setNameRegex(queueName);
List<IQueue> foundQueues;
try {
foundQueues= qm.findQueues(fqp);
} catch (IOException e) {
throw new JidokaQueueException(e);
}
boolean queueExists = !foundQueues.isEmpty();
Once you've created a queue or located an existing queue, you can create the queue's process items. To create an item, use the createItem() method.
The createItem() method receives CreateItemParameters, where you can create a map containing functional data and define the following attributes:
You can also associate a series of files with an item using the setFiles() method.
The following code snippet illustrates a sample item added to a queue.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
CreateItemParameters iParam = new CreateItemParameters();
iParam.setKey("theItemKey");
Map<String, String> functionalData = new HashMap<>();
functionalData.put("one_key", "one_value");
functionalData.put("another_key", "another_value");
iParam.setFunctionalData(functionalData);
List<Path> files = new ArrayList<Path>();
files.add(image1Path);
files.add(image2Path);
iParam.setFiles(files);
iParam.setPriority(EPriority.HIGH);
iParam.setQueueId("myQueueName");
iParam.setReference("theItemReference");
qmanager.createItem(iParam);
Once the queue is created and has items associated with it, it's common that one or more robotic tasks will treat the items. To treat the items, first you must tell the robotic task which queue to process.
To assign a queue to a robotic task, use the assignQueue() method. This method receives AssignQueueParameters, where you can identify a specific queue using the following attributes:
searches: A list of values of the EQueueAssign enumerator. If this is not set, the platform will use the criteria in order of appearance in the enumerator. EQueueAssign has these possible values:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/**
* Queue assigning enumerator
* Declares available algorithms to assign (search) a queue, algorithms can be in chain
*/
public enum EQueueAssign {
/**
* Queue with greatest priority will be returned
*/
PRIORITY,
/**
* First available queue for this robot will be returned
*/
FIRST_LISTED,
/**
* Maximum pending items queue will be returned
*/
MAX_PENDING;
}
Depending on your parameters, this method returns a queue or a list of queues. Queues are represented by the IQueue interface. This interface provides the attributes defined in queue creation, such as:
For more information on this interface, consult the Javadocs in the Appian RPA Console. In the console, click Help > Javadoc in the left menu.
The following example shows how you can assign a queue using its ID:
1
2
3
4
5
6
String queueId = qmanager.preselectedQueue();
AssignQueueParameters qqp = new AssignQueueParameters();
qqp.queueId(queueId);
IQueue queue = qmanager.assignQueue(qqp);
Once the robotic task is assigned a queue, it will begin evaluating the queue's items. To process each item in a queue, you must add a loop in your workflow.
Your loop will begin by requesting the next item. The system will then reserve the item for the requesting robotic task and set its status to IN_PROCESS. Once the item has been processed, the robotic task will update the item's status and functional information.
To create this loop, you will use two methods: reserveItem() and releaseItem().
The reserveItem() method reserves an item in a queue to a specific robotic task. The method is executed synchronously in the console to assure that no other robotic task can reserve the same item. An item can have one of the following statuses:
The code snippet below illustrates how to reserve an item:
1
2
3
4
5
6
ReserveItemParameters reserveItemsParameters = new ReserveItemParameters();
// Only for showing the attribute. "true" is its default value.
reserveItemsParameters.setUseOnlyCurrentQueue(true);
IQueueItem item = qmanager.reserveItem(reserveItemsParameters);
The IQueueItem interface represents an item in a process queue and contains the following attributes:
Once a reserved item has been processed, the next step is to release the item. To release an item, use the releaseItem() method. When invoking this method, an instance of the class must be passed.
The releaseItem() method receives ReleaseItemWithOptionalParameters, where you can indicate which data should be updated. The parameter accepts the following attributes:
The code snippet below illustrates how you could use the releaseItem method:
1
2
3
4
5
6
7
8
9
// release the item. The queue item result will be the same
// as the currentItem
ReleaseItemWithOptionalParameters rip = new ReleaseItemWithOptionalParameters();
rip.setFunctionalData(funcData);
// You must set the current item result before releasing the queue item
server.setCurrentItemResultToOK(currentItem.getTitle());
qmanager.releaseItem(rip);
When all of the items in a queue have been processed, the robotic task must close the queue. If the queue was created using a file, you will also need to update the file used as the origin of the queue.
If the queue is assigned to several robotic tasks concurrently, only the instance of the robotic task handling the last item needs to perform these actions, or other actions like generating an output file, sending an email, etc. To know if the instance is processing the last item, it needs exclusive access to the queue.
To accomplish these actions, you can use the following methods:
Note: The reserveQueue Java method is deprecated and will be removed in a future release of Appian. Customers should update their robotic tasks to use the new reserveQueuePaged method described in this section.
To reserve a queue, use the reserveQueuePaged() method. This allows you to ensure that no other instance will modify the status of the queue. You cannot reserve a process queue if it is already reserved by another robotic task. When using this method, you should check if there are any items left to process.
The reserveQueuePaged() method receives ReserveQueuePagedParameters. The ReserveQueuePagedParameters object has four attributes:
true if you do not want to modify the items in a queue. If you want to modify items, such as their state and functional data, set this value to false and use the reserveItem() and releaseItem() methods to interact with items. Set to true by default.The code snippet below shows how to reserve a queue and page through its items.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
int page = 0;
do {
ReserveQueuePagedParameters rqp = new ReserveQueuePagedParameters()
.queueId(queueId)
.page(page++);
IReservedQueuePaged reservedQueue = queueManager.reserveQueuePaged(rqp);
// Robot can't reserve the current queue
if (reservedQueue == null) {
server.debug("Can't reserve the queue with ID: " + currentQueue.queueId());
return;
}
server.info("Number of items = " + reservedQueue.items().size());
server.info("More items available? " + reservedQueue.moreItemsAvailable());
} while (reservedQueue.moreItemsAvailable());
ReleaseQueueParameters release = new ReleaseQueueParameters();
queueManager.releaseQueue(release);
If a queue is successfully reserved, the returned object is an instance of the IReservedQueuePaged. This interface has three attributes:
false, the list will be empty.The updateQueue() method updates the file used as the origin of the queue.
1
void updateQueue(UpdateQueueParameters parameters) throws IOException, JidokaQueueException;
This method receives UpdateQueueParameters, where you can identify a specific queue using the attributes below. Note that all the attributes are Optional types, so the system will only update those containing a specific value.
For example, you could use this method to extract the Excel file used to create the queue, and then use the Data-Provider module to update the contents of the Excel file with the new functional data of each processed item.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
public class UpdateQueueParameters {
/**
* Name
*/
private Optional<String> name = new Optional<>();
/**
* State
*/
private Optional<EQueueCurrentState> state = new Optional<>();
/**
* Description
*/
private Optional<String> description = new Optional<>();
/**
* Priority
*/
private Optional<EPriority> priority = new Optional<>(EPriority.NORMAL);
/**
* Attempts by default
*/
private Optional<Integer> attemptsByDefault = new Optional<>();
/**
* File name
*/
private Optional<String> fileName = new Optional<>();
/**
* File content
*/
private Optional<byte[]> fileContent = new Optional<>();
/**
* Labels
*/
private Optional<List<String>> labels = new Optional<>();
/**
* Functional data visible keys
*/
private Optional<List<String>> functionalDataVisibleKeys = new Optional<>();
After updating the initial file, you can release and close the queue using the releaseQueue() method. This method receives ReleaseQueueParameters, which has two attributes:
Process Queues Java Module
