Formula Mappings

Formula mappings use expressions to compute the value for a target field. They support transforming, combining, and manipulating data during migration.

Creating a Formula Mapping

1. Open a Migrate Records step and navigate to the Fields tab
2. Select a target field to edit its mapping
3. Choose Formula as the mapping type
4. Enter your formula expression in the editor

Formula Syntax

Formulas use a Python-like expression syntax with some Precision Bridge-specific conventions:

Referencing Source Fields

Use square brackets to reference source field values:

[short_description]
[sys_id]
[priority]

String Concatenation

Use the + operator to combine strings:

[short_description] + ' - migrated using PBv10!'

Referencing Variables

Procedure variables and mapping variables can be referenced directly by name:

incident_id_map.get([element_id])

Important Notes

• Use regular single (') or double (") quotes to enclose strings in formulas — do not use backtick characters
• Formulas have access to all source fields, procedure variables, and mapping variables
• The formula is evaluated once per record during processing

Examples

Formula	Description
[short_description] + ' (migrated)'	Append text to a source field
[priority] + 1	Increment a numeric value
'Migrated from ' + [sys_id]	Combine a constant with a field value
my_variable.get([key_field])	Look up a value from a dictionary variable

AI-Assisted Formula Generation

When the LLM Provider preference is configured and validated, an AI panel appears inline above the formula editor. It drafts a candidate formula from a natural-language description, validates it against the live engine, evaluates it against a few sample inputs, and surfaces the result in a Sample Results table for you to review before accepting.

To use it:

1. Open a Formula mapping. The AI panel is expanded by default when an LLM is available, and collapsed (with a disabled affordance) when no provider is configured.
2. Type a description of what the formula should do — for example, "Concatenate first name and last name with a space", or "Return true if the due date was last year".
3. Press Enter or click the submit arrow inside the prompt input.
4. Review the suggested formula, the one-sentence explanation, and the sample results below.
5. Click Test to try the formula against your own values in the Formula Test dialog, or Insert to write it into the editor.

The assistant has visibility into the source table's fields, the procedure and mapping variables in scope, and the full list of built-in formula functions. It refuses prompts that fall outside what a formula can do (sending emails, calling APIs) or that are too vague to satisfy, returning an explanation rather than a guess.

Datetime reasoning: When the formula reasons about "now", "today", "yesterday", or similar wall-clock concepts, the suggestion is anchored to UTC via datetime.now(timezone.utc) so the result is independent of the host machine's timezone. The explanation field calls this out. See Available Built-in Functions for the full UTC vs local guidance.

The same AI affordance is available behind the Generate button in the standalone Formula editor used by ID mappings, Match mappings, and custom validation rules — there the assistant opens in a dialog rather than inline.

Options

Each Formula mapping has an Options accordion (collapsed by default) housing settings that are less commonly changed:

• On-error action — what to do when the formula raises at runtime: fail the record, set the target to None, or substitute a default value.
• Default value — shown when On-error action is Set Default. The value type matches the target field's data type.
• Exclude from sampling — omit this mapping when running a sampled dry-run or per-field preview.

The Options accordion appears across every mapping type (Source Field, Constant, Formula, Match, Lookup, ID), with controls specific to each.

Learn More

This article covers the basics of formula mappings. For comprehensive documentation on the formula language, including advanced features like comprehensions, conditional logic, string operations, and the complete functions reference, see the Formula Language category.