Check EDI compliance with WebSphere DataPower, Part 2: Generate partner-specific acknowledgements

Extend the DataPower policy to enrich acknowledgements

In the second installment of this series, learn how to use a WebSphere® DataPower® policy and WebSphere Transformation Extender maps to generate partner-specific EDI acknowledgements. You use the environment that you configured in the first installment and new sample artifacts, examples, and procedures to enrich generic acknowledgements. You can customize these enrichment techniques to generate acknowledgements that conform to the rules of your own trading partners.

Share:

Charlie Sumner (csumner@us.ibm.com), WebSphere Consultant, IBM

Photo of Charlie SumnerCharlie Sumner is a Websphere pre-sales consultant based in Boca Raton, Florida. Charlie began his career with IBM on mainframe systems but quickly switched to personal and mid-sized systems and spent the majority of his career as a developer in Speech Recognition systems. He currently focuses his consulting work on WebSphere Transformation Extender and its integration with other WebSphere products.



Lori Napoli (lanapoli@us.ibm.com), Certified IT Specialist, IBM

Photo of Lori Napoli Lori Napoli is a Certified IT Specialist at IBM. She is a consultant in Software Services for WebSphere and has more than 20 years of experience with enterprise application software and middleware development. As a consultant, she has played key roles in the architecture, development and testing of Service Oriented Architecture (SOA) and Business Process Management (BPM) projects. You can reach Lori at lanapoli@us.ibm.com



21 November 2012

Overview

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, V8.4.0.2 or later
  • WebSphere Transformation Extender Pack for EDI (X12 or EDIFACT), V2.8.0.1 or later

WebSphere DataPower:

  • 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
Diagram of the partner-specific processing flow.

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

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:

  1. 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.
  2. Log into the DataPower appliance.
  3. Create a new domain to contain the Acknowledgement Processing Multi-Protocol Gateway. For the purpose of this example, use the name X12_ACK_Processing as your domain name. Do not load the sample-code objects into the default domain.
  4. Switch to the newly created domain.
  5. Go to Administration > Configuration > Import Configuration.
  6. Click Choose File to locate the DataPower sample-code .zip file on your local workstation.
  7. 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:

  1. On the DataPower appliance, go to Services > Multi-Protocol Gateway > Edit Multi-Protocol Gateway.
  2. Click on the gateway name to open it.
  3. Click and edit the Front Side Protocol X12_Compliance_using_HTTP_FSH and change the Port Number value to an available port number.
  4. 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.
  5. 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:

  1. In Windows Explorer, extract the WebSphere Transformation Extender wtx-dp-partner.zip sample-code file to an empty directory.
  2. In Design Studio, right-click your project name and click Import > File System.
  3. In the Import dialog, browse to the directory where you extracted the map source file and the XML schema file.
  4. Hold the Ctrl key, select the two files, and click Import.

EDI-to-XML map

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
Screen capture of the EDI-to-XML map

XML-to-EDI map

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
Screen capture showing how the two input cards map to the output card

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:

  1. In the Design Studio Composition view or Outline view, expand the FA_997_ISA map source file to display the maps.
  2. Right-click on each map and select Build.

You now deploy the built maps to the local store of the DataPower appliance: local:///compliance/mapsandschemas/map_name. 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:

  1. Click Window > Show View > Progress to open the Progress view.
  2. In the Composition view or Outline view, right-click the first map and click Deploy to DataPower.
  3. 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.

  4. 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:

  1. Create a table and name it PartnerControl.
  2. Create two columns:
    • A text column named PARTNERID
    • An integer column named INTERCHANGECONTROLNUM
  3. Use your database program editor to create two rows with the following information:
Table 1. PartnerControl sample data table
PARTNERIDINTERCHANGECONTROLNUM
MYBESTPARTNER10
MYOTHERPARTNER50
  1. 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:

  1. 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.
  2. Name the input field PARTNERIDIN and the output field CONTROLNUM.
  3. The stored procedure must have the same functionality as shown in the code listing:
    1. Use the partner ID to select the interchange control number.
    2. Increment the control number by 1.
    3. 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.)

  1. In the Control Panel Navigator field, enter SQL Source.
  2. Select SQL Source Object.
  3. Click on the PartnerDataSource SQL source object that is installed by the sample code.
  4. 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
  5. 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:

  1. An XPATH extracts the ISA_08 field and stores it in the $PartnerID variable.
  2. The Sproc_CTRL_Lookup_and_Incr stored procedure is called using the $PartnerID variable as input.
  3. 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>
  1. 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 data parameter, 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
Screen capture of a generic acknowledgement with ISA and IEA control numbers set to 1.

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
Screen capture of an enriched acknowledgement with ISA and IEA control numbers set to 11.

Conclusion

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.


Downloads

DescriptionNameSize
Design Studio artifactswtx-dp-partner.zip3KB
DataPower artifactsdatapower-mpg-edi.zip514KB

Resources

Learn

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.

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Commerce on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Commerce, Industries
ArticleID=846622
ArticleTitle=Check EDI compliance with WebSphere DataPower, Part 2: Generate partner-specific acknowledgements
publish-date=11212012