Usage Examples

Entity Path Variables

Entity Path Variables provide the adapter with ways to add common and dynamic information into every call in the adapter. The following list defines entity path variables used in an action.json file.

• Common Variables
  • {base_path}: Replaced with the base_path property in the IAP Service Instance Configuration for the adapter. Allows for easier maintenance if the base path changes.
  • {version}: Replaced with the version property in the IAP Service Instance Configuration for the adapter. Allows for easier maintenance if the version changes.
• Dynamic Variables
  • {pathv#}: Replaced with the path variables provided in the uriPathVars array in the individual request. This is information passed into the adapter method from IAP Workflow or another source when making the call.
    • pathv1 corresponds to the 1st (0) element in the array, and so forth.
  • {query}: Replaced with any information provided in the uriQuery object on the individual request. The adapter library automatically assigns a query string to this object and adds it to the end of the path.

{
  "name": "getDeviceInterface",
  "protocol": "REST",
  "method": "GET",
  "entitypath": "{base_path}/{version}/device/{pathv1}/interface/{pathv2}?{query}",
  "requestSchema": "schema.json",
  "responseSchema": "schema.json",
  "timeout": 3000,
  "sendEmpty": true,
  "sendGetBody": false,
  "requestDatatype": "PLAIN",
  "responseDatatype": "XML2JSON",
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": ""
    }
  ]
},

Entity Path Examples

Given these paths

"entitypath": "/api/v1/devices"

"entitypath": "/api/v1/devices/{pathv1}"

"entitypath": "/api/v1/devices/{pathv1}?{query}"

"entitypath": "/api/v1/devices/{pathv1}/interface/{pathv2}?{query}"

The first path is not altered at all by the adapter libraries. It is simply going to be /api/v1/devices.

The first path might work for getting all devices, but what about a specific device based on an id? Since there is no place to provide the specific id, it will not be able to work. In that case, we have the second path. This path now takes in an id that will be provided to the adapter and can be different each time this call is made. The resulting enpoint can be /api/v1/devices/abc123 on one call and then /api/v1/devices/def456 on the next call. Many systems work this way but some will use query parameters to filter based on criteria like ids.

The third path adds the ability to provide query parameters on the call. Inside the action.json you only need the {query} on the entitypath. The information contained in the query will be based on the information provided on the call in the adapter.js. Query information can include what information to look for or what information you want in the response. Therefore, in the case of the third path, the actual call to the other system may look like /api/v1/devices/abc123?return_field=name,id,interfaces

What if I have multiple path variables? The adapter supports many path variables (fourth path) where the # corresponds to the element in the uriPathVars array less 1 (pathv1 -> 0, pathv2 -> 1 etc.). Generic calls are wired with as many as 20 path variables. There is not technically a limit on path variables, however, it is uncommon to see calls with that many path variables. The result of the fourth path may be a call such as: /api/v1/devices/abc123/interface/eth_101

"entitypath": "/api/{version}/devices/{pathv1}?{query}"

"entitypath": "/api/v2.0/devices/{pathv1}?{query}"

You can hard code the version in a specific action call and in all action calls. However, it is easier to maintain/upgrade to a new version if this is set in the version property within the IAP Service Instance Configuration for the adapter. Then the entity path will look more like the first path above.

You can still support unique actions that use a different version by hard coding that version in the second path. This allows the adapter to support integrations to many different versions of APIs by simply using a property for the predominant version and then hard coding other versions.

"entitypath": "/{base_path}/{version}/devices/{pathv1}?{query}"

"entitypath": "/{base_path}/v2.0/devices/{pathv1}?{query}"

"entitypath": "/api/{version}/devices/{pathv1}?{query}"

"entitypath": "/api/v2.0/devices/{pathv1}?{query}"

Base Path works like version; you can hard code the base_path in any and all action calls. However, it is easier to maintain/upgrade to a new base_path if this is set in the base_path property in the IAP Service Instance Configuration for the adapter. Then the entity path can use the global property (the first and second paths). You can still support unique action calls that use a different base_path by hard coding that base_path (the third and fourth paths).

Note: Remember, the entitypath is set up to support a great deal of flexibility in the API calls. This ranges from easy maintenance to providing dynamic information on each call.

Different Schemas

