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

# Work with mock data

> How mock data works in adapters, how to define it in action.json, how to use multiple mock files per action, and how to capture mock data from Postman, integration tests, or adapter logs.

Mock data is the response an adapter returns when running in stub mode. Instead of making a live call to the external system, the adapter runs through its full processing pipeline and returns the stored mock data at the point where the real call would occur. This allows you to test the complete data flow through the adapter — including schema translation — without integrating with a live system.

Stub mode is also useful for buildingItential Platform workflows when the external system is not yet available.

Mock data cannot test authentication, confirm that URLs are correct, or guarantee the response reflects the current state of the external system. Mock data is also not automatically maintained — if the external system's API changes, mock data files may need to be updated manually.

## Mock data file format

Mock data is the raw response body from the external system. It should match the `responseDatatype` defined in `action.json` — typically JSON.

**Simple format** — the file contains only the response body:

```json
{
  "data": {
    "authentication": {
      "authentication-method": [
        {
          "priority": 1,
          "scope": "remote",
          "statistics": {
            "called": 2,
            "failure": 3,
            "skipped": 10,
            "success": 10
          },
          "type": "tacacs"
        }
      ]
    }
  }
}
```

**Status/response format** — an older format that wraps the response body in a `response` object and adds a `status` field. Use this format when you need to simulate specific HTTP status codes, such as error responses, since mock data files do not contain real HTTP headers.

```json
{
  "status": 200,
  "response": {
    "allowDelete": true,
    "alternateName": "string",
    "dateAdded": 0,
    "description": "TESTING",
    "id": 1245,
    "ipAddress": "10.10.10.1",
    "name": "Michael1"
  }
}
```

## Define mock data files in action.json

Each action in `action.json` has a `responseObjects` array that tells the adapter which mock data file to return when running in stub mode. The `mockFile` path is relative to the entity directory — keep mock data files in a `mockdatafiles/` subdirectory to avoid cluttering the entity root.

```json
{
  "name": "getIP",
  "protocol": "REST",
  "method": "GET",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}",
  "schema": "schema.json",
  "timeout": 3000,
  "datatype": "PLAIN",
  "sendEmpty": true,
  "headers": {},
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/getIP-default.json"
    }
  ]
}
```

## Use multiple mock data files per action

An action can define multiple entries in `responseObjects`, each pointing to a different mock file. The adapter selects which file to return based on the incoming request, using the following hierarchy:

1. Match data in the request body
2. Match data in a path variable
3. Match data in a query or option parameter
4. Request has a body (`withBody`)
5. Request has a path variable (`withPathv#`)
6. Request has a query parameter (`withQuery`)
7. Request has an option parameter (`withOption`)
8. Default

**Example: match-based selection.** The `type` field in each `responseObject` entry specifies the match value. In this example, a request with `{ name: 'abc123' }` in the body returns `a.json`, a request with path variable `error` returns `b.json`, and a request with query `name=happy` returns `c.json`:

```json
{
  "name": "getIP",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}?{query}",
  "responseObjects": [
    { "type": "name-abc123", "key": "", "mockFile": "a.json" },
    { "type": "error",       "key": "", "mockFile": "b.json" },
    { "type": "name=happy",  "key": "", "mockFile": "c.json" }
  ]
}
```

**Example: structural selection.** Use `withPathv#`, `withQuery`, or `default` as the `type` to select based on whether the request includes a path variable, a query parameter, or neither:

```json
{
  "name": "getIP",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}?{query}",
  "responseObjects": [
    { "type": "default",    "key": "", "mockFile": "x.json" },
    { "type": "withPathv1", "key": "", "mockFile": "y.json" },
    { "type": "withQuery",  "key": "", "mockFile": "z.json" }
  ]
}
```

## Capture mock data

### From Postman

Run the API call in Postman, then copy the response body from the response panel and save it as a JSON file in the `mockdatafiles/` directory of the appropriate entity. Reference the file in the corresponding `action.json` `responseObjects` entry.

### From integration tests

Set `isSaveMockData` to `true` and `stub` to `false` in `adapterTestIntegration.js`, then run the integration tests. The adapter makes live calls to the external system, saves each response as a mock data file, and updates the corresponding `action.json` entries automatically.

```javascript
const isSaveMockData = true;
const stub = false;

// ...

describe('#createDeployment', () => {
  it('should work if integrated or standalone with mockdata', (done) => {
    try {
      a.createDeployment(apisApiId, apisCreateDeploymentBodyParam, null, (data, error) => {
        try {
          runCommonAsserts(data, error);
          if (stub) {
            assert.equal('string', data.response.CreatedDate);
            assert.equal('string', data.response.DeploymentId);
          } else {
            assert.equal('string', data.response.CreatedDate);
          }
          saveMockData('Apis', 'createDeployment', 'default', data);
          done();
        } catch (err) {
          log.error(`Test Failure: ${err}`);
          done(err);
        }
      });
    } catch (error) {
      log.error(`Adapter Exception: ${error}`);
      done(error);
    }
  }).timeout(attemptTimeout);
});
```

By default, `saveMockData` saves the translated response. If you want to save the raw, pre-translation response instead, set `return_raw: true` in the request properties. When `return_raw` is enabled, `saveMockData` uses the raw response data, so you do not need to manually revert the translation.

### From adapter logs

Enable debug-level logging on the adapter, then run the call. Two log entries contain the response data:

**`CALL RETURN`** — the full response body before JSON parsing. Use this for mock data when you want the raw response.

```
debug: Test-eai-connectorRest-makeRequest: CALL RETURN:
{"status":"success","code":201,"response":"{\n\"type\":\"oci/card\",\n\"id\":308,...}"}
```

**`CALL RESPONSE`** — the response after JSON parsing. Use this when you want the parsed object.

```
debug: Test-eai-restHandler-handleRestRequest: RESPONSE:
{"type":"oci/card","id":308,"href":"oci/card/308","transientAttributes":{},"key":{"type":"oci/cardKey","keyValue":308}}
```

Copy the relevant value and save it as a JSON file in the `mockdatafiles/` directory of the appropriate entity.