EDI & Trading Partners

Exchange orders, despatch notes and invoices electronically over SFTP, FTPS, HTTPS, VAN, AS2 or OFTP2.

Trading Partners and Transports

EDI exchanges orders, despatch advices, invoices and acknowledgements with trading partners as X12 or EDIFACT messages instead of PDFs somebody rekeys. Everything is now done on one EDI console: partners, their inbound addresses, messages in and out, maps, transports and certificates. A partner can be a supplier you buy from or a customer you sell to.

Where to find it

Admin Panel → ERP - Setup:

EDI — the EDI console, for holders of ERP: Administration

Architect Panel → ERP - Trading & Analytics:

EDI — the same console; the badge counts messages in error or rejected
EDI Trading Partners, EDI Transports, EDI Messages, EDI Maps, EDI Control Numbers and AS2 Certificates — the underlying datastores, for looking up; make changes on the console

The console

The tabs are Partners, Messages, Simulate inbound, Generate & send, Maps, Transports, AS2 certificates and Acknowledgements. Each partner belongs to a company; you see partners of companies you can read and change those you can write to.

Setting up a partner

Agree the standard, version, message types and identifiers with the partner in writing first.
Set up the transport they will use (see AS2, OFTP2 and the Other Transports in this section).
On Partners, add the partner: Partner code, Name, Company, and Trades as a supplier or a customer, then the Supplier record or Customer record it is. Inbound documents are filed against that record, and outbound documents to it go to this partner. A customer partner is also written onto the customer's EDI Partner field.
Standard and Version (X12 004010 or 005010; EDIFACT D96A), and the EDIFACT release where needed.
The four identifiers: Their qualifier, Their interchange ID, Our qualifier, Our interchange ID. Copy them; do not retype them.
Acknowledgements (997, 999 or CONTRL) and Ack expected within (minutes), which turns a missing acknowledgement into something visible.
Transport, Test relationship while commissioning, and Enabled.
Apply on receipt: an inbound business message is applied to a document as soon as it arrives (an 850 becomes a sales order without anyone pressing Apply), when the partner's maps name exactly one document type for it.
For a supplier, Send purchase orders automatically: issuing a purchase order to this supplier sends the 850 or ORDERS at once. It is off by default; nothing is transmitted to a supplier until you opt them in.

The inbound address

A partner that posts messages to you gets its own URL. On the partner's row press Issue URL, copy it, and send it to the partner over a channel you trust; then press Accept messages. The URL is a credential: anyone holding it can deliver messages as that partner, so use Rotate URL if it may have leaked, Stop accepting to pause, and Revoke to destroy it. The interchange's sender ID must also match the partner. An AS2 partner gets the AS2 address instead, where the signature is checked too; an OFTP2 partner has no URL. Partners that drop files are collected by polling: Poll now, or the scheduled task (see Sending and Receiving Messages in this section).

What goes wrong

Messages from a partner are refused: inbound is not accepted, the URL was rotated, or the sender ID in the interchange does not match.
An AS2 partner's token is refused on the plain address: by design. Give them the AS2 address.
Orders are not sent to a supplier: Send purchase orders automatically is off, or the partner has no outbound 850 or ORDERS map.
Outbound sales documents go to the wrong partner: check the customer's EDI Partner field and the partner's Customer record agree.

Worked example

A distributor onboards a water agency that orders by X12. The ERP administrator adds the partner as trading as a customer, linked to the agency's customer record, X12 004010, with the agreed identifiers, 997 acknowledgements and Apply on receipt. They install the customer starter maps, issue the inbound URL and send it to the agency, then press Accept messages. The agency's first 850 arrives, becomes a draft sales order, and a 997 is queued back.

Recommendations

Commission with Test relationship on, and turn it off only when both sides agree you are live.
Treat the inbound URL as a password; rotate it if in doubt.
Opt suppliers in to automatic orders one at a time, after a test order.
Set acknowledgement times and watch the Acknowledgements tab.

Message Maps and Control Numbers

