CSOS WebTrader

The previous topics explain CSOS functionality as incorporated into Interchange. There is another, lightweight way to move CSOS orders. That is by using WebTrader.

WebTrader is a way to move documents between a partner equipped only with a computer, a browser and an Internet connection and a partner who uses Interchange.

In a CSOS context, WebTrader has a specific role. That is to digitally sign purchase orders with the browser user’s certificate, in compliance with federal regulations. This is performed as one step in an interactive pharmaceutical ordering process. Much of this process can take place outside of WebTrader. WebTrader only comes into play in the step where signing is required.

The following outlines such a scenario. In this example, a retail pharmacy plays the role of WebTrader. A pharmaceutical distribution company is the partner who uses Interchange as its B2B gateway and is the WebTrader sponsor.

1. Using a browser, the pharmacy logs onto the distribution company’s pharmaceutical ordering web site.
2. The pharmacy selects items to order. The ordering system constructs a CSOS purchase order based on the selected items.
3. The pharmacy completes its order selection.
4. The ordering system routes the purchase order document file to Interchange, which in turn routes the document to the pharmacy’s WebTrader in-box. At this point, the document file is located on the file system used by the Interchange server and not the pharmacy’s computer.
5. The pharmacy views its WebTrader in-box, which lists the purchase order.
6. The pharmacy selects the purchase order and launches a process to sign the order with a personal certificate. The document is downloaded from the server to the pharmacy’s computer, signed and uploaded to the server. Downloading is necessary because the purchase order must be in the pharmacy’s physical possession during signing.
7. Depending on how WebTrader is integrated in the ordering process, the pharmacy may be unaware Interchange and WebTrader are involved. From the browser user’s point of view, the signing step may appear as part of the distribution company’s ordering web site. For more information, see Use the CSOS applet on your web page.
7. Interchange unpacks and verifies the uploaded signed purchase order.
8. Interchange routes the purchase order to the distribution company’s ordering system or whatever destination is configured.

Use the CSOS applet on your web page

A Java applet is used for signing CSOS documents on the browser user’s machine and uploading to an Interchange host. Instructions for incorporating the applet on your web page are in the README.html file in <install directory>\webapps\wtapplet\csos. In the same directory is a sample file, testCsosApplet.html, that demonstrates the applet. To try out the test page, start Activator server and point a browser to the following URL:

http://<host>:6080/wtapplet/csos/testCsosApplet.html

The variable <host> is the IP address or fully qualified domain name of the machine running Activator server.

Web traders’ must have JCE policy files added to the JRE plug-in for their browsers (see WebTrader partner requirements). Web traders can perform this task manually. Or, you can use the applet’s policy installer. This automatically installs the JCE policy files in a user’s browser when testCsosApplet.html is run. The README.html file has more information. Before version 5.5.1, installing JCE files was solely a manual process.

Manage unlimited strength JCE policy download issues

The client system used by a CSOS WebTrader end user is configured with JRE 8. This system automatically downloads unlimited strength JCE policy files from the Activator server to which it connects (if the files do not exist already exist on the client machine).

The download of these policy files succeeds but, in typical client configurations, the policy files cannot be copied to the local destination directory ...\Java\jre\lib\security and an "Access denied" error can be viewed by running a debug on the applet code.

The reason for the failure is that the JRE (by default) is located in the C:\Program Files or C:\Program Files (x86) folder which is write-protected by Windows User Account Control.

Analyze the issue

In normal use, there is no specific indication to the end user that the policy file download has failed to copy to the directory. However the standard message that the applet has not loaded yet persists with the mention to contact the administrator.

To view the progress of the policy down load you can open a Java console.

1. From the Windows Start Menu select Programs>Java>Configure Java to open the Java Control Panel.
2. Select the Advanced tab.
3. Select the option Java console > Show console.
4. Click OK.

With the console activated, you can view details of the Unlimited Strength Policy download failure.

Correct the issue

There are two options for avoiding this policy download failure:

• A client machine user with administrator privileges can disable the UAC write protection on the jre\lib\security folder.
• The CSOS/WebTrader end user can start the web browser in administrator mode. To do this:
• 1. Locate the browser command in the Windows Start menu.
  2. Right-click the command.
  3. Select Run as Administrator.
  4. Open a CSOS/WebTrader session.

Confirm the resolution

With a Java console, open you should now be able to confirm the success of the policy download. The end user can proceed with trading activities.

Sponsor requirements

To establish a relationship with a WebTrader partner, an Interchange sponsor must first have its own community. Next, the sponsor must add a partner for the WebTrader partner. There are two ways to do this. The sponsor can manually add the partner or direct the WebTrader partner to a self-registration web site hosted on the Interchange server.

To manually add a WebTrader partner, see Add a WebTrader partner.

To direct a WebTrader partner to a self-registration web site, see Activate self-registration for WebTrader partners.

In your community, set up an application pickup that forces the sender to be the WebTrader partner and the receiver to be your community. You can do this using the From routing ID and To routing ID attributes on the message attributes tab of the exchange’s maintenance page. See Message attributes tab.

