Managing Colleague Software Environments

Transcription

1 Managing Colleague Software Environments Reissued Manual as of January 31, 2013 Enclosed is a new edition of the manual Managing Colleague Software Environments for Release 18. This edition replaces the previous version dated January 18, 2012 and incorporates changes delivered with software update SU *9. In addition, the following AnswerNet document was resolved: Update to Setting up Windows Authentication documentation The Primary Changes Made Section Pages Change Made Setting up an Environment as Production Restrictions on Moving an LPR Resetting an LPR in a Restored Environment 141 Procedure has been updated to note that, when using Windows Authentication, usernames entered must exist in the specified domain. 168 Updated introductory paragraph New chapter about how to reset the Local Product Repository so that you can reinstall software updates after restoring an environment. Updating Your Manual Replace all copies of your existing manual with this new edition as it will be the basis for all future updates.

2

3 Colleague by Ellucian Managing Colleague Software Environments Release 18 January 31, 2013 For corrections and clarifications to this manual, see AnswerNet page 4562.

4 Banner, Colleague, PowerCAMPUS, Luminis and Datatel are trademarks of Ellucian or its affiliates and are registered in the U.S. and other countries. Ellucian, Advance, DegreeWorks, fsaatlas, Course Signals, SmartCall, Recruiter, MOX, ILP, and WCMS are trademarks of Ellucian or its affiliates. Other names may be trademarks of their respective owners Ellucian. All rights reserved. The unauthorized possession, use, reproduction, distribution, display or disclosure of this material or the information contained herein is prohibited. Contains confidential and proprietary information of Ellucian and its subsidiaries. Use of these materials is limited to Ellucian licensees, and is subject to the terms and conditions of one or more written license agreements between Ellucian and the licensee in question. In preparing and providing this publication, Ellucian is not rendering legal, accounting, or other similar professional services. Ellucian makes no claims that an institution's use of this publication or the software for which it is provided will guarantee compliance with applicable federal or state laws, rules, or regulations. Each organization should seek legal, accounting and other similar professional services from competent providers of the organization s own choosing. Prepared by: Ellucian 4375 Fair Lakes Court Fairfax, Virginia United States of America

5 Table of Contents 11 Introduction 13 About This Manual 13 Who Should Read This Manual 13 What This Manual Covers 14 How This Manual is Organized 14 Where to Find More Information 15 Setup and Customization 17 Authorizing an Application Server (UniData) 17 In This Chapter 18 Understanding Application Server Authorization 18 Procedures for Authorizing an Application Server 18 Accessing the Authorize Application Server Form 19 Configuring the Authorize Application Server Form 23 Defining DMI Listener and Daemon Parameters 23 In This Chapter 24 Specifying Listener Memory Allocation 24 Syntax for Specifying Listener Memory 25 Procedure for Specifying Listener Memory Allocation 28 Automatically Starting DMI Listeners and Daemons 29 Adding the Listener Start Script to the Boot Sequence (UNIX/Linux Only) 29 HP-UX: Modifying the UNIX Boot Sequence 30 SUN Solaris: Modifying the UNIX Boot Sequence 30 Red Hat Linux: Modifying the Boot Sequence 31 IBM AIX: Modifying the UNIX Boot Sequence 31 Specifying Automatic Start for a DMI Listener 34 Changing the Daemon Port 37 Securing Colleague Connections 37 In This Chapter 38 Understanding Security for Colleague Connections 39 Certificates 40 Signed Certificate Managing Colleague Software Environments, January 31,

6 Table of Contents 40 Client Authentication Certificate 40 Public Certificates 41 Intermediate Certificates 41 Connection Between the DMI Application Server and the Colleague Executables 42 Connection Between the DMI Data Access Server and the Application Server 42 Connection Between the DMI Application Server and WebAdvisor 43 Connection Between SA Valet and the Daemon 44 High Level Procedure for Securing Colleague 46 Procedures for Securing Colleague Connections 46 Managing the Connection Between the DMI Application Server and the Colleague Executables 47 Securing the Connection Between the DMI Data Access Server and the Application Server 49 Securing a DMI Listener 51 Securing the Connection Between the DMI Application Server and WebAdvisor 52 Securing the Connection Between SA Valet and the Datatel Daemon 52 Specifying the Security Level in the Daemon and in SA Valet 54 Establishing Client Authentication for the SA Valet-Daemon Connection 58 Procedures for Installing and Managing Certificates 58 Generating the Request for a Signed Certificate 61 Installing a Signed Certificate 63 Renewing a Signed Certificate 66 Generating a Client Authentication Certificate 69 Examining a Certificate 70 Deleting a Certificate 72 Installing a Public Certificate 73 Managing Public Certificates 75 Examining a Public Certificate 76 Viewing an Encoded Certificate 77 Deleting a Public Certificate 79 Enabling Windows Authentication (SQL Server) 79 In This Chapter 80 Understanding Windows Authentication 80 Windows Authentication 6 Managing Colleague Software Environments, January 31, 2013

7 Table of Contents 82 SQL Server Authentication 84 Dual SQL Server Logins 86 Procedures for Setting Up Windows Authentication 86 Setting Up Windows Authentication in Colleague 88 Creating the Administrative User in the Windows Domain 89 Enabling Single-Role Colleague Access (SQL Server and Oracle) 89 In This Chapter 90 Understanding Single-Role Access 90 Database Access Without Single-Role Access 91 Database Access With Single-Role Access Enabled 93 Procedures for Enabling Single-Role Access for SQL Server 93 Creating the Colleague Access Role in SQL Server 94 Setting Up Users in SQL Server 95 Enabling SQL Server Single-Role Access in Colleague 98 Procedures for Enabling Single-Role Access for Oracle 98 Creating the Colleague Access Role in Oracle 100 Setting Up Users in Oracle 100 Granting the Colleague Access Role 100 Reviewing Other Privileges Granted to Users 101 Enabling Oracle Single-Role Access in Colleague 105 Administration and Monitoring 107 Starting and Stopping DMI Listeners and Daemons 107 In This Chapter 108 Starting and Stopping DMI Listeners 108 Local Product Repository DMI_DAS 108 Starting the Local Product Repository DMI_DAS 109 Stopping the Local Product Repository DMI_DAS 110 Application Environment Listeners 110 Starting and Stopping All Listeners in an Application Environment 111 Starting and Stopping Individual Listeners in an Application Environment 112 Listener Status Indicators 114 Starting and Stopping Datatel Daemons 114 Starting a Datatel Daemon 115 Starting a Datatel Daemon on UNIX or Linux 115 Starting a Datatel Daemon on Windows Managing Colleague Software Environments, January 31,

8 Table of Contents 116 Stopping a Datatel Daemon 116 Stopping a Datatel Daemon on UNIX or Linux 117 Stopping a Datatel Daemon on Windows 117 Daemon Status Indicators 118 Refreshing Daemon Status Indicators 119 Monitoring DMI Listeners 119 In This Chapter 120 Understanding DMI Listener Monitoring 121 DMI Statistics Tables 121 Understanding the DMI Statistics Tables 125 Procedure for Defining the Refresh Interval 125 Procedure for Viewing the Statistics Tables 129 DMI Statistics Log File 129 Understanding the Log File 130 Procedure for Starting and Stopping Logging 132 Procedure for Purging Log Files 133 Memory Monitor 135 Configuration 137 Removing an Application Environment 137 In This Chapter 138 Understanding Application Environment Removal 139 Procedures for Removing an Application Environment 139 Deleting Environment Information from Colleague 140 Setting up an Environment as Production 142 Deleting the Colleague Executables 142 Deleting the Colleague Database 142 SQL Server or Oracle 142 UniData 143 Deleting DMI Listener Files 145 Creating a Training Environment 145 In This Chapter 146 Understanding Training Environments 146 Process for Creating a Training Environment 148 Procedures for Creating a Training Environment 149 Creating the Training Source Environment 149 Retrieving the Training Data Set from Ellucian 151 Installing the Data Set in the Training Source Environment 154 Setting Up the Training Source Environment 8 Managing Colleague Software Environments, January 31, 2013

9 Table of Contents 154 Setting Up Users 154 Creating Computed Columns for General Ledger 155 (Canadian Clients Only) Modifying International Parameters 155 Do Not Enter Your Own Data In the Training Source Environment 155 Creating a Training Environment 156 Refreshing a Training Environment 156 Updating the Training Source Environment With a New Data Set From Ellucian 157 View Environment Configuration 157 In This Chapter 158 Before You Begin 159 Viewing an Environment Configuration 161 Automatic Send to Ellucian Feature 162 Manual Send to Ellucian Feature 162 Why should I send my configuration information to Ellucian? 162 Procedure for Viewing an Environment Configuration 167 Moving a Local Product Repository 167 In This Chapter 168 Understanding Moving a Local Product Repository 168 Restrictions on Moving an LPR 168 Procedure for Moving an LPR 172 Troubleshooting 172 Technical Details 175 Resetting an LPR in a Restored Environment 175 In This Chapter 176 Understanding an LPR Reset 176 Restrictions on Resetting an LPR 176 Security Class 177 Procedure for Resetting an LPR 181 Changing Database Properties 181 In This Chapter 182 Changing Database Properties 184 Changing the Alias / DNS Name of the Database Server 185 Changing the Database Port 185 Changing the Database Name / Path Managing Colleague Software Environments, January 31,

10 Table of Contents 187 Appendices 1 DMI Listener Names 1 Listener Naming Convention 1 Accessing Colleague from SA Valet 1 In This Appendix 2 Connecting to the Local Product Repository from SA Valet 5 Connecting to an Application Environment from SA Valet 8 Storing Login Information in the Login Vault 9 How to Use the Login Vault 10 Forgot the Password? 11 Using SA Valet Without the Login Vault 11 Changing the Login Vault Password 13 Glossary 13 In This Appendix 21 Index 10 Managing Colleague Software Environments, January 31, 2013

11 Managing Colleague Software Environments Introduction

12

13 Introduction 0 About This Manual Who Should Read This Manual Anyone responsible for maintaining and monitoring Colleague Release 18 should read this manual. What This Manual Covers This manual provides instructions for configuring, maintaining, and monitoring your Colleague Release 18 application environments. See How This Manual is Organized on page 14 for details about the information in each chapter and appendix. Other manuals providing information about installing and maintaining Colleague are: The Installation Procedures for Release 18 provides procedures for creating a Colleague application environment. Updating Colleague Software provides procedures for updating your Colleague application environments with software updates from Ellucian. Envision Run-Time Administration provides procedures for setting up and maintaining the Envision-based software used for Colleague. Managing Colleague Software Environments, January 31,