Two partners sending the same message type will not send the same message. A map ties segments of a partner's messages to fields on your documents, per partner, message type and direction. Starter sets now give you working maps for the common flows in one click, and a preview shows what a map would send before anything goes out.

Where to find it

Admin Panel → ERP - Setup:

EDI — the Maps tab, and Generate & send for previews

Architect Panel → ERP - Trading & Analytics:

EDI Maps — the map rows as a datastore
EDI Control Numbers — the sequence counters per partner

Starter sets

On the Maps tab, choose the partner and press Install a starter set. What you get depends on how the partner trades:

A supplier: X12 850 (or EDIFACT ORDERS) out from a purchase order, and 810 (or INVOIC) in to a supplier invoice.
A customer: 850 (or ORDERS) in to a sales order, and 855 (ORDRSP) order acknowledgement, 856 (DESADV) ship notice and 810 (INVOIC) invoice out.

Then adjust the rows to the partner's specification. Reinstalling a set that has gained rows since you installed it adds the new rows and re-sequences the set; a complete set is left alone.

What a map row holds

Partner, Message type, Direction and Document type.
Order: the segment order on the wire follows it.
Segment path: where in the message, such as BEG[3] for the third element of BEG, N1[2]@N1[1]=ST for the name in the ship-to N1 segment, or TAG[n.c] for a component.
Document slot: the field on your document, such as number, doc_date or a line's qty.
Level: header or line. A wrong level is the usual cause of a header value repeated on every line.
Transform: date, upper, lower, abs, negate, n2 (implied two decimals, 94.00 as 9400), and the unit-of-measure translations uom_x12 (X12 code list 355: DAY to DA, BOX to BX) and uom_unece (UN/ECE Recommendation 20: HR to HUR, KG to KGM).
Constant: a fixed value, or a token such as {today}, {time}, {line_count}, {line_seq+1}, {our_id} or {their_id}.
Required: the message is refused on your side, with a clear reason, if this value is missing.

An optional segment whose every value is empty is left out rather than sent half-filled: an order with no delivery date sends no date segment. Segments made only of fixed constants are always sent.

What the starter sets read

Inbound supplier invoices: the invoice number goes into the bill's supplier invoice number (which the duplicate check reads), and the order it bills is used to raise the bill from that purchase order at the invoiced prices, so matching sees what was ordered and received. Lines the order does not have, such as freight, are added as charges. An invoice for an order you do not have, or in a different currency from the order, is raised on its own and the message says why.
Inbound customer orders: the customer's price is recorded as their expectation. An item your price lists price keeps your price, and the message and the order's history say where theirs differs; an item no list prices takes theirs.
Outbound purchase orders carry your item codes as the buyer's part number.

Previewing a map

On Generate & send, choose the partner, message and document and tick Preview only. You see exactly what the maps would send for that document now. No control number is used and nothing is stored or sent. This is how to check a map change against a real document; an interchange already sent is never changed by a map edit, and Resend repeats the same interchange.

Control numbers

Each partner has counters for interchange and message control numbers, which the partner uses to detect gaps and duplicates. Never reset them: a partner treats numbers it has already seen as duplicates and discards the documents silently. Reusing a control number is refused rather than answered with an older message.

What goes wrong

Units rejected by the partner: the unit row still uses upper (maps installed before October). Change its transform to uom_x12 or uom_unece.
Values repeated on every line, or line values collapsed into one: check the Level.
A send fails with a required value missing: fill the field on the document, or correct the map.

Worked example

A customer partner whose maps were installed in August receives our 855 order acknowledgements with training days in the unit DAY, which their system rejects. The administrator opens Maps, changes the unit row's transform to uom_x12, then uses Generate & send with Preview only on yesterday's sales order: the preview now shows DA. The next 855 goes out correctly.

Recommendations

Start from a starter set and adjust to the partner's specification.
Preview before every map change goes live.
Mark fields the partner requires as Required.
Never reset a control number without agreeing it with the partner.

AS2, OFTP2 and the Other Transports

