CyberSource Risk Manager 3.0. Installation Guide

CyberSource Risk Manager 3.0 Installation Guide August 2002

CyberSource Contact Information http://www.cybersource.com Visit our Web site for information about our company, products, and services. sales@cybersource.com Email requests for information regarding any CyberSource service, or call 888.330.2300 (toll-free) or 650.965.6000. http://www.cybersource.com/support Visit the Support Center Web site (password required) if you have questions about any CyberSource service. ics_support@cybersource.com (United States) eu_support@cybersource.com (International) Contact Customer Support if you have problems with any CyberSource service, or call 800.709.7779 (United States) or +44 0 1189 653 545 (international). ii CyberSource Corporation

Copyright and Restricted Rights Legends Risk Manager Installation Guide Copyright 2002 CyberSource Corporation. All rights reserved. CyberSource Corporation furnishes this document and the software described in this document under the applicable agreement ( Agreement ). You may use or copy this document and software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not interpreted in any way as a guarantee or warranty by CyberSource Corporation. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to you for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, you may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource Corporation. Restricted Rights Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Risk Manager Installation Guide August 2002 iii

Trademarks and Document Conventions Trademarks CyberSource, the Power Behind the Buy Button, and the CyberSource logo are registered trademarks in the U.S. and other countries. CyberSource Payment Manager and CyberSource Risk Manager are trademarks of CyberSource Corporation. CyberSource ecommerce Transaction Suite is a service mark of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. Document Conventions bold Courier bold Courier bold italic Courier Fields and applications appear in bold. For example, the ics_auth application uses the request-level field customer_cc_number. Program examples and command-line messages appear in a fixed-width font. For example, you can see the error message Error: Program contacting database. Information you type at a command line exactly as shown appears in a bold, fixed-width font. For example, you can type java ECert. Variable information you type at a command line appears in a bold, italic, fixed-width font. For example, you can type your_merchant_id. iv CyberSource Corporation

Contents Chapter 1 Overview of Risk Manager Installation...1 Intended Audience...1 System Requirements...1 System Security...2 Related Documentation...2 Chapter 2 Installing Risk Manager Files...3 Adding JAR Files to the Classpath...3 Adding JVM Memory for the WebLogic Server...4 Configuring the X Server...4 Copying DTD Files...5 Chapter 3 Setting Up Databases...7 Creating the Databases...7 Oracle Considerations...7 Running the Database Scripts...7 Running the Administration Server Scripts...7 Running the Decision Server Scripts...8 Chapter 4 Configuring WebLogic for Risk Manager...9 Creating the Administration Server Connection Pool...9 Creating a New JDBC Connection Pool...9 Creating a New JDBC Data Source...13 Creating the Decision Server Connection Pool...15 Creating a New JDBC Connection Pool...15 Creating a New JDBC Data Source...19 Restarting WebLogic...21 Chapter 5 Deploying and Testing Risk Manager...23 Deploying Risk Manager EAR Files...23 Risk Manager Installation Guide August 2002 v

Deploying Risk Manager JAR Files...24 Testing the Administration Server...24 Changing the Default Password...25 Testing the Decision Server...26 Index...27 vi CyberSource Corporation

Chapter 1 Overview of Risk Manager Installation The Risk Manager Installation Guide provides instructions for installing CyberSource Risk Manager. This guide also provides instructions for configuring the following components for use with Risk Manager: BEA WebLogic Server 6.1, Service Pack 2 Windows 2000 Server or Solaris 8 Server Microsoft SQL Server 2000 or Oracle 8i database This guide does not provide instructions for installing products other than Risk Manager. Intended Audience The Risk Manager Installation Guide is intended for the following users: System administrator administers the application system Database administrator installs and configures the database and maintains database access controls System Requirements To run CyberSource Risk Manager, your system must meet the following minimum requirements: Windows 2000 with 400 MHz or higher Intel Pentium II-compatible CPU, or Solaris 8 Server with SPARC CPU Microsoft SQL Server 2000 or Oracle 8i database Microsoft Internet Explorer 5.5 or higher 256 MB RAM allocated to your Java virtual machine (JVM) Risk Manager Installation Guide August 2002 1

