> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/adapters/configure/actions/examples/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# action.json usage examples

> Examples covering entity path variables, schemas, datatypes, timeouts, response objects, mock data, and deprecated fields in action.json.

## 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

```json
"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 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:

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

The same pattern applies to `{base_path}`:

```json
"entitypath": "/{base_path}/{version}/devices/{pathv1}?{query}"
"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**

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

**Request schema**

```json
{
  "$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**

```json
{
  "$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 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`.

```json
{
  "name": "getIP",
  "requestDatatype": "PLAIN",
  "responseDatatype": "XML2JSON"
}
```

## 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.

```json
{
  "name": "getIP",
  "timeout": 3000
}
```

## 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.

The `key` field is a static setting. It only works when the target data is always found at the same location in the response.

```json
{
  "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"
    }
  ]
}
```

## 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](/adapters/test/mock-data).

## 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`:

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

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

> Examples covering entity path variables, schemas, datatypes, timeouts, response objects, mock data, and deprecated fields in action.json.