Overview

During a Terra Dotta implementation, a SIS integration links a client's Student Information System (i.e. their centralized institutional database) with their Terra Dotta production site. The result is a seamless, centralized way to access user data within Terra Dotta. A nightly SIS Refresh task keeps data between the two systems in sync.

This article covers the following topics related to the SIS Refresh:

• Understanding the SIS Refresh
• Reading the SIS Refresh Log
• Resolving Core Data Field Discrepancies
• Enabling the Force SIS Data Refresh
• The SIS Refresh & Applicant Parameter Values
• Frequently Asked Questions

Important Note: Client sites are loaded with functionality to support the broad range of Terra Dotta enterprise solutions, including ISSS and Study Abroad. Slight variances in terminology may occur depending on the Terra Dotta solution referenced. For example, this articles refers to both "applicants" and "users" which are synonymous. Your site will display the term relevant to your office.

Understanding the SIS Refresh

The SIS integration is led by a Terra Dotta Integration Specialist with the support of the client's Primary Admin and IT office during the client's Terra Dotta implementation. As part of the SIS integration, the technical team collaborates with the functional office to determine what essential data from the client's SIS should be included in a SIS file to Terra Dotta. The client's finalized SIS file contains user profile information for all campus users of the client's Terra Dotta production site (for example, a currently enrolled student wishing to apply for a study abroad program or an F-1 visa student requesting Curricular Practical Training).

For additional information regarding the SIS integration, clients should direct questions to their Terra Dotta Integration Specialist and reference the Terra Dotta Technical Documentation.

After the SIS integration is complete, a nightly transfer process will occur in which the client's IT office will securely send an updated SIS file to Terra Dotta. The data from this file is loaded into a temporary table. Next, the SIS Refresh takes place: the active user profiles in Terra Dotta are "refreshed", or updated, with the latest information from the SIS table. The full SIS Refresh process is the communication which keeps data values in Terra Dotta updated and in sync with data values in the institution's SIS.

Helpful SIS-Related Reminders

If your Terra Dotta site has applicant parameters that are mapped to your SIS, then those parameters must be updated directly in your SIS. This means that for integrated users, neither the users nor the admin will be able to enter or edit the values for SIS-mapped applicant parameters in Terra Dotta.

• Terra Dotta sites that have been integrated with your institution's Student Information System (SIS) will have integrated users with a UUUID as the username. This serves as the key to your authentication and information services. Note: This does not mean that the user logs in with this UUUID.
• When an integrated user creates a profile on your Terra Dotta site for the first time, they will be asked for permission to access and pull in the necessary core data fields and SIS-mapped parameters and address types. If they refuse permission to this request, their profile will not be created - and they will be logged out of the system.
• If your integrated user has an active application, they will be included in the SIS Refresh that runs nightly to update core data fields, applicant parameters, and address types.

Reading the SIS Refresh Log

An admin can view the details of each night's SIS Refresh that has occurred on their Terra Dotta site by navigating to Maintenance > SIS Refresh. The SIS Refresh log tracks every occurrence of the execution of the st_SISDataRefresh scheduled task as well as the execution of the initial pull for new, internal users.

Important Note: The Task Scheduler maintenance permission is managed exclusively by Terra Dotta for hosted clients.

Your Terra Dotta site will maintain a record of each attempt by Terra Dotta to access the linked Student Information System (SIS), as well as the results of that attempt. The SIS Refresh serves multiple purposes to the maintenance users of a Terra Dotta site and indicates if the SIS Refresh ran successfully, the number of user profiles that were updated, the changes that were applied to those profiles, and a list of profiles which the process attempted to update but could not (either due to an error or missing data in the SIS file). Therefore, understanding the output of the SIS Refresh log can be vital to troubleshooting and accurately updating student information in your Terra Dotta site.

To get started in reading the SIS Refresh log, enter a date into the search field in the SIS Refresh panel and click "Go". The available SIS Refresh statistics for that date will populate in a second SIS Refresh panel.



The information displayed in the SIS Refresh log is organized into columns in the following way:

Start Date Time / End Date Time
These columns indicate when the SIS Refresh started and completed. For the nightly scheduled task, a longer process duration is expected. For the initial pull of new user data from the SIS, this period of time should be relatively short.

By
This column indicates if the SIS Refresh was initiated by the System or by a specific admin user. In cases where the SIS Refresh was started due to the scheduled task or by an new internal user logging in for the first time, the column will indicate "System". If the SIS Refresh was started due to the "Refresh Manually" button being pressed or due to an administrator updating a user's core data, this column will display the name of the admin user that committed the action.

