SIS Integration Troubleshooting Guide

Overview

There are different situations where troubleshooting the SIS integration with Student Success & Engagement is required, such as:

• The SIS data does not display in SS&E as expected
• The SIS data appears to be delayed in SS&E
• The SIS data is missing from SS&E
• The SIS data displays in SS&E yet it does not match the data found in the SIS

In all cases, the initial troubleshooting step is to determine the source of the data inconsistency.

• For a visual representation of the Infrastructure Summary and all import process methods click here.
• Something to note is that some data may only display within a certain department app and/or on a certain person type by design. If that's the case, data will be found in the Imported Data View from SIS Integration Datafeeds Administration, yet may be hidden/missing from the UI based on the department app and/or person type being viewed.

There are two methods for implementing Student Success & Engagement data imports. These are:

1. Method 1 uses CSV files, exported via Informer or another export method.
2. Method 2 is a direct database connection using SQL Database Views.

• Institutions using Informer Reports and the Drill service to extract data from the SIS are responsible for the data in the CSV Files.
• Institutions using SQL views to extract data from the SIS are responsible for the data in the SIS Database Views and must provide the SQL queries for additional assistance.
  • If assistance is needed from SS&E Professional Services, either by utilizing a support plan or a paid engagement, institutions must provide the SQL contained within the view for any views that seem to be exporting incorrect data. This will ensure that SS&E Staff are looking at the most recent version of the SQL making up the view.

If you are not sure which method is being used, this can be viewed within SS&E Administration, from SIS Integration -> Accelerate Configuration. Searching for <ConnectionString> will show how the SS&E source data is being extracted from the SIS system:

• jdbc:drill:drillbit - represents CSV files via Informer reports and Drill service
• jdbc:sqlserver - represents DB Views via SQL Queries run directly on the SIS database

For example, the following diagram visualizes how the SIS data integrates with SS&E utilizing Connect:

In general, there are four areas where data inconsistency is most likely to initiate:

• The SIS -  The SIS is the source of the imported data.
• The Data Extract - During implementation, data extract definitions are created and are often documented in a Data Workbook. The data extract definitions define how and what data is being pulled from the SIS in order to be imported into SS&E. This includes database queries, Informer reports, and/or CSV outputs. 
• The Data Transfer - Once data is extracted from the SIS, the data is sent to the cloud (S3 platform) where it is processed and then imported into SS&E via the SIS Import. The data transfer process results in JSON files (data extracts) on S3 that contain the data extract definitions results. The most recent data extract/JSON file used to import SIS data on each data feed can also be downloaded from the "Download Extract" column under SIS Integration Administration - Datafeeds found here.
• The Data Import - During the data import process, the SIS data (.JSON files) are imported from S3 into the SS&E database. As soon as the data is imported into SS&E it is immediately available and visible throughout the Student Success & Engagement application.

The most common reason for data inconsistency is due to unexpected data changes, delays, or missing data in the data extract, or the SIS itself.

Verify that the SIS Data is Missing or Delayed

• Before you begin troubleshooting, we recommend checking again to make sure the data is still missing. Sometimes missing data is delayed and appears within 24 hours. If the data is no longer missing, this means that whatever caused the data delay is resolved. 
• If you wish to determine what caused the delay, use the following steps:
  • 1. Identify which data feed imported the delayed data.
    2. Check External Logging filtering on the data feed to see the Connect Job schedule and import status for the data feed identified in step 1.
    3. Check Batch Processing to see the SIS Import Job schedule. Drill down into the recent import jobs to see the status and read/writes of the data feed identified in step 1.

The following steps demonstrate how to determine whether the data inconsistency stems from the SIS, the Data Extract, the Data Transfer, or the Data Import.

Data Flow

The following diagrams demonstrate the separate systems and the data flow between them:

Troubleshooting Steps

Prerequisites

Before getting started, the following items are required in order to troubleshoot missing/mismatched data in SS&E:

1. Administrator access to Administration.
2. If available, the Data Workbook and/or familiarity with the data extract definitions.
   • The data workbook includes the data extract definitions defined collaboratively during implementation for each individual institution.
   • The data extract definitions define how and what data is being pulled from the SIS in order to be imported into SS&E.
