Chapter 4   Installing ECXpert on Windows

This chapter describes how to use the ECXpert Installer to install ECXpert on the Windows NT and Windows 2000 platforms. It covers the following topics:

• "Installing ECXpert"
• "Post-Installation Tasks"
• "Starting the ECXpert Administration Server"
• "Enabling Special Features"

Refer to the Installation Worksheet in Table 2-8 as you perform these tasks. Make sure that you have installed all needed dependent software, as described in Chapter 2 "Preinstallation Tasks" before you install ECXpert.

All the instructions in this chapter are written for a new install of ECXpert. It is assumed ECXpert has either not been previously installed on the target system or that you have deleted all files and directories from any previous installation.

If you are migrating from a previous version of ECXpert, see Appendix A, "Upgrading to ECXpert 3.6.2."

If you are re-installing ECXpert Version 3.6.2, see Appendix B, "Reinstalling ECXpert."

Installing ECXpert

---

This section explains how you use the installer to install ECXpert.

1. Log in as a user with administrative privileges.
2. Make sure you have a valid host name and domain name.

Consult your system administrator if either your host name or domain name does not have a valid value.

3. Select the CD drive in the Explorer.
4. Start the ECXpert installer by double-clicking the setup.exe file.

A Setup dialog box appears momentarily while some installer files are copied temporarily to your hard drive from the CD.

Once the installer verifies IP address and memory information, finds the location of your browser, and makes sure Oracle is installed, the following welcome dialog box appears:

Figure 4-1    ECXpert Welcome Dialog Box



If, instead of seeing the Welcome dialog box, you see the error message:

Failed in call to get_machine_info - Code 1

you need to verify your network configuration:

1. From the Windows task bar select Start > Settings > Control Panel.
2. Double-click on Network.
3. In the Network dialog box click the Protocols tab.
4. Select TCP/IP Protocol and click Properties.
5. Click the DNS tab.
6. Make sure the Host Name and Domain fields contain correct values.
7. Click OK.

5. Continue from the Welcome to ECXpert dialog box.

Click Next.

If a Warning message is displayed regarding the amount of RAM installed, read the message and click OK to continue. The ECXpert installation can continue from this point, but you may not be able to operate in a high-volume production environment without the recommended amount of RAM.

If you are installing ECXpert for the first time on this machine, you will see the dialog box illustrated in Figure 4-2.

Figure 4-2    Choose ECXpert Base Directory Dialog Box, No Existing Version Detected



6. To install ECXpert into a different directory than the default, click Browse to select the directory you want, and then click Next. Otherwise, simply click Next.

If you are upgrading ECXpert from a previous version you will see the dialog box illustrated in Figure 4-3.

Figure 4-3    Choose ECXpert Base Directory, Existing Version Detected






---

Caution

If you are upgrading from an earlier version of ECXpert do not simply install the current version over the old one. If the installer has found your existing installation, click Browse to specify a different directory into which to install the new version. For more information on reinstalling ECXpert, see Appendix B

---




When you have selected the directory into which you want to install the new version of ECXpert, make sure that this directory appears in the Destination Directory field before you continue.

7. Click Next to continue.

If you have correctly installed the Sun™ ONE Web Server and have restarted your machine, the dialog box illustrated in Figure 4-4 appears:

Figure 4-4    A valid HTTP Server is already installed... Dialog Box



You must specify the port number on which you installed your web server instance.

8. Click Next to continue.




---

Note

If you have just installed the Sun ONE Web Server, but have not restarted your machine, you may see the error message: httpd-machine_name is not found in the NT Registry If you get this message, click Cancel to abort the installation session. Reboot your machine. After your machine has fully booted, restart the installer.

---




The Choose Destination Location dialog box appears. Use this dialog to specify the directory in which the web server is installed.

Figure 4-5    Choose Destination Location Dialog Box



9. To select a different directory, click Browse. Once the directory you want is displayed in the Destination Directory field, click Next to continue.

The Database Configuration dialog box is displayed.

Figure 4-6    Database Configuration Dialog Box






---

Caution

Selecting the Create New Tables check box causes any data currently in your Oracle database to be overwritten. If you want to retain whatever data you have in your Oracle database, do not select this option.

---



10. Fill in the fields. Consult the values you specified in Table 2-8.

Table 4-1    Values for the Database Configuration Dialog Box 

Field	Value
Server	Enter the database server name.
User	Enter the ECXpert database user (ECX36)
Password	Enter the password for the ECXpert database user account (ECX36)
Home	The directory in which you have installed Oracle. The installer displays this value for you. Verify that it is correct and enter the correct directory if it is incorrect.
SID	Enter the name of the Oracle server instance. This is the same as the database server name in "Server" above.
Database language	Enter the value for NLS_LANGUAGE. This must match the value you specified for this variable when you installed Oracle.
Create New Tables	If you are creating a new ECXpert installation (and thus have no data to retain), select the Create New Tables check box. If you are upgrading from a previous version of ECXpert or reinstalling ECXpert (and have data in your Oracle database that you want to retain), do not select the Create New Tables check box. (Selecting it will cause your data to be lost.) Consult the appropriate appendix in this manual for your needs.

