In "Check EDI compliance with WebSphere DataPower, Part 1", you installed and configured the environment to use the WebSphere Transformation Extender Compliance Check framework with WebSphere DataPower. The Compliance Check framework generates acknowledgements that are partner-neutral. For example, the acknowledgements:
- Use the delimiters from the inbound document
- Set the ISA and ST control numbers to 1
- Start the FG control numbers at 1 and increment them by 1
This article builds upon that context by showing you how to enrich the generic acknowledgements. Acknowledgements from the Compliance Check framework are the input to the custom Acknowledgement Processing Multi-Protocol Gateway that is provided with this article (see Downloads). The gateway invokes a DataPower policy that uses XSL stylesheets and WebSphere Transformation Extender maps to update the ISA and IEA control numbers in the acknowledgements.
You can customize the procedures and artifacts that this article provides to generate acknowledgements that conform to the implementation guidelines of your own trading partners.
Verifying the prerequisites
This article assumes that you read and followed the procedure described in "Check EDI compliance with WebSphere DataPower, Part 1: Artifacts and procedures to get you started."
Ensure that your installation meets the requirements of both products.
WebSphere Transformation Extender:
- WebSphere Transformation Extender Design Studio, V22.214.171.124 or later
- WebSphere Transformation Extender Pack for EDI (X12 or EDIFACT), V126.96.36.199 or later
- DataPower Models XI50, XI52, XB60, or XB62
- DataPower firmware Level V5.0 or later
- WebSphere DataPower export file that is supplied with this article (see Downloads)
- Approximately 1 MB of free space on the DataPower appliance for maps and stylesheets
You also need create access to a DataPower-compatible database.
This article includes a sample-code file that contains two files (see Downloads):
- Eclipse Project Interchange file
This file contains the WebSphere Transformation Extender Design Studio artifacts for the maps that are used in the policy rule.
- Acknowledgement Processing Multi-Protocol Gateway
This file contains the sample gateway and related objects to import onto the DataPower appliance.
Overview of the sample-code process
In the sample-code process, the Compliance Check framework routes the X12 acknowledgement to the Acknowledgement Processing Multi-Protocol Gateway by using the HTTP protocol. (A WebSphere MQ queue can also be used.) The Front Side Handler associated with the gateway triggers a DataPower policy rule to process the incoming request. The first policy-rule action executes a binary-transform action that uses a custom WebSphere Transformation Extender map. The map parses the input by using an X12 acknowledgement type tree (X12_ISAPartner.xsd) that is included with the WebSphere Transformation Extender Pack for EDI. The map transforms the ISA segment of the acknowledgement into XML. For output, the map uses a custom schema that has an XML element for each field in the ISA segment.
When the map completes processing, a standard XSL-transform action serializes the binary output and converts it to XML format. The next transform action uses an XSL stylesheet and XPATH to extract the partner identifier and store it in a local variable. Using the partner identifier as input, a stored procedure selects the correct partner row in the database to retrieve the next available control number. The stored procedure increments the stored control number for the next acknowledgement. The XSL stylesheet updates the XML representation of the ISA segment with the control number retrieved from the database.
The next policy action is a binary-transform action that references a map with two input streams. One input is the original X12 acknowledgement. The other input is the XML representation of the ISA segment that has been augmented with a unique control number for this partner. The output is the partner-specific acknowledgement that contains an updated control number in the ISA and IEA segments.
Figure 1. Processing overview
In the sample code, the DataPower appliance returns the acknowledgement directly to
the requestor. A system variable (
var://service/mpgw/skip-backside) is set to skip any back-side
The topics that follow explain how to install, configure, and test the sample code.
Setting up the DataPower appliance
You import the sample-code file to the DataPower appliance to install the Acknowledgement Processing Multi-Protocol Gateway. Optionally, you can configure the gateway to use a different port.
Importing the DataPower sample-code file
To install the sample-code file onto the DataPower device:
- Copy the datapower-mpg-edi.zip sample-code compressed file to a directory in your local workstation. (See Downloads). Do not uncompress this file. It is in the required format to import into the DataPower appliance.
- Log into the DataPower appliance.
- Create a new domain to contain the Acknowledgement Processing Multi-Protocol
Gateway. For the purpose of this example, use the name
X12_ACK_Processingas your domain name. Do not load the sample-code objects into the default domain.
- Switch to the newly created domain.
- Go to Administration > Configuration > Import Configuration.
- Click Choose File to locate the DataPower sample-code .zip file on your local workstation.
- Click Next and then click Import.
The import process automatically creates the required objects and their dependencies.
Configuring the Front Side Handler to use an alternative port (optional)
The Front Side Handler in the sample code is configured to use port 43070.
- When port 43070 is not in use, the Op-State of the Acknowledgement Processing Multi-Protocol Gateway is set to 'up,' and you can continue by importing the sample code into Design Studio.
- If port 43070 is in use, use the following steps to change to an available port number.
To configure the Front Side Handler to use another port:
- On the DataPower appliance, go to Services > Multi-Protocol Gateway > Edit Multi-Protocol Gateway.
- Click on the gateway name to open it.
- Click and edit the Front Side Protocol X12_Compliance_using_HTTP_FSH and change the Port Number value to an available port number.
- If you made any changes to the Front Side Handler or the Acknowledgement Processing Multi-Protocol Gateway, remember to click Apply and save the domain configuration before you proceed.
- Go to Services > Multi-Protocol Gateway > Multi-Protocol Gateway and verify that the Op-state of the Acknowledgement Processing Multi-Protocol Gateway is 'up.'
Now you have set up the acknowledgement processing objects in the DataPower device. In the next step, you configure Design Studio to connect to the DataPower appliance so you can build and deploy the WebSphere Transformation Extender maps.
Importing the sample code into Design Studio
These steps import a map source file that contains two maps and the XML schema that the maps reference. The import process copies the appropriate files into the Map Source folder and the Schema folder in your Design Studio project.
To import the sample code for Design Studio:
- In Windows Explorer, extract the WebSphere Transformation Extender wtx-dp-partner.zip sample-code file to an empty directory.
- In Design Studio, right-click your project name and click Import > File System.
- In the Import dialog, browse to the directory where you extracted the map source file and the XML schema file.
- Hold the Ctrl key, select the two files, and click Import.
The EDI-to-XML map transforms the ISA segment of the acknowledgement into an XML document. Each ISA segment element maps to a custom XML field element.
Figure 2. EDI-to-XML mapping rules
The XML-to-EDI map uses two input cards to transform the generic EDI acknowledgement into a partner-specific acknowledgement. The cards are named XML_ISA and EDI_997. The input to the XML_ISA card is the generic acknowledgement. The input to the EDI_997 card is the XML representation of the ISA segment, augmented with partner-specific information. The XML_ISA card maps to the ISA Segment in the output card, and the EDI_997 card maps to the 997 functional group object in the output card. The map output is a partner-specific acknowledgement.
Figure 3. XML-to-EDI mapping rules
Building and deploying the maps
The MapRuntime setting of the sample maps is set to WebSphere DataPower, so the maps are ready to build.
To build the maps:
- In the Design Studio Composition view or Outline view, expand the FA_997_ISA map source file to display the maps.
- Right-click on each map and select Build.
You now deploy the built maps to the local store of the DataPower appliance:
Because the maps are directly referenced by a binary-transform action in the policy
rule, it is important to upload them to the correct location. You can open a new
view to monitor the deployment progress.
To deploy the maps:
- Click Window > Show View > Progress to open the Progress view.
- In the Composition view or Outline view, right-click the first map and click Deploy to DataPower.
- Accept the device certificate, if prompted.
The Progress view displays a completion message when the map file is uploaded or deployed to the DataPower appliance.
- Deploy the second map to the DataPower appliance as described in step 2.
Setting up the database
You store partner control numbers in a DataPower-compatible database. The following procedures set up your database to work with the sample code. The procedures:
- Create the database table to store the partner identifiers
- Create the stored procedure to retrieve and store the partner identifiers
- Configure the SQL source object to connect to the database
Creating the sample database table
The sample code uses a simple table that has a single row for each partner. Each row has two fields: the partner identifier and the next available control number.
To create a table that tests the sample code:
- Create a table and name it
- Create two columns:
- A text column named
- An integer column named
- A text column named
- Use your database program editor to create two rows with the following information:
Table 1. PartnerControl sample data table
- Commit your changes to store them in the database table.
Creating the stored procedure
To use the sample, you must create a stored procedure that is compatible with your database. The stored procedure increments the interchange control number by retrieving the next available control number from the database table, incrementing it by 1, and storing it back into the table.
To create the stored procedure:
- Create a stored procedure named
Sproc_CTRL_Lookup_and_Incr. This name is required by the XSL stylesheet that is included with the sample code.
- Name the input field
PARTNERIDINand the output field
- The stored procedure must have the same functionality as shown in the code
- Use the partner ID to select the interchange control number.
- Increment the control number by 1.
- Use the partner ID to store the control number in the database table.
Each database has different syntax requirements. Listing 1 shows a sample stored procedure. Note that the CREATE command is a single command line that is wrapped to accommodate the width of the example.
Listing 1. Sample SQL stored procedure
CREATE PROCEDURE Sproc_CTRL_Lookup_and_Incr (INPARTNERIDIN CHARACTER(15), OUT CONTROLNUM INTEGER ) DYNAMIC RESULT SETS 1 ------------------------------------------------------------------------ -- SQL Stored Procedure ------------------------------------------------------------------------ P1: BEGIN DECLARE CURSOR1 CURSOR WITH RETURN FOR SELECT INTERCHANGECONTROLNUM FROM PARTNERCONTROL WHERE PARTNERID = PARTNERIDIN; UPDATE PARTNERCONTROL SET INTERCHANGECONTROLNUM = INTERCHANGECONTROLNUM + 1 WHERE PARTNERID = PARTNERIDIN; -- Cursor left open for client application OPEN CURSOR1; RETURN CONTROLNUM; END P1 -------------------------------
Note: This stored procedure is not thread-safe. Potentially, two processes can get the same control number. If a second process accesses the database before the first process updates and commits the control number, both processes get the same control number. You are responsible for the thread safety of your stored procedure.
Connecting to the database
The SQL source object establishes connectivity between the DataPower appliance and the compatible database where you keep your partner control numbers. The steps below apply to an IBM DB2® database. See your DataPower documentation for details about how to configure the base SQL data source for other databases. (See Resources.)
- In the Control Panel Navigator field, enter
- Select SQL Source Object.
- Click on the PartnerDataSource SQL source object that is installed by the sample code.
- In the Configure SQL Data Source window, enter the following information:
- Database Type
- Your database type
- Connection User Name
- Your database security name
- Connection Password
- Your database security password
- Data Source ID
- The name of your database (not the table name)
- Data Source Host
- The host name for your database
- Data Source Port
- The port number that your database server listens on
- Click Apply to save your changes.
Incrementing the control number
The policy rule uses an XSL stylesheet in a transform action to increment the control number. The transform action uses the output of the EDI-to-XML map as input. It extracts the partner identifier and stores it in a local variable. A stored procedure retrieves the next available control number. The XSL stylesheet traverses the XML document to update the partner control number element with the control number retrieved from the database.
In the code segment shown in Listing 2:
- An XPATH extracts the ISA_08 field and stores it in the $PartnerID variable.
- The Sproc_CTRL_Lookup_and_Incr stored procedure is called using the $PartnerID variable as input.
- The output from the stored procedure is stored in the variable $SQLResults.
Listing 2. XSL fragment illustrating steps 1 - 3
<xsl:variable name="PartnerID" select="//ISA08_InterchangeRcvrID/text()" /> <xsl:variable name="SearchStmt" select="'CALL Sproc_CTRL_Lookup_and_Incr(?,?)'" /> <xsl:variable name="SQLResults"> <dp:sql-execute source="'PartnerDataSource'" statement="$SearchStmt"> <arguments> <argument type="SQL_CHAR" mode="INPUT"> <xsl:copy-of select="$PartnerID" /> </argument> <argument type="SQL_INTEGER" mode="OUTPUT" /> </arguments> </dp:sql-execute> </xsl:variable>
- An XPATH extracts the value that the stored procedure returns and stores it in the $newValue variable. A replacement ISA13_InterchangeCtrlNo element is created to contain the $newValue variable.
Listing 3. XSL fragment illustrating step 4
<xsl:variable name="newValue" select="$SQLResults/sql/resultSet/row/column/value/text()" /> <xsl:element name="ISA13_InterchangeCtrlNo"> <xsl:value-of select="$newValue" /> </xsl:element>
Testing the Acknowledgement Processing Multi-Protocol Gateway
Now you are ready to test the Acknowledgement Processing Multi-Protocol Gateway. You can use the cURL HTTP test tool to send a sample acknowledgement to the gateway (see Resources). The gateway returns the acknowledgement, augmented with a control number in the ISA segment and the IEA segment. Every time you send the acknowledgement, the control number increases by 1.
To use the cURL utility to send a sample X12 acknowledgement to the Acknowledgement Processing Multi-Protocol Gateway, enter the following command:
curl -–data-binary @compliance_check.tst
http://mydatapower.mydomain.com:43070 -X POST
where mydatapower.mydomain.com is the fully qualified host name, and 43070 is the port number of the Front Side Handler. Change the port number if you modified the Front Side Handler port number.
Note that there are two dashes before the
and one dash after.
Figure 4 displays the generic acknowledgement that arrives from the Compliance Check framework. The acknowledgement does not contain a partner-specific control number.
Figure 4. Generic acknowledgement from the Compliance Check framework
Figure 5 displays the acknowledgement after it is processed by the Acknowledgement Processing Multi-Protocol Gateway. Notice that the ISA and IEA control numbers are set to 11. These control numbers increment with each acknowledgement that passes through the gateway.
Figure 5. Enriched acknowledgement after gateway processing
This installment shows you the basics of how to enhance a generic acknowledgement to comply with partner-specific rules. You learned how to use a DataPower policy and WebSphere Transformation Extender maps to parse a document and transform a segment to XML. You created a stored procedure that retrieves, updates, and stores partner variables in a database. And you saw how a map can merge a generic acknowledgement with an updated variable to generate a partner-specific acknowledgement.
Now you can expand on the examples and procedures in this article to create acknowledgements that adhere to the rules of your own trading partners.
|Design Studio artifacts||wtx-dp-partner.zip||3KB|
- "Check EDI compliance with WebSphere DataPower, Part 1: Artifacts and procedures to get you started" (developerWorks, Aug 2012) gets you started with compliance checking on DataPower appliances and sets up the environment used in this article.
- WebSphere DataPower, Version 5 information center: Find information about the appliances in the DataPower SOA Appliances product family.
- WebSphere Transformation Extender information center: Read reference information for WebSphere Transformation Extender and related product components.
- Read the EDI Compliance Checking documentation that
is installed by the Pack in
WTX_install_dir/docs/en/edi/1155.pdf, or the latest documentation on the web.
- Browse for similar articles and resources in the developerWorks®Commerce zone.
- Stay current with developerWorks technical events and webcasts that focus on a variety of IBM products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools as well as IT industry trends.
- Follow developerWorks on Twitter.
- Watch developerWorks on-demand demos ranging from product installation and setup demos for beginners, to advanced functionality for experienced developers.
Get products and technologies
- Download the cURL tool.
- Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.
- Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.