What are queue schemas and how to use them

News Vote on Tutorials
,
1

Queue Schemas are something that often seem to confuse UiPath developers, but hopefully after reading this post you will fully grasp how to use them, what they actually do and how to write a well formed JSON schema.

Various data points stored on a Queue Item is stored in a JSON format and we can use a JSON Schema to validate that data is well formed. The validations can be simple to ensure the correct data type is used or contain more complex detail validations.

What is a JSON Schema?

A JSON Schema is a way to define rules for the structure and content of JSON data. It acts as a blueprint, outlining the expected properties, types, and relationships within JSON objects. By providing validation and documentation, JSON Schema ensures data consistency, aids communication between teams, and helps prevent errors in applications and APIs. It uses keywords like type , properties , and required to specify data expectations. For instance, a simple JSON Schema can define that an object must have a “name” property as a string and optionally an “age” property as a non-negative integer. This schema is then used to validate incoming JSON data, ensuring it matches the expected format.

There are 3 schemas we can add to a queue, each to validate a different property.
image

The specific data schema is evaluated when a queue item is added and evaluates that the data provided as the input, when using the ‘Add Queue Item’ activity this corresponds to the ‘Item Information’ field
image

If the data added doesn’t match the expected schema then you will get an error trying to add the queue item and it will fail to add.
This can be useful if you want to enforce that some fields are always present on a queue item before it gets added.

If we apply this to a practical example, lets image a queue that requires queue items to contain details of employees and needs to know their first name, surname and email address & role. We will use the following keys:
“Firstname”
“Surname”
“EmailAddress”
“Role”

optionally we’ll include a 5th field for role with the key
“Location”

Adding a new queue item could look like this

image
image655×661 73 KB

If we wanted to validate that all queue items added followed pattern described above we would use the following schema:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/root.json",
  "type": "object",
  "title": "Employee Queue Schema",
  "additionalProperties": { "type": "string" },
  "required": [
    "Firstname",
	"Surname",
	"EmailAddress",
	"Role"
  ],
  "properties": {
    "Firstname": {
      "$id": "#/properties/Firstname",
      "type": "string",
      "title": "Firstname",
      "default": "Joe",
      "examples": [
        "Joe", "Jon", "Jane", "Betty"
      ]
    },
	"Surname": {
      "$id": "#/properties/Surname",
      "type": "string",
      "title": "Surname",
      "default": "Bloggs",
      "examples": [
        "Smith", "Bloggs", "Brown", "Doe"
      ]
    },
	"EmailAddress": {
	  "$id": "#/properties/EmailAddress",
	  "type": "string",
	  "title": "EmailAddress",
	  "default": "example@example.com",
	  "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$",
	  "description": "A valid email address in the format 'user@example.com'"
	},
	"Role": {
	  "$id": "#/properties/Role",
	  "type": "string",
	  "title": "Role",
	  "default": "Employee",
	  "enum": ["Employee", "Manager"],
	  "description": "Valid values are 'Employee' or 'Manager'"
	},
	"Location": {
	  "$id": "#/properties/Location",
	  "type": "string",
	  "title": "Location",
	  "default": "Head Office",
	  "description": "Optionally indicates the office the employee works from."
	}	
  }
}

This schema ensures certain fields are always provided by specifying them in the required section, because we ommitted to include ‘Location’ it is considered an optional field. The Orchestrator does not consider the default value so if you do not provide an input this key will not be present on a queue item.
If you try to add a queue item that do not contain keys for any of the values in the 'required section then you will get an error and won’t be able to add the queue item.

Furthermore you can see that each field has some specifications on it, each has a data typing. All our fields are simple string fields but there is handling for basic JSON types such as integer, boolean and DateTime to ensure the correct data type is used.

We can also validate the value provided matches a regex or against an expected list of values.
The email address contains a regex which ensures it is a valid email.
The role contains a list of accepted values limiting its input.

Hopefully you can see how this can enforce a certain structure which can be used to make sure that dispatchers and performers stay in sync or that badly formed queue items do not get into your queue and cause a mess.

The other two schemas serve the exact same purpose but are evaluated when a queue item is completed. If the output or analytics data set during the set transaction status activity don’t match the schemas provided there then the queue item will be set to failed as a business exception.

7 Likes