Use the Oomnitza block in workflows to make calls to our internal API, enabling a wide range of tasks to be performed efficiently. This includes retrieving run logs and change histories, performing bulk create, update, and delete operations on records, as well as querying across different objects. For instance, when using the Oomnitza API block in an asset workflow, you can retrieve specific fields from related objects, such as extracting a user’s department from the user object to store it within a field on the Asset.

Configuring the Oomnitza block
1. Information
2. Body
3. Validation
4. Response
5. Headers
Running the workflow
Troubleshooting

Prerequisites

Create a workflow in the Configuration > Workflows menu.

Configuring the Oomnitza block

Click the Blocks tab, and drag and drop the Oomnitza block onto the canvas.
Click Edit .

Information

Field name	Description
Name	Enter a name for the Oomnitza block, such as Fetch Oomnitza Accessories
Module	Choose from a list of available modules.
URL	Based on your module selection, you are presented with a list of available API calls.
HTTP Methods	The Oomnitza block supports the following HTTP methods, POST, GET, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively
Path params	Defines the resource location. For some GET requests, you will be asked to supply the `{ident}`or ID of the record. For example, this could be a Location ID for Locations, an Equipment ID for Assets, or other specific identifiers depending on the type of object you're querying. All other path parameters can be found in: Oomnitza block: Path parameters
Query Params	Defines the sort, pagination, or filter operations. For detailed information see: Oomnitza block: Query parameters

Body

The BODY tabbed page contains the request body. The request body is typically required in PUT/ PATCH operations.

The body type is set to send raw JSON data. You can use Jinja2 templating to modify values in your request body.

➢ Use the Assistant

You can ask the assistant for help generating Jinja code. For example, you may wish to ask:

How do I replace LX with XX in a field?
How do I remove XX from a field?
How do I multiply a decimal field by 10.0?
How do I convert a field to upper case?

Using the Assistant to generate Jinja code

➢ Input variables

Manually enter the name of the field into the editor or click Select a field to retrieve field values. You can access the following field values:

Data Model fields as{{barcode}} or {{email}}
Values from global settings
Workflow variables

➢ Test your Jinja code

Click Test Run.
Input a sample value to test your code.
The output should automatically generate.

Important
In some POST/ PATCH operations, the body is pre-populated with JSON schema. This schema defines the format for what JSON data is required. It should not be confused with the JSON data required to make the request. For an example of live sample JSON data that you can use in the request body, refer to the Oomnitza block: Sample JSON requests

Validation

Enables you to define positive and negative API responses. By default, all 100-399 response status codes are mapped to the positive response and all 400-599 response status codes are mapped to a negative response. When an API response is positive, the workflow will pass validation. If the API response is negative, the workflow will fail validation.

For example, let's say 2XX is treated as positive, 2XX: Positive, and a 200 OK response is received. In this case, the workflow will run successfully. Conversely, if a 4XX is treated as negative 4XX: Negative and a 404 NOT FOUND response is received the workflow will fail with errors.

1XX	Includes all 100 information responses such as `102 Processing`
2XX	Includes all 200 successful responses such as `200 OK` or `201 Created`
3XX	Includes all 300 redirection responses such as `301 URL moved permanently`
4XX	Includes all 400 client error responses such as `401 Unauthorized` , `403 Forbidden` and `404 Not found`
5XX	Includes all 500 server error responses such as `500 Internal Server Error`and `502 Bad Gateway`

Response

You can map both positive and negative JSON responses to the Oomnitza fields in the Response tab.

Adding the Response field

By default, some Response fields are automatically created for you. You can remove the fields that you don't want to use by clicking Remove response mapping item .

When adding Response fields, you can:

Access the complete response body by inserting {{response}} in the Response field, which captures the response in JSON or XML in your object attribute.
Target nested fields in the response body by appending the JSON path of the attribute that you want to retrieve in the Response field, such as {{response.accessory_name}} , or {{profile.category}}
Use dot or bracket notation when targeting nested fields, such as {{response.category}} or {{response["category"]}}.
Access the complete response header by inserting {{response_headers}} in the Response field.
Target individual values in the response header similar to the response body, such {{response_headers.Vary}} and {{response_headers.Connection}. Restriction: For values where there is a hyphen in the response, use the following bracket notation: {{response_headers["X-Total-Count"]}} or {{response_headers["Content-Type"]}}, otherwise, the workflow will fail to run successfully.
Hardcode values in the Response field by entering a value without brackets.
Use Jinja2 templating to add rules to your response in the Response field. For example, {% if response and response.id %}{{ response.id }}{% else %}{% endif %}.

Choosing an Oomnitza field

When the Response field is specified, select the Oomnitza field or variable that you want to map to.

When mapping the entire response body, ensure that the field you are mapping the response to has a sufficient character limit. Otherwise, the workflow will fail with the following error: Length of the field [[name]] should be less than [[no of characters]].

Headers

You can use Oomnitza API Headers to update read-only fields, add additional fields, and prevent workflows from running.

Note

The Oomnitza block has a predefined value of Oomnitza-Not-Trigger-WF:1 set for the header. This value is designed to prevent other workflows from triggering. If you are planning on chaining together workflows, set this header to 0.

Oomnitza API Headers

Running the workflow

Click Save and connect the blocks
Edit the Begin block.
1. From the Actions dropdown, select when your workflow is triggered. You can trigger workflows to run when a record is new, edited, archived, or at a specific time by selecting Schedule.
2. Optional. In the Rule criteria section, add a rule to trigger the workflow. For example, the Status is Active, or the Email address is helen.troy@oomnitza.com
Validate the workflow and Activate, so that the workflow is now live in your system.

Result
To check your response mapping, open one of the records that meet the criteria specified in the Begin block, and click History in the side pane. All actions performed by the block will be logged under the name OOMNITZA Workflow.

Troubleshooting

If your workflow fails with an error, you can retrieve details of the error by mapping the Negative response in the Response tab. Insert {{response}} in the Response field to retrieve the complete response body.

Common error codes	Reason
`400 Bad Request`	Bad request or issue with the message body. Ensure that the message Body is formatted correctly. For example, there may be an additional comma in the message body.
`409 Conflict`	These conflicts are most likely to occur in response to a POST/PUT/PATCH request and indicate that you are trying to do something that is not permitted such as using supplying a string instead of a date value, or updating a dropdown field with a value that does not exist. Check your request Body in Advanced Mode.