Skip to main content

Rule Examples — From Simple Mappings to Complex Patterns

How do I copy data between segments using LOOKUPV2 instead of LOOKUP?

A
Written by Ashwath Kirthyvasan
Updated today

Audience: EDI developers, B2B integration teams, technical contacts implementing complex transformations

When the basic transformation rules don't cover your mapping needs, this article covers advanced rule patterns for cross-segment data copying, hard-coding values, address mapping, and conditional transformations.

When You Need Complex Transformations

Complex transformations handle scenarios the basic rules can't address:

  • Cross-segment lookups — Copying data from one segment or loop to another

  • Hard-coded values — Setting fixed values regardless of input data

  • Value mapping — Converting one set of values to another (e.g., unit code standardization)

  • Address segment mapping — Transforming JSON address data into proper N1/N3/N4 segment structure

  • Conditional transformations — Changing field values based on other field conditions

Copying Data Across Segments with LOOKUPV2

LOOKUPV2 is the function for copying data between different segments or loops in a transaction. LOOKUP is the older version — use LOOKUPV2 for all new rules.

LOOKUPV2 works by navigating the transaction's JSON structure using direct path references. Each argument is a full JSON path into the transaction data:

LOOKUPV2(loopPath, matchFieldPath, matchValue, returnFieldPath)

  • loopPath — the path to the loop you want to search through

  • matchFieldPath — the path to the field you're matching against

  • matchValue — the value you're looking for (quoted string)

  • returnFieldPath — the path to the field whose value you want to return

Example: Retrieving a product description by code

This rule searches the PID loop for an item where productDescriptionCode equals "F", and returns the corresponding description value:

LOOKUPV2(   $transactionSets.*.IT1_loop.*.PID_loop,   $transactionSets.*.IT1_loop.*.PID_loop.*.productItemDescription.*.productDescriptionCode,   "F",   $transactionSets.*.IT1_loop.*.PID_loop.*.productItemDescription.*.description )

The * wildcard in the path means "all instances" — so Orderful will traverse every iteration of a loop to find the match.

Troubleshooting LOOKUPV2

If your LOOKUPV2 rule returns no data:

  • Verify the path references — when adding a path, type $ and use the select one of the available paths in the drop down

  • Confirm the match value exists — check a real transaction to ensure a segment with that value is actually present

  • Check capitalization — path references and match values are case-sensitive

  • Test with a specific transaction — use the Rules Editor with real transaction data to inspect the structure before writing the rule

Setting Fixed Values with SET

Use SET to hard-code a specific value regardless of the input:

SET("CS")

This is appropriate when a field always needs a fixed value — for example, a trading partner requires a specific qualifier that never varies.

Mapping Values with REPLACE and LOOKUPDATA

When you need to convert one value to another, use REPLACE for simple one-to-one substitutions or LOOKUPDATA for multi-value mappings against a correspondence table.

REPLACE — single value substitution

REPLACE($transactionSets.*.IT1_loop.*.baselineItemDataInvoice.*.unitOrBasisForMeasurementCode, "CA", "CS")

This replaces "CA" with "CS" and passes all other values through unchanged.

LOOKUPDATA — multi-value mapping

When multiple input values need to map to different outputs, use LOOKUPDATA to reference a lookup table rather than chaining multiple IF/ELSE statements:

LOOKUPDATA("paroductDescription", $transactionSets.*.IT1_loop.*.baselineItemDataInvoice.*.productServiceID)

This keeps rules clean and maintainable when the mapping set is large or likely to change.

Charge code mapping example

For a small set of values, IF/REPLACE combinations work; for larger sets, use LOOKUPDATA:

IF EQUALS($transactionSets.*.IT1_loop.*.SAC_loop.*.servicePromotionAllowanceOrChargeInformation.*.allowanceOrChargeIndicatorCode, "N/A") THEN SET("Air Freight") ELSE LOOKUPDATA("chargeCodeTable", $transactionSets.*.IT1_loop.*.SAC_loop.*.servicePromotionAllowanceOrChargeInformation.*.allowanceOrChargeIndicatorCode)