A transport is how messages travel between you and a partner. Which one you use is usually the partner's choice. Transports are now set up on the EDI console's Transports tab, one form per kind, with every secret stored encrypted and masked on screen. Several partners can share one transport.

Where to find it

Admin Panel → ERP - Setup:

EDI — the Transports and AS2 certificates tabs

Architect Panel → ERP - Trading & Analytics:

EDI — the same console
EDI Transports and AS2 Certificates — the datastores behind them; edit on the console

The kinds

Shared folder (file drop): interchanges written to an Outbound folder and collected from an Inbound folder, with an optional Archive folder and Inbound file pattern (such as *.x12). Use it for a mounted VAN mailbox, a folder synced by another tool, or testing. One ships, switched off until a folder is set.
HTTPS POST: messages posted to the Partner endpoint URL (a public https address), with an optional Authorization header.
AS2: signed, encrypted, with a signed receipt (MDN). Settings: Partner AS2 URL, MIC algorithm (sha256 unless the partner says otherwise), Sign outbound messages, Encrypt outbound messages, MDN address, Asynchronous MDN URL (blank for a synchronous MDN), and an HTTP user and password if the partner needs one.
SFTP: Host, Port, Username, Password or Private key path, and remote outbound and inbound folders. The account must allow SCP and listing a folder; an account restricted to SFTP only is refused with that reason. It also needs the server's SSH extension, which the hosting administrator installs.
OFTP2: the automotive standard: host, port, your SSID identity and password, the virtual file name and certificate files. It is built but has not yet been run against a real OFTP2 partner, so test it thoroughly.
VAN mailbox: listed, but there is no direct VAN connection. Connect to your VAN through its SFTP or AS2 service, or a mounted folder, instead.

Who can set them up

Shared folder, SFTP and OFTP2 transports name folders and key files on the server, so only an architect can create or edit them, and every folder must sit inside the ERP drop-folder area that the hosting administrator configures for the installation. A folder outside it is refused. HTTPS and AS2 transports can be set up by ERP administrators.

Setting up an AS2 partner

On Transports, add an AS2 transport with the partner's AS2 URL and agreed settings, and switch it on.
On AS2 certificates, add a row for the partner: a Label, MIC algorithm, Our certificate (PEM), Their certificate (PEM), Our private key (PEM) and its Key passphrase. The key and passphrase are write-only: they are stored encrypted and never shown again.
A partner's own certificate row overrides the transport's MIC algorithm and its sign and encrypt switches, and can Require a signed MDN: with that on, an unsigned or unverifiable receipt fails the send.
Give the partner your AS2 address from the Partners tab (Issue URL).

Certificates expire

An expired certificate stops the exchange on a date known well in advance, and a swap needs both sides ready. Diary renewals at least 60 days ahead and agree the changeover date with the partner.

Switching a transport off

Switching off a transport that partners use asks first and names the partners it cuts off. Nothing is sent for, or acknowledged on behalf of, a partner that is disabled or deleted.

What goes wrong

A folder is refused: it is outside the drop-folder area. Ask the hosting administrator where that is.
SFTP fails: the server lacks the SSH extension, or the partner's account does not allow SCP and folder listing; the error says which.
The partner says messages are unsigned: check the partner's certificate row, which overrides the transport's switches.
Files are not picked up: the transport is off, the pattern does not match, or nobody has polled. Use Poll now on the Partners tab.

Worked example

A manufacturer trades with three retailers over AS2 and a dozen small customers through a VAN. The architect sets up a shared folder transport pointing at the folder the VAN's own software synchronises, and all twelve partners use it. The ERP administrator sets up one AS2 transport per retailer, loads each retailer's certificate and the company's key, and diaries the certificate expiry dates.

Recommendations

Enable only the transports you use.
Prefer a shared folder fed by your VAN's software for many small partners.
Diary certificate expiry 60 days ahead.
Test OFTP2 end to end with the partner before relying on it.

Sending and Receiving Messages