3. Familiarity with how to download and view the most recent data extracts on file.
   • For instructions on how to download/view the most recent data extract JSON files from S3 from SS&E Administration-> SIS Integration -> Datafeeds, click here.

Identify the missing/mismatched data

The following steps will help Identify the data stream that appears to be missing data.

1. To find the relevant data feed(s) that is "missing" data, either refer to your data workbook or the SIS Import Definitions found here.
   • Search by the item name/id that is missing or inconsistent to find the corresponding data feed.
   • For example, if a certain data-backed tag should be assigned in SS&E yet has not been imported, searching by "tag" will find the relevant data streams which are PersonTag and Tag.
2. Check here to see which data streams integrate data deletion with the SIS.
   • If the data feed Imported Data View displays the record in red and "Delete = Yes", then the reason data is missing is most likely because the source system Id is missing from the data feed All Ids feed.
   • SIS Data Deletion Integration will remove records from the UI while they remain in the SS&E database marked with active=false and deleted=true when the source system ID is found in the SS&E database yet missing from the data feed All Ids import file.
   • For example, if the data is missing inconsistently, and the data feed integrates data deletion with the SIS, this usually indicates that the data extract includes data that is not included in the All Ids file. When that is the case, the data imports every time the SIS Data Import Job runs successfully. However, the data is also "deleted" once a day when the SIS Integration "deletion" job runs. The result is that throughout the day the data inconsistently displays on the UI.
   • When data is missing from the UI, always check if the data that is missing imports on a data feed that supports data deletion integration.
   • For more information about SIS data deletion integration and troubleshooting, click here.

Check the Data Extract

WARNING: THE DATA EXTRACT MAY CONTAIN SENSITIVE INFORMATION

Always consult your Information Security policies so that data is properly handled to avoid any security incidents.

1. To download the most recent data extract on-file, from Datafeeds Administration found here:
   
   • Scroll to the data feed and then right-click on "Download Extract" and select "Save link as..." to download the data extract from S3.
   • If the Download Extract column shows N/A, this means that the JSON file is missing from S3. If it is not supposed to be missing, this explains why the data is missing in SS&E.
   • If the data feed integrates data deletion with the SIS, the All Ids file is available to download as well.
2. The data extract will include the most recent SIS data pulled from the SIS.
3. Search the data extract for the missing/mismatched data.
4. If the missing/mismatched data is not included in the data extract:
   1. Is the data feed out of date?
      1. If yes, this means that the data extract in S3 is not "current". Therefore, this can explain why the data extract does not include the SIS data we expect.
         • If the identified data stream is out of date, this must be resolved before continuing to troubleshoot a data inconsistency.
         • For more information about data feed out-of-date troubleshooting, click here.
      2. If no, and the data extract is missing the expected data, the SIS or data extract definitions must be analyzed and fixed to output the correct data. 
         
         • For Accelerate customers, the SIS data extract definitions can be accessed within SS&E, either from the Datafeeds Extract Queries column or from SS&E Administration -> SIS Integration -> Accelerate Configuration, found here.
         • To check if your institution is using Accelerate, browse to Administration - SIS Integration and verify that "Accelerate Configuration" is listed.
         • If the SIS Integration menu does not list Accelerate, then the data workbook used during implementation should be used to analyze the data extract definitions.
         • Assistance troubleshooting and fixing data extract definitions requires a support plan or a professional services engagement, as this is different for each institution and is not covered by base support. 
5. If the data extract includes the "missing/mismatched" data and there are no import errors, open a ticket with SS&E support.
   • Please include the data feed name and an example of data that is missing/incorrect in SS&E yet included in the data extract.
   • In most cases, SS&E Support will reset the Connector Cache and monitor the SIS Import job to make sure the data updates correctly.
   • If the data does not update correctly, SS&E Support will escalate the ticket for a resolution.  

NOTE: Sometimes the SIS data does not import into SS&E because something in SS&E, the SIS, or the data extract definitions is not configured properly causing the SIS Import Job/feed to fail to import data.