11. When you have filled in all the fields, click Next.

A command prompt window appears, as the installer attempts to log onto the Oracle database. If there are any errors, follow the instructions that appear on the screen. You can also check the C:\temp\ora\ora_testconnect.log file for further information on why the connection failed.

If the connection was successful, the Mail and Logfile Information dialog box appears.

Figure 4-7    Mail and Logfile Information Dialog Box



12. Fill in the fields. Consult the values you specified in Table 2-8.

Table 4-2    Values for Mail and Logfile Information

Field	Value
Mail Host	mailhost
User Name	Your ECXpert admin user name; for example, ecxadmin (This account must already exist.)
Password	Your ECXpert admin user password; for example, ecxadmin (displays as asterisks)
Directory	Specify the location for your installation log files; for example, C:\temp Because the Oracle connection test was run before you got to the Mail and Logfile Information dialog box, if you enter a directory other than C:\temp the ora_testconnect.log file is written to C:\temp instead of the directory you specify.

13. Click Next to continue. The following two screens configure ECXpert to use Secure Trading Agent for sending and retrieving ebXML messages.

If you have not yet installed Secure Trading Agent or do not plan to use Secure Trading Agent to send and retrieve messages, leave the fields blank in these two screens and continue to Step 15.

If you plan to use Secure Trading Agent to send and retrieve ebXML messages, check your Installation Worksheet for actual values associated with ebXML message exchange.

The Secure Trading Agent configuration screen is displayed:

Figure 4-8    ebXML configuration (Secure Trading Agent)



Table 4-3 describes these fields.

Table 4-3    ebXML configuration (Secure Trading Agent) 

Field	Value
ebXML Installed toggle	Select this toggle if you plan to enable ebXML messaging and have installed Secure Trading Agent. If you do not plan to enable ebXML messaging or have not yet installed Secure Trading Agent, leave all fields blank and click Next.
STA Home Path	The path to your installation of Secure Trading Agent. The default paths for Windows platforms is: Windows: C:\Sun\SUNWebXML\S1ISSTA Specify the default path or your custom path if you modified the defaults.
ebXML User and password	The user Id and password for the Secure Trading Agent user that has access to send and retrieve messages. This user can be a Secure Trading Agent administrator or simply a Secure Trading agent regular user. Secure Trading Agent uses the system user Id and system password to authenticate Secure Trading Agent administrators and regular users. Refer to the Secure Trading Agent documentation for more information.
ebXML B2B User	The ebXML B2B user corresponds to a Secure Trading Agent user role. You define the name of the Secure Trading Agent user role in Secure Trading Agent. If you have not yet defined a user role in Secure Trading Agent, pick a name for the ebXML B2B user here and use that name later to define the user role in Secure Trading Agent.

14. Click next to specify configuration parameters to enable ebXML messaging for B2B.

Figure 4-9 displays parameters to configure ECXpert to enable ebXML messaging. If you do not plan to enable ebXML messaging, leave all fields blank and click Next to proceed to Step 15.

Figure 4-9    ebXML Configuration (B2B)



Table 4-4 describes the values of these fields.

Table 4-4    ebXML Configuration (B2B) 

Field	Value
B2B Sending Member and Password	All documents retrieved by the ebXML Communication Agent are submitted with this member as the sending member.
B2B Receiver	All documents retrieved by the ebXML Communication Agent are submitted with this member as the receiving member.
File-type format	Select one or more fields to identify the B2B file type format for retrieving ebXML messages. The Receive Communication Agent uses the file type format to construct the filetype submission parameter when submitting retrieved messages. By default, ebXML CPA ID and ebXML Action Name are selected. If you do not know what to specify here, accept the defaults.

15. Click next to continue.

The "Check your mail setup information" dialog box is displayed. This screen is read-only, allowing you to check values you have set thus far in the installation.

Figure 4-10    Check your mail setup information Dialog Box



If you want to change something, use the Back button as many times as necessary to navigate back to the relevant dialog box.

16. If you are satisfied with the settings, click Next to proceed with the installation.

The ECXpert files are now copied from the CD to the target directory. The Installer displays a screen title "Installing Sun ONE Integration Server B2B Edition (ECXpert) 3.6.2. The screen shows a progress bar for the copying of ECXpert files.

When the file transfer is complete, the installer displays the Modifying the HTTP Server's OBJ.CONF file dialog box. The obj.conf file is the file that contains configuration information for the web server.

