Add content-based routing in your VAN connection

Content-based routing (CBR) decides which flow in integrator.io receives each electronic data interchange (EDI) document that arrives from the value-added network (VAN). All inbound documents from your trading partners reach integrator.io through a single VAN connection, so a routing rule must match every document type your partners send — including acknowledgments such as 997, 824, and CONTRL.

This article is for B2B Manager builders who receive EDI documents through ECGrid. It explains how inbound VAN documents are routed, how to write routing rules in your VAN connection that covers every document type, how to route documents to exports in the same flow or in different flows, and how to fix inbound documents that stop arriving because a routing rule is missing.

Prerequisites

• A B2B Manager subscription.
• A VAN connection in the environment that receives the documents. For setup steps, see Request access and set up a connection to the Value-added network (VAN) connector.
• A configured ECGrid mailbox, EDI ID, and trading partnership. For setup steps, see Understand and configure the ECGrid account.
• At least one flow that uses the VAN connection to listen for inbound documents.

How inbound VAN documents reach a flow

integrator.io routes each inbound VAN document through the same stages. The VAN connection is the only entry point for documents from ECGrid, so every inbound flow in the environment shares it.

1. ECGrid delivers the document. Your trading partner sends the document to the VAN. ECGrid delivers it from your mailbox to integrator.io over AS2.
2. integrator.io identifies the connection. The sender and receiver IDs on the message identify your VAN connection and environment. You can create only one VAN connection per environment, and each environment has its own ECGrid mailbox.
3. The routing rules read the content. integrator.io passes the message to the routing script on the VAN connection. The script inspects the content — for example, the transaction set ID in the ST segment — and returns the flow ID and export ID that should process the document.
4. The matching flow runs. integrator.io sends the document to the listener in the flow that the script returns.

If the routing script doesn't return a valid flow ID and export ID for a document, integrator.io rejects that document. ECGrid treats the rejection as a failed delivery and retries at intervals.  

Why every document type needs a routing rule

Every document type that ECGrid can deliver to your mailbox needs a matching condition in your routing script, even if you don't process that document type. Routing rules don't skip unmatched documents — an unmatched document is rejected and redelivered.

Example: You build a flow for a trading partner's 850 purchase orders and write a routing rule for ST*850* only. A trading partner also sends 824 and 997 documents in response to your invoices. Those documents have no matching rule, so integrator.io rejects them and ECGrid keeps retrying delivery. Your 850 orders stop arriving until you add rules for the 824 and 997 documents.

Every routing rule must return a flow ID and export ID, so each document type needs a flow to receive it. For acknowledgments or other documents your business doesn't act on, create a flow that only receives the documents. The flow accepts the document so integrator.io doesn't reject it, and ECGrid stops retrying. You can route several unused document types, such as 997, 824, and CONTRL, to the same flow. 

How to find the document types you receive

Before you write routing rules, list every document type that your trading partners send to your ECGrid mailbox.

1. Sign in to ECGrid.
2. Go to your ECGrid mailbox, select Transactions. 
   Note each inbound transaction set ID, such as 850, 860, 824, or 997, and each EDIFACT message type, such as ORDERS or CONTRL.
3. Review each trading partner's EDI implementation guide for document types they send that don't appear in your transaction history — for example, acknowledgments for outbound documents you plan to send.

How to write routing rules for your document types

You can write routing rules within the VAN connection using the content-based flow router function stub that Celigo provides. The script receives each inbound message and returns the flow ID and export ID of the flow that should process it.

Celigo's content-based flow router function stub 

Every document that ECGrid delivers arrives with two AS2 headers, as2-from and as2-to. integrator.io reads these headers before it runs your routing script and uses them to identify your VAN connection. It then passes them to your stub in options.httpHeaders.

• as2-from — The AS2 ID of ECGrid, which sends the document to integrator.io.
• as2-to — The AS2 ID of your ECGrid mailbox. You can find it in ECGrid under Mailboxes > My Connections > AS2.

