Integrate Healthcare EDI Documents Like X12 837s

Arc’s mapping tools allow for processing any manner of EDI data, including health-care specific documents like X12 837s. One of Arc’s sample pre-packaged Flows maps an inbound 837 document to a flat CSV file for backend processing. This article walks through the concepts helpful in understanding both this specific Flow and EDI mapping Flows in general.

To follow along with the article directly, please download the 837-to-CSV Flow here.

First, this article will provide a brief overview of EDI integration in Arc, then discuss the details specific to the 837 Flow.

EDI Integration Overview

An EDI integration in Arc has three major steps:

  • Translate EDI into XML
  • Translate the Destination Format (e.g. CSV) into XML
  • Map between these two XML Structures

The important aspect to understand about this approach is that Arc uses XML as the common medium for data transformation. Both the starting data and the desired ending data are modeled as XML, so that the actual transformation step occurs between two XML structures.

This section will introduce the concepts involved in each step, and these concepts will be implemented in the next section.

EDI Translation

Since Arc uses XML as the common medium for transforming and integrating data, the first step in any EDI Flow is to translate the EDI data into XML. Arc includes many dedicated connectors to translate specific file formats into XML or translate XML into another format.

During the XML translation step, Arc also validates the EDI interchange headings to ensure the document was sent to and from the expected parties. The settings of each EDI connector (e.g. X12 Connector, EDIFACT connector) are used to validate the document headings.

EDI connectors are able to translate any arbitrary document type, so only a single connector is required to translate 837s, 834s, 270s, etc.

Destination Format Translation

In addition to translating the EDI data into XML, it is also necessary to generate an XML template for the destination data format. For example, if the EDI data should ultimately be transformed into a CSV file, then it is necessary to generate an XML template of a CSV file.

Arc’s file format connectors can automatically generate XML templates using the Upload Test File feature in the connector. For example, uploading a sample CSV file as a Test File in the CSV Connector will result in an XML template.

Arc also allows for manually generating XML templates, so any file that has been translated into XML can be uploaded directly as a destination template.

Arc also models database input and output as XML, so integrating EDI data with a database does not require translating the destination format into an XML template; the destination template is already modeled as XML.

XML Mapping

Once the EDI data and the destination format have both been modeled as XML, the only task remaining is to map one XML structure onto another. Once this mapping relationship is established, data flows according to the following pattern:

  • Inbound data is translated into XML
  • Inbound XML is mapped into the XML format for an outbound document
  • Outbound XML is translated into the outbound format

The XML Map Connector is used to establish the mapping relationship between two XML Structures. This connector also includes many additional powerful tools to manipulate and transform the data as it’s being mapped.

The XML mapping step requires the most understanding of the data and typically involves the most work. The next section of this article will focus primarily on the mapping relationships established in the example Flow, as these are the most important to understand when implementing your own EDI integrations.

Sample 837 Flow

Having covered the general EDI mapping principles, we will now turn to the sample 837 mapping Flow. It is strongly recommended to install this Flow before continuing.

The sample Flow consists of an X12 Connector, an XML Map Connector, and a CSV Connector. These connectors correspond (in order) to the subsections in the above overview of EDI integration in Arc.

X12 Connector

The X12 Connector translates inbound 837 documents into XML. Since XML is Arc’s common format for data mapping, this is a necessary staging step for further processing of the EDI data.

In a production Flow, the X12 Connector is also configured with the EDI identifiers for the party sending these 837 documents. The X12 Connector validates inbound documents according to these settings during the XML translation step. The sample X12 Connector provided in the Flow does not contain these party identifiers, because they are specific to each individual use case.

When the X12 Connector is configured to process T - Test Data in the Usage Indicator field, the connector will bypass validation and simply translate the EDI files into XML. This allows for testing the Flow without need for prior configuration.

Sample X12 File

This sample Flow includes a sample X12 837 document containing test claim data. Different providers may have subtle differences in the way these 837 documents are generated, so this sample file is not expected to exactly match every production use case.

Most importantly, the sample X12 file shows the structure of an EDI document and how this structure can be mapped into a wholly different format like CSV. Differences between this sample 837 and actual 837 documents can be handled with slightly different value mappings without disrupting any of the concepts discussed in this article.

CSV Connector

The CSV Connector converts XML into CSV, so it provides the final step in an EDI-to-CSV Flow. The CSV Connector also helps establish a destination structure for our XML Mapping by using a sample CSV file.

To understand why this is the case, it is important to first realize that the CSV Connector translates data in both directions: CSV-to-XML and XML-to-CSV. When the connector processes a CSV file, it translates it into an XML file with a standard structure. In order to convert an XML file back into CSV, the XML needs to have this same standard structure (though of course the data itself can vary) to produce a CSV file.

