Change a field mapping

The mapping decides how each incoming HL7 field becomes a field in the FHIR resources NEEV sends. Every HL7 → FHIR conversion node starts with a generated mapping that covers the usual fields. You change only the fields that need to be different, for example writing family names in title case because the receiving system expects it.

A change never reaches messages by surprise. It goes through four stages:

1. Draft. Saving a change puts it in the draft, shown on the blue Test card. Messages keep using what is live.
2. Test. Run test runs the draft over recent messages without delivering anything.
3. Live release. Promote to live turns the tested draft into a numbered release, shown on the green Live card.
4. Applied. Apply live release to node saves the release into the Project's conversion node, and Save on the Orchestration page loads it for incoming traffic.

Before you begin

• A Healthcare Project with a saved HL7 → FHIR conversion node. The assistant can build one for you.
• Edit access to that Project. Without it, the node shows "This node is read-only."
• The member or admin role. See who can do what.

1. Choose the node

1. Open Configure › Mapping in the left sidebar.
2. Under Project, choose the Project.
3. Under Conversion node, choose the HL7 → FHIR node. Most Projects have one.
4. Select Open node Mapping editor.

The editor lists every field the node writes, grouped by Message, Facility, Patient, Encounter, Diagnoses and Allergies. Each row shows the HL7 field, the FHIR element it fills, the rule used, and what it produces from a sample message.

tip

Open Project canvas takes you to the Project the node belongs to. On the Project canvas, the node's own panel opens the same editor.

Or ask Neev

The Map with Neev panel on the right takes requests in plain English, for example "Write given names in title case", or select Explain these mappings or Check source fields. Neev puts its changes in the draft and tests them on a sample, then shows a Review before applying card with each field it would change. Nothing changes until you select Confirm and apply. That does steps 4 and 5 below in one go: it promotes the draft to a new live release and applies it to the node, with the note "Applied through Mapping Neev after user confirmation". Incoming traffic still uses the old mapping until you load it: "This did not activate or reload Gateway."

If the mapping or the Pipeline changed after you reviewed the card, applying is refused: "Mapping or Pipeline changed after confirmation. Inspect and confirm the new version." Ask Neev again to get a fresh card.

Neev waits while you have a field open in the editor: "Finish your field edit first." Save or cancel the edit, then ask again. Collapse the panel with the button at its top right to give the editor more room.

2. Change a field

1. Find the field, for example PID-5.2 Given name, and select its pencil icon.
2. Under Incoming field, keep the HL7 field or choose another. Another field… takes any position, for example PID-4.
3. Under Transformation rules, choose a rule. Add more with Add rule; they run top to bottom. Each rule shows what it does to the sample, and Preview shows the final value.
4. Select Save change.

Editing the given name: Title case turns JANE into Jane

The first time you change a generated field, NEEV asks you to confirm. Select Use my mapping.

Replace the generated mapping? Messages keep the live mapping until the draft is tested and promoted.

The Test card now reads Draft v1 · 1 manual line and "1 change not live yet." Nothing has changed for messages.

Rules you can use

Rule	What it does
Copy	Uses the incoming value as it is.
Date to ISO, Date-time to ISO	19840212 becomes 1984-02-12; HL7 date-times become ISO 8601.
Default value	Uses a value you give when the field is empty.
Fixed value	Always writes the value you give.
Uppercase, Lowercase, Title case	Changes the letter case.
Strip leading zeros, Digits only	Cleans up identifiers such as 000123 or MRN-123.
Add prefix, Add suffix	Adds text before or after the value.
Gender code	Turns HL7 codes such as F into FHIR values such as female.
Value lookup	Swaps values using a table you fill in, for example local ward codes.

Under Advanced · message and resource selection you can limit a line to ADT only or ORU only messages, and choose whether it writes to One unique resource (reject ambiguity) or All matching resource types.

Map a field that isn't listed at the bottom of the list adds a line for any other FHIR element.

3. Test the draft

Select Run test on the Test card.

The draft runs over the newest messages on the feed, or over a sample message if the feed has no traffic yet. Nothing is delivered and no message is logged. The result shows:

• "Test passed on draft v1. You can promote it to live." or the problems found.
• The go-live check: required FHIR fields that the draft would leave empty. A red required field blocks promotion.
• Each draft line in the test: how many messages each changed line Written to, and how many it left Not written.

A passed test, with the go-live check and each draft line's result

Not enough traffic

The go-live check needs at least 10 recent messages. With fewer it says "not enough traffic". You can still promote; run the test again once messages are flowing.

4. Promote it to live

1. Select Promote to live on the Live card.
2. The dialog shows each field that changes, with the generated rule beside yours and the effect on the sample.
3. Add a Note saying why, for example "Given names in title case, as the receiving FHIR server expects." It is kept with the release.
4. Select Promote to live.

Promote draft v2 to live: the change, its effect, and a note

The go-live check runs again first. If a required field has turned red, the promotion stops, whatever your role.

The Live card now shows Release 1 with who promoted it and when.

Promoting without a passing test

A member can promote only a draft whose latest test passed. An admin can promote an untested draft after confirming; the release is then marked Promoted without a passing test in its history.

5. Apply the release to the node

A release is ready, but the Project's node does not use it yet.

1. Scroll back to Field mapping at the top of the page.
2. Under Live Mapping release, choose This node · release 1. To check what it contains, select the "1 field rule in selected release" line below it.
3. Select Apply live release to node.

The live release is applied to the node, saved as a new Pipeline revision

The banner reads "Saved to Pipeline revision 2. Reload the Orchestration into Gateway to apply this snapshot to incoming traffic." The pill changes to Mapping applied with the Pipeline revision, and stays there when you come back later.

Reusing an older feed mapping

Releases promoted on a feed before node mappings existed are listed as Import from feed · release n. Choose one to copy its rules onto this node.

6. Load it for incoming traffic

Incoming messages keep using the snapshot that was loaded when the orchestration was last saved. Open Orchestration and select Save, even if you changed nothing on the canvas. From the next message on, the new mapping is used.

History, snapshots and roll back

Select Releases and roll back on the Live card, or the History & snapshots tab.

Live releases, changes since the generated mapping, snapshots and every version

• Live releases: every release, newest first, with its note. Show what went live lists its changes.
• Since the generated mapping: what the draft changes. Save as snapshot keeps the current set of changes under a name.
• Snapshots: named sets of changes you can go back to.
• Every version: each saved draft, with Current draft, Live and Test passed marks. Restore puts an earlier version back in the draft.
• Shared fixes: fixes people chose to share for review with Share this fix for review. Export CSV downloads them.

Roll back

1. Under Live releases, select Make live again on an earlier release, or Roll back to the generated mapping at the top.
2. Confirm with Make live again.

Rolling back needs no test, so a bad mapping can always be backed out. It is recorded as a new release; nothing is deleted. Then apply the release to the node and save the orchestration again.

To throw away changes that are only in the draft, select Discard draft changes on the Test card and confirm. The draft goes back to the live release. Live does not change, and the discarded draft is kept as a snapshot called "Before restoring live release n", so you can restore it.

Who can do what

Action	Viewer	Member	Admin
See fields, versions and releases	Yes	Yes	Yes
Change a field, run a test, discard, restore		Yes	Yes
Promote a draft whose test passed		Yes	Yes
Promote an untested draft (recorded)			Yes
Roll back		Yes	Yes
Apply a release to the node		With Project edit access	With Project edit access
Promote past a red go-live check