ECS/XML Processor - Outbound Application Integration

ECS/integrated email and the ECS/XML Processor can be integrated to any AS/400 based Business Application with the use of XML Mapping programs. The creation of XML Documents containing data derived from AS/400 based Business Applications requires the development of Generators, to map the data from the business application database to the ECS/XML Transaction and control files (IEXC & IEXT). 

The development of XML Mapping programs is a technical task. Before commencing development please ensure that you have the necessary AS/400 authority to create the required objects and that you are technically able. Developing XML Mapping definitions requires a good understanding of the AS/400, DB/400, PDM, RPG, Query, some knowledge of XML and the Business Application you are extracting data from.

The ECS/XML Processor is responsible for performing the following actions for Outbound transactions: 

• Read through the ECS/XML Control file selecting transactions ready for Generating to XML Documents. 

• Linking the Transaction Control record to retrieve the XML Event definition.  

• Build the XML Document, in three stages; 

  • Header Text

  • Body Text 

  • Footer Text

• Parse (validate) the Outbound XML Document and report any errors to the Event Administrator.

• Translate data values according to the predefined Element Translations configured for the XML Event.

• Copy the Outbound XML Document to the Output Folder defined within the XML Event.

The ECS/XML Processor expects the Transaction and Control records to have been created by an external user developed Generation program. The Generation program is closely linked to the Business Application and should be designed/developed according to the Business Application & XML Document requirements.

The Generator

The XML Generation program is an Outbound  mapping program that is responsible for extracting the required details from the Business Application to create the ECS/XML Transaction and Control records. A Generator is executed once for every XML Document required. The Generator is called by the Selector.

The Generator should be designed and developed to perform the following

• Use Unique Business Application Transaction reference, passed to the Generator by the Selector,  to retrieve required data from the Business Application

• Map the required data contents from the Business Application database to the ECS/XML Transaction detail file (IEXT).  

• Write an ECS/XML Control record to indicate the data has been mapped.

• Update the Business Application system to indicate that the data has been mapped.

The Selector 

The role of the Selection program is required for the creation of Outbound XML Documents. The Selector is responsible for reading through the Business Application Header file, selecting unprocessed records for which Outbound XML Documents should be created for. 

A Selector is normally linked to a business transaction (such as Purchase Orders). A Selector is responsible for executing the relevant Generation Programs passing to it the Unique Transaction Id as a Parameter.

A Selector can be designed to execute multiple Generators, if for example, multiple XML Document formats must be supported for the same business transaction.

Developing Generators

The structure of a typical XML document can be broken down into three primary sections, Header, Body and Footer. The Header and Footer sections normally contains static information which rarely  varies between individual transactions. The Body section normally contains more volatile information relating to the individual business transaction. 

The XML Header and Footer  sections can be configured within ECS/integrated email as optional configuration to assist in the development of Outbound mapping programs. This aids development by allowing the configuration of the static information within ECS/integrating email, meaning that the Business Application based mapping program need only map the Body section of the XML Document.

The  following example demonstrates how this principle works with a sample XML Order:

<?xml version ="1.0"?>
<!-- ECS/XML -->
        <Document>
                <header>
                        <delivery>
                                <message>
                                        <messageID>XML_Order</messageID>
                                        <sent>2002-02-20T18:22:51+01:00</sent>
                                        <subject>XML Sample Order</subject>
                                </message>
                                <to>

                                        <address>customer.services@xyz.com</address>

                                </to>
                                <from>

                                        <address>purchasing@ecs-europe.com</address>

                               </from>
                        </delivery>

                </header>

<body>
        <Order>

                <OrderHead>

                        <OrderType>Purchase Order</OrderType>
                         <OrderCurrency>

                                <Currency Code="EUR">Euro</Currency>
                        </OrderCurrency>
                </OrderHead>
                <OrderReferences>

                        <BuyersOrderNumber>181853</BuyersOrderNumber>
                </OrderReferences>
                <OrderDate>2002-02-20</OrderDate>
                <Supplier>

                       <Party>XYZ Supplies Ltd</Party>
                        <Address>

                               <AddressLine>Alphabet House</AddressLine>
                                <AddressLine>1 The Loop</AddressLine>
                                <City>Birmingham</City>
                                <State>Midlands</State>
                                <PostCode>B19 1DS</PostCode>
                       </Address>
                </Supplier>
                <Buyer>

                       <Party>ECS Limited</Party>
                        <Address>

                               <AddressLine>Commerce House</AddressLine>
                                <AddressLine>London Road</AddressLine>
                                <City>Horsham</City>
                                <State>West Sussex</State>
                                <PostCode>RH13 9WJ</PostCode>
                        </Address>
                </Buyer>
                <OrderLine>

                       <LineNumber>1</LineNumber>
                        <Quantity>

                                <Amount>3</Amount>
                        </Quantity>
                        <Product>

                               <ItemCode>PEN</ItemCode>
                        </Product>
                </OrderLine>
                <OrderLine>

                       <LineNumber>2</LineNumber>
                        <Quantity>

                                <Amount>6</Amount>
                        </Quantity>
                        <Product>

                                <ItemCode>INK</ItemCode>
                        </Product>
                </OrderLine>
            </Order>
        </body>
