# Choose where a connector's records land (/use/map-a-connector)

Map each kind of record a plugin's connector brings onto a type and tier you choose, fill the type's fields, and rewrite what it already brought.



A plugin's connector brings one or more **kinds** of record, such as a tracker's issues and comments, and each lands by default as the connector's own type, in the [feed](/build/items-and-types#library-and-feed). **The mapping** lets you change that for each kind: whether it comes in, the type and tier it lands as, and where each field's value comes from. The connector reads the mapping and writes each kind as it says. Each command needs `connectors.manage`.

## Read the mapping [#read-the-mapping]

```bash
marfa plugins mapping show tracker --json > mapping.json
```

Until you save one, each kind shows its default at `version` `0`: its own type, `feed`, and each field filled from the field of the same name, unless the plugin's author set another default.

## Change it [#change-it]

Edit the file, in JSON or YAML. This sends the tracker's issues to your tasks, in the library:

```yaml title="mapping.yaml"
version: 0
kinds:
  issue:
    enabled: true
    target_type: core.task
    tier: library
    status_overrides:
      open: not_started
      closed: completed
    fields:
      title: { from: title }
      description: { from: summary }
      url: { from: url }
      notes: { fixed: "From the tracker" }
      body: { template: "Reported by {{ reporter }}" }
```

Each field takes exactly one of `from`, a field of the connector's own type; `fixed`, one value for every item; or `template`, a Jinja template the connector fills, for a text field only. `status_overrides` turns each of the connector's status words into one the target type has. `enabled: false` leaves a kind out.

```bash
marfa plugins mapping set tracker mapping.yaml
```

Output:

```text
saved the mapping of tracker at version 1
```

A kind or member you leave out keeps its default. **Marfa checks the mapping as it saves it** and refuses `400 validation_error`, naming the path, for a required field nothing fills, a field the type lacks, a fixed value the field refuses, a template on a field that isn't text, a status word either type lacks, or a target type under `system`. The target type also needs write in your own reach. A mapping saved since you read yours is refused `409 connector_mapping_stale`: read it again.

## Preview a kind before you save it [#preview-a-kind-before-you-save-it]

To see how one kind would land, put a draft of its entry, the part under `issue:` above, in a file of its own, and ask the connector to render it:

```bash
marfa plugins mapping preview tracker --kind issue --file issue.yaml --wait
```

Marfa checks the draft as a save would, and saves nothing. The connector renders it on its next look, on the item `--item` names or one it chooses, and `--wait` prints the fields it filled. Without `--file`, it previews the mapping in force. **A preview lasts 10 minutes,** and one the connector couldn't render, or didn't answer in time, ends with `preview_ended`.

## What a mapped connector may reach [#what-a-mapped-connector-may-reach]

**On a type that isn't its own, a connector reads and writes only its own items,** those under its source, so mapping it onto `core.task` never lets it see or change your own tasks, or a link you made from one. Its bin, restore and purge never carry your items with its own. On its own types, its key decides alone.

## Rewrite what it already brought [#rewrite-what-it-already-brought]

Saving a mapping changes no item: it applies to what the connector writes next. To bring the items it already wrote on each kind's target type into line, such as after you fill another field, count them first, then ask:

```bash
marfa plugins mapping rewrite tracker --dry-run
marfa plugins mapping rewrite tracker --kind issue
```

The first answers `a rewrite of tracker would touch issue: 214 on core.task`. The second stores a numbered request that the connector carries out on its next run and then clears; until then, `mapping show` lists it under `rewrites`.

Removing the plugin removes its mapping. An archive carries it, and a restore keeps a mapping you saved over the archive's ([Move your data with an archive](/run/export-and-restore#what-a-restore-changes)).

The rules behind this page are in the [plugins](https://github.com/withmarfa/marfa/blob/main/conformance/spec/plugins.md#a-connectors-mapping) chapter of the contract.