14 Introduction: About This Manual How This Manual is Organized This manual is organized is the following manner: Part 1, Introduction, contains information about this manual and how it is organized. Part 2, Setup and Customization, contains information for specifying Listener memory characteristics, securing connections, enabling Windows authentication, and enabling single-role access. Part 3, Administration and Monitoring, contains information for starting and stopping Listeners, and information for monitoring performance. Part 4, Configuration, contains information for removing an environment, creating a training environment, and viewing environment configuration information. The Appendices contain standard information about Colleague Release 18. Where to Find More Information Table 1 lists sources of information that provide additional assistance in installing and administering Colleague. Other procedure manuals for using Colleague are available from the Documentation area of the client web site ( Table 1: Additional Sources of Information for Colleague Installation Type of Information Installing a full release of Colleague. Updating your Colleague application environments with software updates from Ellucian. Setting up and maintaining the Envision-based software used for Colleague. Source Installation Procedures for Release 18 Updating Colleague Software Envision Run-Time Administration 14 Managing Colleague Software Environments, January 31, 2013

15 Managing Colleague Software Environments Setup and Customization

16

17 Setup and Customization Authorizing an Application Server (UniData) In This Chapter This chapter contains the procedure for authorizing a UniData Application Server. Table 2 lists the topics covered in this chapter. Table 2: Topics in This Chapter Topic Understanding Application Server Authorization 18 Page Procedures for Authorizing an Application Server 18 Managing Colleague Software Environments, January 31,

18 Setup and Customization: Authorizing an Application Server (UniData) Understanding Application Server Authorization For UNIX, you will need to configure UniData server authorization parameters for an Application server. Using SA Valet, configure the following: Make sure that the daemon user has read/write permissions to the UDTHOME/include/sysconfig file. Make sure that the daemon user has read/write permissions to the product.list and product.info files in the UDTBIN and UDTHOME/include directories (to be able to run the confcmd command). Make sure UniRPC services are running. UDTHOME/UDTBIN is used to determine which installation is being authorized. You must restart UniData as the final step to complete the authorization process. Procedures for Authorizing an Application Server This section contains the procedures for authorizing an application server using SA Valet. Accessing the Authorize Application Server Form In order to access the form to authorize a UniData Application server, you must complete the following steps. Step 1. In SA Valet, select the Hosts tab. Step 2. Select a UniData Application server node (Figure 1 on page 19). 18 Managing Colleague Software Environments, January 31, 2013

19 Procedures for Authorizing an Application Server Figure 1: Select a UniData Application Server Node Step 3. Right-click and select Authorize. Figure 2: Select the Authorize Option Configuring the Authorize Application Server Form Complete the Authorize Application Server form to configure your UniData server authorization parameters for an Application server. Managing Colleague Software Environments, January 31,

20 Setup and Customization: Authorizing an Application Server (UniData) Figure 3: Authorize Application Server Form Step 1. Go to the Authorize Application Server form. See Accessing the Authorize Application Server Form on page 18. Step 2. The Status field displays the current authorization status of this Application server. Step 3. In the Serial number field, maintain the serial number associated with this Application server. For example, enter for the complete serial number UDT. You need to enter the serial suffix separately. 20 Managing Colleague Software Environments, January 31, 2013

21 Procedures for Authorizing an Application Server Step 4. In the Serial suffix field, maintain the suffix to the serial number for this Application server. For example, enter UDT for the complete serial number UDT. Note that the suffix is case sensitive. Step 5. In the Number of users field, specify or view the number of users that can use this Application server concurrently. Step 6. In the Version field, maintain the UniData version number associated with this Application server. Step 7. In the Expiration date field, maintain the date in mm/dd/yyyy format after which authorization to use this Application server will expire. Step 8. The NFA Service field enables the Network File Architecture (NFA) Service which offers local access to data on remote UniData servers. Leave the check box cleared since this option is not supported by Colleague at this time. Step 9. The RFS field enables Recoverable File System (RFS) which provides the ability to recover in case of a system or media failure. Leave the check box cleared since this option is not supported by Colleague at this time. Step 10. The EDA field enables External Data server Access (EDA) which provides the ability to store one or more UniData files on an external data server in a manner that is transparent to the application. Leave the check box cleared since this option is not supported by Colleague at this time. Step 11. The Number of connection pooling users field controls the number of connection pooling users allowed on this Application server. Connection Pooling (CP) enables developers to design and deploy applications that do not use persistent connections to the data server. Enter 0 since this option is not supported by Colleague at this time. Step 12. The Number of connections per device field controls the number of connection pools authorized per device on this Application server. Connection Pools are authorized separately and do not consume data server licenses. Enter 0 since this option is not supported by Colleague at this time. Managing Colleague Software Environments, January 31,

22 Setup and Customization: Authorizing an Application Server (UniData) Step 13. In the Name field, maintain the author s name for this Application server authorization. Step 14. In the field, maintain the address associated with the author of this Application server authorization. Step 15. In the Company field, maintain the company associated with the author of this Application server authorization. Step 16. In the User name field, maintain the UniRPC user name for this Application server. Step 17. In the Password field, maintain the UniRPC password for this Application server. Step 18. In the Install path field, maintain the installation path to use for this Application server authorization. For example, c:\ibm\ud72 Step 19. You must restart UniData as the final step to complete the authorization process. 22 Managing Colleague Software Environments, January 31, 2013

23 Setup and Customization Defining DMI Listener and Daemon Parameters In This Chapter This chapter contains procedures for specifying parameters for DMI Listeners and Datatel daemons. Table 3 lists the topics in this chapter. Table 3: Topics in this Chapter Topic Page Specifying Listener Memory Allocation 24 Automatically Starting DMI Listeners and Daemons 28 Changing the Daemon Port 34 Managing Colleague Software Environments, January 31,

24 Setup and Customization: Defining DMI Listener and Daemon Parameters Specifying Listener Memory Allocation Typically, Java processes are allocated a limited amount of memory. You can specify both the minimum amount of memory, which is the memory allocated to the Listener at Listener startup, and the maximum amount of memory. As delivered, DMI Listeners are allocated a maximum memory of 512 MB. There is no default minimum. However, you may need to change these values for specific Listeners. The required amount of memory depends on the following factors: Listener role. For example, the DMI data access server requires more memory than the DMI application server. Number of users. The required memory may be different for a production application environment than for a test application environment. See AnswerNet page 4516 for recommended memory values. Syntax for Specifying Listener Memory Listener memory parameters are defined on the Listener Startup Properties form (Figure 7 on page 33), in the Java Virtual Machine Arguments field. Both minimum and maximum memory are specified on the same line, with the arguments separated by a space. Table 4 shows the syntax for specifying each parameter. Check your Java documentation to confirm the syntax. Table 4: Syntax for Specifying Listener Memory Parameters Parameter Syntax Example Minimum memory Maximum memory -Xms###M where ### is megabytes of memory -Xmx###m where ### is megabytes of memory -Xms128M -Xmx512m 24 Managing Colleague Software Environments, January 31, 2013

25 Specifying Listener Memory Allocation Figure 4: Listener Memory Parameters on the Listener Startup Properties Form Procedure for Specifying Listener Memory Allocation Use the procedure below to specify Listener memory allocation. Step 1. Review AnswerNet page 4516 to identify recommended memory allocation for DMI Listeners in this application environment. Step 2. In SA Valet, connect to the application environment for which you want to specify Listener memory parameters, if not already connected. Managing Colleague Software Environments, January 31,

26 Setup and Customization: Defining DMI Listener and Daemon Parameters See Accessing Colleague from SA Valet on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. You are already connected if the application environment node is expanded to display other nodes as shown in Figure 5 on page 26. Step 3. Perform the following steps for each Listener for which you want to specify memory parameters. a. Right-click the node for the Listener and select Properties from the popup menu (Figure 5). The example in Figure 5 is for the DMI application server (the node whose name ends with APP_LISTENER ). For the DMI data access server, the node name ends with DB_LISTENER. Figure 5: Listener Properties Menu Option b. On the Listener Startup Properties form (Figure 7 on page 33), in the JVM Arguments field, specify the minimum and maximum memory based on the recommendations in AnswerNet page Example:-Xmx512m -Xms128M Note: If you don t specify the memory on this form, the Listener will use the default maximum memory of 512 MB. There is no default minimum. 26 Managing Colleague Software Environments, January 31, 2013

27 Specifying Listener Memory Allocation c. Click OK to save the changes. For Windows, the process will automatically stop the Listener in order to write the new properties to the Windows Registry. After the process is complete, restart the Listener. For UNIX or Linux, the process will not stop the Listener. You must manually stop and restart the Listener in order for the new properties to take effect. See Starting and Stopping DMI Listeners on page 108. d. Repeat Steps a through c for each Listener for which you want to specify memory parameters. Each Colleague application environment includes at least two DMI Listeners (a DMI application server and a DMI data access server). In addition, you may have installed other DMI Listeners, such as a DMI print server and DMI RPC server. Managing Colleague Software Environments, January 31,

28 Setup and Customization: Defining DMI Listener and Daemon Parameters Automatically Starting DMI Listeners and Daemons ALERT! Ellucian strongly recommends that UNIX clients set the daemon and all Listeners to auto-start. Otherwise, when you restart the Listener, you will be prompted for a username and password. That username and password are stored in the process command stack and can be viewed by other users (for example, by using the ps command). DMI Listeners can be set to automatically restart when the computer that hosts the DMI Listener is restarted. The default setting, and the method for specifying auto-start, depends on the type of DMI Listener (Table 5). Table 5: DMI Listener Auto-Start Settings Type of DMI Listener DMI data access server for the local product repository DMI Listeners in application environments Auto-Start Default Enabled Disabled Where to Enable/Disable Auto-Start Listener Startup Properties form (see procedure on page 31) Datatel daemons Enabled Setting cannot be changed To enable Listener auto-start on UNIX or Linux operating systems, you must also add the Listener start script to the boot sequence using the procedure on page 29. Table 6 lists the procedures in this section. Table 6: Procedures for Enabling DMI Listener Auto-Start Procedure Page Adding the Listener Start Script to the Boot Sequence (UNIX/Linux Only) 29 Specifying Automatic Start for a DMI Listener Managing Colleague Software Environments, January 31, 2013

29 Automatically Starting DMI Listeners and Daemons Adding the Listener Start Script to the Boot Sequence (UNIX/Linux Only) Perform the appropriate procedure below for your operating system to include the script for starting the DMI Listeners in the UNIX or Linux boot sequence. Before performing this procedure, identify the daemon home directory (the directory where you installed the Datatel daemon). To determine the daemon home directory, view the /etc/datateltab file and look for a line like the following: 0:daemon:/datatel/coll18/daemon:/opt/java1.6:Y In this example, the daemon home directory is /datatel/coll18/daemon. For all UNIX and Linux platforms, UniData must be started before any Listeners on that computer are started. Even if you are using Oracle, this applies to the application server computer where the DMI application server (a DMI Listener) is installed. To start UniData before the Listeners, you must create a script to start UniData, and create a symbolic link for the script, with the following properties: The UniData symbolic link must be at a lower run level than the link for the Listener script, or, if at the same run level, must have a lower integer. For example, the UniData symbolic link could be at run level 2 and the Listener symbolic link at run level 3. Or, if at the same run level, the UniData symbolic link could be S50 and the Listener symbolic link could be S99. The script must have the variable LANG set to C before the UniData start command. This ensures that UniRPC starts properly, which is required for Listener auto-start. Example commands: LANG=C;export LANG /usr/ud61/bin/startud HP-UX: Modifying the UNIX Boot Sequence Step 1. Copy the dmiservice file from the daemon home directory to the /sbin/init.d scripts folder. Example command: cp /datatel/coll18/daemon/scripts/dmiservice / sbin/init.d/dmiservice Managing Colleague Software Environments, January 31,

30 Setup and Customization: Defining DMI Listener and Daemon Parameters Step 2. Create a symbolic link from the rc2.d directory to the dmiservice file. Choose a unique number within the directory. Generally, user applications like this one use a high number, for example in the high 900s. Example command: ln -s /sbin/init.d/dmiservice /sbin/rc2.d/ S999dmiservice SUN Solaris: Modifying the UNIX Boot Sequence Step 1. Copy the dmiservice file from the daemon home directory to the /etc/init.d scripts folder. Example command: cp /datatel/coll18/daemon/scripts/dmiservice /etc/ init.d/dmiservice Step 2. Create a symbolic link from the rc2.d directory to the dmiservice file. Choose a unique number within the directory. Generally, user applications like this one use a high number, for example in the high 90s. Example command: ln -s /etc/init.d/dmiservice /etc/rc2.d/ S99dmiservice Red Hat Linux: Modifying the Boot Sequence Step 1. Copy the dmiservice file from the daemon home directory to the /etc/init.d scripts folder. Example command: cp /datatel/coll18/daemon/scripts/dmiservice /etc/ init.d/dmiservice Step 2. Create a symbolic link to the dmiservice file in the default run level for the Linux server (typically Level 3). Choose a unique number within the directory. Generally, user applications like this one use a high number, for example in the high 90s. Example command: ln -s /etc/init.d/dmiservice /etc/rc3.d/ S99dmiservice 30 Managing Colleague Software Environments, January 31, 2013

31 Automatically Starting DMI Listeners and Daemons IBM AIX: Modifying the UNIX Boot Sequence Step 1. Add a line to the /etc/inittab file to run the dmiservice script with the start parameter. Example command (all on one line): dmiservice:2:once:/datatel/coll18/daemon/scripts/ dmiservice start >/dev/console 2>&1 Note that the second parameter must be a 2 because this is a user application. Specifying Automatic Start for a DMI Listener Perform the following procedure to enable or disable auto-start for DMI Listeners in the local product repository or application environments. This procedure does not apply for Datatel daemons, for which auto-start is enabled and cannot be changed. Step 1. In SA Valet, connect to the local product repository if not already connected. See Connecting to the Local Product Repository from SA Valet on page 2 for the detailed procedure for connecting to the local product repository. Step 2. If you are enabling or disabling auto-start for the Listeners in an application environment, connect to that application environment. See Connecting to an Application Environment from SA Valet on page 5 for the detailed procedure for connecting to the application environment. You are already connected if the application environment node is expanded to display other nodes as shown in Figure 6 on page 32. You can skip this step if you are enabling or disabling auto-start for the DMI data access server for the local product repository. Managing Colleague Software Environments, January 31,

32 Setup and Customization: Defining DMI Listener and Daemon Parameters Step 3. Perform the following steps for each Listener for which you want to enable or disable auto-start. a. Right-click the node for the Listener and select Properties from the popup menu (Figure 6 on page 32). The example in Figure 6 is for the DMI application server (the node whose name ends with APP_LISTENER ). For the DMI data access server in the application environment, the node name ends with DB_LISTENER. If you want to select the DMI data access server for the local product repository, select the local product repository node. Figure 6: Listener Properties Menu Option b. On the Listener Startup Properties form (Figure 7), select or clear the Automatic Startup check box: 32 Managing Colleague Software Environments, January 31, 2013

33 Automatically Starting DMI Listeners and Daemons Figure 7: Listener Startup Properties Form c. Click OK to save the changes. d. Repeat Steps a through c for each Listener that you want to automatically start. Each Colleague application environment includes at least two DMI Listeners (a DMI application server and a DMI data access server). In addition, you may have installed other DMI Listeners, such as a DMI print server and DMI RPC server. Managing Colleague Software Environments, January 31,

34 Setup and Customization: Defining DMI Listener and Daemon Parameters Changing the Daemon Port When you install a daemon, it is set to listen on Port Use the following procedure if you want to change that port. Step 1. On the host computer where the daemon is installed, access the dmi.ini file in a text editor. The dmi.ini file is located in the daemon installation directory that you selected when you ran the daemon InstallShield. Step 2. Edit the DaemonPort line to the desired port. Example: DaemonPort=8800 Step 3. Save the changes to the dmi.ini file. Step 4. Stop and restart the daemon so that the change will take effect. See Starting and Stopping Datatel Daemons on page 114 for the procedure for stopping and starting the daemon. Perform the rest of this procedure on each SA Valet installation that you use to access Colleague. Step 5. In SA Valet, select the Hosts tab. Step 6. Right-click the node for the computer where the daemon is installed, and select Edit Connection from the pop-up menu (Figure 8). 34 Managing Colleague Software Environments, January 31, 2013

35 Changing the Daemon Port Figure 8: Selecting Host Machine Connection Properties in SA Valet Step 7. On the Host Connection form (Figure 9), enter the new port number in the Daemon Port # field. Figure 9: Changing the Daemon Port on the Host Connection Form Step 8. Click OK to change the port. Managing Colleague Software Environments, January 31,

36 Setup and Customization: Defining DMI Listener and Daemon Parameters 36 Managing Colleague Software Environments, January 31, 2013

37 Setup and Customization Securing Colleague Connections In This Chapter This chapter contains procedures for securing connections between Colleague software components. Table 7 lists the concepts and procedures covered in this chapter. Table 7: Topics in this Chapter Topic Page Understanding Security for Colleague Connections 38 Procedures for Securing Colleague Connections 46 Procedures for Installing and Managing Certificates 58 Managing Colleague Software Environments, January 31,

38 Setup and Customization: Securing Colleague Connections Understanding Security for Colleague Connections This section provides background information about securing connections between Colleague components. Table 8 lists the topics covered in this section. Table 8: Topics in this Section Topic Page Certificates 39 Connection Between the DMI Application Server and the Colleague Executables Connection Between the DMI Data Access Server and the Application Server Connection Between the DMI Application Server and WebAdvisor 42 Connection Between SA Valet and the Daemon 43 Step-by-step procedures for securing Colleague connections begin on page 46. Figure 10 on page 39 shows the Colleague connections addressed in this chapter. Note that Figure 10 show a Datatel daemon installed on an application server computer and a database computer. Your configuration might be different. For example, you might have just one computer instead of two, with the Colleague executables and data on the same computer. Or, you might have additional computers that host a Datatel daemon (such as a DMI print server). 38 Managing Colleague Software Environments, January 31, 2013

39 Understanding Security for Colleague Connections Figure 10: Colleague Connections That Can be Secured SA Valet computer Application server computer Database computer SA Valet Daemon Daemon DMI application server DMI data access server Colleague executables Web server computer Web server software WebAdvisor See the User Interface Installation and Administration manual for the procedure for securing this connection. UI client computer UI client Certificates Security for Colleague connections is supplied by a combination of a signed or client authentication certificate, which contains a private key, and a public certificate, which contains the corresponding public key. You can install all of these types of certificates from SA Valet. Managing Colleague Software Environments, January 31,

40 Setup and Customization: Securing Colleague Connections Signed Certificate A signed certificate is a certificate obtained from a certificate authority such as VeriSign. Signed certificates are used for securing a server that communicates with any machine outside of your firewall. For example, if you are using WebAdvisor to process credit card payments, you must install a signed certificate on the application server computer. The process for installing a signed certificate includes the following steps: From SA Valet, generate a request for the signed certificate. Send the request to the certificate authority. After receiving the signed certificate, install it using SA Valet. Client Authentication Certificate A client authentication certificate is similar to a VeriSign Class 1 certificate. A client authentication certificate authenticates the validity of client connection. A client authentication certificate may only be used to authenticate the connection from SA Valet to a daemon. Public Certificates To verify that a signed or client authentication certificate is authentic, the receiver needs the corresponding public key, which is stored in a public certificate. Public certificates are also known as root certificates. For signed certificates, which come from certificate authorities, the corresponding public certificate is supplied by the certificate authority (CA). CA public certificates from the major certificate authorities are delivered with the following software: Web browsers. Web server software. SA Valet. Public certificates are stored in the following folder: C:\Program Files\Datatel\SaValet 2.7.0\security\clientcas. Datatel daemon. Public certificates are stored in the /security/clientcas subdirectory. If the required public certificate is delivered with the software, you don t need to do anything to install it. 40 Managing Colleague Software Environments, January 31, 2013

41 Understanding Security for Colleague Connections However, for client authentication certificates, you need to install the public certificate using SA Valet. Even for signed certificates, there are cases where a required public certificate is not delivered with the software. In particular, there are two cases where you may want to import and install a CA public certificate manually to a Web server, to SA Valet, or to a daemon: You want to import a CA public certificate that was not shipped with the software. You have installed a trial server certificate in your test environment, requiring a matching test CA public certificate to be installed to SA Valet and the Web server in the test environment. Intermediate Certificates Some CA s also generate an intermediate certificate. Intermediate certificates are used to add an extra level of security between signed certificates and the CA public (root) certificate. A public certificate and an intermediate certificate together are sometimes referred to as a chained certificate. To install an intermediate certificate, paste the intermediate certificate immediately after the signed certificate in the Insert Certificate window in SA Valet. See Installing a Signed Certificate beginning on page 61 for the procedure. Connection Between the DMI Application Server and the Colleague Executables This connection is not secured with certificates. Ellucian recommends specifying the loopback address ( ) for communications, so that transactions are kept local to the computer on which the DMI application server and the Colleague executables are installed. Use the procedure on page 46. Managing Colleague Software Environments, January 31,

42 Setup and Customization: Securing Colleague Connections Connection Between the DMI Data Access Server and the Application Server If you have multiple networks connecting your DMI Data Access Server and Application Server, you can choose to Enable Private IP support which can increase throughput between the servers. If your database server has both a public IP and a private IP address, and you do not choose to enable the Private IP option, then the public IP address will be used automatically. See Securing the Connection Between the DMI Data Access Server and the Application Server on page 47 for the step-by-step procedure. Connection Between the DMI Application Server and WebAdvisor Figure 11 shows the components involved in the connection between the DMI application server and WebAdvisor, and the certificates needed to secure that connection. Figure 11: Components and Certificates for a Secure Connection Between the DMI Application Server and WebAdvisor Application server computer DMI application server Server Cert A Web server computer Web server software Public Cert A Securing this connection requires that you do the following: Install a signed certificate on the computer that hosts the DMI application server (Server Cert A in Figure 11). If you already installed a signed certificate to support secure communications between the daemon on that computer and SA Valet, you don t need to take any further action for the signed certificate. Ensure that a public certificate that is compatible with the signed certificate is installed with the Web server (Public Cert A in Figure 11). If you installed a signed certificate, the corresponding public certificate most 42 Managing Colleague Software Environments, January 31, 2013

43 Understanding Security for Colleague Connections likely was delivered with the Web server software. If not, you can install it from SA Valet. Specify a secure port for the DMI application server. Specify the certificate vault password on the Listener Startup Properties form. Specify secure transmittals from the Web server to the DMI application server. See Securing the Connection Between the DMI Application Server and WebAdvisor on page 51 for the step-by-step procedure. Connection Between SA Valet and the Daemon Figure 12 shows the components involved in the connection between SA Valet and the Datatel daemon, and the certificates needed to secure that connection. Three levels of security are available for this connection. Table 9 describes each level and lists the certificates required to achieve that level of security. Ellucian recommends using client-authenticated SSL to secure each of these connections. See Securing the Connection Between SA Valet and the Datatel Daemon on page 52 for the step-by-step procedure for securing this connection. Figure 12: Components and Certificates for a Secure Connection Between SA Valet and the Daemon SA Valet computer Application server computer Database computer SA Valet Daemon Daemon Public Cert A Public Cert B ClientAuthentication Cert C* Server Cert A Public Cert C* Server Cert B Public Cert C* *Required only for client-authenticated SSL Managing Colleague Software Environments, January 31,

44 Setup and Customization: Securing Colleague Connections High Level Procedure for Securing Colleague Table 9: Security Levels for the SA Valet-Daemon Connection Security Level Description Certificates Required for this Level of Security None Connection is not secure. SSL Client-authenticated SSL Communications are encrypted. Communications are encrypted and SA Valet is authenticated when it attempts to contact the daemon. Install a signed certificate on the computer that hosts the daemon (Server Certs A and B in Figure 12). If necessary, install an intermediate certificate with the server certificate (required only if instructed to do so by the certificate authority). Same as above, plus: Install a client certificate with SA Valet (Client Authentication Cert C in Figure 12). Use this high level procedure as a guide for the overall process for securing Colleague. Be sure to conduct thorough testing for each connection you secure before moving on to the next step. Step 1. Manage communications between the DMI application server and the Colleague executables. Complete Managing the Connection Between the DMI Application Server and the Colleague Executables on page 46 to complete this step. Step 2. Secure communications between the DMI application server and the DMI data access server (DAS). Complete Securing the Connection Between the DMI Data Access Server and the Application Server on page 47 to complete this step. Step 3. Install a signed certificate on each host. Complete Generating the Request for a Signed Certificate on page 58 and Installing a Signed Certificate on page 61 to request and install a signed certificate on each host. Step 4. Secure communications for DMI Listeners. 44 Managing Colleague Software Environments, January 31, 2013

45 Understanding Security for Colleague Connections Complete Securing a DMI Listener on page 49 for each DMI Listener that you want to secure, including any Listeners used for style sheet printing. Step 5. Secure communications from WebAdvisor to the DMI application server. Complete Securing the Connection Between the DMI Application Server and WebAdvisor on page 51 to complete this step. Step 6. Optional. Authenticate communications between SA Valet and all daemons. See Securing the Connection Between SA Valet and the Datatel Daemon on page 52 for more information. Managing Colleague Software Environments, January 31,

46 Setup and Customization: Securing Colleague Connections Procedures for Securing Colleague Connections This section contains procedures for securing connections between Colleague components. Where certificates are used, these procedures refer to the detailed procedures in Procedures for Installing and Managing Certificates beginning on page 58. Table 10 lists the topics covered in this section. Table 10: Topics in this Section Topic Managing the Connection Between the DMI Application Server and the Colleague Executables Securing the Connection Between the DMI Data Access Server and the Application Server Page Securing a DMI Listener 49 Securing the Connection Between the DMI Application Server and WebAdvisor 51 Securing the Connection Between SA Valet and the Datatel Daemon 52 Managing the Connection Between the DMI Application Server and the Colleague Executables The connection between the DMI application server and the Colleague executables is not secured with certificates. Ellucian recommends specifying the loopback address ( ) for communications, so that transactions are kept local to the computer on which the DMI application server and the Colleague executables are installed. Use the procedure below. Step 1. From User Interface, access the Define Account WebConfig (DWEB) form (Figure 13). 46 Managing Colleague Software Environments, January 31, 2013

47 Procedures for Securing Colleague Connections Figure 13: Define Account WebConfig (DWEB) Form Step 2. In the DMI Listener IP Address field, enter Step 3. Save your changes on the DWEB form. Securing the Connection Between the DMI Data Access Server and the Application Server The connection between the DMI data access server (DAS) and the application server can be made with either a public or private IP address (such as using a crossover cable). Use a private IP address to secure the connection between the DAS and the application server. Perform the following procedure to enable private IP support. Step 1. In SA Valet, connect to the application environment if not already connected. Managing Colleague Software Environments, January 31,

48 Setup and Customization: Securing Colleague Connections See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded, you are already connected. Step 2. Right-click the application environment node and select Database Access Server Properties from the pop-up menu. The Database Access Server Properties form displays, as shown in Figure 14. Figure 14: Database Access Server Properties Private IP Support Set Up 48 Managing Colleague Software Environments, January 31, 2013

49 Procedures for Securing Colleague Connections Step 3. On the Database Access Server Properties form, enter the following information: Enable Private IP. Check this box to use a private IP address. Database Host Private IP. Enter the private IP address to use when connecting the servers. If you are running in a combined environment, you can use the loopback address ( ). Technical Tip: If you specified the same server host name for the database and application servers when you created the application environment, using either the Set Up Colleague Application Environment wizard or the Clone Application Environment wizard, then the wizard automatically specifies the loopback address. You do not need to use this procedure to specify it. Step 4. Click OK. Note: Enabling or disabling this option will stop and restart the Database Access Server (DAS) and all application Listeners. Securing a DMI Listener Before starting this procedure, you must first install a signed certificate on the host for each DMI Listener you want to secure. See Generating the Request for a Signed Certificate on page 58 for the procedure. Note: In order to access this secure port from WebAdvisor, you must also set up WebAdvisor to use a secure port when communicating with the DMI application server. See the WebAdvisor Installation and Administration manual for the procedure. Step 1. In SA Valet, connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded, you are already connected. Step 2. Right-click on the node for the DMI Listener for which you want to specify security, and then click Properties. The Listener Startup Properties form displays, as shown in Figure 15. Managing Colleague Software Environments, January 31,

50 Setup and Customization: Securing Colleague Connections Figure 15: Specifying the Certificate Vault Password for a Listener Step 3. In the Host Certificate Vault Password field, enter the certificate vault password that is associated with the certificate vault on the server where the Listener resides. Step 4. Enter the DMI Listener s secure port number in the Secure SSL Port field. Step 5. If you want the Listener to use only the secure port for communications, select Force Server SSL. Note: Only select this option after extensive testing to ensure communication occurs properly on the secure port. With this option selected, the Listener will not allow connections to the non-secure port if communication on the secure port fails. Step 6. Click OK to close the form and save your changes. 50 Managing Colleague Software Environments, January 31, 2013

51 Procedures for Securing Colleague Connections Securing the Connection Between the DMI Application Server and WebAdvisor Perform this procedure to establish a secure connection between the DMI Application Server and WebAdvisor. Follow Step 1 through Step 3 to install a public certificate on the Web server software to support secure communications with the DMI application server. If the Web server software already has the required public certificate from the certificate authority, skip to Step 4. Most Web server software has the public certificates for the more popular certificate authorities included. Step 1. Obtain the public certificate (also known as a root certificate) from the certificate authority (CA). For example, if your CA is VeriSign, you can download the root certificates from pca_certificate.html. Contact your CA for specific instructions on how to obtain their root certificates. Step 2. Manually add the certificate as a pem file to the clientcas folder under the WebAdvisor deployment directory. Step 3. If this is a WebAdvisor 3.x installation, rebuild and redeploy the WAR file. See the WebAdvisor Installation and Administration manual for the procedure. Step 4. Specify secure transmittals between the Web server and the DMI application server, using the procedure in the WebAdvisor Installation and Administration manual. Managing Colleague Software Environments, January 31,

52 Setup and Customization: Securing Colleague Connections Securing the Connection Between SA Valet and the Datatel Daemon See Connection Between SA Valet and the Daemon on page 43 for a description of securing this connection. Before performing the procedures in this section, do the following: Decide on a security level (SSL or client-authenticated SSL). See Connection Between SA Valet and the Daemon on page 43 for a description of the security levels. Select a server certificate type (signed or client authentication) for each computer that hosts a daemon. If you have secured the DMI Listeners on each host, you already have a signed certificate installed on those hosts. See Certificates on page 39 for considerations. Based on the selected security level and server certificate type, perform the applicable procedures listed in Table 11. Table 11: Procedures Required for SA Valet-Daemon Security Security Type Required Procedures Note SSL Client authenticated SSL Installing a Signed Certificate on page 61 Specifying the Security Level in the Daemon and in SA Valet on page 52 All of the above plus: Establishing Client Authentication for the SA Valet-Daemon Connection on page 54 If you previously secured a DMI Listener on the same machine as the daemon, you already installed a signed certificate that can be used to secure communications to the daemon. You do not need to install another signed certificate. In order to use client authenticated SSL, you must first have a signed certificate. Specifying the Security Level in the Daemon and in SA Valet Perform this procedure for each computer on which you have installed a Datatel daemon. Step 1. On the host computer where the daemon is installed, access the dmi.ini file in a text editor. 52 Managing Colleague Software Environments, January 31, 2013

53 Procedures for Securing Colleague Connections The dmi.ini file is located in the daemon installation directory that you selected when you ran the daemon InstallShield. Step 2. Which type of secure connection do you want to use? SSL. Edit the SecurityType line to SecurityType=SSL. Continue with Step 3. Client authenticated SSL. Edit the SecurityType line to SecurityType=CLIENTSSL. Complete Establishing Client Authentication for the SA Valet-Daemon Connection on page 54 before continuing with the rest of this procedure. Step 3. Save the changes to the dmi.ini file. Step 4. Stop and restart the daemon so that the change will take effect. See Starting and Stopping Datatel Daemons beginning on page 114 for the procedures. Step 5. In SA Valet, select the Hosts tab. Step 6. Right-click the node for the host computer on which the daemon is installed, and select Edit Connection from the pop-up menu. The Host Connection form is displayed, as shown in Figure 16. Figure 16: Selecting Security Type on the Host Connection Form Managing Colleague Software Environments, January 31,

54 Setup and Customization: Securing Colleague Connections Step 7. On the Host Machine Properties form, select the appropriate security type on the Daemon Security Type group. This security type must match the type that you specified in Step 2. Step 8. Click OK to save the changes. Step 9. Repeat Steps 1 through 8 for each host computer. Establishing Client Authentication for the SA Valet- Daemon Connection The application server computer or database computer to which you are establishing client authentication must first have a signed certificate. Client authentication will fail without a signed certificate. Step 1. In SA Valet, select the Hosts tab. Step 2. Select the SA Valet node (Figure 17). Figure 17: Selecting the SA Valet Node Step 3. Generate a client authentication certificate for SA Valet, using the procedure in Generating a Client Authentication Certificate on page Managing Colleague Software Environments, January 31, 2013

55 Procedures for Securing Colleague Connections Step 4. Select the SA Valet node (Figure 17). Step 5. From the Security menu, select Manage Private Key, and then View Encoded Certificate. Step 6. If prompted, enter the certificate vault password that you created when you generated the client authentication certificate (Figure 18), and then click OK. Figure 18: Entering the Certificate Vault Password Step 7. In the View Encoded Certificate window (Figure 19), copy the text of the certificate as follows: a. Right-click anywhere in the text and select SELECT ALL. b. Right-click anywhere in the text and select COPY. Be sure to copy the entire text including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers. Managing Colleague Software Environments, January 31,

56 Setup and Customization: Securing Colleague Connections Figure 19: View Encoded Certificate Window Step 8. Click Close. Step 9. Select the node for the host computer on which the daemon is installed (Figure 20). Figure 20: Selecting the Host Computer Node Step 10. From the Security menu, select Install Public Certificate. 56 Managing Colleague Software Environments, January 31, 2013

57 Procedures for Securing Colleague Connections Step 11. In the Install Public Certificate window (Figure 21), enter the following: Friendly Name (Alias). Enter a short name that will be used to identify the certificate when it is installed. Message Text. Click anywhere in this text field and use the CTRL+V shortcut to paste the text that you copied in Step 7. Figure 21: Install Public Certificate Window Step 12. Click OK to create the public certificate on the host computer. Step 13. Repeat Steps 9 through 12 for each host computer (for example, the application server computer and the database computer. Managing Colleague Software Environments, January 31,

58 Setup and Customization: Securing Colleague Connections Procedures for Installing and Managing Certificates This section contains procedures for installing and managing certificates on computers used with Colleague. Table 12 lists the topics covered in this section. Table 12: Topics in this Section Topic Page Generating the Request for a Signed Certificate 58 Installing a Signed Certificate 61 Examining a Certificate 69 Deleting a Certificate 70 Installing a Public Certificate 72 Managing Public Certificates 73 Generating the Request for a Signed Certificate When SA Valet is used to generate a certificate request (also known as a certificate signing request, or CSR), a public key and a private key are generated by an encryption algorithm. The private key is saved in the Listener s keystore, while the public key is included in the certificate request. Perform the following steps to request a signed digital certificate. Step 1. In SA Valet, select the Hosts tab. Step 2. Select the node for the host computer on which you want to install the signed certificate (Figure 22). 58 Managing Colleague Software Environments, January 31, 2013

59 Procedures for Installing and Managing Certificates Figure 22: Selecting the Host Computer Node Step 3. From the Security menu, select Generate Signed Certificate Request. The Certificate Request Properties dialog box is displayed, as shown in Figure 23. Figure 23: Certificate Request Properties Dialog Box Step 4. Complete the Certificate Request Properties dialog box. See the online help for more information about any field. Step 5. Check your entries carefully, and then click OK to create the certificate request, or Cancel to discard it and start again. The Certificate Request window is displayed, as shown in Figure 24. Managing Colleague Software Environments, January 31,

60 Setup and Customization: Securing Colleague Connections Figure 24: Certificate Request Window Right-Click Pop-up Menu Options Step 6. Right click anywhere in the window to display the pop-up menu. Use the SELECT_ALL and COPY options to copy the encrypted text from the Certificate Request window to the Windows clipboard. Step 7. Open the certificate authority s Web page and follow the directions shown there. Paste the encrypted text that was copied to the clipboard from the Certificate Request window into the appropriate text box, and submit the certificate request as directed. ALERT! At this time we strongly recommend that you backup the dmi.keystore file that contains your private key information. The dmi.keystore file resides in the daemon directory with dmilistener.jar file. If this file should become corrupted or lost before you receive your signed digital certificate, you will be unable to install the certificate. After the signed digital certificate has been installed into the vault, you should again back up the dmi.keystore file. 60 Managing Colleague Software Environments, January 31, 2013

61 Procedures for Installing and Managing Certificates Installing a Signed Certificate Before starting this procedure, you must first request a signed certificate. See Generating the Request for a Signed Certificate on page 58 for the procedure. Upon receipt of the request you generated, the certificate authority performs due diligence to verify the information. This process typically takes five to ten days. After verifying the information in your request, the certificate authority adds its digital signature to the certificate and returns it to you in the form of a Base64 Privacy Enhanced Mail (PEM) encoded message, encrypted with your public key so that only you can decrypt it. The certificate is automatically decrypted when you install it. Perform the following steps to install the signed certificate. Step 1. Copy the PEM encoded message that you received from the certificate authority, including the -----BEGIN CERTIFICATE----- and END CERTIFICATE----- headers, into the Windows clipboard. You can use the Windows shortcut CTRL+C to copy to the clipboard. Note: Ellucian strongly recommends that you also save the PEM encoded message in a secured folder and/or keep a soft copy of it in a secure location. Step 2. In SA Valet, select the Hosts tab. Step 3. Select the node for the host computer for which you requested a certificate (Figure 22). Managing Colleague Software Environments, January 31,

62 Setup and Customization: Securing Colleague Connections Figure 25: Selecting the Host Computer Node Step 4. From the Security menu, select Manage Private Key, and then Install Signed Certificate. Step 5. If prompted, enter the certificate vault password that you created when you generated the server certificate (Figure 26), and then click OK. Figure 26: Entering the Certificate Vault Password Step 6. In the Insert Certificate window (Figure 27), paste the entire certificate into the Certificate field, using the Windows shortcut CTRL+V. 62 Managing Colleague Software Environments, January 31, 2013

63 Procedures for Installing and Managing Certificates Figure 27: Insert Certificate Window Step 7. If the certificate authority issued an intermediate certificate along with the signed certificate, copy the intermediate certificate and paste the test immediately after the signed certificate (after the END CERTIFICATE line). Not all signed certificates have an associated intermediate certificate. Step 8. Click OK to install the signed certificate into the DMI Listener certificate vault. ALERT! At this time we strongly recommend that you backup the dmi.keystore and vaultpki.p12 files that contain your private key information. The dmi.keystore file resides in the daemon directory with dmilistener.jar file. The vaultpki.p12 file resides in the security subdirectory. Keep the backup copy in a secure location. Renewing a Signed Certificate Perform the following steps to renew a signed certificate. Managing Colleague Software Environments, January 31,

64 Setup and Customization: Securing Colleague Connections Step 1. In SA Valet, select the Hosts tab. Step 2. Select the node for the host computer on which you want to renew the signed certificate (Figure 28). Figure 28: Selecting the Host Computer Node Step 3. From the Security menu, select Manage Private Key, and then Renew Signed Certificate. Step 4. If prompted, enter the certificate vault password that you created when you generated the server certificate (Figure 29), and then click OK. Figure 29: Entering the Certificate Vault Password The Certificate Renew Properties dialog box is displayed, as shown in Figure Managing Colleague Software Environments, January 31, 2013

65 Procedures for Installing and Managing Certificates Figure 30: Certificate Renew Properties Dialog Box Step 5. Complete the Certificate Renew Properties dialog box. See the online help for more information about any field. Step 6. Check your entries carefully, and then click OK to renew the certificate, or Cancel to discard it and start again. The Certificate Request window is displayed, as shown in Figure 31. Figure 31: Certificate Request Window Managing Colleague Software Environments, January 31,

66 Setup and Customization: Securing Colleague Connections Step 7. Right click anywhere in the window to display the pop-up menu. Use the SELECT_ALL and COPY options to copy the encrypted text from the Certificate Request window to the Windows clipboard. Step 8. Open the certificate authority s Web page and follow the directions shown there. Paste the encrypted text that was copied to the clipboard from the Certificate Request window into the appropriate text box, and submit the certificate request as directed. Step 9. Click Close. Step 10. Once you receive a response from the certificate authority, delete the existing certificate and then install the signed response. See Deleting a Certificate on page 70 and Installing a Signed Certificate on page 61 for more information. Generating a Client Authentication Certificate Perform the following steps to generate a client authentication certificate. A client authentication certificate is only valid for the connection between SA Valet and a daemon. Step 1. In SA Valet, select the Hosts tab. Step 2. Select the SA Valet node. 66 Managing Colleague Software Environments, January 31, 2013

67 Procedures for Installing and Managing Certificates Figure 32: Selecting the Node for a Client Authentication Certificate Step 3. From the Security menu, select Generate Client Authentication Certificate. The Client Authentication Certificate Properties dialog box is displayed, as shown in Figure 33. Figure 33: Client Authentication Certificate Properties Dialog Box Step 4. Complete the Client Authentication Certificate Properties dialog box as follows: Client Certificate Vault Password. Create a password for the certificate vault. Record this password in a safe place. You will need to provide it when you Managing Colleague Software Environments, January 31,

68 Setup and Customization: Securing Colleague Connections want to manage the Listeners. Common Name. Specify the fully qualified host name used in DNS lookups (for example, servername.mycollege.edu), in other words, the host name in the URL that a browser uses to connect to your site. Technical Tip: When you are generating the client authentication certificate for SA Valet on a PC, you can get the common name of the PC using Control Panel/System. The computer name is on the Computer Name tab. Organization. Enter the official, legal name of your institution. Most certificate authorities require this information to be verified with legal documents, such as a Dun & Bradstreet DUNS number. Organization Unit. Enter a description of an organizational unit within your institution, if desired. Locality. Enter the name of the city, principality, or country for your institution, if desired. State or Province. Enter the full name (not the two-letter abbreviation) of the state or province in which your institution is located. Country. Enter the two-character abbreviation of your country name in International Organization for Standardization (ISO) format. The twocharacter country codes for current Ellucian Clients are: United States US Canada CA Bermuda BM Note: For more information about ISO, see Step 5. Click OK to generate the client authentication certificate. 68 Managing Colleague Software Environments, January 31, 2013

69 Procedures for Installing and Managing Certificates Examining a Certificate Use this procedure to view when a certificate expires. You can also view which root certificate the signed certificate uses. Step 1. In SA Valet, select the Hosts tab. Step 2. Select the node for the host computer on which you want to examine the certificate (Figure 34). Figure 34: Selecting the Host Computer Node Step 3. From the Security menu, select Manage Private Key, and then Examine Certificate. Step 4. In the Examine Certificate window (Figure 35), view the certificate. You can copy the contents to paste elsewhere, if desired. Managing Colleague Software Environments, January 31,

70 Setup and Customization: Securing Colleague Connections Figure 35: Examine Certificate Window Right-Click Pop-up Menu Deleting a Certificate ALERT! Deleting a signed certificate might require that you purchase a replacement certificate. Use the following procedure to delete a signed or client authenticated certificate. This procedure clears the contents of the certificate vault. Step 1. In SA Valet, select the Hosts tab. Step 2. Select the component for which you want to delete the certificate (Figure 36): To delete the server certificate on a Colleague host computer, select the node for that host computer. To delete a client certificate on SA Valet, select the SA Valet node. 70 Managing Colleague Software Environments, January 31, 2013

71 Procedures for Installing and Managing Certificates Figure 36: Selecting the Node for Deleting a Certificate Select SA Valet or the host computer, depending on where you want to remove the certificate. In this example, the host computer is selected. Step 3. From the Security menu, select Manage Private Key, and then Delete Certificate. Step 4. In the Confirm Reset window (Figure 37), click OK to confirm that you want to delete the certificate. Figure 37: Confirm Reset Dialog Box Step 5. If prompted, enter the certificate vault password that you created when you generated the certificate (Figure 38), and then click OK. Figure 38: Entering the Certificate Vault Password Managing Colleague Software Environments, January 31,

72 Setup and Customization: Securing Colleague Connections Installing a Public Certificate Before starting this procedure, you must obtain the public certificate and copy the text of the public certificate. Step 1. In SA Valet, select the component on which you want to install the public certificate: To install a public certificate on a Colleague host computer, select the Hosts tab, and then select the node for that host computer. To install a public certificate on SA Valet, select the Hosts tab, and then select the SA Valet node. To install a public certificate on the Web server, select the Environments tab, and then select the Web server node. Note: To see the Web server node, you will need to connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. Step 2. From the Security menu, select Install Public Certificate. The Install Public Certificate window is displayed, as shown in Figure Managing Colleague Software Environments, January 31, 2013

73 Procedures for Installing and Managing Certificates Figure 39: Install Public Certificate Window Step 3. In the Install Public Certificate window, enter the following: Friendly Name (Alias). Enter a short name that will be used to identify the certificate when it is installed. Message Text. Click anywhere in this text field and use the CTRL+V shortcut to paste the text of the public certificate. Step 4. Click OK to install the public certificate. Managing Public Certificates The Manage Certificates option in the SA Valet Security menu allows you to examine, view, or remove a public certificate in the certificate vault of a host computer, SA Valet, or Web server. To manage the certificates in a certificate vault, perform the following steps: Managing Colleague Software Environments, January 31,

74 Setup and Customization: Securing Colleague Connections Step 1. In SA Valet, select the component on which you want to manage the public certificate: To manage a public certificate on a Colleague host computer, select the Hosts tab, and then select the node for that host computer. To manage a public certificate on SA Valet, select the Hosts tab, and then select the SA Valet node. To manage a public certificate on the Web server, select the Environments tab, and then select the Web server node. Note: To see the Web server node, you will need to connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. In the example in Figure 40, a host computer node is selected. Figure 40: Selecting the Computer Where You Want to Manage Public Certificates Step 2. From the Security menu, select Manage Public Certificates. Step 3. In the Certificates window (Figure 41), select the certificate that you want to manage. Step 4. Right-click on the node for that certificate to display the pop-up menu. 74 Managing Colleague Software Environments, January 31, 2013

75 Procedures for Installing and Managing Certificates Figure 41: Certificates Window Right-click pop-up menu options Step 5. Choose the desired option and continue as directed in Table 13. Table 13: Options for Managing a Public Certificate Menu Option Procedure Examine Certificate Examining a Public Certificate on page 75 View Encoded Certificate Viewing an Encoded Certificate on page 76 Remove Certificate Deleting a Public Certificate on page 77 Examining a Public Certificate If you choose Examine Certificate, information about the certificate is displayed as shown in Figure 42. Note: The information is displayed in inquiry-only mode. Although it appears to be editable, changes made here are not saved when you click Close. You can copy the information to the clipboard by right-clicking anywhere in the window and choosing SELECT_ALL and COPY from the pop-up menu. Managing Colleague Software Environments, January 31,

76 Setup and Customization: Securing Colleague Connections Figure 42: Examining a Public Certificate Right-Click Pop-up Menu Options Viewing an Encoded Certificate To view the text of a public certificate, choose View Encoded Certificate from the pop-up menu. Typically, you would use this option in order to copy the text of the encoded certificate so that you can install it on another computer. 76 Managing Colleague Software Environments, January 31, 2013

77 Procedures for Installing and Managing Certificates Figure 43: View Encoded Certificate Window Deleting a Public Certificate To remove a certificate from the truststore, choose Delete Certificate from the pop-up menu. A confirmation box is displayed. Click Yes to confirm or No to cancel the deletion. Managing Colleague Software Environments, January 31,

78 Setup and Customization: Securing Colleague Connections 78 Managing Colleague Software Environments, January 31, 2013

79 Setup and Customization Enabling Windows Authentication (SQL Server) In This Chapter This chapter provides procedures for enabling Windows authentication for SQL Server databases, so that users are authenticated against user information in the Windows domain rather than the SQL Server database. Table 14 lists the topics covered in this chapter. Table 14: Topics in this Chapter Topic Understanding Windows Authentication 80 Page Procedures for Setting Up Windows Authentication 86 Setting Up Windows Authentication in Colleague 86 Creating the Administrative User in the Windows Domain 88 Managing Colleague Software Environments, January 31,

80 Setup and Customization: Enabling Windows Authentication (SQL Server) Understanding Windows Authentication SQL Server offers two methods of authenticating users: Windows authentication. Users are authenticated against the user information in the Windows domain. SQL Server authentication. Users are authenticated against the user information in SQL Server. Windows Authentication Figure 44 shows an example of a login to Colleague where Windows authentication has been selected. When the Colleague user logs in to Colleague (for example, from UI Desktop), the user s login ID and password are authenticated against the Windows domain. If this login succeeds, the login ID and password are passed, via the Colleague executables and the DMI data access server, to SQL Server. SQL Server then performs its own authentication (database authentication) against the Windows domain. This second authentication should always succeed because the login ID and password were already confirmed by the earlier system login. 80 Managing Colleague Software Environments, January 31, 2013

81 Understanding Windows Authentication Figure 44: User Login With Windows Authentication Windows domain users ID = jsmith, PW = jns999 Windows domain 1) System login 2)Database authentication SQL Server SQL Server users ID = MYCOLLEGE\jsmith, (no password needed) Ellucian login ID = jsmith, PW = jns999 Colleague executables DMI data access server Colleague database Application server computer Colleague database computer With Windows authentication, the user must be set up in SQL Server with the same login ID as in Windows. You also specify the Windows domain, so that the resulting SQL Server login ID includes the domain name as shown in Figure 45. However, the user does not need a password in SQL Server. Managing Colleague Software Environments, January 31,

