The first step to implement Handshake is setting up an automated data feed between the student information system and Handshake.
Provisioning Student Accounts
This is the most important step of the implementation process. It is required to launch to students and is the most resource intensive part of the process from an IT perspective.
What it involves:
- You'll manually upload a list of records from your student information system. Use these instructions to create your student file
- You’ll access a tool called the Importer to upload the initial student CSV file. The importer will give you feedback on the file. You should address any warnings or errors given to you by the importer before moving on.
- Once your file is in the correct format you can automate the upload of this profile. Generally, this file should be set to run weekly but the cadence can be defined by the university.
Creating the Data File
Handshake requires a CSV file to create and update student accounts. This file should pull from the student information system and include *all students that should have access to the Handshake platform.
To complete this, we generally suggest writing a script that pulls from the student information system and creates a file in the format specified here.
A few things to note:
-
Handshake handles checking for changes, so no need to build that logic into the script. We'll only update accounts where something has changed since the last run
-
In the next step, we'll be automating this process so writing this script to reusable will save time there.
Once you have a file that you're ready to test, you'll need access to the Importer tool. Your Handshake point of contact will help you get connected to that tool. Once you're connected you'll be able to upload the file and get feedback on any errors.
Once the file is error free you can submit it for final review by the Handshake team. Assuming all is good to go, we'll run this file and create the accounts in production.
Automating the Data Sync
Once the importer approves your file you should automate the process of uploading the file to your university's dedicated AWS bucket. A few notes before we go on:
- You will only have write permissions to your university's folder
- These S3 directories are write-only so any attempts to GET/LIST contents would result in 'Access Denied' Errors.
- We support all standard methods of uploading to AWS S3 that only require PUT access
- We do not support FTP/SFTP due to the required LIST access.
- Region must be set to eu-central-1 for upload to work.
- Note: existing accounts that configured auto-run before 01/07/2023, region can still be set to: eu-west-2.
Automating Your Sync: Step A
We will be using Amazon's Command Line Interface (CLI) tools. This is the best tool for interacting with AWS S3 for automating your upload. If you don't already have python installed you'll need to run the following (more details on installing Python here)
pip install --upgrade --user awscli
If you don't have python, you can install using the bundled installer here
curl "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" -o "awscli-bundle.zip"
unzip awscli-bundle.zip
# with sudo
sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws
# without sudo (assumes ~/bin is in your PATH)
./awscli-bundle/install -b ~/bin/aws
Please contact Handshake's Support team here to receive the AWS credentials for uploading data to Handshake. Unless otherwise instructed by the Handshake team, you should use “eu-central-1" as your region.
Next run the following and enter in your AWS Access Key and Secret Key:
Configuring your AWS Credentials
aws configure
AWS Access Key ID [****************JRTA]:
AWS Secret Access Key [****************RZ7O]:
Default region name [eu-central-1]:
Default output format [None]:
Once you have set up these credentials you can upload your first file using the following syntax:
Uploading your first file
aws s3 cp [/path/your_local_file] s3://handshake-importer-uploads/[your folder]/
[yyyymmdd]_users.csv
Example Upload and Response
aws s3 cp /your/local/dir/test.csv s3://handshake-uk-importer-production-uploads/
importer-production-amaranta-ac-uk/test.csv
upload: to s3://handshake-uk-importer-production-uploads/
importer-production-amaranta-ac-uk/test.csv
The AWS S3 API will respond with the document ID if the file was successfully transferred, otherwise it will respond with an error. You can also check the command exit code to determine it was successful.
If you wish to do a test run, simply send a file and our data team will verify that it is received and ready for production.
Automating Your Sync: Step C (Validate the File)
Login to the importer application to see that your file was accepted by the importer. The importer will check the file for common issues and verify the formatting. If the file does not show up check for these common mistakes:
* The file is not a true CSV: Double check that the file you are trying to upload can be uploaded manually to the importer and processed successfully
* The script you're running isn't successfully uploading the file to your s3 bucket: Double check your script path and ensure it is returning successfully and giving you back the path of the uploaded object
Automating Your Sync: Step D (Schedule the Upload)
After you've validated everything looks good, we recommend using cron to schedule the upload. Pick a weekly, monthly, or semesterly date to do your upload, in general the format is:
SchedulingFormat Example
5 8 * * Sat aws s3 cp users.csv s3://handshake-importer-uploads/
importer-production-hudson_university/`date +"%Y-%m-%d"`_users.csv >/dev/null 2>&1
All articles in this series: