Transactions Requests

Note: Queue items can only be processed by Robots. For example, making a POST request to the /odata/Queues/UiPathODataSvc.StartTransaction endpoint requires information which is only available to the Robot.

Viewing the History of an Item

The following call enables you to view all the actions that a specific queue item went through.

GET

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItemEvents/UiPath.Server.Configuration.OData.GetQueueItemEventsHistory(queueItemId=1050203)?$orderby=Timestamp&$top=10

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#QueueItemEvents",
    "@odata.count": 5,
    "value": [
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T16:02:59.09Z",
            "Action": "Create",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "New",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 18276
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:04.46Z",
            "Action": "Status",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20333
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:05.07Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20334
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:05.507Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "Failed",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20335
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-08T10:47:40.463Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 583,
            "UserName": "admin",
            "Status": "Failed",
            "ReviewStatus": "None",
            "ReviewerUserId": 583,
            "ReviewerUserName": "admin",
            "Id": 21240
        }
    ]
}

Retrieving the Average Execution Time for a Specific Queue

The following request enables you to see the average execution time of items in an indicated queue.

Note: This type of request can only be filtered according to the queue name or description, and not queue id.

GET

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueProcessingRecords/UiPathODataSvc.RetrieveQueuesProcessingStatus?$filter=QueueDefinitionName eq 'DocQueue'

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#Collection(UiPath.Core.Model.Queues.QueueProcessingStatus)",
    "@odata.count": 1,
    "value": [
        {
            "ItemsToProcess": 682,
            "ItemsInProgress": 0,
            "QueueDefinitionId": 188,
            "QueueDefinitionName": "DocQueue",
            "QueueDefinitionDescription": null,
            "QueueDefinitionAcceptAutomaticallyRetry": true,
            "QueueDefinitionMaxNumberOfRetries": 5,
            "QueueDefinitionEnforceUniqueReference": false,
            "ProcessingMeanTime": 2.15,
            "SuccessfulTransactionsNo": 0,
            "ApplicationExceptionsNo": 0,
            "BusinessExceptionsNo": 883,
            "SuccessfulTransactionsProcessingTime": 0,
            "ApplicationExceptionsProcessingTime": 0,
            "BusinessExceptionsProcessingTime": 2.15,
            "TotalNumberOfTransactions": 883,
            "LastProcessed": "2018-03-07T18:20:29.3833333Z"
        }
    ]
}

Changing the Reviewer of a Queue Item

The following example enables you to change the reviewer of the failed transaction item with the 1050200 Id.

Note: The value of the RowVersion parameter changes each time an update is made to a queue item. To retrieve this information, perform a GET call on the /odata/QueueItems() endpoint, such as https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems(1050200).

POST

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems/UiPathODataSvc.SetItemReviewer

Request headers

Key	Value
Authorization	Bearer

Request body

{
    "queueItems": [{
        "Id": 1050200, 
        "RowVersion":"AAAAAABDIK8="
    }], 
    "userId": 583
}

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfInt64",
    "Success": true,
    "Message": null,
    "FailedItems": []
}

Retrieving Queue Items With an Indicated Review Status

This example enables you to extract the first two queue items that have a Revision status set to In Review.

GET

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=ReviewStatus eq 'InReview'&$top=2

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#QueueItems",
    "@odata.count": 3,
    "value": [
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "Failed",
            "ReviewStatus": "InReview",
            "ReviewerUserId": 583,
            "Key": "e4760d27-a76d-4469-b7e6-fbda2f732b10",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": "BusinessException",
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T18:14:56.633Z",
            "EndProcessing": "2018-03-07T18:14:58.723Z",
            "SecondsInPreviousAttempts": 2,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Gets a specified credential by using a provided AssetName, and returns a username and a secure password.\"}}",
            "CreationTime": "2018-03-07T16:02:57.547Z",
            "Progress": null,
            "RowVersion": "AAAAAABDFiU=",
            "Id": 1050199,
            "ProcessingException": {
                "Reason": "authentication",
                "Details": null,
                "Type": "BusinessException",
                "AssociatedImageFilePath": null,
                "CreationTime": "2018-03-07T18:14:58.723Z"
            },
            "SpecificContent": {
                "Description": "Gets a specified credential by using a provided AssetName, and returns a username and a secure password."
            },
            "Output": null
        },
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "Failed",
            "ReviewStatus": "InReview",
            "ReviewerUserId": 583,
            "Key": "e90e8067-50fc-407a-9678-eede311f815a",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": "BusinessException",
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T18:14:54.85Z",
            "EndProcessing": "2018-03-07T18:14:57.103Z",
            "SecondsInPreviousAttempts": 2,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Gets a specified asset by using a provided AssetName. If the asset is not global, it must be assigned to the local robot in order to be retrieved.\"}}",
            "CreationTime": "2018-03-07T16:02:57.287Z",
            "Progress": null,
            "RowVersion": "AAAAAABDFiY=",
            "Id": 1050198,
            "ProcessingException": {
                "Reason": "authentication",
                "Details": null,
                "Type": "BusinessException",
                "AssociatedImageFilePath": null,
                "CreationTime": "2018-03-07T18:14:57.103Z"
            },
            "SpecificContent": {
                "Description": "Gets a specified asset by using a provided AssetName. If the asset is not global, it must be assigned to the local robot in order to be retrieved."
            },
            "Output": null
        }
    ]
}

Adding a Queue Item

The example below enables us to add an item to the "DocQueue" queue, with a high priority, defer and due dates, and two arguments with values. All items added like this have the New status, just like the Add Queue Item activity.

Please note that the SpecificContent parameter should be populated only with primitive values.

POST

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Queues/UiPathODataSvc.AddQueueItem

Request headers

Key	Value
Authorization	Bearer

Request body

{
    "itemData": {
        "Priority": "High",
        "DeferDate": "2018-03-21T13:42:27.654Z",
        "DueDate": "2018-03-25T13:42:27.654Z",
        "Name": "DocQueue",
        "SpecificContent": {
            "Email": "[e-mail]", 
            "Name": "O'Brian"
        }
    }
}

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#queueItem/$entity",
    "QueueDefinitionId": 188,
    "OutputData": null,
    "Status": "New",
    "ReviewStatus": "None",
    "ReviewerUserId": null,
    "Key": "e9cb2205-0232-4b99-9556-52dc2e686663",
    "Reference": null,
    "ProcessingExceptionType": null,
    "DueDate": "2018-03-25T13:42:27.654Z",
    "Priority": "High",
    "DeferDate": "2018-03-21T13:42:27.654Z",
    "StartProcessing": null,
    "EndProcessing": null,
    "SecondsInPreviousAttempts": 0,
    "AncestorId": null,
    "RetryNumber": 0,
    "SpecificData": "{\"DynamicProperties\":{\"Email\":\"[e-mail]\",\"Name\":\"O'brian\"}}",
    "CreationTime": "2018-03-21T15:31:27.2699068Z",
    "Progress": null,
    "RowVersion": "AAAAAABDGLk=",
    "Id": 1050947,
    "ProcessingException": null,
    "SpecificContent": {
        "Email": "[e-mail]",
        "Name": "O'Brian"
    },
    "Output": null
}}

Adding Multiple Queue Items

Important:

If you are assigned to multiple folders, your request must contain an HTTP header providing either the FolderId or FolderPath of the desired queue. See here for details.

If not included, the request fails with the following error: An organization unit is required for this action.

The examples below enables us to add multiple items at the same time to the "DocTest" queue that has been configured to only allow unique references. Once the items have been added, they all have the New status.

It is recommended to specify the data type for Specific Data content. For example, if the Name field contains data of type String, then you should add an extra key:value pair using the following syntax "[e-mail]": "#string". See the examples below.

The first example is successful, while the latter fails because the items lack references which are required for unique-reference queues.

There are two upload strategies one can use when adding multiple queue items:

• AllOrNothing - Adds queue items only if an error is not encountered. Otherwise, it does not insert anything and returns the row where the error occurred.
• ProcessAllIndependently - Adds all your items and returns a list of all those that failed.
  Note:

  Failed requests return 200 OK, as the failed items are returned in the body of the response, as you can see in the second example.

  The only requests that do not return 200 OK are those in which the input parameters are incorrect.