82 Setup and Customization: Enabling Windows Authentication (SQL Server) Figure 45: SQL Server Login for Windows Authentication SQL Server Authentication Figure 46 shows an example where SQL Server authentication has been selected. As before, the system login is against the Windows domain. The database authentication, however, is against the user database in SQL Server. This raises the following issues: If a user s password in Windows and SQL Server are different, the database authentication will fail and the user will be prompted for the database password (the one in the SQL Server database of users). The system administrator must maintain the SQL Server passwords. The user must remember two passwords. For these reasons, Windows authentication is usually preferred over SQL Server authentication. 82 Managing Colleague Software Environments, January 31, 2013

83 Understanding Windows Authentication Figure 46: User Login With SQL Server Authentication Windows domain users ID = jsmith, PW = jns999 Windows domain SQL Server 1) System login SQL Server users ID = jsmith, PW = abc001 Ellucian login ID = jsmith, PW = jns999 Colleague executables DMI data access server 2) Database authentication Colleague database Application server computer Colleague database computer With SQL Server authentication, both the login ID and password are specified (Figure 47). Managing Colleague Software Environments, January 31,

84 Setup and Customization: Enabling Windows Authentication (SQL Server) Figure 47: SQL Server Login for SQL Server Authentication Dual SQL Server Logins You will need to set up some users with both types of logins in SQL Server: For any application environment, you will need to set up the administrative user with both types of logins. This is the database username and password you entered when you created the application environment (Figure 48). If you have one environment that uses Windows authentication and another that uses SQL Server authentication, all users needing access to both environments must have both types of logins. This might happen, for example, if you are switching from SQL Server authentication to Windows authentication, and your test environment uses Windows authentication but your production environment still uses SQL Server authentication. 84 Managing Colleague Software Environments, January 31, 2013

