EDI and Plex

EDI and Plex

Most DataMagik EDI customers run Plex, and the two systems meet in two places: pulling documents out of a Plex mailbox, and getting documents a partner sent you into Plex as records. This page covers both.

Getting an inbound document into Plex

When a partner sends you an 850 and you want a customer order in Plex, choose one of two routes. Both are configuration; neither needs anything built.

Route A — a script that writes through the Plex API

Use this when you want control over exactly what is created, or when the mapping needs a lookup, a default or a validation on the way in.

1. Create a Plex Connect credential (the plex_oauth type).
2. Write a script that takes the mapped document and calls the Plex API.
3. Attach it: either set the partner's routing row for that document to Hand to a script and name it, or link it to the mapping spec as its document-logic script and set the row to Write to Plex. Either way, this script is what performs the write.

function main(context) {
  const order = context.mapped.purchaseOrders[0];

  const res = plex.api.call({
    credentialName: "PLEX_CONNECT",
    product: "sales",
    operation: "create-customer-order",
    body: {
      customerOrderNo: order.poNumber,
      orderDate: order.poDate,
      lines: order.lines.map(l => ({ partNo: l.product, quantity: l.quantity }))
    }
  });

  return { success: res.ok, script_message: "created order " + order.poNumber };
}

Use the plex_api_search and plex_api_describe tools to find the right product and operation — the per-operation schemas are live rather than static, so they always match your tenant.

Route B — hand the document to a Plex mailbox and let Plex load it

Use this when Plex already has the trading-partner and document setup for this document type — its own mailbox, trading partner and document templates. Plex does the loading; DataMagik does the transport and the audit trail.

1. Set up the Plex mailbox transport on the partner (below).
2. Configure the matching trading partner and document setup in Plex, so it knows what to do with the document when it lands.
3. Route the document to that mailbox. Plex processes it with its own templates, exactly as it would a document that arrived through any other channel.

What DataMagik does and does not do itself

Worth being precise, because it decides which route you need: DataMagik parses, maps, validates, routes, records and acknowledges the document. It does not itself post a business record into Plex — that is the script in Route A, or Plex's own document setup in Route B. Setting a routing row to Write to Plex without either in place records the decision and writes nothing, and the console says so on the transaction: an issue marked plex_write_unwired and a note ending "nothing was written to Plex". If you see that, the route is missing its script.

Retrieving documents from a Plex mailbox

Documents your partners send may land in Plex's mailboxes rather than with DataMagik. The Plex mailbox transport pulls them out and runs them through the normal inbound pipeline.

Setting it up

1. Create a Plex Connect credential — the plex_oauth type. This is not the classic Basic-Auth credential used by plex.execute; conflating them produces a 401 that looks like a permissions problem.
2. On the trading partner, choose Plex mailbox as the delivery method and select the credential.
3. DataMagik loads your actual mailboxes and log statuses from Plex and offers them as pickers. You never type an ID.
4. Pick the mailbox by name. Names are unique in Plex and survive a mailbox being rebuilt; a stored UUID would silently point at nothing while the configuration still looked correct.
5. Use import interchange identity to copy the mailbox's ISA01–ISA04, delimiters and qualifiers onto the partner record.

Retrieval, and the one thing to get right

Retrieval lists mailbox logs, fetches each document and records it. Configure a status filter, an action filter, how many days back to look, and a cap per run. Tick Enable scheduled pickup with a cron expression to run it automatically, or press Retrieve now.

Two smaller behaviours: very old logs in Plex can have no usable id and cannot be fetched — they are skipped and counted, because silently ignoring documents is exactly the failure this feature exists to prevent. A log with no stored document is also skipped and counted rather than failing the run.

Sending a document to Plex

With the Plex mailbox transport selected, an outbound document produced by edi.emit is written into the Plex mailbox as an EDI log plus its content. The interchange control number DataMagik reserved is passed through, so both systems agree on it.

If the log is created but the content upload fails, that is reported precisely — an empty log in Plex is a visible, recoverable state, and the delivery status says so rather than reporting a bare failure.