• For example, in order to import a student's advisor/coach from the SIS on the Person data feed, the person id associated with the advisorId/coachId must already be assigned a role in SS&E that has an advisor/coach function.
• To find which users are assigned to each role/function in SS&E, click on the role name and use the "People" link from here. 
• For more information about advisor and coach assignments, click here.
• In addition, when importing a Person Import Role from the SIS on a Person record, it is case sensitive and must import from the SIS with an exact match to the SS&E role Integration Id.
• To view each role Integration Id in SS&E , from Role Administration, select the Person Import Role name found here. If the Person data extract ROLE_ xxx does not match with the SS&E role Integration Id, there will be import errors showing "Group/Role null not found".

How to Check the SIS

If changing the data extract definitions does not resolve the missing/mismatched data issue, then either the data is not included in the SIS or is included incorrectly in the SIS.

Once the data is fixed in the SIS, it should flow into SS&E.

How to Check the Data Transfer

If the missing data is included in the data extract definitions output yet is not included in the data extract (Json file) on S3, then there is a problem with the data transfer.

In rare cases, even after data was successfully extracted from the SIS and the data extract definitions output the correct data, it sometimes does not display in the JSON file used to import data into SS&E.

1. Is there a warning in SS&E Administration indicating that data streams are out of date?

1. • When a data stream is out of date, it means that the data transfer was unsuccessful and the data extract in S3 is not current.
   • For more information about data feed out-of-date troubleshooting, click here.
   • From the above article, Advanced Administration > External Logging may display error messages that help explain/resolve data feeds out-of-date.
   • In general, when data feeds are out of date:
     • • When a single data feed is out of date, this is usually related to the data extract definitions or a file formatting issue/syntax error.
       • When all data feeds are out of date, this usually indicates a network/permissions issue such as a server move, firewall configuration, limited disk space, user/password change on the SS&E user running the Connect job scheduled task, Drill service related issue, or any type of network issue that is preventing the SIS data from reaching SS&E.
       • For example, when using Informer to extract data from the SIS for SS&E:
         • The Informer solution must be allowed to write data across the network to the proper location/virtual server.
         • The Informer export must update the files used for the Data Transfer to S3. 
         • There are different ways to accomplish this, however, the writing of this data needs to be enabled through some type of network configuration.
           1. The Informer service runs under a certain user/service account that must be set up with the proper permissions.
           2. The permissions of this account will control whether the Informer can write data to a location that is not on the local machine.
           3. In most cases, the Informer will write the exported files to the Connect server/virtual server. However, it may write the exported files to a local directory on the Informer server, and then a scheduled job would move the files across the network, based on the permissions that the user this scheduled job runs under.
              1. • NOTE: All network configuration settings and decisions are to be made by the institution and their network security team, not by SS&E.
2. If there is no warning in SS&E Administration, this means that there are no data feeds out of date and the Data Transfer process is working as expected.
   • If there is no red warning icon in SS&E Admin and the data transfer is not working, please open a ticket with SS&E Support. Please include all details including the data feed name, the data extract definitions output from the Connect server, a screenshot/file showing the source data, and the mismatched data missing from the data extract (Json file). 

How to Check the Data Import

There are numerous rules that may prevent SIS data from being inserted into the SS&E database during the SIS Import process.

Check Import Errors to search for error messages explaining why the record containing the missing/mismatched data is being blocked. By default, SSE displays import errors that occurred during the past 30 days.

Once the root cause for an import error causing the SIS Import to fail on a specific record is identified, depending on the error, this must be resolved either in SS&E, the data extract definitions, or the SIS (or a combination of the three) in order for the record to import successfully into SS&E.

• • For example, click here for the resolution of the import error "Could not parse file". 

Import Errors can be accessed from two places in SS&E Administration:

• Administration -> SIS Integration -> Import Errors, found here.
• Import Errors can also be accessed from the data feed "Errors" column, found here.

Import Errors search tips

1. On the Import Errors screen, click on Name to sort by the name column, and then search for the data name/id that is included in the data extract on file and missing from SS&E.
2. If there are 0 errors on the data feed "errors" column, open the Import Errors menu and enter the missing data Id/Name into the "Search Imported Row" filter without any data feed selected.
   • In some cases, this will return error messages that explain why the data is not being imported into SS&E and are not associated with the specific data feed.
3. Scroll through Import Error results for all datafeeds, without any data feed selected.
   • In most cases, there are many duplicate error messages since the issue will most likely repeat itself on multiple records/data extract files.
   • Many times, import errors are caused by bad data or old data.
   • To identify import error messages associated with missing data, scroll and search by Id on all data feeds. Sometimes errors display on related data feeds.
