Choose where a connector's records land

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

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

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

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.

Terminal
marfa plugins mapping set tracker mapping.yaml
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

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:

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

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

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:

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

The rules behind this page are in the plugins chapter of the contract.

On this page