Preserve file names when using WebSphere DataPower B2B Appliances to exchange AS2 messages with trading partners

Content

Introduction

IBM WebSphere DataPower B2B Appliance (hereafter called DataPower B2B) has recognized great success over the past five years as IBM's second best-selling DataPower model. We have a customer base of over 100 customers with almost all of them using the AS2 standard to exchange data. The adoption of DataPower B2B in the banking industry is significant and, as a result, we have added new functionality to facilitate the AS2 Filename Preservation features option that is part of AS2 V1.2. The filename preservation capability is needed for our growing customer base in the banking industry. DataPower B2B can support this feature by using the processing policy and some new functionality added to the graphical user interface (GUI). This tutorial describes how to configure an AS2 trading relationship in DataPower B2B that supports AS2 Filename Preservation.

Overview

AS2 is a Request for Comment (RFC) standard that enables companies to securely communicate and exchange data over the Internet. The AS2 standard is one of the most widely adopted B2B messaging standards in the world with 14 vendors representing 21 products, all participating in third-party AS2 certification and interoperability testing with the Drummond Group this year. The financial industry uses AS2 every day to exchange billions of critical financial transactions between banks, government entities, retailers, manufacturers, healthcare organizations, and so on, and their trading partners.

The banking industry relies on filenames to facilitate routing of financial data to the appropriate systems inside their network and, as a result, the Financial Services Technology Consortium (FSTC) asked Drummond Group Inc. to offer filename preservation (defined in the AS2 Filename Preservation draft specification) as an optional AS2 pattern to be tested during the AS2 certification process.

This tutorial describes the steps involved to configure DataPower B2B to trade AS2 messages that preserve the original filename with your trading partners. In an effort to more effectively demonstrate this functionality, we use some pre-configured domains that represent each side of the trading relationship and import them into DataPower B2B. The PartnerHub and MyHub domains are completely configured for you to trade AS2 with the PartnerHub gateway without using filename preservation. This test configuration does not use any AS2 security so we can see the result of adding AS2 Filename Preservation to the existing inbound and outbound AS2 data flows. In the real world, customers would want to use AS2 security in production.

If you want to use AS2 Filename Preservation with your existing partner's and configuration, skip all of the prerequisites and follow the instructions in the Configure AS2 Filename Preservation section of this tutorial for each of the existing profiles and test them in a fashion consistent with your existing testing practices.

Understanding how profiles are used in DataPower B2B

Data is exchanged between two trading partners. In DataPower, these partners are either internal to the system or external to the system. For more details on partner profile management in DataPower, refer to section 7.1.1 in IBM Redbook: WebSphere DataPower B2B Appliance XB60 Revealed.

Internal Partner: The internal partner is the primary company and driving force within the hub community. This company is responsible for the purchase and construction of the hub community, including the definition of the electronic business processes transacted between them and their external partners. The Internal Partner's company is represented by a B2B Gateway Service named "MyHub".

External Partner: External partners are the companies that do business with the internal partner via the hub community. External partners must complete a configuration process to connect to the hub community. Once connected, external partners can exchange electronic business documents with the internal partner. The external partner's company is represented by a separate Application Domain named "PartnerHub", which has already been created for you on DataPower B2B.

Outbound AS2 (MyHub to PartnerHub)

In the outbound flow, we will consume a file from an FTP server and send an AS2 message to the external partner that preserves the original filename in the Content-Disposition header of the payload part of the multipart MIME message. This is done by creating and that uses a processing policy in the PartnerHub External profile in the MyHub domain. The AS2 data flow is shown in Figure 1.

Figure 1. Outbound AS2 flow

Inbound AS2 (PartnerHub to MyHub)

In the inbound flow, we will consume an AS2 message from the PartnerHub's gateway, extract the original filename from the Content-Disposition header of the payload part of the multipart MIME message, and write the file to an FTP directory. This is done by turning on the filename preservation in the AS Settings tab and using a processing policy in the MyHub internal profile in the MyHub domain. The AS2 data flow is shown in Figure 2.

Figure 2. Inbound AS2 flow

Prerequisites

The following prerequisites must be met to support the testing of the AS2 Filename Preservation feature on DataPower B2B. This tutorial assumes that DataPower B2B is installed and ready to be configured with the test environment. A real world implementation would only need to follow the instructions on how to apply the policies to the internal and external profiles.

• A desktop computer running Windows XP or above that has the following installed:
  • An FTP client and server solution. We are using FileZilla in this example, which can be downloaded from the following URL: https://fileZilla-project.org/.
  • A supported browser such as Microsoft Explorer, Firefox, or Chrome.
