Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bundle ¶
Bundle renders every channel into one Markdown document.
Sorted by name, because Go maps and directory listings both range in an order nobody chose, and a document that reorders itself between runs cannot be diffed - which removes the main reason to keep it in version control. Bundle takes the channels that loaded and the files that did not, keyed by name with the reason.
Broken files are part of the document rather than the caller's problem, and rendering them here rather than in each caller is the point: the API endpoint and the file on disk must say the same thing, and two renderers drift.
func DescribeTransport ¶
func DescribeTransport(d config.Destination) string
describeTransport says where a destination sends, without credentials.
Never a DSN, never a token. A specification is a document that gets emailed to a vendor, which is the last place a password should end up. DescribeTransport says where a destination sends, in one phrase.
Exported because three places were describing destinations independently and the CLI's version knew only about addresses and directories - so every other destination type printed a blank where its target should be. A single function means a new destination type is described everywhere at once, or nowhere, rather than in two places out of three.
func DescribeV3Step ¶
DescribeV3Step says what one HL7 v3 transformation step does, in words.
Words rather than the YAML, because the reader of a specification is often not the person who wrote the channel - it is somebody at the other end of the feed asking what happens to their data, or an auditor asking what is changed.
The three removals are described distinctly and deliberately. "Clears" and "records that no value is available" and "removes" read almost the same in a summary, and they are not the same: a masked address is a decision somebody made, and a downstream system that fills the gap from another source has undone it.
Types ¶
type Delivery ¶
type Delivery struct {
Name string `json:"name"`
// How describes the transport in words, without credentials.
How string `json:"how"`
// When describes the destination filter, empty when it takes everything.
When string `json:"when,omitempty"`
// Durable says whether a message survives the receiver being unavailable.
Durable bool `json:"durable"`
}
Delivery is one place the interface sends.
type Document ¶
type Document struct {
Channel string `json:"channel"`
Description string `json:"description,omitempty"`
DataType string `json:"dataType"`
// Receives and Acknowledges are the contract with the sender.
Receives string `json:"receives"`
Acknowledges string `json:"acknowledges"`
// Accepts describes the filter in words, empty when everything is accepted.
Accepts string `json:"accepts,omitempty"`
// Reads are the fields the interface depends on. This is the list a sending vendor needs:
// these are the fields that must be populated for the interface to work.
Reads []FieldUse `json:"reads,omitempty"`
// Writes are the fields the interface changes. This is the list a receiving vendor needs.
Writes []FieldUse `json:"writes,omitempty"`
Mappings []Mapping `json:"mappings,omitempty"`
Steps []string `json:"steps,omitempty"`
Deliveries []Delivery `json:"deliveries,omitempty"`
// Caveats are the things this document cannot tell you, stated rather than omitted.
Caveats []string `json:"caveats,omitempty"`
// Narration is the same document in sentences, for somebody who needs to know what this channel does rather than to hand a
// specification to a vendor. Derived from the fields above, so the two cannot describe the channel differently.
Narration []string `json:"narration,omitempty"`
}
Document is a whole interface specification.
type FieldUse ¶
type FieldUse struct {
Path string `json:"path"`
// Name is from the HL7 dictionary, when the standard defines the field.
Name string `json:"name,omitempty"`
// Description adds what the dictionary knows beyond the name.
Description string `json:"description,omitempty"`
// Table is the HL7 table constraining it, when there is one.
Table string `json:"table,omitempty"`
// Repeats reports whether the standard allows repetition, which a receiver has to handle
// whether or not this sender uses it.
Repeats bool `json:"repeats,omitempty"`
// Why says what the interface does with it: tested by the filter, written by a step,
// read by a destination.
Why []string `json:"why"`
}
FieldUse is one path the interface touches.
type Mapping ¶
type Mapping struct {
Path string `json:"path"`
Name string `json:"name,omitempty"`
// From and To are parallel: From[i] becomes To[i].
From []string `json:"from"`
To []string `json:"to"`
// Unmatched says what happens to a value not in the table.
Unmatched string `json:"unmatched"`
}
Mapping is one code translation the interface performs.
Listed in full, because this is the part a receiving vendor most needs and the part most often missing from a hand-written document. A translation table in a channel file is precise; the same table transcribed into prose is where the errors come from.
Source Files