System Security If you need more memory for your JVM, see Adding JVM Memory for the WebLogic Server on page 4. 100 MB of available hard-disk space You must also install BEA WebLogic Server 6.1 with Service Pack 2 on your server. All of your Risk Manager servers must run the same version of BEA WebLogic Server. If you use clustering with BEA WebLogic, you can cluster Risk Manager. System Security Your system architecture should include a firewall between your application server and any untrusted clients. The firewall should deny direct access to any other servers in the system. Related Documentation The following documents are also essential for implementing and using Risk Manager: Risk Manager User s Guide Risk Manager Developer s Guide Risk Manager Custom API Developer s Guide 2 CyberSource Corporation

Chapter 2 Installing Risk Manager Files This chapter explains how to install Risk Manager files on the WebLogic server. Adding JAR Files to the Classpath You must install several Java Archive (JAR) files to support Risk Manager, both on the Administration Server and on the Decision Server. These JAR files must be copied to your server and added to the WebLogic classpath. 1 In WebLogic s lib/ directory, create a new directory called rm. For Windows: c:\bea\wlserver6.1\lib\rm For Solaris: /bea/wlserver6.1/lib/rm 2 Copy the following files from the thirdparty/ directory on the installation CD into the rm/ directory: jakarta-regexp-1.2.jar jdom.jar jimi.zip jregex1.1_02.jar rmplugin.jar xerces.jar xmlrpc-1.1.jar If you are using SQL Server, you must also copy the following files into the rm/ directory: msbase.jar mssqlserver.jar msutil.jar 3 Using a text editor, open the WebLogic startup script. Risk Manager Installation Guide August 2002 3

Adding JVM Memory for the WebLogic Server On Windows, this file is called startweblogic.cmd. On Solaris, this file is called startweblogic.sh. 4 Add the new JAR files to WebLogic s classpath. On Windows, if you are using SQL Server, the text will now appear similar to the following: set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar;.\lib\rm\ jakarta-regexp-1.2.jar;.\lib\rm\jdom.jar;.\lib\rm\jimi.zip;.\lib\r m\jregex1.1_02.jar;.\lib\rm\rmplugin.jar;.\lib\rm\xerces.jar;.\lib \rm\xmlrpc-1.1.jar;.\lib\rm\msbase.jar;.\lib\rm\mssqlserver.jar;.\ lib\rm\msutil.jar On Windows, if you are using Oracle, the text will now appear similar to the following: set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar;.\lib\rm\ jakarta-regexp-1.2.jar;.\lib\rm\jdom.jar;.\lib\rm\jimi.zip;.\lib\r m\jregex1.1_02.jar;.\lib\rm\rmplugin.jar;.\lib\rm\xerces.jar;.\lib \rm\xmlrpc-1.1.jar On Solaris, the text will now appear similar to the following: CLASSPATH=$WL_HOME:$WL_HOME/lib/weblogic_sp.jar:$WL_HOME/lib/weblo gic.jar:$wl_home/lib/rm/jakarta-regexp-1.2.jar:$wl_home/lib/rm/jdo m.jar:$wl_home/lib/rm/jimi.zip:$wl_home/lib/rm/jregex1.1_02.jar:$w L_HOME/lib/rm/rmplugin.jar:$WL_HOME/lib/rm/xerces.jar:$WL_HOME/lib /rm/xmlrpc-1.1.jar 5 Save and close the WebLogic startup script. Adding JVM Memory for the WebLogic Server If additional memory is needed, then increase the amount of heap space the JVM can allocate by adjusting the -mx and -ms settings in the WebLogic start-up script. Configuring the X Server If you are running the WebLogic server on Solaris, you must complete several tasks to ensure that the Administration Server can create workflow images. 1 Verify that the machine running the Administration Server is also running an X server. For example, you can use the ps command to get a list of processes, then display only those with a capital X in their names: ps -ef grep X 2 Using a text editor, open the WebLogic startup script, startweblogic.sh. 3 Add the following two lines to the WebLogic startup script: DISPLAY=<server name>:<display number> 4 CyberSource Corporation

Chapter 2 Installing Risk Manager Files export DISPLAY For example, you might type the following: DISPLAY=localhost:1.0 export DISPLAY 4 Save and close the WebLogic startup script. Copying DTD Files If you want to use Risk Manager s document type definition files (DTDs) as a reference, you can copy them to any location on your server. The DTDs specify the format of the Extensible Markup Language (XML) request and reply documents. The DTDs are available on the installation CD in the dtds/ directory. They are also included in the Risk Manager Developer s Guide. Risk Manager Installation Guide August 2002 5

Copying DTD Files 6 CyberSource Corporation