</Document>

• The RED section represents the Header text which can be configured within the XML Event Header Maintenance.  

• The BLUE section represents the XML Document Body text which is generated by a user developed Business Application specific mapping program. .  

• The GREEN section represents the Footer text which can be configured within the XML Event Footer Maintenance.  

The configuration of XML Event Header and Footer is optional. This information can be written with the same user developed Business Application Mapping program that writes the Body text, if preferred. 

The Header and Footer can contain specific volatile information, such as Date, Time and retrieve certain key values from the ECS/XML Processor Control file. The insertion of these values is controlled by using special values which will be automatically replaced by the ECS/XML Processor when the XML document is generated. See the section on maintaining Header and Footer Text for more information. 

Each Generator should be designed to only map the required "Body" section of the XML Document. It is important when designing Generation programs that the mapped section must originate from a single root. In the example shown above the entire Blue section is wrapped within the "Order" Label. Note that <Order> is the first element within the Body Section and </Order> is the last element label within the Body section.

The point of application integration with the ECS/XML Processor is with two DB/400 physical files: 

• IEXC  - ECS/XML Transaction Control

• IEXT  - ECS/XML Transaction Detail file

User defined mapping programs, shown in the following diagram in yellow, are required to integrate the ECS/XML Processor Transaction and Control Files with your Business Application System: 

The Generation program must write one record to the ECS/XML Transaction file for each data element required in the Outbound XML Document. The Element Labels and Tree structure of the XML Document must also be written to the Transaction file: 

The following defines the mapping requirements for Outbound XML Documents: 

File: IEXT, ECS/XML Transaction detail file - Map one record for every data value.

Required: M=Mandatory, O=Optional

File: IEXC, ECS/XML Control file - Map one record for every XML Document required.

Required: M=Mandatory, O=Optional

For Example the following represents a section of a sample XML Order, this section contains two element values and one Attribute Value; "Purchase Order", "EUR"  and "Euro"  : 

        <Order>

                <OrderHead>

                        <OrderType>Purchase Order</OrderType>
                         <OrderCurrency>

                                <Currency Code="EUR">Euro</Currency>
                        </OrderCurrency>
                </OrderHead>

The example section only actually represents two elements containing data. 

An example of the ECS/XML Transaction and Control records required to create the section of XML Document shown would look like: 

File: IEXT, ECS/XML Transaction detail file - Record 1

File: IEXT,  Record 2

File: IEXC, ECS/XML Control file - Map one record for every XML Document required.

Support for Elements with Blank Values

The ECS/XML Processor will ignore records where the fields IEXT.XTVAL, XTATV, XTATV2, XTATV3, XTATV4 and XTATV5 all contain blanks. If you have a requirement to write an XML Element with a Blank value then special value &BLANK can be used in IEXT.XTVAL. The &BLANK will be automatically replaced with a blank space by the XML Processor.

Forcing the occurrence of a new Group

There are times when you may need to force the end of a Group and the start of a new identical Group. The ECS/XML Processor will detect new Groups and automatically insert the end tags and start tags unless the Groups have exactly the same Tags. Following Example demonstrates where this may be used: 

<REFERENCE REFTYPE="CUR">

                <REFDESC>Customers Reference Number</REFDESC>

                <REFCODE>112288785</REFCODE>

</REFERENCE>

<REFERENCE REFTYPE="CON">

                <REFDESC>Contact</REFDESC>

                <REFCODE>Fred Smith</REFCODE>

</REFERENCE>

The REFERENCE Element Group is defined twice, but in normal circumstances the ECS/XML Processor will attempt to logically group all the elements contained within both REFERENCE elements into one single group, which in this instance would be logically incorrect. The following record definitions demonstrates how the XML Transaction file (IEXT) should be populated to result in the creation of these XML statements and more importantly how the instruction to force a new Group is defined:

File: IEXT, ECS/XML Transaction detail file - Record 1

File: IEXT,  Record 2

 File: IEXT,  Record 3

 File: IEXT,  Record 4

File: IEXT,  Record 5

File: IEXT,  Record 6

 File: IEXT,  Record 7

In this example, the fourth record is responsible for forcing the closure of the first group and the occurrence of the second group. This blank record resets the XML Processor back to the previous element group (Order).  The special value &BLANK is used because a value is not required to be written to this element.

This same logic should also be implemented for writing multiple detail records, such as Order Lines or Address information. 

ECS/XML Processor Sample Application

ECS/integrated email is supplied with a sample XML integration environment with programs and documented source code demonstrating how Generation programs are built,  these can be used as templates and adapted to suit the requirements of your XML Documents and Business Application.

 Click here for more information on using the XML Sample Application and Mapping Programs.

ECS/XML Outbound Processing limits and capabilities: 

• Maximum number of element levels within the Body section of an Outbound XML Document is 20.

• Maximum number of Attributes and Attribute values per Element is 5.

<<<<< Back to ECS/XML Menu <<<<< 

Copyright © 1998-2003 Electronic Commerce Solutions All rights reserved.

ECS/integrated email & ECS/ie are trademarks of Electronic Commerce Solutions, Ltd. Other brand names and product names used in this document are the trademarks and trade names of their respective holders and may be registered.