Skip to main content

CITI Interface Integration Guide

Emily Yeomans

Please note: A PDF version of this guide is available for download at the bottom of the article.

 

This document is intended to help guide the configuration and troubleshoot the CITI Training Interface with iRIS.

 

  1. The CITI Training URLs are provided to our Clients by CITI, this transaction is conducted between the client and CITI, any fees involved are also between our client and CITI – the CITI Training URL is not part of the CITI Interface that a client purchases from iMedRIS.

 

  1. Typically a client receives two URLs from CITI that look like this:

 

1a.        Use the following link to download a Comma-delimited (*.csv) file that lists all completion reports earned by z _ iMedRIS users:

https://www.citiprogram.org/members/institutionaladministrators/transcriptdownload.asp?data=downloadall&ID=BE56F0DB-53A1-4DD9-B93F-D8ADA6FB6C19&category=0

 

2a.        Use the following link to download a Comma-delimited (*.csv) file that lists completion reports earned by z _ iMedRIS users since the last time the data was downloaded on 1/1/2000:

https://www.citiprogram.org/members/institutionaladministrators/transcriptdownload.asp?data=lastdownload&ID=BE56F0DB-53A1-4DD9-B93F-D8ADA6FB6C19&category=0

 

The first URL should contain the string data=downloadall – this means that this is the URL that will provide iRIS with a Report.csv file that will contain all of the CITI Training records for the specific client (campus) NOTE: This many not be all of the records for the institution.

 

The second URL should contain the string data=lastdownload – this URL will only download the records that CITI has modified since the last time that the URL with the string data=downloadall was accessed. NOTE: The maintenance of the URLs, records, dates, updates to user’s email address, and course information is all maintained by CITI, iMedRIS is not responsible for the content of the information contained in the Report.csv file.

 

The format of the Report.csv file should be as follow:

  1. The URLs must direct the user to Save or Open a *.csv file, the interface does not currently support a *.xls file, please verify that the URLs provided to the client by CITI direct to a *.csv file (typically it is Report.csv)
  2. The order of the columns of the *.csv file must be:
Last Name First Name Email Group Curriculum Stage Number Stage Date Completed Expiration Date

Currently the CITI Interface requires that the values for the Date Completed and Expiration Date columns to have dates in the following format:

MM/DD/YYYY – NOTE: Currently all columns must also have a value – meaning no NULL (empty) values

 

  • The final phrase of each URL is typically category=0, this means that the URL will retrieve all records regardless of category, CITI can refine the results returned by a modification to the category value, for example:

 

  • Data can be downloaded for gradebooks in a specific research category by including the appropriate category ID number in the url.  The research categories are:
  • Animal Research (use "&category=2" in the url)
  • Biosafety/Biosecurity (use "&category=4" in the url)
  • Export Control (use "&category=6" in the url)
  • Human Research (use "&category=1" in the url)
  • Radiation Safety (use "&category=5" in the url)
  • Responsible Conduct of Research (use "&category=3" in the url)
  • To download data for multiple research categories separate the category numbers with a comma, "category=1,3,4". To download data for all categories use "category=0" or "category=".
  • Please request our client to contact CITI if they would like to refine the results returned by the CITI URLs.

 

Configuration of CITI in iRIS – from the User Interface:

 

  1. The configuration of CITI is done via the System Configuration link under the System Administration tab in iRIS, currently the path to the necessary fields is:

System Adminitration -> System Configuration -> Reserved Settings:

 

Once the user has authenticated their password to make the Reserved Settings page editable these are the System Propreties necessary to configure the CITI Interface in iRIS:

system.citi_csv_report_url = this is where the URL with the string data=downloadall needs to be placed

system.citi_csv_report_url_Sec = this is where the URL with the string data=lastdownload needs to be placed

system.use_citi_training = This property needs to be set to ‘Yes’

 

Once the system property system.use_citi_training is set to yes the following functionality will be enabled in iRIS:

  1. Via the following path:

System Administration ->List Configuration and Maintenance ->Clean Up Tab

On this screen there should now be a link labeled: “Merge matchless CITI training records” – this link is used to match CITI training records that do not match user email accounts in iRIS.

  1. Via the following path:

System Administration ->User Accounts->Click on the name link of any User Account

 

  1. On the user account screen there should be an Additional Email Addresses area of the user account screen with buttons labeled “Add” and “Remove” this functionality is to allow iRIS multiple email accounts per user account to match with the email accounts lists in the Report.csv that is downloaded via the CITI URLs. The additional email accounts entered on this screen are saved in the database table SYSTEM_USER_ADDL_EMAIL; if there are any issues with use of the Additional Email Addresses feature of a user account please verify that the table SYSTEM_USER_ADDL_EMAIL exists.

 

 

Configuration of CITI in iRIS – from the Application Server:

 

  1. The following configuration settings are necessary for iRIS 9.03+ Application Servers. The property configuration and settings of the keyStore and trustStore properties paths may be described in other iMedRIS documentation as well; however it is critical for the CITI Interface to function that these property settings be correct in the SA.Properties file on the iRIS Application server.

 

This is an example of a typical trustStore property setting:

system.trustStore_1=/iMedRIS/jdk1.7.0_17/jre/lib/security/cacerts

system.trustStorePassword_1=changeit

The path of the cacerts file must be defined for each application server, meaning that settings provided in this document are an example. The cacerts file should be located in the similar path on each iRIS application server …\iMedRIS\jdk…\jre\lib\security. The password is usually “changeit.”

The keyStore property setting must also be set, if the server is not SSL certified, meaning the that the URL to get to the iRIS login page does not contain “https:” then the same property setting can be used for the keyStore setting.

However if the iRIS Application server does have an SSL Certificate it is then necessary to generate iRIS a keyStore file that it can use to authenticate with other SSL Certified websites. The Instructions to extract the keyStore are documented at the end of this document.

 

  1. Once the trustStore and keyStore property settings are configured, and the CITI Interface property settings within iRIS, as well as the CITI URLs have been entered the iRIS Service will need a restart in order for the changes to take effect.

 

  1. The iMedRIS CITI Interface will utilize the URL provided in the system.citi_csv_report_url iRIS system property during the nightly thread run to update the CITI_TRAINING_IMPORT table. The URL provided in the system.citi_csv_report_url_Sec system property is used every 6 hours by iRIS update the CITI_TRAINING_IMPORT table based on CITI’s update to the report.csv file that the URL in the system.citi_csv_report_url_Sec iRIS system property is using.

 

  1. *NOTE:

There is an additional system property system.citi_merge_course_stage when this property is set = Yes then the system in concantinate the Group and Course names when matching training records with user accounts. This may be deserved behavior for a client that desires to track course information with each group. This functionality was based on a paid enhancement.

 

 

 

 

 

 

 

 

 

Steps to get Key Store File from certificate.

 

  1. Open IIS Manager, Select Local Name for the system

 

  1. Right Click Select Properties

 

  1. Select Directory Security Tab.

 

  1. Click On View Certificate.

 

  1. Click  Copy to File. Follow Next🡪 Button

 

  1. Type in Keystore password

  1. Save the KeyStore file in <imedris-root>\security folder

 

  1.  Click on Finish.

 

Convert pfx file to Java Keystore file

 

  1. Download the lastest version of Jetty, which is currently 6.1. This zip file can be downloaded  here.

Or,  Get latest version from SourceSafe.$ Documentation/Development./ jetty-6.1.1.zip

 

  1. Extract this file into a folder.
  2. In a command prompt, go to the extracted Jetty directory and execute the following command to verify that the files are okay and that your Java environment variables are setup properly:
  3. To verify that Java Environment Variables are set, Type in java in command prompt.

If 'java' is not recognized as an internal or external command, operable program or batch file. error occurs, Please set PATH Variable.

 

Set Path variable using command : set PATH=PATH;<JAVA_HOME_>/bin

Example: set PATH=PATH;c:/iMedRIS/jdk1.6.0_03/bin

 

  1. Now run this command

                java -classpath lib/jetty-6.1.1.jar org.mortbay.jetty.security.PKCS12Import <pkcs_file_path> <new_jks_file_path>

        Eg: java -classpath lib/jetty-6.1.1.jar org.mortbay.jetty.security.PKCS12Import c:/iMedRIS/security/www.imedris.net.pfx c:/iMedRIS/security/www.imedris.net.jks

 

  1. Type in input and output keysore passphrase. (Please remember this passphrase, same will be used in System Properties for Keystore password in Grants.gov Category.)

 

Reference: http://www.entrust.net/knowledge-base/technote.cfm?tn=7925

 

 

  1. Click On Save After Edit.

 

  1. Restart IRIS Service.

 

 

 

 

 

 

 

Related articles