Adapting Code Values from External Sources

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

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

Adapting Code Values from External Sources

In the EDI configuration files supplied by default with MapForce, some data elements are configured to have incomplete validation, as explained in Relaxing Field Validation. This is due to the fact that the possible code values for these data elements rely on specifications which are external to the EDI standard itself.

 

When incomplete (or relaxed) validation of a field is not acceptable or desirable, it is possible to configure MapForce to perform full field validation. This approach requires adding custom .codelist files in addition to the default ones already available in MapForce. The role of the custom .codelist files is to supply any code values that are not defined by default in the EDI standard and consequently are not present in MapForce configuration files. This usually applies to code values that are defined in external standards or recommendations.

 

Note that the custom .codelist file will require an entry for every possible code value that is to be validated (which may be hundreds of records). An example is the Data Element 4405 of the UN/EDIFACT D16A. In addition to the code values defined in the UN/EDIFACT standard, this field also allows code values that are specified in the UN/ECE Recommendation 24 ("Trade and Transport Status Codes", see https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec24/rec24_ecetrd258e.pdf) which amount to 346 codes. In order to accommodate all these external code values, a custom .codelist file must be created which contains an entry for each of the 346 codes present in the recommendation. Therefore, if that is acceptable by your particular business case, using incomplete validation is a simpler solution (see Relaxing Field Validation). Be aware that incomplete validation involves the risk of allowing invalid data to be produced in the mapping output, so full field validation is recommended instead.

 

To perform full field validation of fields whose code values are defined in an external standard, take the following steps:

 

1.Create a copy of the default .codelist file supplied with MapForce. The .codelist files available for each EDI flavour are in the C:\Program Files\Altova\MapForce2019\MapForceEDI\ directory. For example, if adding a custom .codelist file to validate UN/EDIFACT messages, use as template the UNCL.Codelist file available in C:\Program Files\Altova\MapForce2019\MapForceEDI\EDIFACT\.

 

Note:You must have write permissions to the C:\Program Files\Altova\MapForce2019\MapForceEDI directory in order to modify its contents.

 

2.Rename the newly created .codelist file to a short and descriptive filename, since the file will be referred from other MapForce configuration files. For the scope of this example, the custom .codelist file will be called UNECE24.codelist.
3.Using an XML editor such as XMLSpy, delete from the new file all content included between the <Codelist> and </Codelist> tags. The file should now look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="5" xsi:noNamespaceSchemaLocation="../EDIConfig5.xsd">  
  <Codelist>
   

...

 
  </Codelist>
</Config>

4.Add a new <Field> structure under <Codelist>, as shown below. In this example, we assume to be adding external code values for Data Element 4405 of the UN/EDIFACT. Otherwise, replace the field attributes as required by your particular case. Remember that you can find the correct name, length and type of each field in the default .codelist file supplied by MapForce (in this example, UNCL.Codelist).

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="5" xsi:noNamespaceSchemaLocation="../EDIConfig5.xsd">  
  <Codelist>    
    <Field Name="F4405" Length="3" Type="Alphanumeric">
        <Title>Trade and transport status codes</Title>
        <Description>Code specifying a status.</Description>        
        <Values>
         

...

 
        <Values>
    </Field>
  </Codelist>
</Config>

5.Under <Values>, add a new <Value> for each external code, as shown below. In this example, we are adding the first two codes defined in the UN/ECE Recommendation 24 ("Trade and Transport Status Codes", see https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec24/rec24_ecetrd258e.pdf).

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="5" xsi:noNamespaceSchemaLocation="../EDIConfig5.xsd">  
  <Codelist>    
    <Field Name="F4405" Length="3" Type="Alphanumeric">
        <Title>Trade and transport status codes</Title>
        <Description>Code specifying a status.</Description>        
        <Values>
          <Value Code="1">
              <Title>Arrival, completed</Title>
              <Description>The goods/consignment/equipment/means of transport has arrived.</Description>
          </Value>
          <Value Code="2">
              <Title>Loading, authorized</Title>
              <Description>Authorization to load has been given.</Description>
          </Value>
        <Values>
    </Field>
  </Codelist>
</Config>

At this stage, the custom .codelist file is ready but not yet bound to MapForce. Just be aware that, for the scope of the example, we have only added two external codes ("1" and "2"); however, in a real-life scenario the custom .codelist file is expected to include all code values specified by the external standard.

 

Finally, before the custom .codelist file can be recognized by MapForce, the following must also be done:

 

1.Since now the Data Element 4405 does no longer have incomplete validation, MapForce must be instructed to apply full validation. Namely, the Incomplete="1" attribute must be modified in the UNCL.codelist file for this field (the attribute must either be removed, or set to Incomplete="0"). Therefore, modify the UNCL.codelist file as shown below:

...

 

<Field Name="F4405" Length="3" Type="Alphanumeric" Incomplete="0">
        <Title>Status description code</Title>
        <Description>Code specifying a status.</Description>
        <Note>1 For transport status, use UN/ECE Recommendation 24.</Note>

 

...

2.Modify the UNCL.codelist file to add a reference to the newly created UNECE24.codelist file, as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="5" xsi:noNamespaceSchemaLocation="../EDIConfig5.xsd">
  <Include href="UNECE24.codelist"/>
  <Codelist>

 

....

 

You have now finished adapting MapForce configuration files to validate Field 4405 from code values defined in a custom file. This approach can also be used for other EDI flavours to achieve full field validation based on some external standard.

 

Although it is possible to define external code lists by editing the existing .codelist file supplied with MapForce (in this example, UNCL.codelist), this is not recommended. A good practice is to always define external code lists in custom files and keep changes to the default MapForce configuration files to minimum; this will make it easier to migrate to new versions of EDI formats in future.

 

Note that the instructions above cause the field validation to be global, for any segment that may be using Field 4405. In some cases, you may want the custom code lists to apply only to certain messages (in other words, the configuration should not apply globally for all messages, but inline, or locally, for a particular message only). For more information about using the "inline" approach, see Defining Code Values at Message Level (Inline).


© 2019 Altova GmbH