Action Field Definitions
  • 18 Nov 2022
  • Dark
  • PDF

Action Field Definitions

  • Dark
  • PDF

Article summary

Every action in the an action.json file can be defined with the following information. This information should be auto-populated by the Adapter Builder, but there are circumstances where the Adapter Builder may not be able to derive the information from the provided OpenAPI document - thus, the information may be defaulted.

Field Required Definition
name Yes This is the name of the action which must be unique within the adapter as it relates to method names in the action.json. The Adapter Builder will use the operationId within the OpenAPI if that is available, otherwise it will make the method unique by using the method and path of the endpoint. When the method in adapter.js wants to take this action in the other system, it calls identifyRequest and provides the entity (first parameter) that this action is in and the name (second parameter) to identify the particular action.
protocol Yes REST is currently the only protocol supported but this field can support others. SOAP would still use REST as it makes an HTTP/HTTPS POST call.
method Yes This is the REST method (sometimes referred to as a verb) the call uses. The most common are GET, POST, PUT, PATCH and DELETE but others are supported as well.
entitypath Yes This is the path that is added to the API call – https://host:port/entitypath. It is the added part of the call. You will notice it has variables in it {base_path}. These variables are replaced by the adapter library when the call is made.

This value can either be a string or an object. When supporting multiple paths for the same task, enititypath is an object with key as the version. The user can set this version in the choosepath property within the IAP Service Instance Configuration for the adapter (for example "choosepath":"v1"), which will tell the adapter which path to pick when that task is called. If this key is not defined the adapter will pick the first path by default.
schema Yes (if no specific schemas) Default schema used for both the request and response, unless overridden by a specific schema.

This field is used to define the data that is sent between the adapter and the other system. You can have a different schema definition for every call in an action file. You may also have different schemas for the request and the response. Consequently, you may see various schema files within an entity.
requestSchema Yes (if no general schema) Defines a schema specific to the request.
responseSchema Yes (if no general schema) Defines a schema specific to the response.
timeout No -> 0 While the adapter provides a property to set a global timeout, sometimes a particular action may take a long time. This property provides the ability to set a timeout on the action which overrides the global timeout

If no value is provided or it has a value <= 0, the global request timeout will be used.
sendEmpty No -> false This flag tells the adapter when there is no information to send that is should still send an empty object (e.g.{}). Some systems will require this in order to work.
sendGetBody No -> false This flag tells the adapter whether to send a body on a GET request. Typically no data is sent on GET request but some systems will want a body on a GET request, this allows the adapter to do that.
datatype No -> JSON This required field is used to define the type of data that is sent between the adapter and the other system. Can be used for the request or response, or both. Similarly to schemas, you may have different datatypes for the request and the response.

Some example datatypes include PLAIN, XML, XML2JSON, URLENCODE, FORM and JSON.

URLQUERY is an accepted datatype for token which will have the token data passed in url instead of the body.
requestDatatype No -> JSON Defines the datatype of the request.
responseDatatype No -> JSON Defines the datatype of the response.
headers No -> {} Many systems may require additional headers, and there are several ways to specify headers on the request. If the headers are always the same for a particular action, specifying them on the action is the best method. Other ways to specify headers include:

Global request properties– These headers are consistent on all requests. This will be overriden for an action if you specify headers in that action.

Additional headers– These headers can be static for a call or dynamic by allowing them to be set based on user input.

Some headers (e.g. Content-Type and Accept) are set by the adapter libraries based on the datatype, but those can be overridden if you specify them elsewhere.
responseObjects Yes Tells the adapter how to handle the response. Some actions may have many responses, so this field is often used for different purposes.

First, it provides a way to tell the adapter where in the response to find the data that IAP cares about.

Second, this field is crucial for standalone testing because it tells the adapter libraries where to find mock data that it should return when not integrated with the other system.
responseObjects.type Yes Used by the adapter libraries to identify which response object to use. The adapter libraries will go through a hierarchical process to match the best response type for a specific request. This field is required. There should always be a response object with the type default which can be used when no other response object matches to the call that was made.
key Yes, but can be empty Used by the adapter libraries to tell the adapter where in the response to find the data that IAP is concerned with. It supports JSONquery. It allows you to remove metadata, etc. and only return the data that you really care about.
mockFile Yes, but can be empty This is used by the adapter libraries when running in stub mode (not integrated) to tell the adapter where the mock data that should be returned is located. It is the relative path to your mock data file.

Sample action.json

      "name": "getIP",
      "protocol": "REST",
      "method": "GET",
      "entitypath": "{base_path}/{version}/addresses/{pathv1}",
      "requestSchema": "schema.json",
      "responseSchema": "schemaReturn.json",
      "timeout": 3000,
      "sendEmpty": true,
      "sendGetBody": false,
      "requestDatatype": "PLAIN",
      "responseDatatype": "XML2JSON",
      "headers": {
        "Content-Type": "application/text"
      "responseObjects": [
          "type": "default",
          "key": "",
          "mockFile": "mockdatafiles/getIP-default.xml"

Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.