Overview

The purpose of this document is to provide an overview of the implementation and deployment considerations and process for the AcademyOne Academic History Web Service.

Description

The Academic History Web Service handles AcademicCalendar, AcademicHistory, Ping, and service Statistics Query-Request messages.  This service will be deployed at academic institutions participating in Web-based transfer and articulation services and will be invoked by applications like AcademyOne's Student Passport to import student academic histories and monitor the remotely deployed service and report on its status.  For more details on the definition and content of these objects and messages, see the Academic History Web Service Definition (WSDL) and Academic History Web Service OpenEAI analysis template.

This service utilizes open source Enterprise Application Integration (EAI) and Service-oriented Architecture (SOA) infrastructure from the OpenEAI and Apache projects to make the service and its deployment open and transparent.  Many institutions deploying this service will either not have EAI or SOA infrastructure or the people deploying the service may not be familiar with their existing infrastructure.  In order to ensure the quickest possible deployment, the service is packaged within a lightweight Apache Axis2 deployment that includes all infrastructure required to deploy, configure, and start the service in one easy deployment process without highly specialized assistance.   

Users of course articulation and transfer services like AcademyOne will want to import their academic history from institutions they attended into these applications.  They will select the option to import, specify the institution, and provide their appropriate username and password for that institution.  The course articulation and transfer application will then invoke the Academic History Web Service at the target institution to authenticate the user and retrieve the user's academic history.  This request is an AcademicHistory.Query-Request made via web service protocols. 

Course articulation and transfer applications will likely also want to monitor the availbility of the service to inform their users about the availability of the service.  Deploying institutions will potentially also want to monitor the status of these services in order to support their users and assist with managing and troubleshooting any remotely deployed services.  This monitoring can be performed with any standard monitoring framework by making Ping and service Statistics requests of the web service.

Pre-deployment Steps

1.       Identify technical support contacts and practices

The deploying institution and the consuming service provider should identify primary and, if possible, secondary Subject Matter Experts (SMEs) and contacts for the following:

• Student information system (Banner, Datatel, home grown, etc.)
• Database management system
• Server administration or support staff who will deploy the web service

2.       Determine which authentication method the service will use to authenticate users

The Academic History Web Service may authenticate the consuming service provider using certificate authentication features of the web services framework in which it is running.  It then handles the query request by authenticating the user with a configurable authenticator and, if the user is authentic, building the academic history with a configurable academic history provider. 

The request for an academic history will contain a username and password for the user. The deploying institution must decide how it will take this information and authenticate the user.  For example, many institutions have an enterprise directory such as an LDAP server or Microsoft Active Directory that can be used to authenticate the user with a username and password.  Other institutions can authenticate users directly against their student information system such as Banner or Datatel.

We must establish which authentication method is available at the institution deploying the service, so we know which authentication method to configure.  It is also possible that an authenticator does not exist for the method available at the institution.  In that case, someone must develop the appropriate authenticator.

The following authenticators are planned to be developed as part of the initial implementations:

• LDAP bind
• Microsoft Active Directory bind
• Banner login
• Datatel login
• Java Database Connectivity (JDBC) connection operation

Other authenticators can be developed as needed.  It would be optimal if authenticators could be contribued back to the project, so subsequent deployers with that authentication method can benefit.

3.       Determine which system will provide the academic history and academic calendar

In addition to the configurable authenticator, the web service also uses configurable providers for the academic history and acedmic calendar. Like the authenticator, the deploying site must select and configure existing academic history and academic calendar providers or someone must develop new providers for their system if none exist.  The academic history provider is the component that knows how to get the academic history from the appropriate student information system.  The academic calendar is the component that knows how to get teh academic canedar from the appropriate student informaiton system.  The following academic history providers and academic calendar providers are planned in the initial deployments:

• Banner
• Datatel
• General Relational Database Management System

The Banner and Datatel academic history providers will know precisely how to retrieve academic histories from these systems. The general relational database management system providers will be configured with an SQL query to retrieve an academic history or academic calendar from any system to which access to the underlying database is possible with a SQL query.

4.       Prepare an environment in which the service can run

The Academic History Web Service is a Java web service.  It can run within an existing web service framework operated by the deploying site or the site can deploy a lightweight web service container like Apache Axis2 in which to run the web service.  The prerequisites for deployment are:

• an operating system that can run Java 5 or Java 6, so most commonly site use Windows 2003, Windows 2008, Linux, Solaris, or just about any other current Windows or Unix-like system
• a current release of Java 5 or 6.  We suggest you deploy with Java 5 (JDK), but Java 6 should work as well.  We just do not test as regularly with Java 6 at this point

Best practices recommend that sites maintain at least one test and production environment for every application, so one may test upgrades and patches.  This is also helpful for the Academic History Web Service, so we suggest establishing at least two deployments from the start.  This is also helpful if the site will be doing their own deployment on custom provider components of the service.

Deployment Steps

1.       Deploy the web service package

Unpack the web service package archive and run the appropriate setup script for Linux, UNIX, or Windows.  Follow several detailed deployment instructions to configure the appropriate authenticator and academic history provider components identified in the pre-deployment steps.  Start the web service.

Note that the web service may also be deployed in existing integration infrastructure at the institution if desired. That process will be different depending on the institution, but general instructions will be provided.  In most cases, institutions do not already have Enterprise Service Bus (ESB), EAI, and SOA infrastructure in which to deploy and mange this service, so the service comes packaged in a lightweight deployment of the Apache ServiceMix ESB.

2.       Run local tests

Follow the detailed instructions to execute the testing applications included in the web service package.  These tests allow the institution to bypass user authentication and verify that academic histories are being properly retrieved.

3.       Run tests with AcademyOne

Create an appropriate test user with which AcademyOne can test invoking the web service.  Contact AcademyOne and perform testing.

Post-deployment Steps

1.       Register the web service in monitoring infrastructure

Both AcademyOne and the deploying institution will likely have monitoring tools and infrastructure to invoke the service's test features on a scheduled interval and report on the status and statistics of the service.  This monitoring should be setup and parties should decide and document to whom alerts should be sent when the service is unavailable.

2.       Document technical support contacts and practices

The deploying institution and AcademyOne should document their understanding of who primary and secondary contacts are for the service and how and when the service will be fixed when it is unavailable.