Translating codes between systems with Boomi Cross Reference Tables

Every system has its own codes for the same things. The e-shop calls a payment method card, the ERP calls it 07, and the tax authority’s format expects yet another value. The ERP’s main warehouse is 01, the warehouse management system calls it ATH-MAIN. Translating these codes is a small part of every integration, and one of the most common reasons integrations need a developer for what should be a two-minute change.

This article explains the pattern for code translation in general, then implements it with Boomi Cross Reference Tables.

Why hardcoding codes fails

The quick way is to put the translation inside the mapping: an if statement, a small lookup in the map, a script. It works on day one. Then:

• The business adds a value. A new payment method (say, a buy-now-pay-later provider) appears in the e-shop. Orders with it fail or, worse, arrive in the ERP with an empty payment method.
• The same translation is needed in two places. The order flow and the refund flow both translate payment methods, each with its own copy. One gets updated, the other doesn’t.
• Test and production differ. The test ERP has warehouse 99 for testing; production doesn’t. A hardcoded table can’t be right for both.
• Nobody outside IT can see the rules. The accountant who knows the VAT categories can’t review a script.

The pattern: a shared, maintained code table

The pattern is simple: keep code translations in one table per concept, outside the mapping logic, with one column per system. Every flow that needs the translation looks it up in that table.

Concept	E-shop	ERP	Tax format (myDATA)
Payment method	card	07	7
Payment method	cod	03	3
Payment method	bank	06	6

A few rules make the pattern work:

• One owner per table. Someone in the business (finance for VAT, logistics for warehouses) is responsible for its content.
• Explicit handling of missing values. A lookup that finds nothing should stop the document with a clear error, not pass an empty value on.
• Values per environment. Test and production can have different rows, without changing the integration.

The myDATA values above are an example only. Always take the actual codes from the current specification of the system you send to.

Building it in Boomi

In Boomi, the table is a Cross Reference Table component, and maps read it with the Cross Reference Lookup map function.

Step 1: Create the Cross Reference Table

1. Create a new Cross Reference Table component, for example XREF Payment Methods.
2. Define the columns, one per system: Eshop, ERP, myDATA. Name them after the systems, not after the direction of one flow, because other flows will read the same table in other directions.
3. Add the rows, one per payment method.
4. Do the same for the other concepts: XREF VAT Categories (ERP VAT code to the tax format’s VAT category) and XREF Warehouses (ERP warehouse to WMS warehouse code).

Keep one concept per table. A single “all codes” table with a type column looks tidy, but it is harder to maintain and easier to break.

Step 2: Use it in a map

1. Open the map, for example the e-shop to ERP order map from Mapping a JSON order to XML with Boomi maps and profiles.
2. Add a Cross Reference Lookup function (in the lookup category of map functions).
3. Select the table, choose Eshop as the input column and ERP as the output column.
4. Link the source field payment to the function’s input, and its output to the destination PaymentMethod.

The order flow uses Eshop → ERP. The invoice flow to the tax authority can use ERP → myDATA from the same table. One table, several directions, no duplicated logic.

Step 3: Fail clearly when a code is missing

When the lookup finds no row, the destination field is left empty. Don’t let that reach the ERP silently:

• After the Map shape, add a Decision shape (or a Business Rules shape if you have several checks) that tests whether PaymentMethod is empty.
• On the “empty” branch, stop the document with an Exception shape and a message that names the missing value, for example Unknown payment method 'klarna' in order WEB-58211.

That message tells the table’s owner exactly which row to add. Combine it with your normal error handling and alerts; see Error handling and retries in Boomi.

Step 4: Different values per environment

The rows you enter in the component are deployed together with the process. That is fine for values that are the same everywhere. For values that differ between test and production, such as warehouse codes, use environment extensions: Cross Reference Tables can be marked as extensible, and their rows can then be overridden per environment from the environment’s extensions dialog, without changing or redeploying the process.

The exact labels for extensions vary between releases and depend on your account’s permissions, so check the current documentation for where to enable it. Two practical points apply in any case:

• Decide which tables are extensible from the start. Making a table extensible later means a redeploy.
• Restrict who can edit extensions in production. A wrong VAT mapping is a real financial error.

Step 5: Test the edge cases

In Test mode, run the process with samples that cover:

• every known code (one order per payment method),
• an unknown code, to confirm the Exception path,
• the exact casing and spacing the source system sends (Card vs card, trailing spaces), because a lookup may treat them as different values.

When not to use a Cross Reference Table

• Large or frequently changing lists, such as product codes or customers, belong in a database, the ERP itself or a master data hub, not in a static table. See master data management for that problem.
• Translations with logic, such as “VAT category depends on country and product type”, may need a Decision or a small rule set rather than a flat lookup. Keep the codes in the table and the logic in the process.

Before you go live

• Document every table: owner, meaning of each column, where it is used.
• Export the content regularly. Treat the tables like configuration you can review and restore.
• Add new values before they are used. Agree with the business that a new payment method or warehouse is added to the table before it goes live in the source system.
• Test the production values. If you override values in production, check them against the real target system once, with a controlled order.

Summary

Code translation is a small job that becomes a large problem when it is scattered through mappings. Keep codes in one table per concept, with a column per system, an owner, and a clear failure when a value is missing. In Boomi, Cross Reference Tables and the Cross Reference Lookup function give you exactly that, with per-environment values through extensions. For the bigger picture, see our data mapping and formats guide.