85 Understanding Windows Authentication Giving a user both types of logins means creating two logins for the user in SQL Server, one using Windows authentication and one using SQL Server authentication. In the examples above, the user would need two logins in SQL Server: jsmith and MYCOLLEGE\jsmith. Figure 48: Database Username and Password Entered When Creating the Application Environment Managing Colleague Software Environments, January 31,

86 Setup and Customization: Enabling Windows Authentication (SQL Server) Procedures for Setting Up Windows Authentication Table 15 lists the procedures for setting up Colleague to use Windows authentication. In addition, you must set up SQL Server to use Windows authentication; see your SQL Server documentation for those procedures. Table 15: Procedures for Setting Up Windows Authentication Topic Setting Up Windows Authentication in Colleague 86 Page Creating the Administrative User in the Windows Domain 88 Setting Up Windows Authentication in Colleague Step 1. In SA Valet, connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded as shown in Figure 49 on page 87, you are already connected. Step 2. Right-click the application environment node and select Database Access Server Properties from the pop-up menu (Figure 49). 86 Managing Colleague Software Environments, January 31, 2013

87 Procedures for Setting Up Windows Authentication Figure 49: Selecting Database Access Server Properties Step 3. On the Database Access Server Properties form (Figure 50), enter the following: Enable Windows Authentication. Select this check box. Domain. Enter the Windows domain where the users reside. Additionally, if your SQL Server implementation is using NTLMv2 authentication, select Enable NTLMv2. Managing Colleague Software Environments, January 31,

88 Setup and Customization: Enabling Windows Authentication (SQL Server) Figure 50: Enabling Windows Authentication in Colleague Step 4. Click OK to save your changes. Creating the Administrative User in the Windows Domain When you created this application environment, you entered a database username and password that Colleague uses to access the database (Figure 48 on page 85). This username and password must exist in both SQL Server and the Windows domain if you are using Windows authentication. If you have not already done so, create this user in the Windows domain with the same username and password as in SQL Server. In addition, make sure that this user has both types of logins in SQL Server as described in Dual SQL Server Logins on page Managing Colleague Software Environments, January 31, 2013

89 Setup and Customization Enabling Single-Role Colleague Access (SQL Server and Oracle) In This Chapter This chapter provides procedures for enabling single-role Colleague access for SQL Server and Oracle databases. Single-role access allows Colleague users to modify Colleague data via Colleague forms, without requiring you to grant each user the SQL Server or Oracle roles to allow them to modify data in the database outside of Colleague. Table 16 lists the topics covered in this chapter. Table 16: Topics in this Chapter Topic Understanding Single-Role Access 90 Page Procedures for Enabling Single-Role Access for SQL Server 93 Creating the Colleague Access Role in SQL Server 93 Setting Up Users in SQL Server 94 Enabling SQL Server Single-Role Access in Colleague 95 Procedures for Enabling Single-Role Access for Oracle 98 Creating the Colleague Access Role in Oracle 98 Setting Up Users in Oracle 100 Enabling Oracle Single-Role Access in Colleague 101 Managing Colleague Software Environments, January 31,

90 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Understanding Single-Role Access Users can access the Colleague database in either of the following ways: Database access via Colleague. The user accesses the database by using Colleague (for example, through UI Desktop or WebAdvisor). Direct database access. The user accesses the database directly (for example, using a database management system tool such as SQL Server Enterprise Manager). Database Access Without Single-Role Access The top picture in Figure 51 on page 92 shows both access paths for the situation where single-role access has not been implemented. The user s access to Colleague forms is limited by Envision security such as Opers records and security classes. Because the user must be able to modify database data from the Colleague forms, you must grant the user a role in the SQL Server or Oracle database that permits data modification. However, this role also allows the user to modify data directly, for example using a database management system tool such as SQL Server Enterprise Manager. You might not want users to be able to modify data in this manner. Example: Jill Smith works in the Financial Aid office. Using Envision security, you have limited Jill s Colleague access to the forms she needs in the Financial Aid application. However, in order to allow Jill to change Colleague data via those forms, you have given her a SQL Server role in the Colleague database that allows her to change data. But now she can use SQL Server query tools to access the database directly and change data in any table in the database. 90 Managing Colleague Software Environments, January 31, 2013

91 Understanding Single-Role Access Database Access With Single-Role Access Enabled The bottom picture in Figure 51 on page 92 shows the same situation, but with single-role access enabled. Using the procedures in this chapter, you will have done the following: Defined a special Colleague access role in SQL Server or Oracle, with rights to change data in all tables. Set up users in SQL Server or Oracle to use the Colleague access role. Enabled single-role access in the DMI data access server (DMI_DAS), so that the DMI_DAS will use that Colleague access role when accessing the database. As a result, each Colleague user can be prevented from making direct updates in the Oracle or SQL Server database while at the same time having full access to make updates as needed through Colleague. Managing Colleague Software Environments, January 31,

92 92 Managing Colleague Software Environments, January 31, 2013 Without Single-Role Access User Database access via Colleague Direct database access With Single-Role Access Enabled User Database access via Colleague Direct database access Figure 51: User Access to Colleague Database Without and With Single-Role Access Colleague access defined by Envision security Colleague access defined by Envision security Colleague forms Colleague forms Database query tools Database query tools DMI data access server Database access defined by user s role in database DMI data access server (single-role access enabled) Database access defined by single Colleague access role in database Database access defined by user s role in database Colleague database Colleague database (Colleague access role defined) Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle)

93 Procedures for Enabling Single-Role Access for SQL Server Procedures for Enabling Single-Role Access for SQL Server Table 17 lists the procedures in this section. Table 17: Procedures for Enabling Single-Role Access for SQL Server Procedure Creating the Colleague Access Role in SQL Server 93 Page Setting Up Users in SQL Server 94 Enabling SQL Server Single-Role Access in Colleague 95 Creating the Colleague Access Role in SQL Server This procedure uses SQL Server Query Analyzer to create the Colleague access role. You can also create this role from SQL Server Enterprise Manager if you prefer. Step 1. Access SQL Server Query Analyzer. Step 2. From the drop-down list on the tool bar, select the database for the Colleague application environment. Step 3. In the query window (Figure 54 on page 97), enter the following: ='PASSWORD' go go Managing Colleague Software Environments, January 31,

