ECS/XML Processor - Inbound 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. Integration of data derived from Inbound XML Documents requires the development of Converters and Selectors.
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 system that is being updated.
The ECS/XML Processor is responsible for performing the following actions for Inbound transactions:
Search the defined Input Folder for new XML Documents on the PC.
Validate the Inbound XML Documents and report any errors to the Event Administrator.
Translate data values according to the predefined Element Translations configured for the XML Event.
Break down the XML Document using Document Object Model (DOM) to write the data to the ECS/XML Transaction and Control Files.
The ECS/XML Processor responsibility ends once the XML element values has been written to the DB/400 Transaction file (IEXT) and the control file updated (IEXC). The Application relevant mapping program developed to select Inbound Transactions with a status of "RDY", meaning that the transaction is ready for mapping. Once mapped the status should be changed to "FIN" to indicate the data has been mapped successfully.
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 ECS/XML Transaction File contains a record for every data element contained within the Inbound XML Document.
The XML Transaction record contains the following values:
Element Value (XTVAL)
Element Value Type (Attribute Value or Element Value) (XTTYP)
List of Element Node Labels linking to the Element Value. (XTELxx)
For Example the following represents a section of a sample XML Order, this section contains three element values; "XML_Order", "2002-02-20T18:22:51+01:00" and "XML Sample Order" :
<Document>
<header>
<delivery>
<message>
<messageID>XML_Order</messageID>
<sent>2002-02-20T18:22:51+01:00</sent>
<subject>XML Sample Order</subject>
</message>
The result following the processing of this section of the sample XML document would be three records in the XML Transaction file (IEXT), one for each value:
Record 1
Field | Description | Field Value |
XTGUI | Unique Transaction Identifier | 20001231125959001 |
XTSEQ | Element Sequence Number | 1 |
XTVAL | Element Value | XML_Order |
XTTYP | Type (V= Element Value, A=Attribute Value) | V |
XTEL01 | Element Label | Document |
XTEL02 | Element Label | header |
XTEL03 | Element Label | delivery |
XTEL04 | Element Label | message |
XTEL05 | Element Label | messageID |
Record 2
Field | Description | Field Value |
XTGUI | Unique Transaction Identifier | 20001231125959001 |
XTSEQ | Element Sequence Number | 2 |
XTVAL | Element Value | 2002-02-20T18:22:51+01:00 |
XTTYP | Type (V= Element Value, A=Attribute Value) | V |
XTEL01 | Element Label | Document |
XTEL02 | Element Label | header |
XTEL03 | Element Label | delivery |
XTEL04 | Element Label | message |
XTEL05 | Element Label | sent |
Record 3
Field | Description | Field Value |
XTGUI | Unique Transaction Identifier | 20001231125959001 |
XTSEQ | Element Sequence Number | 3 |
XTVAL | Element Value | XML Sample Order |
XTTYP | Type (V= Element Value, A=Attribute Value) | V |
XTEL01 | Element Label | Document |
XTEL02 | Element Label | header |
XTEL03 | Element Label | delivery |
XTEL04 | Element Label | message |
XTEL05 | Element Label | subject |
The Element labels (XTELxx) are used to identify the value held in the Element Value field (XTVAL). For example, if you need to map the message subject to a database field called XXSUBJ then the psuedo code would look like:
IF XTEL01="Document" AND XTEL02="header" AND XTEL03="delivery" AND XTEL04="message" AND XTEL05="subject" THEN XXSUBJ=XTVAL
The ECS/XML Control File contains a record each XML Document processed. The following record layout provides an example of the information available on the ECS/XML Control File (IEXC) when receiving a sample XML Order document:
Field | Description | Field Value (sample data) |
XCGUI | Global Unique Id | 20001231125959001 |
XCDIR | Direction (I/O) | I |
XCEVT | Event Id | ABC_ORD_IN |
XCSTS | Status (RDY, FIN, ERR) | RDY |
XCTRAN | Transport Method | *BLANK |
XCSID | Sender Id | ABC |
XCRID | Receiver Id | ECS |
XCTRIP | Trigger Pgm Override | *BLANK |
XCTRIL | Trigger Pgm Override Lib | *BLANK |
XCETRP | Error Trigger Pgm Override | *BLANK |
XCETRL | Error Trigger Pgm Override Lib | *BLANK |
XCIPTH | XML Input Path | C:\XML\IN\sample_file.xml |
XCOPTH | XML Output Path | C:\XML\OUT\sample_file.xml |
XCXFIL | Output XML File name Override | *BLANK |
XCOFIL | Output File Name Override | *BLANK |
XCOGUI | Original GUID (XCGUI) | *BLANK |
XCAREF | Application Reference | *BLANK |
XCLMU | Last Maintained User | ECSie.EXE |
XCLMD | Last Maintained Date | 20001231 |
XCLMT | Last Maintained Time | 235959 |
The Converter
The Conversion program is an Inbound mapping program that is responsible for processing the transaction records for a single XML Document on each program execution. The conversion program should be developed to perform the following basic functions;
Read through the ECS/XML Transaction records (File: IEXT)
Select the required data values and populate the appropriate Business Application database.
Update the status on the ECS/XML Control file to indicate the data has been mapped. (IEXC.XCSTS from "RDY" to "FIN")
The Selector
There are two approaches to controlling the execution of Inbound conversion program:
Select the required data using a Selector program.
Configure the Conversion program as a Trigger Program within the XML Event.
The decision as to which option is best depends on the Business Application environment. If ECS/integrated email is to control the execution of the conversion programs then allowances need to made to ensure that the library list is set accordingly and the User Id configured within ECS/ie has authority to the application.
The design of the Conversion program should remain the same, whether a Selection program is used or not. A conversion program is responsible for processing the transaction records for a single XML Document.
ECS/integrated email is supplied with a sample XML integration environment with programs and documented source code demonstrating how Conversion programs and Selectors 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 Inbound Processing limits and capabilities:
Maximum number of element levels within an Inbound XML Document is 20.
<<<<< 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.