You can use the API block in workflows to make calls to external endpoints. And, you can use the API block to transform key data, such as the status of a SaaS user's account, into consumable information and actionable insights.

Creating a workflow

Before you begin working with the Oomnitza block, you need to create a workflow.

To create a workflow, complete the following steps:

From the menu, click Configuration > Workflows.
Click Add (+).
Search or choose an object such as Users or Assets from the list.
Enter the name and a description of the workflow.
Click the Blocks tab, and drag and drop the API block onto the canvas.
Click Edit .

Choosing a preset

To easily interact with integrations, you can use presets. For example, you can use Jira presets to retrieve detailed user information, onboard and offboard users, retrieve SaaS user roles, and so on. Presets have all the information that is required to make the API request, such as the URL, headers, parameters, and request body.

Tip
If you prefer to create your own API request, skip this section and read the next section Using the advanced mode.

To choose from a list of presets, complete the following steps:

Enter the name of your integration in the Select Preset search field and choose a preset.
To select your preset, click the right arrow >.
Add the required information in the Configure section .

Tip
Click the documentation link to learn more about the configuration steps.

Using the advanced mode

To create or modify the message URL, body, or response, click Advanced Mode .

Information

The INFORMATION tabbed page contains the information that is required to make the API request.

Field name	Description
Name	Edit the name of the block so that it adequately describes its purpose, such as Fetch Jira tickets.
HTTP Methods	The API block supports the following HTTP methods, POST, GET, PUT/PATCH, and DELETE. These methods correspond to create, read, update, and delete or CRUD operations.
URL	The target URL for the API call, such as `https://app.betterworks.com/api/v1/user`

Authorization

The AUTHORIZATION tab contains the authorization credentials for using the API.

Field name	Description
Mode	Select either Static or Dynamic. Static enables you to choose from a list of available options. Dynamic enables you to look up the credentials in your instance.
Type	Select Dynamic to choose a field from the list which has the name of the credentials as its value. The credentials name must match the credentials name in Configuration > Security > Credentials. For example, you have a field called Credentials name, which has the value Jira OAuth credentials. When the workflow is triggered, the system checks for credentials matching the name Jira OAuth credentials from the list of credentials in Configuration > Security > Credentials. Select Static to choose an available authorization type from the list.
Credentials	Choose the credentials corresponding to the authorization type that you have added in Configuration > Security > Credentials.

Params

Optional. The PARAMS tabbed page contains the parameters for the API call.

Headers

The HEADERS tabbed page contains the headers that are required for the API call. The hidden headers are included in all the calls that are made by the API block.

Body

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

Field name

Description

Body types

Choose one of the following options:

raw. Send raw JSON data.
form-data. Set key/value pairs using the key-value editor for your data

Body

Click Select a field to update the message body with a value from an existing field. For example, the following raw JSON data can be updated to refer to the email and phone number fields.

{
"email": {{email}}, 
"contact": {{phone_number}},
"department": "HR"
}

Using Jinja in the message body

Enhance and customize your request body using Jinja2 templates.

➢ 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.
Enter a sample value for evaluation.
The output should automatically generate.

Validation

The VALIDATION tabbed page contains the timeout for the call, the number of retries, the retry frequency, and the interval between retries.

The Response validation section determines whether an API response will be positive or negative. 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 401 Unauthorized response is received. The workflow will fail with errors.

Response Code	Description
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

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.
You can 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.location_id}} , or {{profile.user[0].name}}
You have the option to use dot or bracket notation when targeting nested values, such as {{response.location_id}} or {{response["location_id"]}}.
You can access the complete response header by inserting {{response_headers}} in the Response field.
You can target individual values in the response header similar to the response body, such {{response_headers.Vary}} and {{response_headers.Connection}}.
Restriction: In the unusual circumstance where there is a hyphen in the response, use the following bracket notation: {{response_headers["X-Total-Count"]}}{{response["test-field"]}} or {{response_headers["Content-Type"]}}, otherwise, the workflow will fail to run successfully.
You can hardcode values in the Response field by entering a value without brackets.
You can 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.

Tip
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]].

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 new record is added and when a record is edited or archived. You can also configure the schedule to run at a specific time by selecting Schedule.
2. Optional. In the Rule criteria section, you can add a rule to trigger the workflow. For example, the Status is set to Active, or the Email address is helen.troy@oomnitza.com.
Validate the workflow and Activate it so that the workflow is live in your system.

Using the API block