94 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Where: COLLEAGUE_ACCESS_ROLENAME is the name of the role that you are creating. PASSWORD is a password for that role name. Write the password down; you will need to enter it later (Step 3 on page 96). Example: ='abcd01' go go Step 4. Execute the query to create the Colleague access role. Setting Up Users in SQL Server Use the procedure below to set up a single user in SQL Server to use singlerole access. The settings in this procedure will allow the user to access the database via Colleague using the special Colleague access role that you have created, but will prevent the user from changing database data via direct database access. Step 1. In SQL Server Enterprise Manager, access the Login Properties form for the user (Figure 52). Step 2. On the Server Roles tab, ensure that no roles are selected. Step 3. On the Database Access tab, do the following: a. In the upper window, check the box next to the databases that this user should be able to access. b. In the lower window, check the Public box. Step 4. Click OK. 94 Managing Colleague Software Environments, January 31, 2013

95 Procedures for Enabling Single-Role Access for SQL Server Figure 52: Setting Up Single-Role Access on the SQL Server Login Properties Form Enabling SQL Server Single-Role Access in Colleague Perform the following procedure to enable single-role access in Colleague. Step 1. In SA Valet, connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded as shown in Figure 53, you are already connected. Step 2. Right-click the application environment node and select Database Access Server Properties from the pop-up menu (Figure 53). Managing Colleague Software Environments, January 31,

96 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Figure 53: Selecting Database Access Server Properties Step 3. On the Database Access Server Properties form (Figure 54 on page 97), enter the following: Enable Role Based Database Access Security. Check this box. Role Name. Enter the name of the role that you created in SQL Server for Colleague access (Step 3 on page 93). Password. Enter the password that you created in SQL Server for that role (Step 3 on page 93). Verify Password. Enter the password again for confirmation. Step 4. Click OK. 96 Managing Colleague Software Environments, January 31, 2013

97 Procedures for Enabling Single-Role Access for SQL Server Setup in SQL Server Query Analyzer Figure 54: Colleague Access Role Setup in SQL Server Query Analyzer and Colleague (SA Valet) Setup in Colleague (SA Valet) Role names must match Passwords must match Managing Colleague Software Environments, January 31,

98 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Procedures for Enabling Single-Role Access for Oracle Table 17 lists the procedures in this section. Table 18: Procedures for Enabling Single-Role Access for Oracle Topic Creating the Colleague Access Role in Oracle 98 Page Setting Up Users in Oracle 100 Enabling Oracle Single-Role Access in Colleague 101 Creating the Colleague Access Role in Oracle This procedure uses SQL Plus to create the Colleague access role. You can use another method if you prefer. Step 1. Access SQL Plus. Step 2. At the SQL Plus prompt, enter the following: create role colleague_access_rolename identified by password grant privileges to colleague_access_rolename Where: colleague_access_rolename is the name of the role that you are creating. password is a password for that role name. Write the password down; you will need to enter it later (Step 3 on page 102). privileges are Oracle privileges to grant to that role name. You must grant all of the privileges listed in Table 19 on page 99. Example: create role colleague_access identified by abcd01 grant alter any index, alter any procedure, alter any table, alter session, create any index, create any table, create any procedure, create any view, 98 Managing Colleague Software Environments, January 31, 2013

99 Procedures for Enabling Single-Role Access for Oracle create public synonym, create session, delete any table, drop any index, drop any table, execute any class, execute any procedure, insert any table, lock any table, select any dictionary, select any table, update any table to colleague_access Table 19: Oracle Privileges Required for Single-Role Access ALTER ANY INDEX Oracle Privilege ALTER ANY PROCEDURE ALTER ANY TABLE ALTER SESSION CREATE ANY INDEX CREATE ANY TABLE CREATE ANY PROCEDURE CREATE ANY VIEW CREATE PUBLIC SYNONYM CREATE SESSION DELETE ANY TABLE DROP ANY INDEX DROP ANY TABLE EXECUTE ANY CLASS EXECUTE ANY PROCEDURE INSERT ANY TABLE LOCK ANY TABLE SELECT ANY DICTIONARY SELECT ANY TABLE UPDATE ANY TABLE Managing Colleague Software Environments, January 31,

100 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Setting Up Users in Oracle Note: After you enable the Colleague access role, users will have the privileges granted to that role, and any Oracle database privileges granted to them personally, when they access Colleague. Granting the Colleague Access Role Use the procedure below to set up a user in Oracle to use single-role access. The settings in this procedure will allow the user to access the database via Colleague using the special Colleague access role that you have created, but will prevent the user from changing database data via direct database access. Step 1. Access SQL Plus. Step 2. At the SQL Plus prompt, enter the following: grant colleague_access_rolename, CONNECT to username alter user username default role all except colleague_access_rolename Where: colleague_access_rolename is the name of the role that you created. username is the user s Oracle database login. Example: grant colleague_access, CONNECT to b_smith alter user b_smith default role all except colleague_access The first command grants the special Colleague access role (as well as the Oracle CONNECT role) to the user, and the second command ensures that the user does not have that role when accessing the Oracle database through a path other than Colleague. Reviewing Other Privileges Granted to Users Once the Colleague access role is enabled, you may want to review the privileges granted to individual users. You can limit those privileges to whatever the user needs when accessing the database outside of Colleague. 100 Managing Colleague Software Environments, January 31, 2013

101 Procedures for Enabling Single-Role Access for Oracle Enabling Oracle Single-Role Access in Colleague Perform the following procedure to enable single-role access in Colleague. Step 1. In SA Valet, connect to the application environment if not already connected. See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded as shown in Figure 55, you are already connected. Step 2. Right-click the application environment node and select Database Access Server Properties from the pop-up menu (Figure 55). Figure 55: Selecting Database Access Server Properties Managing Colleague Software Environments, January 31,

102 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) Step 3. On the Database Access Server Properties form (Figure 56 on page 103), enter the following: Database Type. Select Oracle. Database Host. Enter or change the name of the host on which the database resides. Database Port. Enter or change the port number for the database. Database Name / Path. Enter or change the name / path for the database. Enable Role Based Database Access Security. Check this box. Role Name. Enter the name of the role that you created in Oracle for Colleague access (Step 2 on page 98). Password. Enter the password that you created in Oracle for that role (Step 2 on page 98). Verify Password. Enter the password again for confirmation. Step 4. Click OK. 102 Managing Colleague Software Environments, January 31, 2013

103 Procedures for Enabling Single-Role Access for Oracle Setup in Oracle (SQL Plus) Figure 56: Colleague Access Role Setup for Oracle in SQL Plus and in Colleague (SA Valet) Setup in Colleague (SA Valet) Role names must match Passwords must match Managing Colleague Software Environments, January 31,

104 Setup and Customization: Enabling Single-Role Colleague Access (SQL Server and Oracle) 104 Managing Colleague Software Environments, January 31, 2013

105 Managing Colleague Software Environments Administration and Monitoring

106

107 Administration and Monitoring Starting and Stopping DMI Listeners and Daemons In This Chapter This chapter contains procedures for starting and stopping DMI Listeners and Datatel daemons. Table 20 lists the topics in this chapter. Table 20: Topics in this Chapter Topic Page Starting and Stopping DMI Listeners 108 Starting and Stopping Datatel Daemons 114 Managing Colleague Software Environments, January 31,

108 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Starting and Stopping DMI Listeners Table 21 lists the topics in this section. Table 21: Topics for Starting and Stopping DMI Listeners Topic Page Local Product Repository DMI_DAS 108 Starting the Local Product Repository DMI_DAS 108 Stopping the Local Product Repository DMI_DAS 109 Application Environment Listeners 110 Starting and Stopping All Listeners in an Application Environment 110 Starting and Stopping Individual Listeners in an Application Environment 111 Listener Status Indicators 112 Local Product Repository DMI_DAS The local product repository has one DMI Listener: the DMI data access server (DMI_DAS). Starting the Local Product Repository DMI_DAS Step 1. In SA Valet, connect to the local product repository if not already connected. To connect to the local product repository, right-click the product repository node, select Connect and enter login information if prompted. See Connecting to the Local Product Repository from SA Valet on page 2 for a detailed procedure. You are already connected if the local product repository node is expanded to display application environment nodes. Step 2. Right-click the listener from the product repository node and select Start Listener from the pop-up menu (Figure 57). 108 Managing Colleague Software Environments, January 31, 2013

109 Starting and Stopping DMI Listeners Figure 57: Starting the LPR DMI_DAS from SA Valet Stopping the Local Product Repository DMI_DAS Perform the following procedure if you want to stop the DMI data access server for the local product repository. Step 1. In SA Valet, connect to the local product repository if not already connected. To connect to the local product repository, right-click the product repository node, select Connect and enter login information if prompted. See Connecting to the Local Product Repository from SA Valet on page 2 for a detailed procedure. You are already connected if the local product repository node is expanded to display application environment nodes. Step 2. Right-click the Listener from the product repository node and select Stop Listener from the pop-up menu (Figure 58). Managing Colleague Software Environments, January 31,

110 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Figure 58: Stopping the DMI Data Access Server for the Local Product Repository Application Environment Listeners Each Colleague application environment includes at least two DMI Listeners: a DMI application server and a DMI data access server. In addition, you may have installed other DMI Listeners, such as a DMI print server and DMI RPC server. Use the procedures below to start and stop the Listeners. Before performing these procedures, you must connect to the local product repository and then to the application environment using the procedures in Accessing Colleague from SA Valet beginning on page 1. Starting and Stopping All Listeners in an Application Environment You can start or stop all Listeners in an application environment. Right-click the environment node and select one of the following options (Figure 59): Start All Listeners. Starts any Listeners in the application environment that are not running. Stop All Listeners. Stops all Listeners in the application environment. 110 Managing Colleague Software Environments, January 31, 2013

111 Starting and Stopping DMI Listeners Figure 59: Right-Click Menu Options for All Listeners Starting and Stopping Individual Listeners in an Application Environment You can start or stop individual Listeners in an application environment. Right-click the Listener node and select one of the following options (Figure 60): Start Listener. Starts the Listener if it is not running. This option will be unavailable if the Listener is already running. Stop Listener. Stops the Listener if it is running. This option will be unavailable if the Listener is already stopped. Managing Colleague Software Environments, January 31,

112 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Figure 60: Right-Click Menu Options for Individual Listeners Listener Status Indicators In SA Valet, the icon next to each application environment Listener (Figure 61) indicates the Listener status: Green indicates that the Listener is running and is not secure. Green with a padlock indicates that the Listener is running and is secure; specifically, that a server certificate is installed on the host computer and the corresponding public certificate is installed with this SA Valet. Red indicates that the Listener is stopped. 112 Managing Colleague Software Environments, January 31, 2013

113 Starting and Stopping DMI Listeners Figure 61: Icons Indicating Listener Status Refreshing Listener Status Indicators The Listener status indicator icons are not automatically updated when the Listener status is changed from outside of SA Valet (for example, if a Listener is stopped or started from the Windows Services folder). Do either of the following to ensure that the Listener status indicators are providing the current status: If you want to refresh all icons in an application environment, right-click the environment node and select Refresh All Listener Statuses from the pop-up menu (Figure 59 on page 111). If you want to refresh the icon for just one Listener, right-click the Listener node and select Refresh Listener Status from the pop-up menu (Figure 60 on page 112). Managing Colleague Software Environments, January 31,

114 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Starting and Stopping Datatel Daemons This section contains procedures for manually starting and stopping a Datatel daemon. Table 21 lists the topics in this section. Table 22: Topics for Starting and Stopping Datatel Daemons Topic Page Starting a Datatel Daemon 114 Stopping a Datatel Daemon 116 Daemon Status Indicators 117 The daemon starts automatically when you install it, and is set to restart automatically when the host computer restarts. Examples of situations requiring these manual stop/start procedures are: If you ever need to install a new version of the daemon, you need to stop the existing daemon first. After changing the properties in the dmi.ini file, you need to stop and restart the daemon. Every computer that hosts a DMI Listener must have a Datatel daemon installed on it. See the Installation Procedures for Release 18 for the procedure for installing a Datatel daemon. Starting a Datatel Daemon Perform this procedure on each computer where you installed the daemon. You can leave the daemon running on these computers. The daemon must be running when you do any of the following on a computer: install or upgrade Listeners, start and stop Listeners, or create a local product repository or application environment. 114 Managing Colleague Software Environments, January 31, 2013

115 Starting and Stopping Datatel Daemons Starting a Datatel Daemon on UNIX or Linux Step 1. Log in to the computer using a login with the following permissions: Read/write permissions on the /etc/datateltab file. Read/write/execute permissions on the daemon folder, including subfolders and files. Step 2. Navigate to the unixscripts subdirectory in the directory where you installed the daemon. Step 3. Start the daemon using the following command: datatelmgr start daemon Technical Tip: To start the daemon in the foreground, navigate to the unixstart subdirectory and type startlistener. If you start the daemon in the foreground, the telnet session used to start the daemon must remain active. You might start the listener in the foreground to monitor the telnet window for debugging purposes. Starting a Datatel Daemon on Windows You can start a daemon in either of two ways: as a Windows service or from the daemon installation folder. The daemon starts as a Windows service when it is automatically started after installation and after machine reboot. Starting a Daemon as a Windows Service Step 1. From the Windows Control Panel, open the Services folder. Step 2. Select the DatatelDaemon service. Step 3. From the Action menu, select Start to start the daemon. Managing Colleague Software Environments, January 31,

116 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Starting a Daemon from the Installation Folder Step 1. Navigate to the directory where you installed the daemon. Step 2. Start the daemon by double-clicking the node for the startlistener.bat file. Stopping a Datatel Daemon Use the appropriate procedure below for your operating system if you need to stop the daemon. Stopping a Datatel Daemon on UNIX or Linux Step 1. Navigate to the unixscripts subdirectory in the directory where you installed the daemon. Step 2. Stop the daemon using the following command: datatelmgr stop daemon This command will only work if you used the datatelmgr start daemon command to initially start the daemon. If you did not use that command to start the daemon, you must locate the process ID and kill the process.to locate the process ID, enter the following command at the UNIX prompt in the directory where the dmilistener.jar file resides: ps -ef grep java This command displays all running Java processes with their process IDs, enabling you to identify and kill the daemon process. 116 Managing Colleague Software Environments, January 31, 2013

117 Starting and Stopping Datatel Daemons Stopping a Datatel Daemon on Windows If you started the daemon from the installation folder using the startlistener.bat file, enter CTRL+C in the DOS-type daemon window to stop the daemon. If you started the daemon as a Windows service, use the procedure below. The daemon starts as a Windows service when it is automatically started after installation and after machine reboot. Step 1. From the Windows Control Panel, open the Services folder. Step 2. Select the DatatelDaemon service. Step 3. From the Action menu, select Stop to stop the daemon. Daemon Status Indicators In SA Valet, the icon next to each host name (Figure 62) indicates the daemon status: Green indicates that the daemon is running and is not secure. Green with a padlock indicates that the daemon is running and is secure; specifically, that the daemon security type specified on the Host Machine Properties form (Figure 16 on page 53) is either Client-authenticated SSL or Server-Only SSL. Red indicates that the daemon is stopped. Figure 62: Icons Indicating Daemon Status Stopped Running in secure mode Running but not secure Managing Colleague Software Environments, January 31,

118 Administration and Monitoring: Starting and Stopping DMI Listeners and Daemons Refreshing Daemon Status Indicators The daemon status indicator icons are not automatically updated when the daemon is stopped or started. Do either of the following to ensure that the daemon status indicators are providing the current status: To refresh the status of all daemons, right-click the SA Valet node and select Refresh All Statuses from the pop-up menu (Figure 63). To refresh the icon for just one daemon, right-click the host node and select Refresh Daemon Status from the pop-up menu (Figure 64). Figure 63: Refreshing the Status Indicators for All Daemons Figure 64: Refreshing the Status Indicator for One Daemon 118 Managing Colleague Software Environments, January 31, 2013

119 Administration and Monitoring Monitoring DMI Listeners In This Chapter This chapter provides procedures for monitoring performance of DMI Listeners, using monitoring tools in SA Valet. Table 23 lists the topics covered in this chapter. Table 23: Topics in this Chapter Topic Page Understanding DMI Listener Monitoring 120 DMI Statistics Tables 121 DMI Statistics Log File 129 Memory Monitor 133 Managing Colleague Software Environments, January 31,

120 Administration and Monitoring: Monitoring DMI Listeners Understanding DMI Listener Monitoring When a DMI Listener is running, it can periodically record statistics such as the number of connections to the Listener and database sessions currently in use. These statistics are particularly useful for optimizing WebAdvisor performance. You can view statistics using any of the following methods: View current statistics on the DMI statistics tables in SA Valet. See DMI Statistics Tables on page 121. Review a log file that records the statistics at specified intervals. See DMI Statistics Log File on page 129. View real-time memory usage using the Memory Monitor, accessed from SA Valet. See Memory Monitor on page 133. Some Listener parameters require that you stop and restart the Listener for a change to the parameter to take effect. The parameter values displayed in the statistics tables and the log file reflect the current settings of the Listener, which might not match the value entered in a parameter form if you haven t yet restarted the Listener. For example, if you change the Maximum Concurrent Connections for the Listener from 20 to 30, and then view the Overall Statistics table before restarting the Listener, the Overall table will still display 20 in the Max Threads Allowed row. 120 Managing Colleague Software Environments, January 31, 2013

