EANCOM Connectors support generating EANCOM documents (also known as GS1 documents) from XML or converting EANCOM documents into XML.
When receiving EANCOM documents, EANCOM Connectors validate interchange headers and convert the EANCOM document into XML. This is useful as a staging step, as XML is the primary format that ArcESB uses to manipulate data within a flow. The EANCOM Connector automatically reads the input file to determine the appropriate schema, then parses the document according to this schema.
When generating EANCOM documents, EANCOM Connectors convert XML into EANCOM document syntax and apply the appropriate interchange headers. This is useful as the final step for creating an EANCOM document, after the XML data has been fetched and transformed elsewhere in the flow.
This section contains all of the configurable connector properties.
Settings related to the core operation of the connector.
- Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
- Connector Description An optional field to provide free-form description of the connector and its role in the flow.
- Translation Type Whether the connector should convert EANCOM documents into XML, or generate EANCOM documents from XML.
Settings related to the EANCOM interchange headers. When converting EANCOM documents into XML, the document headers will be validated against these settings; when generating EANCOM documents from XML, these settings will be used to generate document headers.
- Syntax Identifier (UNB1.1) Identifies the character set used in the EANCOM document.
- Syntax Version (UNB1.2) In combination with the Syntax Identifier determines the syntax to be used in the EANCOM document. The available elements for interchange settings may change depending on this value.
- Service Code List Directory Version Number (UNB1.3) Further specifies the syntax to be used in the EANCOM document. Only applicable for EANCOM syntax version 4.
- Character Encoding (UNB1.4) Specifies how characters are encoded (e.g. ASCII, UTF-8). Only applicable for EANCOM syntax version 4.
- Sender Identifier (UNB2.1) The unique ID identifying the sending party in the EANCOM communication (when generating an EANCOM document, this should be your identifier).
- Sender Code Qualifier (UNB2.2) The qualifier for the Sender Identifier, providing context to the value (e.g. EAN location number).
- Address for Reverse Routing (UNB2.3) The optional address within the sender’s system to which responding interchanges should be sent. Only applicable for EANCOM syntax versions earlier than version 4.
- Sender Internal ID (UNB2.3) An additional sender identifier to facilitate internal routing of response interchanges. Only applicable for EANCOM syntax version 4.
- Sender Internal Sub-Identification (UNB2.4) Further identifies the sender, for when sub-level identification is required. Only applicable for EANCOM syntax version 4.
- Recipient Identifier (UNB3.1) The unique ID identifying the receiving party in the EANCOM communication (when generating an EANCOM document, this should be your partner’s identifier).
- Recipient Code Qualifier (UNB3.2) The qualifier for the Recipient Identifier, providing context to the value (e.g. EAN location number).
- Routing Address (UNB3.3) The optional address within the recipient’s system to which interchanges should be routed. Only applicable for EANCOM syntax versions earlier than version 4.
- Recipient Internal ID (UNB3.3) An additional recipient identifier to facilitate internal routing of received interchanges. Only applicable for EANCOM syntax version 4.
- Recipient Internal Sub-Identification (UNB3.4) Further identifies the recipient, for when sub-level identification is required. Only applicable for EANCOM syntax version 4.
- Recipient Password (UNB6.1) Reference or password to gain access to the recipient’s system.
- Recipient Password Qualifier (UNB6.2) The qualifier that provides context to the Recipient Password, if applicable.
- Application Reference ID (UNB7) Identifies the application group to which the messages in the interchange relate.
- Processing Priority Code (UNB8) Code for requesting processing priority for the interchange.
- Communication Agreement (UNB10) Defines the type of communication agreement controlling the interchange.
- Test Indicator (UNB11) Whether the interchange is in test mode or production mode. If this setting is enabled when receiving documents, interchange headers will not be validated.
Functional Group Settings
Settings related to the functional group headers of EANCOM documents. These optional identifiers may help group similar interchanges together or facilitate sub-addressing within an organization.
- Application Sender Identifier (UNG2.1) Identifies the application sending the document (e.g. a division, branch, or computer system).
- Application Recipient Identifier (UNG2.1) Identifies the application for which the document is intended.
Settings related to generating and requesting acknowledgments.
- Technical acknowledgment (CONTRL) expected Whether a technical CONTRL ACK should be returned (when receiving) and requested (when sending). A technical acknowledgment serves as a receipt of the interchange.
- Functional acknowledgment (CONTRL) expected Whether a functional CONTRL ACK should be returned (when receiving) and requested (when sending). A functional acknowledgment serves as an indication of acceptance or rejection of the received interchange.
- Route ACKs to Connector The specified connector will generate acknowledgments using the transaction data received by the current connector. The specified connector adds interchange headers and passes the acknowledgment along in the flow like any other message. Thus this should typically be set to a pre-configured EANCOM Connector that generates outbound documents for the intended recipient.
Settings related to the automatic processing of files by the connector.
- Send A toggle that instructs the connector to automatically send files when they are ready.
- Retry Interval The interval the connector will wait before retrying a failed send.
- Max Attempts The number of attempts the connector will make to send the message. Setting this value to 1 instructs the connector to only make the initial send attempt without retrying. The connector waits the duration specified by Retry Interval between each attempt.
Settings that determine where on disk files will be processed from, and where they will be placed after processing.
- Input Folder (Send) Files placed in this folder will be processed by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to process.
- Output Folder (Receive) Files will be placed here after being processed by the connector. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
- Processed Folder (Sent) After processing a file, the connector will place a copy of the processed file in this folder if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.
Settings that specify which characters separate elements, segments, etc.
- Data Element Separator The character that separates individual data elements within the document.
- Component Element Separator The character that separates elements within a composite data structure in the document.
- Segment Terminator The character that indicates the end of a segment within the document.
- Release Char The character that ‘releases’ or ‘escapes’ the next character, overriding its usual meaning. This allows reserved characters to appear as data withing documents, as long as they are preceded by the Release Char.
- Repetition Char The character that indicates repetition of element values.
- Suffix Appended to the Segment Terminator to distinguish segments.
Settings related to the allocation of resources to the connector.
- Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
- Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.
Settings not included in the previous categories.
- Generate Description As When translating EANCOM into XML, descriptions of the EANCOM segments and elements will be provided as context for the EANCOM data. This context can be added as an XML comment or included within the XML elements as XML attributes. Use this setting to determine which of these approaches, or neither, is used.
- Nest Master-Detail Loops When enabled, the connector will detect EDI structures that have hierarchical relationships embedded in the EDI data, and will generate XML with these hierarchical relationships represented as Parent-Child relationships. For more information, please see the Master-Detail Hierarchy: Translating CPS Loops section.
- SNIP Validation When enabled, the connector will perform the first three levels of SNIP Validation for HIPAA compliance: (1) the syntactical integrity of the document, (2) the presence of required segments and appropriate repetitions for repeated segments, and (3) the correct mathematical relationship between claim line items and claim totals. Higher levels of SNIP Validation (4+) may require a Validate Connector or custom script.
- Send Filter A glob pattern filter to determine which files in the Send folder will be processed by the connector (e.g. *.edi). Negative patterns may be used to indicate files that should not be processed by the connector (e.g. -*.tmp). Multiple patterns may be separated by commas, with later filters taking priority except when an exact match is found.
- Local File Scheme A filemask for determining local file names as they are processed by the connector. The following macros may be used to reference contextual information:
%ConnectorId%, %Filename%, %FilenameNoExt%, %Ext%, %ShortDate%, %LongDate%, %RegexFilename:%, %DateFormat:%, %ControlNumber%, %TransactionControlNumber%, %TransactionCode%, %StandardVersion%.
As an example: %FilenameNoExt%_%ControlNumber%%Ext%
- Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector.
- Strict Schema Validation Whether the connector should Ignore, Warn, or Fail when the following are detected: Repeat counts above the allowed number; missing required elements/segments; invalid qualifier and code values; disallowed element lengths; invalid element values.
Settings for specific use cases.
- Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like
setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.
XML to EANCOM
When generating EANCOM files, select the Translation Type to be XML to EANCOM. The application reads all of the header information for the Interchange, Functional Group, and Message sections from the settings configured in the Settings page for this connector. These settings include the sender identifier and code qualifier, receiver identifier and code qualifier, and so on.
Once you have configured the v with the settings from your trading partner agreement, click the Input tab and select More > Create Test Files. The application creates various test XML files that provide example data of what the XML should look like for the connector to generate an EANCOM document. You can also select the documents and click Send to see the generated EANCOM documents.
EANCOM to XML
When generating XML, select the Translation Type to be EANCOM to XML. The application only processes EANCOM files when this option is selected. You need to configure the settings for the trading partner agreement on this page for the application to validate the information in EANCOM documents during processing. XML files are generated into the Output folder for this connector.
Click the Input tab and select More > Create Test Files to create test EANCOM files for several EANCOM documents. You can select these documents and click Send to see the generated XML.
Acknowledgments can be automatically generated and processed by the application. There are two commonly requested types of acknowledgments used in EANCOM communications, interchange and functional. Both of the acknowledgments types are classified as as EANCOM CONTRL message.
This is an indication that an interchange has taken place between the two parties (though not necessarily that any individual message has been exchanged) and is generated automatically in response to a request in the interchange.
Functional acknowledgments are an indication that an individual message such as an Invoice or PO has been accepted. These are generated in response to a bidirectional agreement by both parties.
EANCOM Connectors in XML-to-EDI mode can be configured so that both interchange and functional acknowledgments can be requested for a message. Select the Technical acknowledgment (CONTRL) expected and Functional acknowledgment (CONTRL) expected check boxes in the Settings tab of the connector to direct the connector to maintain a Pending ACK status for the transmission until the appropriate acknowledgments have been returned and processed.
The above illustration shows a complete message exchange from the standpoint of the message originator. An EANCOM Connector in XML-to-EDI mode generates the document to be exchanged (1) and holds it in a Pending ACK state. The trading partner processes the transmission in their business logic and creates acknowledgments in accordance with the configured exchange parameters and the bidirectional agreement between parties (2). When the acknowledgments are returned, they are parsed with and an EANCOM Connector in EDI-to-XML mode and routed to the original EANCOM Connector (XML-to-EDI) to resolve the status of the transfer (3).
When interchange and functional EANCOM acknowledgments are received at an EANCOM Connector in EDI-to-XML mode, the connector can be configured to automatically route any detected acknowledgments to the EANCOM Connector that first generated the transmission. Select the originating (XML-to-EDI) EANCOM Connector in the Route ACKs to Connector menu in the settings for the receiving (EDI-to-XML) EANCOM Connector.
The configured (XML-to-EDI) EANCOM Connector pairs the acknowledgments to the original message and resolves the matching message.
When an EANCOM Connector in EDI-to-XML mode processes received messages from the originator and generates XML, tell the connector to automatically generate CONTRL acknowledgments by selecting the Acknowledgment check boxes in the Settings tab. Route these acknowledgments to an EANCOM Connector in XML-to-EDI mode to generate the EANCOM acknowledgement. In the Route ACKs to Connector menu, select the (XML-to-EDI) EANCOM Connector that generates EANCOM documents for this partner.
As shown in the above diagram, when a partner sends a message where an acknowledgment is expected (1), the (EDI-to-XML) EANCOM Connector configured for that partner automatically generates an acknowledgment (2) as an XML file containing the transactional information relevant for that file. This XML acknowledgment must be routed back to an (XML-to-EDI) EANCOM Connector (3) so that all of the EDI party agreement settings are used when generating the EANCOM file that is sent back to your trading partner.
Master-Detail Hierarchy: Translating CPS Loops
In EDI documents, most hierarchical relationships are represented by the order of EDI segments. Some EDI structures, like CPS Loops (which are found in DESADV documents), do not follow this convention and instead have the hierarchical relationships embedded in the EDI element data itself. This can make it difficult to preserve these hierarchical relationships when converting the EDI data to XML.
The EANCOM Connector supports preserving hierarchical relationships in CPS segments via the Nest Master-Detail Loops setting in the Advanced tab. When enabled, the connector will parse the elements within the CPS segments to determine which segments “belong to” other segments in a hierarchical relationship. These hierarchical relationships are reflected in the output XML as Parent-Child relationships; in other words, this setting converts hierarchy implied by the EDI content into hierarchy represented by the XML structure.
This section will briefly explain both how hierarchy is encoded in CPS data, and how this hierarchy is converted into XML when Nest Master-Detail Loops is enabled.
All CPS segments have two values that help establish hierarchy:
- an ID value, which identifies the current CPS segment (this value is stored in CPS01, or the first element in an CPS segment)
- a parent-ID value, which identifies the current CPS segment’s hierarchical parent (this value is stored in CPS02, or the second element in an CPS segment)
For example, say that an CPS segment has an ID value of ‘2’. If the next CPS segment should “belong to” this prior segment in a hierarchical relationship, then the next CPS segment’s parent-ID should also be ‘2’.
If an CPS segment’s parent-ID is ‘0’, this means that the segment does not have a parent (i.e. it is at the top level of the hierarchy).
Converting CPS Hierarchy to XML
When Nest Master-Detail Loops is enabled, the EANCOM Connector handles the conversion of CPS hierarchy to XML hierarchy automatically. The connector parses the ID and parent-ID values from CPS segments and ensures that the resulting XML elements are appropriately nested (indented) inside the elements representing their parents.
In other words, if segmentA’s parent-ID value is equal to segmentB’s ID value, then the resulting XML will have segmentA as a child of segmentB. In this way, the hierarchical relationships are preserved in the XML structure when the EDI data is translated.