Integration Documentation

Terra Dotta has a standard integration process for all SaaS/Saas Unlimited/Hosted clients. This page provides a detailed explanation of the integration configuration options and requirements for all client types.


Visit the following links for a simplified overview of the integration requirements and timelines for various client types:

SFTP

(See Transferring Data to Terra Dotta for more detailed documentation)

Terra Dotta will provide each client account with an SSH folder for the transmission of text-only SIS (Student Information System) and HR data files. The client will provide a nightly SFTP of the SIS text file extract(s).

SIS FILE

(see SIS/HR Data or SIS/HR Data (ISSS) for more detailed documentation on the required format of the SIS file)

The SIS file must be a tab-delimited text file, containing user creation information for all potential campus users of the site, plus additional optional information. User creation information includes, at a minimum, unique ID (UUUID -- see below), first name, last name, and email address.


Potential users will be determined by the primary business use of the site. For instance, for a Study Abroad site, potential users of the site would be anyone wishing to apply for a study abroad program. In practicality, this generally means that any currently enrolled student at the institution would be a potential user. For an ISSS TDS implementation, however, potential users of the site usually would be limited to international students, scholars, and associated administrators.

FACULTY/STAFF DATA

HR data may be transferred in a separate flat file, or it may be included in the same file as student/applicant/user data with a flag to indicate who should be considered as HR.

  1. Must contain the entire eligible population of potential staff users.

SYSTEM of RECORD

In this integration configuration, the SIS is the System of Record, meaning that data that is pulled into TDS via the integration cannot be edited or deleted within TDS. SIS data will be read-only within TDS, and will reflect the value of that same data within the SIS.

SIS REFRESH

The scheduled task that refreshes SIS applicant parameter values for integrated users is executed each night. To make this process efficient and reduce the load on the source of the data, Terra Dotta software does not refresh data for all of the applicants that have ever had an application on the site, but only those active applicants that meet the following three conditions:

1. User must be 'integrated':

2. User must have one of the following applications/statuses:

Any application with a status or status alias of pending, accepted, or committed. (Note that waitlisted applications are not considered 'active' and are therefore not included in the SIS refresh.)

-- OR --

An advising application and the site is configured to refresh SIS data for advising applicants.

3. The application must be considered 'active' based on application itinerary dates and the site's SIS refresh window:

An application is 'active' if it has an application itinerary with an end date in the future and for a small window of time after the end date. That window of time is 2 months by default, but can differ for each Terra Dotta client.

If the application does not have an itinerary, there is no end date for TDS to use to determine the 'active' status. In this situation, the system will instead look at the decision date and consider the application 'active' until the decision date is reached and then for that small refresh window after the decision date.

For sites that use 'rolling admissions' it is common to have decision dates far in the past, causing applications to not meet the 'active' requirements if start/end dates haven't been provided or if the application itineraries haven't been created.

If the application is an advising application, it will be included in the refresh if it is not older than the timeframe of the refresh window. For example, assuming the refresh window was left at the default of 2 months, advising applications will be refreshed for 2 months.

UUUID

The SIS file must contain a UUUID (Unique, Universal, Unchanging Identifier) for each potential user. This can be any UUUID the campus prefers, usually a Student/Employee ID, PIDM or even an email address. This ID must be:

  1. Unique, in that no two people have the same UUUID
  2. Universal, in that everyone on the campus has one, whether they are faculty, staff or a student, and
  3. Unchanging, so that, even if the person changes their name, withdraws and then returns, and/or changes roles at the institution, they will keep the same UUUID.

USER CREATION

User creation is the process by which a user account is created in the Terra Dotta system. User accounts can be created in multiple ways, but the two overarching categories are user self-creation and administrative user creation.

User Self-Creation

Integrated user creation often, but certainly not always, happens in conjunction with a user's first attempt at user authentication via their institutional login identity. This is user self-creation. In user self-creation, users initiate the process of creating their user account in the system when attempting the following actions for the first time:

  • Applying to a program
  • Requesting an advising appointment
  • Requesting information
  • if enabled, creating a stand-alone user profile

A queryable data source must be available to look up the required Core Data (First name, Last name, email, UUUID) at the point of authentication. This lookup is performed based on the UUUID value responded from the authentication.

Administrative User Creation

Administrative user creation is the process by which a user creates an account for another. Administrative user creation is done via lookup for integrated users. A queryable data source must be available for new integrated user look up. The following actions in the TD system require user lookup for integrated user creation:

  • an administrator creating an application for a new user
  • an administrator creating a profile for an applicant (if enabled)
  • an administrator adding a new staff member
  • A third party creating an application/registration for another user
  • an administrator adding a contact to a program
  • an applicant requesting a recommendation from a new recommender

USER AUTHENTICATION

User authentication is the process by which users validate their identity through the use of a username and password. User authentication is accomplished by one of two processes.

  1. Local Authentication: Terra Dotta Software has the built-in ability for both applicant and admin users to login using local authentication. Local authentication means that users can have an account in TDS that is based on their email address as their username and a password they set themselves. Since the local authentication functionality is native to the software, this option is maintained even for clients who set up an integration with a campus (remote) authentication system.
  2. or the user has institutional login identity credentials. An integration with Terra Dotta Software requires that the client also provide a campus-wide authentication solution. This means that users who are associated with your institution will be able to log in to Terra Dotta Software using the same username and password combination that they use to access other campus systems. Setting up campus authentication makes logging into TDS easy and straightforward for your institution's users. Someone who logs into the site using campus/remote authentication is called an integrated user.

Integrated user authentication uses the institutional user authentication mechanism. When an integrated user attempts to login to the Terra Dotta system, the system sends a request for user authentication and the user's "UUUID" (Unique, Universal, and Unchanging ID) to the institutional user authentication service. User access is granted based on the response from the institutional system.

CUSTOM URL (optional)

There are two available options:

1. URLs for both the public and post-login portions of the site remain as they are, using the terradotta.com domain.

2. Both the public and post-login portions of the site will have a custom URL using the institutional domain. (e.g. goabroad.myuni.edu, international.myuni.edu, etc.)

Changing the post-login URL also has multiple implications for the remainder of the authentication. Most importantly it will impact the progress of the institutional authentication. So determination of the URL as early as possible is especially important.

ISSS Integration Timeline

Intro to integrations meeting

An overview of the required integration tasks, Terra Dotta's technical documentation, the integration planning form, as well as time for Q&A.

Integration planning meeting

Reviewing, completing, and submitting the ISSS Integration Planning Form. Between this meeting and day 1 of Implementation week 3, the client will work with Terra Dotta to establish the SFTP connection and submit the finalized SIS data file.

Implementation weeks 1-2

Client IT is programming the SIS data file, and working with Terra Dotta to establish the SFTP connection.

Implementation week 3

The completed SIS data file is submitted via SFTP on or before the first day of week 3. Terra Dotta will review and list any required edits. These edits must be completed by the end of the week.

Implementation weeks 4-5

Intensive working weeks with daily check-in meetings. Clients will import the SIS file data into TDS and compare SIS data with data downloaded from SEVIS. Clients will work intensively to resolve any data validation issues or discrepancies.

Implementation weeks 6-8

Work continues on SIS data file edits, if necessary. In addition, the custom URL and authentication portions of the project will be completed and tested during this time.