Overview
Oomnitza's API workflow block is one of Oomnitza's most powerful and unique tools. It not only lets you make calls to external endpoints but can also be used to make calls to Oomnitza's own API, effectively functioning as an advanced extension of the Update Workflow Block.
With Oomnitza Version 5.0, this block has been enhanced to be even more powerful.
Contents
The API Workflow Block
Much like Oomnitza's other Workflow blocks, the API Workflow acts after the parameters set in the Begin block. Unlike other blocks, rather than affect a pre-set object, you can use the API block to make changes to nearly anything with a public API.
With the correct implementation, you can use do things not otherwise possible through Workflow Blocks.
Making Calls to External Services
The primary purpose of the API Block is to allow changes in Oomnitza to trigger changes in any external system that allows it.
This also allows you to use workflows much like you would webhooks, in order to effectively create a subscription to any set of changes you opt to isolate in the Begin Block.
While not obvious at first, this can greatly expand Oomnitza's reach, allowing it to not only aggregate data on all of your things but also allow those changes to dictate changes in other systems.
Configuring the API Block
Adding Metadata
What good is an API call if it can't contain information from Oomnitza? The API block allows for the addition of metadata in calls. Whenever you see a field with the {...} button ( 
) you can select a field to include from the object that triggers the workflow.
You can also add metadata manually by putting the desired field's external id between sets of double curly brackets. For example {{serial_number}} will evoke the serial number for that asset. A fields external ID can be checked by selecting that field on the customization page.
This is particularly useful in the URL for specifying a location for the call based on an object's unique identifiers, or in the body for assembling the payload itself.
Information
The information page is where you specify the name of the block (API block by default), the type of call being made (GET, POST, PATCH, PUT, DELETE), and the URL where the call is being made to.
Authorization
The authorization block lets you specify how to authenticate with the external API. The current options are Basic Auth and API Key. OAuth will be added in future versions.
Params
Allows you to specify parameters for your API call.
Headers
The headers included in your API call. The Hidden headers are included with all calls made by the Oomnitza API Block.
Body
The body tab is used to construct the content of the API payload. We allow for raw body data, or key: value form-data payloads.
Validation
Aside from the sleek new interface, one of the biggest enhancements in the new workflow block is the ability to validate responses. This block allows you to set a timeout on the call, specify the number of retries and a retry frequency, and specify a time between retries.
Additionally, you can specify paths for your responses, which is useful for notifying Oomnitza Administrators if an API call fails.
Response
The Response tab allows you to map responses from the API into fields in Oomnitza. This allows you store response data from your API Calls, enabling more robust bidirectionality within the API Block. Uses include retrieval and storage external IDs to allow for downstream updates to external systems, and a far wider range of bidirectionality that afforded by the API Block and Connectors alone. To accomplish this we introduced the response object which you may query for certain attributes to find the specific attribute you want to map to a variable within the workflow object.
To map a response from the REST API, enter the name of the attribute you wish to retrieve in curly brackets, as so {{response.location_id}}. You have also access to the entire response by simply referring to {{response}}, which will capture the entire response in Json or XML in your object attribute. This is a good way to capture the entire response from the webservice call for further evaluating which parts you may want to capture in Oomnitza. Values can also be hardcoded by entering a value without brackets. Once the field has been specified, select the Oomnitza field you wish to map it to on the right.
Please note that the API block currently only supports mapping of a single response object not a collection or list. You can find more details on mapping responses here.
Using Preset API Blocks
The other major enhancement in Oomnitza's New API block is the inclusion of Presets API configurations. Systems like Jira and Zendesk are common targets for API blocks, as is Oomnitza itself. Starting with Versio 5.0 Oomnitza has begun maintaining a catalog of external API configurations, to make it easy to set up interfaces with external systems:
Creating Cascading Workflows
With the exception of scheduled begin blocks, Oomnitza workflows will not trigger other workflows. While this prevents the accidental creation of infinite loops, it prevents users from creating Cascading workflows. The API block is an exception to this rule.
By using an API block to make changes to your own Oomnitza instance, your changes will trigger subsequent workflows, allowing for cascades of changes.
0 Comments