Skip to main content
CollegeSource Support

Installation and Upgrade Guide for Webapps


This guide details how to install and upgrade the uAchieve 4.5 web apps. All new and existing users should follow this guide.

BEFORE YOU BEGIN
The installation/upgrade process is very different from previous uAchieve releases. Please read this guide carefully, and review the System Requirements before you begin.

 

Do not copy PROPERTY and PROPERTY_CONFIG tables
Through the installation/upgrade process, you may copy back from your production environment to your test environment. Be aware that this can wipe out all of your configs if you copy your PROPERTY and/or the PROPERTY CONFIG tables.

 

CSIHome Directory Structure

CollegeSource-security.properties

CollegeSource.properties

+daversion folder

  • Contains the three types of degree audit files (darwin, uachieve, peoplesoft).

CSIHome/daversion requires configuration only if running uAchieve Planner

+loader folder

  • Place old property files you want to load into the database here.

+logs folder

  • Place logs for the applications here. Update your log4j2.xml within each app to point here.

+programMatcher_index folder

  • This is where Program Matcher will build its index files.

quartz.properties

+reports folder

  • Recommended to put all report files here to customize or to change.

+scheduleBuilder_index folder

  • This is where Schedule Builder will build its index files.

Step 1: Download Dashboard

Dashboard 4.5 download files are available in the Support Center.

Two options for running scripts exist, depending upon whether your installation is a new installation or an upgrade installation:

MSSQL database users: be sure to add global configs to the school

> New Install

NOTE:
Prior to running, locate the "create" scripts in the vendor-specific directories of the release distribution files. INSTIDQ and INSTID variables are found on the lines indicated below:

ORACLE 2244
DB2 1906
MSSQL 1653
    • In the "create" script, set two variables to your institution's INSTIDQ and INSTID:
    • Run the single "create" script to create all of the tables and other objects required for the uAchieve Suite schema. This also inserts the data into the PROPERTY table and the PROPERTY_CONFIG table in the database to set up some default property values. Data will also be inserted into various tables, with the following considerations:
      • Inserts into various other tables, including default groups and roles
      • Allows the user to access the application with ALL permissions
      • What default status indicators to set on roadmap requirements and courses when building roadmaps, etc.

Ensure your DBA grants security access to appropriate users for the two new tables created by the scripts: PROPERTY and PROPERTY_CONFIG.

 

> Upgrade Install

Handling schools with multiple instIDs
Use the institution's InstID and InstIDQ in the PROPERTY table to update

1. Upgrade the backend database to 4.3 (script running-wise) to move the backend uAchieve database schema from the 4.3 format to 4.4 format.

You must upgrade the backend database to 4.3 prior to running an "update" script for 4.4 (below).

2. Run the "update" scripts for 4.5

Step 2: Grab the Reports

Grab the report-ctx.xml after running the scripts since that is database-version specific.

  • Locate the database vendor-specific report-ctx.xml file from the directory you just ran the scripts for
  • Copy and paste that file into the <dashboardRoot>/WEB-INF/classes/ctx/ directory
  • Step 3: Configure Dashboard Files

