Pantrysoft Data Integrations (SSO, Flat-File Exchange)- Technical Specifications

Learn technical specifics about Pantrysoft's two data integration offerings— SSO and an ERP-derived flat-file exchange.

Brief Overview

Pantrysoft offers two integration services—Single Sign-On (SSO) and an Flat-File Integration—to help manage student authentication and streamline the student registration process. 

SSO Overview

Pantrysoft’s SSO integration is straightforward and designed to work seamlessly with your existing SSO setup. Here’s a brief overview:

• • Authentication Only: Pantrysoft uses SSO purely for authentication purposes. We do not currently offer any additional authorization functionality (e.g. a SAML claim indicating authorization) for the principle after they've been authenticated.
  • No Claims Encryption: While the entire SAML payload is encrypted via TLS 1.3, we do not support encryption of the claims themselves. This ensures that Pantrysoft can properly digest the authentication assertions.
  • Flexible Mapping: We can consume nearly any core data point brought over via SSO. While auth systems typically have access only to core information about the student, we can digest non-essential data points like address info, phone, etc. with no trouble.

Flat-File Integration

Pantrysoft’s Flat-File Integration allows your campus ERP or CRM to directly influence pantry operations by providing nightly updates through a .csv file. Here’s a brief overview:

File Format and Structure: The flat-file must be in .csv, .txt or .dat format and will be derived from student records in your campus' main student information system. This file is typically generated and sent on a job or cron schedule each night.

Core Fields: Certain fields in Pantrysoft are essential and must be represented by specific headers in the .csv file. We provide these headers in a template sent to you during the setup process. Other more custom information sent from these campus systems (such as a custom Registration question like "Student Major") can be included with any header names you choose.

Primary Functions:

• Auto-Fill: Optionally the flat-file can auto-fill custom questions during the student registration or intake process. While students can still modify the information after it has been auto-filled, this feature accelerates the process and helps suggest consistency with campus records.
• Authorization Layer: Optionally after SSO authentication, the flat-file can act as a second and more flexible additional authorization layer after basic SSO authorization. With this feature activated, only students represented in the .csv file with the correct credentials will be allowed to access pantry services.
  
  

SSO Integration Specifics

Technical Process for Setting Up SSO Integration

Integrating your campus’s Single Sign-On (SSO) system with Pantrysoft involves configuring the necessary components to allow students to authenticate using their existing campus credentials. Below is an overview of the steps involved in setting up this integration:

1. Metadata Exchange

• Pantrysoft SP Metadata:
  Pantrysoft operates as the Service Provider (SP) in the SSO process. We’ll provide you with our SP metadata, which you will need to load into your Identity Provider (IdP) system, such as Azure AD or Shibboleth.

• Campus IdP Metadata:
  In return, we’ll need your campus’s IdP metadata. This file contains the necessary configuration details that Pantrysoft will use to authenticate users through your existing SSO infrastructure. 

2. Test Login and Claim Names 

Once we've mutually digested the metadata files into our respective systems, you'll perform a test login at your pantry's online portal url. From there, Pantrysoft staff will map the claims you've sent:

Claim Names (IdP choice except for the email claim):

• • Email. The email attribute is the only required assertion for Pantrysoft, and it must be presented using one of the supported keys (see Appendix A: Reserved Email Claims at the end of this article). While additional attributes such as first name, last name, and student ID are optional, they can enhance the user experience by allowing for auto-filling and other features.
  • Student Id Preferred. We prefer to get a Student Id claim (labeled however you like) via sso for operational purposes. Ensuring every student record has a student id (delivered through the SSO payload) means that pantry staff never has to ask a student for their name, which helps ensure dignity and privacy.
  • Authorization Claims? Pantrysoft does not currently support an additional authorization layer after authentication. Therefore, the feature is focused on ensuring that the authentication process is secure and correctly configured.
  • Other Claims. For all claims but the campus email address, use any label you like. We'll pull the names you choose from your first test login/ SAML response, and use those to map to our system. 

3. Finalizing the SSO Process

After the test-send you'll arrange to script a nightly delivery of the file. After verifying this automatic delivery is up and running, the system is ready for student logins.

• If any issues arise during testing, we will work closely with your IT team to troubleshoot and resolve them promptly.
• For SSO and the flat-file to mutually identify the same student record in Pantrysoft, they must send the same value for the student campus email address.
• Once the SSO integration is live, regular monitoring is recommended to ensure that the authentication process remains smooth. Should any changes occur in your IdP configuration, please notify us so that we can adjust the setup on our end as needed.

SSO FAQ

1. What metadata do we need to exchange?
We will provide you with Pantrysoft’s Service Provider (SP) metadata, which you’ll need to load into your Identity Provider (IdP) system. In return, we’ll need your campus’s IdP metadata to complete the SSO setup on our end.

2. Do we need to (or can we) encrypt the SAML assertions or claims?
No, Pantrysoft does not support the encryption of individual claims. However, the entire SAML payload is encrypted via TLS 1.3 during transmission, ensuring the security of the authentication process.