• Sample XML and EDI test files, XB62 export file, and filename preservation stylesheets for both inbound and outbound are copied to the desktop. They are provided in code_sample.zip file in the Download section of this tutorial:
  • AS2FNP_XB62_Export.zip
  • Myhub-PartnerHub.xml
  • PartnerHub-MyHub.edi
  • Outbound-AS2FNP.xsl
  • Inbound-AS2FNP.xsl
• DataPower B2B is installed on your network and configured with the MyHub and PartnerHub domains:
  • Be sure that DataPower B2B is at or above firmware version 6.0.0.0. If it is not at the right level, download the most current firmware from IBM Fix Central and install it on your appliance prior to proceeding.
  • Log on as an Admin.
  • Import AS2FNP_XB62_Export.zip. No security is used in this example so you can see the Content-Disposition headers in the AS2 message:
    • The internal profile destination needs to be edited to point to the FTP server being used.
    • The FTP Poller in the MyHub Gateway must be edited to point to the FTP server being used.

Installing and configuring the prerequisites

This tutorial assumes that you already have experience with configuring DataPower B2B to trade AS2 messages and have followed the instructions to download and install the prerequisite software on the desktop being used to demonstrate this feature.

Prepare the FTP server

1. Download both the FileZilla server and client from https://filezilla-project.org/ and follow the installation instructions provided with the software.
2. Create the following directory structure on the c: drive of the desktop being used for this demonstration as shown in Figure 3.

   Figure 3. FTP directory structure

3. Launch the FileZilla FTP server and configure a user to be used with the DataPower B2B MyHub connection by clicking on the user icon as shown in Figure 4.

   Figure 4. FileZilla Server user config

4. In the Users view on the General page, click the Add (1) button to add a new user. For this example, we are using XB62 (2) as the username in the Add user account box. Click OK (3).

   Figure 5. FileZilla server user view – Add account

5. In the Users view on the General Page with the XB62 user (1) highlighted, check the Password box (2) to require a password. For this example, we used datapower as the password (3).

   Figure 6. FileZilla Server user view - Password

6. In the Users view, click Shared folders (1) under the Page section, click the Add (2) button, browse to the directory location that you had set up in Step 1, and select the C:\FTP\XB62 directory. This creates the Home directory for user XB62 user (3).
7. Now check all of the permission boxes (4) on the right under the Files section to give the XB62 user full access rights to the directory and all sub-directories under it and click OK (5).

   Figure 7. FileZilla server user view – Home directory

8. Repeat Steps 1 through 7 to create a user called PARTNER, give it a password of Datapower, and point it to the home directory under C:\FTP\Partner.
9. Test your FTP server configuration by launching the FileZilla client and logging on as user XB62 with a password of datapower. You see a screen that looks like Figure 8. Logout of the server and continue to the next section.

   Figure 8. FileZilla client login – XB62 user

Copy the demonstration artifacts

Copy and unzip the artifacts in the code_sample.zip file provided with this tutorial to your temporary directory on the desktop being used for the demonstration. There are five files that are needed to complete this demonstration:

1. AS2FNP_XB62_Export.zip is the XB62 Export file that contains the test domains and config.
2. MyHub-PartnerHub.xml is the outbound payload sample.
3. PartnerHub-MyHub.edi is the inbound payload sample.
4. Inbound-AS2FNP.xsl is the stylesheet used to capture the filename from the inbound AS2 file.
5. Outbound-AS2FNP.xsl is the stylesheet used to insert the Content-Disposition header with the original filename into the AS2 message.

Prepare the DataPower B2B appliance

1. Login as Admin to your DataPower B2B appliance.
2. Import the AS2FNP_XB62_Export.zip file into DataPower B2B. This creates the MyHub and PartnerHub domains.
3. Change to the MyHub domain and edit the MyHub Internal profile's (MyCompany) FTP destination to point to the IP address of the desktop being used to demonstrate this functionality (Figure 9).

   Note: The username and password were set to the values we used in this example config and match what was set up on the FTP server being used for this demonstration. If you used your own username and passwords on your own FTP server, be sure to edit them on this screen.

   Figure 9. MyCompany – Edit FTP destination

4. Edit the MyHub B2B Gateway's FTP Poller Front-side Handler (1) IP address to point to the IP address of the desktop (2) being used to demonstrate this functionality, as shown in Figure 10.

   Figure 10. MyHub – FTP Poller config

   Note: The username and password were set to the values we used in this example config and match what was set up on the FTP server being used for this demonstration. If you used your own username and password, be sure to edit them by scrolling down in the Configure FTP Poller screen to the XML Manager field, click the ellipsis to edit the XML Manager, and scroll down to edit the User Agent. In the User Agent view, click the Basic Auth tab and edit the username and password values.

