**Advanced configuration: please rope in all pertinent IT resources before proceeding.
Our SIS integration (AKA student data feed) syncs your student population to Suitable by creating/updating user accounts. Standing up the data feed will require collaboration between your institution's IT, program administrators, Suitable success reps, and Suitable technical POC.
1. Determine Data Fields
To streamline the feed's development you must first decide which data fields are of interest to sync to Suitable. At a minimum the feed should include:
- Non-alias email (or ePPN)
- First name
- Use "Preferred Name" if your Institution captures one. Provide "Preferred Name" when one is provided. If blank, use "First Name".
- Last name
- SIS ID/Student ID
- Class standing for each student.
You may decide on adding additional fields to cover students' info such as:
- College/School (if the feed is University-wide)
- Entry term
- Other custom cohorts
Talk with your success rep to determine which fields are valuable per your program's goals and then confirm with your IT team the data is accessible. At the end of this exercise you should have a list of fields to hand over to your technical POC.
2. Determine Transfer Process
Once the data fields are identified your technical POC will work with your IT team to determine the schedule and mode of transfer. It is advisable to schedule the transfer daily but a weekly schedule is also acceptable.
To transfer the file, your IT team will be required to package the file as a CSV and leverage the Suitable REST API for transmission. To authenticate and interact with the API your IT can script directly against our API or leverage a provided API wrapper.
Regardless of which avenue taken, your IT should provide an email address to receive status emails from the completion of transfer jobs, in exchange, your technical POC will provide API credentials to use for authentication.
Scripting API Interaction
If scripting the API interaction you may find it helpful to toggle the Language option in our developer docs to align with your preferred language and http client library. Setting the proper Language option will provide code snippets for each request which you can use as a starting point. The two APIs to look at are:
- Login - Use this endpoint authenticate using the provided access credentials and retrieve an access token for use in subsequent requests for authorization
- Update Student Roster Info - Use this endpoint to transfer the student data CSV file to
To hasten the student data feed's development your IT may alternatively use an API wrapper that handles the API authentication and file transmission on your behalf. Below is an example of executing the API wrapper via the CLI:
./roster-sync -id=<INSTITUTION_ID> -username=<API_USERNAME> \
-password=<API_PASSWORD> -baseUrl=https://<API_ENV>.suitable.co \
3. Test Transfer
To verify the efficacy of the student data feed, a sandbox environment will be leveraged to not disrupt your production environment. Once the file is available your IT should transfer it to the sandbox environment in coordination with your technical POC. Your technical POC will confirm if the file was successfully processed or if there are any data violations. After processing a transfer successfully your IT should verify, with the program administrator and any other stakeholders, the data is satisfactory via the web platform.
4. Promote Transfer to Production
After receiving the proper sign offs to move to production your IT should begin transferring the to your production environment, at which point your IT should begin receiving emails to their status recipient once the transfer has been processed. Once online, virtual high fives are in order 🤩.
NOTE: Your access credentials and instance identifiers will be provided for the respective environment via your technical point of contact.
What is the CSV file format and column ordering?
Your technical POC will provide a CSV template that declares the necessary header row and strict column ordering to use for the data fields. The file content is required to be UTF-8 encoded data. All columns should be surrounded with double quotes and delimited by commas.
What are the dictionaries for each data field?
Review Mappings section in API docs for standard fields. All custom fields will accept any value provided in the file.
How should I handle multi-valued fields?
Review Multi-Valued Columns section in API docs.
Custom data columns that are multi-valued need to be delimited by a semicolon
;. For example, if a majors column exists and a student has both Psychology and Marketing majors this would be represented as
Psychology; Marketing in the column.
If you have additional questions, chat with us below or send us an email at email@example.com.