Field mappings tell Bridge how to translate fields from an external system into platform fields when records sync or import. Without mappings, Bridge can only pass through fields with identical names. Mappings let you rename fields, transform values (format dates, map status codes, truncate text, and more), and mark fields as required.
How Field Mappings Work
Each mapping belongs to a connection and an entity type (for example, the ConnectWise connection, Tickets entity). A mapping record contains:
- Source field — the field name as it arrives from the external system
- Target field — the platform field name to write to
- Transform function — an optional operation applied to the value before it is written
- Transform parameters — configuration for the transform (for example, the lookup table for a status map)
- Required — if checked, a record missing this field will be errored rather than skipped
Applying a Default Template
Bridge includes default mapping templates for the major PSA and RMM platforms. Applying a template saves you from building mappings from scratch.
- Go to Field Mappings in Bridge.
- Select your connection and entity type.
- Click Apply Template and choose the platform (for example, ConnectWise Manage - Tickets).
- Bridge populates all common field mappings with reasonable defaults.
- Review the mappings and adjust any that don't match your setup.
Adding or Editing a Mapping
- Go to Field Mappings, select a connection and entity type.
- Click Add Mapping or click an existing mapping to edit it.
- Enter the source field name exactly as the external API returns it.
- Enter the target field name as the platform expects it.
- Optionally select a transform function (see below).
- Save.
Available Transform Functions
Bridge provides the following per-field transform operations:
| Transform | What It Does |
|---|---|
dateFormat |
Converts a date/time string from the source format to the platform format |
statusMap |
Maps external status codes (e.g. "New", "In Progress") to platform status values |
priorityMap |
Maps external priority values to platform priority values |
truncate |
Shortens a string to a maximum length |
concat |
Joins two or more fields into one value |
split |
Splits a delimited string and takes a specified segment |
lookup |
Replaces a value using a lookup table you define |
lowercase / uppercase
|
Changes case |
trim |
Strips leading and trailing whitespace |
toNumber |
Converts a string to a numeric value |
toBoolean |
Converts a string like "true" / "1" / "yes" to a boolean |
default |
Supplies a fallback value when the source field is empty |
Chaining Transforms Into a Pipeline
For more complex transformations, you can chain multiple operations in order using Transform Pipelines. A pipeline processes each record through a series of steps — for example: trim the input, apply a regex extract, then map the extracted value to a platform status.
Pipelines can be saved and reused across connections and entity types. Go to Transforms in Bridge to create and manage saved pipelines.
AI Mapper
If you are not sure how to map an unfamiliar external payload, use the AI Mapper. Paste a sample payload (or upload a CSV row), and THEO will suggest field mappings. Review the suggestions and click Confirm to save them as active mappings.
FAQ
Can I use the same mapping template on multiple connections? Templates are a starting point — they populate mappings that you can then save per connection. If you want to share a pipeline across connections, save it as a Transform Pipeline and apply it to each connection's mappings individually.
What happens to a record if a required mapped field is missing?
The record is moved to Error Recovery with an error message noting the missing required field. It is not written to the platform. Fix the data in the external system or adjust the mapping (for example, add a default transform to supply a fallback value), then retry the record.
The field names from my PSA don't match the template — how do I find the right names? Run a sync with minimal mappings and check the Changes tab on the resulting sync job. The raw data from the external system is stored there, showing the actual field names returned by the API.