Figure 4-11    Modifying the HTTP Server's OBJ.CONF file Dialog Box



17. Select one of the options for modifying the obj.conf file, and click Next.

• If you select the Do not make any changes option you must manually edit the obj.conf file or ECXpert will not function properly. Refer to "Edit the Web Server Configuration Files" for instructions.
• If you allow the installer to edit the obj.conf file, the following message is displayed.

Figure 4-12    Information Message Box



18. Click OK when the Message Box is displayed.
19. The Installer now displays a message asking if you want to modify the magnus.conf file. This file is also used to configure the web server. Indicate whether you want the installer to modify the file or whether you want to make changes manually. See "Configuring the Web Server" for instructions on making these changes.
20. Click Next and then OK (in the following message box).

A Command Prompt window opens while the installer sets up your Oracle database tables. SQL script output scrolls through the window.

In addition to setting up the Oracle tables, the installer performs the following functions as it completes the installation:

• updates registry information
• constructs and updates ECXpert configuration files, and makes changes to your HTTP server's configuration files for use with ECXpert. See "Configuring the Web Server" for instructions on making these changes (if you have chosen to make these changes yourself).
• imports certificates
• updates the system path to point to the ECXpert libraries, following the next reboot
• copies the ECXpert Components folder to the ECXpert Components program group
• imports data about ebXML members if you are using Secure Trading Agent

21. Specify a restart option.

ECXpert installation is now complete, but you must restart your computer before you can use ECXpert.

Figure 4-13    ECXpert Installation Complete Dialog Box

Post-Installation Tasks

---

This section describes the tasks you must perform after installing ECXpert. These include

• Configuring the web server
• Applying configuration changes
• Setting environment variables

Configuring the Web Server

Configuring the web server involves two steps: editing the obj.conf file and magnus.conf file, and applying these changes.

• If you have let the installer edit the files for you, you can skip the section "Edit the Web Server Configuration Files".
• To apply changes to the obj.conf file (whether the changes were manual or done by the installer), follow the directions in "Apply Web Server Configuration Changes".

Edit the Web Server Configuration Files

If you have a lot of customization to do, you might want to manually edit the obj.conf and magnus.conf files. Whether you edit the file manually or you let the installer do it, you must explicitly apply the changes, as described in "Apply Web Server Configuration Changes".

To edit the obj.conf file

1. Open the obj.conf file.

Using a text editor, such as Notepad, open the file

C:\SunONE\Servers\https-my_server\config\obj.conf

where C:\SunONE is the directory under which the Sun ONE Web Server is installed, and my_server is the name of your server.

2. Comment out unnecessary content.

If either of the following lines appear in your obj.conf file, comment them out by typing the pound character ("#") as the first character in each line:

#NameTrans fn="pfx2dir" from="/help" /
         dir="C:/SunONE/Servers/manual/https/ug"
#NameTrans fn="document-root" root="C:/SunONE/Servers/docs"

3. Add the required lines to the obj.conf file.

If, during the installation, you selected Save the required changes to obj.mod file as the option in the Modifying the HTTP Server's OBJ.CONF File dialog box, open the following file:

C:\SunONE\Servers\https-my_server\config\obj.mod

where my_server is the name of your server. Paste the contents of the obj.mod file into the obj.conf file immediately above the first line that begins with NameTrans.

However, if you instead selected the Do not make any changes option, add the following lines to the obj.conf file, in the following order, immediately above the first line that begins with NameTrans. Specify the directory in which you have installed ECXpert for c:/SunOne in the following lines:

NameTrans fn="pfx2dir" from="/images"
dir="c:/SunONE/NS-apps/ECXpert/cgi-bin" name="cgi"
NameTrans from="/bin" fn="pfx2dir"
dir="c:/SunONE/NS-apps/ECXpert/cgi-bin" name="cgi"
NameTrans fn="document-root"
root="c:/SunONE/NS-apps/ECXpert/UI/html"




---

Note	The forward slashes ("/") in the above lines are intentional, because the obj.conf file does not recognize back slashes. Do not change the forward slashes to back slashes.

---




4. Save your changes.

To edit the magnus.conf file

1. Open the magnus.conf file.

Using a text editor, such as Notepad, open the file

C:\SunONE\Servers\https-my_server\config\magnus.conf

where C:\SunONE is the directory under which the Sun ONE Web Server is installed, and my_server is the name of your server.

2. Append the following lines to the magnus.conf file. Specify the directory in which you have installed ECXpert for c:/SunOne in the following lines

KernelThreads 1

Init fn="init-cgi" PATH="c:/SunONE/NS-apps/ECXpert/bin/Solaris_JRE_140/lib/sparc:
   c:/SunONE/NS-apps/ECXpert/mercsdk/libs:
   c:/SunONE/NS-apps/ECXpert/lib" 
   BDGHOME="c:/SunONE/NS-apps/ECXpert"
   MERC_DO_NOT_CHDIR="TRUE" timeout="600"