121 DMI Statistics Tables DMI Statistics Tables Table 24 lists the topics covered in this section. Table 24: Procedures for Setting Up and Viewing Listener Statistics Procedure Page Understanding the DMI Statistics Tables 121 Procedure for Defining the Refresh Interval 125 Procedure for Viewing the Statistics Tables 125 Understanding the DMI Statistics Tables In SA Valet, you can view tables of current statistics for any of the DMI Listeners in an application environment. See below for a description of each of the available statistics tables. The information in the statistics tables is automatically refreshed periodically, at the interval you specify as described in Procedure for Defining the Refresh Interval on page 125. You can also refresh the statistics tables at any time while you are viewing the statistics (see Step 5 on page 127). This section contains examples of the DMI statistics tables available in SA Valet. Table 25: DMI Statistics Tables Statistics Table Example Overall Figure 65 on page 122 Current Connections Figure 66 on page 122 Database Pools Figure 67 on page 123 Database Sessions Figure 68 on page 123 Extensions Figure 69 on page 124 JVM Figure 70 on page 124 Managing Colleague Software Environments, January 31,

122 Administration and Monitoring: Monitoring DMI Listeners The Overall table (Figure 65) shows high-level statistics for the DMI Listener. Some of the statistics this table displays include: The date and time when the Listener was started. The total number of connections made through this Listener since it was started. Maximum threads allowed connected through this Listener. Figure 65: Overall Table The Current Connections table (Figure 66) shows statistics for clients that connect to this DMI Listener, such as WebAdvisor. Some of the statistics this table displays include: The IP address of users connected to this Listener. The port number for the server where this Listener resides. The port number for the computer from which a user is connected. Figure 66: Current Connections Table 122 Managing Colleague Software Environments, January 31, 2013

123 DMI Statistics Tables The Database Pools table (Figure 67) shows statistics for database pools, which are the databases available to this Listener. Some of the statistics this table displays include: Maximum database sessions allowed. Database sessions currently in use. Connections waiting for a database session. Figure 67: Database Pools Table The Database Sessions table (Figure 68) represents the time spent in the native database for transactions sent through this Listener. This is measured by how long the DMI Listener is waiting for a response from DMI_DISPATCH. Some of the statistics this table displays include: Minimum execution time for this database. Maximum execution time for this database. Average execution time for all transactions to this database for this session. Figure 68: Database Sessions Table Managing Colleague Software Environments, January 31,

124 Administration and Monitoring: Monitoring DMI Listeners The Extensions table (Figure 69) shows statistics for the extensions processed by the DMI Listener, such as INAS and style sheet printing. Some of the statistics this table displays include: Transaction type. Transaction description. Total transactions processed for each transaction type. Figure 69: Extensions Table The JVM table (Figure 70) shows the memory usage of the Java Virtual Machine associated with this Listener. Some of the statistics this table displays include: Total memory available to this JVM. Free (unused) memory currently available to this JVM. Active threads count. Figure 70: JVM Table 124 Managing Colleague Software Environments, January 31, 2013

125 DMI Statistics Tables Procedure for Defining the Refresh Interval Use the procedure below to specify the interval at which DMI statistics are automatically refreshed. This interval determines both when the online statistics tables are updated and how often a new set of statistics information is written to the log (if you enable logging as described in Procedure for Starting and Stopping Logging on page 130). Note: This setting applies to all Listeners. Step 1. In SA Valet, from the Tools menu, select Statistics > Log Preferences. Step 2. In the Log Preferences dialog box (Figure 71), enter the interval at which you want the statistics to be automatically refreshed. The default is 900 seconds (15 minutes). Figure 71: Log Preferences Dialog Box Step 3. Click OK to save the interval. Procedure for Viewing the Statistics Tables Perform the following procedure to view statistics for a Listener. Step 1. In SA Valet, connect to the application environment for which you want to view statistics, if not already connected. Managing Colleague Software Environments, January 31,

126 Administration and Monitoring: Monitoring DMI Listeners See Accessing Colleague from SA Valet beginning on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. If the application environment node is expanded as shown in Figure 72, you are already connected. Step 2. Right-click the node for the Listener for which you want to view statistics, and click Show Statistics (Figure 72). Figure 72: Selecting Show Statistics for a DMI Listener Step 3. If the Colleague Environment Login window (Figure 73) appears, enter the information below and then click OK. (This window will not appear if you previously entered this information since connecting to the application environment.) DMI Username and Password. Valid username and password for a Colleague login. Save Login Information. Check this box if you want to save the username and password in a login vault, so that you don t have to enter them in later SA Valet sessions. See Storing Login Information in the Login Vault on page 8 for more information. 126 Managing Colleague Software Environments, January 31, 2013

127 DMI Statistics Tables Figure 73: Colleague Environment Login Window Step 4. Click on any tab to view the desired statistics table. For a description of each statistics table, see DMI Statistics Tables beginning on page 121. Step 5. To refresh the statistics, right-click on any DMI statistics table (Figure 74) and choose one of the Refresh Options to immediately refresh all the tables or only the current table. Note: Even if you don t manually refresh statistics, they will be automatically refreshed at the interval specified in the Log Preferences box (see Procedure for Defining the Refresh Interval on page 125). Figure 74: Refresh Options Menu Managing Colleague Software Environments, January 31,

128 Administration and Monitoring: Monitoring DMI Listeners Step 6. If you want to change which tables are displayed, right-click on any DMI statistics table (Figure 74) and select one of the following options: Add/Remove Table. If you don t want to see all seven tables, or you previously removed a table and you now want to view it again, you can choose the proper table to show or hide from this submenu. Note: If you have removed multiple tables, you can right-click on the DMI Listener, and then select Statistics from the menu to reset all the tables to be visible. Remove. This option will remove the current table from view. 128 Managing Colleague Software Environments, January 31, 2013

129 DMI Statistics Log File DMI Statistics Log File Table 26 lists the topics covered in this section. Table 26: Procedures Related to Logging of Listener Statistics Procedure Page Understanding the Log File 129 Procedure for Starting and Stopping Logging 130 Procedure for Purging Log Files 132 Understanding the Log File The DMI statistics can be stored in a log file at specified intervals. Figure 75 on page 130 shows an example of the DMI statistics log. The DMI statistics log is saved in the SA Valet home directory (example: C:\Program Files\Datatel\SaValet 2.0) The filename format is Listener_lprname_envname_host_port_Profile_datetime.log, where: lprname = local product repository name. envname = application environment name. host = name of the computer on which the DMI Listener is installed. port = port on which the DMI Listener is listening. datetime = date/time stamp, needed because each Listener can have multiple logs. Example filename: Listener_coll18_test_sdw2k3sql_7222_Profile_ log You can specify the logging interval as described in Procedure for Defining the Refresh Interval on page 125. Note that this interval also determines how often the online statistics tables are updated. If you restart SA Valet, a new log file is started. You can also import the log into a spreadsheet program. When opening the log in a spreadsheet program, such as Microsoft Excel, use the character (often called a pipe) as the delimiter. Managing Colleague Software Environments, January 31,

130 Administration and Monitoring: Monitoring DMI Listeners Figure 75: Example of the DMI Statistics Log Procedure for Starting and Stopping Logging Perform the procedure below to start or stop logging Listener statistics to a log file. See DMI Statistics Log File on page 129 for more information about logging. To change the logging interval, see Procedure for Defining the Refresh Interval on page 125. Step 1. Right-click the node for the Listener for which you want to log statistics (Figure 76). The example in Figure 72 is for the DMI application server (the node whose name ends with APP_LISTENER ). For the DMI data access server, the node name ends with DB_LISTENER. 130 Managing Colleague Software Environments, January 31, 2013

131 DMI Statistics Log File Figure 76: Selecting Start Logging for a DMI Listener Step 2. From the right-click pop-up menu, select Start Logging or Stop Logging as desired. Step 3. If the Colleague Environment Login window (Figure 77) appears, enter the information below and then click OK. (This window will not appear if you previously entered this information since connecting to the application environment.) DMI Username and Password. Valid username and password for a Colleague administrative user. You can use the username and password that you entered when you created a DMI administrative user as part of creating the application environment. Save Login Information. Check this box if you want to save the username and password in a login vault, so that you don t have to enter them in later SA Valet sessions. See Storing Login Information in the Login Vault on page 8 for more information. Managing Colleague Software Environments, January 31,

132 Administration and Monitoring: Monitoring DMI Listeners Figure 77: Colleague Environment Login Window Procedure for Purging Log Files If you have started statistics logging for a DMI Listener, a new log file will be created each time SA Valet is restarted, for each Listener. Because these log files can become large, you should periodically purge old log files to free up disk space on the PC. Use the following procedure to delete all log files except those created during the current SA Valet session. Note that this procedure deletes the log files for all Listeners. Step 1. In SA Valet, from the Tools menu, select Statistics/Purge Log. Step 2. In the Purge Log Confirmation box, click Yes to delete the log files. 132 Managing Colleague Software Environments, January 31, 2013

133 Memory Monitor Memory Monitor SA Valet has a visual memory monitor that displays real-time memory usage for the chosen DMI Listener. Figure 78 shows an example of the Memory Monitor. Figure 78: Memory Monitor Window The procedure for viewing the memory monitor is the same as that for viewing the statistics tables ( Procedure for Viewing the Statistics Tables beginning on page 125), except that you should click Memory Monitor on the right-click menu (Figure 72). Figure 79: Selecting Memory Monitor Managing Colleague Software Environments, January 31,

134 Administration and Monitoring: Monitoring DMI Listeners 134 Managing Colleague Software Environments, January 31, 2013

135 Managing Colleague Software Environments Configuration

136

137 Configuration Removing an Application Environment In This Chapter This chapter provides the procedure for removing a Colleague application environment. Table 28 lists the topics covered in this chapter. Table 27: Topics in this Chapter Topic Page Understanding Application Environment Removal 138 Procedures for Removing an Application Environment 139 Managing Colleague Software Environments, January 31,

138 Configuration: Removing an Application Environment Understanding Application Environment Removal Removing an application environment involves the following steps: From SA Valet, run a process to remove information about the application environment. This process does the following: Stops all DMI Listeners in the environment. Removes DMI Listeners registrations (Windows services for the Windows operating system, and information in the datateltab file for UNIX operating systems). Removes information about this environment in the local product repository. Delete the Colleague executables directory, using operating system tools. Delete the database, using database management tools (SQL Server or Oracle) or operating system tools (UniData). Delete all DMI Listener directories and files, using operating system tools. 138 Managing Colleague Software Environments, January 31, 2013

139 Procedures for Removing an Application Environment Procedures for Removing an Application Environment Table 28 lists the procedures in this section. Table 28: Procedures in this Section Procedure Page Deleting Environment Information from Colleague 139 Deleting the Colleague Executables 142 Deleting the Colleague Database 142 Deleting DMI Listener Files 143 Deleting Environment Information from Colleague Use the procedure below to remove information about the application environment. See Understanding Application Environment Removal on page 138 for a description of what happens during this process. Step 1. Right-click the node for the application environment that you want to delete, and select Delete Application Environment from the pop-up menu (Figure 80). Managing Colleague Software Environments, January 31,

140 Configuration: Removing an Application Environment Figure 80: Delete Application Environment Menu Option Step 2. In response to the warning message, click Yes to confirm that you want to delete this application environment. If prompted, enter a username and password with administrative rights to the database on which the environment is installed. SA Valet deletes the application environment information. Note: After deleting an application environment, follow the steps outlined in Setting up an Environment as Production beginning on page 140 to specify which is your production environment. Setting up an Environment as Production Follow the procedure below to review application environment parameters. Specifically, use this form to indicate which is your production environment. 140 Managing Colleague Software Environments, January 31, 2013

141 Procedures for Removing an Application Environment Step 1. In SA Valet, right-click on an application environment and select the Environment Accounts Setup option (Figure 81). Figure 81: Selecting Environment Accounts Setup Step 2. On the Environment Accounts Setup window, review the information about the application environment (see Figure 82). Username. If you are using Windows Authentication, the username must exist in the domain specified on the Database Access Server Properties form. See Procedures for Setting Up Windows Authentication beginning on page 86 for more information. Production Environment. When appropriate, select the check box to indicate that this is your production environment. Otherwise, leave the check box cleared. Note: Make sure to clear this check box for any other application environment that you may have previously used as production. Managing Colleague Software Environments, January 31,

142 Configuration: Removing an Application Environment Figure 82: Example Environment Accounts Setup form Step 3. Click OK when you are done. Deleting the Colleague Executables Use operating system tools to delete the Colleague executables directory and all subdirectories. Example path to the Colleague executables directory: /datatel/coll18/test/ apphome Deleting the Colleague Database SQL Server or Oracle Use database management system tools to remove the database. UniData No action is needed. You deleted the Colleague data along with the Colleague executables using the procedure in Deleting the Colleague Executables on page Managing Colleague Software Environments, January 31, 2013

143 Procedures for Removing an Application Environment Deleting DMI Listener Files Use operating system tools to delete the DMI Listener directory and all subdirectories, for all DMI Listeners in the environment. Each application environment has a DMI application server and a DMI data access server, and may have other DMI Listeners as well. Table 29 shows example paths to the DMI Listener directories. Delete those directories and all subdirectories. Table 29: Example Paths to DMI Listener Directories DMI Listener DMI data access server DMI application server Other optional Listeners, such as DMI print server Example Path to DMI Listener Directory /datatel/coll18/test/das (on database computer) /datatel/coll18/test/svr01 (on application server computer) /datatel/coll18/test/svr02 Managing Colleague Software Environments, January 31,

144 Configuration: Removing an Application Environment 144 Managing Colleague Software Environments, January 31, 2013

145 Configuration Creating a Training Environment In This Chapter This chapter provides the procedure for creating a Colleague application environment to be used for training classes. Table 30 lists the topics covered in this chapter. Table 30: Topics in this Chapter Topic Page Understanding Training Environments 146 Process for Creating a Training Environment 146 Procedures for Creating a Training Environment 148 Creating the Training Source Environment 149 Retrieving the Training Data Set from Ellucian 149 Installing the Data Set in the Training Source Environment 151 Setting Up the Training Source Environment 154 Creating a Training Environment 155 Refreshing a Training Environment 156 Updating the Training Source Environment With a New Data Set From Ellucian 156 Managing Colleague Software Environments, January 31,

146 Configuration: Creating a Training Environment Understanding Training Environments A training environment is a Colleague application environment to be used for classes taught by Ellucian instructors. The training environment includes sample data that is provided by Ellucian and that supports the examples used in Colleague classes and learning guides. Specifically, the data includes: Sample data for all Colleague modules, used by instructors to demonstrate Colleague setup and use. All Envision Tool Kit files for the Parking Ticket application (PT), which is used in Envision Tool Kit training. Ellucian recommends the following approach for creating a training environment: Create a training source environment. This environment is configured for training, including the training data set and user setup, but no training is done in this environment. This ensures that the clean data in this environment is not changed. As needed, create a training environment by cloning the training source environment. Periodically refresh the training environment by deleting the used training environment and cloning a new one, with clean data, from the training source environment. Process for Creating a Training Environment Table 31 summarizes the steps in creating a training source environment and training environments. Figure 83 on page 147 shows the main steps. For the detailed procedures, see Procedures for Creating a Training Environment beginning on page 148. Table 31: Steps in Creating a Training Environment Step Create the training source environment using the instructions in the Installation Procedures for Release 18 for creating a new application environment (not upgraded from Release 17). Procedure page 149 Retrieve the training data set from Ellucian. page 149 Install the training data set in the training source environment. page Managing Colleague Software Environments, January 31, 2013

147 Understanding Training Environments Table 31: Steps in Creating a Training Environment Set up the training source environment: Set up users. Step Create computed columns for general ledger. (Canadian clients only) Modify international parameters. Create a training environment by cloning the training source environment. Periodically refresh the training environment by deleting the used environment and cloning a new environment. Procedure page 154 page 155 page 156 Periodically retrieve an updated data set from Ellucian. page 156 Figure 83: Training Environment Configuration Datatel product repository Release package with training data Ellucian Retrieve data release package from Ellucian using SA Valet. Your site Local product repository Release package with training data Install data release package in training source environment using the MDRP form. Training source environment Colleague database with training data Clone Training environment Colleague database with training data Managing Colleague Software Environments, January 31,

148 Configuration: Creating a Training Environment Procedures for Creating a Training Environment Table 32 lists the procedures in this section. Table 32: Procedures in this Section Procedure Page Creating the Training Source Environment 149 Retrieving the Training Data Set from Ellucian 149 Installing the Data Set in the Training Source Environment 151 Setting Up the Training Source Environment 154 Creating a Training Environment 155 Refreshing a Training Environment 156 Updating the Training Source Environment With a New Data Set From Ellucian Managing Colleague Software Environments, January 31, 2013

