We recommend that you read the About Queues and Transactions page, for an overview on queues and transactions, before further proceeding to the QueueItem variable.
Before getting into an in-depth detailing of the subject, make sure you understand the distinction between queue items (items stored in a queue in Orchestrator) and QueueItem variables (variables used in Studio to process queue items). We refer to them exactly like that: “QueueItem variables” and “queue items”.
Broadly, as the name says, the QueueItem variable stores an item which has been extracted from a container of items, a queue. This extraction is generally made with the purpose of further using the queue items in various scenarios. Let’s say you represent a banking institution and you have a deposits’ report of 50 clients. You want to process the data of each client who had previously deposited an On-Us Check smaller than $5000, using a third-party financial application. In this regard, you can make a workflow in which the QueueItem variable stores, by turn, the information of each client. Each entry read by the QueueItem variable is stored in a queue item and added to the designated queue in Orchestrator. The result of this whole process is a queue which contains the clients' information, each in the corresponding queue item.
To further process the data which meets the condition, you must create another workflow which extracts from the previously created queue, the items with a corresponding On-Us Check value smaller than $5000. A step-by-step procedure on how to create such a project is provided at the end of this topic.
Supported .NET Methods
Name/Syntax | Description |
---|---|
EqualsFunction Object.Equals(obj As Object) As Boolean | Click here for details. |
GetHashCodeFunction Object.GetHashCode() As Integer | Click here for details. |
GetTypeFunction Object.GetType() As Type | Click here for details. |
ToStringFunction Object.ToString() As String | Click here for details. |
Supported Properties
Name/Syntax | Description |
---|---|
AssignedToProperty QueueItem.AssignedTo As String | Click here for details. |
DueDateProperty QueueItem.DueDate As Date? | The latest date and time at which the item should be processed. If empty, the item can be processed at any given time. |
DeferDateProperty QueueItem.DueDate As Date? | The earliest date and time at which the item is available for processing. If empty, the item can be processed as soon as possible. |
IdProperty QueueItem.Id As Long? | Click here for details. |
ItemKeyProperty QueueItem.ItemKey As Guid | The unique identifier of the item. For example, 1bf829e1-cd6b-4275-a364-19db3cfe09c7 . |
PriorityProperty QueueItem.Priority As QueueItemPriority | The priority of the queue item as defined in Studio in the Priority field on the Properties panel. |
ProcessingExceptionProperty QueueItem.ProcessingException As ProcessingException | The processing exception of a failed item. |
ProgressProperty QueueItem.Progress As String | Custom progress information about a queue item whose status is InProgress. |
QueueDefinitionIdProperty QueueItem.QueueDefinitionId As Long | The unique identifier of the queue under which a queue item/transaction has been created. |
QueueNameProperty QueueItem.QueueName As String | The name of the queue containing the processed items. |
ReferenceProperty QueueItem.Reference As String | A user-specified value for easier queue item identification. |
RetryNoProperty QueueItem.RetryNo As Integer | The number of times the item has been retried. |
ReviewStatusProperty QueueItem.ReviewStatus As String | The revision status of the queue item as retrieved from Orchestrator. |
RowVersionProperty QueueItem.RowVersion As Byte() | An internal field used for version stamping. It gets updated whenever a property of the current transaction is changed. |
SpecificContentProperty QueueItem.SpecificContent As Dictionary(Of String, Object) | A collection of key value pairs containing custom data associated with the current transaction, as configured in the Add Queue Item activity. |
StartTransactionTimeProperty QueueItem.StartTransactionTime As Date? | The time and date the transaction processing began. |
StatusProperty QueueItem.Status As QueueItemStatus | The status of the queue item as retrieved from Orchestrator. |
Example of Using a QueueItem Variable
Due to the nature of this example, we have split this section in two parts, each representing one of the two main workflows to be used when working with queues and queue items:
Uploading Items into a Queue
To demonstrate how to add items into a queue, let us create an automation that processes entries contained in a .xlsx
file. Let’s say you represent a banking institution and you have a deposits’ report of 50 clients. You want to process the data of each client that previously deposited an On-Us Check smaller than $5000, using a third-party financial application. The report contains the name of the client, the On-Us Check value, and two other additional values, let’s say Cash In and Not On-Us Check. We create a workflow in which the QueueItem variable stores, by turn, the information of each client. Each entry read by the QueueItem variable is then stored in a queue item and added to the designated queue in Orchestrator. The result of this whole process is a queue which contains each clients’ specific information. Before proceeding to the actual workflow, you might want to take a look at the clients’ report here. We are going to work with the "July Reports" sheet.
Without further ado:
- Create a new sequence.
- Add an Excel Application Scope activity inside the sequence, and define the location of the workbook in the Properties pane of the activity.
- Inside the Do section, add a Read Range activity to read the desired range of values from the report and store them in a DataTable variable. In our case, type
"A1-D51"
or simply leave the default value, “”, which means the entire spreadsheet is read. - In the Sheet Name field, type the name of the sheet, namely
“July Report”
. - In the Data Table field, press Ctrl + K to create a new DataTable variable which stores the previously read data range. Name it
DataTable1
or similar. The Variables pane should also display the newly created variable as follows:
- Next, add a For Each Row activity to the Designer panel and fill in the blank fields with “row” and the name of the DataTable variable,
DataTable1
, respectively. This activity performs the action defined in the Body section for each row in the data table. The Do section should look similar to the following screenshot so far:
- In the Body section of the For Each Row activity, add an Add Queue Item activity. This adds an item to a queue (defined below at steps 8 and 12), for each row in the spreadsheet.
- In the Properties pane, in the QueueName field, type the name of the queue you want your items to be stored in, let's say
ReportQueue
. - In the Input section, click the button corresponding to the ItemInformation field to open the ItemInformation window. Create 4 arguments, each corresponding to a column from the report. Define them as follows:
Name
, keeping the default values for Direction and Type, and with Value set torow(0).ToString
. This retrieves the value from the column with the counter 0 for each row in the workbook, in our case the name of the client.CashIn
, keeping the default values for Direction and Type, and with Value set torow(1).ToString
. This retrieves the value from the column with the counter 1 for each row in the workbook, in our case the Cash In value.OnUsCheck
, keeping the default values for Direction and Type, and with Value set torow(2).ToString
. This retrieves the value from the column with the counter 2 for each row in the workbook, in our case the On-Us Check value.NotOnUsCheck
, keeping the default values for Direction and Type, and with Value set torow(3).ToString
. This retrieves the value from the column with the counter 3 for each row in the workbook, in our case the Not On-Us Check value.
- The ItemInformation window should look similar to the following screenshot:
- Connect Studio’s Robot to Orchestrator. For details on how to do it, click here.
- Navigate to https://platform.uipath.com, log in using your credentials, and then create a queue, ReportQueue, to store the items. Make sure that, whatever name you used above (step 8), you use the same here.
- Go back to Studio. At this point your workflow should be error-free and functional, so the next step is to make it available to Orchestrator. In this regard click Design > Publish.
- To run the process, click Design > Run.
Note
Take into account that, after being processed, queue items become transactions, and are further handled as such.
- Navigate to https://platform.uipath.com again and display the transactions.
Processing the Transactions from a Queue
To demonstrate how to further process transactions from a queue, we are going to create a second workflow which retrieves from the appropriate queue, the transactions with an On-Us Check value smaller than $5000. For each transaction that meets the condition, the values are collected and introduced into a third-party dummy application. The other ones are labeled as business exceptions.
- Go to Design > New > Flowchart to create a new file in the project initiated above.
- Add an Open Application activity to open the third-party dummy application. Connect it to the Start node.
- Fill in the required details (Display Name, FileName, Selector) on the Properties panel, and configure the activity to log in with the corresponding credentials. Use
admin
for the Username field, andpassword
for the Password field. - In the FileName field, fill in the path of the application.
- In the Selector field, using Selector Editor, define a selector for UIDemo.
- Add a Should Stop activity to the Designer panel and connect it to the Open Application activity.
- Add a Flow Decision activity to the Designer panel and connect it to the Should Stop activity. These last two activities check if you stopped the job while it was still running. This gives you the possibility to further configure the workflow to perform various safety routines after the stop is triggered. See below an example of such a routine:
- Add a Log Message activity and connect it to the True branch of the previously added flow decision.
- In the Properties panel, in the Message field, type “Stop process required” or something similar to be displayed if the stop is triggered.
- Add a Close Application activity and connect it to the Log Message activity previously added.
- In the Properties panel, in the DisplayName field, after Close application, type
UIDemo.exe UIDemo
.
- Add a Get Transaction Item activity to the False branch of the flow decision added previously (step 7). This activity retrieves the transaction items from the queue and stores them, by turn, with each iteration of the loop, in a QueueItem variable.
- In the Properties pane, in the QueueName field, type the name of the queue which stores your items. In our case, as defined in the Uploading Items into a Queue section, the name is "ReportQueue".
- In the TransactionItem field, press Ctrl+K to create the QueueItem variable which stores each transaction item. Name it "TransItem" or similar.
- Add a Flow Decision activity to the Designer panel and connect it to the Get Transaction Item activity.
- In the Properties pane, in the Condition field, type
TransItem isNot Nothing
. This activity checks the value of each item to determine if the end of the queue has been reached. - Connect the False branch of the flow decision to the Log Message activity created in step 7. This ensures the job stops when the end of the queue is reached.
- Add another Flow Decision activity to the Designer panel and connect it to the True branch of the flow decision created in step 11.
- In the Properties pane, in the Condition field, type
cint(TransItem.SpecificContent("OnUSCheck").ToString) < 5000
, where:
cint
converts a variable of type string to one of type integer.TransItem
is the QueueItem variable (step 18) used to store the items.SpecificContent("OnUSCheck")
retrieves the content of the On US Check argument in each item..ToString
converts the content of the QueueItem variable into a variable of type string.< 5000
is the condition to be checked against.
The above expression converts the OnUSCheck value in each QueueItem variable into a string variable, which is then further converted into an integer. The value thus obtained is checked for compliance with the condition.
- Add a Set Transaction Status activity to the Designer panel, and connect it to the False branch of the previous flow decision (step 13).
- In the Properties pane, make sure the Status field is set to Failed, and ErrorType to Business. This way, if the value of On US Check is bigger or equal to 5000, the transaction is marked as failed with a business exception.
- In the TransactionItem field add the
TransItem
variable. - In the Reason field, type "OnUSCheck amount is bigger than 5000" or similar, to display for a failed transaction.
- Connect the Set Transaction Status activity to the Should Stop activity (step 6), to create a loop and process the next transaction in the queue.
- Add a Sequence activity to the Designer panel, and connect it to the True branch of the previous flow decision (step 13). Inside the sequence, add a Try Catch activity and configure it such that any potential errors are correctly labeled as application errors when processing the items.
- Open the UIDemo application, and log in with the username
admin
and the passwordpassword
. - Perform the following series of activities for each of the Cash In, On Us Check and Not On Us Check fields in the UIDemo application:
- Into the previous Try Catch activity, add a Type Into activity.
- Click Indicate on screen and select from the UIDemo interface, the blank field corresponding to Cash In.
- In the Properties pane, in the Text field, type
transItem.SpecificContent("CashIn").ToString
. Each term in the expression is explained above (step 15). This expression converts the value in each QueueItem variable into a string variable. - Make sure that the Simulate Type option is selected.
- On the Design tab, in the Wizards section, click Screen Scraping and point at the transaction number in the UIDemo application.
- From the Screen Scraper Wizard, choose a scraping method and click Finish. This inserts a Screen Scraping activity in your workflow. Make sure to position it after the previous Type Into activities, and set the Text field to a new variable, say
TransactionValue
. This retrieves the transaction number for each queue item that meets the initial condition. - Add a Set Transaction Status activity after the Screen Scraping activity.
- In the Properties pane, make sure the Status field is set to Successful, and the ErrorType is set to Application. This way, if the set of values is successfully introduced in the application, the status of the transaction is set to Successful, or else labeled as an application exception.
- In the Output window, define a new argument and add the previously created variable,
TransactionValue
(step 25) as value. - In the TransactionItem field, add the
TransItem
variable. - Add a Click activity to the Sequence activity after the Type Into activities.
- Click Indicate on screen and select the Accept button from the UIDemo interface. Make sure the Simulate Type option is selected.
- The Try Catch activity should look similar to the following screenshot:
- Return to the flowchart and connect the previous Sequence activity (step 21) to the Should Stop activity (step 6) to create a loop and process the next transaction in the queue.
- The flowchart should look similar to the following screenshot:
- To run the process, click Design > Run.
- After the execution has ended, you may navigate to https://platform.uipath.com and display the processed transactions with the corresponding processing details:
- Successful Transaction
- Failed Transaction
Updated about a year ago