SIS/HR Data (ISSS)
ISSS SIS data file specifications
To view the full spreadsheet, hover your mouse over the document, and click the arrow in the upper right-hand corner. Please note the various tabs at the bottom of the sheet.
Scroll further down this page to see additional file specifications, overview of the integration structure, and FAQs.
Additional SIS file specifications
- 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, students, scholars, and exchange visitors.
- 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.
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.
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 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; TDS 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 TDS.
The automated SIS refresh task then refreshes active user accounts in TDS 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 TDS. 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 TDS.
After admin review/approval, SIS updates as well as any other updates can be included in a batch event to SEVIS for overnight processing. TDS 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 TDS.
Q: How many 'Custom' fields should we include in the data file?
A: The answer depends on the type of TDS 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 TDS 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 TDS, 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 TDS 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: TDS 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 TDS, and the ISSS office can take advantage of the many features in TDS 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 TDS.
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 TDS 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 TDS 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 TDS 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 TDS 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.