4. Something else that may prevent data from importing into SS&E is a "missing" prerequisite, such as:
   • When importing a Student/Person record, the Person Id on the student's AdvisorId and CoachId must already be assigned a role with the Advisor/Coach function in SS&E.
   • When importing a Person Import Role on a Person record, the role is case sensitive and must match the Integration Id on the matching role in SS&E. For more information about this error click here.
   • For more information about Role Administration click here.

Summary

Once the source of import errors and/or data inconsistency is identified, IF the data is missing from the data extract, this must usually be resolved either in the data extract definitions or the SIS.

The following table gives a quick overview of the SIS Integration troubleshooting steps:

SIS Import Process Overview

The following diagram visualizes how Database Queries are used to import data from the SIS into SS&E:

The following diagram visualizes how CSV files are used to import data from the SIS into SS&E:

SIS Import Job Frequency

Many times, when implementing the SIS data import process via CSV files, there is a need to adjust how and when the SIS source data is included in the CSV files since that determines what data is ready to be processed during the Connect job and later imported into SS&E.

• By default, the SIS import Batch Job runs 4 times a day at 4:30 AM, 10:30 AM, 4:30 PM, 10:30 PM.
  • • The SIS Import Job schedule/status can be viewed in Batch Processing Administration here.
    • The Engage worker process is responsible for importing the data into our database at 4:30am, 10:30am, 4:30pm, 10:30pm and currently we cannot change this schedule.
    • During this time changes will slowly start showing up in SS&E. This is based on the data from the batch job log found here.
• By default, the Connect Job runs 4 times a day, at 2AM,  8 AM, 2 PM, 8 PM, prior to each of the SIS Import Jobs.
  • • The Connect Job schedule can be viewed in External Logging Administration from here.
    • The most recent Connect job schedule and how long it takes for the Connect job to process can also be viewed by downloading the Connect 2 Full Log from the External Logging page.
    • The Connect job schedule may differ between institutions, yet what is important is that it completes before the SIS Import job is scheduled to start running.
    • The Connect 2 process runs and processes the files into the format we ultimately import.
• In addition, the Informer data is usually updated 4 times a day (based on report configuration).
  • • The Informer reports schedule can be found on the Connect server, either by looking at Informer or checking the dates on the CSV files to see when they were last updated. Since the reports are scheduled per data feed/CSV file, this can be different for each CSV.
    • How long it takes to create the export files from your SIS (CSV files) is important when considering what data may be available in those files.

SIS Import Timing Issue

Based on the above, the SIS data should update 4 times a day in SS&E, however this is not guaranteed.

• In order to determine when SIS data should display in SS&E, this depends on the Informer data output schedule, the Connect Job scheduled task schedule, and the SIS Import Job schedule to figure out the timing for the SIS data to flow into SS&E.
• As these "jobs" are scheduled to run at different times, depending on when the data is updated in the SIS, Informer, the CSV files, the database, it may or may not be included in the "most recent" the JSON data extract file on S3.
• The data must be included in the data extract (JSON) on S3 in order to import into SS&E (as long as the data feed is not out of date, the import job is running/completing on schedule, and there are no import errors).
• To view the most recent data imported into SS&E, download data extract files from here.

Additional Items to check

If there appears to be no issue with the SIS, the Data Extract, the Data Transfer, or the Data Import, yet data is still missing/displayed incorrectly in SS&E, check the following configurations:

1. On the SIS Import Job schedule - Click here to verify that the SIS Import Job is running on schedule and completing successfully.

• If subsequent jobs are failing consistently, open a ticket with Watermark Support.
• If jobs are sometimes completing, then SIS data is reaching SS&E less than four times a day.

2. On the Datafeed Configuration - Click here to verify that a data feed is marked as "Enabled - Yes".

• If a data feed is marked as Enabled "No", then the data is missing "by-design".
• When a data stream is disabled this means that it is intentionally being excluded from the SIS Import batch job.

3. On the Data Deletion Configuration - For data streams that synchronize data deletion with the SIS, check how this is managed here.

• If the data stream allows data deletion via All Ids or another method, that may explain why data is missing from the UI.