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

# Base properties

> Reference for the top-level adapter properties that control how the adapter communicates with an external system.

Base properties are defined at the top level of theItential Platform service instance configuration for the adapter — they are not nested inside other objects. These properties control how the adapter communicates with the external system.

## Properties

| Property           | Type              | Required     | Description                                                                                                                                                                                                                                                                                  |
| ------------------ | ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host`             | string            | Yes          | Hostname or IP address of the external system. Do not include protocol, port, or path — this is the hostname only. **Example:** In `http://xyz.abc.com:8080/xyz/v1/abc`, the host is `xyz.abc.com`.                                                                                          |
| `port`             | number            | Yes          | Port on which to connect to the external system. Always verify this value even if you are using a default port. **Example:** In `http://xyz.abc.com:8080/xyz/abc`, the port is `8080`. When no port appears in the URL, the default is `80` for HTTP and `443` for HTTPS.                    |
| `choosepath`       | string            | No → `""`    | Controls which API version path to use for calls when the endpoint configuration defines an array of entity paths. If not set, defaults to the first path in the array.                                                                                                                      |
| `base_path`        | string            | No → `""`    | A path prefix that appears in most or all API calls. Set this once here rather than on every action in the endpoint configuration. You can override it on individual actions as needed. **Example:** In `http://xyz.abc.com:8080/api/rest/v1/abc`, the base path is `/api/rest`.             |
| `version`          | string            | No → `""`    | The API version segment that appears in most or all API calls. Like `base_path`, setting it here means you only need to update it in one place when it changes. **Example:** In `http://xyz.abc.com:8080/api/rest/v1.5/abc`, the version is `v1.5`.                                          |
| `cache_location`   | enum              | No → `none`  | Determines where the entity cache is stored. Use caching only if a broker needs to check adapter capabilities before requesting actions. Options: `none` (no caching), `local` (in-memory; lost on adapter restart).                                                                         |
| `encode_pathvars`  | boolean           | No → `true`  | Controls whether path variables are URL-encoded. Encoding prevents characters like `?` or `/` from being interpreted as URL syntax. Set to `false` to disable.                                                                                                                               |
| `encode_queryvars` | boolean           | No → `true`  | Controls whether query variables are URL-encoded. Encoding prevents characters like `?` or `/` from being interpreted as URL syntax. Set to `false` to disable.                                                                                                                              |
| `save_metric`      | boolean or string | No → `false` | When enabled, the adapter collects and persists per-call metrics including success rates and average response times. If set to `true`, metrics are stored in a directory inside the adapter. If set to a string, that string is used as the storage path.                                    |
| `stub`             | boolean           | No → `false` | When `true`, the adapter runs in standalone mode with mock data instead of connecting to the external system. Use this for unit tests, integration tests with mock data, or development environments where the external system is unavailable. In production, this should always be `false`. |
| `protocol`         | enum              | No → `http`  | The protocol the adapter uses to communicate with the external system. Supported values: `http`, `https`.                                                                                                                                                                                    |

## Examples

### Simple scenario

The adapter communicates with `mysystem.abc.com` over HTTPS on port `3443`. All requests start with `/api/rest` and use API version `v2.3`. Entity caching is disabled. Metrics are saved. The adapter runs in production mode.

```json
"host": "mysystem.abc.com",
"port": 3443,
"choosepath": "",
"base_path": "/api/rest",
"version": "v2.3",
"cache_location": "none",
"encode_pathvars": true,
"encode_queryvars": true,
"save_metric": true,
"stub": false,
"protocol": "https"
```

### Complex scenario

The adapter communicates with `mysystem.abc.com` over HTTPS on the default port `443`. There is no shared base path or version. URL encoding is disabled for path variables but enabled for query variables. Metrics are not saved. The adapter supports multiple paths per call using `choosepath`.

The entity path in `action.json` is defined as an object:

```json
{
  "2020v": "{base_path}/{version}/getmy/pathforaction",
  "2021v": "{base_path}/{version}/getmy/specificpathforaction"
}
```

```json
"host": "mysystem.abc.com",
"port": 443,
"choosepath": "2021v",
"base_path": "/",
"version": "",
"cache_location": "none",
"encode_pathvars": false,
"encode_queryvars": true,
"save_metric": false,
"stub": false,
"protocol": "https"
```