| Sun ONE Integration Server B2B 3.6.2 Update 1, ECXpert Support for AS2 Messaging |
Chapter 1
Getting Started with AS2 Messaging: Installation and ConfigurationThis guide describes Sun™ Open Net Environment (Sun ONE) Integration Server B2B Edition 3.6.2 (ECXpert) support for Applicability Statement 2 (AS2). It provides the information you need to understand, install, and configure ECXpert for AS2 messaging. It covers the following topics:
- Overview – provides a context for understanding AS2 messaging with ECXpert.
- Setting Up the AS2 Plug-in – gives procedures for downloading, installing, and using the AS2 plug-in with ECXpert.
- Starting and Stopping the Servers – describes the proper order for starting and stopping all the servers in the AS2 system (ECXpert, AS2 Servers, and the Web Server).
- Uninstalling AS2 – provides instructions for restoring the system to its state prior to installing the AS2 plug in.
- What to Do Next – gives suggestions for what to do after installing the plug-in.
This document assumes that you are familiar with basic reliability and security concepts and that you have some understanding of the transport protocols involved.
OverviewLarge-scale retailers are increasingly implementing AS2 trading solutions to eliminate their need for value-added networks (VAN). A VAN is a private network provider that companies hire for monthly and per-character fees to transport their business documents to and from trading partners. With the ubiquitous use of the World Wide Web, the internet is often a more cost-efficient way for companies to move their data. However, there have been security, reliability, and non-repudiation challenges. AS2 is fast becoming the business document transport protocol for large retailers because it meets these challenges by offering:
The AS2 specification describes how to exchange business data securely and reliably using HTTP as an underlying transport. The data is packaged using standard MIME content types so you can use XML, EDI, binary data, and any other data describable in MIME. Message security (authentication, confidentiality) is implemented using S/MIME. Message reliability is enabled through the use of MDNs. Nonrepudiation and Nonrepudiation of Receipt are business/legal concepts that build upon the security and reliability components in AS2.
This section provides background for understanding AS2’s role with respect to Sun ONE Integration Server B2B Edition 3.6.2 (ECXpert) and describes high-level architecture and process flow for the Sun ONE AS2 implementation.
ECXpert and Its Communications Agents
Trading partner applications send data files via ECXpert using their native messaging protocols, for example, FTP, HTTP, JMS, ebXML, SMTP, or AS2. ECXpert itself does not interpret all the different protocols. It uses inbound and outbound Communications Agent components as interpreters as illustrated in Figure 1-1.
On the inbound side, the appropriate Communications Agent accepts the message, extracts the data within it, and submits the data to ECXpert for processing. After processing the submitted data, ECXpert passes the data and messaging parameters to the outbound Communications Agent. The outbound Communications Agent constructs a message in the protocol appropriate for the receiving application using the messaging parameters, and then transmits the message according to the rules of that particular protocol.
Figure 1-1 ECXpert’s Messaging System
As with all of the Communications Agents, the AS2 feature provides two agents: an inbound, or receive, Communications Agent and an outbound, or send, Communications Agent. The rest of this section describes these Communications Agents.
Receiving and Sending AS2 Messages
AS2 receive processing depicted in Figure 1-1 starts when the HTTP/AS2 Protocol Listener (or Protocol Listener) receives an AS2 message via HTTP POST from the remote trading partner. The receive processing ends when the AS2 Inbound Communications Agent submits the message payload to ECXpert core processing for parsing, translation, and routing as required.
The Protocol Listener is implemented as a servlet. Its job is to process inbound HTTP POST requests sent by the trading partner application. The AS2 Inbound Communications Agent handles all the details of the AS2 protocol processing. It authenticates the message, decrypts it if it is encrypted, and performs MDN generation and reconciliation if required before passing the business data to ECXpert.
The send processing starts as a response to an event, such as submitted data or a scheduled event. Referring to Figure 1-1, after ECXpert completes processing business data to transmit using AS2, it passes the data to the AS2 Outbound Server (a component of the AS2 Outbound Communications Agent). Based on outbound AS2 partnership parameters, the Outbound Server constructs a valid AS2 message with the appropriate type and MDN request attributes. The payload is encapsulated inside an AS2 message envelope. The message is optionally signed, encrypted, or signed and encrypted. The Sending Agent sends the message to trading partner.
Throughout its operation, the Outbound Server uses its logging interface to record events to the ECXpert Event Log, which you can access through ECXpert’s Tracking page under the Event Log tab.
Setting Up the AS2 Plug-inAs the AS2 administrator, you perform the following tasks to install the AS2 Communications Agent:
This section provides the details for performing these tasks.
Set the following environment variables in the shell in which you will perform the installation:
- IWS_SERVER_HOME
The root directory of your Sun ONE Web Server installation. (For example, /export/home/ecxadmin/iWS60SP5)
- BDGHOME
The root directory of your Sun ONE Integration Server B2B Edition installation. For example, set $BDGHOME to /export/home/actraadm/ecx36/NS-apps/ECXpert if you have accepted the default location.
Create the HTTP/AS2 Protocol Listener
Ensure that the following products are installed and running:
Configure the Sun ONE Web Server to use JRE 1.4. For the example shown in these procedures, IWS_SERVER_HOME represents /export/home/ecxadmin/iWS60SP5/.
Figure 1-2 illustrates the procedure.
To configure the Web Server to use JRE 1.4
- Open the Web Server Administration Server interface from a web browser.
- Click the Global Settings tab.
- Click the Configure JRE/JDK Paths link in the list of links on the left side of the page. The resulting screen should be similar to Figure 1-2.
Figure 1-2 Configure JRE/JDK Paths Screen
- Update the JRE Path to point to your B2B 1.4 JRE.
- Click Ok and restart the web server as directed.
- Close the browser window.
- Restart the Web Server Administration Server using the stop and start commands in $IWS_SERVER_HOME/https-admserv. Table 1-1 lists an interactive session that stops and starts the sever.
To create the HTTP/AS2 Protocol Listener
- Reopen the iPlanet Web Server Administration Server interface.
- Click the Add Server link on the left side of the Servers tab page.
See Figure 1-3 for an example of the screen.
Figure 1-3 Add Server Screen
- The fully qualified server name appears by default in the Server Name field.
- Set the server port value to an unused port (9000 in the example).
- Set the server identifier to the recommended default, as2.
- Set the server user to the ECXpert login name (excadmin in the example).
- Accept the default MTA Host, localhost.
- Click the OK button. Figure 1-4 shows an example of the resulting screen.
Figure 1-4 Add Server Success Screen
- Click the Configure your new server... link.
- Click the Server On button. This results in the screen shown in Figure 1-5.
Figure 1-5 Server On Screen
To Change https-as2 Ownership
- Change the file system ownership of the $IWS_SERVER_HOME/https-as2 directory contents to be the same as the owner of the server instance.
For example, the administrator in the example would change the owner to ecxadmin. If the file ownership is left as root, it could cause problems during deployment.
Install the AS2 Plug-In
These instructions assume that you have already downloaded the AS2 plug-in from the Sun website.
Preconditions for Installation
Ensure that the environment variables IWS_SERVER_HOME and BDGHOME are set as described on .
You need the following access information:
Table 1-2 Access Checklist
Required Information
Description
Default
ECXpert administrator login and password
Administrative ID and password required to configure ECXpert services and access membership/partnership information.
ECX, ECX
Oracle Hostname
The hostname of the machine on which the Oracle database is installed.
[hostname]
Oracle Port Number
The port number of the Oracle listener.
1521
Oracle SID
The SID for the ECXpert database.
ECX
Web Server Instance Name
The name of the web server instance you will create.
as2
To set up the new files
To install the AS2 plug-in components
- Execute the setup.sh script located in the root of your temporary directory.
You should see a listing similar to that shown in Table 1-3.
Table 1-3 Example Listing for AS2 Installation
ecxadmin@host[94]% ./setup.sh
## AS2 Plugin Installer ##
##########################
- B2B Configuration Settings -
B2B Admin User [ECX]:
B2B Admin Pass [ECX]:
- Oracle Configuration Settings -
Oracle Host [host]:
Oracle Port [1521]:
Oracle SID [ECX]: HOST
Deploying AS2 WAR file to iWS ...
AS2 Server Instance Name [as2]:
[wdeploy] The war file name is /export/home/ecxadmin/ecx36/NS-apps/ECXpert/http_as2/as2.war
[wdeploy] Deploying web application
[wdeploy] Loading new configuration
[wdeploy] Web application deploy successful
- Fill in the required information accepting defaults where appropriate up to the AS2 Server Instance Name.
If you have the admin account with login and password as ECX, ECX; and Oracle is installed on the same machine, you should be able to accept all of the defaults. In the example shown above, the administrator had an Oracle SID different from the default.
- Fill in the server instance name. If you created the server as https-as2, then accept the default.
- Watch the status messages returned by the installation program. You know that the installation is a success when you see the message Web application deploy successful.
The resulting directory structure is shown in Figure 1-6.
Figure 1-6 AS2 Directory Structure
The installation program installs all the necessary AS2 components in the correct directory structure locations. It configures the ecx.ini file so that the AS2 Communications Agents appear as choices in ECXpert’s Partnership Protocols Administration screen and otherwise integrates the AS2 plug-in with ECXpert.
If your AS2 usage profile requires communication through a proxy server, the use of signature and encryption, or SSL, you need to make minor modifications to one or more fields in ECXpert’s configuration file, ecx.ini. Appendix A, "ECXpert’s Configuration File (ecx.ini)" describes the fields specific to AS2.
After completing the installation procedure, you can start the system components and configure partnerships for AS2 communications.
Starting and Stopping the ServersBecause the AS2 Communications Agents are a plug-in for 3.6.2, AS2 administration differs from administration for native Communications Agents (for example, FTP, SMTP, or ebXML). The AS2-related servers will not appear in the ECXpert Administrator interface, so these servers must be manually started and stopped.
Figure 1-1 shows the servers involved for AS2 communication. They are the inbound and outbound AS2 Communication Agents, the HTTP Protocol listener that listens for inbound HTTP post messages, and the ECXpert server. The order in which you start the servers is important. If it is not done correctly, the communication fails resulting in an error message. For example, if you brought up the web server before starting the AS2 server, when the servlet tries to deliver data to the AS2 Communications Agent, the server will not be available. The web server will return errors for inbound AS2 messages until the inbound server is started.
Starting the Servers
First, start the ECXpert system so that it is ready to send and receive AS2 data. Then start the AS2 inbound and outbound servers directly from the command line. Finally, start the Web Server instance to enable the HTTP/AS2 Protocol Listener.
To start the ECXpert server
To start the AS2 Servers
- Start the AS2 inbound and outbound servers using the as2-server start command in the $BDGHOME/http_as2/bin.
The listing in Table 1-4 shows this step for the example.
The AS2 Server command-line interface allows you to manually start or stop the inbound and outbound AS2 servers. Note that there is no option to start or stop only one (inbound or outbound) of the servers.
Table 1-4 Example Listing for Starting the AS2 Servers
ecxadmin@host[74]% cd $BDGHOME/http_as2/bin
ecxadmin@host[75]% as2server start
ecxadmin@host[76]%
AS2 Server Bootstrap Loader v1.0
-> Created RMI registry.
-> Created Inbound AS2 Server.
-> Created Outbound AS2 Server.
-> Bootstrap Successful, Awaiting Requests...
To start the AS2 web server instance
To confirm that all servers are up and running
- Use the console on Solaris systems to confirm that the Java™ AS2 servers are running correctly. For Windows systems, look at the output from the as2server start command and look at the as2.log file.
- Use the ECXpert Administrative interface to verify that ECXpert is running.
- Use the web server logs to verify that the web server is running.
Stopping the Servers
As with starting the servers, there is a specific order in which to stop each server in the system. After shutting the servers down, ECXpert cannot receive AS2 messages.
To stop the AS2 web server instance
- Stop the web server instance for AS2 using the stop command in $IWS_SERVER_HOME/https-as2.
- Verify that the AS2 Inbound Communications Agent is not performing any work. One way to do this on Solaris machines is to use the tail command on the log files. On Windows machines, use the Task Manager.
When there is no more activity, proceed to the next step.
To stop the AS2 Servers
- Stop the AS2 inbound and outbound servers using the as2server stop command in the $BDGHOME/http_as2/bin. See Table 1-5.
Table 1-5 Example Listing for Stopping the AS2 Servers
ecxadmin@host[68]% as2server stop
ecxadmin@host[69]%
AS2 Server Bootstrap Loader v1.0
-> Server shutdown in 5 seconds!
- Verify that no work is currently in process on the ECXpert servers. When there is no activity, proceed to the next step.
To stop the ECXpert server
To confirm that all servers are shut down
Uninstalling AS2The AS2 setup.sh --uninstall command restores the system to its preinstallation state.
To uninstall the AS2 plug-in components
What to Do NextAfter you complete the AS2 plug-in installation and start the servers, you can test the new communications agents and set up encryption and signing if you need those features.
Test the Installation
Chapter 2, "Example: End-to-End Test for AS2 Messaging" gives a detailed example for testing between sending and receiving hosts for a simple plain message. If you are familiar with ECXpert administration, you can skip that chapter. However, it is recommended that you become familiar with the fields of the new protocol screen that are now available in the ECXpert Administration interface. See Table 2-6 and Figure 2-6.
Set Up Encryption and Signing Features
To set up encryption and signing you must create certificates as described in Chapter 3, "Creating Certificates for AS2 Messaging".
For instructions on setting up SSL, refer to Sun ONE Web Server documentation at http://docs.sun.com/db/coll/S1_ipwebsrvree60_en.
