Altova MapForce 2022 Enterprise Edition

Example: Customizing an ANSI X12 transaction

Home Prev Top Next

This example illustrates how to customize MapForce so that it can process non-standard or changed X12 formats. Note that this customization example is specifically based on version 6020 of ANSI X12; instructions may slightly vary for other X12 versions.

 

The example is accompanied by a sample mapping which is available at the following path: <Documents>\Altova\MapForce2022\MapForceExamples\Tutorial\ExtractCustomX12.mfd. Note that, if you open this mapping before following the customization instructions below, MapForce does not validate it successfully. The reason is that the mapping references a custom X12 collection which does not exist yet on your computer (it will be created in this example).

 

The example mapping reads data from the Orders-Custom.X12 file, available in the <Documents>\Altova\MapForce2022\MapForceExamples\Tutorial\ directory. If you open this file with a text editor, notice that it uses a customized N2 segment. Specifically, line 6 contains an additional ++Mrs entry:

mf_x12_customize_01

Before you can map data from custom X12 files such as the one above, a custom X12 configuration must be created. In this example, you will customize the default X12 configuration so as to extend the N2 segment with a new data element which would accommodate the title of the person. For convenience, the final result of the customization procedure is available in the <Documents>\Altova\MapForce2022\MapForceExamples\Tutorial\ directory, as a ZIP archive (X12.Nanonull.zip).

 

Prerequisites

To complete this example, first download the "X12 Configuration Files" executable from the Altova Download Center (https://www.altova.com/mapforce/download). Make sure to choose the package applicable to your version and platform (32-bit, 64-bit) of MapForce.

 

The installation package contains all X12 versions supported by MapForce, including version "6020" used in this example. To perform the installation, double-click the downloaded executable file and follow the on-screen instructions. After installation, new directories corresponding to the installed X12 configuration versions are created in C:\Program Files\Altova\MapForce2022\MapForceEDI.

 

If you run 32-bit MapForce on a 64-bit operating system, adjust the directory path above to C:\Program Files (x86).

 

Setting up the customization files

1.Create a new directory that will store your custom EDI collection, at the following path: C:\users\<name>\Documents\Altova\MapForce2022\MapForceEDI\X12.Nanonull. The name "X12.Nanonull" helps differentiate this custom EDI collection from the default one installed with MapForce.

2.Copy the following files from C:\Program Files\Altova\MapForce2022\MapForceEDI\X12.6020 to C:\users\<name>\Documents\Altova\MapForce2022\MapForceEDI\X12.Nanonull:

 

850.Config

EDI.Collection

Envelope.Config

ParserErrors.Config

X12.Codelist

X12.Segment

 

For information about the purpose of each file, see EDI Configuration Files.

 

The new EDI.Collection file should now be accessible to MapForce. You can test this as follows:

 

1.Start MapForce.

2.On the Insert menu, click EDI. Alternatively, click the Insert EDI ic-edi toolbar button. A dialog box such as the one below opens, displaying a new collection named "X12.Nanonull".

mf_x12_customize_02
Note:You can also create your custom EDI collection in a different directory, as described in Creating a Custom EDI Collection.

 

Configuring the EDI.Collection file

1.Open EDI.Collection file in an XML editor (for example, XMLSpy).

2.Remove all "Message" elements, except for the "Purchase Order" message. Make sure you retain the <Messages> tags, however.

 

<?xml version="1.0" encoding="UTF-8"?>
<Messages Version="3">
  <Meta>
    <Release>6020</Release>
    <Agency>X12</Agency>
  </Meta>
  <Root File="Envelope.Config"/>
  <Message Type="850" File="850.Config" Description="Purchase Order"/>
</Messages>

 

3.Save the file.

 

If you run the Insert | EDI menu command, now the collection shows only one message type: "850 - Purchase Order".

mf_x12_customize_03

 

Global versus inline customization

The goal of this example is to redefine the N2 "Additional Name Information" segment so that it contains a custom X1000 data element which would store a person's title (for example, "Mrs"). Before customization, N2 consists of one data element only, "F93 Name". There are several ways the customization can be achieved:

 

Globally, by customizing the X12.Segment file. "Global" means that all segments, in all transactions that use N2, will contain/reference the new element.

Inline, by customizing the 850.Config file. "Local" means that only the customized segment (N2) in the current transaction will contain the new element.

 

Global customization

To make access to the new X1000 field global, changes have to be made only to the X12.Segment file. All segments, in all transactions that use N2, will contain/reference the new element.

 

To redefine the N2 segment globally:

 

1.Open the X12.Segment file in an XML editor and navigate to Config | Elements | Segment name="N2".

<Segment name="N2" info="Additional Name Information">
  <Data ref="F93" mergedEntries="2"/>
</Segment>

2.Insert the following line under F93, and save the file.

<Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>

The segment definition should now look as shown below:

<Segment name="N2" info="Additional Name Information">
  <Data ref="F93" mergedEntries="2"/>

  <Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>
</Segment>

Notes:

 

The new X1000 field is defined using the name attribute as opposed to other fields of the segment which use the ref attribute. The F93 field is defined at the beginning of the X12.Segment file and is only referenced here.

The mergedEntries attribute of F93 specifies that there can be two consecutive occurrences of this element with the same name. This reflects the definition of this field as it is defined in the ASC X12 specification. For this reason, in the source EDI file that is being customized here, the N2 segment looks as follows:

N2+Michelle Butler++Mrs'

In the line above, notice the two consecutive "+" separators between "Michelle Butler" and "Mrs". The explanation is that the N2 segment consists of a "F93" data element ("Michelle Butler"), followed by a "+" separator, followed by the second "F93" element (which is empty), followed by a "+" separator, followed by the custom "X1000" data element ("Mrs"). For more information about the mergedEntries attribute, see Handling Multiple Consecutive Data Elements.

 

The new X1000 field is now available to all transactions that use segment N2. You can preview the new field in MapForce as follows:

1.On the Insert menu, click EDI. Alternatively, click the Insert EDI ic-edi toolbar button.

2.Click the "X12.Nanonull" collection, and select the "Purchase Order" message.

3.When prompted to select a source EDI file, click Skip. The 850 component is now visible in the mapping window.

4.Click the component header, press Ctrl + F and enter "X1000" as search text. Click Find Next to jump to the next occurrence of the new X1000 element (it should be under Envelope > Interchange > Group > Message_850 > LoopN1 > N2).

mf_x12_customize_04

 

Local customization

If you want to make access to the new X1000 field local, then only the 850.Config file must be edited. In this case, only the segment N2 in the "850 - Purchase Order" transaction will contain/reference the new X1000 field.

 

To redefine the N2 segment locally:

 

1.Open the 850.Config file in a text or XML editor and navigate to Group name="LoopN1" (or search for LoopN1).

 

<Group name="LoopN1" maxOccurs="10" minOccurs="0">
  <Segment ref="N1"/>
  <Segment ref="N2" minOccurs="0" maxOccurs="2"/>

 
  ... ...

 

</Group>

 

2.Replace the line <Segment ref="N2" minOccurs="0" maxOccurs="2"/> with the following lines:

 

<Segment name="N2" info="Additional Name Information">
  <Data ref="F93" mergedEntries="2"/>
  <Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>
</Segment>

 

The Group definition should now look as shown below:

 

<Group name="LoopN1" maxOccurs="10" minOccurs="0">
  <Segment ref="N1"/>
  <Segment name="N2" info="Additional Name Information">
    <Data ref="F93" mergedEntries="2"/>
    <Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>
  </Segment>

 
  ... ...

 

</Group>

 

You can now preview the new field in MapForce, using the same instructions as those described above for global customization.

mf_x12_customize_04

 

Using the customized message in mappings

If you have followed all the instructions above, you can now use the custom X12 configuration in your mappings. An example mapping which uses the custom EDIFACT configuration created above is ExtractCustomX12.mfd, available in the <Documents>\Altova\MapForce2022\MapForceExamples\Tutorial\ folder. The example maps the ORDERS-Custom.X12 file to a CSV file. The custom X1000 field that was added in the steps above maps to the Salutation item in the target file.

mf_x12_customize_05

ExtractCustomX12.mfd

To preview the mapping result, click the Output tab. As expected, the Salutation target item is populated with the value "Mrs" extracted from the custom X1000 data element of the X12 file.

mf_x12_customize_06

© 2016-2022 Altova GmbH