Chapter 3 Setting Up Databases This chapter explains how to create and configure Risk Manager s databases. Creating the Databases You can create a single database, to be shared by the Administration Server and the Decision Server, or you can create a separate database for each server. If you create separate databases and run each one on a different server, your Decision Server can continue to process transactions even if you need to restart the Administration Server. Select an owner of each database and configure the permissions for your users. Oracle Considerations The database Block Size parameter (db_block_size) value must be at least 4096. Note Depending on your operating system and the tool used to create the database, the default value may be 2048; do not use this default value. Running the Database Scripts You must run scripts to set up the Administration Server and Decision Server databases. The scripts are available in the scripts/ directory on your installation CD. Running the Administration Server Scripts 1 Create the Administration Server database. For SQL Server, use the SQL Server Enterprise Manager. Note Make sure to note whether you create a Unicode or a non-unicode database. Risk Manager Installation Guide August 2002 7

Running the Database Scripts For Oracle, use the Oracle Database Configuration Assistant. 2 Run the table creation script against the Administration Server database. For SQL Server (Unicode database): Admin_Schema_SQLServer_2000_Unicode.sql For SQL Server (non-unicode database): Admin_Schema_SQLServer_2000.sql For Oracle: Admin_Schema_Oracle_8i.sql 3 Run Admin_Init.sql against the Administration Server database. Running the Decision Server Scripts 1 Create the Decision Server database. For SQL Server, use the SQL Server Enterprise Manager. For Oracle, use the Oracle Database Configuration Assistant. 2 Run the table creation script against the Decision Server database. For SQL Server (Unicode database): Decision_Schema_SQLServer_2000_Unicode.sql For SQL Server (non-unicode database): Decision_Schema_SQLServer_2000.sql For Oracle: Decision_Schema_Oracle_8i.sql 8 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager This chapter explains how to create and configure the Administration Server and Decision Server connection pools. You will need the following information about your Administration Server and Decision Server databases to complete the procedures in this chapter: IP address and port number User name and password Database name (SQL Server only) Database system identifier, or SID (Oracle only) Creating the Administration Server Connection Pool To create the Administration Server connection pool, you must create a JDBC connection pool, then add a JDBC data source. Creating a New JDBC Connection Pool 1 Using a Web browser, go to http://<servername>:<port>/console, where <servername> is the computer where BEA WebLogic is installed. 2 Type the BEA WebLogic administrator s user name and password, then click OK. The WebLogic Server Console opens. 3 In the left navigation bar, click Services > JDBC > Connection Pools. The JDBC Connection Pools page opens. Risk Manager Installation Guide August 2002 9

Creating the Administration Server Connection Pool 4 Click Configure a new JDBC Connection Pool... The Configuration tab opens. 5 Type the information in the form as follows. For SQL Server: Name: AdminPool URL: jdbc:microsoft:sqlserver://<databaseipaddress>: <databaseport> Driver Classname: com.microsoft.jdbc.sqlserver.sqlserverdriver Properties: user=<databaseusername> DatabaseName=<databaseName> ACLName: reserve Password: <databasepassword> For Oracle: Name: AdminPool URL: jdbc:oracle:thin:@<databaseipaddress>:<databaseport>: <databasesid> Driver Classname: oracle.jdbc.driver.oracledriver Properties: user=<databaseusername> dll=ocijdbc8 10 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager protocol=thin ACLName: reserve Password: <databasepassword> 6 Click Create. WebLogic creates the connection pool. 7 Click the Testing tab. The Testing tab opens. 8 Type the information in the form as follows. For SQL Server: Test Table Name: sysobjects Test Reserved Connections: enabled Test Released Connections: disabled For Oracle: Test Table Name: DUAL Test Reserved Connections: enabled Test Released Connections: disabled Risk Manager Installation Guide August 2002 11

Creating the Administration Server Connection Pool 9 Click Apply. WebLogic saves the settings. 10 Click the Connections tab. The Connections tab opens. 11 Type the information in the form as follows. Initial Capacity: 4 Maximum Capacity: 20 Capacity Increment: 1 Login Delay Seconds: 1 Refresh Period: 10 Supports Local Transaction: disabled Allow Shrinking: enabled Shrink Period: 15 Prepared Statement Cache Size: 10 12 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager 12 Click Apply. WebLogic saves the settings. 13 Click the Targets tab. The Targets tab opens. 14 Move the Risk Manager server from the Available list to the Chosen list, then click Apply. The connection pool is complete. Creating a New JDBC Data Source 1 In the WebLogic console s left navigation bar, click Services > JDBC > Data Sources. The JDBC Data Sources page opens. Risk Manager Installation Guide August 2002 13

