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 (Study Abroad) 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.
- 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 (with a few exceptions) data that is pulled into TDS via the integration will be displayed as read-only and cannot be edited or deleted within Terra Dotta.
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:
- Unique, in that no two people have the same UUUID
- Universal, in that everyone on the campus has one, whether they are faculty, staff or a student, and
- 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.
- 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.
- 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.