Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Pega Foundation for Healthcare X12 message processing tech note

Updated on April 23, 2021


The Accredited Standards Committee (ASC) X12 message is used to transfer data across and between industries. Pega Foundation for Healthcarecan recognize, accept, and parse messages that comply with the X12 EDI Standard version 5010. The following message standards are supported:

The parsing of each message file type shown above is complete according to the EDI Standard defined for the message, and no further extension is needed. It is assumed that the message is compliant with the ASC X12 Standards for EDI Technical Report Type 3 documents (Implementation Standard) and has been validated against all WEDI SNIP validation edits for

syntax validation, balancing validation, and inter-segment validations. This is typically done by EDI Gateway systems.

The X12 standards provide the syntax and control structures that allow data elements, segments, and transaction sets to be defined. The following diagram shows the overall structure of X12 data and examples of message content.

ISA*00* *01*SECRET *ZZ*107039 *ZZ*103269

*030101*1253*^*00501*000000905*1*T*:~ GS*HC*107039*103269*20100601*0802*1*X*005010X222~ ST*837*1002*005010X222~ BHT*0019*00*1002*20100601*09460000*CH~


NM1*40*2*MY HEALTHPLAN*****46*12345MYHP~

HL*1**20*1~ PRV*BI*PXC*193200000X~


N4*CAMBRIDGE*MA*021421234~ REF*EI*666666666~

HL*2*1*22*0~ SBR*P*18*******CI~

NM1*IL*1*GAST*RONALD*T***MI*S-007~ N3*125 CITY AVENUE~ N4*HOPKINTON*MA*017481234~ DMG*D8*19390412*M~


CLM*GASTR12*170***11:B:1*Y*A*Y*I*P~ HI*BK:V202*BF:25000~

Each line is a segment that starts off with a segment identifier and ends with the tilde (~) symbol. Each segment is composed of one or more delimited data elements. The most common delimiter used is the asterisk (*) and it is used in the example below.

The example above is a part of an 837 claim transaction. In the example, the following line is an NM1 segment.

NM1*40*2*MY HEALTHPLAN*****46*12345MYHP~

This NM1 segment represents the Receiver Name. The segment’s structure is of the 837 transaction type, Loop 1000B, which means that it is the Receiver Name. In addition, the first data element in the segment indicates that it is the Receiver Name. The NM1 segment contains the following data elements:

  • *40* — Entity identifier code (40=Receiver)
  • *2* — Entity type qualifier (2=non-person entity, 1=person)
  • *MY HEALTHPLAN* — Last name or Organization name
  • ***** — 4 unused data elements
  • *46* — Identification code qualifier (46=Electronic Transmission Identification Number)
  • *MYHP* — Identification code (Receiver Identifier)

Mapping X12 messages

The rules described below are available as part of the PegaX125010 Application included in your media.

Rules for processing X12 transaction files are stored in the following rulesets:

  • PegaX12 — Base classes for all supported X12 messages
  • PegaX125010 — Rules for processing version 5010 of the X12 EDI Standard
  • PegaHCEDI —Rules and sample business processes for processing 270/271 and 276/277 transactions

There is a class for each segment in the X12 standard and a property for each data element in the segment. These classes are common to all transaction types and can be used by each of them. In addition, a class exists for each transaction type (such as PegaX12-Data-N837), which is built using the predefined classes as the inbound X12 message file is processed.

The data in an X12 message is typically received by a File or MQ Listener agent rule that maps the data to properties on the clipboard. An activity rule dynamically determines the message type based on information in the functional group segment of the message. A clipboard page is created that includes all the transactions that are found in the functional group. It is assumed that a functional group contains transactions of the same type (e.g. all 837). However, an X12 message file can contain more than one functional group, and each group can contain different transaction types. While unlikely, Pega Foundation for Healthcare can process an X12 message file containing multiple transaction types and map them all to the clipboard. Pega Foundation for Healthcare maps the data in the message to the X12 clipboard page. The following example is for the N837 claim transaction:

  • While maintaining the looping structure, a property of an associated class is created for each segment as embedded pages in the PegaX12-Data-N837 class.
  • Properties are then created in each of these segment classes for each data element.
  • These segment classes are defined in the PegaX12-Data- class and are general for all message types.
  • A class is created for each loop.

X12 inbound message processing

Pega Foundation for Healthcare provides a pre-configured File Service rule instance called X12file.X12.X12Inbound that reads the X12 message input file and calls the activity X12ParseMessageStart to start the processing.

The X12ParseMessageStart activity includes Java that calls the X12ParseMessageType activity. This activity sets the type of transactions that are in each functional group. It then calls an activity that handles the given message type by calling the X12ParseMessage activity defined in the appropriate class (such as PegaX12-Data-N837).

