Skip to main content

Code Mappings

Complete guide to configuring client-to-EDI destination mappings for automated email processing.

Code mappings bridge client names in spreadsheet attachments and the EDI destinations that receive data. When mail rules parse Excel or CSV files, they look up client names (e.g. "FLOH", "CMAD", "CRWH") here to determine routing, picture search window, and optional email notifications.

Table of contents​

  1. Introduction
  2. What are code mappings?
  3. Creating and managing mappings
  4. Multiple destinations per client
  5. Email notifications
  6. Fallback mapping
  7. Autogenerate from YAML
  8. How it works
  9. Best practices
  10. Troubleshooting

Introduction​

Centralise client-to-destination relationships so you can update routing without editing individual mail rules. Configure email notifications and fallback destinations for unmatched clients.

What you can do in the Admin UI​

  • Map client names to one or more EDI destinations
  • Set days back for picture search (default: 30)
  • Add email notification destinations
  • Configure fallback for unknown clients
  • Autogenerate many mappings from YAML
  • Copy, edit, activate/deactivate, delete mappings

What are code mappings?​

A code mapping means: "When processing a spreadsheet row with client name X, send data to EDI destination Y, looking back Z days for pictures."

Example: Client FLOH → EDI FLOH → 30 days back

When processing row client "FLOH" and container "CAIU1234567", the system will:

  1. Search for pictures with container "CAIU1234567" from the last 30 days
  2. Send data to the "FLOH" EDI destination
  3. Send email notification if configured

Key components​

FieldDescription
Client nameIdentifier in spreadsheet rows — case-sensitive
EDI destinationMust exist in your EDI destinations list
Days backPicture search window (default: 30)
ActiveInactive mappings are ignored
Force triggerFor email: send even when pictures are found

Creating and managing mappings​

Create a new mapping​

  1. Click Create mapping
  2. Enter Client name (must match spreadsheet exactly)
  3. Select EDI destination
  4. Set Days back
  5. Ensure Active is checked
  6. Click Save
Important

Client names are case-sensitive. "FLOH" and "floh" are different clients.

Edit, copy, delete​

  • Edit — Pencil icon; for clients with multiple destinations, all destinations save together
  • Copy — Duplicate an existing mapping with a new client name
  • Delete — Stops routing immediately; consider deactivating instead

Activate and deactivate​

  • Active — Used when processing spreadsheets
  • Inactive — Ignored (useful for testing)
  • Use Show only active filter to hide inactive rows

Multiple destinations per client​

One client can route to multiple EDI destinations (processed sequentially).

Example: Client CRWH → destinations CRWH and EOS, both 30 days back — both receive data for each matching row.

To add destinations when editing a client, click Add destination, select EDI destination, set days back, and Save.

If one destination fails, others still process.

Email notifications​

Add New email as a destination type alongside EDI.

Configuration​

  • To — Recipient addresses (comma-separated)
  • CC — Optional
  • Subject template — e.g. {container} NLRTM10
  • Body template — Optional
  • Force trigger — See below

Placeholders​

PlaceholderValue
{container}Container code from spreadsheet
{client_name}Client name
{terminal}Terminal code (if available)
{case_date}Case date (if available)

Example: Subject {container} NLRTM10 becomes CAIU1234567 NLRTM10

Force trigger behaviour​

SettingBehaviour
OffEmail sent only if no pictures found
OnEmail sent always, regardless of pictures
Use case

Use Off to notify when pictures are missing. Use On for notification on every processed container.

Fallback mapping​

Used when a spreadsheet row's client name matches no active mapping.

Example: Mappings exist for FLOH, CMAD, CRWH; row has client UNKNOWN → fallback sends to DEFAULT EDI with configured days back.

Create fallback​

  1. Click Create fallback (when none exists)
  2. Select EDI destination and days back
  3. Click Save fallback

The fallback appears as a special row at the bottom of the table.

Best practice

Always configure a fallback to catch typos and new clients.

Autogenerate from YAML​

Bulk-create or update mappings by pasting YAML.

YAML format​

edi_connections:
  - client_name: FLOH
    client_edi_name: FLOH
    client_days_back: 30
    email_notification:
      to: "notifications@example.com"
      subject_template: "{container} NLRTM10"
      send_when_no_pictures: true
  - client_name: CMAD
    client_edi_name: CMAD
    client_days_back: 30
  - client_name: CRWH
    client_edi_name:
      - CRWH
      - EOS
    client_days_back: 30

YAML fields​

FieldDescription
client_nameRequired
client_edi_nameString or list of EDI destination names
client_days_backDefault 30
email_notificationOptional: to, cc, subject_template, body_template, send_when_no_pictures

Steps​

  1. Click Autogenerate
  2. Paste YAML
  3. Click Preview — shows create vs update per client
  4. (Optional) Select mailbox and Generate rule for spreadsheet mail rule
  5. Click Generate mappings
Preview

Existing client names are updated; new names are created.

How it works​

  1. Email arrives with spreadsheet attachment
  2. Mail rule matches the email
  3. Spreadsheet is parsed; rows extracted
  4. For each row:
    • Extract client name (via rule column map)
    • Look up code mapping → use EDI destination(s) and days back
    • If not found → use fallback (if configured)
    • Search pictures by container and days back
    • Send to EDI and email destinations
  5. Results logged in Processing state

Code mappings integrate with mail rules that use the parse_spreadsheet action (use_code_mappings enabled by default).

Best practices​

  • Match client names exactly (case-sensitive) to spreadsheet values
  • Always configure a fallback
  • Test new mappings with sample spreadsheets
  • Use autogenerate for bulk setup
  • Review inactive mappings periodically
  • Monitor Processing state
  • Set minimum days back needed for performance
  • Use email notifications sparingly

Troubleshooting​

Spreadsheet rows not processed​

  • Verify mail rule is active and matches email
  • Confirm parse_spreadsheet action and use_code_mappings
  • Check Processing state for errors

Client name not found / unexpected fallback​

  • Exact case match on client name
  • Check for extra spaces or special characters
  • Ensure mapping is Active
  • Verify column map in mail rule

Wrong EDI destination​

  • Verify mapping destination selection
  • Check for duplicate mappings for same client
  • Ensure EDI destination is active

Email notifications not sent​

  • Verify New email destination on client
  • Check To addresses and Force trigger setting
  • Verify SMTP configuration
  • Review Processing state for send errors

Autogenerate preview errors​

  • Valid YAML syntax and indentation (spaces, not tabs)
  • Required fields present
  • EDI destination names exist

Changes not taking effect​

  • Click Save after edits
  • Mapping must be Active
  • Changes apply to new emails only

See also: Mail rules, Processing state, EDI