Add Missing Loops or Segments with "Add {} To Array"

If you are missing a whole segment (REF segment) or loop address (N1 Loop), use "Add {} To Array" next to the array name and use rules in each array values.

If the array values are all hard-coded, use the SET rule. If they should be copied from elsewhere in the transaction, use LOOKUPV2.

Testing and Troubleshooting Complex Rules

Using the Rules Editor effectively

  • Start with real transaction data — don't test with hypothetical payloads; the actual JSON structure may differ from what you expect

  • Inspect field names carefully — use the exact field names shown in the transaction JSON, not X12 element names, use $ to select the correct path whenever possible

  • Build incrementally — test one rule at a time before combining multiple transformations

  • Verify values are case-sensitive — match values in LOOKUPV2, REPLACE, and EQUALS are case-sensitive

Common debugging scenarios

Rule returns no data or doesn't seem to apply:

  • Confirm the source field exists in the transaction JSON

  • Check spelling and capitalization of field names and path references

  • Verify the match value is actually present in the transaction

  • Refresh - Longer rules may take some time to be resolved

Rule applies but gives wrong result:

  • Check conditional logic in IF/EQUALS statements

  • Test with multiple sample transactions to confirm consistent behavior

Rule works in test but not in production:

  • Confirm production transactions have the same JSON structure as your test data

  • Check that the rule is applied to the correct stream (test vs. production)

  • Verify the rule is active on the correct trading relationship

Applying updated rules to existing transactions

The behavior depends on whether you are the sender or receiver of the transaction.

If you are the sender: Once a transaction has been sent to your trading partner, updating a rule won't automatically apply to it. To apply the updated rule, resend the transaction — this will process it through the current rules before delivering it again. You can also copy the transaction to test to validate the rule change without affecting production.

If you are the receiver: You can update rules and see their effect as long as the transaction hasn't been sent to your communication channel yet. If the transaction has already been delivered to your communication channel, you can still update rules and preview their result — but if you resend the transaction, the updated rules won't be applied. To apply the updated rules and resend, use reprocess and resend instead.

What to Send Orderful Support

For complex transformation rule issues, contact [email protected] with:

  • Transaction ID from a specific failed or incorrect transaction

  • Exact rule syntax you're trying to implement (copy from the Rules Editor)

  • Expected vs. actual output — show what field values you're getting vs. what you need

  • Sample input data showing the source JSON structure

  • Trading partner relationship details (ISA IDs, transaction types affected)

  • Screenshots from the Rules Editor showing the rule configuration

Frequently Asked Questions

Why should I use LOOKUPV2 instead of LOOKUP?

LOOKUP is the older version of the function. LOOKUPV2 uses direct JSON path references and is more reliable for complex transactions with multiple loops. Use LOOKUPV2 for all new rules.

When should I use SET vs. REPLACE vs. LOOKUPDATA?

Use SET when a field always needs a fixed value with no condition, or when a specific condition should hard-code a value. Use REPLACE for a simple one-to-one value substitution. Use LOOKUPDATA when multiple input values map to different outputs — it's cleaner than chaining IF/ELSE statements.

Can I apply the same rule to multiple trading partners?

Rules are configured per trading relationship. You'll need to set up the rule separately for each partner, or contact Orderful Support to discuss applying rules at a broader level.

My rule works in the Rules Editor but not on actual transactions. Why?

This usually means the actual transactions have a different JSON structure than your test data. Test with real transaction data from your partner to ensure the field paths and structure match what you've built the rule against.

How do I transform data that spans multiple segments or loops?

Use LOOKUPV2 with direct JSON path references to traverse all instances of a loop and return the value that matches your criteria.

Did this answer your question?