*Described in the Release Notes. Generally this step will be performed by the admin end-users.

(1)

StudioAbroad 6 Installation Instructions Page 1

StudioAbroad 6 FP

Installation Instructions

Overview

The installation of StudioAbroad v. 6 FP entails the following steps: 1. Installation/configuration of web server.

2. Installation/configuration of Adobe ColdFusion. 3. Database schema creation and configuration. 4. Installation of StudioAbroad application code tree. 5. Creation/base configuration of settings file (host INI). 6. Configuration:

a. Maintenance & Installation Utilities b. System Settings (by admin end-users) *

*Described in the Release Notes. Generally this step will be performed by the admin end-users.

Webserver/Website Configuration

It is recommended that the webserver software be installed and activated before installation of ColdFusion. The following instructions are meant to be generic and applicable to either Apache or IIS, although the terminology may more closely reflect IIS.

1. Create a new website with its home configured as the directory where the StudioAbroad code is to be installed. StudioAbroad can also be installed as a subdirectory or virtual directory of the web root, though some additional configuration is needed for this type of setup.

2. Create a directory _usermedia as subdirectory of the site root, or alternatively, create a virtual directory _usermedia pointing to a network share or other local drive.

ColdFusion must have read-write permissions (recursively) on

• {SA_MEDIA_ROOT}_usermedia/ • {SA_ROOT}maintenance/dictionary/

3. Assign one or more DNS hostnames for the website. This can be done at any time before launch and requires only a minor configuration change in StudioAbroad for each added hostname.

4. Acquire and install a trusted SSL certificate. The secured host can be different from the non-secure host name if necessary. However, the relative path to the site root must be the same. That is:

OK http://studyabroad.university.edu/

https://www.studyabroad.university.edu/

OK http://www.international.university.edu/studyabroad/

https://secure.university.edu/studyabroad/

X http://www.educationabroad.university.edu/_{https://secure.university.edu/websites/intl/educationabroad/}

Recommended: if a trusted SSL certificate has not been acquired yet, install a self-signed certificate in the interim. This will allow the site to be enabled for secure

communications and will not require reconfiguring StudioAbroad after the SSL certificate is purchased.

(2)

Configuring ColdFusion for StudioAbroad:

The following settings represent a typical initial configuration for use with StudioAbroad. The outline follows the organization of the ColdFusion Administrator. Use default settings where not indicated here. Other settings may be altered to suit the needs of the environment where installed, but there may be some compatibility issues encountered. Please notify Terra Dotta for questions about specific desired settings outside of those below.

Server Settings: Settings:

[X] Timeout Requests after ( seconds ) [ 300 ] (Timeout can be adjusted depending on needs.)

[O] Enable HTTP status codes

[X] Enable whitespace management (recommended) Memory Variables:

Enable all:

[X] J2EE session variables [X] Application Variables [X] Session Variables Mail:

Mail Server: institution SMTP server and any necessary security settings. See Post-installation Steps: Testing: 1.c. (page 8) for testing instructions. Also enable Logging:

[X] Log all mail messages sent by ColdFusion

Java and JVM: Check the version of JVM installed by looking under SYSTEM

INFORMATION. ColdFusion 8 ships with JVM v. 1.6. If the JVM version is less than 1.4.2_11, it is strongly recommended that you upgrade to that version for conformance with the 2007 Daily Saving Time change, or to the highest JVM level supported for your version of ColdFusion, following Adobe’s instructions:

http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=d2ab4470

Data & Services: Data Sources:

Follow Adobe ColdFusion documentation for adding your data source(s), the StudioAbroad database and any queriable SIS/HR data sources that will be accessed in the campus data integration (to be completed at the appropriate time). Relevant settings:

Data Source Name: can be whatever desired; this will be set the host INI file for the StudioAbroad site.

Advanced: Allowed SQL: SELECT; INSERT; UPDATE; DELETE Debugging & Logging:

Debugging Setting:

[O] Enable Robust Exception Information (This can be enabled during the installation process for troubleshooting.)

Logging Settings:

Log file size and archiving settings may be set according to needs. [X] Log slow pages taking longer than 30 seconds (optional) [X] Enable logging for scheduled tasks (optional)

Scheduled Tasks:

A task configuration utility is provided in the Maintenance & Installation area. StudioAbroad uses several scheduled tasks for such processes as data refresh from SIS, automated reminder e-mails, decision notifications, and log purge.