The X12ParseMessage activity is composed of Java code that parses the message according to its message type (such as 837) to determine the segments and the context of where these segments lie within the message. With this information, the activity determines the classes that should be populated with the data and calls a Parse Delimited rule for each segment. The rule parses the data and puts the data onto the clipboard. After the entire functional group has been processed, an instance of the X12 data object is created.

The Java code in the activity uses the syntax of a given message type based on the segments used and the format of the transaction as defined in the associated EDI Implementation Guide. The code uses the following logic to parse the X12 message one segment at a time:

  1. Gather control information from the ISA, GS, and ST segments and determine the message type found in the GS functional group.
  2. Keep track of the current loop identifier and monitor when it changes. The loop identifier is hard coded into the Java code based on the message type. With the 837 message type, the starting loop ID is HEADER, which switches to the second loop 2000A. The loop ID can change when any of the following is found:
    • HL segment identifying a new Hierarchical Level
    • NM1 segment identifying a new sub-loop
  3. For each segment, identify the Parse Delimited rule name and the class that should be populated with this segments data. Invoke that Parse Delimited rule to populate the clipboard with the appropriate class and properties.

X12 message classes

Two types of classes support processing X12 Messages:

  • Generic classes that are common to all types of X12 messages. There is one class for each segment in the X12 standard.
  • Specific classes for a given message type (such as 837). These are sub-classes of the message type class (such as PegaX12-Data-N837). These classes contain properties that are of the appropriate PegaX12-Data-segment class.

Segments and properties

Each data element in a segment results in a property defined in the class for that segment. Refer to the X12 EDI standards documentation for a complete list of all the segments and their data elements (classes and properties). Some of the properties for an 837 message are discussed here for illustration purposes.

This diagram is a data element diagram taken from the X12 EDI standards documentation showing the data segments in the NM1 segment. The NM1 segment holds the individual or organization name. The first data element, NM101 Entity ID Code, identifies how this name will be used. For example, a value of “40” identifies this as the name of the Receiver of the transaction. The second data element, NM102 Entity Type Qualifier, determines if this name is for an individual or an organization. A value of “1” is a person and a value of “2” is a non-person.

The data element for the NM1 segment in the diagram results in the creation of the following properties in the NM1_IndividualOrOrganizationalName class.

Key X12 mapping rules

Activity rules map the X12 message into the X12 page on the clipboard. This table describes each of the activities used in mapping X12 messages (837 example).

Rule nameFunction
Class: PegaX12-Data-

Initial activity that starts the processing of an X12 file. This activity is called from the service rule that handles the X12 inbound interface. It reads the message in and breaks it into sub-messages, each containing a functional group (bounded by GS and GE segments). It then calls

X12ParseMessageType for each sub-message for continued processing.

X12ParseMessageTypeThis activity sets the message type and calls the X12ParseMessage activity in the appropriate class to process the message.

Writes an outbound X12 message to a file in a temp folder on the server.

This activity should be modified to customize the output location.

Class: PegaX12-Data-N837

Invokes Parse-Delimited-Rules that parse and map the 837 message into X12 segments and properties on an X12 page on the clipboard. Each Parse-Delimited-Rule parses data elements in a segment. It creates an instance of the PegaX12-Data-N837 data object and calls the following activity:

CreateHCClaimWork to map data to claim work object.

CreateHCClaimWorkPlaceholder activity, implemented in Claims Layer (PegaHCCLM).
X12GenerateProfessionalGenerates the X12 message with a single professional claim from the X12 clipboard structure.

Generates the X12 message with a single institutional claim from the X12

clipboard structure.

X12 EDI management

The Foundation contains preconfigured rules for managing the following pair of real-time X12 EDI messages:

  • X12 270/271 — Healthcare Eligibility Request and Response
  • X12 276/277 — Healthcare Claim Status Request and Response

The sample implementations contain message intake and parsing rules, work object creation and mapping, sample business edits, and outbound response message generation. The Foundation also includes sample X12 files for 270 and 276 messages.

Healthcare eligibility request message processing

The Foundation provides preconfigured rules to process real-time 270 Eligibility Request messages. The X12 parsing rules are configured per the X12 270/271 Implementation Guide of the Standard and support batch as well as real-time message processing.

The sample scenarios included in the Foundation reflect a real-time processing situation with an immediate response generated after processing the message. To reflect that real-time situation, the messages are limited to one benefit request per member (subscriber or patient).

