Altova MapForce 2022 Enterprise Edition

Example: Customizing an EDIFACT message

Home Prev Top Next

This example shows you how to customize EDIFACT messages so that MapForce can process non-standard or changed EDIFACT formats. Note that this customization example is specifically based on version 19B of EDIFACT; instructions may slightly vary for other EDIFACT versions.

 

A sample mapping which processes a custom EDIFACT file with a slightly extended CTA (Contact Information) segment of the ORDERS message is available at the following path: <Documents>\Altova\MapForce2022\MapForceExamples\Tutorial\ExtractCustomEDIFACT.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 EDIFACT configuration which does not exist yet on your computer (it will be created in this example).

 

The example mapping reads data from the Orders-Custom.EDI 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 CTA segment. Specifically, line 9 contains a Mr entry, and line 11 contains a Mrs entry:

mf_edifact_customize_01a

Before you can map data from custom EDI files such as the one above, a custom EDIFACT configuration must be created. In this example, you will customize the default EDIFACT configuration so as to extend the CTA segment with a new field 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 (EDIFACT.Nanonull.zip).

 

Prerequisites

To complete this example, first download the "EDIFACT 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 EDIFACT versions supported by MapForce, including version "19B" 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 EDIFACT 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).

 

Create the custom EDI collection

1.Create a new directory that will store your custom EDI collection, at the following path: C:\users\<name>\Documents\Altova\MapForce2022\MapForceEDI\EDIFACT.Nanonull. The name "EDIFACT.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\EDIFACT.2019B to C:\users\<name>\Documents\Altova\MapForce2022\MapForceEDI\EDIFACT.Nanonull:

 

Admin.Segment

EDI.Collection

EDSD.Segment

Envelope.Config

ISO6346.Codelist

ORDERS.Config

UNCL.Codelist

 

Except for ORDERS.Config, all these files are referenced from the Envelope.Config file, so they must be present in the EDI collection. 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 (or restart it if it was already running).

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

mf_edifact_customize_01
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 the EDI.Collection file from your custom EDI collection in an XML editor (for example, XMLSpy).

2.Remove all "Message" elements, except for the "ORDERS" message. The file should now look as follows:

 

<?xml version="1.0" encoding="UTF-8"?>
<Messages Version="3">
  <Meta>
    <Version>D</Version>
    <Release>19B</Release>
    <Agency>UN</Agency>
  </Meta>
  <Root File="Envelope.Config"/>  
  <Message Type="ORDERS" File="ORDERS.Config" Description="Purchase order message"/>  
</Messages>

 

3.Save the file.

 

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

mf_edifact_customize_02

 

Global versus inline customization

The goal of the example is to redefine the CTA (Contact Information) segment. The CTA segment consists of one field (F3139) and one composite (C056). To store the title data (for example, "Mr" or "Mrs"), we will add to the C056 composite a new field, called X1000. There are several ways to perform the customization:

 

Globally, by customizing the EDSD.segment file. All segments, in all messages that use composite C056, will contain/reference the new element.

Inline, by customizing the ORDERS.Config file. Only the customized segment (CTA) in the current message will contain the new element.

 

Global customization

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

 

To redefine the Composite C056 globally:

 

1.Open the EDSD.Segment file in a text or XML editor, and navigate to Config | Elements | Composite | C056.

<Composite name="C056" info="CONTACT DETAILS">
 <Data ref="F3413" minOccurs="0"/>
 <Data ref="F3412" minOccurs="0"/>
</Composite>

2.Insert the following line in the C056 segment, under "F3412":

 

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

 

The Composite definition should now look as shown below:

<Composite name="C056" info="CONTACT DETAILS">
 <Data ref="F3413" minOccurs="0"/>
 <Data ref="F3412" minOccurs="0"/>

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

In the code listing above, the new X1000 field is defined using the "name" attribute as opposed to other fields of the segment which use the "ref" attribute. The two other fields are defined at the beginning of the file and are only referenced here.

 

The new X1000 field is now available to all messages that use composite C056. 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 "EDIFACT.Nanonull" collection, and select the ORDERS message.

3.When prompted to select a source EDI file, click Skip. The ORDERS 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_ORDERS > SG2 > SG5 > CTA > C056).

mf_edifact_customize_03

 

Inline customization

To make access to the new X1000 field local (or inline), changes have to be made only to the ORDERS.config file. In this case, only the redefined CTA segment in the current message will contain/reference the new element. In other words, the CTA segment is redefined locally to contain a redefined Composite C056, with a custom new field X1000.

 

To redefine the Composite C056 locally:

 

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

 

<Group name="SG5" minOccurs="0" maxOccurs="5" info="CTA - Contact information">
  <Segment ref="CTA"/>
  <Segment ref="COM" minOccurs="0" maxOccurs="5"/>
</Group>

 

2.Replace the line <Segment ref="CTA"/> with the following lines:

 

<Segment name="CTA" id="CTA_ORDERS_SG5" info="CONTACT INFORMATION">
  <Data ref="F3139" minOccurs="0"/>
  <Composite name="C056" minOccurs="0" info="DEPARTMENT OR EMPLOYEE DETAILS">
          <Data ref="F3413" minOccurs="0"/>
          <Data ref="F3412" minOccurs="0"/>
          <Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>
  </Composite>
</Segment>

 

The Group definition should now look as shown below:

 

<Group name="SG5" minOccurs="0" maxOccurs="5" info="CTA - Contact information">
  <Segment name="CTA" id="CTA_ORDERS_SG5" info="CONTACT INFORMATION">
  <Data ref="F3139" minOccurs="0"/>
  <Composite name="C056" minOccurs="0" info="DEPARTMENT OR EMPLOYEE DETAILS">
          <Data ref="F3413" minOccurs="0"/>
          <Data ref="F3412" minOccurs="0"/>
          <Data name="X1000" type="string" maxLength="35" minOccurs="0" info="New Element"/>
  </Composite>
  </Segment>
  <Segment ref="COM" minOccurs="0" maxOccurs="5"/>
</Group>

 

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 "EDIFACT.Nanonull" collection, and select the ORDERS message.

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

4.Navigate to Envelope > Interchange > Group > Message_ORDERS > SG2 > SG5 > CTA > C056, to see the new X1000 element.

mf_edifact_customize_04

 

Using the customized message in mappings

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

mf_edifact_customize_05

To preview the mapping result, click the Output tab. As expected, the value "Mrs" extracted from the custom X1000 data element of the EDIFACT file appears in the second field of the CSV file ("Salutation").

mf_edifact_customize_06

Similar to other mapping design files in MapForce, EDI mappings can be executed outside MapForce as well. For example, you can deploy them to another server for execution with MapForce Server, or generate program code to run the mapping. For the scope of this example, if you choose to run the mapping by generating C++ code, note that a class named "CX1000Type" is generated, which is accessible from the "CC056Type" class.

 

© 2016-2022 Altova GmbH