# Working with files

## Mocks as files

A mock in Traffic Parrot is a set of files. A mapping is a JSON file, a response body or template can be a file of its own, and the settings are properties and JSON files. The web UI edits those same files, so you can leave it closed: write the files in your editor, keep them in git, and load and check them from a script.

With the settings Traffic Parrot ships with, a mapping or template file you save is used by the next request, with no restart and no reload call. The [file layout](https://trafficparrot.com/documentation/5.66.x/file-layout.html#when-changes-take-effect) page says when that is not so.

## Where to start

| You want to | Read |
| --- | --- |
| Write a mapping in your editor, with autocomplete, and see it answer | [Write a mapping by hand](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html), for HTTP, gRPC, JMS, native IBM MQ and file messages |
| Know which file holds what, and when an edit takes effect | [The file layout](https://trafficparrot.com/documentation/5.66.x/file-layout.html) |
| See every key a mapping file can carry | The [mapping explorer](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/explorer/index.html), a searchable tree of the keys, or the key reference for [HTTP](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/reference/http.html), [gRPC](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/reference/grpc.html), [JMS](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/reference/jms.html), [native IBM MQ](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/reference/ibm-mq.html) and [file messages](https://trafficparrot.com/documentation/5.66.x/mapping-explorer/reference/file-message.html). The [mapping schemas](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#editor-setup) your instance serves give your editor the same keys |
| Match requests and build responses | [Request Matching](https://trafficparrot.com/documentation/5.66.x/request_matching.html) for the matchers, [Dynamic Responses](https://trafficparrot.com/documentation/5.66.x/dynamic.html) for the Handlebars helpers and [template files](https://trafficparrot.com/documentation/5.66.x/dynamic.html#template-files) |
| Check the files before they are loaded, by hand or in CI | [The `validate` command](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#validate) |
| Check the files, start Traffic Parrot with them and run your tests in a CI job | The [CI example](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#ci-example), a script and a GitHub Actions workflow to copy |
| Find out why a request got no answer | [When a request gets no answer](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#no-answer) |
| Drive Traffic Parrot from a script | The [table below](https://trafficparrot.com/documentation/5.66.x/working-with-files.html#ui-file-api) and the [Management API reference](https://trafficparrot.com/documentation/5.66.x/openapi/index.html) |
| Add your own matcher, helper or transformer | [Custom extensions](https://trafficparrot.com/documentation/5.66.x/dynamic.html#write-your-own), with the [SDK Javadoc](https://trafficparrot.com/documentation/5.66.x/sdk-javadoc/index.html) and the [SDK workspace project](https://trafficparrot.com/documentation/5.66.x/downloads/trafficparrot-sdk-workspace-5.66.x.zip) to start from |

## The UI, the file and the API side by side

Each thing the web UI does is a file it writes, a call on the management port (`8080` unless you changed it), or both. The calls are in the [Management API reference](https://trafficparrot.com/documentation/5.66.x/openapi/index.html).

| In the UI | The file | The API call |
| --- | --- | --- |
| Add or edit an HTTP mapping | One JSON file in `mappings/`, and a file in `__files/` when the body is kept in a file | `POST /api/http/__admin/mappings` with `"persistent": true` in the mapping. Without it the mapping is held in memory and is gone at a restart. |
| Turn on response templating | Nothing to turn on: a response body is a template already, with no `transformers` entry | None |
| Import and export HTTP mappings | The files in `mappings/` and `__files/` | `POST /http/management/importMappings`, `GET /http/management/exportMappings` |
| Record HTTP traffic | The recorded mappings, in `mappings/` and `__files/` | `POST /http/management/startRecording`, `POST /http/management/stopRecording`, `GET /http/management/currentRecordingStatus` |
| The warning that a mapping file was not loaded | None | `GET /http/management/skippedMappingFiles`, `GET /grpc/management/skippedMappingFiles` |
| Choose the virtual service to serve | One folder per virtual service, `scenarios/Name/` | `GET /api/scenarios` lists them. `PUT /api/scenarios/{name}` with `{"enabled": true}` selects one. |
| Add or edit a gRPC mapping | A JSON file in `grpc-mappings/`, served from the `.proto` files in `proto/` | `POST /api/grpc/mapping`, `GET /grpc/management/mappings`, `POST /grpc/management/importMappings` |
| Add or edit a JMS mapping | A JSON file in `jms-mappings/` | `POST /jms/management/prime`, `GET /jms/mappings`, `POST /jms/management/importMappings` |
| Add or edit a native IBM MQ mapping | A JSON file in `ibm-mq-mappings/` | `POST /api/ibmMq/mappings`, `GET /ibmMq/mappings` |
| Add or edit a file message mapping | A JSON file in `file-mappings/` | `POST /fileMessage/management/importMappings` |
| Start and stop replay or recording for JMS, IBM MQ or file messages | None | `POST` to `/jms/replay`, `/ibmMq/replay` or `/fileMessage/replay`, and to the matching `/record` path. `GET` reads the state. |
| The connections to brokers, queue managers, file roots and databases, which the UI lists and does not edit | `jms-connections.json`, `ibm-mq-connections.json`, `root-directories.json`, `database-connections.json` | None: edit the file |
| A setting, which the UI does not change | `trafficparrot.properties` | None: edit the file, or pass the value to the start script, then restart |

[How a mapping gets loaded](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#loading) shows the HTTP mapping call and the virtual service call with their answers, and [the messaging samples](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#other-formats) show the replay calls.

## Going further with an AI assistant

An AI coding assistant can write and check these files with you. The install directory holds a brief for it, `AGENTS.md`, and a running instance serves the mapping schemas and the helper and matcher catalogues it reads. See [Generate mocks with AI](https://trafficparrot.com/documentation/5.66.x/generate-mocks-with-ai-agent.html) and the [MCP endpoint reference](https://trafficparrot.com/documentation/5.66.x/mcp.html).
