Action Field Definitions

Updated on 18 Nov 2022

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

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

Usage Examples

Table of contents