149 Procedures for Creating a Training Environment Creating the Training Source Environment Follow the instructions in the Installation Procedures for Release 18 for creating a new (not upgraded from Release 17) application environment. The steps include: Run the Create Application Environment wizard. Upgrade DMI Listeners. Run the Populate Application Environment wizard. Create a printer control record. Build new file indexes. Build application security. Define DMI Listener parameters (memory allocation and auto-start). Install Ellucian software updates (but not your custom release packages). Note: When creating a new application environment for training is it important that you do not install software updates with a release date after the release date of the training data until the training data has been loaded. Loading the software updates before the training data can cause problems because the training data is built using file specs that may have changed by a recent software update. If this scenario occurs, it is recommended to start over and only load updates up through the release date of the training data. After the training data has been loaded you can proceed to load any of the recent software updates if necessary. Execute automated post-install steps. Build PERSON file indexes. Run the dictionary date conversion. Retrieving the Training Data Set from Ellucian Note: Retrieving the release package of training data may take several hours. The training data set is a release package that you retrieve from Ellucian using the same process that you use to retrieve software updates. The following is a summary of the procedure. See Updating Colleague Software for the detailed procedure for retrieving software updates from Ellucian. Managing Colleague Software Environments, January 31,

150 Configuration: Creating a Training Environment See AnswerNet page for information about the training data set, and make yourself an Add-Me to that page so that you will be notified when Ellucian updates the training data set. Step 1. In SA Valet, connect to the local product repository by right-clicking the local product repository node, selecting Connect, and entering login information if prompted. Step 2. Right-click the local product repository node again and select View/Update Product Repository. Step 3. Enter your organization code and password in the login box. Step 4. In the Update Product Repository window (Figure 84 on page 151), do the following: a. In the Enter Retrieval Codes box, enter the retrieval code for the training data set. See AnswerNet page for the appropriate retrieval code. In the example in Figure 84 on page 151, the retrieval code is TRAIN_DATA, but that is only an example. The use of a retrieval code ensures that you only get the training data set when you want it, and aren t required to download it when you retrieve Ellucian software updates. The training data set is large and takes a long time (several hours) to download. b. Click View Available Updates to display the training data set. The latest training data set will be displayed. A training data set will have DATA displayed in the Type column. If the latest training data set is already in your local product repository, no training data set will be displayed. Other available software updates will be displayed as well. In the example in Figure 84, there are no other software updates. c. Click Download Available Updates to retrieve the training data set and any other available software updates. 150 Managing Colleague Software Environments, January 31, 2013

151 Procedures for Creating a Training Environment Figure 84: Retrieving the Training Data Set Installing the Data Set in the Training Source Environment Note: Installing the data will likely take about 1-2 hours. Use the following procedure to install the training data set in the training source environment, using the Manage Data Release Packages (MDRP) process. If you have more than one version of the training data set in your local product repository, this process will delete all versions except the latest one from the local product repository before installing the latest version in this application environment. Older versions of the training data set are not needed and removing them reduces the disk space required by the local product repository. This procedure will overwrite existing data in the training environment. Managing Colleague Software Environments, January 31,

152 Configuration: Creating a Training Environment Step 1. In the training source environment, from the UT application, access the Manage Data Release Packages (MDRP) form (Figure 85 on page 153). Note: You will be unable to access the form (instead, you will get an error message) if this application environment appears not to be a training environment; that is, if it already has data (specifically, it has at least one PERSON record) and it has never had a training data set installed previously. These criteria ensure that you do not accidentally overwrite good data in a non-training environment by installing the training data set. Step 2. Is a release package ID displayed next to the Install Release Packages field? Yes. Continue with Step 3 to check for unresolved dependencies (prerequisite software updates). No. (Instead of a release package ID, none available is displayed). Cancel from this form; there is no data release package to install. Either there are no data release packages in your local product repository, or the latest data release package is already installed in this application environment. Review the information in the Data Release Packages window to determine the situation. If appropriate, retrieve the latest data release package from Ellucian using the procedure in Retrieving the Training Data Set from Ellucian on page 149, and then return to this form to install that data release package. 152 Managing Colleague Software Environments, January 31, 2013

153 Procedures for Creating a Training Environment Figure 85: Manage Data Release Packages (MDRP) Form Step 3. Are there any software updates displayed in the Unresolved Dependencies window? Yes. Cancel from this form and install those software updates; then return to this form to install the data release package. The Unresolved Dependencies window displays uninstalled prerequisite software updates for the data release package displayed in the Install Release Package field. Ellucian defines prerequisite software updates for the data release package, generally based on the software updates released by Ellucian as of the date when Ellucian built the data release package. No. Continue with Step 4 to install the data release package. Step 4. Enter Y in the Install Release Package field. Step 5. Save your work on the MDRP form to install the data release package. Managing Colleague Software Environments, January 31,

154 Configuration: Creating a Training Environment Setting Up the Training Source Environment Perform the procedures below in the training source environment. Setting Up Users Create generic users for your training classes. For example, you might create a user called instructor and others called student01, student02, etc. The required user setup will be specific to your configuration, considering factors such as your operating system, database management system, and use of Windows authentication or LDAP. Examples of user setup requirements are operating system logins, Colleague PERSON records, and Colleague OPERS records. Your PERSON IDs Will Start at When you install the training data set into your training source environment, the key counter for PERSON IDs is set to (nine million). Any PERSON IDs that you create for instructors and students will have IDs of , , etc. This ensures that, when you load an updated training data set, your PERSON records will not be overwritten by PERSON records delivered by Ellucian. OPERS records that you create will likewise not be overwritten, because the training data set delivered by Ellucian does not include OPERS records. Creating Computed Columns for General Ledger Use the GL I-Descriptor Update (GLDU) form to create computed columns that describe the general ledger account number components. See the Installation Procedures for Release 18 for the procedure. In that manual, the GLDU procedure is included as a post-install step when upgrading a Release 17 account to Release 18. This is normally not required for a new environment because it's done later when you do your application setup. But it is required after you install Ellucian's training data set in the training source environment. 154 Managing Colleague Software Environments, January 31, 2013

155 Procedures for Creating a Training Environment (Canadian Clients Only) Modifying International Parameters Note: You must repeat this procedure each time you retrieve a new data set from Ellucian and install it in your training source environment. The Ellucian training data set uses American settings. Canadian clients should do the following to change those settings: Modify the settings on the International Parameters (INTL) and International Defaults (PID1) forms. See Getting Started with the Core System. (UniData only) Run the Dictionary Date Convert (DDCV) process to change the data dictionary formats for date fields so that they are consistent with the date formats specified on the INTL form. See the Installation Procedures for Release 18. Do Not Enter Your Own Data In the Training Source Environment The training environment described in this chapter is for classes that use the Ellucian-provided training data set. Each time you retrieve an updated data set from Ellucian and install it in the training source environment, it will overwrite existing data (actually, just those data records whose IDs match those in the new data set). As a result, if you create your own data and set parameters in the training source environment, they may be overwritten when you install a new data set. Note: PERSON and OPERS records that you create for your instructors and students will not be overwritten, as discussed in Your PERSON IDs Will Start at on page 154. Creating a Training Environment To keep the data in the training source environment clean, you should not conduct training classes in that environment. Instead, create a training environment by cloning the training source environment. See the Installation Procedures for Release 18 for the cloning procedure. Managing Colleague Software Environments, January 31,

156 Configuration: Creating a Training Environment Refreshing a Training Environment Because students will create and change data during training classes, you will periodically want to start with a fresh training environment with clean data. You might choose to do this after each training class or after several classes. To refresh the training environment, do the following: Remove the used training environment using the procedure in Removing an Application Environment beginning on page 137. Create a new training environment by cloning the training source environment as described above. Updating the Training Source Environment With a New Data Set From Ellucian Ellucian will periodically update the training data set. Make yourself an Add- Me to AnswerNet page to keep informed of updates to the data set. Do the following to update the training source environment with a new data set from Ellucian: Retrieve the new data set using the procedure on page 149. Install the data set in the training source environment using the procedure on page 151. (Canadian clients only) Modify international parameters as described on page Managing Colleague Software Environments, January 31, 2013

157 Configuration View Environment Configuration In This Chapter This chapter contains information to assist you with viewing your environment information and transmitting that information to Ellucian. Table 33 lists the topics covered in this chapter. Table 33: Topics in this Chapter Topic Page Before You Begin 158 Viewing an Environment Configuration 159 Automatic Send to Ellucian Feature 161 Manual Send to Ellucian Feature 162 Procedure for Viewing an Environment Configuration 162 Managing Colleague Software Environments, January 31,

158 Configuration: View Environment Configuration Before You Begin Table 34 lists the tasks that must be complete before you can continue with the procedures in this chapter. Table 34: Before You Begin Task Install software update , which enables the functionality described in this chapter. Reference For procedures on installing software updates, see the Updating Colleague Software manual. 158 Managing Colleague Software Environments, January 31, 2013

159 Viewing an Environment Configuration Viewing an Environment Configuration Release 18 is a major shift from previous Colleague releases, both in architecture and technology. Due to these changes, Release 18 has more configuration settings than previous releases. To assist a system administrator with Colleague configuration, SA Valet allows you to produce a report of the configuration settings for an application environment or for a specific DMI Listener. Examples of the environment configuration report are shown in Figure 86 and Figure 87 on page 160 Figure 86: Example 1 of the View Environment Configuration Report Managing Colleague Software Environments, January 31,

160 Configuration: View Environment Configuration Figure 87: Example 2 of the View Environment Configuration Report Figure 88 shows an example of the report produced for a specific DMI Listener. 160 Managing Colleague Software Environments, January 31, 2013

161 Viewing an Environment Configuration Figure 88: Example of the DMI Server Info Report Automatic Send to Ellucian Feature SA Valet allows us to support you by recording environmental configuration settings. Environmental information will be recorded by our support system each time software updates are downloaded from Ellucian into your LPR. This information is intended to aide in troubleshooting and to provide Ellucian's technical support with current information on your hardware and parameters. The types of information recorded include: Hardware specifications. DMI parameters. Software settings. You can view the information being updated by using SA Valet version or later. For more information, see Figure 89 on page 163. Managing Colleague Software Environments, January 31,

162 Configuration: View Environment Configuration Manual Send to Ellucian Feature The environment configuration report has an option for you to send the information to Ellucian. If you want to send the information to Ellucian, click Send to Ellucian at the bottom of the View Environment Configuration window. Why should I send my configuration information to Ellucian? Sending your configuration information to Ellucian greatly assists Solution Center with troubleshooting. Up-to-date configuration data is often needed before any accurate troubleshooting can occur. If Ellucian already has your current configuration data, Solution Center can begin analysis of your issue in a much more timely manner. In addition to assisting Solution Center, your configuration data can help Ellucian to recommend configuration parameters for other institutions who share a similar profile (such as database and operating system). Procedure for Viewing an Environment Configuration Follow these steps to view your environment configuration. Step 1. In SA Valet, connect to the application environment for which you want to view configuration details, if not already connected. See Accessing Colleague from SA Valet on page 1 for the detailed procedure for connecting to the local product repository and then to the application environment. Step 2. Right-click on the application environment node and select View Environment Configuration, as shown in Figure Managing Colleague Software Environments, January 31, 2013

163 Viewing an Environment Configuration Figure 89: View Environment Configuration Menu Option The View Environment Configuration report is displayed, as shown in Figure 86 on page 159 and Figure 87 on page 160. Step 3. If you want to send your configuration information to Ellucian manually, click Send to Ellucian. A dialog box is displayed, as shown in Figure 90 on page 164. Managing Colleague Software Environments, January 31,

164 Configuration: View Environment Configuration Figure 90: Confirm Sending to Ellucian Dialog Box Step 4. Click Yes to send the information to Ellucian. Step 5. Do you want to view information for a specific Listener? No. You are finished with this procedure. Yes. Right-click on the Listener node and select DMI Server Info, as shown in Figure 91 on page Managing Colleague Software Environments, January 31, 2013

165 Viewing an Environment Configuration Figure 91: DMI Server Info Menu Option The DMI Server Info report is displayed, as shown in Figure 88 on page 161. Step 6. Repeat this procedure for any other environment or Listener for which you want to view configuration details. Managing Colleague Software Environments, January 31,

166 Configuration: View Environment Configuration 166 Managing Colleague Software Environments, January 31, 2013

167 Configuration 91 Moving a Local Product Repository In This Chapter This chapter contains information on how to move your Local Product Repository (LPR) from one host to another using SA Valet. Technical Tip: The ability to move an LPR was introduced with SA Valet You must use SA Valet or newer to follow the procedures in this chapter. Table 35 lists the topics covered in this chapter. Table 35: Topics in This Chapter Topic Page Understanding Moving a Local Product Repository 168 Troubleshooting 172 Managing Colleague Software Environments, January 31,

168 Configuration: Moving a Local Product Repository Understanding Moving a Local Product Repository Moving a Local Product Repository (LPR) consists of three main steps. 1. Make a backup of the current LPR and manually copy the LPR database to the new host. 2. Use SA Valet to move the LPR DAS and update all environments associated to the LPR with the new connection information. 3. After thorough testing, delete the old LPR database. Restrictions on Moving an LPR An LPR can only be moved to a host that has the same database and operating system. For example, if the existing LPR is installed on UniData on a UNIX/ LINUX operating system, then the new host must also have UniData on a UNIX/LINUX operating system, not Windows. The Move LPR process is not intended to migrate from one database to a different database or from a UNIX/ LINUX operating system to a Windows operating system, or vice versa. If you are interested in migrating databases or operating systems, consult your sales representative and refer to the Migrating Colleague Software Environments manual. Additionally, you cannot download or install software updates once the move process has started. If you download or install software updates after copying the LPR database to the new host but before you begin the Move Product Repository wizard in SA Valet, the new LPR will show that those installed software updates have not been installed and any newly downloaded software updates will not be present in the new LPR. Procedure for Moving an LPR Follow these steps to move your LPR from one host to another host. Note that once you begin this procedure you cannot install any software updates until after you have successfully completed the procedure. 168 Managing Colleague Software Environments, January 31, 2013

169 Understanding Moving a Local Product Repository Step 1. Make a backup copy of your LPR. This is not an optional step. If you do not have a backup of your LPR and an unrecoverable error occurs, it will be very difficult and time-consuming to recreate your LPR. Step 2. Copy the LPR database to the new host. Refer to your database documentation for procedures on copying a database. Make a note of the installation path or database name and port number as you will need them later in this procedure. Step 3. Define the new host in SA Valet, if not previously defined. To define a host, click on the Hosts tab, then select File, then Add, and finally Host Connection. For the detailed procedure, see the Installation Procedures for Release 18 manual. Step 4. From the Environments tab in SA Valet, select the LPR you want to move and, from the Wizards menu, select Move Product Repository, as shown in Figure 92. Figure 92: Move Product Repository Menu Option Step 5. At the Database Copy Confirmation prompt, click Yes if you can confirm that you have not installed any software updates since completing Step 2. If you have installed any software updates, you must restart this procedure from the beginning. Step 6. The Move Local Product Repository (1/3) window is displayed, as shown in Figure 93. Managing Colleague Software Environments, January 31,

170 Configuration: Moving a Local Product Repository Figure 93: Move Local Product Repository (1/3) Window Step 7. Enter the following information for the fields in this window: Host Name. Select the new host for the LPR database. Database Port. Enter the port for the new LPR database. Database Name/Path. Enter the path (UniData) or the name (SQL Server and Oracle) for the new LPR. Username and Password. Enter an administrator username and corresponding password for the new LPR database. Step 8. Click Next to continue. The Move Local Product Repository (2/3) window is displayed, as shown in Figure 94. Figure 94: Move Local Product Repository (2/3) Window 170 Managing Colleague Software Environments, January 31, 2013

171 Understanding Moving a Local Product Repository Step 9. Enter the following information for the fields in this window: DMI_DAS Port. Enter the port on which the LPR DAS will communicate. DMI_DAS Installation Path. Enter the path where you want the LPR DAS to be moved. SA Valet moves the DAS from the old LPR installation to the new location as part of the wizard. Path to JRE. Enter the path to the JRE on the new host. Step 10. Click Next to continue. The Move Local Product Repository (3/3) window is displayed, as shown in Figure 95. Figure 95: Move Local Product Repository (3/3) Window Step 11. Enter a username and corresponding password that has access to each environment associated with the LPR. SA Valet uses this username and password to log into each environment and update the connection information to the LPR. If SA Valet cannot connect to any of the environments, the move process will abort. Step 12. Click Install to begin the move process. Step 13. After the move process is complete, thoroughly test the new LPR to ensure it is functioning properly. Signs the LPR is functioning correctly include: Successful refresh of your institution s license codes. Successful download of new software updates. Successful installation of software updates into an environment associated with the LPR. Step 14. Once you are satisfied that the new LPR is working correctly, delete the old LPR database on the old host. Managing Colleague Software Environments, January 31,

172 Configuration: Moving a Local Product Repository Troubleshooting Refer to AnswerNet document 6670 for assistance if the move LPR process does not complete or completes with errors. Technical Details This section contains details on the Move Product Repository wizard. This information may be helpful if there are errors with the move process. 172 Managing Colleague Software Environments, January 31, 2013