Creating the Administration Server Connection Pool 2 Click Configure a new JDBC Data Source... The Configuration tab opens. 3 Type the information in the form as follows. Name: AdminDataSource JNDI Name: AdminDataSource Pool Name: AdminPool Row Prefetch Enabled: disabled Row Prefetch Size: 48 Stream Chunk Size: 256 4 Click Create. WebLogic creates the data source. 14 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager 5 Click the Targets tab. The Targets tab opens. 6 Move the Risk Manager server from the Available list to the Chosen list, then click Apply. The data source is complete. Creating the Decision Server Connection Pool To create the Decision Server connection pool, you must create a JDBC connection pool, then add a JDBC data source. Creating a New JDBC Connection Pool 1 In the WebLogic console s left navigation bar, click Services > JDBC > Connection Pools. The JDBC Connection Pools page opens. Risk Manager Installation Guide August 2002 15

Creating the Decision Server Connection Pool 2 Click Configure a new JDBC Connection Pool... The Configuration tab opens. 3 Type the information in the form as follows. For SQL Server: Name: DecisionPool URL: jdbc:microsoft:sqlserver://<databaseipaddress>: <databaseport> Driver Classname: com.microsoft.jdbc.sqlserver.sqlserverdriver Properties: user=<databaseusername> DatabaseName=<databaseName> ACLName: reserve Password: <databasepassword> For Oracle: Name: DecisionPool URL: jdbc:oracle:thin:@<databaseipaddress>:<databaseport>: <databasesid> Driver Classname: oracle.jdbc.driver.oracledriver Properties: user=<databaseusername> dll=ocijdbc8 16 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager protocol=thin ACLName: reserve Password: <databasepassword> 4 Click Create. WebLogic creates the connection pool. 5 Click the Testing tab. The Testing tab opens. 6 Type the information in the form as follows. For SQL Server: Test Table Name: sysobjects Test Reserved Connections: enabled Test Released Connections: disabled For Oracle: Test Table Name: DUAL Test Reserved Connections: enabled Test Released Connections: disabled Risk Manager Installation Guide August 2002 17

Creating the Decision Server Connection Pool 7 Click Apply. WebLogic saves the settings. 8 Click the Connections tab. The Connections tab opens. 9 Type the information in the form as follows. Initial Capacity: 4 Maximum Capacity: 20 Capacity Increment: 1 Login Delay Seconds: 1 Refresh Period: 10 Supports Local Transaction: disabled Allow Shrinking: enabled Shrink Period: 15 Prepared Statement Cache Size: 10 18 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager 10 Click Apply. WebLogic saves the settings. 11 Click the Targets tab. The Targets tab opens. 12 Move the Risk Manager server from the Available list to the Chosen list, then click Apply. The connection pool is complete. Creating a New JDBC Data Source 1 In the WebLogic console s left navigation bar, click Services > JDBC > Data Sources. The JDBC Data Sources page opens. Risk Manager Installation Guide August 2002 19

Creating the Decision Server Connection Pool 2 Click Configure a new JDBC Data Source... The Configuration tab opens. 3 Type the information in the form as follows. Name: RMDecisionDataSource JNDI Name: RMDecisionDataSource Pool Name: DecisionPool Row Prefetch Enabled: disabled Row Prefetch Size: 48 Stream Chunk Size: 256 4 Click Create. WebLogic creates the data source. 20 CyberSource Corporation

Chapter 4 Configuring WebLogic for Risk Manager 5 Click the Targets tab. The Targets tab opens. 6 Move the Risk Manager server from the Available list to the Chosen list, then click Apply. The data source is complete. Restarting WebLogic After you create and configure Risk Manager s connection pools, you must restart WebLogic. Risk Manager will not work correctly until you have restarted WebLogic. Risk Manager Installation Guide August 2002 21

Restarting WebLogic 22 CyberSource Corporation