ECGrid sends every inbound document, so these header values are the same for all your trading partners and all document types. Your routing script doesn't need to check them. Route on the document content in options.rawMessageBody instead. To route documents by trading partner, read the sender ID in the ISA segment of the document.

Function fields

The routing function receives one options argument and must return an object with two properties:

• options.httpHeaders — A JSON object that contains the HTTP headers of the inbound request.
• options.mimeHeaders — A JSON object that contains the MIME headers of the part that holds the EDI document.
• options.rawMessageBody — A string that contains the unencrypted EDI or XML content.
• _flowId (returned) — The ID of the flow that processes the document. Required.
• _exportId (returned) — The ID of the VAN listener in that flow. Required.

To signal a failure, throw an exception in the script. 

Use the function stub to create your script

1. From the left navigation, go to Resources > Connections.
2. Open your VAN connection.
3. Under Configure routing for shared connections, in the Routing rules editor, select Launch.
4. In the Routing rules editor, click the + sign to create a new script.
   
5. In Create script, 
   1. Enter a name for your script.
   2. In Insert function stub, select Content-based flow router.
   3. Click the expand icon () to open the script editor, then edit and save the content.. 
   4. Click Save and close. 

Example routing script

This script routes 850 purchase orders and 860 change orders to their own flows, and routes 997, 824, and CONTRL acknowledgments to one receive-only flow. It reads the element separator from the ISA segment, so it works when a partner uses a separator other than *.

function contentBasedFlowRouter(options) {
  const body = options.rawMessageBody;

  // EDIFACT messages: the message type follows the UNH reference number, so CONTRL acknowledgments contain '+CONTRL:'.
  if (body.includes('+CONTRL:')) {
    return { _flowId: '<acknowledgments_flowId>', _exportId: '<acknowledgments_exportId>' };
  }

  // X12 messages: the element separator is the 4th character of the ISA segment.
  const isaStart = body.indexOf('ISA');
  const sep = isaStart >= 0 ? body.charAt(isaStart + 3) : '*';
  const stStart = body.indexOf('ST' + sep);
  const transactionSet = stStart >= 0 ? body.substr(stStart + 3, 3) : '';

  if (transactionSet === '850') {
    return { _flowId: '<purchase_orders_flowId>', _exportId: '<purchase_orders_exportId>' };
  } else if (transactionSet === '860') {
    return { _flowId: '<change_orders_flowId>', _exportId: '<change_orders_exportId>' };
  } else if (transactionSet === '997' || transactionSet === '824') {
    return { _flowId: '<acknowledgments_flowId>', _exportId: '<acknowledgments_exportId>' };
  }

  throw new Error('No routing rule for document type: ' + (transactionSet || 'unknown'));
}

Replace each placeholder with the flow ID and export ID from your account. The final throw makes an unmatched document fail with a clear message instead of an invalid ID. After creating your script, check if the routing rules work as required.

How to check if the routing rules work

To check the output, you can paste a sample options object or enter the headers yourself into Function input. (For live documents, integrator.io fills them in from the inbound message.) Then, select Preview, and check Function output. The input has the same structure in both scenarios. Only the routing rule is different, and so the output, changes.

This sample options object contains a trading partner 850 purchase order:

{
  "httpHeaders": {
    "as2-from": "<ECGrid_AS2_ID>",
    "as2-to": "<your_mailbox_AS2_ID>",
    "content-type": "application/pkcs7-mime"
  },
  "mimeHeaders": {
    "content-type": "application/edi-x12",
    "content-disposition": "attachment; filename=PO12345-850.edi"
  },
  "rawMessageBody": "ISA*00*          *00*          *ZZ*TPTEST         *ZZ*YOURCOMPANY    *260923*1200*U*00401*000000101*0*P*>~GS*PO*TPTEST*YOURCOMPANY*20260923*1200*101*X*004010~ST*850*0001~BEG*00*SA*PO12345**20260923~PO1*1*10*EA*4.99**VP*SKU-100~CTT*1~SE*5*0001~GE*1*101~IEA*1*000000101~"
}

