action.json usage examples

Entity path variables

Entity path variables let you inject both static configuration and dynamic runtime values into API call paths. Variables are defined in entitypath and replaced by the adapter library when a call is made.

Common variables

• {base_path} — Replaced with the base_path property from theItential Platform service instance configuration.
• {version} — Replaced with the version property from theItential Platform service instance configuration.

Setting these in the service instance configuration means you only need to update them in one place if they change, rather than updating every action.

Dynamic variables

• {pathv#} — Replaced with the corresponding element from the uriPathVars array passed in with the request. {pathv1} maps to the first element (index 0), {pathv2} to the second, and so on. Generic adapter calls support up to 20 path variables, though calls with that many are uncommon.
• {query} — Replaced with query parameters from the uriQuery object on the request. The adapter library assembles the query string automatically.

Entity path examples

1
"entitypath": "/api/v1/devices"
2
"entitypath": "/api/v1/devices/{pathv1}"
3
"entitypath": "/api/v1/devices/{pathv1}?{query}"
4
"entitypath": "/api/v1/devices/{pathv1}/interface/{pathv2}?{query}"

The first path is static and returns all devices. The second accepts a dynamic device ID, so the same action can resolve to /api/v1/devices/abc123 on one call and /api/v1/devices/def456 on the next. The third adds query parameters, allowing a call like /api/v1/devices/abc123?return_field=name,id,interfaces. The fourth supports two dynamic segments, resolving to something like /api/v1/devices/abc123/interface/eth_101.

Mixing static and dynamic versions

You can use {version} for most actions while hard-coding a version for actions that require a specific API version:

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

The same pattern applies to {base_path}:

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

Different schemas

You can define a different schema for the request and response on every action. This is useful when:

• You want to validate required fields on the request that are not present in the response.
• The request and response structures are different enough that a shared schema would be unnecessarily complex.

The field name in the schema is theItential Platform name for the data. The external_name is the name the external system uses for the same field. For example, if the external system returns a token in a field called access_token butItential Platform expects token, the response schema maps access_token → token automatically.

action.json

1
{
2
  "name": "getToken",
3
  "requestSchema": "reqTokenSchema.json",
4
  "responseSchema": "respTokenSchema.json"
5
}

Request schema

1
{
2
  "$id": "reqTokenSchema.json",
3
  "type": "object",
4
  "schema": "http://json-schema.org/draft-07/schema#",
5
  "translate": true,
6
  "dynamicfields": true,
7
  "properties": {
8
    "ph_request_type": {
9
      "type": "string",
10
      "description": "type of request (internal to adapter)",
11
      "default": "getToken",
12
      "enum": ["getToken", "healthcheck"],
13
      "external_name": "ph_request_type"
14
    },
15
    "username": {
16
      "type": "string",
17
      "description": "username to log in with",
18
      "external_name": "login"
19
    },
20
    "password": {
21
      "type": "string",
22
      "description": "password to log in with",
23
      "external_name": "passwd"
24
    }
25
  },
26
  "required": ["username", "password"],
27
  "definitions": {}
28
}

Response schema

1
{
2
  "$id": "respTokenSchema.json",
3
  "type": "object",
4
  "$schema": "http://json-schema.org/draft-07/schema#",
5
  "translate": true,
6
  "properties": {
7
    "ph_request_type": {
8
      "type": "string",
9
      "description": "type of request (internal to adapter)",
10
      "default": "getToken",
11
      "enum": ["getToken"],
12
      "external_name": "ph_request_type"
13
    },
14
    "token": {
15
      "type": "string",
16
      "description": "the token returned from system",
17
      "external_name": "access_token"
18
    }
19
  },
20
  "definitions": {}
21
}

The external_name field also supports dot notation for nested fields. If access_token is nested inside a credentials object, set external_name to "credentials.access_token".

Different datatypes

The adapter supports the following datatypes:

• PLAIN — Plain text. Never translated.
• XML — XML data. Not translated.
• XML2JSON — XML data that is translated to JSON before being returned toItential Platform.
• URLENCODE — Data that is URL-encoded before being sent to the external system.
• FORM — Data sent as a form submission.
• JSON — JSON data, translated based on the schema. This is the default.

If an unsupported datatype is specified, the adapter falls back to PLAIN.

1
{
2
  "name": "getIP",
3
  "requestDatatype": "PLAIN",
4
  "responseDatatype": "XML2JSON"
5
}

Individual action timeout

By default, an action uses the global request.attempt_timeout from theItential Platform service instance configuration. You can override this per action when you know a particular call will consistently take more or less time than the global setting.

1
{
2
  "name": "getIP",
3
  "timeout": 3000
4
}

Finding response data

The key field in responseObjects is a JSONQuery string that locates the relevant data within the response. Use it to strip metadata and return only the dataItential Platform needs.

1
{
2
  "name": "getIP",
3
  "entitypath": "{base_path}/{version}/addresses/{pathv1}?{query}",
4
  "responseObjects": [
5
    {
6
      "type": "anykey",
7
      "key": "result[id=88911]",
8
      "mockFile": "a.json"
9
    },
10
    {
11
      "type": "anykey",
12
      "key": "result[4]",
13
      "mockFile": "b.json"
14
    },
15
    {
16
      "type": "anykey",
17
      "key": "result.goodData",
18
      "mockFile": "c.json"
19
    }
20
  ]
21
}

Mock data

Mock data files defined in action.json allow the adapter to run in standalone mode without connecting to the external system. Each mockFile value is the relative path to a file that returns data mimicking what the external system would return. For more information, see Mock data overview.

Deprecated fields

The following fields are still supported in the codebase but should not be used.

• querykey — Previously used to specify the key to insert before a query string. Instead, insert the query key directly in entitypath:

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

  Or provide the query key in the query object passed to the adapter method.