Scroll further down this page to see additional file specifications, overview of the integration structure, and FAQs.
- The population of the file will vary slightly by institution, but usually is defined as: all confirmed applicants, current students, and students who have withdrawn or graduated within the last 60 days, who have a citizenship other than US, and who are NOT US permanent residents ("green card" holders). IMPORTANT: The population of the student file should be based on visa type or citizenship, and NOT dependent on enrollment in a current or future term. This is because ISSS offices need to know when international students do not enroll as expected.
- Tab-delimited text file with any empty/null columns delimited with the appropriate number of tabs to maintain column alignment.
- Double quotes should be removed
- Header row is required. See the above spreadsheet for the list of required headers.
- If no data is present in the SIS for a required field in the SIS file, the header should be included but the data fields can be null.
- Single record per user. The file cannot contain duplicate UUUIDs.
- Must contain a record for every potential user of the site. For an ISSS site, this is generally all international applicants and students.
- If HR data is sent in the same file as student data, the filename should be sis_hr_user_info.txt. If HR and student data are sent in separate files, the filenames should be hr_user_info_core.txt and sis_user_info.txt.
SIS addresses
SEVIS requests both US and foreign addresses. The US physical address and US mailing address fields listed in the SIS data file must not contain any foreign addresses, as these will not pass validation. Similarly, the foreign address fields in the SIS file must not contain any US addresses.
Important Note: Separating US addresses from foreign addresses in the SIS file typically requires clients to establish a business procedure at the institution to ensure that these addresses will be accurately entered and identified in the SIS. This may require working with other campus stakeholders who enter information into the SIS, such as Admissions or the Registrar. Creating an institutional business procedure and updating the address data in the SIS can sometimes be a lengthy process, so we recommend clients start assessing and addressing this issue as soon as possible.
HR data
HR data refers to user creation information for any campus administrators or faculty who will need access to the site. Providing data for these users does not automatically grant them access to the site; Terra Dotta administrative accounts and permissions are controlled by the functional office. However, providing HR data does allow for the possibility for these users to have integrated accounts on the site, and to use the campus authentication system when logging in.
The minimum required data for an HR user is: UUUID, first name, last name, and email address. If HR data is included in the same file as student data, an HR flag column must be included as well.
Besides the ISSS functional office users, many other campus faculty and administrators may need access to the site. Generally, we recommend including data for all professional staff and faculty at the institution. Some examples of HR use cases: academic advisors may need to submit approvals for students, or departments may need to review or update visiting scholar information.
The above graphic illustrates the general data flow in a Terra Dotta ISSS integration:
SIS data is sent via automated SFTP across Terra Dotta's firewall and deposited in an SSH folder.
Then, Terra Dotta's automated data loader loads the file into the Temporary SIS database. After the SIS file is loaded, it is deleted from the SSH folder. The SIS database is overwritten with new SIS data every night. This means that Terra Dotta does not retain SIS data unless the user has an account in Terra Dotta.
The automated SIS refresh task then refreshes active user accounts in Terra Dotta with data from the SIS. This refresh process will also alert the admin to possible SEVIS updates.
Users have the ability to manually enter data directly into Terra Dotta. Manually-entered data is in addition to the SIS data, and is not meant to replace or edit SIS data. SIS data cannot be manually edited in Terra Dotta.
After admin review/approval, SIS updates as well as any other updates can be included in a batch event to SEVIS for overnight processing. Terra Dotta also allows clients to manually update individual records in SEVIS via the RTI Connect tool.
After processing, data and documents from SEVIS are downloaded into Terra Dotta.
During the Integration, it is highly recommended that at least one staff member in the functional office has access to view and/or edit data in your SIS. The reason for this is during the implementation, data from SEVIS will be imported into your TD site and compared with data from the SIS. At that time, functional offices often determine that data may need to be updated, such as U.S. Addresses. Due to the implementation timeline, the functional office may need to make trivial updates in the SIS to align the data best for SEVIS reporting. Additionally, after your implementation, your SIS will become the system of record for your integrated fields/parameters. If any formatting or updates to these fields are needed, it is recommended that those take place in your SIS. Therefore it is recommended to maintain access to your SIS to make the necessary updates.
FAQs
Q: We have an existing integration, either with a different SEVIS batching solution, or another Terra Dotta site (study abroad, travel registry, etc.). Can we reuse the integration logic from this other solution to save time on building the SIS data file for the Terra Dotta ISSS/SEVIS site?
A: In short, no. Terra Dotta Software for ISSS has unique data requirements that differ substantially enough from other SEVIS batching solutions (or even other Terra Dotta software solutions) that very little of what was built for the integration of the other site can be reused for the new site.
In the case of a previous SEVIS batching solution, it will be helpful to review what was built for that integration (especially custom data fields or data translations) and understand the business needs behind those decisions. However, please note, since Terra Dotta Software for ISSS is intended to support all the business needs of the ISSS office, not just SEVIS reporting, our data file requirements also include additional biographical and academic information beyond what SEVIS requires.
This means the data file for the Terra Dotta ISSS site should be considered as if it is an entirely new project, and the institution's IT will need to commit programming /development resources in order to complete the integration on schedule.
Q: How many 'Custom' fields should we include in the data file?
A: The answer depends on the type of Terra Dotta implementation purchased. A Simple implementation includes 10 custom fields, a Standard implementation includes 25 custom fields, and an Enterprise implementation includes as many custom fields as necessary.
If you are not sure what type of Terra Dotta implementation your institution has purchased, please ask your Terra Dotta Integration or Implementation Specialist.
Q: How are the 'Custom' fields used?
A: The custom fields will have a generic column header (CUSTOM1, CUSTOM2, etc.) and can be populated with any additional data the ISSS office may require beyond the data already included in the file specifications. Many offices choose to include additional biographical or academic information. However, it is not required to populate the custom fields with data at the time of implementation -- some or all of the custom fields can remain blank.
Later, as the institution develops their use of Terra Dotta, the functional users may wish to add additional data to the file. At that time, any custom fields that were previously blank can be populated with data, while keeping the column header itself unchanged. Terra Dotta can then configure the Terra Dotta user interface to display the description of the data that has been added to the custom field. This allows the client to have the flexibility to add additional data to the file as needed, and because the format of the file is unchanged, Terra Dotta will not need to rebuild the data loader processes or the user database in the software, streamlining the process and saving time for everyone.
Q: What are some suggestions of data to include in the 'Custom' fields?
A: Here are some examples of data elements that previous clients have included in the custom fields: Admit Type (ESL, degree-seeking, certificate, etc.), Athletic Sport, On-Campus Employment (Y/N), Major-Specific GPA, Transfer GPA, On-Campus Housing (Y/N), Disability Information, Ethnicity/Race Information
Q: Do we have to include the 'Custom' fields in the data file?
A: Yes. If you don't wish to include any data in these fields, they can remain blank, but the custom columns must be included in the data file.
Q: What if we want to include users with visa types other than F, M, or J in the data file?
A: Terra Dotta only supports SEVIS batching and RTI for records with F, M, and J visa types, but clients can include users with any visa type in the data file. Including these users in the file allows them to have accounts in Terra Dotta, and the ISSS office can take advantage of the many features in Terra Dotta to better track, manage, and provide services to non-F/M/J visa types.
There is no required code for any visa type other than F, M, or J. For non-F/M/J users in the file, the VISA_TYPE column should be populated with the description of the visa type rather than a numeric code. For instance, if a user has the H-1B visa type, then 'H-1B' or 'H1B' can be included in the VISA_TYPE column for that user.
Q: How should credit information be sent in the file? Why is it necessary, and how will it be used?
A: ISSS offices have an obligation to certify to the government whether or not an international student is currently enrolled full-time at the institution. This process is called "SEVIS registration" and must be completed for every single student, every single term. Only a limited number of online credits count towards these enrollment requirements. Therefore, credit information in the file is necessary in order for the ISSS office to fulfill their registration reporting requirement via Terra Dotta.
The fields CREDITS_CAMPUS, CREDITS_ONLINE, and CREDITS_ESL should contain numeric totals for each type of credit for which the student is enrolled for the current term. If there are no credits of a particular type to report, these fields should list a zero instead of being blank. The CREDITS_TOTAL field should be the sum of the previous three fields.
The FULL_TIME field should have a single indicator of whether the student is currently enrolled as a full-time student or not, according to the requirements for their particular program of study. This indicator is not required to be in any particular format -- we will build custom queries based on the code(s) you include in the file.
The CREDITS_TERM field should indicate the term and year for which the credit fields above are currently being reported in the file (such as 'Fall 2019' or '201901' or whatever format you prefer). The CREDITS_TERM field allows functional users to know at a glance the term and year to which the other credit fields are referring.
For example, at a semester institution, if today is the day after the add/drop deadline for Fall 2019, the credit fields listed in today's file should report the Fall 2019 credit values, and CREDIT_TERM should list the code for Fall 2019. The values in these fields should stay static all through the rest of fall term, winter break, and the add/drop period for Spring 2020. The day after the add/drop deadline for Spring 2020, these fields should all be updated to the Spring 2020 values.
Finally, CREDITS_EARNED lists the total number of credits a student has earned in the entire course of study at the institution. This field is not used for SEVIS registration, but is very useful for the ISSS office for advising and other internal functions.
Q: For fields such as LANGUAGE_TEST1, LANGUAGE_TEST2, FINANCIAL_HOLD, CONDUCT_HOLD, etc., the SIS contains multiple possible values that could be included in the file. How should these be managed?
A: Reporting and querying in Terra Dotta work best when each data field contains a single value. If the ISSS office has a large student population or plans to make extensive use of Terra Dotta functionality for reporting or querying on these fields (for example, creating a report ranking users by their language test score, or querying for all users with one particular kind of financial hold), then just one value should be included in the specified field, and additional information can be included in the Custom fields in the file. We can then configure the user interface in Terra Dotta to display the description of the actual data included in each field so there is no confusion.
However, if the institution has a smaller international student population, or if this kind of detailed querying or reporting is not necessary, then either a Y/N indicator (in the case of holds) or multiple values can be included in each field. Most data fields can accommodate up to 500 variable characters.
If you are still not sure, request a meeting with your Integration specialist to talk about the various options and receive a personalized recommendation.
Q: What value do we enter in the CITIZENSHIP_COUNTRY field if the student has more than one country of citizenship?
A: SEVIS only allows one value for country of citizenship, and Terra Dotta is set up to mirror SEVIS. You will need to choose one country as the primary country of citizenship and include that in the CITIZENSHIP_COUNTRY column. If you like, you can use one of your Custom fields at the end of the file to include information about a secondary country of citizenship.
Q: What if a student is currently enrolled in one degree program but then is admitted to another degree program at the same institution?
A: In the case of a current enrolled student admitted to a future different program at the same institution, (i.e. a current undergraduate admitted to a future Ph.D. program at the same university) the Education Level and associated Major CIP code for the new program should be sent no earlier than the day after graduation for the current program. So the file should contain one record for that student and list that information as the Active program until the date that program ends. The next day, the data file can switch over to reporting the upcoming program for that student. If you need to know about the new program ahead of that date, you can include a Y/N indicator or a description of the upcoming program in a custom field, and then set up a query watch (automated notification) in TDS to alert you to it.
Q: What if a current student cancels or withdraws from the institution?
A: You can include information about withdrawal or cancellation in a custom field, and then you can continue to include the student in the data file for at least one day past the date that the withdrawal or cancellation goes into effect.