Overview of Request Import Interface In this document:
Overview of Request Import Interface
JDBC Driver For Request Import Interface
Authentication for Request Import Interface
Configuring Request Import Interface
Overview of Request Import Interface [Note: References to CAS (Course Applicability System) are to u.select's former name (now Transferology). IMS was the vendor that supplied the Request Import software. Wherever possible these references have been updated to the new names, but in some cases they have been left to avoid making changes to the program's code.]
| Task | Min Hours | Max Hours | Skillsets Needed | Software |
| Install and configure CASRI software | 1 | 3 | Web Programmer | Tomcat or other Java servlet container |
| Build authentication page | 8 | 24 | Web Programmer | Provided by your portal software????? |
| Create a DB user | 1 | 2 | Database Administrator | JDBC driver |
| Create a DB view of academic history | 2 | 3 | Database Administrator | JDBC driver |
| Install an SSL certificate | 2 | 3 | Security Manager | Certificate from your chosen vendor |
| System testing | 4 | 6 | Transfer Articulation Specialist | |
| Hour Totals | 18 | 41 | ||
JDBC Driver The CASRI application utilizes JDBC technology for accessing tabular data from the SIS. The cross-DBMS capability that JDBC provides allows for efficient development and support for the application, but requires the institution to obtain and place the driver in the servlet container. The JDBC driver is usually supplied as a .jar file as part of your original database distribution package. It can also be obtained from your database vendor, or by searching online.
The driver is then placed in the servlet container as a .jar. The directory may be different depending on which server you are using, but we have provided an example for a Tomcat – Oracle configuration:
…[tomcat root]\common\lib\classes12.jar
By putting the .jar in the common directory, the JDBC driver will be available to all applications that require it.
[Note: References to CAS (Course Applicability System) are to u.select’s former name. IMS was the vendor that supplied the Request Import software. Wherever possible these references have been updated to the new names, but in some cases they have been left to avoid making changes to the program’s code.]
Overview
Your authentication page will have to accept an incoming query string from uselect and store it for later use. It should then display a typical login page with text boxes for the student to enter their user id and password. When the student clicks the submit button the processing should query your student information system with the user id and password with the student id as the field returned for a valid login. This student id is then appended to the original query string with a separator and keyword (“&stuid=123456789”) and this is forwarded on to the CASRI server.
Details
When your student starts a Request Import in u.select, your portal/authentication server will receive a string from the u.select server that will look similar to this:
https://ucadm.IllinoisSchool.edu/prod/acadmichistory.main?key=2003102718134030&uid=admin@CASRI&return=http://www.transfer.org/cas/receiver.jsp
https://ucadm.IllinoisSchool.edu/prod/acadmichistory.main is the institution’s authentication page URL.
?key=2003102718134030 is a u.select supplied key. This is a unique identifier of the transaction request from u.select, and is used to match the reply with the request when the academic history is returned to the u.select server.
&uid=admin@CASRI is the u.select user that has requested authentication. This is a student created anonymous ID.
&return=http://www.transfer.org/cas/receiver.jsp is the u.select supplied return URL. This is the web address for the requesting u.select server. It ensures that requests are only returned to the requestor, and to an authorized u.select instance (designated by the domain transfer.org)
After the institution has authenticated the student, the stuid will be appended to the string and the institution will POST this to the RI server at the institution behind the institution firewall. The POST string should look similar to this:
http://APPSERVER:Port/CASRI/requestImport.do?key=2003102718134030&uid=admin@CASRI&return=http://www.transfer.org/cas/receiver.jsp&stuid=123456789
http://APPSERVER:Port/CASRI/requestImport.do is the application server URL where the CASRI application is deployed.
&stuid=123456789 is the user’s stuid that the institution will append to the POST URL string.
Once CASRI receives the POST it will then verify the string for the key, uid, return url and the stuid. If any of these items are missing the CASRI displays an exception error. CASRI will then use the stuid to request the student’s academic history from the institution’s student information system (SIS) server. The information returned is translated into an XML document, encapsulated in an HTTP post, and sent back to the u.select server.
NOTE: Sample authentication pages are available in the distribution packet.
Database View The view name must be “vw_cas_ims_enrollments”.
Field Descriptor Definition
| stuID | student’s SIS ID |
| term | YYYYMM MM = beginning month 01 W, 03 Sp, 05 Su, 08 Fa |
| oldTerm | term from SIS without decode |
| dept | size based on host institution (i.e. MATH, CHEM) |
| crse_numb | course number, size based on host institution |
| credithours | xx.xx, decimal point in position 3 |
| grade | size based on host institution |
| crsetitle | size based on host institution |
| repeat | has the course been repeated |
Sample Code (Banner in this case)
create or replace view vw_cas_ims_enrollments as
select shrtckg_term_code as oldterm,
substr(shrtckn_term_code, 1,4)||decode(substr(shrtckn_term_code,5,2), '10', '08', '20', '01', '30', '05', '40', '07', '31', '06', '41', '07') as term,
shrtckn_subj_code as dept,
shrtckn_crse_numb as crse_numb,
shrtckg_credit_hours as credithours,
decode(shrtckg_grde_code_final,null,'n/a',shrtckg_grde_code_final) as grade,
shrtckn_crse_title as crsetitle,
shrtckn_repeat_sys_ind as repeatcd,
shrtckg_pidm as stuid
from shrtckg, shrtckn
where shrtckg_pidm = shrtckn_pidm
and shrtckg_term_code = shrtckn_term_code
and shrtckg_tckn_seq_no = shrtckn_seq_no
Sample Code to Create Database User (if needed)
drop user CAS_User;
create user CAS_User
identified by CAS_User
default tablespace CAS_User
temporary tablespace temp;
GRANT CONNECT, RESOURCE TO CAS_User;
grant select on system.VW_CAS_IMS_ENROLLMENTS;
commit;
Sample Code to Create Authentication View (if needed, Banner in this case)
create or replace view vw_cas_ims_authenticate as
select spriden_pidm as stuid,
spriden_first_name as firstname,
spriden_last_name as lastname,
gobtpac_pin as password,
gobtpac_external_user as userid
from spriden, gobtpac
where spriden_pidm = gobtpac_pidm
Configuring Request Import Interface The Request Import Interface files are distributed as a zip file. The files should be unzipped with directory names so the entire file structure is preserved. The top directory should be “casri”. This top level directory is then copied to the webapps directory at [Tomcat root]\webapps. The casri directory should be backed up anytime a configuration change is made. (This same process is used with the testing app IMS_Verify.)
Several local directories need to be created to store the XML requests and acknowledgements. The directory location can be anything desired, but will need to be configured in the CASRI.properties to allow the application to find the files.
Create the following directories:
AckDir=C:\uselect\Acknowledgements
ArchiveDeferredDir=C:\uselect\Archive \Deferred
ArchiveDirRequests=C:\uselect\Archive\Requests
DeferredDir=C:\uselect\Deferred
OutputDir=C:\uselect\Requests
Log file directory: C:\uselect\Log
File: CASRI.properties
Location: …[Tomcat root]\webapps\CASRI\WEB-INF\classes\resources\
[Special Note: Perhaps because the CASRI app was originally created and installed in two pieces these configuration lines must be exactly repeated in the application.properties file. Also, see below for additional instructions applying only to the application.properties file.]
File contents:
#<!-- uselect Configuration Parameters-->
# <!-- uselect Institution Unique Parameters -->
AckURL=
InstIDQ=73
InstID=111111 – Put your school’s FICE code here
# <!-- uselect XML Persistent Storage -->
--Note: These directory lines must use double slashes and end with double slashes.
--Note: Must be modified to match the directories created above.
AckDir=C://uselect//Acknowledgements//
ArchiveDeferredDir=C://uselect//Archive//Deferred//
ArchiveDirRequests=C://uselect//Archive//Requests//
DeferredDir=C://uselect//Deferred//
OutputDir=C://uselect//Requests//
# <!-- Page Accesibility Resources -->
Authenticate=disabled
Deferred=disabled
RemoteHostAddr= IP of the authenticating server
SecureOnly=disabled
Debug=enabled
File: repository_database.xml
Location: \casri\WEB-INF\classes\ repository_database.xml
File Contents:
<jdbc-connection-descriptor
jcd-alias=""
default-connection="true"
platform="Oracle" - - Must be modified
jdbc-level="2.0"
driver="oracle.jdbc.driver.OracleDriver" - - Must be modified
protocol="jdbc"
subprotocol="oracle:thin" - - Must be modified
dbalias="@66.14.138.81:1521:cas" - - Must be modified
username="uselect_user" - - Must be modified
password="sample" - - Must be modified
batch-mode="false"
>
<connection-pool maxActive="21" validationQuery="" />
<sequence-manager="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
<attribute attribute-name="grabSize" attribute-value="1"/>
</sequence-manager>
</jdbc-connection-descriptor>
The JDBC connector descriptor must be modified to reflect your current platform, driver string, subprotocol, dbalias (address), and DB authentication.
File: application.properties
Location: …[Tomcat root]\webapps\CASRI\WEB-INF\classes\resources\
There are several message lines with school specific text that need to be customized for your institution. Search for the phrase “Your school” to find the places.
Startup and Shutdown
The U.select Request Import Interface is started and shutdown as part of its Tomcat container. Tomcat provides batch files for this process at:
C:\Program Files\jakarta-tomcat-5.0.28\bin\shutdown.bat
C:\Program Files\jakarta-tomcat-5.0.28\bin\startup.bat
References to the startup file should be placed in either the registry run key at
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
Or in the Startup menu group.
School Customization
See also instructions above for the application.properties file.
Logo – Find a jpg image of your school’s logo that is approximately 180 x 500 pixels in size and rename it to school_logo.jpg. Copy the file to C:\Program Files\jakarta-tomcat-5.0.28\webapps\casri\images.
Debugging Aids
When testing the RI interface through uselect it is necessary to delete all old imported courses and import requests in uselect. Uselect will not overwrite old courses and does not automatically delete completed import requests.
The RI interface uses log4j logging that is configured in the file:
[Tomcat root]\webapps\casri\WEB-INF\classes\log4j.properties
This file has been preconfigured to write a log file at the location shown in the CASRI.properties file. Extensive information is available on the web about the details of log4j logging. The RI interface has been tested with Apache log4j-1.2.9.jar. Refer to http://logging.apache.org to download the latest version of log4j. Once you have the latest version downloaded, refer to the log4j manual at http://logging.apache.org for installation instructions.
XML files showing both the incoming and outgoing transmissions for the interface are recorded at the locations shown in the CASRI.properties file. See also Transmission Document Sample for a sample of what the file should look like.
Intermediate Database Option (not required)
Some schools have chosen to use an intermediate database instead of connecting directly to their SIS database. This provides an extra layer of isolation for the SIS database and can also simplify the query from casri (helpful when the SIS database is UniData). You will need to build a batch process to move the necessary data to the intermediate server on a regular basis. See the file Server Diagram, Intermediate DB Option.jpg.
Database Connectivity Testing Overview
NOTE: Many schools tested the connection by other means and this program may be more trouble than it is worth!
Testing database connectivity can be done with a small program called IMSVerify. It is a validation tool that ensures that all functionalities and systems are in place and returning the expected results. IMSVerify is a Java application that performs several verifications, including:
IMSVerify.zip should be unziped and deployed in your servlet container. For Tomcat IMSVerify should be copied to:
…[tomcat root]\webapps
Running the Application
With the IMSVerify deployed, the application can be called from most browsers to initiate the validation process:
http://localhost:8888/ims_verify/ (The port number can vary depending on how you setup your servlet, Tomcat in this case.
Upon selecting the “submit query” button on the Query Input form the application will direct the browser to a Database Results page. The Database Results page displays the selected academic history records in a table for verification.
Screenshot of the IMSVerify application:
File Locations| Group | Description | Comment |
| Application | config pointer | [Tomcat root]\webapps\casri\WEB-INF\classes\resources\config.xml |
| Application | Images | [Tomcat root]\webapps\casri\images |
| Application | logging config | [Tomcat root]\webapps\casri\WEB-INF\classes\log4j.properties |
| Application | messages | [Tomcat root]\webapps\casri\WEB-INF\classes\resources\application.properties |
| Application | parameters | [Tomcat root]\webapps\casri\WEB-INF\classes\resources\CASRI.properties |
| Backup | this directory & subdirs | [Tomcat root]\webapps\casri |
| Database | connectivity | [Tomcat root]\webapps\casri\WEB-INF\classes\repository_database.xml |
| Database | driver location | [Tomcat root]\common\lib |
| Database | fields defined | [Tomcat root]\webapps\casri\WEB-INF\classes\repository.xml |
| Image Reference | background.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\defaultLayout.jsp |
| Image Reference | background.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\loggedInVerify.jsp |
| Image Reference | background.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\LogOnMenu.jsp |
| Image Reference | footer_with_space.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\copyright.jsp |
| Image Reference | request_import_title.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\header.jsp |
| Image Reference | school_logo.jpg | [Tomcat root]\webapps\casri\WEB-INF\JSP\tiles\copyright.jsp |
| Tomcat | documentation | [Tomcat root]\webapps\tomcat-docs |
| Tomcat | port | [Tomcat root]\conf\server.xml |
| Tomcat | Shutdown file | [Tomcat root]\bin\shutdown.bat |
| Tomcat | Startup file | [Tomcat root]\bin\startup.bat |
| Tomcat | users config | [Tomcat root]\conf\tomcat-users.xml |
| u.select Production Server | 74.126.83.21 | http://www.transfer.org/ |
| u.select Test Server | 74.126.83.25 | http://test.transfer.org |
User Added Notes/Suggestions