To test the 860 condition, replace the rawMessageBody value with an 860 document:

"rawMessageBody": "ISA*00*          *00*          *ZZ*TPTEST         *ZZ*YOURCOMPANY    *260923*1200*U*00401*000000102*0*P*>~GS*PC*TPTEST*YOURCOMPANY*20260923*1300*102*X*004010~ST*860*0001~BCH*01*SA*PO12345**20260923~POC*1*CA*10*5*EA*4.99**VP*SKU-100~CTT*1~SE*5*0001~GE*1*102~IEA*1*000000102~"

When you preview each sample, Function output shows these results. In scenario 1, the flow ID stays the same and only the export ID changes. In scenario 2, both IDs change.

What are example scenarios for routing VAN documents

Example scenario 1: Routing different document types to the same trading partner flow

Example: A trading partner sends 850 purchase orders and 860 purchase order changes. Both create or update sales orders in NetSuite, so you build one flow, TP orders to NetSuite, with two VAN listeners: one for 850 documents and one for 860 documents. Your routing rules return the same flow ID for both document types, and a different export ID for each listener.

Route document types to different listeners in the same flow when they share the same downstream processing — for example, when they update the same records in the same destination application. Use this scenario when you want to manage, schedule, and monitor related document types together in one flow. 

Example scenario 2: Routing different document types to different trading partner flows

Example: A trading partner sends 850 purchase orders and 860 purchase order changes. You sync purchase orders to NetSuite sales orders, and you sync purchase order changes to Shopify orders. You build two flows, each with its own VAN listener. Your routing rules return a different flow ID and a different export ID for each document type.

Route document types to listeners in different flows when each document type needs its own processing or goes to a different destination application. Use this scenario when document types have different mappings, destinations, or schedules, or when you want an error in one flow to stay separate from the others.

FAQ: What to do when inbound documents stop arriving from ECGrid

When a document type has no routing rule, ECGrid can't deliver it, and documents you expect — such as purchase orders — stop reaching integrator.io.

Symptoms

• Inbound documents, such as 850 purchase orders, stop appearing in your flows, and no new data arrives in integrator.io.
• Documents in your ECGrid mailbox stay in a pending or retry status, and no MDN (message disposition notification) is returned.
• Resending or reprocessing a document from ECGrid doesn't deliver it.
• An invalid flowid error appears for 824, 997, or other document types. 

Cause

The routing script on the VAN connection has no condition for one or more document types that ECGrid delivers. integrator.io rejects those documents, and ECGrid retries them at intervals. Clearing individual stuck documents in ECGrid doesn't fix the problem, because the next document of the same type is rejected again.

Resolution

1. List every inbound document type in your ECGrid mailbox. For steps, see the Identify the document types you receive section in this article.
2. For each document type your business doesn't process, create a receive-only flow, or route it to an existing one.
3. Open the Routing rules editor on your VAN connection, and add a condition for every document type.
4. Preview the script with a sample of each document type, and then save the connection.
5. Contact Celigo support to have the documents stuck in your ECGrid mailbox released or resent. 
   Include the ECGrid ticket number, if you have one, and the first ISA segment of an affected document.
6. Confirm that the stuck documents arrive in the correct flows.

Prevention

• Before you send a new outbound document type, add routing rules for the acknowledgments your partner returns, such as 997 or 824.
• Before you onboard a new trading partner, review their implementation guide for every document type they send.
• Preview your routing script with a sample of each document type whenever you add a flow that uses the VAN connection.

Learn more

• Understand content-based routing for AS2 connections
• Integrate with AS2
• Request access and set up a connection to the Value-added network (VAN) connector
• Understand and configure the ECGrid account