Field Mapping

Field Mapping lets Admins extend Realm9's built-in forms with organisation-specific fields — custom data captured on environments, environment requests, decommission requests and bookings, plus the reusable field groups behind Additional Forms.

Path: Configuration → Field Mapping in the sidebar (Admin/Super Admin only). Each target area has its own page — /settings/fields/environment, /settings/fields/request-form, /settings/fields/decommission, /settings/fields/booking, and /settings/fields/additional.

---

Where Custom Fields Apply

Field Mapping has five separate target areas, each on its own page under Configuration → Field Mapping in the sidebar:

• Environment — fields shown on the environment create/edit form and as tabs on the environment detail page
• Request Form — fields shown on the Environment Request create/edit form and detail page
• Decommission — fields shown on the Decommission Request create/edit form and detail page
• Booking — fields shown on the booking create/edit form and on the Forms tab of the booking detail page. Bookings also carry three groups that hold no fields — Booking Provisioning, Booking Access Info and Cost Information. They are rendered by panels rather than by configured fields, but they order, tab and switch off like any other section
• Additional Form — reusable groups of fields an approver can include when asking for more information mid-review. Everything picked in one action becomes a single form, and these are its sections (see Additional Forms for how that works at runtime)

Don't confuse the Booking target with Booking Control. The Booking target is what a requester fills in when asking for an environment. Booking Control is a system field group under the Environment target, holding that environment's own rules — whether it can be booked at all, whether it needs approval, its maximum duration. One is a question put to the requester; the other is a setting on the thing being requested.

---

Field Groups

A field group is a named collection of related fields, shown as its own card (or its own tab, if tab-assigned) on the relevant form.

Each group has:

• Name / Display Name / Description
• Enabled toggle — disabled groups are hidden from forms but their data isn't deleted
• Order — position among other groups
• Tab — optionally assign the group to a named tab (see Tabs below); ungrouped fields render above the tab bar
• Sensitivity — can be marked sensitive/encrypted (see Sensitive Fields below)

Creating and editing a group

Add Custom Group opens a full page rather than a popup, and editing an existing group does the same. The group's own settings sit at the top, the fields it contains below, and Save and Cancel stay pinned to the bottom no matter how long the field list gets.

The page has its own address, so you can bookmark a group you're working on, share the link with a colleague, or reopen it from history. Opening a link to a group that has since been deleted — or one belonging to another organisation — tells you so, rather than quietly starting a new group.

Adding a field opens a dialog. Fill in the field and press Add Field; it joins the list on the page behind, expanded so you can refine it straight away. Nothing is written until you save the group, so you can add several fields, reorder them, and change your mind before committing.

Leaving with unsaved changes asks first. That covers Cancel, the sidebar, the breadcrumb, the browser's Back button and a reload — anything that would lose the edit. Choosing Keep editing leaves everything exactly as it was. If you haven't actually changed anything, you leave without being asked.

System Groups vs. Custom Groups

Each target area ships with a few built-in system groups that can't be deleted, only enabled/disabled (and some can't even be disabled) — for example, Overview and Booking Control on Environments, Basic Information on Request Forms, Basic Details on Decommissions, and Booking Details on Bookings. Additional Form Fields has no system groups — everything there is admin-defined.

Everything else is a custom group you create yourself, either from scratch or by importing from a template.

---

Fields and Field Types

Within a group, you add individual fields. Supported types:

Each field can have a description/help text, placeholder, default value, and be marked required. Text/number fields support length or value range validation and (for text) a regex pattern.

Date validation

Date and Date & Time fields can restrict which dates users may pick, via two settings in the field editor:

• Earliest allowed date — No limit, Today (no past dates), Tomorrow (future dates only), or a specific date
• Latest allowed date — No limit, Today (no future dates), Yesterday (past dates only), or a specific date

Both bounds are inclusive and compared by calendar day — "Today (no past dates)" still accepts today itself, and for Date & Time fields a time earlier today is fine. Use Tomorrow (future dates only) when today itself must not be selectable, and Yesterday (past dates only) for strictly-past dates. The Today/Tomorrow/Yesterday options are relative: they resolve to the current date every time the form is used, not the date the rule was saved. Out-of-range days are greyed out in the date picker, and a value outside the range fails validation on submit.

Date validation applies to forms built on the form engine — Environment, Request Form, Decommission and Booking. Additional form fields don't support it.

---

Conditional Visibility

Any custom field or custom group can be set to appear only when another field's value on the same form matches a condition. Until it matches, the field isn't on the form at all.

Available on Environment, Request Form, Decommission and Booking. Additional form fields don't support conditional visibility.

Creating a rule

• On a field — expand the field within its group and turn on Show this field conditionally
• On a group — open the group's settings and turn on Show this group conditionally

Then build the condition: pick a field, pick a comparison, and pick or type a value. It reads as a sentence — "Show this field when this matches: Environment Type is Production."

You can add up to 20 conditions and choose whether all or any of them have to match.

What can be used as a condition

Any field on the same form, in any group — including built-in ones like Environment Type. Cross-group conditions are normal and expected: a field in Costs can depend on a field in Networking.

These can't be picked:

Comparisons

The comparisons you're offered depend on the type of the field you picked:

A rule always compares against a fixed value you choose, never against other records in the system. Where the field has a defined set of options — a dropdown, a multi-select, or Environment Type — you pick from that list rather than typing the value.

What people see on the form

A hidden field isn't rendered at all. A required field that's hidden doesn't block submission — the requirement only applies while the field is showing. A group rule hides the entire card at once.

Values are removed when a field is hidden. If someone fills a field in, then changes the value that hides it, then saves, the value they entered is deleted rather than kept invisibly on the record.

A value that was already hidden when the form was opened is left alone. The person editing never saw it and made no decision about it, so an unrelated edit won't quietly discard it.

Spotting conditional fields in Field Mapping

• A field with a rule shows a small conditional marker on its row, even when collapsed
• A group with a rule shows a Conditional badge

Without these, a conditional field looks identical to one that is simply missing.

Rules can't loop

If a field only shows when another one matches, that second field can't be made to depend back on the first. The save is refused and the loop is shown, because there's no consistent answer to "which of these is visible".

Auditing

Every rule change is recorded in the Field Mapping audit trail with the before and after rule — including changes that were refused. See Audit Logs.

---

Highlighting Important Fields

A status column tells you at a glance which row needs attention. By default a custom field can't: Data Classification: Restricted renders exactly like Runtime Version: 3.11, so the one answer a reviewer must not miss sits in the same grey as sixty that don't matter.

Highlighting marks a field so its saved answer reads the way a status does. Available on Environment, Request Form, Decommission and Booking fields.

Turning it on

Open the field in Field Mapping and pick a Highlight style. There are two, plus off:

Then pick one of eight colours. A live preview shows the result as you choose, so you're not guessing.

Colouring by answer

For a dropdown, a toggle or a checkbox list, you can go further and give each answer its own colour — so the same field shows No in red and Yes in green, exactly the way a status column does. Pick the style and base colour first, then set colours per answer underneath; each row shows a live preview of that answer.

• An answer you don't colour uses the field's base colour, so adding a new dropdown option later never leaves it unstyled.
• Click a colour again to clear it and fall back to the base.
• A toggle is mapped as Yes / No — what the form actually shows — rather than true/false.
• A checkbox list with one answer selected takes that answer's colour. With two or more there's no single colour, so it uses the base.
• Text, number and date fields don't offer this — there's no fixed set of answers to map. They still take one colour for the whole field.

The colour follows the answer everywhere: in read views, and live in the form as someone changes the dropdown.

What it looks like where

• Viewing a request, environment or decommission — the highlight is applied in full: the pill, or the tinted panel.
• Creating or editing — the field keeps a standard input, with a coloured edge and a coloured label. The control itself is left alone deliberately: an input already uses its border to show focus and validation errors, and a second colour on top makes "this field matters" and "this field is invalid" look alike.

Things worth knowing

• Highlighting is per field, not per group. Highlight the two answers that matter, not the whole section. A form where every field shouts is one where nothing does.
• An unanswered field is never highlighted. A chip around nothing reads as a rendering fault, and drawing the eye to Not provided is the opposite of the point.
• A hidden field is never highlighted, because it isn't shown at all. If a visibility rule hides a field, its highlight goes with it.
• No and 0 are answers, not blanks, and are highlighted. Making Encryption at rest: No impossible to miss is exactly what this is for.
• Highlights carry onto the environment. A highlighted field on the request form keeps its highlight when its answer is inherited onto the environment — the emphasis belongs to the question, not to one form.
• Password fields can't be highlighted. Their value is masked behind a reveal control everywhere, so there's nothing to emphasise — the highlight controls aren't offered on a password field at all.
• In a sensitive group, the highlight appears once the values are revealed. Until someone presses Reveal there is no answer on screen to colour, so nothing is highlighted — which is the same rule as any unanswered field. After revealing, a highlighted field is coloured exactly as it would be in an ordinary group. Password fields stay plain, as above.
• Existing fields are unaffected — highlighting is off until someone turns it on.

---

Tabs

For Environment, Request Form, Decommission and Booking targets, you can create named tabs and assign groups to them, then drag and drop to reorder groups within or across tabs. Renaming a tab is inline; deleting a tab just un-assigns its groups back to "no tab" rather than deleting them. Additional form fields don't support tabs — each group is a flat set of fields. The tabs that appear on a request itself are a separate thing: everything an approver picks in one action becomes a single additional form, with one section per group picked, shown as its own tab beside the request's own form.

---

Carrying Request Details onto the Environment

A group on the Request Form can be marked Inherit to environment. When it is, whatever the requester filled into that group is carried onto the environment created from the approved request, where it becomes part of the environment's own details — visible when viewing the environment and editable when editing it.

Some things carry across regardless — the environment name, the requested software, and a few others. This setting is how you add your own.

Turning it on. Open Request Form Fields, find the group, and switch on Inherit to environment. The toggle appears on custom request groups only: the built-in ones hold information that lives on the request itself rather than as environment fields, so there would be nothing to carry.

Seeing the full picture. Groups you've marked appear under Inherited from request at the bottom of Environment Fields. That list is read-only — the groups belong to the request form and are edited there — but it means you can see everything an environment will hold in one place. Use Configure in Request Form to jump to the group itself.

What the person creating the environment sees. The create-environment form shows the group already filled in with what the requester provided. They can change anything before saving; edits affect the environment only and never alter the original request. A group the requester left blank still appears, empty and ready to complete — so environments of the same type stay consistent.

Sensitive groups work exactly as they do elsewhere. Values stay encrypted, and someone below the minimum role sees the group without its values rather than the values themselves.

Turning it off later stops future environments inheriting the group. Environments that already have it keep the group and everything recorded in it — no data is removed.

---

Templates

Rather than building common field sets from scratch, you can import pre-built templates:

• Environment Request Form — a full 30-field template
• Environment Design Document (EDD) — a 25-field template
• Decommission Checklist — a 17-group template across two tabs (Environment Checklist and Service Checklist), covering things like data management, access/security sign-off, backout plans, and incident/problem/knowledge management — the same template referenced in Decommissions

Importing is per-group, not all-or-nothing — expand a template to preview its groups and fields, then pick which ones to bring in. Groups already imported from a template are shown as such and can't be re-imported as duplicates.

---

Sensitive Fields and Encryption

Any custom group can be marked sensitive, which:

• Encrypts all existing values for that group's fields (AES-256-GCM)
• Is one-way — once marked sensitive, a group cannot be unmarked
• Lets you set a minimum role required to view the values (defaults to Viewer, i.e. no extra restriction, but can be raised)
• Excludes the group's data from search, if desired
• Is logged to a dedicated sensitivity audit trail, in addition to the general audit log

Two system groups — Access Credentials and Terraform Workspace — ship pre-marked sensitive by default. Any field of type Password automatically marks its parent group sensitive.

Separately, there's an org-wide Sensitive Data Access setting (at the top of the Field Mapping page) controlling the minimum role that can view sensitive values across the board — a choice of Provisioner or Admin (default) or Admin only. This works alongside, not instead of, any per-group minimum role override.

---

Deleting and Disabling

• Deleting a field group that already has data attached to it (any environment, request, or decommission using it) is blocked — you'll see a list of what's using it and can disable it instead, which hides it from new records while keeping existing data intact.
• Removing a single field happens in two steps. Clicking the X on a field marks it: the row stays where it is, struck through, with an Undo button in its place. Nothing is deleted yet, and Undo puts it back exactly where it was. The field disappears only when you press Update, and Update asks first — one prompt listing every field being removed, warning that their stored values go with them. Backing out of that prompt saves nothing.
• A group cannot be saved with no fields left. If you mark every field, Update is disabled until you undo one or add another.
• A request group that has been inherited onto environments is protected further: deleting the group is blocked while any environment holds values from it, and so is removing one of its fields. The message names the environments affected. Turn off Inherit to environment first if you no longer need it — that stops new environments inheriting the group without touching the ones that already have it.

Removing fields while you edit

Everything in the editor is a draft until you save. Adding a field, editing one, reordering, and marking one for removal are all local changes — the group is written in a single save when you press Update or Create, so you can make several changes and review them together.

That has two consequences worth knowing:

• Marking a field for removal does not touch anything else you're doing. Other fields you've added but not yet saved stay exactly as they are.
• A marked field cannot be edited. Its row will not open, because any change you made there would be discarded by the save that deletes it. Press Undo first if you want it back.
• A field you're removing stops being offered as a condition. The moment you mark it, it disappears from the dependency picker on every other field and in the Add Field dialog — a rule pointing at a row the same save deletes is a rule that cannot work.
• Removing a field and adding a new one under the same internal name is refused. It looks harmless and isn't: the new field would silently take over the old row and everything stored in it, so the answers the removal prompt warned about would survive rather than go. If you also changed the type — a text field re-added as a dropdown — those inherited answers become values the dropdown doesn't even offer. Give the new field a different internal name, or undo the removal and edit the existing field in place.
• Two fields in a group cannot share an internal name. Display labels can repeat as much as you like — two groups both asking Region is normal — but the internal name is what identifies the stored answers, so it has to be unique within its group.

When a Visibility Rule Depends On It

• Deleting a field or group that a visibility rule points at is blocked. The message names every rule that depends on it, written as Group › Field, so you can find it even when the rule lives on a group you weren't working in. Either remove those conditions first, or delete the dependent fields in the same save — doing both at once is allowed, because nothing is left pointing at nothing.
• Inside the editor you're told before you confirm anything. If a field you're keeping has a rule conditioned on one you've marked for removal, Update refuses straight away and names both — rather than letting you confirm a prompt about destroying stored answers and only then failing. It refuses rather than quietly dropping the condition, because a field with no rule is visible: silently removing it would put a field that had been conditionally hidden in front of everyone.
• Disabling that group is allowed, with a warning — it's reversible, unlike deleting. Be clear about what it does, because it's the opposite of what most people expect: with the group gone from the form, the condition can no longer be evaluated, so the dependent field shows on every form rather than staying hidden. The warning names each rule affected.
• If a rule ends up pointing at a field that no longer exists, that condition is quietly dropped the next time the group is saved, and the field goes back to always showing.

---

Related Settings

• ServiceNow CMDB field groups are a related but separate mechanism — fields synced from a ServiceNow CI class — managed under ServiceNow/CMDB settings rather than here, and excluded from the main Field Mapping list.
• Custom fields you add here also become available as filters on the Environments list page.

---

Permissions

Field Mapping is restricted to Admin and Super Admin — unlike most infrastructure-adjacent settings, Provisioners do not have access here.

---

Next Steps

• Manage Environments
• Environment Requests
• Decommissions
• Additional Forms