ConfigureService instance configuration

Base properties

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

PropertyTypeRequiredDescription
hoststringYesHostname 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.
portnumberYesPort 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.
choosepathstringNo → ""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_pathstringNo → ""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.
versionstringNo → ""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_locationenumNo → noneDetermines 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_pathvarsbooleanNo → trueControls whether path variables are URL-encoded. Encoding prevents characters like ? or / from being interpreted as URL syntax. Set to false to disable.
encode_queryvarsbooleanNo → trueControls whether query variables are URL-encoded. Encoding prevents characters like ? or / from being interpreted as URL syntax. Set to false to disable.
save_metricboolean or stringNo → falseWhen 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.
stubbooleanNo → falseWhen 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.
protocolenumNo → httpThe 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.

1"host": "mysystem.abc.com",
2"port": 3443,
3"choosepath": "",
4"base_path": "/api/rest",
5"version": "v2.3",
6"cache_location": "none",
7"encode_pathvars": true,
8"encode_queryvars": true,
9"save_metric": true,
10"stub": false,
11"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:

1{
2  "2020v": "{base_path}/{version}/getmy/pathforaction",
3  "2021v": "{base_path}/{version}/getmy/specificpathforaction"
4}
1"host": "mysystem.abc.com",
2"port": 443,
3"choosepath": "2021v",
4"base_path": "/",
5"version": "",
6"cache_location": "none",
7"encode_pathvars": false,
8"encode_queryvars": true,
9"save_metric": false,
10"stub": false,
11"protocol": "https"