In workflows, you use the API block to make calls to a vendor application's external endpoints.
Contents
Creating a workflow
- From the menu, click Configuration > Workflows.
- Click Add (+).
- Select an object such as users or assets.
- 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
.
Selecting a preset
You use presets to interact with third party applications. 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 the information that is required to make an 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 Using the advanced mode.
To select presets, complete these steps:
- Enter the name of the integration in the Select Preset search field and select a preset.
- Click the right arrow >.
- In the Configure section, add the information.
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 to make the API request.
Field name | Description |
Name | Make sure you edit the name of the block to describe the action that the API block completes such as Fetch Jira tickets. This will make it easier to troubleshoot issues should any arise. |
HTTP Methods |
The API block supports the following the Post, Get, Put, Patch, and Delete HTTP methods. |
URL |
The target URL for the API call, such as |
Authorization
The AUTHORIZATION tab contains the authorization credentials for making the API request.
Field name | Description |
Mode |
You can select static or dynamic. |
Type |
Static When you select the static mode, you can select the type of authorization from the Type list. Dynamic When you select the dynamic mode, you select a field from the list which is the name of the credentials that were created on the Configuration > Security > Credentials page. Example You have a field called Credentials name that 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 on the Configuration > Security > Credentials page. |
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 usually required in Put and Patch operations.
Field name | Description |
Body types |
Choose raw to send raw JSON data. Choose form-data to set key/value pairs using the key-value editor for your data. |
Body |
Click Select a field { |
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 might want to know:
- 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
Enter the name of the field in 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.
- The output is automatically generated.
Validation
The validation tabbed page contains the timeout for the call, the number of retries, the retry frequency, and the interval between retries.
To improve the performance of workflows and avoid bottlenecks, retires are only attempted when a retry can result in a positive outcome. See HTTP response codes.
The response validation section determines whether an API response is positive or negative. When an API response is positive, the workflow passes the validation test. If the API response is negative, the workflow fails the validation test.
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.
Table: HTTP response codes
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 To optimize performance, retries are only attempted when the following HTTP responses are received:
|
5XX |
Includes all 500 server error responses such as Retries are attempted for all HTTP 500 responses. |
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 can use dot or bracket notation to target 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
To ensure that the workflow runs successfully, use the following bracket notation if the response contains a hyphen:{{response_headers["X-Total-Count"]}}
{{response["test-field"]}}
or{{response_headers["Content-Type"]}}
. - 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 %}
.
Selecting an Oomnitza field
When the Response field is specified, select the Oomnitza field or variable that you want to map to.
Running the workflow
- Click Save and connect the blocks
-
Edit the Begin block.
- 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.
- 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.
Related Links
Adding credentials to the Oomnitza vault
Mapping positive and negative responses
Comments
0 comments
Please sign in to leave a comment.