IBM WebSphere Commerce practice – UPS integration (Aaron Dai)

In particular, this blog is provided by Aaron Dai.

Perficient GDC has a team focusing on IBM WebSphere commerce development. To deliver client eCommerce solution with better user experience, the team devotes to learn technologies related to WebSphere Commerce project. As a member of it, I would like to share some experience of integrating UPS API from WebSpehre C ommerce.

How to get started?

1. Register from My UPS

Go to this site https://www.ups.com/upsdeveloperkit and register.

2. Request an access key

Login in with your account, find Request an access key in that page, and click on that link.

When requesting an access key, you will be asked to open an UPS account. It seems that the system will check your IP and shipping address, then decide whether to approval your request. That means it will a little bit difficult for us Chinese guys to request an access key successfully.

3. Download the Developer API document

There are different APIs we can get from UPS website, like Address Validation and Shipping. For the purpose of calculating shipping charge, we should use the Rating API.

Set up the sample project

UPS supply the official sample project codes. After downloading the API document, we can get them.

1. Import the code sample to IDE

Create a new java project using the existing code. The sample code should in “Rates_Pkg_Gnd/RatingPACKAGE/PACKAGEXMLTools/CodeSamples/Rate/JAXB” from Rating API which you have downloaded.

2. Prepare the JAXB environment

JAXB is part of Java Web Service Developer Pack. You need to download it from the official website and then install it. If you fail to install the pack, you need to download the necessary jar file by yourself and put them in somewhere like “C:\Sun\jwsdp-2.0\jaxb\lib” which defined as the jaxb lib home.

The jar files are: jaxb-api.jar, jaxb-impl.jar, jaxb-xjc.jar, jaxp-api.jar

3. Modify the ant build script

You need to define the UPS information, jaxb home and xsds’ location in build property file, for instants:

                accesskey=XXXXXXXXXXXXXXXXXX

                username=XXXXXXXX

                password=XXXXXXXX

                jaxb.home=C:/Sun/jwsdp-2.0/jaxb/lib

                requestxsd=C:/ups/Schemas/RateRequest.xsd

                responsexsd=C:/ups/Schemas/RateResponse.xsd

                accessrequestxsd=C:/ups/Schemas/AccessRequest.xsd

4. Generate the UPS object

The sample project will be generated by a running ant file. Run the ant build script. It will generate all the UPS objects we need.

5. Validate the sample project

Run the main method, you can find the request and response in console. And they will be written into an XML file.

 

Installing a Security Certificate for UPS

To ensure the UPS web service call works properly with WCS server, we need to install the security certificate for UPS in WCS server.

1. Start WCS serve.
2. Start Administration Console by right clicking the server and selecting “Run Administration Console” from Administration Context menu.
3. From the Administration console window, expend Security and select “SSL certificate and key management”.
4. Click on “SSL configuration”.
5. Select “NodeDefaultSSLSetting”.
6. Click on “Key stores and certificates”.
7. Select “NodeDefaultTrustStore”.
8. Click on “Signer certificates”.
9. Click on “Retrieve from port” button.
10. Fill in “wwwcie.ups.com” as host and “443” as port.
11. Click on “OK” button and save.
12. Restart the WCS server.

Glance of Calculation Framework

Now we get all the prepare works done. The next step is to integrate UPS API with WCS commands. However, before we start, let’s take primary understand of the Calculation Framework in WC project.

There are five major components to the WebSphere Commerce calculation framework:

1. Calculation methods

Calculation methods reference task commands to implement the parts of the calculation framework.

2. Calculation usages

Calculation usages are the categories of calculations that are performed using the calculation framework. These include discounts and sales tax.

3. Calculation codes

Calculation codes indicate the calculations to be performed for OrderItems.

4. Calculation rules

Calculation rules calculate the monetary amounts for the calculation codes associated with an OrderItem.

5. Calculation scales and calculation ranges

Calculation scales allow a calculation rule for determining monetary amounts in a manner that is similar to looking up a value from a table. Calculation ranges define the relationship between a look-up number and value to be located for a calculation scale.

To understand how we assign the calculated shipping charge result to an order item, we should know the general flow of calculation methods:

1. InitializeCalculationUsage

2. ApplyCalculationUsage calls:

     a. CalculationCodeCombine calls:

               CalculationCodeQualify

      b. CalculationCodeCalculate calls:

                 CalculationRuleCombine calls:

                               CalculationRuleQualify

                 CalculationRuleCalculate calls:

                              CalculationScaleLookup

                              CalculationRange

       c. CalculationCodeApply

3. SummarizeCalculationUsage

4. FinalizeCalculationUsage

We should add the shipping charge calculation logic to the CalculationCodeApply task command.

Integrate UPS API with WebSphere Commerce

Since we have known the right place to put the calculation logic, we can keep on the integration work.

1. Copy the UPS objects to WebSphereCommerceServerExtensionsLogic

2. Create a java class extending ApplyShippingCmdImpl

3. Register the command to CMDREG table

insert into cmdreg (storeent_id, interfacename, classname, target) values (10001, ‘com.ibm.commerce.order.calculation.ApplyShippingCmd’, ‘com.mycompany.commerce.command.calculation.MyCompanyApplyShippingCmdImpl’, ‘local’);

4.  Implement the code to calculate shipping charge using the ship data which retrieved from wcs

Necessary Shipping data for UPS:

• Shipper address
• Ship from address
• Ship to address
• Rating service code – to define the package delivery services.
• Package information – to define the package code, package weight and weight measure.

You can create a class like: UPSShipRateService, then implement methods like:

• populateShipRate
• getShipToAddress
• getShipFromAddress
• getShipperAddress
• getRatingService
• getPackageInfo

 

Above is the procedure to integrate UPS with WebSphere Commerce. Hope it is helpful when you intend to  integrate with UP