Adapters allow you to specify different schemas on every request and response. Schemas are used to translate fields between IAP and the external system. When IAP uses a username to refer to something and the external system refers to that same thing as login, the adapter (through the schema) is smart enough to perform the translation so that it is refering to the information the way the system it is talking to expects it.

In the schemas, the field name is the IAP name for the data while the external_name is the field name for the other system. So, in the response schema below, what IAP is going to use as a token is provided in the access_token field in the response from the external system.

This example shows the use of a different request and response schema. There are different scenarios where you may want to do this.

• One scenario is when you want to validate required information on the request that may not exist in the response.
• Another scenario is when the information in the request is very different from the response and you do not want to make the schema too complex.

action.json

{
  "name": "getToken",
  …
  "requestSchema": "reqTokenSchema.json",
  "responseSchema": "respTokenSchema.json",
  …
}

request schema

{
  "$id": "reqTokenSchema.json",
  "type": "object",
  "schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "dynamicfields": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getToken",
      "enum": [
        "getToken",
        "healthcheck"
      ],
      "external_name": "ph_request_type"
    },
    "username": {
      "type": "string",
      "description": "username to log in with",
      "external_name": "login"
    },
    "password": {
      "type": "string",
      "description": "password to log in with",
      "external_name": "passwd"
    }
  },
  "required": ["username", "password"],
  "definitions": {}
}

response schema

{
  "$id": "respTokenSchema.json",
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getToken",
      "enum": [
        "getToken"
      ],
      "external_name": "ph_request_type"
    },
    "token": {
      "type": "string",
      "description": "the token returned from system",
      "external_name": "access_token"
    }
  },
  "definitions": {}
}

The external_name field can include fields nested in an object as shown below. So, if the access_token field was nested within a object called credentials, you would make the external_name "credentials.access_token".

response data

{
  "credentials": {
    "access_token": "sdfasdasdadsadsadA"
  }
}

Different Data Types

Adapters support the following data types:

• PLAIN – Used for plain/text. This datatype is never translated.
• XML – Used for application/xml. This datatype is not translated.
• XML2JSON – Used for application/xml, but unlike XML, this datatype is translated from XML to JSON before being returned to IAP.
• URLENCODE – Used for URL encoding of the data sent to the other system.
• FORM – Used to send data to the other system in the format of a form.
• JSON – Used for application/json. This datatype is translated based on the schema definition.
  • JSON is the default.

If a datatype is provided that is not supported, then the field is set to PLAIN as that is less impactful.

{
  "name": "getIP",
  …
  “requestDatatype”: “PLAIN”,
  “responseDatatype”: “XML2JSON”,
  …
},

Individual Action Timeout

Although the default is to use the global request.attempt_timeout property from the IAP Service Instance Configuration, you can provide a timeout on a particular action that overrides the global request timeout.

An action timeout is useful when you know a certain action may take a lot longer (or it may take less time) to complete than most typical responses. 5000ms is the default value for the action timeout field.

{
  "name": "getIP",
  …
  "timeout": 3000,
  …
},

Finding Response Objects

This example illustrates how you can set the responseObjects field to find and limit data in a response.

The key in the responseObjects tells the adapter where to find the response data. This field should be a JSON Query string. This provides a more powerful way to find and limit the data in the response to IAP.

Note: This is a STATIC setting; it is only used to LOCATE data when it is always in the same place.

{
  "name": "getIP",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}?{query}",
  ….
  "responseObjects": [
    {
      "type": ”anykey",
      "key": "result[id=88911]",
      "mockFile": ”a.json"
    },
    {
      "type": ” anykey",
      "key": "result[4]",
      "mockFile": ”b.json"
    },
    {
      "type": ” anykey",
      "key": "result.goodData",
      "mockFile": ”c.json"
    }
  ]
},

Multiple Mock Data

The mock data files defined within the action.json provide a way for the adapter to be tested in standalone mode without integrating with other systems. These files also provide results that mimic the data it expects to receive when connected to the other system.

Click here to review information about Mock Data.

Deprecations

There are still supported fields in the action.json within the code base, but as a best practice, are no longer used. If you have not seen these, you can ignore this section as it will not be a good practice to use any of them.

• The querykey was used to specify the key to insert into a request prior to the query. It is no longer used. Instead the query key should be inserted directly into the following entitypath: /{base_path}/{version}/devices/{pathv1}?myquery={query}. Or can be provided within the query object provided to the adapter method.