Verifying the prerequisites

This section assumes that you have already imported the DataPower B2B configuration from the prerequisites and have followed the DataPower B2B and FTP preparation instructions. The import uses no AS2 security. This allows you to see the message in a human readable format. In this section, we will test the imported configuration and FTP installation.

Outbound test

1. Be sure the FileZilla server is up and running.
2. Copy the MyHub-PartnerHub.xml file into the C:/FTP/XB62/Out directory.
3. The FTP poller on DataPower B2B will pick up the file after 10 seconds.
4. After the file is picked up, logon to DataPower B2B and changes to the MyHub domain.
5. In the left navigation bar, search for B2B (1) and select B2B Transaction Viewer (2) as shown in Figure 11.
6. Click the Show AS Only (3) filter.
7. You can see the outbound AS2 transaction was a Success (4) and a Positive MDN (5) was received.

   Figure 11. B2B viewer – Outbound flow

8. Now let's look at the headers to verify that the Content-Disposition is not set. While still in the Show AS Only view, scroll over to the Headers column and hover over the (Show Headers) text for the transaction you just sent.
9. You see that the Content-Disposition header is blank.

   Figure 12. B2B viewer – Outbound flow and header data

Inbound test

1. Be sure the FileZilla server is up and running.
2. Copy the PartnerHub-Myhub.edi file into the C:/FTP/Partner/Out directory.
3. The PartnerHubFTP poller on DataPower B2B will pick up the file after 10 seconds.
4. After the file is picked up, logon to DataPower B2B and changes to the MyHub domain.
5. In the left navigation bar, search for B2B (1) and select B2B Transaction Viewer (2) as shown in Figure 13.
6. Click the Show AS Only (3) filter.
7. You can see the outbound AS2 transaction was a Success (4) and a Positive MDN (5) was sent.

   Figure 13. B2B viewer - Inbound flow

Configuring AS2 Filename Preservation

You are now ready to add AS2 Filename Preservation to the configuration.

Add AS2 Filename Preservation to outbound messages

1. Logon to DataPower B2B as an admin and change to the MyHub domain.
2. Click the B2B Partner Profile icon to access the configured profiles.
3. Click the MyPartner profile so you can edit it.
4. In the Main tab, scroll down to the "Processing Policy" field and click the plus (+) symbol as shown in Figure 14.

   Figure 14. MyPartner Profile – Processing policy

5. You are now in the Processing Policy view. Give your policy a meaningful name, such as "AS2FNP_OUT (1)" shown in Figure 15.
6. Click the New Rule (2) button. This drops down a Match (2) action on the palette.
7. Change the Rule Direction to Client to Server (3).
8. Drag a Transform (4) action to the palette to the right of the Match action.
9. Drag a Results (5) action to the right of the Transform action.

   Figure 15. AS2FNP_OUT processing policy

10. Edit the Match action and set it to match on All. If "All" does not exist, create it and set it to "*" (asterisk) to match on everything. Click Done to close the Match action.
11. Edit the Transform action and fill it as shown in Figure 16. Note: Be sure the values for the Input and Output fields are all capitalized.

    Figure 16. AS2FNP_OUT – Transform action

12. Upload the Outbound_AS2FNP.xsl stylesheet provided with this tutorial. This takes the filename from the FTP or SFTP URI and generates a Content-Disposition header that includes the original filename. Click Done to close the Transform action.
13. Edit the Results action to look like Figure 17 and click Done to close the Results action. Note: Be sure the values for the Input and Output fields are all capitalized.

    Figure 17. AS2FNP_OUT – Results action

14. Click Apply Policy in the upper left corner and then Close Window in the upper right corner of the policy. Click Apply in the Main tab to save the changes to the profile.
15. Save the entire config by clicking on Save Config in the upper right corner of the top navigation bar.

Use AS2 Filename Preservation inbound to write files to FTP/SFTP with the original filename

1. Logon to DataPower B2B as an admin and change into the MyHub domain.
2. Click the B2B Partner Profile icon to access the configured profiles.
3. Click the MyCompany profile so you can edit it.
4. In the Main tab, scroll down to the Processing Policy field and click the plus (+) symbol as shown in Figure 18.

   Figure 18. MyCompany processing policy

5. You are now in the Processing Policy view. Give your policy a meaningful name, such as "AS2FNP_IN (1)" shown in Figure 19.
6. Click  New Rule (2) button. This drops down a Match (2) action on the palette.
7. Change the Rule Direction to Client to Server (3).
8. Drag a Transform (4) action to the palette to the right of the Match action.
9. Drag a Results (5) action to the right of the Transform action.

   Figure 19. AS2FNP_IN processing policy