You also need to set up a CSOS order source. See Identify CSOS purchase orders.

Once configuration is completed, copy a purchase order document to the application pickup directory. Activator consumes the message and writes it to the WebTrader’s document store on the file system used by Activator. Typically, WebTraders’ document stores are under <install directory>\common\webtrader. Message Tracker reports the message as delivered to the WebTrader partner, although the document file remains on the sponsor’s file system. See Approve CSOS documents in WebTrader for the WebTrader’s steps to approve and sign the document.

WebTrader partner requirements

The WebTrader partner needs a valid DEA-issued certificate with which to sign CSOS purchase orders. The signature is evidence of the WebTrader partner’s approval of such orders. The Interchange sponsor, upon receiving signed orders, verifies the signature against DEA-issued root certificates. The WebTrader partner's browser must haveJava Runtime Environment (JRE) 1.6. The WebTrader partner also must deploy Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 5.0 or 6.0.

You can do the following to check the browser for the JRE plug-in and obtain and deploy the JCE files. An applet also is available to check whether the JCE files are deployed. If the files are missing, the applet installs them.

• Internet Explorer – Select Tools > Internet Options to open the Internet Options window. Select the Advanced tab. Scroll down the list of settings and look for a category named Java (Sun). Under this might be a setting that is the same or similar to the following line:
• Use JRE 1.5.0_05 for <applet> (requires restart)
• If present, select the check box for this entry if not already selected. Click OK to close the window and save your change and restart Internet Explorer.
• Mozilla Firefox – Type about:plugins in the address field and press Enter. Scroll down the installed plug-ins page and check the version of the latest Java plug-in.

If you need JRE 1.5.0_05 or later, go to the following URL and download and install the JRE:

http://java.sun.com/j2se/1.5.0/download.jsp

You can download the JCE files on the same page you downloaded the JRE. However, you can skip this manual process by using the applet to check whether a browser has the JCE files and install them for you if missing.

Once you have downloaded the JCE files do the following:

1. Unzip the downloaded jce_policy-1_5_0.zip file. This unzips to a folder named jce that contains four files:
   
   • COPYRIGHT.html
   • local_policy.jar
   • README.txt
   • US_export_policy.jar
2. You only will use the JAR files.
2. Open the security directory of JRE 1.5.0_05 or later. On Windows this is typically:
3. C:\Program Files\Java\jre1.5.0_05\lib\security
3. Rename the two JAR files in the security directory in case you need to use them later. These are local_policy.jar and US_export_policy.jar.
4. Copy local_policy.jar and US_export_policy.jar from the jce folder to the security directory.

Approve CSOS documents in WebTrader

Use this procedure if you are a WebTrader partner and want to check WebTrader for CSOS documents awaiting signing.

1. Log on to WebTrader with your user ID and password.
2. Check the inbox for documents awaiting approval.
3. Click Approve to display the Approve CSOS order page.
4. Under select a signing certificate, if a certificate is not already selected, click Browse and locate a signing certificate on your file system.
5. Click Approve to display a dialog box for entering the certificate’s password.
6. Type the password and click OK. An approving purchase order dialog box appears, reporting the progress of the signing. In this process, WebTrader downloads the document from the Interchange server, signs the document with the private key in the certificate and uploads the signed document to the server.
7. A copy of the signed document is kept on your computer in your Java user home directory. On Windows, typically this is at:
8. C:\Documents and Settings\<user ID>\.cyclone\csos_backup
7. Click Close to close the dialog box.
8. The signed document is listed in the WebTrader partner's sent folder. Click the Details link for information about the signed document or to view it.
9. Message Tracker on the sponsor’s Interchange system reports the document as sent by the WebTrader partner to the sponsor’s community or re-routed by the sponsor to a third-party.

Turning on HTTP chunking

The CSOS order signing applet can chunk large messages before sending.

A chunked message is a large message broken into smaller pieces for sending to a partner.

The applet on its own chunks messages larger than 2 gigabytes. However, a parameter named httpChunkingAlwaysOn is available to enable chunking always. A value of true for this parameter enables chunking in the HTTP client regardless of the size of the uploaded payload.

The applet breaks messages into chunks of 64KB. So a file must be larger for chunking to occur.

There are two ways you can use the parameter to enable HTTP chunking.

1. Applet parameter – This first option is a server-side change. You can edit the web page containing the applet to pass a value for httpChunkingAlwaysOn as an applet parameter. For example:
2. <applet ...
3. <param name="httpChunkingAlwaysOn" value="true"/>
4. </applet>
5. After adding the parameter, reload the page for the change to take effect.
2. Applet properties file – The second option is a client-side change.
3. After you run the signing upload applet and sign a document, a file named applet.properties appears in your Java user home directory. If you use Windows, your user home directory is your personal directory in C:\Documents and Settings. In your user home directory is a subdirectory named .cyclone. In that directory is a file named applet.properties.
4. Close all browser windows. Add the following line to the applet.properties file:
5. httpChunkingAlwaysOn=true
6. Then point your browser at the page with the applet and try uploading.