Once a partner, a transport and maps are in place, messages flow both ways: inbound orders and invoices are read and applied to documents, and outbound acknowledgements, ship notices, invoices and purchase orders are generated from documents, often automatically as those documents move. The EDI console shows every message, what happened to it, and the acknowledgements owed in each direction.

Where to find it

Admin Panel → ERP - Setup:

EDI — the Messages, Simulate inbound, Generate & send and Acknowledgements tabs

Architect Panel → ERP - Trading & Analytics:

EDI — the same console; the badge counts messages in error or rejected
EDI Messages — every message as a datastore, for looking up

The Messages tab

Quick views: Everything, Inbox - to apply, Outbox - to send and Needs attention. Inbound messages go Received, Read, Mapped, Applied; outbound ones Queued to send, Sent, Acknowledged or Rejected by partner; any can be Error or Cancelled. Open a message to see its segments and act on it:

Preview mapping and Apply to document: show what the maps make of it, then create the document with its totals and currency.
Acknowledge or Reject: answer the message's whole group.
Send now, Resend (the same interchange again) and Cancel for outbound messages.
Reprocess: work out the partner again from the sender.
Dismiss: an inbound message that will never be applied is kept, with who dismissed it and why, and leaves Needs attention.
Simulate their acknowledgement: proves that an acknowledgement would close your message, during commissioning.

Receiving

Partners with an inbound URL post messages to it; the message is stored at once. With Apply on receipt on the partner, an inbound order or invoice becomes a document straight away.
Partners that drop files are collected by polling: Poll now on the Partners tab, or the EDI Inbound Poll task. A file from an unknown sender is left where it is; a file that is not an interchange is moved to a quarantine folder.
With acknowledgements on, one 997 or 999 per group (one CONTRL per EDIFACT interchange) is built and queued back. A transaction that is not valid is stored as an error and rejected in the acknowledgement, never acknowledged as received. A redelivered message is recorded once.

Simulate inbound lets you paste or load an 850, 810, ORDERS or INVOIC, or Insert a sample built from the partner's own identifiers, and receive it exactly as the endpoint would, optionally applying it (Then apply it as). Use it to test maps before the partner sends anything.

Sending

Automatically, for partners with outbound maps:

Confirming a sales order sends an 855 (ORDRSP for EDIFACT partners).
Shipping a delivery note sends an 856 (DESADV).
Posting a sales invoice sends an 810 (INVOIC).
Issuing a purchase order sends an 850 (ORDERS), only to suppliers with Send purchase orders automatically ticked.

The message is sent as soon as the document's change is saved, and only once per message type. A failed send never blocks the document's move (the message stays queued in the Outbox), but a map that cannot build the message does, with the reason.

By hand, on Generate & send: choose To partner, Message, From document type and the document (Find document), then tick Send straight away or Preview only. You can only send documents of the partner's own company, with write access to it.

Scheduled tasks

EDI Inbound Poll (every 15 minutes) collects files from folder and SFTP transports; EDI Outbound Send (every 5 minutes) sends what is queued. Both ship switched off; switch them on when you go live (see Tasks). Without the send task, anything left queued (a failed send, or a message generated without Send straight away) waits in the Outbox until someone presses Send now.

What goes wrong

Messages sit in the Outbox: the send failed (open the message for the error), the transport is switched off, or the send task is off.
An acknowledgement never comes: the Acknowledgements tab lists what you are owed past the partner's expected time. Chase the partner; never just resend.
Inbound messages sit in Needs attention: a map is missing or a required value is absent. Preview the mapping, fix the map, and apply again; or dismiss with a reason.

Worked example

A customer's 850 arrives through its inbound URL and, with Apply on receipt, becomes a draft sales order; a 997 is queued and sent by the EDI Outbound Send task. The sales administrator confirms the order and an 855 goes out. The warehouse ships the delivery and an 856 follows; Receivables posts the invoice and an 810 is sent. The customer's 997s arrive and each outbound message shows Acknowledged.

Recommendations

Simulate every inbound message type before go-live.
Switch both tasks on together when you go live.
Check Needs attention daily.
Dismiss with a reason rather than leaving dead messages in the inbox.