The following indicate the state of checkboxes in ColdFusion Administrator indicated above: [X] = Enable

(3)

Database Schema Setup

Installation Files:

SA6FP_schema_ddl_DBMS.sql: StudioAbroad 6 FP database schema (DDL) SA6FP_dataload.sql: common data-loader script (DML)

DBMS Installation notes:

• MySQL must be configured to permit mixed-case table/column referencing. • Oracle must be installed with either ISO-8859-1 or UTF-8 character set enabled. • MS SQL default installation settings may be used.

1. Create a database/schema named studioabroad or any other name you prefer. Ensure that a database user exists with SELECT, UPDATE, INSERT and DELETE on all objects in the schema. (If the schema owner or other privileged user is to be used for the data connection from StudioAbroad, special data source configuration can be done in ColdFusion to limit the SQL commands permitted.)

2. Configure network access to permit the web application server to connect to the database.

3. Connect to your DBMS server in the schema context of the database you have created and run the DDL script: SA6FP_schema_ddl_DBMS.sql

Expected warnings on MS SQL Server (ignore):

Warning: The table 'table_name' has been created but its maximum row size (####) exceeds the maximum number of bytes per row (8060).

4. Oracle only: verify all triggers have been compiled and are valid. 5. Run the data loader scripts SA6FP_dataloader.sql.

6. Oracle only: execute a COMMIT statement (if no errors in the data loader step, else ROLLBACK).

Account initialization steps

There are three database records that must be seeded in order to establish the site account and an initial admin (staff) user. The staff1 user will have full permissions on the site administration but does not have secure credentials (username and password are ‘staff1’). Therefore it is essential that the user be deactivated once the campus data integration is underway, to prevent unauthorized access to student records.

1. Insert a record in tbl_Accounts

• Account_Name: name of the office / organization (e.g. “Study Abroad at SAU”)

• Account_Host: must match the DomainHost setting from the Host INI • Account_Active: 1 (or True for SQL 2005 client)

• Leave all other fields null 2. Create a staff record in tbl_Users

• Use Account_ID from the record in tbl_Accounts • User_Name: staff1

• User_Type_ID: F

• User_Password_Enc: 4D7D719AC0CF3D78EA8A94701913FE47 3. Create a record in lnk_User_Roles

• User_ID from tbl_Users • Role_ID: 2

(4)

4. Create a student record in tbl_Users

• Use Account_ID from the record in tbl_Accounts • User_Name: student1

• User_Type_ID: F

• User_Password_Enc: 5E5545D38A68148A2D5BD5EC9A89E327

Code Installation:

1. Download the most recent release of StudioAbroad from the software distribution site (part of the StudioAbroad Client Support Center). Also download the custom code supplement (SA6_demo.zip).

2. Unpack the code archive and copy the code tree from the contained folder into the website directory designated for StudioAbroad (see Website Config).

3. Unpack the custom code supplement (SA6_demo.zip) into the SA_ROOT. Its contained folders, _themes and components, overlay the existing StudioAbroad code tree.

4. In the components/ini directory, create a host INI file named for your domain: e.g., _university.ini. See instructions and examples below.

5. Create a router INI file for the top node of all valid host names for the site. For example: if www.studyabroad.university.edu and studyabroad.university.edu are active URLs, you would need an INI called _www.ini and another named

_studyabroad.ini.

Within each router INI, the following 2 lines must be added: [Host]

Host=university

6. In the components/scl directory, rename demo.cfc as university.cfc. 7. Configure the host INI. Instructions and sample INI files follow.

Configuring the Host INI file

StudioAbroad can be configured to run one or more data accounts (sites) depending on licensing. The data account connected to the website is identified to the application by the host header of the URL.

The host INI created in step 3 above contains the following sections, which serve several purposes:

Host:

1. Define various parameters of the server/data environment.

2. Set switches pertaining to certain installation/integration features. 3. Store feature settings configured through the user interface. Mappings:

• Base configuration for campus data integration. Address_[n]:

• Extension of Mappings for each address entry in the integration. (Mappings and Address sections are discussed in the Data Integration Manual.)

(5)

StudioAbroad 6 Installation Instructions Page 5 Host = Required. Name of the host, matching the filename (e.g., Host=university

for _university.ini)

DomainHost = Required. Standard is the full DNS host name (e.g.,

studyabroad.university.edu). If the DNS host name is not yet available, any identifier can be used. Whatever is used, the DomainHost string must match the Account_Host field of the account record for the site in tbl_Accounts.

DBMS = Required. [mssql|mysql|oracle]

Datasource = Required. The name of the ColdFusion Data Source configured for the connection to the StudioAbroad database.

Schema = Required. Name of the schema of the StudioAbroad database. Layout = Default is Host value. Until the site layout is developed, a temporary

layout (demo) will be used, and the Layout setting set to demo. Once the layout is in place in a directory named {SA_ROOT}/_themes/[host], the setting can be removed.

DebugEnabled = [0|1] If enabled, all errors are re-thrown (not

caught/handled/logged); only enable this setting in development or during installation/troubleshooting.

AbsoluteMediaRoot = Default is {SA_ROOT}_usermedia/

This is the absolute file system path to the directory that will store all file-based media and data. The _usermedia directory can be named and located as desired, provided that ColdFusion has read-write access on the directory and that the directory can be accessed by URL as {SA_WEBSITE}_usermedia/. See Website Configuration.

Note that on Windows systems, ColdFusion runs as Local System by default, which typically ensures that ColdFusion will have read-write permissions if _usermedia is on a local drive. Unix/Linux systems and cases where _usermedia is located on a network resource generally require some security configuration.

PubHost/AuthHost settings:

StudioAbroad is normally configured on a non-secure, HTTP URL for publicly available areas (PubHost) and a secure, HTTPS URL for the authenticated portions of the system

(AuthHost). There is a series of settings available to allow the two hosts to share or differ. Each of the following has an equivalent AuthHost setting if needed to differentiate,

otherwise the AuthHost setting defaults to its PubHost counterpart.

PubHostProtocol = [http|https] Default is http. (Some campus policies require SSL even for the public site.)

PubHostDomain = Full DNS host name. This may be different from the

DomainHost setting, which is purely a data value identifying the account in the database.

PubHostRelativeRoot = URL path, including leading and trailing slash. Default: / (Currently, there is no support for a different AuthHostRelativeRoot.)

PubHostPort = Default is no explicit port. If a port is supplied, it must be followed by a colon (e.g. 8443:). This is rarely needed, as most production hosts use implicit 80/443 ports for the http and https protocol. Omit this setting if standard ports are used.

The following setting has no AuthHost equivalent:

(6)

Sample router and host INI initial configurations

The following representations of router and host INI files resemble the initial settings needed to enable a StudioAbroad site. More settings will be required as the site is integration with campus data systems (SIS/HR) and may change according to specific needs.

Config. 1: PubHost and AuthHost are mostly identical. The DNS host names for the site are www.studyabroad.university.edu and studyabroad.university.edu.

Router: _www.ini [Host] Host=university Router: _studyabroad.ini [Host] Host=university Host: _university.ini [Host] Host=university DomainHost=studyabroad.university.edu Layout=demo DBMS=mssql Datasource=StudioAbroad Schema=StudioAbroad.dbo AbsoluteMediaRoot=C:\Inetpub\fileroot\_usermedia\ PubHostDomain=www.studyabroad.university.edu NonSecureHostURL=http://www.studyabroad.university.edu/ DebugEnabled=1

Config. 2: PubHost and AuthHost here are dissimilar in many ways, except for the relative root (a required similarity). The DNS host names for the site are

international.university.edu and secure.university.edu and the relative path to the root is /educationabroad/. Among other differences, such as database and OS, the AbsoluteMediaRoot for this installation is located on a directory outside of the the SA_ROOT. Router: _international.ini [Host] Host=university Router: _secure.ini [Host] Host=university Host: _university.ini [Host] Host=university DomainHost=international.university.edu Layout=demo DBMS=mysql Datasource=StudioAbroad Schema=studioabroad AbsoluteMediaRoot=/web/fileroot/studioabroad/_usermedia/ PubHostDomain=international.university.edu

(7)

AuthHostRelativeRoot=/educationabroad/

NonSecureHostURL=http://www.studyabroad.university.edu/educati onabroad/

DebugEnabled=1

Note that AuthHostRelativeRoot will inherit from PubHostRelativeRoot, but we include it here explicitly to emphasize the requirement that they be the same.

At the point when all of the above steps have been taken, the site should be

accessible by web browser.

Post-installation Configuration Steps

The following actions can be performed by the administrative end-users (initial staff1 login) but may require the advice of institutional IT administrators for the scheduling of nightly tasks that may need to be timed to coordinate with other nightly jobs.

1. Access the Maintenance and Installation area:

a. Log in to your StudioAbroad website as a user with full System Settings access.

b. Edit the address line (URL) as follows:

https://[yoursite]/index.cfm?FuseAction=Maintenance

c. You may see a menu with options to add the Maintenance & Installation role to one or more of your Staff users. CAUTION! Assigning the Maintenance & Installation role grants access to student SIS information, data manipulation functions and site configuration. The list of users with this level of access should be reviewed before the system goes into live production.

2. Checkpoints: File/Folder I/O Check: This routine must be run to create the required subdirectories

3. Checkpoints: Task Scheduler Setup

For systems with multiple application servers, the Task Scheduler should only be used on ONE of servers in the group. That requires accessing the Task Scheduler on the specific host URL of the machine. When this is not possible, an external job scheduler may be needed. See the note about the IP Restriction List:

a. Under Current Tasks, you will see any scheduled tasks that exist on the current host, including any configured for other applications on the same ColdFusion server. Most StudioAbroad tasks can be Pinged to check availability, Edited to change scheduling/naming or Deleted.

b. The Missing Tasks area attempts to report on tasks that have yet to be enabled on the host, and provides a default schedule for automatic task creation. Tasks can be added and then their schedules edited. The Missing Tasks list is based on a new naming convention of st_TaskName_host. Required: Ensure that ALL tasks under the Missing Tasks area are created, and edit them to configure their schedules.

c. Required step: IP Restriction List:

The PRIVATE IP address of the server must be entered in the IP Restriction List or the tasks will not execute. This setting also allows execution of the tasks by their URL if the IP of the calling machine is other than the server IP address. (Example: a cron job on the database server.)

4. MaintenanceAccessIP: (a manual setting in the Host INI) By default, the

Maintenance & Installation area is accessible to a Terra Dotta IP address, which is useful for support purposes. To disable or change this IP address, simply add a

(8)

blank setting to the host INI file (MaintenanceAccessIP={blank or other IP}). Note: Maintenance is accessible to authorized users from any IP address. (See step 3.)

Testing:

1. Checkpoints:

a. File/Folder I/O Check: Test to check file read-write access on required directories of _usermedia. Please report any unsuccessful reads/writes to Terra Dotta.

b. Task Scheduler: It is recommended that all tasks be run manually to test or at least Pinged. Tasks produce logs of varying detail. The SISDataRefresh task has a special log viewer with utilities, because of its complexity and importance.

c. Email Tests: (Optional step) Verify that your SMTP server configured in ColdFusion has the ability to mail to and from various e-mail addresses. 2. Audit Logs: Some of these logs will not yet be populated, since they are newly

installed with version 6:

a. Login audit: Provides a detailed trace of the outcome of user login attempts. b. Sent E-mail: A complete log of e-mail messages sent through StudioAbroad.

This is separate from the e-mail history that is accessed through the application, and the log flush does not affect the stored messages in StudioAbroad.

c. Errors: When errors are caught by StudioAbroad’s error handler, they are logged in this area.

d. ColdFusion Logs: If no link appears for ColdFusion Logs, you will have to configure a CFLogPath in the host INI file. This is an optional step, since not all servers will permit access to the log path.

3. Task Logs: These are the HTTP response pages returned by the task URLs. The special SISDataRefresh log and utilities are accessed under Other Utilities. Note that the “flush” mechanism only deletes logs greater than 2 months old.

4. Other Utilities:

a. SIS Refresh: extensive logging and tools for monitoring and managing the data refresh process.

b. SIS Mappings: field mappings for Student Params to SIS; utility has changed little since version 5.

c. SIS/SCL data tests: used to verify the data mappings interfaces to SIS and HR systems.

d. User Merge: Experimental tool for merging the applications of two different user records under one record. Use with caution. Includes logging.

e. Application Scrub: allows removal of individual unwanted application records (e.g., test applications).

f. non-SCL to SCL Conversion: tool for correcting improper student user

creation as non-institutional user. (When a student misidentifies him/herself as external, this utility converts their site access to use campus login

credentials and identifies them as internal.)

g. Edit User: In the event of improper data entry by the student or erroneous SIS data, this tool allows edit of the root user record, which is cannot be modified through the application.

h. Maintenance Users: tool for managing the users who have access to the Maintenance and Installation Utilities.