10. Edit the Match action and set it to match on All. If "All" does not exist, create it and set it to "*" (asterisk) to match on everything. Click Done to close the Match action.
11. Edit the Transform action and fill it in as shown in Figure 20. Note: Be sure the values for the Input and Output fields are all capitalized.

    Figure 20. AS2FNP_IN – Transform action

12. Upload the Inbound_AS2FNP.xsl stylesheet provided with this tutorial. This takes the filename from the Content-Disposition header and writes the file out with the original filename. Click Done to close the Transform action.
13. Edit the Results action to look like Figure 21 and click Done to close the Results action. Note: Be sure the values for the Input and Output fields are all capitalized.

    Figure 21. AS2FNP_IN – Results action

14. Click Apply Policy in the upper left corner and then Close Window in the upper right corner of the policy. Click Apply in the Main tab to save the changes to the profile.
15. Save the entire config by clicking on Save Config in the upper right corner of the top navigation bar.
16. By default, the B2B Gateway does not preserve the Content-Disposition header of the payload when unpackaging the AS2 messages. The policy needs this header value to be used as input to the processing policy. To enable the header to be preserved, click the AS Setting tab and check the Preserve Filename box in the "Advanced Settings" section of the screen as shown in Figure 22.
17. Click Apply in the top left of the screen and then click Save Config to save the changes.

    Figure 22. MyCompany AS Settings – Preserve filename

Testing AS2 Filename Preservation

In the previous section, you added the filename preservation to both the inbound and outbound flows. In this section, you will test both inbound and outbound data flows to verify that you are adding the filename to the outbound AS2 message as well consuming the filename from the Content-Disposition header from the inbound AS2 message. You will test in the same manner as you did in the Verify the prerequisites section of this tutorial.

Outbound testing

1. Be sure the FileZilla server is up and running.
2. Copy the MyHub-PartnerHub.xml file into the C:/FTP/XB62/Out directory.
3. The FTP poller on DataPower B2B will pick up the file after 10 seconds.
4. After the file is picked up, logon to DataPower B2B and changes to the MyHub domain.
5. In the left navigation bar, search for "B2B" and select B2B Transaction Viewer.
6. Click the Show AS Only (1) filter as shown in Figure 23.
7. You can see the outbound AS2 transaction was a Success (2) and a Positive MDN (3) was received.

   Figure 23. B2B Viewer – Outbound flow with AS2 FNP

8. Now let's look at the headers to verify that the Content-Disposition is set. While still in the Show AS Only view, scroll over to the Headers column and hover over the Show Headers (4) text for the transaction you just sent.
9. You see that the Content-Disposition header now shows the filename of the original file you picked up from the FTP directory (Figure 24).

   Figure 24. Viewer Outbound Flow – Show headers

Inbound testing

1. Be sure the FileZilla server is up and running.
2. Copy the PartnerHub-Myhub.edi file that is provided in the code_sample.zip file with this tutorial into the C:/FTP/Partner/Out directory.
3. The PartnerHubFTP poller on DataPower B2B will pick up the file after 10 seconds.
4. After the file is picked up, logon to DataPower B2B and changes to the MyHub domain.
5. In the left navigation bar, search for "B2B" and select B2B Transaction Viewer.
6. Click the Show AS Only (1) filter as shown in Figure 25.
7. You can see the inbound AS2 transaction was a Success (2) and a Positive MDN (3) was sent.

   Figure 25. Viewer inbound flow - AS2 FNP

8. Now let's look at the headers to verify that the Content-Disposition is set. While still in the Show AS Only view, scroll over to the Headers column and hover over the Show Headers (4) text for the transaction you just received.
9. You see that the Content-Disposition header now shows the filename of the original file you received from the trading partner (Figure 26).

   Figure 26. Viewer inbound flow – Show headers

10. You can also verify that the correct filename was used by looking in the MyHub's FTP directory, C:\FTP\XB62\In, as illustrated in Figure 27.

    Figure 27. FTP directory – Inbound file

    Note: If you want the original filename to be used, but you also require uniqueness generated by the DataPower B2B Gateway, you can accomplish this by editing the MyCompany Internal Profile, clicking on the Destination tab, editing the FTP destination, and checking the Use Unique File Names box.

Conclusion

In completing this tutorial, you learned how to use DataPower's robust processing policy functionality to extend your AS2 deployment to support the AS2 Filename Preservation feature. Using this feature provides you with the benefit of being interoperable with any organization that needs to preserve the original filename to trigger internal business processes, making it easier and faster to connect to your trading partners.