Successful Request

POST

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Queues/UiPathODataSvc.BulkAddQueueItems

Request headers

Key	Value
Authorization	Bearer

Request body

{
    "queueName": "DocTest",
    "commitType": "AllOrNothing",
    "queueItems": [{
            "Priority": "High",
            "SpecificContent": {
                "Name": "rêvé",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref4"
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "même",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref5"
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "Žao",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref6"
        }
    ]
}

Response code

200 OK

Response body

{
  "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfFailedQueueItemDto",
  "Success": true,
  "Message": null,
  "FailedItems": []
}

Failed Request

POST

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Queues/UiPathODataSvc.BulkAddQueueItems

Request headers

Key	Value
Authorization	Bearer

Request body

{
    "queueName": "DocTest",
    "commitType": "AllOrNothing",
    "queueItems": [{
            "Priority": "High",
            "SpecificContent": {
                "Name": "rêvé",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "même",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "Žao",
                "[e-mail]": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        }
    ]
}

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfFailedQueueItemDto",
    "Success": false,
    "Message": "Some items have not been inserted.",
    "FailedItems": [{
        "Ordinal": 1,
        "ErrorCode": "TransactionReferenceRequired",
        "ErrorMessage": "Error creating Transaction. Reference is required for Unique Reference Queues."
    }]
}

Retrieving Transactions According to Their Status and Robot Id

The example below queries the Orchestrator database for the first 10 queue items with the In Progress status that were processed by the Robot with the 749 Id. Lastly, the Robot information is expanded. Please note that the Response was truncated.

GET

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$top=10&$expand=Robot&$filter=Status eq 'InProgress' and Robot/Id eq 749

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#QueueItems",
    "@odata.count": 1752,
    "value": [
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "Key": "1c632cc1-44ab-4624-bace-6fbb5fd1c0cd",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": null,
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T15:05:05.113Z",
            "EndProcessing": null,
            "SecondsInPreviousAttempts": 0,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Checks if Stop was triggered in UiPath Orchestrator.\"}}",
            "CreationTime": "2018-03-05T18:39:16.06Z",
            "Progress": null,
            "RowVersion": "AAAAAABC3aA=",
            "Id": 1048065,
            "ProcessingException": null,
            "SpecificContent": {
                "Description": "Checks if Stop was triggered in UiPath Orchestrator."
            },
            "Output": null,
            "Robot": {
                "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 749,
                "ExecutionSettings": null
            }
        },
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "Key": "7dfa834b-8398-476e-bd18-b0fa51d4ddf6",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": null,
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T15:05:04.503Z",
            "EndProcessing": null,
            "SecondsInPreviousAttempts": 0,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Sets the status of a transaction item to Failed or Successful.\"}}",
            "CreationTime": "2018-03-05T18:39:15.627Z",
            "Progress": null,
            "RowVersion": "AAAAAABC3Z8=",
            "Id": 1048064,
            "ProcessingException": null,
            "SpecificContent": {
                "Description": "Sets the status of a transaction item to Failed or Successful."
            },
            "Output": null,
            "Robot": {
                "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 749,
                "ExecutionSettings": null
            }
        }
    ]
}

Retrieving Comments for a Specific Item

The example below displays all the comments of the queue item with the 1050204 Id, in ascending order of creation.

GET

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItemComments/UiPath.Server.Configuration.OData.GetQueueItemCommentsHistory(queueItemId=1050204)?$orderby=CreationTime%20desc

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/$metadata#QueueItemComments",
    "@odata.count": 2,
    "value": [
        {
            "Text": "needs review asap",
            "QueueItemId": 1050204,
            "CreationTime": "2018-03-08T13:41:49.167Z",
            "UserId": 583,
            "UserName": "admin",
            "Id": 320
        },
        {
            "Text": "fixed. excel hiccup.",
            "QueueItemId": 1050204,
            "CreationTime": "2018-03-08T13:46:48.613Z",
            "UserId": 901,
            "UserName": "dragomirmir",
            "Id": 321
        }
    ]
}