Data exchange prototypes
Table of Contents
1. Summary
Importing and exporting a party, one dataset, or a whole environment. The journeys ask for a prototype; the screens answer them, because the trigger, the payload and the permission change a variant and the act changes a screen. Every import publishes into a sandbox chosen from the book tree, and every screen that records an attempt names that sandbox. The table of the screens opens each one; the table of the journeys walks from a journey to the state of the screen that serves it.
Each prototype is a static page under doc/prototypes/, opens with no build
and no session, and reads mock data only. Where a prototype carries a Gemini
review the last column opens it; none does. Prototypes is
the top page and the only inventory.
2. Why these screens, and not one per journey
A screen is a place a person acts. The journeys differ in what does not make a screen: the trigger (a defect, a seed, a promotion, a feed, a correction), the payload (a package, a sample tree, the market files, one conventions file), and who may act (tenant administrator, operations user, maintainer, support). Those are variants of the entry, and of the review, and of the register.
The differences that do make a screen are the acts themselves:
- Name a source and a scope. Every import journey starts here. Most of them share it because the first step is identical.
- Decide a staged import. A different act and a different actor: the maker cannot decide. One journey names it, and others pass through it.
- Read one attempt's outcome. A per-family question, asked after the commit. Several journeys ask it of the same record.
- Read the party's history. A question about all attempts, not one. No journey names it as its destination, and several need it. It is the one screen that survives without a journey of its own.
- Take data out. The writing side, shared by the export journeys and the import journeys that begin with an export.
Some consolidations deserve their own line. Reproduce a defect and Promote an environment get no screen: each is an export package, an entry, a review, a run and a register row, and another screen would duplicate them all. Import as a party-scoped user gets no screen either: it is the permission and scope variant of the entry, the review and the register, and giving it a screen would hide the boundary it is about. See what a failed family left behind is the run record in its failed state, and Retry is that record's retry plus the register's comparison — the same data read twice, not two screens.
3. The journeys and the screens that serve them
| Journey | Actor | Screens | State to open |
|---|---|---|---|
| Reproduce a defect | support engineer | Entry, Review, Run, Register, Export | ?case=defect on Entry and Run |
| Seed a fresh environment | operations user | Entry, Review, Run, Register | ?case=seed; ?attempt=2 on Run |
| Onboard a party | tenant administrator | Entry, Review, Run | ?case=onboard; ?state=families on Entry |
| Promote an environment | operations user | Export, Entry, Review, Run, Register | ?purpose=promote on Export; ?variant=promotion on Register |
| Import one dataset | reference-data maintainer | Entry, Review, Run | ?case=one-dataset |
| Retry a failed import | the importer | Run, Register | ?attempt=2 on Run; ?variant=compare on Register |
| Import as a party-scoped user | operations user | Entry, Review, Run, Register | ?case=party&actor=ops; ?actor=ops on Register |
| See what a failed family left behind | the importer | Run, Register | ?state=failed&mode=today on Run; ?variant=failed on Register |
| Import market data from a feed | market-data maintainer | Entry, Review, Run | ?case=feed; ?state=partial on Run |
| Export to share with support | any reader | Export, Entry | ?purpose=share; ?state=refused |
| Export for archival | operations user | Export | ?purpose=archive; ?instant=apart |
| Review an import before it is applied | the importer or a decider | Review, Entry, Run | ?state=decide; ?check=lookup |
4. The screens
| Prototype | What it argues | Open it | Review |
|---|---|---|---|
| Bring data in | The trigger is a variant, not a screen: name the source, the scope, the families and the sandbox target once, show the scan, the party rule, the missing permission and the book tree that refuses an official node, and name the workflow the import starts. | prototype | none |
| Stage an import | The review is its own screen because a second person decides there: the chosen sandbox, per-family new, replaced, unchanged and refused, where each family lands, the maker kept apart from the decider, and the staged rows as the commitment. | prototype | none |
| One import run | After the commit the only question is per family, so one attempt record answers the failure, the retry, the feed's sections and the seed's batch — and draws the atomic and per-family mechanisms side by side, over the live workflow instance that performed the import and the sandbox tree it fills. | prototype | none |
| The import register | The journeys need the party's history rather than one attempt, so the register holds the retry beside its first attempt, the promotion hops, the sandbox each attempt targeted, and the boundary that keeps another party absent. | prototype | none |
| Take data out | The support export, the archive, the promotion package and the sandbox package are one act with one manifest, one instant, the omissions named and the sandbox scope that reproduces a defect elsewhere. | prototype | none |
Progress is not another screen. The import is one workflow instance, and the
Run screen follows it: a region reads the instance
and its steps and draws ?wf=staged|in_progress|waiting|failed|retrying|completed|warnings|compensated,
with ?play=1 to walk them on a timer, and the sandbox tree beside it fills at
the commit. The Entry screen names the type, the
steps and the sandbox target before anything runs; the target travels as
?target=sb-import-repro from the entry to the review, the run and the register.
A decider-gated import needs two instances, one that stages and one that
applies, because an instance cannot wait for a person.
5. Adding a prototype
Create doc/prototypes/data_exchange/<name>/ with an index.html, and a
prototype.css and prototype.js when it needs them. Open the page with the
links table every prototype carries, and leave its review row at none. Write
the design note at doc/prototypes/data_exchange/<name>.org, add a row to the
table above, and link the note from the row's first cell. Add the journeys it
serves to the journey table. Stop there: the site build finds every prototype
under this tree, so no build file names it.
A review goes at doc/prototypes/data_exchange/<name>/review/, with an
index.html that lists its screens. The row names it. Prototypes
states the whole method and the rules that hold for every group.
6. See also
- Prototypes — the top page: the groups, and the one way to add a prototype.
- Data exchange journeys — the journeys these prototypes answer.
- Conventions prototypes — the authoring screen the review follows.