# Write a mapping by hand

## An HTTP mapping from an empty file

[Start Traffic Parrot](https://trafficparrot.com/documentation/5.66.x/start.html) and work in its install directory. The ports below are the defaults: `8080` for management and `8081` for the HTTP virtual service.

Create `mappings/hello.json`:

```json
{
  "request": {
    "method": "GET",
    "urlPath": "/hello"
  },
  "response": {
    "status": 200,
    "body": "Hello from a file"
  }
}
```

Call it:

```bash
curl -i http://localhost:8081/hello
```

```
HTTP/1.1 200 OK
Vary: Origin
Matched-Stub-Id: 0d2b8e97-9989-31af-aa1f-695144ab9b6e
Matched-Stub-Name: hello.json
Content-Length: 17

Hello from a file
```

Nothing was restarted or reloaded: the file was read when the request arrived. `Matched-Stub-Name` names the file that answered. [The file layout](https://trafficparrot.com/documentation/5.66.x/file-layout.html#when-changes-take-effect) says when a saved file takes effect for every kind of file.

## Autocomplete and validation in your editor

A running instance serves a JSON schema for each mapping format, listed at `http://localhost:8080/schemas/index.json`. They ship inside Traffic Parrot, so they describe the version you run.

| Format | Directory | Schema, under `http://localhost:8080` |
| --- | --- | --- |
| HTTP | `mappings/` | `/schemas/http-mapping.schema.json` |
| gRPC | `grpc-mappings/` | `/schemas/grpc-mapping.schema.json`: the HTTP keys, with gRPC's `urlPath`, `method` and `status` |
| JMS | `jms-mappings/` | `/schemas/jms-mapping.schema.json` |
| Native IBM MQ | `ibm-mq-mappings/` | `/schemas/ibm-mq-mapping.schema.json` |
| File messages | `file-mappings/` | `/schemas/file-message-mapping.schema.json` |

Make `$schema` the first key of a mapping file, with the schema's address as its value:

```json
{
  "$schema": "http://localhost:8080/schemas/http-mapping.schema.json",
  "request": {
    "method": "GET",
    "urlPath": "/hello"
  },
  "response": {
    "status": 200,
    "body": "Hello from a file"
  }
}
```

An editor that reads JSON schemas then offers each key as you type, and marks a key the format does not have or a value of the wrong type. Traffic Parrot ignores the line when it loads the file.

- **Visual Studio Code** reads the `$schema` line and needs nothing else. To cover a whole folder without the line in each file, add the schema to `.vscode/settings.json`:

  ```json
  {
    "json.schemas": [
      {
        "fileMatch": ["**/mappings/*.json"],
        "url": "http://localhost:8080/schemas/http-mapping.schema.json"
      }
    ]
  }
  ```

- **IntelliJ IDEA**: under **Settings**, **Languages & Frameworks**, **Schemas and DTDs**, add a mapping in **JSON Schema Mappings** with the schema's address and your `mappings` folder. A schema at an address is downloaded when **Allow downloading JSON Schemas from remote sources** is ticked in **Remote JSON Schemas**, in the same group.

To work with the instance stopped, save the schema in a folder of its own beside `mappings/`, and use that file's path in place of the address. Run this in the directory that holds `mappings/`:

```bash
curl --create-dirs -o schemas/http-mapping.schema.json http://localhost:8080/schemas/http-mapping.schema.json
```

Do not save it in `mappings/` or a folder inside it: Traffic Parrot reads every JSON file there as a mapping, and a schema is loaded as one that matches any request. A request that none of your mappings matches is then answered `200` with an empty body.

One thing to know if you also use the web UI: saving a mapping there rewrites its file without the `$schema` line. The file name and the `id` are kept.

## A name, an id, a template file and a partial

A mapping you keep in git is easier to live with when it has a `name` and an `id` of its own and its response body in a file. Three files:

`mappings/orders-open.json`

```json
{
  "$schema": "http://localhost:8080/schemas/http-mapping.schema.json",
  "id": "5c7e6e1a-3f0b-4d38-9d0e-0d7c4a1f2b10",
  "name": "orders-open",
  "request": {
    "method": "GET",
    "urlPath": "/orders",
    "queryParameters": {
      "status": {
        "equalTo": "open"
      }
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "bodyFileName": "orders-open.hbs"
  }
}
```

`__files/orders-open.hbs`

```
{
  "status": "{{request.query.status}}",
  "orders": [
    { "id": "A-1001", "total": 42.50 }
  ],
  {{> templates/page-footer}}
}
```

`templates/page-footer.hbs`

```
"servedBy": "Traffic Parrot", "path": "{{request.path}}"
```

```bash
curl -i "http://localhost:8081/orders?status=open"
```

```
HTTP/1.1 200 OK
Vary: Origin
Content-Type: application/json
Matched-Stub-Id: 5c7e6e1a-3f0b-4d38-9d0e-0d7c4a1f2b10
Matched-Stub-Name: orders-open
Content-Length: 133

{
  "status": "open",
  "orders": [
    { "id": "A-1001", "total": 42.50 }
  ],
  "servedBy": "Traffic Parrot", "path": "/orders"

}
```

- `bodyFileName` is a path under `__files/`. The file is rendered as a [Handlebars template](https://trafficparrot.com/documentation/5.66.x/dynamic.html), as an inline `body` is; neither needs a `transformers` entry.
- `{{> templates/page-footer}}` includes `templates/page-footer.hbs` from the install directory, a [partial](https://trafficparrot.com/documentation/5.66.x/dynamic.html#template-files) any template can share.
- The `name` and the `id` come back in the `Matched-Stub-Name` and `Matched-Stub-Id` response headers, so a test or a log line can say which mapping answered. A mapping with no `name` is reported under its file name, as `hello.json` was above.
- The helpers and matchers your instance has are listed, each with a snippet, at `http://localhost:8080/helpers-catalogue.json` and `http://localhost:8080/matchers-catalogue.json`, and described under [Dynamic Responses](https://trafficparrot.com/documentation/5.66.x/dynamic.html) and [Request Matching](https://trafficparrot.com/documentation/5.66.x/request_matching.html).

## Check the files before they are loaded

A running instance does not check a mapping file against its schema: a key it does not know is dropped without a word. The [`validate` command](https://trafficparrot.com/documentation/5.66.x/http.html#validate-cli) does check, without starting a server, so it suits a commit hook or a CI step. Give it the directory that holds `mappings/` and the other mapping directories:

```bash
./trafficparrot.sh validate /path/to/files-root
```

```
No mapping schema drift detected.
```

It exits `0` when every file matches and `1` otherwise, naming each file and key:

```
Some HTTP mappings do not match the HTTP mapping schema: (1)
HTTP mapping 'mappings/dsl-name.json' does not match http-mapping.schema.json: /request: property 'urlEqualTo' is not defined in the schema and the schema does not allow additional properties; 'urlEqualTo' is the Java DSL name of a matcher, not a mapping key: write 'url'
```

The result follows a few logging warnings that start `SLF4J` or `log4j`, which you can ignore.

- It checks HTTP, JMS, native IBM MQ and file message mappings against their schemas, and gRPC mappings against the `.proto` files.
- It also lists warnings, which leave the exit code as it was: a gRPC mapping that does not match its schema, and a `bodyFileName` naming a file that is not in `__files`.
- It also checks HTTP mappings against any OpenAPI specification in the directory's `openapi/` folder. A new install ships an example specification there, so `validate` run on the install directory itself reports your mappings as missing from that example. Move the example out, or keep your files in a [directory of their own](https://trafficparrot.com/documentation/5.66.x/file-layout.html#files-root).

The check is stricter than loading in a few more ways. It refuses some values that Traffic Parrot accepts, such as an HTTP method the schema does not list, or a `priority` below `1` in a JMS, native IBM MQ or file message mapping. Those three kinds of mapping must also be strict JSON: a comment or a single-quoted string, which Traffic Parrot reads when it loads the file, is reported as not valid JSON. An HTTP mapping is read as Traffic Parrot reads it, so a comment passes, and a file that holds several mappings under a `mappings` key has each of them checked. An editor that checks such a file against the HTTP schema reports it, because the schema describes one mapping.

### An example for CI

The [CI example workspace](https://trafficparrot.com/documentation/5.66.x/downloads/trafficparrot-ci-workspace-5.66.x.zip) is a small repository to copy from. It holds two HTTP mappings and a template under `traffic-parrot/`, one script, `ci/run-traffic-parrot.sh`, and a GitHub Actions workflow that runs the script on every push and pull request. The script runs the same way on a laptop:

```bash
TRAFFIC_PARROT_ZIP=/path/to/trafficparrot-release.zip ci/run-traffic-parrot.sh
```

1. It unzips the release into a scratch folder, `target/traffic-parrot-ci` unless you move it, and copies `traffic-parrot/` beside it, so nothing Traffic Parrot writes lands in `traffic-parrot/`.
2. It runs `validate` on the copy. An error stops the run here with exit code `1`, before anything starts; warnings are printed and pass.
3. It starts Traffic Parrot with the files and waits for it to answer: from the unzipped release, or, with `TRAFFIC_PARROT_DOCKER=true`, in a Docker image built from the release and the files (`ci/Dockerfile`). If Traffic Parrot does not start, the run stops here with exit code `1`. A Docker run prints Traffic Parrot's logs from the container first; a run from the zip leaves them in the unzipped release, under `target/traffic-parrot-ci/release/`.
4. It runs your test command with `TRAFFIC_PARROT_URL` set to the virtual service's address, stops Traffic Parrot and exits with the test's exit code. With no command it runs `ci/smoke-test.sh`, which calls the two example mappings.

The script takes the release zip without a Java runtime and needs Java on the `PATH`, with or without Docker, because it checks the files with the release itself. `TRAFFIC_PARROT_LICENSE_FILE` names the license file to use in place of the one in the zip, and `TRAFFIC_PARROT_HTTP_PORT` and `TRAFFIC_PARROT_GUI_PORT` move the ports from `8081` and `8080`. The header of the script lists the other settings. It exits `2` when it is not set up: no zip, or no Java.

The workflow, `.github/workflows/traffic-parrot.yml`, runs the script twice, from the zip and in Docker. It reads two repository secrets: `TRAFFIC_PARROT_ZIP_URL`, where the job downloads your release zip from, and `TRAFFIC_PARROT_LICENSE_BASE64`, your license file base64-encoded. When the zip job fails, it keeps Traffic Parrot's logs as the `traffic-parrot-logs-zip` artifact.

## How a mapping gets loaded

**Save the file.** That is all the samples above did. With the shipped settings the next request reads it, and every file is read when Traffic Parrot starts. With the mapping cache turned on, a saved file waits for the reset call that [the file layout](https://trafficparrot.com/documentation/5.66.x/file-layout.html#mapping-cache) names.

**Post it to the Management API** when a script should not write into the install directory. With `"persistent": true` Traffic Parrot writes the file for you. `orders-closed.json`:

```json
{
  "name": "orders-closed",
  "persistent": true,
  "request": {
    "method": "GET",
    "urlPath": "/orders",
    "queryParameters": {
      "status": {
        "equalTo": "closed"
      }
    }
  },
  "response": {
    "status": 200,
    "body": "No closed orders"
  }
}
```

```bash
curl -i -X POST http://localhost:8080/api/http/__admin/mappings \
  -H "Content-Type: application/json" \
  -d @orders-closed.json
```

The answer is `201 Created` with the mapping and the `id` it was given. `mappings/orders-closed.json` now exists, named after the mapping's `name`, and the mapping answers at once:

```bash
curl -i "http://localhost:8081/orders?status=closed"
```

```
HTTP/1.1 200 OK
Vary: Origin
Matched-Stub-Id: ce51cbd9-5c0e-4cf3-a23a-512f562fdd5a
Matched-Stub-Name: orders-closed
Content-Length: 16

No closed orders
```

Without `"persistent": true` the mapping is held in memory and is gone when Traffic Parrot restarts. The `id` above is the one this run was given; yours will differ unless the mapping sets one.

**Put it in another virtual service.** A folder `scenarios/Orders/` with a `mappings/` directory of its own is a [virtual service](https://trafficparrot.com/documentation/5.66.x/virtual_services.html) named `Orders`, listed as soon as the folder exists. Select it:

```bash
curl -X PUT http://localhost:8080/api/scenarios/Orders \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

With the shipped settings the default ports then answer from its files. Select `Default` in the same way to go back.

## When a request gets no answer

An HTTP request that no mapping matches is answered with status `900`:

```bash
curl -i "http://localhost:8081/orders?status=shipped"
```

```
HTTP/1.1 900 900
Transfer-Encoding: chunked

Traffic Parrot Virtual Service: No responses matched the given request
```

Three places say why.

- **The closest mappings.** The [Request Log](https://trafficparrot.com/documentation/5.66.x/http.html#request-log-near-misses) in the web UI compares the request with the closest mappings field by field. From a script, this call lists each unmatched request with the mappings closest to it, the closest first:

  ```bash
  curl http://localhost:8080/api/http/requests/unmatched/near-misses
  ```

- **Files that were not loaded.** A file that is not valid JSON, or holds a value of the wrong type, is skipped, and the mappings beside it go on answering. The HTTP pages show a warning, the log has an `ERROR` line that starts `Skipping mapping file`, and this call lists the files:

  ```bash
  curl http://localhost:8080/http/management/skippedMappingFiles
  ```

  ```
  [ {
    "skipped" : "mapping file /opt/trafficparrot/mappings/broken.json",
    "reason" : "Unexpected character ('}' (code 125)): was expecting double-quote to start field name"
  } ]
  ```

- **The mapping that did answer.** When the wrong mapping answers, `Matched-Stub-Name` in the response names it.

A gRPC call, a JMS or IBM MQ message, or a file that no mapping matches is listed on the Requests page of its protocol: [gRPC](https://trafficparrot.com/documentation/5.66.x/grpc.html#requests-page), [JMS](https://trafficparrot.com/documentation/5.66.x/jms.html#requests-page), [IBM MQ](https://trafficparrot.com/documentation/5.66.x/ibmmq.html#requests-page) and [files](https://trafficparrot.com/documentation/5.66.x/filemessage.html#requests-page).

## gRPC, JMS, native IBM MQ and file messages

### gRPC

A gRPC mapping is served from a `.proto` file. `proto/greeter.proto`:

```
syntax = "proto3";

package example;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}
```

`grpc-mappings/say-hello.json`:

```json
{
  "id": "0b6a3a52-7d0e-4f0c-8a55-3d2f1c9e4a21",
  "name": "say-hello",
  "request": {
    "urlPath": "example.Greeter/SayHello",
    "method": "ANY",
    "headers": {
      "Protocol": {
        "equalTo": "GRPC"
      }
    },
    "bodyPatterns": [
      {
        "matchesJsonPath": "$.name"
      }
    ]
  },
  "response": {
    "status": 0,
    "jsonBody": {
      "message": "Hello {{jsonPath request.body '$.name'}}"
    }
  }
}
```

Call `example.Greeter/SayHello` with `{"name": "Ada"}` from your gRPC client, on port `5552` without TLS. The reply's `message` is `Hello Ada`, with status `OK`.

- `urlPath` is `package.Service/Method`, with no slash in front.
- `status` is the gRPC status code, and `0` is `OK`.
- Messages are written and matched as JSON. See [gRPC](https://trafficparrot.com/documentation/5.66.x/grpc.html).

### JMS

A messaging mapping has keys of its own: a `destination` for the queue, a `bodyMatcher` for the request and `text` for the reply. `jms-mappings/order-status.json`:

```json
{
  "$schema": "http://localhost:8080/schemas/jms-mapping.schema.json",
  "mappingId": "9a1d2c3e-4b5f-4a6b-8c7d-0e1f2a3b4c5d",
  "request": {
    "destination": {
      "name": "orders.request",
      "type": "QUEUE"
    },
    "bodyMatcher": {
      "contains": "status"
    }
  },
  "response": {
    "destination": {
      "name": "orders.response",
      "type": "QUEUE"
    },
    "text": "{\"status\": \"shipped\"}"
  }
}
```

Messages are answered while replay runs. Start it on the web UI's JMS replay page, or with a call. `replay.json`, for the broker inside Traffic Parrot:

```json
{
  "action": "START",
  "broker": {
    "type": "INTERNAL",
    "internalProvider": "ACTIVE_MQ",
    "internalPort": 9091
  },
  "queue": {
    "consumeRequestsFromConnectionId": "USE-TRAFFIC-PARROT-INTERNAL-BROKER",
    "replayResponsesToConnectionId": "USE-TRAFFIC-PARROT-INTERNAL-BROKER"
  }
}
```

```bash
curl -X POST http://localhost:8080/jms/replay \
  -H "Content-Type: application/json" \
  -d @replay.json
```

```
{
  "flash" : {
    "success" : "Started"
  },
  "status" : "ON"
}
```

A message `{"order": "A-1001", "status": "?"}` sent to `orders.request` on `tcp://localhost:9091` is answered on `orders.response` with `{"status": "shipped"}`. For a broker of your own, define a connection in [`jms-connections.json`](https://trafficparrot.com/documentation/5.66.x/jms.html#define-jms-connections) and choose it when you start replay.

### Native IBM MQ

The same mapping in `ibm-mq-mappings/`, with the IBM MQ schema and the queues of your queue manager, is a native IBM MQ mapping:

```json
{
  "$schema": "http://localhost:8080/schemas/ibm-mq-mapping.schema.json",
  "mappingId": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
  "request": {
    "destination": {
      "name": "DEV.QUEUE.1",
      "type": "QUEUE"
    },
    "bodyMatcher": {
      "contains": "status"
    }
  },
  "response": {
    "destination": {
      "name": "DEV.QUEUE.2",
      "type": "QUEUE"
    },
    "text": "{\"status\": \"shipped\"}"
  }
}
```

Start replay with the id of a connection in [`ibm-mq-connections.json`](https://trafficparrot.com/documentation/5.66.x/ibmmq.html#define-connections):

```bash
curl -X POST http://localhost:8080/ibmMq/replay \
  -H "Content-Type: application/json" \
  -d '{"action": "START", "queue": {"consumeRequestsFromConnectionId": "1", "replayResponsesToConnectionId": "1"}}'
```

A message containing `status` put on the request queue is answered on the response queue with `{"status": "shipped"}`. Every queue the mappings name has to exist on the queue manager, or replay does not start.

### File messages

A file message mapping answers a file with a file. Its `destination` is a directory under a root directory from [`root-directories.json`](https://trafficparrot.com/documentation/5.66.x/filemessage.html#configuration), `fileNameMatcher` matches the request file's name, and `fileName` names the reply. `file-mappings/order-status.json`:

```json
{
  "$schema": "http://localhost:8080/schemas/file-message-mapping.schema.json",
  "mappingId": "7e6d5c4b-3a29-4f18-9e07-1a2b3c4d5e6f",
  "request": {
    "destination": {
      "name": "orders/in",
      "type": "QUEUE"
    },
    "fileNameMatcher": {
      "matches": ".*\\.json"
    },
    "bodyMatcher": {
      "contains": "status"
    }
  },
  "response": {
    "destination": {
      "name": "orders/out",
      "type": "QUEUE"
    },
    "fileName": "order-status.json",
    "text": "{\"status\": \"shipped\"}"
  }
}
```

Create `orders/in` and `orders/out` under the root directory, and start replay with the root directory's id. In the shipped `root-directories.json`, id `2` is `/tmp/file-transfers-root` and id `1` is `c:/tmp/file-transfers-root`:

```bash
curl -X POST http://localhost:8080/fileMessage/replay \
  -H "Content-Type: application/json" \
  -d '{"action": "START", "directories": {"consumeRequestsFromRootDirectoryId": "2", "replayResponsesToRootDirectoryId": "2"}}'
```

Move a file `order-1001.json` holding `{"order": "A-1001", "status": "?"}` into `orders/in`. Traffic Parrot takes it, and `orders/out/order-status.json` holds `{"status": "shipped"}`.

## Three mistakes to know

Each of these loads without an error. The [`validate` command](https://trafficparrot.com/documentation/5.66.x/mappings-by-hand.html#validate) catches the first two.

### A Java method name used as a key

`mappings/dsl-name.json`:

```json
{
  "request": {
    "method": "GET",
    "urlEqualTo": "/orders"
  },
  "response": {
    "status": 200,
    "body": "every request gets this"
  }
}
```

`urlEqualTo` is a method of WireMock's Java API, not a mapping key. Traffic Parrot drops a key it does not know, so this mapping has no URL and answers every `GET`:

```bash
curl -i http://localhost:8081/anything/else
```

```
HTTP/1.1 200 OK
Vary: Origin
Matched-Stub-Id: 08deea7a-68a2-35d1-816e-d46931fde25f
Matched-Stub-Name: dsl-name.json
Content-Length: 23

every request gets this
```

The URL keys of a mapping file are `url`, `urlPattern`, `urlPath`, `urlPathPattern` and `urlPathTemplate`.

### HTTP keys in a messaging mapping

In `jms-mappings/http-keys.json`:

```json
"request": {
  "destination": {
    "name": "orders.request",
    "type": "QUEUE"
  },
  "bodyPatterns": [
    {
      "contains": "status"
    }
  ]
}
```

`bodyPatterns` belongs to HTTP mappings; a messaging mapping has one `bodyMatcher`. While this file is in `jms-mappings/`, no message on its queue is answered, one that a correct mapping beside it matches included, and the log does not name the file:

```
ERROR QueueReplayService-jms-vs-Default-0 Skipping JMS message because of an unexpected error
java.lang.IllegalStateException: Request must either match text or bytes!
```

`validate` does name it:

```
Messaging mapping 'jms-mappings/http-keys.json' does not match jms-mapping.schema.json: /request: required property 'bodyMatcher' not found
Messaging mapping 'jms-mappings/http-keys.json' does not match jms-mapping.schema.json: /request: property 'bodyPatterns' is not defined in the schema and the schema does not allow additional properties
```

### A query string in `urlPath`

```json
"request": {
  "method": "GET",
  "urlPath": "/invoices?status=open"
}
```

`urlPath` is compared with the path alone, so this mapping never matches: `GET /invoices?status=open` is answered with `900`. Nothing reports it, `validate` included. Put the query in `queryParameters`, as `orders-open.json` does above, or match path and query together with `url`.

If you come from WireMock: a response needs no `response-template` transformer here. See the page for [WireMock users](https://trafficparrot.com/documentation/5.66.x/wiremock_users.html).