173 Troubleshooting The move wizard does the following: 1. Check locks, etc. in source LPR before beginning move. Ensures no LPR download job is running, and the source LPR is not currently locked by any installs. 2. Locks the source LPR, so no installs can be started during move. 3. Logs into the database for each environment to validate the logins, read apphome path, and ensure CONNECT_PROD files exist in each before running wizard. Also compares ALSERVRS and DMIACCTS of source and new database and throws a warning if they do not match. 4. Stops the original LPR DAS Listener. 5. Creates new DAS. Install DAS listener service for new LPR. Copy DAS Listener directory files from source to new server {except.log,.out, startdmi or stopdmi files). Check dmiservice.exe and ensures the correct (32-bit or 64-bit) version is placed in new LPR DAS directory. Copy dmi.ini file and override necessary arguments: RegistryName, RegistryUser, RegistryType, RegistryServer, RegistryPort, RegistryPath, JDBCUrl, JDBCDriverName, VaultPassword, auto-start settings. 6. Modifies the following tables with new LPR s information (name, database, DAS, ports, etc.) ALSERVRS DMIACCTS DMILISTENERS 7. Updates all environments with new LPR information. 8. Validates to ensure move succeeded. Check if CONNECT_PROD for each environment has been updated properly. Start LPR DAS and ping new DAS and ensure the Listener is running. 9. If validation succeeds: Delete original DAS Listener service. Delete all records from original database from these tables: APPL_ENVIRON_CONFIG, ENVIRON_RELEASE_PKGS, ENVIRON_GROUP_DEPLOY, ENVIRON_ITEMS, ENVIRON_REL_ITEMS. 10.Stores wizard profile. 11.Unlocks the source LPR so that it is now available for other tasks. 12.Edits SA Valet's tree node to have new LPR information. 13.Edits savalet.ini and vault files to have new LPR information. Managing Colleague Software Environments, January 31,

174 Configuration: Moving a Local Product Repository 174 Managing Colleague Software Environments, January 31, 2013

175 Configuration 95 Resetting an LPR in a Restored Environment In This Chapter This chapter contains information on how to reset your Local Product Repository (LPR) after you have restored an environment from a previous backup. Table 36 lists the topics covered in this chapter. Table 36: Topics in This Chapter Topic Page Understanding an LPR Reset 176 Managing Colleague Software Environments, January 31,

176 Configuration: Resetting an LPR in a Restored Environment Understanding an LPR Reset After an environment has been restored from a backup, you must make sure that the environment and the LPR are consistent with each other regarding installed software updates. If software updates were installed in the environment after the restored backup was created, those software updates will not be available to install into the environment because the LPR shows those updates have already been installed. Resetting the LPR synchronizes the LPR with the software updates that are currently installed in the restored environment, allowing you to install the missing software updates. Restrictions on Resetting an LPR To reset the LPR, the following pieces of the environment must be restored from backups taken at the same time: The environment database The environment apphome All the listener directories pertaining to the environment Security Class The Reset Status of Restored Environment (RSRE) form used to reset the LPR is delivered as a secured form. Users must have the PRIV.RSRE security class to access the RSRE form. 176 Managing Colleague Software Environments, January 31, 2013

177 Understanding an LPR Reset Procedure for Resetting an LPR Follow these steps to reset the LPR to the software updates that are currently installed in the restored environment. Step 1. Restore the environment, ensuring that the environment database, apphome, and associated listeners are restored from backups taken at the same time. Note: You must be running a version of UI that is compatible with the restored environment. Depending on the date of the backup used to restore the environment, you might need to install a previous version of UI to access the environment and reset the LPR. Step 2. In Colleague, access the Reset Status of Restored Environment (RSRE) form (Figure 96) in the restored environment and enter your LPR credentials, if necessary. Figure 96: The Reset Status of Restored Environment (RSRE) Form Managing Colleague Software Environments, January 31,

178 Configuration: Resetting an LPR in a Restored Environment Note: If there are no packages that need to be reset in the environment, a message will be displayed and the RSRE form will close. The RSRE form compares the information in the LPR with the restored environment to determine the list of software updates that will be reset based on the restore date the latest date of any successfully installed Envision software update. You can detail to the Software Update Inquiry (SOUI) form on any of the listed software updates to see more information about the software update that will be reset. Step 3. In the Software Update Group Name field, enter a name for the software update group that will be created for the software updates that will be reset. Step 4. Save your work on the RSRE form. The software updates listed will have their statuses reset in the LPR and a report will be generated that contains information on the software updates that were reset (Figure 97). Figure 97: The RSRE Report After the report has been generated, you will be taken to the Install Software Updates (ISUG) form to install the newly created software update group. Due to dependencies, you may need to install DMI software updates before installing other software updates. Note: If you want to build a different software update group, or use existing software update groups, you can cancel from ISUG and use the Manage Software Update Groups (MSUG) form. See the Updating Colleague Software manual for more information about using ISUG and MSUG to install software updates. 178 Managing Colleague Software Environments, January 31, 2013

179 Understanding an LPR Reset Step 5. If any DMI software updates were reset, use SA Valet to install those software updates. See the Updating Colleague Software manual for more information about installing DMI software updates using SA Valet. Step 6. If any optional module packages were deleted, use the Create Optional Module Group (COMG) form to rebuild and reinstall the optional modules. See the Updating Colleague Software manual for more information about using COMG to install optional modules. Step 7. If any new DMI Listeners were created after the Restore Date listed on the RSRE form, you will need to recreate them after restoring the environment. See the Updating Colleague Software manual for more information about creating DMI Listeners. Step 8. Any information entered on any form in the environment, including security classes, OPERS records, etc., after the Restore Date listed on the RSRE form must be reentered. Managing Colleague Software Environments, January 31,

180 Configuration: Resetting an LPR in a Restored Environment 180 Managing Colleague Software Environments, January 31, 2013

181 Configuration 97 Changing Database Properties In This Chapter This chapter contains information on how to change database properties using SA Valet. Table 37 lists the topics covered in this chapter. Table 37: Topics in This Chapter Topic Page Changing Database Properties 182 Changing the Alias / DNS Name of the Database Server 184 Changing the Database Port 185 Changing the Database Name / Path 185 Managing Colleague Software Environments, January 31,

182 Configuration: Changing Database Properties Changing Database Properties Use the Database Access Server Properties to modify properties for the DMI database access server. These properties are defined originally during the creation of the application environment. Note: You can change the database properties for either the application environment (Figure 99) or the LPR (Figure 100). Step 1. Connect to the application environment or LPR using SA Valet. Step 2. Right-click on the application environment or LPR and select Database Access Server Properties (Figure 98). Figure 98: Select Database Access Server Properties 182 Managing Colleague Software Environments, January 31, 2013

183 Changing Database Properties Figure 99: Database Access Server Properties - Environment Figure 100: Database Access Server Properties - LPR Managing Colleague Software Environments, January 31,

184 Configuration: Changing Database Properties Changing the Alias / DNS Name of the Database Server Complete the following steps if you want to change the alias / DNS name of the database server. Note: You cannot move the database from one server to another using this field. This field simply allows you to change the alias / DNS name of the same server where the database resides. Step 1. Add the new alias / DNS name on the database server. At this point, both the new and the old aliases should be valid for the server. This can be done using the host file for the server: Note: See your network administrator for more information. Step 2. Add a new host in the Hosts tab for SA Valet with the new alias / DNS name. Step 3. Use the Database Host field to change the old alias to the new alias. Click OK. Step 4. Disable the old alias on the database server. Step 5. Ensure that everything works properly in the Environment and LPR. 184 Managing Colleague Software Environments, January 31, 2013

185 Changing Database Properties Changing the Database Port Use the Database Port field to change the port number on which communications to the database occur. Complete the following steps if you want to change the database port. Step 1. Use the Database Port field to change the database port. Click OK. Step 2. Move the database from the old port to the new port instance on the server. Note: See your database administrator for more information. Step 3. Connect back to the Environment and LPR using SA Valet. (This will now use the database on the new port.) Step 4. Start all of the listeners and ensure that everything works properly in the Environment and LPR. This procedure can be used in the case of a database upgrade. For example, upgrading from SQL Server 2005 running on Port 1432 to SQL Server 2008 running on Port 1433 on the same server. Changing the Database Name / Path Use the Database Name / Path field to change the name and path for your database. Complete the following steps if you want to change the database name / path. Step 1. Use the Database Name / Path field to change the database name (path in the case of Unidata). Click OK. (Please note that the new path should also reside on the same server.) Step 2. Move the database from the old name instance (Oracle database ID) to the new instance. See your database administrator for more information. In the Managing Colleague Software Environments, January 31,

186 Configuration: Changing Database Properties case of a Unidata database only, move your apphome directory to the new path on the same server. Step 3. Connect back to the LPR and Environment using SA Valet. (This will now use the database on the new path.) Step 4. Start all of the listeners and ensure that everything works properly in the Environment and LPR. This procedure can be used in the case of a database upgrade. For example, when moving your Colleague schema from one Oracle database ID to another on the same server 186 Managing Colleague Software Environments, January 31, 2013

187 Managing Colleague Software Environments Appendices

188

189 Appendices DMI Listener Names Listener Naming Convention When you create a DMI Listener from one of the wizards in SA Valet, it is assigned a name as shown in Table 38. Table 38: DMI Listener Names Wizard DMI Listener Listener Name Syntax Example Create Local Product Repository DMI data access server for the local product repository lpr name_db_listener coll18_db_listener Create Application Environment or Clone Application Environment DMI data access server for the Colleague database DMI application server environment name_db_listener environment name_app_listener test_db_listener test_app_listener New DMI Listener or Clone Application Environment Other application environment Listeners environment name_listener name a test_printserver a a. You specify the listener name in the New DMI Listener wizard or the Clone Application Environment wizard. This Listener name appears in several places, including: In Windows, this name appears in the Services folder (Figure 101 on page 2). In UNIX, this name appears as the process ID if you view a list of running processes. It also appears as the Listener name in the datateltab file. Managing Colleague Software Environments, January 31,

190 Appendices: DMI Listener Names Figure 101: Example of DMI Listener Name in Windows Services Folder 2 Managing Colleague Software Environments, January 31, 2013

191 Appendices Accessing Colleague from SA Valet In This Appendix Table 39 lists the topics covered in this appendix. Table 39: Topics in This Appendix Topic Page Connecting to the Local Product Repository from SA Valet 2 Connecting to an Application Environment from SA Valet 5 Storing Login Information in the Login Vault 8 When you use SA Valet to manage Colleague environments, you must be logged in to the PC with a login that has administrator rights on the PC. This ensures that SA Valet can read and write to SA Valet-related files on the PC. Managing Colleague Software Environments, January 31,

192 Appendices: Accessing Colleague from SA Valet Connecting to the Local Product Repository from SA Valet Use the following procedure to connect to the local product repository from SA Valet. This procedure will also start the DMI data access server for the local product repository if it is not running. Note: You must be logged in to the PC with a login that has administrator rights on the PC. This ensures that SA Valet can read and write to SA Valet-related files on the PC. Step 1. In SA Valet, select the Environments tab. Step 2. Right-click the node for the local product repository node and select Connect from the pop-up menu (Figure 102). If the Connect option is unavailable, you are done with this procedure (the DMI data access server is already started and this SA Valet installation is connected to it). Figure 102: Connecting to the Local Product Repository from SA Valet 2 Managing Colleague Software Environments, January 31, 2013

193 Connecting to the Local Product Repository from SA Valet Step 3. Perform one of the following, depending on what you see in SA Valet: a. If the nodes for application environments appear (Figure 103), you have successfully connected to the local product repository. You are done with this procedure. This will occur if you previously stored the login information in the login vault and you have already entered the login vault password during this SA Valet session. Figure 103: Successful Connection to the Local Product Repository Node for application environment b. If the Enter Login Vault Password form (Figure 104) appears, enter your login vault password and click OK. In this case, you previously stored the login information in the login vault, but have not yet entered the login vault password during this SA Valet session. Managing Colleague Software Environments, January 31,

194 Appendices: Accessing Colleague from SA Valet Figure 104: Enter Login Vault Password Form c. If the Product Repository Login form (Figure 105 on page 4) appears, enter the following information, and then click OK: Username and Password. Valid username and password for the product repository database (SQL Server or Oracle) or the computer where the database account is installed (UniData). You can use the username and password that you entered when you created the local product repository. Environment Keystore Password. Password for the keystore that was installed with the DMI data access server. This password must match the one you entered when you created the local product repository. Save Login Information. Select this check box if you want to save the username, password, and environment keystore password in a login vault, so that you don t have to enter them in later SA Valet sessions. See Storing Login Information in the Login Vault on page 8 for more information. Figure 105: Product Repository Login Window 4 Managing Colleague Software Environments, January 31, 2013

195 Connecting to an Application Environment from SA Valet Connecting to an Application Environment from SA Valet Use the following procedure to connect to an application environment from SA Valet so that you can manage the environment. After you complete this procedure, the application environment node will be expanded to display Listeners and other nodes. Step 1. In SA Valet, right-click the application environment node and select Connect from the pop-up menu (Figure 106). If the Connect option is unavailable, you are done with this procedure (you have already connected to this application environment). Figure 106: Connecting to the Application Environment from SA Valet Managing Colleague Software Environments, January 31,

196 Appendices: Accessing Colleague from SA Valet Step 2. Perform one of the following, depending on what you see in SA Valet: a. If the application environments expands to display other nodes (Figure 107), you have successfully connected to the application environment. You are done with this procedure. This will occur if you previously stored the login information in the login vault and you have already entered the login vault password during this SA Valet session. Figure 107: Successful Connection to the Application Environment b. If the Enter Login Vault Password form (Figure 108) appears, enter your login vault password and click OK. In this case, you previously stored the login information in the login vault, but have not yet entered the login vault password during this SA Valet session. 6 Managing Colleague Software Environments, January 31, 2013

197 Connecting to an Application Environment from SA Valet Figure 108: Enter Login Vault Password Form c. If the Database Login form (Figure 109) appears, enter the following information, and then click OK: Database Username and Password. Valid username and password for the Colleague database (SQL Server or Oracle) or the computer where the database account is installed (UniData). You can use the username and password that you entered when you created the application environment. Environment Keystore Password. Password for the keystore that was installed with the Colleague DMI data access server. This password must match the one you entered when you created the keystore. Save Login Information. Select this check box if you want to save the username, password, and environment keystore password in a login vault, so that you don t have to enter them in later SA Valet sessions. See Storing Login Information in the Login Vault on page 8 for more information. Figure 109: Database Login Window Managing Colleague Software Environments, January 31,

198 Appendices: Accessing Colleague from SA Valet Storing Login Information in the Login Vault In order to safeguard Colleague information, you are required to enter login credentials when you try to access, from SA Valet, any of the following: Local product repository. Application environments. The Colleague application. Figure 110 is an example login form in SA Valet for accessing the local product repository. Figure 110: Login Form for the Local Product Repository To simplify the login process, you can create a password-protected login vault. The login vault is a file that stores, in encrypted form, the login information described above. Once you have populated the login vault with the login information, you only need to enter one password (to the login vault itself) during each SA Valet session. After entering that password, you won t be prompted for other login information. Technical Tip: The login vault is the profile file stored in the security directory under SA Valet. Example path to that file: C:\Program Files\Datatel\SaValet 2.5.0\security\profile. Each installation of SA Valet can have just one login vault. 8 Managing Colleague Software Environments, January 31, 2013

199 Storing Login Information in the Login Vault How to Use the Login Vault Each login form in SA Valet has a Save Login Information check box that gives you the option to store that login information in the login vault. See Figure 110 on page 8 for an example. The first time you select that check box on any login form and click OK, you will be prompted to create a password for the login vault, using the Create Login Vault form shown in Figure 111. Figure 111: Create Login Vault Form Enter a password to be saved for future logins to SA Valet After you enter (and confirm) the new login vault password and click OK, the login vault will be created and the login information stored. (Actually, the information is stored in memory until you exit SA Valet, when the login vault [the profile file] is created.) If you enter incorrect login information, it won t be stored in the login vault. SA Valet verifies the login information before storing it. As you continue to work in SA Valet and enter other login information, that information will be stored in the login vault if the Save Login Information check box on those login forms is selected. The next time you access SA Valet, you will be prompted one time for the login vault password, using the Enter Login Vault Password form shown in Figure 112. Figure 112: Enter Login Vault Password Form Enter the password you created earlier. Managing Colleague Software Environments, January 31,

200 Appendices: Accessing Colleague from SA Valet Eventually, when you reach the point where you have entered all of your login information in the login vault, you will only need to enter one password per SA Valet session (the login vault password). You won t be prompted for any other login information. Forgot the Password? If you forget the login vault password, you can still use SA Valet. When you are prompted for the login vault password (Figure 112 on page 9), click Cancel. You will then be prompted for the login information to the entity (local product repository, application environment, etc.) that you were trying to access. If you have permanently forgotten the login vault password, you can clear the current login vault information. From the Tools menu, select Clear Login Vault, as shown in Figure 113. Figure 113: Clear Login Vault Menu Option in SA Valet After the login vault information is cleared, you can create a new login vault with a new password, using the process described in How to Use the Login Vault on page 9. You will need to re-enter all login information. 10 Managing Colleague Software Environments, January 31, 2013

201 Storing Login Information in the Login Vault Using SA Valet Without the Login Vault Other users who don t know the login vault password can still use this SA Valet installation. When prompted for the login vault password (Figure 112 on page 9), they should click Cancel. They will then be prompted for the login information to the entity (local product repository, application environment, etc.) that they are trying to access. Changing the Login Vault Password To change the password for the login vault, select Tools >Change Vault Password. You will be prompted to enter the current password once, then the new password twice for confirmation (see Figure 114). Figure 114: Change Vault Password Dialog Box Managing Colleague Software Environments, January 31,