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.jsonUntil 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:
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.
marfa plugins mapping set tracker mapping.yamlsaved the mapping of tracker at version 1A 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 --waitMarfa 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 issueThe 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.