3. Add the following line before any line that begins with "Init".

KernelThreads 1

4. Save your changes.
5. Stop and then restart the Sun ONE Web Server.

1. In the Windows task bar, select Start > Settings > Control Panel.
2. Double-click the Services entry.
3. Select the Sun ONE Web Server service and click Stop.

A message box appears, telling you that the system is stopping the service. When the message box disappears, click Start.

4. Click Close.

Apply Web Server Configuration Changes

Whether you edit the web server configuration files manually or you let the installer do it, you must explicitly apply the changes, as described in this section.

1. Start your web browser and go to the following URL.

http://machine_name:port#/admin-serv/bin/index

2. Enter a user ID and password for a Netscape Enterprise Server user with administrative privileges.
3. Apply any changes you made to the obj.conf file and magnus.conf file.

A message window appears telling you that you must apply your changes.

4. Click OK.
5. In the Netscape Enterprise Server bar at the top of the screen, click Apply. The Apply Changes screen appears.
6. Click Load Configuration Files for the Sun ONE Web Server.

If the changes are successfully applied, a "success" message window appears. Click OK to continue.

7. Exit your web browser.

Set Environment Variables

Parts of the installation process, as well as the routine operation of the ECXpert system, require the $BDGHOME environment variable be properly set.

To set the BDGHOME variable

1. From the Windows NT or Windows 2000 task bar, select Start > Settings > Control Panel > System.
2. In the System Properties window, select the Environment tab.
3. In the Variable input field, type BDGHOME.
4. In the Value input field, type the full path you specified for the directory into which you installed ECXpert (Root_ECX_Install), and append "\NS-apps\ECXpert" to the end of the path.

For example, if you had specified the path c:\foo\bar\mumble as the value of the Root_ECXInstall environment variable, you would set BDGHOME as

c:\foo\bar\mumble\NS-apps\ECXpert

You do not neet to reboot the machine to have these variable settings take effect; however, only new command-shell windows will see the changes.

Starting the ECXpert Administration Server

---

Follow the steps below to start the ECXpert Administration Server.

1. Start the web browser.
2. Display the ECXpert Administration home page.

Enter the URL hostname:port_number, where hostname is the name of the machine on which your web server resides, and port_number is the number of the port on which your web server is listening.




---

Note	If you used port 80 when you installed ECXpert, you do not need to enter a port number.

---




The ECXpert Main Screen appears, as shown in Figure 4-14.

Figure 4-14    ECXpert Main Menu



3. Save the URL to the ECXpert Main Menu as a bookmark.
4. Click Admin to display the ECXpert management screen.

The ECXpert Administration Server is not pre-configured with password protection. Use the Sun ONE Web Server Administration interface to enable this feature, if desired

Figure 4-15    ECXpert Management Screen Main Menu



The Management screen appears, as shown in Figure 4-15, when the ECXpert Administration Server is On. If your screen shows the ECXpert Administration Server Off, click the On portion of the button's toggle to turn on the server. Then click the Update Screen button to refresh the screen.

5. Continue to the next chapter, "Testing Your ECXpert Installation", to test your installation.

Enabling Special Features

---

The following sections explain how you do the following:

• Enable the Billing Code feature
• Enable expanded data fields

Enable the Billing Code Feature

To use the Billing Code feature

1. Navigate to your Oracle directory:

C:\> cd %BDGHOME%\dbadmin\oracle

2. Start sqlplus:

C:\> sqlplus myaccount/mypassword@myserver

where myaccount/mypassword@myserver is your configured account and its password.

3. From the sqlplus prompt, run the script:

sqlplus> @ora_pkgbody.sql

4. Restart ECXpert.

Enable Expanded Data Fields

ECXpert 3.6.2 supports larger data entry fields for the following parameters:

• senderid
• receiverid

Extract the script enlarge_email_addr.sql from the zip file %BDGHOME%\dbadmin\oracle\migration\30_to_35\30_to_35.zip.

To use this feature, run the following script as the ECXpert admin user from the Command Prompt:

%BDGHOME%\dbadmin\oracle\migration\30_to_35\enlarge_email_addr.sql

The ECXpert tables updated for char128 length are shown in Table 4-5:

Table 4-5    Tables Enabled for Expanded Data Fields 

Table	Field(s)	New Length
MBADDRESSES	MBAQUALID	128
PARTNERSHIPS	PNSNDRQUALID, PNRCVRQUALID	128
TRKINTCHG	TISNDRQUALID,TIRCVRQUALID	128
TRKDOC	TDSNDRQUALID, TDRCVRQUALID	128