Please enable JavaScript to view this site.

Altova MapForce 2020 Enterprise Edition

This example illustrates how to customize MapForce so that it can process non-standard or changed X12 formats. The example is accompanied by a sample mapping which is available at the following path: <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\Orders-Custom-X12.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\MapForce2020\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:

x12-source1

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 your convenience, the final result of the customization procedure is available in the <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\ directory, as a ZIP archive (X12.Nanonull.zip). The instructions below assume that you have not unpacked the ZIP file to the C:\Program Files\Altova\MapForce2020\MapForceEDI directory.

 

Setting up the customization files

1.Open the MapForce installation directory (C:\Program Files\Altova\MapForce2020\ ). When running 32-bit MapForce on 64-bit operating systems, adjust the path to C:\Program Files (x86)\Altova\MapForce2020\MapForceEDI.

2.Under the ..\MapForceEDI\ directory, create a directory called X12.Nanonull.

3.Copy the following files from the ...\MapForceEDI\X12 folder into the X12.Nanonull folder.

 

850.Config

EDI.Collection

Envelope.Config

ParserErrors.Config

X12.Codelist

X12.Segment

 

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

 

Note:        Change the attributes of the files to read-write to make them editable.

 

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>6040</Release>
    <Agency>X12</Agency>
  </Meta>
  <Root File="Envelope.Config"/>
  <Message Type="850" File="850.Config" Description="Purchase Order"/>
</Messages>

 

3.Save the file.

 

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". When selected, the collection shows only one message type: "Purchase Order".

mf_x12_customize_01

 

Note:At startup, MapForce scans all sibling subfolders under the ...\MapforceEDI\ directory and looks for a file called "EDI.Collection". Each folder name containing an EDI.Collection file appears in the dialog box. The Message types list shows the content of the collection file, which in this example contains only a "Purchase Order" message.

 

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/Loop_N1/N2).

mf_x12_customize_02

 

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_02

 

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 Orders-Custom-X12.mfd, available in the <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\ folder. The example maps the ORDERS-Custom.X12 file to the Order-EDI.xsd schema. The custom X1000 field that was added in the steps above maps to the Salutation item in the target schema.

mf_x12_customize_03

Orders-Custom-X12.mfd

If you have followed the instructions above, you can open this mapping and run it successfully. 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.

x12-example2

© 2020 Altova GmbH