3. What attributes (claims) are required?
The only mandatory attribute for Pantrysoft is the email address. This must be provided using one of the supported attribute keys. Additional attributes like first name, last name, and student ID are optional but can enhance the user experience.

4. How does Pantrysoft handle the UID (User Identifier)?
We require the UID to be the full email address. Some systems, such as Azure, may only send the email prefix (NetID), which can cause issues. Ensure that the full email address is provided as the UID.

5. Does Pantrysoft support logout requests?
Yes, Pantrysoft supports logout requests upon user logout, if configured. This feature ensures that a public workstation logged out of Pantrysoft also terminates the session with the campus authentication service, preventing subsequent users from accessing the previous session.

6. How does Pantrysoft create and manage user records with SSO?
When a user logs in via SSO, Pantrysoft will either match the email to an existing user (customer) record or create a new record if no match is found. New records created this way are flagged as isSsoOnly in our system.

7. What happens if the email attribute is passed with an unsupported key?
If the email attribute is passed using an unsupported key, Pantrysoft’s system may not recognize it, leading to authentication failures. We provide a list of supported keys that should be used to avoid this issue.

8. How do we perform a test login?
After the metadata has been exchanged and the setup is complete, you can perform a test login by accessing the Pantrysoft Client Portal. This will help verify that the SSO integration is functioning correctly.

9. What happens if the SSO setup encounters issues during testing?
If any issues arise during the testing phase, Pantrysoft will work closely with your IT team to troubleshoot and resolve the problem promptly, ensuring a smooth and secure integration.

10. Do you support IdP-initiated logins? Currently, no. On your own web pages and materials, you'll have to embed a link to the URL above rather than truly starting the login process from your own login page. Our current workflow relies upon a session created with our server as the principal clicks Login on the Pantrysoft login page.

Flat-File Integration Specifics

Technical Process for Setting Up Flat File/ ERP Integration

Integrating your campus ERP system with Pantrysoft involves setting up a nightly flat-file transfer process via Amazon CLI to a credentialed S3 Bucket. This will automatically update student data nightly (our ingestion routine occurs at 3am Mountain Time nightly). Appendix B: AWS CLI Setup Instructions at the bottom of the article provide detailed instructions for setting up that tool and sending a file, but this section details the basic process: 

1. File Preparation

• CSV Format: The flat-file must be in .csv format, encoded as UTF-8. This file will be derived from records in your campus ERP system and should include all relevant student data (as discussed with the pantry operations people in our initial meeting).
• File Name: Call the file anything you like, but it cannot contain concatenated dynamic data points like date or version. For instance, yourcampus_pantrysoft.csv is good, yourcampus_pantrysoft_2024_10_07.csv (where a differently named filename is delivered nightly) is not.
• Required Fields. If you are using the flat-file in conjunction with SSO, email_address is the primary key and is required. For flat-file-only integration setups, account_number serves as the primary key, although we highly encourage you to send email_address as well.
• Core Fields in the Template: Certain core fields in Pantrysoft, such as email_address , account_number, phone_number, etc. must be represented by specific headers. We will provide these headers in a template to ensure compatibility with Pantrysoft’s system.
• Custom Fields: You can include additional (custom) fields in the file with any header names you choose. These fields can be used to auto-fill custom questions during the registration process.

2. Setting Up the File Transfer

AWS CLI Overview:
We use Amazon’s S3 service to facilitate the secure transfer of files. Your campus IT team will need to configure the AWS Command Line Interface (CLI) tool on the server that will manage these transfers. This setup will allow for the automatic nightly delivery of your flat-file (.csv) with Pantrysoft’s S3 bucket.

Configuration Process:

• After setting up the AWS CLI, you’ll configure it with the credentials specific to the S3 bucket provided by Pantrysoft via secure file transfer. We’ll guide you through this process during the setup phase, ensuring that everything is correctly configured for your environment.
• Once the CLI is set up, you’ll schedule a cron job (or equivalent task scheduler) to automate the nightly transfer of your flat-file. The file should be uploaded to the S3 bucket before 2 AM Mountain Time.

3. Test File Send

Send an initial file to the S3 bucket manually to ensure the connection and the quality of the file:

• • Start by sending a test file to the production S3 bucket. Inform Pantrysoft once the file is sent, so we can validate the setup on our end.
  • We will check that the file headers conform to the template, and that the values are properly formatted to be processed for the go-live event. 

4. Verifying the File and its Contents

There are three major points to verify in this process: File contents, file content compatibility with Pantrysoft, and the general success of the latest upload. Here's how you perform these verifications:

• Success of your latest upload. After performing an upload, use the command aws s3 ls s3://your-bucket-name/ --recursive to verify that the date and time of the last upload matches the last
• File Contents. If you perform the step immediately above, this ensures that the file on your drive is the one in the bucket. From there, just check your local copy of the file you just uploaded.
• File Content Compatibility. Pantrysoft offers a manual version of the upload tool that you can use inside the app to test the compatibility of your file (and incidentally test the Eligibility function if this setting is turned on). Ask us for an admin login, then once you're logged in to your Pantrysoft installation go to Setup->Eligible Client CSV Upload. After uploading the file, the screen will look as it does below, mapping the fields it can identify.

5. Activating the Integration (Regular File ingestion at 3am Mountain)

• Final Setup:

  • Once your script is running and the cron job is regularly sending files to the S3 bucket, you'll notify Pantrysoft of the static file name (do not append dates to the filename). This allows us to configure our system to recognize and process the file nightly in time for the pantry's go-live.

• Ongoing Maintenance:

  • The file sent each night will overwrite the previous one if it has the same name. This allows for daily updates to the student data, such as adding or removing students based on their current enrollment status.
  • At any time, check the indexing of the S3 bucket with the AWS CLI command aws s3 ls s3://your-bucket-name/ --recursive to list the files and determine the last-updated.

Flat-File FAQ

1. Are we sending files to a Pantrysoft test environment?
No, all files— including test files— should be sent to the same S3 bucket that will be used in production. There is no separate test environment for these transfers.

2. How do we activate the file transfer once our script and nightly file-send job (i.e. cron) are set up?
The final step is to notify us once your script is running and the cron job is sending files to the bucket. Please provide the filename so we can configure Pantrysoft to recognize and process it. The file will begin influencing pantry operations the following day.

3. Will the file transfer be executed via SFTP?
No, Pantrysoft uses Amazon’s proprietary S3 protocol rather than SFTP. While some other applications, such as FileZilla, can support sending to an S3 bucket, the primary method is through the AWS CLI tool.

4. What time should the .csv file be sent each night?
Files should be uploaded before 2 AM Mountain Time to ensure they are processed on time.

5. What documentation is available for the file transfer process?
Besides the information contained in this article, we provide three short text files to guide you through the process: a CSV Template, a Data Specification file detailing each field, and Setup Instructions that explain how to configure the file transfer using various software and protocols.

6. What is the ideal file format?
The preferred format is a UTF-8 encoded .csv. A .txt or .dat file will also work as long as the contents are comma-separated values.

7. Can we name the file anything we like? Any static name is fine; do not add dynamic aspects to the file name such as a date or other changing identifier.

8. What happens if we upload a file with the same name as one already in the bucket?
The existing file will be overwritten. This allows you to update the file’s contents nightly (e.g., removing a student who has dropped out for the semester) without giving you delete permissions.

9. Can we omit fields from the CSV template?
Yes, you can omit any fields that are not relevant to your integration. Only include the columns from the template that you want to use.

10. Can we omit values in a column?
Yes, blank or null values are acceptable. However, missing values in the email_address and account_number field (student id) may cause issues. If a record is missing an email address, Pantrysoft will attempt to match the student by account_number. If no match is found, that student will not be represented by the autofill or eligibility features. This is true as well if the account_number field is missing and you're only using the flat-file integration.

11. What happens if we upload a file with a different name than the one expected?
Pantrysoft will ignore the file, and it will remain in the bucket indefinitely until we purge it from our side.

12. What happens when a student hits the "Eligibility wall" in the Client Portal?
If a student is not on the eligibility list, they will be redirected to the login page with a message stating, "not eligible at this time."

Appendix A: Reserved Email Claims:

Appendix B: AWS CLI Setup Instructions

Install the Tool

If you are using a debian-based linux system, run the following command to install the tool:
sudo apt install awscli  

If not using debian-based linux use your appropriate package install for awscli. 

NOTE: We suggest running the rest of these commands with the user the cron will be attached to.

Configure the Tool

Perform the following command to create a profile:

aws configure --profile BUCKETNAME

(replace BUCKETNAME with the bucket name we provide you)

Provide the following as prompted:

• Enter the credential keys (provided to you earlier in a secure file transfer).
• Default region name: us-west-2.
• Default output format: json (really not necessary for our purposes, can leave at none too).

Test Connection using a test file with "Dryrun"

The following "dryrun" mode will report details about the send you would have performed, had the --dryrun flag not been present. The --dryrun flag prevents an actual send, and is good for just testing the connection and verifying the file path.

Perform the following command to perform a "dry run" to test the viability of the connection:

aws s3 sync /path/to/the/directory/with/your/files/to/upload s3://BUCKETNAME --dryrun --profile BUCKETNAME  

Sync/Upload (Manual/ Test Send *and* CRON)

Use the following command to perform an actual test-deposit, and then inform us so we can verify it on our end. 

aws s3 sync /path/to/the/directory/with/your/files/to/upload s3://BUCKETNAME --profile BUCKETNAME

Once you're ready, this is also the command you'll run via the CRON

You could also use the full path to the aws binary. The default on an ubuntu server is /usr/bin/aws

Tell us to verify the Send

Now you're ready to let us know we've got a test file in the bucket, and to verify its presence and contents!