To map the EDI data into an XML structure that the CSV Connector accepts, it is necessary to first translate a sample desired CSV file into XML. The resulting XML is the target for our mapping: any XML file matching that structure can be converted into the desired CSV file by the CSV Connector.

Sample CSV File

This sample Flow includes a sample CSV file containing the fields deemed necessary for storing the 837 data. Note that the specific fields relevant for the destination CSV are up to the specifics of a particular use case, so while the example CSV file is intended to provided a comprehensive representation of the 837 data, it is not expected that this exact CSV format will match every customer’s exact requirements.

Most importantly, the sample CSV file shows the process of mapping EDI data into a flat format like CSV. Specific fields within the CSV file can be added, removed, or re-arranged without disrupting the general mapping concepts discussed in this article.

XML Map Connector

The XML Map Connector performs the majority of the work involved in this sample Flow. In general, the process of establishing a mapping relationship with the XML Map Connector is as follows:

  • Set an XML template for the source file (in the example Flow, this is an 837 document translated into XML by the X12 Connector)
  • Set an XML template for the destination file (in the example Flow, this is a sample CSV file translated into XML by the CSV Connector)
  • Drag elements from the source structure onto elements in the destination structure within the visual designer

This section will cover the concepts important for understanding the mapping relationship established in the sample XML Map Connector. These same concepts can be used to generate your own custom mapping relationships, though it will always be necessary to have an understanding of the data you are working with in order to map the appropriate values.

Foreach Loop (Claim)

The first aspect of the mapping is the Foreach loop relationship established between ClaimItem in the destination (this represents a row in the CSV file) and the LXLoop1 within each CLMLoop1. This is displayed next to the ClaimItem element via a green xpath with a Foreach modifier prefix.

A CLMLoop1 represents a claim, and each LXLoop1 within it represents a line item of the claim. So, the Foreach relationship means this:

Each line item of each claim should result in a new row in the destination CSV file.

So, a CSV row contains data for a specific claim line item.

Determining what each CSV row should represent, and therefore which segment should have a Foreach relationship with the CSV row element, is the first step when mapping EDI data to a flat format like CSV.

Foreach loop relationships are established by dragging a parent node in the source onto a parent node in the destination. Parent nodes are nodes with children, but no value. They are easily recognizable in the XML Map Connector’s visual designer because they can be expanded (to view the children) or contracted (to hide them).

Value Mappings

Once the Foreach relationship has been established to generate a new CSV row for each claim line item, the fields of each row need to be filled in with data from the source EDI document. These value-to-value mappings are displayed via the green xpaths in square brackets (without a Foreach modifier prefix). The green xpath shows the path in the source document where the value should come from.

Note: The green xpaths for value mappings are relative to the Foreach xpath that they are inside of; in this mapping example, there is only one Foreach xpath, so all value xpaths are relative to the LXLoop1 element in the source.

For example, the Service Amount for each claim line item is stored within the SV1/SV102 element, which is itself within the LXLoop1 segment that represents a claim line item. Since all value xpaths are already relative to the xpath for LXLoop1, the value for the Service Amount simply comes from [SV1/SV102].

Some value xpaths include ‘dot-dot’ syntax: .. This indicates that the xpath “exits” the current Foreach loop xpath to access an earlier level in the source document. For example, since the LXLoop1 node is directly within a CLMLoop1 node, the .. syntax means to “leave” the LXLoop1 to be in the prior CLMLoop1 segment. This syntax can be chained together to move outward (i.e. from child-to-parent) through the source XML structure.

Value-to-value mappings are established by dragging a leaf node in the source onto a leaf node in the destination. Leaf nodes are nodes with values but no children (they cannot be expanded or contracted, but they contain the actual data).

During a full custom mapping, the process of dragging a source leaf node onto the destination would be repeated many times to map each of the values from the source to the destination. Naturally, this requires an understanding of which values in the source correspond to the desired fields in the destination.

Lookaheads (NM1Loops)

Some value mappings require additional syntax to ensure that the correct value is mapped from the source. This extra syntax is known as a “lookahead” and is specified in the Expression Editor within a destination node.

Each of the lookahead examples for this mapping involve a value coming from an NM1Loop in the source. Each NM1Loop represents a party in the exchange, e.g. the service provider, subscriber, or practitioner, etc. Since each NM1Loop contains the data for a different party, it is important to differentiate between the NM1Loop segments when mapping data. However, some NM1Loop segments can only be distinguished based on the NM1/NM101 value, so a lookahead is required to “look into” the loop and check this NM101 value.

As an example, take a look in the EDI source data at the two NM1Loop2 nodes within the second HLLoop1. For clarity, the xpath to both of these NM1Loop2 nodes is provided below:


One of these NM1Loop2 segments contains data for the payer, and one contains data for the subscriber. In order to determine which is which, it is necessary to check the NM1/NM101 value:

  • ‘IL’ means subscriber
  • ‘PR’ means payer

Only once we have determined this value do we know if this NM1Loop2 contains the data we want to map to a particular destination node.

To see how this lookahead appears in the XML Map Connector, find the SubscriberLastName node in the destination (CSV). The value mapping (xpath) for this node takes the value from NM1Loop2/NM1/NM103, but there is additional syntax within square brackets specifying a lookahead condition:


This lookahead condition is discriminating between NM1Loop2 segments; only map the value from an NM1Loop2 where NM1/NM101 is equal to ‘IL’ (which is the code for ‘subscriber’). This way, we are confident that the Subscriber last name will be mapped, rather than the Payer last name.

Lookaheads are specified in the Expression Editor, which can be opened by clicking the Tablet and Pencil icon next to a destination node. You can open up the expression editor for the SubscriberLastName node to see that the lookahead condition is added in the middle of the usual xpath notation, using escaped square brackets. When adding your own lookahead conditions, use the following two steps:

  • First map the appropriate value using the regular drag-and-drop approach
  • Open the expression editor and add a lookahead condition in escaped square brackets to discriminate between repeated segments

Conditional Scripts (IsChargeable)

The sample mapping includes two nodes, IsReissue and IsChargeable, that are mapped to custom scripting logic. To view the scripts, find these nodes in the Destination panel, and click the </\> button next to them. This section will briefly explain the script in the IsChargeable node, to help demonstrate how custom logic can be implemented during a mapping.

The script for IsChargeable is shown below:

<arc:set attr="isChargeable" value="" />

<arc:if exp="[xpath(../../../BHT/BHT06) | equals('CH')]">
  <arc:set attr="isChargeable" value="YES" />
    <arc:set attr="isChargeable" value="NO" />

<arc:set attr="result.text">[isChargeable]</arc:set>

The first thing to note is that this mapping script is written in ArcScript, a dedicated scripting language included with the application. A primer for getting comfortable with ArcScript is provided in our Knowledge Base here.

This script is reading a value from the input EDI document (specifically the BHT/BHT06 element) and checking whether this value equals ‘CH.’ Since ‘CH’ is the code for a chargeable transaction, the isChargeable variable is set to ‘YES’ if that code is present and ‘NO’ otherwise. The last line of the script returns the value in the isChargeable variable so that it is mapped to the output document.

The logic for the IsReissue output node is very similar, though it is checking a different element in the BHT segment.

These are simple examples of leveraging scripting logic to modify data during a mapping, but the full flexibility of ArcScript is available within the XML Map connector to accomplish varied specific use cases.

Data Assumptions (ClaimDiagnosisCode)

Some mapping relationships may need to make assumptions about the data being processed. In this sample Flow, there are two sets of output elements that contain claim diagnosis information:

  • ClaimDiagnosisCodeQualifier1
  • ClaimDiagnosisCode1
  • ClaimDiagnosisCodeQualifier2
  • ClaimDiagnosisCode2

These elements are mapped with a ‘hardcoded’ reference to a repeated HI segment, for example the ClaimDiagnosisCode1 element is mapped to the following:


The ‘[1]’ syntax next to the HI segment indicates the value should be mapped from the first occurrence of this xpath, unconditionally. Note the contrast with the ‘lookaheads’ section earlier, which specified a condition within the square brackets to determine which segment to use.

The ClaimDiagnosisCode2 element is mapped to the subtly different xpath:


This means the value is unconditionally taken from the second occurrence of this xpath, or in other words, the second repetition of the HI segment. If no such repetition exists, the output node will remain empty.

This mapping approach makes the assumption that a maximum of two ClaimDiagnosisCode values are relevant. A different approach might remove the need for this assumption. For example, introducing a second line type in the CSV file that contains diagnosis information may allow the mapping to handle any number of codes. However, making the above assumption maintains the simplicity of the output data structure and of the mapping as a whole.

For the purposes of taking this example Flow and making it work with a live production case, it may be necessary to modify or address this assumption. We expect this sample to handle the vast majority of live data cases, but it is always important to understand any assumptions that must be true about the data being mapped.


The aim of this article is to help provide context to the sample 837-to-CSV Flow so you can see how it relates to your specific mapping needs. Once the principles of an EDI mapping Flow are understood, the majority of the work comes in understanding the specific mapping relationships within the XML Map Connector.

This sample contains many of the fundamental mapping techniques found in EDI mappings:

  • Foreach loops to handle repetitions
  • Value-to-value mappings
  • Lookahead conditionals
  • Custom scripting logic

For further help in understanding the tools available within the XML Map Connector, we recommend browsing the dedicated documentation page here.

Ready to get started?

Learn more about ArcESB or download the free single-connector license:

Download Now