Mapping positive and negative responses

Get responses for negative and positive outcomes for API blocks when a workflow completes.

Use the Response tab in the API block to map positive and negative API responses. To map a response in the API block, you must specify the path for the JSON response and map it to a field in Oomnitza.

Identifying the JSON path

The response body is stored in the {{response}} object and can be accessed by appending the JSON path to the {{response}} value, for example, {{response.field_name}}. The response value must be enclosed in double curly brackets.

Nested fields use dot or bracket notation such as {{response.profile["field_name"]}} or {{response.profile.field_name}}.

For example, if the data coming from the source system is:

{
    "profile": {
        "first_name": "Helen",
        "last_name": "Troy"
    },
    "status": "Active"
}

To access the first_name you can use the following notation:

{{response.profile.first_name}}
{{response.profile["first_name"]}}

To access the last_name you can use the following notation:

{{response.profile.last_name}}
{{response.profile["last_name"]}}.

To access the statusyou can use the following notation:

{{response.status}}
{{response["status"]}}

Important
In the unusual circumstance where there is a hyphen in the response, use the following bracket notation: {{response["test-field"]}, otherwise, the workflow will fail to run successfully.

The response header is stored in the {{response_header}} object and can be accessed similarly to the response body.

For example, if the data coming from the source system is:

 {
  "Server": "nginx",
  "Date": "Wed, 08 Feb 2023 15:44:48 GMT",
  "Content-Type": "application/json",
  "Connection": "keep-alive",
  "Vary": "Accept-Encoding",
   "X-Total-Count": "281"
}

To access the VaryConnection or Date value in the response header you can use the following notation:

{{response_headers.Vary}}
{{response_headers.Connection}}
{{response_headers.Date}}

For values where there is a hyphen in the response, such as X-Total-Count or Content-Typeyou need to use bracket notation, such as:

{{response_headers["X-Total-Count"]}}
{{response_headers["Content-Type"]}}

Mapping values to Oomnitza fields

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

In the Validation tab, you can 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.

To map a response, specify the JSON path in the Response field and map it to a field in Oomnitza.

This is an example of a 200 OK positive response body that is mapped to fields in Oomnitza:

{
	"name": "Aaron Levie",
	"notification_email": {
		"email": "notifications@example.com",
		"is_confirmed": "true"
	},
	"phone": "6509241374",
	"status": "active"
}

Tip
You can hardcode values in the Response field by entering a value without brackets.
You can use Jinja2 templating in the Response field to add rules to the response, for example: {% if response and response.id %}{{ response.id }}{% else %}{% endif %}

Troubleshooting

If you don’t know what response you’ll get, or if an error occurs, you can retrieve the complete response body by inserting {{response}} in the Response field, which will capture the response in JSON or XML in your object attribute.

Similarly, if you are not aware of the values stored in the response header, you can retrieve the complete response header by inserting {{response_headers}} in the Response field.

You can map negative responses in the Response tab to get a clearer idea of an error. In this example, the 400 Bad Request, a negative response, is mapped to a custom long text field in Oomnitza. The response is mapped to a long text field to ensure that there is sufficient space to capture the entire response.

{
  "type": "error",
  "code": "item_name_invalid",
  "context_info": {
    "message": "Something went wrong."
  },
  "message": "Method Not Allowed",
  "request_id": "abcdef123456",
  "status": 400
}

Important
The response must be a JSON response and not an empty string such as NOT FOUND, otherwise, your API block will fail with errors.

Related Links

Creating custom fields