Go to primary content
Oracle® Health Sciences WebSDM and Empirica Study Upgrade Instructions
Release 3.1.2.1 for Windows 2003/2008 Server
E40536-02
  Go To Table Of Contents
Contents

Previous
Previous
 
 

2 Upgrade to WebSDM 3.1.2.1

This chapter contains information on upgrading to WebSDM 3.1.2.1.

2.1 Prerequisites

You must have the following information when you start the upgrade. In these procedures, the values are shown in <text_in_angle_brackets>.

  • The installation media for WebSDM 3.1.2.1

    The product ZIP file from My Oracle Support (https://support.oracle.com).

  • Windows administrator account

    <win_admin_acct> and <win_admin_pass>

    Windows account and password on the server where WebSDM is installed. The account must have the Administrator role.

  • Installation root

    <root>

    File system root where the \Lincoln subdirectory is located, typically C:\.

  • WebSDM instance name

    <instance>

    Name of the WebSDM 3.1.2 instance you are upgrading.

  • WebSDM Superuser account and password. For example, the admin username supplied with WebSDM is a Superuser.

    <app_admin_acct> and <app_admin_pass>

    Password for the WebSDM user account with the reserved name admin, or other Superuser.

    Note whether the WebSDM application server is 32-bit or 64-bit.

    Note the operating system version running on the WebSDM server (Windows 2003 or Windows 2008).

  • WebSDM Windows user account

    <win_user_acct>Name of the Windows account that is running the WebSDM service. Usually this is the WebSDM instance name, with the suffix, _app, appended. For example, websdm_app.

You must also have access to the Java jar and jarsigner utilities, and to your company's jar signing process.

2.2 Stop the WebSDM Service

  1. Log into WebSDM as <app_admin_acct>.

  2. Click Settings, and then click View Currently Logged in Users.

  3. If sessions in addition to your own are running, either instruct the users to finish their sessions or cancel the sessions from the WebSDM interface.

  4. Exit WebSDM.

  5. Log into the Windows administrator account using <win_admin_acct>.

  6. Select Start > Administrative Tools > Services.

  7. Right-click the <instance> service, and then click Stop.

  8. Right-click World Wide Web Publishing Service, and then click Stop.

  9. Navigate to the <root>\Lincoln\apps\<instance>\bin folder.

  10. Do one of the following:

    • (Windows 2008 server)-Right-click the uninstall_service.bat file, and select Run as administrator.

    • (Windows 2003 server) -Double-click the uninstall_service.bat file.

2.3 Modify the Tomcat and JDK Configurations

  1. Back up the <root>\Lincoln folder.

  2. Locate the Lincoln.zip file on the installation media. (For a 64-bit server, use Lincoln_x64.zip.)

  3. Extract the contents of this file to a temporary folder, making sure that path names stored in the archive will be used (for example, in WinZip, the Use folder names checkbox must be selected).

  4. Copy the apache-tomcat-6.0.41 folder from the temporary folder to the <root>\Lincoln folder.

  5. Delete the \apache-tomcat-6.0.36 folder under <root>\Lincoln.

  6. Update the JDK:

    1. Delete the jdk1.x folder under <root>\Lincoln\.

    2. Locate the jdk1.6 folder in the temporary folder, and copy the folder to the <root>\Lincoln folder.

  7. Delete all the files from the <root>\Lincoln\apps\<instance>\bin folder.

  8. Copy all the files from the temporary \Lincoln\apps\<instance>\bin folder into <root>\Lincoln\apps\<instance>\bin folder.

2.4 Upgrade the WebSDM Software

  1. Locate the <root>\Lincoln\apps\<instance>\webapps\web_root folder on the server that is running your current installation of WebSDM. Copy the contents of this folder to a temporary folder, such as C:\temp\web_root.

  2. Delete the contents of the <root>\Lincoln\apps\<instance>\webapps\web_root folder, keeping the folder itself in place.

  3. Locate the websdm-3_1_2_1_4xx.zip file (where 4xx represents a specific build number) on the installation media. Extract the contents of this file to the <root>\Lincoln\apps\<instance>\webapps\web_root directory, making sure that path names stored in the archive are used (for example, in WinZip the Use folder names checkbox must be selected).

  4. Restore your saved copy of website.properties, and of license.config, if it exists, from the temporary folder C:\temp\web_root\WEB-INF\classes\ to <root>\Lincoln\apps\<instance>\webapps\web_root\WEB-INF\classes.

  5. Restore your saved copy of ojdbc*.jar (either ojdbc6.jar or ojdbc14.jar) from the temporary folder C:\temp\web_root\WEB-INF\lib\ to <root>\Lincoln\apps\<instance>\webapps\web_root\WEB-INF\lib.

  6. If you have created or included any custom content (home pages or logos), copy the files from the \customhomes or \image subfolder under C:\temp\web_root\ to the respective subfolder under <root>\Lincoln\apps\<instance>\webapps\web_root.

  7. Delete the contents of the <root>\Lincoln\apps\<instance>\work folder.

2.5 Reinstall the WebSDM Service

This section contains information on reinstalling the WebSDM Service on Windows 2003 and 2008 configurations.

2.5.1 Reinstall the WebSDM Service for Windows 2008

This section is for Windows 2008 Server only.

  1. Delete the existing Windows user account that is running the WebSDM service.

    1. Select Start > Administrative Tools > Server Manager > Configuration > Local Users and Groups > Users.

    2. Right-click the account named <win_user_acct> (usually <instance>_app) that is running the WebSDM service.

    3. Click Delete, and then click Yes to confirm.

  2. Close Administrative Tools.

  3. Navigate to the <root>\Lincoln\apps\<instance>\bin folder.

  4. If you are using a WebSDM instance name other than websdm:

    1. Edit the uninstall_service.bat file.

    2. Change the value of SERVICE_NAME from websdm to the value of <instance>.

    3. Save your changes.

    4. Edit the install_service.bat file.

    5. Change the value of SERVICE_NAME from websdm to the value of <instance>.

    6. Change the value of the APPLICATION_DIR from websdm to the value of <instance>.

    7. Save your changes.

  5. Right-click the install_service.bat file, and then select Run as administrator.

  6. After install_service.bat runs, inspect the transcript to ensure that no errors occurred. When you are finished, press any key.

  7. Select Start> Administrative Tools > Server Manager > Configuration > Local Users and Groups > Users.

  8. Right-click <instance>_app and select Set Password.

  9. In the Set Password for <instance>_app dialog box, click Proceed.

  10. Change the password according to the password policy restrictions at your site, and click OK.

  11. Click Services.

  12. Right-click the <instance> service, and select Properties.

  13. On the Log On tab, click This account, clear the password fields, and enter the password you just changed.

  14. On the Recovery tab, select the Restart the Service value for both First Failure and Second Failure.

  15. On the General tab, set Startup type to Automatic (Delayed Start).


    Note:

    This setting allows time for the database service to start before the WebSDM application service.

  16. Click OK.

2.5.2 Reinstall the WebSDM Service for Windows 2003

This section is for Windows 2003 Server only.

  1. Delete the existing Windows user account that is running the WebSDM service.

    1. Right-click the server's desktop My Computer icon and select Manage. Expand System tools > Local Users and Groups > Users.

    2. Right-click Users and select the account named <win_user_acct> (usually <instance>_app) that is running the WebSDM service.

    3. Click Delete.

    4. Close the Computer Management window.

  2. Navigate to the <root>\Lincoln\apps\<instance>\bin folder.

  3. If you are using a WebSDM instance name other than websdm:

    1. Edit the uninstall_service.bat file.

    2. Change the value of SERVICE_NAME from websdm to the value of <instance>.

    3. Save your changes.

    4. Edit the install_service.bat file.

    5. Change the value of SERVICE_NAME from websdm to the value of <instance>.

    6. Change the value of the APPLICATION_DIR from websdm to the value of <instance>.

    7. Save your changes.

  4. Double-click the install_service.bat file.

  5. After install_service.bat has completed, inspect the transcript to ensure that no errors occurred. When you are finished, press any key.

  6. Close the Command window.

  7. Right-click the server's desktop My Computer icon and select Manage. Expand System Tools > Local Users and Groups > Users.

  8. Right-click <instance>_app, and select Set Password.

  9. In the Set Password for <instance>_app dialog box, click Proceed.

  10. Change the password, using the password policy restrictions at your site, and click OK.

  11. Expand the Services and Applications directory, and then click Services.

  12. Right-click the <instance> service, and select Properties.

  13. On the Log On tab, click This account. Clear the password fields, and enter the password you just changed.

  14. On the Recovery tab, select Restart the Service for both First Failure and Second Failure.

  15. Click OK.

2.6 Add Manifest Entries and Sign JAR Files

Modify the WebSDM JAR files to enable users to work with DataMontage graphs in applet mode. If you do not perform this procedure:

  • Security-related dialog boxes appear when users work with DataMontage graphs in applet mode.

  • DataMontage might be blocked by a client machine's security settings.

Before you begin, verify that:

  • The PATH variable on the application server includes the jdk1.6\bin directory.

  • You have access to the Java jar and jarsigner utilities in the jdk1.6\bin directory.

  • You have access to your company's JAR signing process.

  1. From the <root>:\Lincoln\apps\<instance>\webapps\web_root\AppJars\DataMontage23\ folder, copy the lti.jar and DataMontage.jar files to a temporary folder such as C:\temp\UpdateJarManifest\.

  2. Update the manifest is both JAR files:

    1. In the temporary folder where you copied the JAR files, create the following text files.

      • AddToDMjar.txt

      • AddToLTIjar.txt

    2. In a text editor, insert the following lines in the AddToDMjar.txt file.

      Caller-Allowable-Codebase: *
      Codebase: *
      

      Note:

      You must include a carriage return after the last line.

    3. In a text editor, insert the following lines in the AddToLTIjar.txt file.

      Application-Library-Allowable-Codebase: *.example.com
      Caller-Allowable-Codebase: *.example.com
      Codebase: *.example.com
      

      where example.com is the domain name or IP address where the Empirica Study application is hosted. For more information, see https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/manifest.html


      Note:

      You must include a carriage return after the last line.

    4. Save and close the text files.

    5. In a Windows command window, navigate to the temporary folder containing the JARs and text files.

    6. At the prompt, issue the following commands:

      jar -ufm DataMontage.jar AddToDMjar.txt
      jar -ufm lti.jar AddToLTIjar.txt
      
  3. Sign the modified JAR files using your company's JAR signing process.

    If the process includes using Java's jarsigner utility, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/jarsigner.html for information about the utility.

  4. Copy both signed JAR files to the <root>:\Lincoln\apps\<instance>\webapps\web_root\AppJars\DataMontage23\ folder, replacing the original files.

  5. Copy only the signed DataMontage.jar file to the <root>:\Lincoln\apps\<instance>\webapps\web_root\WEB-INF\lib\folder, replacing the original file.

    You do not need a copy of lti.jar in this folder.

2.7 Set File Permissions

  1. Navigate to the <root>\Lincoln\apps\<instance>\bin folder.

  2. Use a text editor to open the file set_permissions.bat and review the values of SERVICE_NAME, INSTALL_ROOT and APPLICATION_DIR, and WORKING_DIR:

    1. If the value of <instance> is other than websdm, change the values of SERVICE_NAME, APPLICATION_DIR, and WORKING_DIR to the value of <instance>.

    2. If the value of <root> is other than the C drive, change the value of the INSTALL_ROOT to the value of <root>.

    3. If the D drive is not an acceptable location for the working directory, change the drive for WORKING_DIR to an acceptable drive.

    4. Verify that CATALINA_HOME is defined correctly.

  3. Optionally, grant permissions to a Windows group of non-administrator users who might require access to the log files and \web_root folder.

    1. While editing the set_permissions.bat file, locate the following lines:

      REM -

      REM - Local Administrators group

      REM -

      REM SET ADMIN_GROUP=Study Operators

    2. Remove REM from the REM SET ADMIN_GROUP line.

    3. Replace Study Operators with the Windows user group that requires access.

  4. If changes are needed, edit, save, and close the file.

  5. When you are prompted, press any key.

  6. Examine the log file <root>\Lincoln\apps\<instance>\logs\set_permissions.log for errors. If errors occur, you must take ownership, recursively, of C:\Lincoln\apps\<instance> and D:\websdm, and then repeat this procedure.

  7. Do one of the following:

    • (Windows 2003 server) -Double-click the set_permissions.bat file.

    • (Windows 2008 server) -Right-click the set_permissions.bat file, and then select Run as administrator.

2.8 Start Instance

  1. Select Start > Administrative Tools > Services.

  2. Right-click the <instance> service, and then select Start.

  3. Right-click the World Wide Web Publishing Service, and then click Start. If the service is already running, click Restart.

  4. In an Internet Explorer window, access the URL for WebSDM.

  5. If you receive a message that the server is still initializing, wait a few minutes and access the URL again.

2.9 Set Site Options and Restart Listener

  1. Log into WebSDM as <app_admin_acct>.

  2. Click Settings.

  3. Click Set Site Options.

  4. Set System Version Description to Version 3.1.2.1.

  5. Click Save.

  6. Click Continue.

  7. Click Restart Listener.

  8. Log out.

2.10 Verify the WebSDM Upgrade

For Upgrade Qualification (UQ) and Operational Qualification (OQ) testing, see the UQ_Test.doc and OQ_Test.doc files on the installation media.