Example: Customizing an EDIFACT message

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Data Sources and Targets > EDI > Customizing EDI Structure >

Example: Customizing an EDIFACT message

This example shows you how to customize EDIFACT messages so that MapForce can process non-standard or changed EDIFACT formats. 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\MapForce2019\MapForceExamples\Tutorial\Orders-Custom-EDI.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\MapForce2019\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:

edi-adapt-1

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

 

Setting up the customization files

1.Open the MapForce installation directory (C:\Program Files\Altova\MapForce2019\ ). When running 32-bit MapForce on 64-bit operating systems, adjust the path to C:\Program Files (x86)\Altova\MapForce2019\MapForceEDI.
2.Under the ..\MapForceEDI\ directory, create a directory called EDIFACT.Nanonull.
3.Copy the following files from the ...\MapForceEDI\EDIFACT folder into the EDIFACT.Nanonull folder.

 

EDI.Collection
Envelope.Config
UNCL.Codelist
Admin.Segment
EDSD.Segment (Electronic Data Segment Definition)
ORDERS.Config

 

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 "ORDERS" message. Make sure you retain the <Messages> tags, however.

 

<?xml version="1.0" encoding="UTF-8"?>
<Messages Version="3">
  <Meta>
    <Version>D</Version>
    <Release>16A</Release>
    <Agency>UN</Agency>
  </Meta>
  <Root File="Envelope.Config"/>  
  <Message Type="ORDERS" File="ORDERS.Config" Description="Purchase order message"/>  
</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 "EDIFACT.Nanonull". When selected, the collection shows only one message type: "ORDERS".

mf_dlg_edi_customize

 

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 an ORDERS message.

 

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_map_Orders-Custom-EDI_1

 

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_map_Orders-Custom-EDI_1

 

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

mf_map_Orders-Custom-EDI_2

If you have followed the instructions above, you can open this mapping and run it successfully. However, if you have not followed the customization instructions, you can run this mapping as follows:

 

1.Create a new directory called "EDIFACT.Nanonull" under "C:\Program Files\Altova\MapForce2019\MapForceEDI\" directory. When running 32-bit MapForce on 64-bit operating systems, adjust the path to C:\Program Files (x86)\Altova\MapForce2019\MapForceEDI.
2.Unzip the EDIFACT.Nanonull.zip file (located in <Documents>\Altova\MapForce2019\MapForceExamples\Tutorial\) into the new directory.
3.Open Orders-Custom-EDI.mfd.

 

To preview the mapping result, click the Output tab.

edi-adapt-9

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 FlowForce 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.


© 2019 Altova GmbH