# The file layout

## What is in the install directory

Everything Traffic Parrot serves is a file under its install directory. The `Default` virtual service uses the directories at the top of the install directory. Every other [virtual service](https://trafficparrot.com/documentation/5.66.x/virtual_services.html) is a folder `scenarios/Name/` holding the same directories.

```
trafficparrot/
|-- mappings/                  HTTP mappings
|-- __files/                   response bodies and templates
|-- grpc-mappings/             gRPC mappings
|-- proto/                     .proto files for gRPC
|-- jms-mappings/              JMS mappings
|-- ibm-mq-mappings/           native IBM MQ mappings
|-- file-mappings/             file message mappings
|-- websocket-mappings/        WebSocket mappings
|-- data/                      data files a response reads
|-- templates/                 Handlebars partials (a folder you add)
|-- scenarios/Name/            one folder per virtual service
|-- jms-connections.json
|-- ibm-mq-connections.json
|-- root-directories.json
|-- database-connections.json
|-- trafficparrot.properties
`-- jvm.args
```

Traffic Parrot creates the mapping directories the first time it starts.

### Keeping the files in your own repository

To serve the files from a git checkout, point [`trafficparrot.virtualservice.trafficFilesRootUrl`](https://trafficparrot.com/documentation/5.66.x/properties.html#virtualservice-properties) at it, in `trafficparrot.properties` or on the start script:

```
./start.sh trafficparrot.virtualservice.trafficFilesRootUrl=file:/path/to/checkout
```

The mappings, bodies, templates, partials and `.proto` files are then read from `/path/to/checkout`, and the mapping directories in the install directory are no longer served. `trafficparrot.properties`, `jvm.args` and `root-directories.json` stay in the install directory, as do the `Default` virtual service's JMS and IBM MQ connection files. Its `database-connections.json` is read from the checkout, as are the JMS, IBM MQ and database connection files of every other virtual service.

## When a change on disk takes effect

With the shipped `trafficparrot.properties`, a mapping, body, template, data or proto file you save is used by the next request. Nothing needs a restart except the settings in the last two rows.

| Path | Holds | A change takes effect |
| --- | --- | --- |
| `mappings/`, subfolders included | HTTP mappings, one JSON file each | On the next request, for a new file, an edit and a deleted file |
| `__files/` | Response bodies and response templates, named by a mapping's `bodyFileName` | On the next request |
| `templates/` | [Handlebars partials](https://trafficparrot.com/documentation/5.66.x/dynamic.html#template-files), `.hbs` files a template includes with `{{> templates/name}}` | On the next request |
| `data/` | Data files a response reads, such as the CSV files of the [dataSource](https://trafficparrot.com/documentation/5.66.x/dynamic.html) helper | On the next request |
| `grpc-mappings/`, subfolders included | gRPC mappings | On the next call |
| `proto/` | The `.proto` files gRPC mappings are served from | On the next call, a field added to a message included |
| `jms-mappings/` | JMS mappings | On the next message, for a queue replay already reads. A mapping for a new request queue answers once replay is stopped and started. |
| `ibm-mq-mappings/`, `file-mappings/` | Native IBM MQ and file message mappings | On the next message or file, for a queue or directory replay already reads |
| `scenarios/Name/` | A virtual service: its own set of the directories above, and its [`service.properties`](https://trafficparrot.com/documentation/5.66.x/virtual_services.html#vs-configuration) | A new folder is listed at once, and served once it is selected |
| `jms-connections.json`, `ibm-mq-connections.json`, `root-directories.json` | The brokers, queue managers and file roots Traffic Parrot connects to | With no restart: a connection you add can be chosen the next time replay starts |
| `trafficparrot.properties` | Every [setting](https://trafficparrot.com/documentation/5.66.x/properties.html) | After a restart |
| `jvm.args`, `plugins/`, `lib/external/` | JVM options, [extensions](https://trafficparrot.com/documentation/5.66.x/user_guide.html#custom-extensions) and extra JARs | After a restart |

### The setting that changes this

[`trafficparrot.virtualservice.mapping.cache.milliseconds`](https://trafficparrot.com/documentation/5.66.x/properties.html#virtualservice-properties) ships as `0`, which is what makes a saved mapping file live at once. The performance profile sets it far above zero. An HTTP mapping file you edit is then used when that period ends, or after `POST /__admin/mappings/reset` on the HTTP virtual service port (see [resetting between tests](https://trafficparrot.com/documentation/5.66.x/user_guide.html#junit-spring-tests-reset)), and a JMS mapping file after a restart.

## Settings files

`trafficparrot.properties`, in the install directory, holds the [settings](https://trafficparrot.com/documentation/5.66.x/properties.html) and is read when Traffic Parrot starts. A value passed to the start script wins over the file:

```
./start.sh trafficparrot.virtualservice.mapping.cache.milliseconds=0
```

A property is not read from an environment variable. To take one from the environment, in a container or a CI job, have the shell pass it to the start script in the same way. See [Configuration](https://trafficparrot.com/documentation/5.66.x/user_guide.html#configuration) for the Windows form and for `jvm.args`.

The connection files sit beside it, and each protocol page describes its own: [`jms-connections.json`](https://trafficparrot.com/documentation/5.66.x/jms.html#define-jms-connections), [`ibm-mq-connections.json`](https://trafficparrot.com/documentation/5.66.x/ibmmq.html#define-connections), [`root-directories.json`](https://trafficparrot.com/documentation/5.66.x/filemessage.html#configuration) for file messages and `database-connections.json` for the [dataSource](https://trafficparrot.com/documentation/5.66.x/dynamic.html) helper. The web UI lists the connections and does not edit them, and the Management API has no call that changes them: edit the file.

An [upgrade](https://trafficparrot.com/documentation/5.66.x/user_guide.html#upgrade) carries the files on this page into the new install. For partials it carries `templates/`, `responses/` and `.hbs` files at the top of the install directory, so keep partials there.