The required files that need to be configured will be found in the config folder in the dashboard-4.5.zip

  • (Optional) Move the security-ctx.xml for your specific implementation from config/security/implementation into the dashboard/WEB-INF/classes/ctx 
    • By default, Dashboard will start up out-of-the-box using DAO security implementation.
  • (Optional) If you did update the security-ctx.xml to your security implementation: you will need to update the CollegeSource-security.properties found in the CSIHome folder with your implementation settings
  • (Optional) If you install with WebLogic: The base installation of Dashboard contains the directory dashboard-4.5\config\weblogic that contains two files specific to WebLogic:

    • jasper-compiler-jdt-5.5.23.jar must be placed in dashboard\WEB-INF\lib

    • weblogic.xml must be placed in dashboard\WEB-INF\

      • If running uAchieve Planner, Self-Service and/or Schedule Builder, you must also place this file in those application's <webApp>\WEB-INF\ directory.
  • Update the home.properties file with the location where your CSIHome folder will exist and the daversion 

    Create a copy now to place in every app later.

     

    Avoid placing a closing "/" at the end of the csi.home location

     

  • Update the log4j2.xml appender locations to the logs folder in the CSIHome directory location (line 85 and 86 for file name and file pattern in the log4j2.xml)
  • Only if running uAchieve Planner: Update one of the three degree audit files found in CSIHome/daversion for the degree audit you are using. The value set in the daversion home.properties field determines which property file the application reads from–this is the property file that needs to be updated. (You may remove the two unused files):
    • darwin.properties
    • peoplesoft.properties
    • uachieve.properties

      Check your server to find the values to set here.

       

  • Update the CollegeSource.properties found in the CSIHome folder. Required properties (essentially datasource and school) are described below:

    Property Description
    instidq

    Default institution to use when not set via properties on groups/users

    instid

    Default institution to use when not set via properties on groups/users

    CollegeSource.instcds

    The different instcds that will be available to select at log in when logging in via Self-Service. The format is simple: instcds are defined using an actual instcd value, plus a name to describe that instcd to the user (e.g., "MU" and "Miami University"). The instcd and name are separated by a colon (:) and each instcd/name pair are separated by a comma (,). Optionally, you can have a single instcd/name pair per line by using the backslash (\) to continue the definitions on the next line.

    Here's the formal syntax:  <instcd1>:<name1>,<instcd2>:<name2>, etc...

    CollegeSource.jdbc.driver

    JDBC driver class name 

    com.microsoft.sqlserver.jdbc.SQLServerDriver (MS SQL

    oracle.jdbc.OracleDriver (Oracle)

    CollegeSource.jdbc.url

    JDBC URL
    jdbc:sqlserver://[server name]:1433;databaseName=[database name]; (MS SQL
    jdbc:oracle:thin:@[server name]:1521/[database name] (Oracle)

    CollegeSource.jdbc.username

    JDBC user name

    CollegeSource.jdbc.password

    JDBC password

    CollegeSource.jdbc.jndi

     

    CollegeSource.jdbc.validationQuery

    The SQL query that will be used to validate connections from this pool before returning them to the caller.  If specified, this query MUST be an SQL SELECT statement that returns at least one row.

    CollegeSource.hibernate.dialect

    The dialect that hibernate will use to run against your SQL database

     

    JTDS No Longer Supported
    Third-party library updates made in 4.4 require the MSSQL JDBC jar, which means that JTDS is no longer supported (do not copy/paste!).

     

  • Move the CSIHome folder to its new location on your system that you specified in your home.properties

Step 4: Set up the Database Migration Tool (UPGRADE INSTALL ONLY)

The property to database migration tool now included in Dashboard 4.4 will move any existing configuration changes from a previous version of the u.achieve Suite to its new database location uAchieve Suite 4.5.

  • Run the query (below) against your database to direct the  Database Migration Tool to run on the next startup of Dashboard
    • Every property updated in the database will be listed in the Dashboard log file
    • Save your dashboard.log to get a complete list of every database table that was updated (useful for cross-checking)
    update PROPERTY_CONFIG set VALUE = 'T' WHERE PROPERTY_NAME = 'RUN_PROP_LOADER'

     

  • Locate any properties files from your previous installation of the uAchieve Suite webapps. Below is a list of files to look for, by application:

    Self-Service

        • selfservice-general.properties
        • selfservice-audit.properties
        • selfservice-batch.properties
        • selfservice-graph.properties
        • selfservice-misc.properties
        • selfservice-student.properties
        • email.properties
        • message.properties

    uAchieve Planner

        • udirect.properties

    Dashboard

        • dashboard.properties
  • Copy any of the above properties files to the loader folder found in your CSIHome folder.

  • The next time you start up Dashboard, the migration tool will copy all of the configurations in the properties file in the loader folder to the PROPERTY_CONFIG table.
  • If you already started Dashboard and want to migrate more files, see the note below to reset the migration tool.
Reset the Migration Tool
CAUTION
Resetting the Property Config flag back to "true" can potentially override all of your work.

RUN_PROP_LOADER property in the PROPERTY_CONFIG table tells the loader whether to run or not. It only runs once when Dashboard is initially started. Change the value of this property back to "true" ("T") to make the database Migration Tool run again the next time Dashboard is restarted. Every property updated in the database will be listed in the Dashboard log file again. Save this to get a complete list of every database table that was updated (useful for cross-checking)

update PROPERTY_CONFIG set VALUE = 'T' WHERE PROPERTY_NAME = 'RUN_PROP_LOADER'

 

 Refreshing the database will refresh all of these changes. This logging will only display the first time and not on subsequent restarts.

To check changes outside of the logs, the LAST_MOD_USER column will be marked as "Loader"

select * from PROPERTY_CONFIG where LAST_MOD_USER = 'Loader'

 

Will only run for the default insitution (i.e.,instcd of DFL)

Step 5: Deploy Dashboard

Move the following files from the config folder into dashboard/WEB-INF/classes/

  • home.properties 
  • log4j2.xml

Tomcat Deploy

To configure and deploy the Dashboard application, you have two options:

  • The first option is to copy the modified configuration files listed above from the config folder to a shared directory. When using Tomcat 5.x, there is a directory called [Tomcat]/shared/classes available for you to use. In Tomcat 6.x or later, you would need to create a folder and extend your app server's classpath to include it. See your application server's documentation to see how this is done. Once you have placed the config files into a shared directory, put the dashboard.war file directly in the [Tomcat]/webapps directory without any modification. Then, start the Tomcat server.

  • The second option is to deploy the WAR file in the [Tomcat]/webapps directory so that it explodes to a directory. Then, copy the files list above from the config folder into dashboard/WEB-INF/classes. Note that a restart of Tomcat does need to be done after copying the files there.

Oracle Application Server (OAS) Deploy

Within your distribution directory, uncompress the dashboard.war file by following these steps:

  • Create the Dashboard directory, change to the Dashboard, and uncompress the .war file contents by typing the following commands:
    mkdir dashboard
    cd dashboard
    jar -xvf ..\dashboard
  • Copy the modified configuration files the files list above from the config folder directory of the distribution to the dashboard/WEB-INF/classes directory. Type the following:
    cd WEB-INF\classes
    copy ..\..\..\config* .
  • Recreate the dashboard.war file based on the content within the Dashboard directory by typing the following:
    cd ..
    cd ..
    del ..\dashboard.war
    jar -cvf ..\dashboard.war *
  • Deploy the new dashboard.war file on OAS

Step 6: Start Dashboard and Review Configurations

> New Install

  • Start up Dashboard
  • Test Dashboard to verify your installation
  • Log in to Dashboard with username: Superuser and password: password
  • In the menu, click on the gear icon () and then select the Admin option
  • The first thing you MUST do is configure your application links for the products you own, thereby enabling all other admin configurations related to those products
  • Begin updating all configurations for your products. (This requires a logout for all users to see any changes made.).

> Upgrade Install

  • Start up Dashboard
  • Test Dashboard to verify your installation
  • Review the Dashboard log file and the PROPERTY_CONFIG table:
    1. Review the Dashboard log, which should be found in your logs folder in your CSIHome folder. You should see log statements stating which configurations where migrated by the Migration tool.
    2. Review your PROPERTY_CONFIG table to make sure implemented changes have applied (this depends on the school).
  1. Log in to Dashboard with username: Superuser and password: password
  2. In the menu, click on the gear icon () and then select the Admin option
  3. From here, review all of your migrated configurations. Also make any additional configuration changes to the products, as desired.
  4. If the data migration tool did not run as expected, stop Dashboard and reset the database migration tool.

Step 7: Set Security Roles and Permissions

  1. Follow the Security Documentation to setup application permissions for your user and groups.

First, assign users to a role of either CS_STAFF or CS_STUDENT–not both–before adding further user permissions.

Step 8: Install Self-Service, uAchieve Planner, and/or Schedule Builder

  1. Download the application that you want to install:

    Self-Service Downloads uAchieve Planner Downloads Schedule Builder Downloads

     

  2. Update the log4j2.xml appender locations to the logs folder in the CSIHome directory location (line 85 and 86 for file name and file pattern in the log4j2.xml) and move to application/WEB-INF/classes
  3. If you did not put the home.properties in Dashboard on a shared classpath on the  web server, then you will need to copy that file into  application/WEB-INF/classes
    1. Step 7 is optional if you used a shared classpath
  4. (Optional) Move the security-ctx.xml for your specific implementation from config/security/implementation into the application/WEB-INF/classes/ctx 
    1. By default, the application will start up out-of-the-box using DAO security implementation.

Proceed to which web apps you have (in no particular order):

uAchieve Planner Self-Service Schedule Builder

Configure the udirect-yearTermTemplate-ctx.xml in the config folder and then copy it into Planner/WEB-INF/classes

The JDBC folder in the config directory of the uAchieve Planner contains third-party database drivers if you need them.

 

 

Before you begin...
Does your SIS use a different database connection than uAchieve?

Configure the message.properties in the config folder and then copy it into selfservice/WEB-INF/classes

Configure the quartz.properties in the config folder and then copy it into selfservice/WEB-INF/classes

Copy either the banner or peoplesoft xml files from their folder found in conf/SIS/  and then copy it into schedulebuilder/WEB-INF/classes/ctx

For new install of Schedule Builder, you will need to go to collegesource.properties and set the SIS datasource. Schedule Builder will not start without this.

 

 

Quartz Database Change
Third-party library changes made in 4.4 included an update to Quartz 2.3. We missed including an update script to add a column. Run the following script based on your database vendor:

Oracle

alter table QRTZ_FIRED_TRIGGERS add (SCHED_TIME NUMBER(13) NOT NULL)

MSSQL

alter table QRTZ_FIRED_TRIGGERS add SCHED_TIME [BIGINT] NOT NULL

DB2

alter table QRTZ_FIRED_TRIGGERS add SCHED_TIME NUMERIC(19) NOT NULL DEFAULT 0

 

Step 9: Deploy the Web Apps

Deploy and test the web apps. Some help with troubleshooting the web apps is also available.

 

  • Was this article helpful?