Using the API block

Overview

You use the API block in workflows to interact with external endpoints and the Oomnitza API.

Contents

• API workflow block
• Making calls to external services
• Configuring API blocks
  • Adding metadata
  • Information
  • Authorization
  • Params
  • Headers
  • Body
  • Validation
  • Response
• Using Presets in API blocks
• Creating cascading workflows

API workflow block

Like other workflow blocks, the API block is triggered by the schedule, or rules, or both that are set up in the Begin block. Unlike other workflow blocks, the API block can interact with and complete actions in integrations with public APIs.    

Making calls to external services

The purpose of the API Block is to allow changes in Oomnitza to trigger changes in any external system that allows it. When you use API blocks, you can transform key data changes, such as the status of a SaaS user's account, into actionable insights that reduce costs and automate complex tasks.

Configuring API blocks

To configure an API block, edit the API block and click the Advanced Mode button located in the upper right of the window.

Adding metadata

API blocks allow you to to add metadata in calls. Whenever you see a field with the {...} button, you can select the Object field that you want to include to trigger the workflow.

You can also add metadata manually by adding the object field's external ID between two sets of curly brackets. For example {{serial_number}} will evoke the serial number for the asset. 

Find field ID
To find the ID for an asset field, click Assets > Customization, and click a record. At the bottom of the page, the field ID and external ID are listed. 

Information

On the INFORMATION tabbed page, you specify the name of the block, which by default is called API block, the type of HTTP method, such as GET, POST, PATCH, PUT, or DELETE, and the target URL for the call. 

Authorization

On the AUTHORIZATION tabbed page, you select the type of authentication that is used, such as API key or OAuth 2.0, to communicate with the external API. And, you select the credentials that you added to the Oomnitza vault for the integration .  

Parameters (params)

On the PARAMS tabbed page, you add the parameters for your API call. 

Headers

On the HEADERS tabbed page, you include the headers in your API call. The hidden headers are included in all calls that are that are made by the Oomnitza API block.

Body

On the BODY tab, the content of the API payload is specified. You can specify raw body data or a key  such as key: value form-data payloads. 

Validation

On the VALIDATION tabbed page, you can set a timeout for the call, the number of retries, the retry frequency, and specify the interval between retries.

To notify Oomnitza Administrators when an API call fails, you can also specify paths for responses .

Response

On the RESPONSE tab, you can map responses from the API to Oomnitza fields, which allows you store response data from API calls, thus enabling robust bidirectionality between the API block and the target system. Supported uses include the retrieval and storage of external IDs which can enable downstream updates to external systems, and a far wider range of bidirectionality than that afforded by the API Block and integrations by themselves. The response object can be queried to find the specific attribute that you want to map to the variable in the workflow object.

To map a response from the REST API, you enter the name of the attribute that you want to retrieve in like this {{response.location_id}}.

To access the complete response, you refer to {{response}}, which captures the response in Json or XML in your object attribute. You can capture the complete response from the web service call so that you can determine which parts of the response that you want to capture in Oomnitza. Values can be hard coded by entering a value without brackets. When the field is specified, select the Oomnitza field that you want to map to.

Information
The API block supports the field-to-field mapping of a single response, but not collections or lists.
 Mapping response variables

Using presets in API blocks

To easily interact with integrations, you can use presets. For examples, external systems like like Jira and Zendesk are common targets for API blocks, as is Oomnitza. 

Creating cascading workflows

By using an API block to make changes to your own Oomnitza instance, your changes will trigger subsequent workflows, allowing for cascades of changes.