Chapter 5 Deploying and Testing Risk Manager This chapter explains how to deploy Risk Manager using the WebLogic console. It also describes how to verify that the deployment succeeded. Deploying Risk Manager EAR Files You must deploy the following Enterprise Archive (EAR) files through the WebLogic console: adminserver.ear: Administration Server decisionserver.ear: Decision Server Note If you are running the Administration Server and Decision Server on separate systems, you do not need to deploy both EAR files on each system. 1 Using a Web browser, go to http://<servername>:<port>/console, where <servername> is the computer where BEA WebLogic is installed. 2 Type the BEA WebLogic administrator s user name and password, then click OK. The WebLogic Server Console opens. 3 In the left navigation bar, click Deployments > Applications. The Applications page opens. 4 Click Install a new Application... The Install or Update an Application page opens. 5 Click the Browse... button. The browser prompts you for the location of the EAR file. Choose adminserver.ear from the rm/ directory on the installation CD, then click Open. 6 Click Upload. WebLogic installs the Administration Server. 7 Repeat Step 5-Step 6 for decisionserver.ear. WebLogic installs the Decision Server. Risk Manager Installation Guide August 2002 23

Deploying Risk Manager JAR Files Deploying Risk Manager JAR Files You must deploy the following Java Archive (JAR) files through the WebLogic console: addfields.jar: AddFields Plug-In emailaction.jar: EmailAction Plug-In Also, if your Risk Manager license supports additional Custom API plug-ins, you must deploy the JAR file for each plug-in: listcheck.jar: Hotlist Plug-In velocitycheck.jar: Velocity Plug-In Other plug-ins, such as the ICS/CPM Plug-In and the Payer Authentication Plug-In, require additional JAR files. For more information, see the documentation for your plugin. 1 In the WebLogic console s left navigation bar, click Deployments > EJB. The EJB Deployments page opens. 2 Click Install a new EJB... The Install or Update an Application page opens. 3 Click the Browse... button. The browser prompts you for the location of the JAR file. Choose addfields.jar from the rm/ directory on the installation CD, then click Open. 4 Click Upload. WebLogic installs addfields.jar. 5 Repeat Step 3-Step 4 for each additional JAR file. Testing the Administration Server If WebLogic deploys adminserver.ear with no errors, go to http://<servername>:<port>/admin and log in as the user admin. The default password is admin. 24 CyberSource Corporation

Chapter 5 Deploying and Testing Risk Manager If your deployment is successful, the Choose a Business page opens. Changing the Default Password As soon as the Administration Server is running, change the password for the user admin. Important If you do not change the password, unauthorized users may be able to access your server. 1 On the left navigation bar, click Users. The User Administration page opens. Risk Manager Installation Guide August 2002 25

Testing the Decision Server 2 Click the user name admin. The Edit User page appears. 3 Type a new password in the Password and Confirm Password boxes, then click Save Changes. Risk Manager saves your changes and returns you to the User Administration page. Testing the Decision Server To test that the Decision Server is working correctly, add an alias for the Decision Server to the Administration Server. For instructions, see the Risk Manager User s Guide. 26 CyberSource Corporation

Index A Administration Server 4, 7 Administration Server database 7, 8 B BEA WebLogic Server 1, 2 Block Size 7 C Configuring the Administration Server Connection Pool 9 Configuring the Decision Server Connection Pool 15 Configuring the X Server 4 Configuring WebLogic for Risk Manager 7 Creating a New JDBC Connection Pool 9, 15 Creating a New JDBC Data Source 13, 19 Creating the Administration Server Connection Pool 9 Creating the Decision Server Connection Pool 15 Creating the Risk Manager Database 7 Custom API 24 D Decision Server 7 Decision Server database 8 Deploying Risk Manager 9 Deploying the Administration Server 23 document type definition files 5 E Extensible Markup Language (XML) 5 F firewall 2 I Intended Audience 1 J Java virtual machine 1 JDBC connection pool 9, 15 JDBC data source 9, 15 JVM Memory 4 M Microsoft Internet Explorer 1 Microsoft SQL Server 1 Microsoft SQL Server 2000 1 O Oracle 8i 1 Oracle Considerations 7 Oracle Database Configuration Assistant 8 Overview of Risk Manager 1 P plug-ins, installing 24 Risk Manager Installation Guide August 2002 27

R X R Related Documentation 2 Risk Manager Custom API Developer s Guide 2 Risk Manager Developer s Guide 2 Risk Manager User s Guide 2 Running Database Scripts 7 Running the Administration Server Database Script 7 Running the Decision Server Database Script 8 S Solaris 4 Solaris 8 1 Solaris 8 Server 1 SQL Server 1 SQL Server Enterprise Manager 7, 8 System Requirements 1 System Security 2 T Testing the Deployment 24, 26 W WebLogic server 3 WebLogic Server Console 9, 23 Windows 2000 1 Windows 2000 Server 1 X X Server 4 28 CyberSource Corporation