Configure headers

Adapters automatically add Content-Type and Accept headers based on the requestDatatype and responseDatatype defined in action.json. They also calculate and add a Content-Length header to any call that includes a payload. Both can be overridden. Authentication headers should be configured through auth_field and auth_field_format in the service instance configuration — not through the methods described here.

Choosing where to add a header

The right place to add a header depends on two questions:

1. Is the header value static (the same on every call) or dynamic (different per call)?
2. Should the header apply to a specific call or to all calls?

Both static approaches override the headers the adapter sets automatically from requestDatatype.

Static headers

To add a static header to a specific call, define it in the headers object in action.json. See Action field definitions for details and examples.

To add a static header to all calls, define it in global_request.addlHeaders in the service instance configuration. See Request properties for details and examples.

Dynamic headers

To add a dynamic header — one whose value is not known until the call is made — pass it in addlHeaders on the reqObj in adapter.js. This requires exposing a parameter in the adapter method and in pronghorn.json to accept the dynamic value.

If the adapter method exposes an iapMetadata object, you can pass dynamic headers through that object without any code changes. See Add dynamic headers for details and examples.

title: Add dynamic headers sidebar-title: Add dynamic headers slug: headers/add-dynamic-headers description: How to add headers with values that are not known until call time, using iapMetadata or adapter.js code changes.

A header is dynamic when its value is not known until the call is made. Static header configuration in action.json or the service instance configuration cannot accommodate this — the header value must be supplied at call time.

Using iapMetadata (no code change required)

If the adapter method exposes an iapMetadata parameter, pass the headers inside an addlHeaders object on that parameter. You can construct the iapMetadata object usingItential Platform workflow capabilities such as query and merge.

Structure:

1
{
2
  "addlHeaders": {
3
    "<header1_name>": "<value1>",
4
    "<header2_name>": "<value2>"
5
  }
6
}

Example:

1
{
2
  "addlHeaders": {
3
    "x_custom_header": "63121931219fdd",
4
    "Session-id": "AB9637462349"
5
  }
6
}

If the adapter method does not have an iapMetadata parameter, you can request that the Adapter Team add it. Note that adding iapMetadata requires creating new methods — Itential does not modify existing method signatures to avoid breaking changes.

Using adapter.js (code change required)

If the adapter does not support iapMetadata, you can expose the dynamic header value as a parameter in the adapter method and set it in addlHeaders on the reqObj. This approach also requires updating pronghorn.json to match the new method signature.

See Call properties authentication for an example of this pattern applied to authentication, which follows the same approach.

Static headers

If the header value does not change between calls, use the static header options instead.