The key functionality includes:

  • X12 270 Message Parsing — Per the 270/271 Implementation Guide
  • Eligibility Request Work Object Creation — For every benefit request submitted in the transaction
  • Validation of Information Source Level
    • Check Limit Validation — Sample business validation rule evaluates for the number of benefit requests in a single transaction. The validation fails if the number exceeds a pre-defined threshold for real-time processing (Foundation parameter is set at 25). If validation fails, further processing of the message is skipped, and an appropriate AAA Request Validation segment is included in this loop in the outbound 271 message.
      • AAA01 = Y
      • -AAA03 = 04
      • AAA04 = C
  • Validation of Information Receiver Level
    • Check for Provider on File — The sample business validation rule that searches for the provider record based on the Information Receiver record is not found in the sample database. If validation fails, further processing of the message is skipped, and an appropriate AAA Request Validation segment is included in this loop in the outbound 271 message.
    • AAA01 = Y
    • AAA03 = 51
    • AAA04 = C
  • Validation of Subscriber Level
    • Check for Subscriber on File — Sample business validation rule that searches for the subscriber record based on the Subscriber ID submitted on the 270. The validation fails if a matching subscriber record is not found in the sample database. If validation fails, further processing of the message is skipped, and an appropriate AAA Request Validation segment is included in this loop in the outbound 271 message.
  • AAA01 = Y
  • AAA03 = 75
  • AAA04 = C
  • Eligibility Benefit Request Processing
    • Check for Active Policy — If validation fails, an appropriate EB segment is returned in the 271 message.
      • EB*6**30~
      • EB01 = 6 (Inactive)
      • EB03 = 30 (Health Benefit Plan Coverage)
    • Check Eligibility On Service Date — The validation fails if the requested service date is outside the effective period on the active policy. If validation fails, an appropriate EB segment is returned in the 271 message.
      • EB*I**30~
      • EB01 = I (Non Covered)
      • EB03 = 30 (Health Benefit Plan Coverage)
    • Process Generic Eligibility Request — The following 2110C/D EB03 values are returned if they are a covered benefit category at a plan level.
      • 1 - Medical Care
      • 33 - Chiropractic
      • 35 - Dental Care
      • 47 - Hospital
      • 86 - Emergency Services
      • 88 - Pharmacy
      • 98 - Professional (Physician) Visit – Office
      • AL - Vision (Optometry)
      • MH - Mental Health
      • UC - Urgent Care
    • If a specific EQ segment is not submitted on the 270, a minimum eligibility information response is returned in the corresponding EB segment on the 271 response message.
    • X12 271 Message Generation — per the 270/271 Implementation Guide.

Key rules for eligibility request and response message

This table lists the key rules used in the processing of the X12 270/271 messages.

Rule nameRule typeFunction
Class: PegaHC-EDI-Work-EligibilityRequest
ProcessX12N270ActivityMain activity to launch 270 message processing
Process270TransactionCollectionMain collection rule for processing 270 message
ParseTransactionCollectionParses 270 message and prepares 271 response
ValidateTransactionCollectionControls validation rules for various loops
ValidateInformation SourceCollectionControls validation of Information Source level



CollectionControls validation of Information Receiver level
ValidateSubscriberCollectionControls validation of Subscriber level
ProcessEligibility RequestCollectionControls mapping to work object and processing of benefit request
SendResponseCollectionControls 277 message generation and distribution
ParseMessageActivityParses 270 message
PrepareResponseActivityPrepares 271 message shell
CheckLimitActivityValidates the number of requests in a transaction
CheckProviderOnFileActivityLooks up Provider based on ID submitted on 270
CheckSubscriberOnFileActivityLooks up Subscriber based on ID submitted on 270
MapMessageToWork itemActivityMaps 270 message to work object
ProcessEligibilityActivityInitiates specific benefit request processing
Generate271ActivityGenerates 271 message
SendMessageActivityPlaceholder for 271 message distribution
ReviewX12ActivityProvides side by side comparison of 270-271

Healthcare claim status request message processing

The Foundation provides preconfigured rules to process real-time 276 Claim Status Request messages. The X12 parsing rules are configured per the X12 276/277 Healthcare Claim Status Request & Response Implementation Guide and support batch, as well as real-time message processing.

The sample scenarios included in the Foundation reflect a real-time processing situation with an immediate response generated after processing the message. To reflect this real-time situation, the messages are limited to one claim status request per member (subscriber or patient).

As per the X12 276/277 Implementation Guide specification, there is no validation at the various levels of the message loops.