The "Refresh Manually" button can be used to push out SIS updates immediately to user profiles instead of waiting for the nightly scheduled task to occur. Two scenarios where this feature may be used are when changes are made to the SIS file or when an issue has occurred with the scheduled SIS Refresh task.

The "Flush Task Data" button is used to remove all existing, historic SIS Refresh log information. It's advised that you first consult with Terra Dotta Support before using this feature.

Init. Type
This column indicates the type of action which triggered the SIS Refresh to occur and is usually one of the following:

• System Task: The SIS Refresh was due to a scheduled task. 
  • When the SIS Refresh is executed due to a scheduled task, the site's Contact 1 email address will receive the related report via email after the process has completed.
• User Initiated: An administrator clicked on the "Refresh Manually" button or updated a user's core data.
• New User: A new, internal user logged into the system for the first time.

Refresh Type
This column will indicate one of the following:

• All: The SIS-mapped parameters were all updated during the SIS Refresh.
• SingleUser: The SIS Refresh was a core data update for a single user's specific data field.

Status
This column will note whether or not the SIS Refresh was able to complete its execution without errors or if it failed to complete the process with one of the following indicators:

• Completed: The SIS Refresh completed. However, this status could have a warning attached to it that requires investigation by examining the detailed results of the SIS Refresh (see "Total Warnings" below).
• Failed: The SIS Refresh failed to execute due to an error. Investigate by examining the detailed results of the SIS Refresh (see "Total Errors" below).

Click the arrow to the left of the applicable SIS Refresh entry to expand and view the full report of the SIS Refresh log.



The information displayed in the SIS Refresh log report is organized into rows in the following way:

Batch ID
This is a unique ID for the execution of this specific SIS Refresh. Include the batch ID in any Terra Dotta Support request that may require an investigation of the SIS Refresh.

Applicants/Users Pooled
This is the number of applicants/users that were included in the SIS Refresh. When the SIS Refresh is triggered by a new, internal user, this number will be 1. In the case of the st_SISDataRefresh scheduled task and manual updates, this will be the number of active applicants/users that the SIS Refresh found in your system. Click "View" for more details.

# of Parameters in Refresh
This is the number of mapped student parameters that were checked during the SIS Refresh. For example: Three might include EDUCATION_LEVEL, CIP_MAJOR, and CIP_MINOR. Click "View" for more details.

Import Changes
This is the number of individual data fields that were changed during the SIS Refresh process. If there were changes made to your Terra Dotta database, see the specific updates by clicking "View".

Core Discrepancies
This is the number of core data fields in which the stored Terra Dotta value for X field was different from what was sent in the SIS file for X field.

The core data fields are:

• First Name
• Middle Name
• Last Name
• Email Address
• Date of Birth
• Gender
• Username
• Confidentiality Indicator

Important Note: By default, Terra Dotta does not automatically update core data field discrepancies during the SIS Refresh. These discrepancies are flagged and must be manually updated by an admin unless the "Force SIS Data Refresh" setting is enabled. For detailed instructions, see the Resolving Core Data Field Discrepancies section below.

User Discrepancies
This is the number of integrated users who exist in Terra Dotta yet were missing in the SIS file. Some of these cases may be resolved when updating the core discrepancies (usually in the case of a changed username), but more frequently, these are users that have left the host institution but still have active applications/records in Terra Dotta. It is recommended that you consult with your IT office regarding why these users were not sent in the SIS file to Terra Dotta.

A very high number (larger than 150) of user discrepancies is frequently an indication of a SIS data issue and should be investigated promptly.

Total Execution Time
This number indicates the amount of time it took for the SIS Refresh to complete.

Total Warnings
This is the number of warnings that were encountered during the execution of the SIS Refresh. A warning typically points out a Terra Dotta user with a missing profile in the SIS file. Warnings do not prevent the SIS Refresh from completing. Click "View" for specific warning details.

A very high number (larger than 150) of total warnings is frequently an indication of a SIS data issue and should be investigated promptly. Include all warning details in any Terra Dotta Support case that may require an investigation of the SIS Refresh.

Total Errors
This is the number of errors that occurred during the execution of the SIS Refresh. Click "View" for specific error details. In most cases, the SIS Refresh will have not completed its process due to an error, and this issue should be investigated immediately. Include all error details in any Terra Dotta Support case that may require an investigation of the SIS Refresh.

Resolving Core Data Field Discrepancies

• The core data was not imported into Terra Dotta during the initial new user creation process. Possible causes could be that the SIS was temporarily down/offline, or the SIS did not have the data at the time it was requested.
• There has been a legitimate change to the core data value in the SIS that needs to be updated in Terra Dotta. Examples include a new last name due to a legal name change or case sensitivity (i.e. Mary to MARY).

