Process Queues Java Module

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:

IQueueManager
IQueue
IQueueItem

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.

Using process queues

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:

/** 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:

// 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.

Creating a queue

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.

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.

Searching for queues

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:

queueId: Search by the queue identifier. This must be an exact match.
nameRegex: Search by the name of the queue using a regular expression.
descriptionRegex: Search by the description of the queue using a regular expression.

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.

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();

Adding items to a queue

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:

setKey(): The element's identifier in the queue. It's recommended that this is a unique ID so it can be quickly located in the list of items.
setReference(): The value used to locate the item in the source. For example, in a list of items created from an Excel file, the reference could be the row number where the data was obtained from. This is useful if you want to place the result of the process back in the original source.
setState(): The status of an item in the process. By default, an item starts with a PENDING status.
setRemainingAttempts(): Specifies the number of times a robotic task should try to process the item. This is useful when a robotic task does not finish due to external factors.
setPriority(): The value that determines the order in which items should be processed in a queue. The value of this attribute has to be considered each time a robotic task requests the next item to the system.

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.

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);

Working with a queue from the robotic task

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:

queueId: Assigns the queue with this identifier to the execution. The robotic task can get the identifier in two different ways:
- Using the IQueueManager.preselectedQueue() method.
- Using a parameter defined in the robotic task. This is useful when the robotic task is invoked from another robotic task.
name: Locates a queue with the parameter name.

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:

/**
 * 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:

queueId(): Returns the queue identifier.
name(): Name of the queue.
state(): Current state (PENDING, IN_PROCESS, FINISHED, RESERVED, CLOSED).
description(): Description of the queue.
priority(): Established priority (HIGHEST, HIGHER, HIGH, NORMAL, LOW, LOWER, LOWEST).
attemptsByDefault(): Number of attempts by default the contained items can be tried. This is the initial value for each item, which can be modified during its lifecycle.
items(): Total number of items (in any state).
pendingItems(): Number of items pending to be processed (PENDING, IN_PROCESS).
fileName(): Name of the file (if applicable) used in the queue creation.
hasFileContent(): Indicates if the file used in the creation exists as a byte array.
fileContent(): The file content as a byte array. It's useful if we want to get the original file to complete it with information about the items and return it. This byte array is set in the creation of the queue.

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:

String queueId = qmanager.preselectedQueue();
 
AssignQueueParameters qqp = new AssignQueueParameters();
qqp.queueId(queueId);
 
IQueue queue = qmanager.assignQueue(qqp);

Processing the items of a queue

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().

Reserving an Item

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:

PENDING: Items waiting to be processed. You can only reserve items with this status.
IN_PROCESS: Items currently being processed by a robotic task. Reserved items will have this status.
FINISHED_OK: Items that have finished and processed successfully.
FINISHED_WARN: Items that have finished and have a warning.
DISABLED: These items are not taken into account. The platform will ignore these items when providing the next item to be processed.

The code snippet below illustrates how to reserve an item:

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:

queueItemId(): The item's identifier.
queueId(): The identifier of the queue containing the item.
key(): The item key is the functional data to identify it (an invoice number, a bank account, etc.).
state(): The state of the item, the possible values are: Pending, In Process, Finished Ok, Finished Warning.
reference(): A value used to locate the item in the source. For example, in a list of items created from an Excel file, the reference could be the row number where the functional data was obtained from. This is useful if you want to place the result of the process back in the original source.
priority(): The item's priority.
remainingAttempts(): Number of remaining attempts to process the item.
Map<String, String> functionalData(): A map of key value pairs containing functional information that the robotic task will use to process the item.
Map<String, byte[]> files(): A map with the files of the item.

Releasing an Item

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:

process: Indicates the mechanism to use to determine the item's status. This is a parameter that uses one of the following values in the EQueueItemReleaseProcess:
- SYSTEM: The system will determine the final item status depending on the number of remaining attempts and the item status.
- PENDING: The item's status is pending.
- FINISHED_OK: Finished successfully.
- FINISHED_WARN: Finished with warnings.
retry: Manages the number of attempts to release an item. This is one of the values of the EQueueItemReleaseRetry enumerator:
- DECREMENT_BY_1: The default value. Each time an item is released, the number of remaining attempts will decrease by 1.
- NO_CHANGE: The number of remaining attempts will not change.
- SET_TO_0: The number of remaining attempts is set to 0. This option is commonly used when you know the item processing will always lead to the same error, no matter how many times it's retried.
- RESET_TO_DEFAULT: The number of remaining items is reverted to its original value that is defined in the queue.
labels: Permission tags on the item.
functionalData: Map of functional values. If the item's functional data has changed, the data will be updated on the item that is loaded on the queue.
filesToAdd: A list of paths indicating the files that should be added to the element before releasing it.

The code snippet below illustrates how you could use the releaseItem method:

// 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);

Updating and closing a queue

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:

reserveQueuePaged(): Reserve the queue. To update and close the queue, you will first need to get exclusive access to the queue. This is also where you can confirm there are no other items to process.
updateQueue(): Updates the information of the file used as the origin of the queue. For example, you can use this method to extract the file loaded in the queue and update each row with the data stored in the items.
releaseQueue(): Release the queue to close it.

Reserving a queue

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:

queueId: Specify the queue to reserve using its identifier.
name: Specify the queue to reserve using its name.
page: Specify the index of the page to retrieve from the queue. Only one page of items can be retrieved at a time.
downloadItems: Downloads the items in a queue into memory, allowing you to iterate over them directly. Use this attribute when you want all the items to be stored locally with a single call to the console. This is an alternative to using the reserveItem() and releaseItem() methods. Set this parameter value to 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.

    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:

queue: Instance of a class implementing the IQueue interface.
items: A list of IQueueItem (List<IQueueItem>), corresponding to the requested page of the queue. If downloadItems is set to false, the list will be empty.
moreItemsAvailable: Indicates if there are more items available in the queue.

Updating a queue's information

The updateQueue() method updates the file used as the origin of the queue.

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.

queueId(): Returns the queue identifier.
name(): Name of the queue.
state(): Current state (PENDING, IN_PROCESS, FINISHED, RESERVED, CLOSED).
description(): Description of the queue.
priority(): Established priority (HIGHEST, HIGHER, HIGH, NORMAL, LOW, LOWER, LOWEST).
attemptsByDefault(): Number of attempts by default the contained items can be tried. This is the initial value for each item, which can be modified during its lifecycle.
items(): Total number of items (in any state).
pendingItems(): Number of items pending to be processed (PENDING, IN_PROCESS).
fileName(): Name of the file (if applicable) used in the queue creation.
hasFileContent(): Indicates if the file used in the creation exists as a byte array.
fileContent(): The file content as a byte array. It's useful if we want to get the original file to complete it with information about the items and return it. This byte array is set in the creation of the queue.

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.

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<>();

Releasing a queue

After updating the initial file, you can release and close the queue using the releaseQueue() method. This method receives ReleaseQueueParameters, which has two attributes:

closed: Indicates the queue's processing has been completed.
state: Establishes the queue in one of the following states:
- PENDING
- IN_PROCESS
- FINISHED
- RESERVED
- CLOSED

Feedback

Was this page helpful?