The key functionality includes:

  • X12 276 Message Parsing — per the 276/277 Implementation Guide.
  • Claim Status Request Work Object Creation — for every claim submitted in the transaction.
  • Claim Retrieval — sample business rules to retrieve a claim from the sample database based on the Claim Identifiers submitted on the 276 message. If a matching claim is not found, an appropriate STC segment is returned on the outbound 277 message. If a matching claim is found, the system returns the claim status information in the STC segment of the 277 message.
  • X12 277 Message Generation — per the 2760/277 Implementation Guide.

Key rules for claims status request and response message

This table lists the key rules used in the processing of the X12 276/277 messages.

Rule nameRule typeFunction
Class: PegaHC-EDI-Work-ClaimStatusRequest
ProcessX12N276ActivityMain activity to launch processing of 276 message
Process276TransactionCollectionMain rule for processing 276 message
ParseTransactionCollectionParse message & prepare 277 response
ProcessClaimStatus RequestCollectionMaps message to work object and processes claim lookup
SendResponseCollectionGenerates 277 and sends message
ParseMessageActivityParses 276 message
PrepareResponseActivityPrepares 277 message shell
MapMessageToWork ItemActivityMaps 276 message to work object
SendMessageActivityPlace holder to configure 277 message
ReviewX12ActivityProvides side by side comparison of 276 and 277

X12 N834 Benefit Enrollment - Inbound

Pega Foundation for Healthcare provides a mechanism to manage membership enrollment workflow processes and be able to intake a HIPAA compliant 834 inbound messages for Member / Policy - Adds / Updates / Terminations.

The existing membership and policy workflows in the sample data admin portals will be enhanced and designed using data flows for each category of transaction:

  • New Benefit Enrollment Full File (typically generated monthly)
  • Benefit Enrollment Change File (for adds / updates / deletes of member and policy profiles)

The process work flows include the ability to pool cases for periodic batch file generation based on configurable time parameters (nightly / weekly / monthly) and a portal to manage and demo the transaction processing.

Business users are also able to model required transaction elements like transaction IDs, keys, and other metadata that is needed to generate HIPAA compliant outer loops of the transaction files.

The ability should include following:

  • Ability to ingest a change or monthly file
  • Ability to enroll a subscriber
  • A dashboard to run the sample demo
  • A configurable page to support mandatory elements configuration

Implemented the capability to read and Map Parsed-834 records from existing N834 table.

  1. A Job schedular – “Process834Records” implemented as part of PegaX12 application.
  2. This Job schedular is responsible for retrieving the persisted and unprocessed 834 records.
    1. Map the details to the existing PFHC Member -Policy Data modal.
    2. Create Enrollment case for each record with the data structure created above.

The following are the key features of Enrollment Case:

  • Stage-based case life cycle using the Pega Platform Case Designer to showcase the Enrollment Process.
  • Though There is no manual intervention in the case type at this point as we are creating the enrollment cases by reading 834 records, it is easy to extend and implement the manual process of Member -Policy Enrollment.
  • Create the Enrollment case as a parent case and child cases for each member/insurer in the select 834 record.
  • Enrollment case gets resolved once all the child cases gets resolved.
  • Implemented Exception handling and retry in case of exceptions as part of case life cycle.
  • Child case (member case) will be routed to the Admin WB in case of exception for further processing.

Customer can utilize these case types if their requirement matches or these case types can be extended and modify as per the requirement.

X12 message processing: Demo portal

The X12 Demo portal provides the capability to demonstrate and simulate the intake and processing of X12 EDI messages.

The list comes with pre-configured sample message types and can be leveraged to add/update new transactions. Each demo scenario is tagged with a sample file.

To access and demo the X12 Processing capability, log in to the system as 5010Administrator (use the password that you specified when you enabled this operator. To enable Pega-provided operators, see Enabling operators) and launch the X12 Demo portal.

Select a message type and click Submit.

After processing is completed with the sample file, review the X12 Message processing summary, which lists the following:

  • File name
  • Time taken in processing
  • Number of messages sent and processed with given sample file

Click Review X12 Message to view inbound and outbound messages:

Sample X12 scenario maintenance

For adding/updating X12 scenarios, navigate to the “PegaHC-Data-DemoScenarios” data type and open it.

To add a new demo scenario, click Add Record (+) and enter the required details.

To add a new demo scenario to the sample X12 processing portal, add a new record to the PegaHC-Data-DemoScenarios data type and complete the following fields.

Key rules for X12 Demo-scenarios maintenance

Rulename Ruletype Function
D_PegaHCDataDem oScenariosListData PageTo get all demo scenarios for all transaction types




Used to retrieve all the DemoScenario instances from the System

X12 message processing: Log file notes

There is no log published to the system log file while processing X12 messages. This is to avoid publishing any sensitive health data to log files.

  • Previous topic Pega Foundation for Healthcare 8.7 common objects API technical specification guide

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us