Connecting Colleague and LYNX History Tables With CNColleagueLYNXLink


The Series25 LYNX Interface uses a database integration to connect to any student information system which is hosted locally on an institution's servers.

The integration has two parts:

  1. A series of custom tables that track historical changes to SIS data
  2. The LYNX-APP, a lightweight Java application that exchanges data between those tables and the hosted Series25 database

This article explains how to install and configure CNColleagueLYNXLink, the connection between these new custom tables, and your existing Colleague UniData environment. You should perform this step after Deploying LYNX History Tables for Colleague UniData.

Once this connection is in place, you are ready to Install the LYNX-APP to bridge the gap to your hosted Series25 environment.

Technical Requirements

  • Windows Server 2012+ (.NET 4.5+)
  • Network connectivity to Colleague environment
  • Network connectivity to SQL Server database
    • SQL database 2012+ required for LYNX schema

Note: if you plan on using a specific user to automate the synchronization of Colleague and 25Live data, you must create it before the installation date. See "Automate the Synchronization Process" below.

Gather information from the Colleague environment:

You will need to know the following information based on the Colleague environment you are connecting to. All these values are based on your main application listener.

  • Environment name (application listener value which should end in "_rt")
  • Hostname address
  • Host port
  • Connection Pool Size
  • Shared Secret (this is specific to the application listener)

Installation Steps

  1. Find the LYNX-Colleague-Unidata.zip folder you downloaded earlier.
  2. Copy the folder \CNColleagueLYNXLink\ to the recommended locations on the integration application server:
    • C:\CollegeNET\CNColleagueLYNXLink-Prod\
    • C:\CollegeNET\CNColleagueLYNXLink-Test\
      (If you do not use the recommended locations above, please note that the new location will need to be updated in step 6 of "Automate the Synchronization Process" below, or the integration will not be able to sync data changes automatically.)
  3. Copy the folder \CNColleagueLYNXLink\ to the desired location on the integration application server.
  4. Run ~\CNColleagueLYNXLink\CollSDKParamsEditor.exe to create a configuration stub file to connect to Colleague. (Make sure to run as Admin.) You will need to enter the information collected from your Colleague application listener in the previous step.
    • Environment
    • Host-Address
    • Host Port
    • Connection Pool Size
    • Shared Secret
    • Confirm Shared Secret
  5. Click "File > Save As..." and select where to save the file after giving it a recognizable name. (Save the file as XML type as that is the format of the content)
  6. Open the file saved from the previous step.
  7. Copy the needed configuration lines <ColleagueSettings> from the XML file into the CNColleagueLYNXLink.exe.config file, replacing the <ColleagueSettings> block of XML.

Configuration Steps

  1. Fill out CNConnectorConfiguration sections within ~\CNColleagueLYNXLink\CNColleagueLynxLink.exe.config
    • Institution (required)
    • Logging (required)
    • Colleague (required)
  2. Alternatively, this process can be done via a command line argument (-c or --config). See CNColleagueLYNXLink Command Line Arguments for further details.
  3. Confirm the character used as a delimiter in Colleague between Building and Room code information. This is set as a space (" ") character by default, but should be changed if a different character is used. 
    • This setting is stored as Location "buildingDelimiter" on line 35 of .\CNColleagueLYNXLink.exe.config

The full list of fields in this configuration file can be found at CNColleagueLYNXLink Configuration Settings. It is not necessary to configure any but the ones marked as required above.


Testing

Perform tests to ensure that data flows properly from Colleague Unidata to the SQL database.  This involves running a quality check sql script, and several commands from the command line (which can be found here: https://knowledge25.knowledgeowl.com/help/cncolleaguelynxlink-command-line-arguments).

 1.  From a MSSQL query window on the LYNX database run the e_uni_sis_mssql_data_qc.sql script as the LYNX user on the SQL database to get a baseline of the rowcounts for each table. 

2.  From the command line, navigate to the installation directory of the LYNX Unidata App, and run `CNColleagueLYNXLink.exe reference` and let the process complete. 

3.  Run the e_uni_sis_mssql_data_qc.sql script again and there should now be a greater number of rows for the reference data tables. 

4.  From the command line run `CNColleagueLYNXLink -t=<Term Code>` and replace `<Term Code>` with a term with valid data, and let the process complete.  Warning: the value for term code IS case sensitive.

 5.  Run the e_uni_sis_mssql_data_qc.sql script again and there should now be a greater number of rows for the term-based data tables.

Automate the Synchronization Process

In order to keep Colleague and 25Live in sync, CNColleagueLYNXLink.exe must run on a regular schedule. The recommended run interval is every 5 or 10 minutes. We recommend using a Windows Scheduled Task, unless your institution has another preference.

If your institution requires a specific user to run the scheduled task, please create this user before the installation date. Only a local user is required, but you can use a domain user if desired. 

If you decide to use the Windows Task Scheduler, follow these steps to import from the TEST or PROD task template.

  1. Launch Task Scheduler.
  2. Click "Import Task".
  3. Locate "TEST - Colleague UniData Synchronization with LYNX.xml" within .\CNColleagueLYNXLink\ folder.
  4. Click "Open" button.
  5. By default, the task will be run as the "SYSTEM" user account. If you do not want the task run as the "SYSTEM" user, click "Change user or Group..." button.
    • Update to user with administrative privileges for the machine.
    • Click "OK" button to save changes.
    • Ensure the radio icon "Run whether user is logged on or not" is still selected.
    • If a user other than "SYSTEM" is configured, ensure the box next to "Do not store password. The task will only have access to local computer resources." is checked.
  6. Review the configuration option of the CNCollleagueLYNXLink.exe install location.
    • Click on "Actions" tab.
    • Double click the "Details" path value to edit.
    • Update the path depending based on where the executable is installed.
    • Click "OK" button to close the "Edit Action" window.
  7. Click "OK" button to save changes.
  8. Repeat steps 2 - 7 with "PROD - Colleague UniData Synchronization with LYNX.xml" if installing both on the same application server.