By default, Terra Dotta does not automatically update core data field discrepancies as they are considered critical to the user's profile in the Terra Dotta database. It is best practice for core data field value changes to be monitored by a system administrator to ensure that changes are not being made with invalid values due to data file corruption or unexpected changes in the SIS data source. However, you may request to enable a setting known as "Force SIS Core Data Refresh" on your Terra Dotta site that will automatically update any core data field discrepancies discovered as part of the SIS Refresh.

The "Force SIS Core Data Refresh" setting is a Maintenance > SIS/HR Mappings permission that is not granted to clients hosted on Terra Dotta's server environment. To enable this setting*, open a Support Case.

*If this permission was assigned to you prior to the TDS 19.0 release and has not been removed from your account, then you may choose to independently take the following steps:

1) Navigate to Maintenance > SIS/HR Mappings. Click on "SIS/HR Integration Settings".
2) From the "Mappings: Environmental Settings" page that appears, locate the "Force SIS Core Data Refresh" section. Check the option of "Yes" to make the auto-update feature the current setting on your Terra Dotta site.
3) Click "Update" at the bottom of the page to preserve your changes.




Important Note: By enabling the "Force SIS Data Refresh" setting, you will not eliminate the core discrepancies alerts that appear in the SIS Refresh log. However, the enabled feature does eliminate the manual step of clicking "Update" to approve each change.

The SIS Refresh & Applicant Parameter Values

As part of the scheduled SIS Refresh, SIS-mapped applicant parameter values for integrated users are updated. To make this process efficient and reduce the load on the data source, Terra Dotta does not refresh data for all of the applicants/users that have ever had an application/record on the site, but only for those applicants that meet the following three conditions:

1) Applicant/User must be integrated.

To quickly determine if an applicant/user is integrated:
- Navigate to Maintenance > Edit User.
- Search for the user, select them from the search results, and click "Next" to view their information. The "Integrated User" setting will be configured to "Yes".

2) Applicant/User must have one of the following applications/records:

• Any application with a status or status alias of pending, accepted or committed; OR,
• An advising application on a site that where the "SIS Refresh for Advising Applications" setting has been enabled.

To enable the "SIS Refresh for Advising Applications" setting:
- Navigate to Settings > System Features.
- Click on the "Process Options" tab.
- Check the "enable" box next to the "Enable SIS Refresh for Advising Applications" setting. It is possible to specify the duration of time (in months) for which you want the SIS Refresh to occur after the application creation date.




Important Note: Waitlisted applications are not considered "active" (whereas pending, accepted, or committed status are) and are not included in the SIS Refresh.

3) The application must be considered "active".
The following criteria are considered when determining if an application is "active" or not:

Applications with an Itinerary

An application is considered "active" if it has an itinerary with an end date in the future. In addition, a "SIS Mapped Parameter Data Refresh" setting allows you to specify the number of months after the return date that applicants are included in the SIS Refresh and have SIS-mapped parameters updated. By default, this refresh window is set for 2 months after the return date.

To manage the "SIS Mapped Parameter Data Refresh" setting:
- Navigate to Settings > System Features. Click on the "Applicants" tab.
- Under the "Applicant Data Options" section, locate the "SIS Mapped Parameter Data Refresh" field. Make your update in months here.
- Click "Update" to preserve your changes.

• The application has a status or status alias of pending, accepted, or committed.
  • For advising applications, the "SIS Refresh for Advising Applications" setting must be enabled. (This is done from Settings > System Features > Applicants > Applicant Data Options > SIS Mapped Parameter Date Refresh.) And, 

• The application has an itinerary with an end date in the future.
  • For applications without itineraries, the system looks at the decision date and considers the application "active" until the decision date is reached.
  • If the "SIS Mapped Data Parameter Refresh" setting has been enabled, then the applicant will be included in the SIS Refresh and have SIS-mapped parameters updated for the amount of time (in months) specified. This means that if you combine the decision date (for example, January 1, 2020)+ the SIS Refresh window amount (for example, 2 months), then this will give you the date on which the applicant would have stopped being active. The applicant's profile parameters would not have been updated since this date.

3. How can I resolve the issue of my applicant's profile not being updated?

First, read the information in response to question #2 above to understand what is likely happening. Then these are actions you can consider taking:

• Add an itinerary to the applicant's program application. After you do this, the applicant will be active until "X" amount of months (with "X" being based on the amount of time set in your site's SIS Refresh window).
• Move up the decision date to within the past "X" amount of months (with "X" being your site's SIS Refresh window).
• Extend the SIS Refresh Window setting to keep applicants active for a longer amount of time.