This page was created to contain general notes/documentation for the CAS API and Slate integration that is CAS-agnostic. It is under construction.
Common Terms and Definitions
Term | Definition |
|---|---|
CAS association | The group that owns and manages the CAS (e.g., APTA for PTCAS, ASPPH for SOPHAS, etc.) |
Organization ID | Associated with the school/institution (e.g., Tufts University). Indicates the institution’s entity within the CAS/cycle. A unique ID used in setting up API accounts and subscriptions. Remains the same across cycles. Tufts has multiple Organization IDs; Vet is different from CASPA, and they are different from each different location PT has. |
Application Form ID | Associated with the CAS/cycle (e.g., the PTCAS application for 23-24), represents the configurations made by the CAS association for their centralized application for that cycle, a unique ID used in setting up API accounts and subscriptions. Each year/cycle it will change for the CAS, but within that cycle it is the same for any program within that CAS (i.e., the individual DPT programs use the same application form ID because it is for PTCAS and not the program itself). |
Program ID | Associated with each program within the organization. Some CAS applications will only have one program (e.g., CASPA) but others will have multiple (e.g. SOPHAS). Used to generate the CAS/Liaison Application ID (the unique identifier used for matching data sent from the CAS to Slate on the application, vs. the person) which is key for both the data and document integrations. In the API this is stored in the progMate.progSele0.programID field, in WebAdMIT it is found under Designation > Program Identifier. |
Subscription ID | Each individual subscription--the one for documents, the one for in-progress apps, etc-- has a unique identifier. Any time a new subscription is started (or re-started after being deleted), a new subscription ID would be generated. This ID is required to do a replay. |
Prelaunch is a "staging" environment that allows you to configure programs for the new cycle without impacting the current cycle. | |
The "live environment" is where you perform your applicant review processes. | |
CAS Applicant ID | Unique to the person; consistent across cycles and CAS. Note that Liaison does not generate a single application ID; best practice is to concatenate the Applicant ID with the Program ID (progMate.progSele0.programId) before import. |
API Configurations
CAS API Account (Liaison)
To configure subscriptions and gain access to the CAS API data Liaison requires a “CAS API Account.” Access to a specific CAS environment (production or prelaunch) is granted to this account.
An Institution Manager (IM) for each CAS must request either a new account or that access be given to an existing account for their CAS. However, the CAS API Account itself can have a different “owner” than the IM. If the owner will be different than the IM, the owner will need to have access to WebAdMIT prelaunch and/or production in order to be given access via the CAS API Account to those environments.
There can be multiple IMs for any instance.
Each CAS will have an organization code to identify it. So for example, PTCAS 23-24 for PHX has one organization ID, and PTCAS 23-24 for SEA has a different organization ID.
A separate account is required for production vs. prelaunch (which is a test environment available before the cycle opens), but it is possible to have multiple CAS and cycles under a single account.
Once access for a CAS/organization is added to the account, it will “roll over” each year when the new cycle is added, so this process only needs to happen once per CAS/organization.
Timing for access to each cycle’s prelaunch environment and production environment will depend on when it is “opened” as part of the cycle (see Cycle Turnover Process). Typically, the Prelaunch API becomes available when the Configuration Portal opens, and Production API becomes available when applicants can select particular schools.
Sample Tickets
Send to apisupport@liaisonedu.com.
CAS API Accounts Managed by TTS Slate Team
Username | Environment | CAS (Org) and Cycles |
|---|---|---|
TuftsUni | Production | SOPHAS, PTCAS |
TuftsUniPre | Prelaunch | PTCAS, VMCAS* |
TuftsVet | Production | VMCAS |
*Yes, this doesn’t make any sense, but when requesting access to Prelaunch VMCAS, I did not specify that it should be attached to TuftsVet, and it works, since it is just a username/password combo, but it is weird.
CAS/Liaison Service Account Configurations (Slate)
To enable automated delivery of CAS application data through the API, Slate requires each instance to have a “CAS/Liaison Service Account” (functionally a “user”) which is assigned a role that allows SFTP access. This “user” is what holds the permissions, allowed networks, and other security settings to allow the data to be transferred from the CAS environment into the Slate environment via SFTP.
The CAS/Liaison Service account is pre-configured in Slate and available from the Slate Template Library (STL). Instructions for adding it are in the Slate KB.
Password
Copy and save the password prior to saving changes, because once saved, the password will not be visible. You will need the password to configure the CAS API subscription within the Postman endpoints.
Allowed Networks
In December 2023 - January 2024, Liaison migrated their CAS systems to AWS. Initially, Liaison included in their documentation instructions to whitelist thousands of possible IP addresses and CIDR subnets in the allowed networks for the CAS/Liaison Service Account in Slate. Concerns about whitelisting so many IP addresses were raised; in addition, adding the suggested IP addresses (over 7K) didn’t solve issues with file delivery to the SFTP for either WebAdMIT delivered files or the CAS API.
Liaison instructed, via two separate emails, that the following IP addresses be added to the allowed networks in order to ensure successful file delivery. They have also indicated that the “templated” CAS/Liaison Service account was updated by Slate/Technolutions, however if the account had already been added in an instance (was now custom) it needs to be updated manually.
CAS API
3.221.151.218 35.174.21.29 100.24.188.151 35.168.84.72 44.198.99.254 54.221.197.67
WebAdMIT Destination Manager
AWS CAS Production 34.226.75.67 44.212.160.251 52.45.20.177 AWS CAS Prelaunch 52.1.245.183 54.157.13.223 54.174.7.196
February 2024 - Forum discussion post about this list of all AWS IP addresses ever and how it is ridiculous; eventually this is posted:
12.130.14.3, 35.196.40.74, 35.237.218.144, 35.237.169.192, 34.74.5.60, 35.185.121.56, 34.74.128.171, 104.196.102.47, 3.221.151.218, 35.174.21.29, 100.24.188.151, 35.168.84.72, 44.198.99.254, 54.221.197.67, 44.196.149.171, 18.211.99.194, 34.231.157.239, 52.71.217.11, 54.161.89.200, 54.205.199.53
Sneaky Method for Identifing IP Addresses
Slate released new SFTP features in mid-2024 that added an SFTP Log to user accounts. Send test files using the appropriate service account and they will fail. Check the SFTP Log for the service account to view the IP address attempted and add that IP address to the allowed networks.
IP addresses will change and fluctuate, but this seems to work over adding a ridiculous list (that isn’t possible anyway).
How to Add Allowed Networks
The instruction to use CIDR subnets (e.g., 123.45.67.0/24) mean literally to use the .0/24 characters, even if the number you see in your machine’s individual IP address is something outside of that range. Setting this means there is no waiting when using these account credentials with Filezilla or Postman
Allowed Networks (Deprecated January 2024)
CAS API SFTP Login Frequency
In May 2024, Technolutions contacted instances with SFTP service accounts that were attempting logins to the Slate SFTP more frequently than the recommended rate (no more than 12 connection attempts per hour, or approximately one every 5 minutes).
The CAS API is configured to make a SFTP login attempt each time it delivers a single file, either for data or a document. The CAS API will also attempt additional connections if there is an initial failure until it is able to successfully deliver the file.
Therefore, it is one SFTP login per applicant data file and PDF document, per business event, as those triggers occur throughout the cycle. If a school is getting a file at every business event stage, then each applicant represents at least 4+ SFTP logins for the application data alone, and more when you include documents (again, one login per document... transcript, evaluation, etc.). Multiplied over the entire applicant pool, then over however many CAS integrations might be in a single instance, it is starting to make sense that Slate is seeing such frequent login attempts from the CAS account.
Per Liaision, "The only way to really modify the frequency of API delivery, would be to modify your usage of business events in your active subscriptions since those are always passively sending files when the events are triggered. For example, using more business events in a subscription will trigger the API to send more information/files; whereas using fewer business events in the subscription will cause the API to trigger less, sending less information/files."
When determining what business event subscriptions to use for the CAS integration, consider the frequency of SFTP connection attempts that will be required. Do not set up extraneous subscriptions for files that are unnecessary to the business process in Slate.
Cycle Turnover Process
Each CAS has an annual cycle which is based off of the application deadlines/timeline for the programs using it. Each cycle includes:
Configuration Portal/Prelaunch environment launch/open - institutions/programs are given access to set up the application configurations they can customize (questions, deadlines, documents, etc.). Level of customization is dependent on the CAS association rules/choices.
Configuration Portal “closes” - institutions/programs have finalized their custom configurations and submitted to the CAS association for “approval.”
Application Portal launch/open - the school-specific application becomes live/available to prospective students to access. Typically a few weeks/months after configuration portal has closed; during this time the CAS association reviews configurations and approves the configurations, and those final configurations are pushed from prelaunch to production.
Applicant data available in WebAdMIT - the last step is for the CAS to generate a new WebAdMIT “environment” for the cycle and then to push application data to it. Typically, the WebAdMIT “environment” will become available the same day the application portal launches, and application data will be sent the next day.
Automated Notifications from Liaison
When Liaison “promotes or rolls over” (i.e., opens) the new cycle for either the production or the prelaunch environment, access to that environment will be added for any CAS API account which had access during the previous cycle (it will “roll over”) and there is nothing the institution needs to do.
Automatic notifications will go to the user associated with the CAS API user account:
Notification of a user update(s), which is updating the CAS API user account to include access to the new cycle (includes a new Application Form ID).
Notification of subscription update(s), which is indicating that a subscription which existed in the previous cycle has been created/copied over to the new cycle (includes a new Subscription ID).
Data will begin flowing via these subscriptions to Slate without any further human intervention.
However, in order to do a replay, get lists of applications, or the subscription details or any other interaction with the API, the Postman environment needs to be updated.
Updating Postman Environment
The subscription update emails from Liaison contain the Application Form ID, which is what changes from year to year. It needs to be added to Postman. When copying the environment over from the previous year, the App Form ID must be added to the current value column.
Troubleshooting Connection Issues
Useful Forum Posts w/Issues:
https://knowledge.technolutions.com/hc/en-us/community/posts/20008552350875-SFTP-Issues
Using Postman and Endpoints
CAS Resources
Obtaining an individual application file
The following instructions use the CAS → Slate V5 Postman collection provided by Liaison. At minimum you need the name of the applicant, but it is also good to have the CAS Applicant ID to ensure the correct application data is identified.
The application data you will get back using this process is “live” as of when the request is sent. It is not dependent on a business event and is not “retroactive.” If the exact file sent via a subscription is required, you should do a replay and not use this process.
Select the environment for the CAS application you are trying to access, and send a call for an authorization token (POST Call Auth Token).
Next send a call to the GET applications list. The response will contain details for every application in the CAS and cycle (application form ID) and the school/college/university (organization) established in your environment. Use the search tool in Postman to search for the name or CAS Applicant ID of the applicant you are trying to find; make note of the application ID.
Open the GET individual application endpoint. Paste the application ID into the value under the “Params > Path Variables” section. Next, in the Headers menu make sure that Accept is set to text/csv (default is application/json, changing this ensures a text file is returned). Save the endpoint and then send it.
Save the response locally.
Open Excel, use “Open” to find the file that you saved in the previous step. Make sure to change the type of file you are looking for to “All Files.”
Excel may give a warning, but click yes to open anyway. Excel will then run through the Text Import Wizard. Select Delimited for Step 1, then “comma” in Step 2, and then finish. The workbook will open; save as a CSV file.
Go to Slate to the Source Format configured to import this type of file for the API.
Deciding to use the CAS API vs. WebAdMIT API
Identifying and Interpreting Data Fields
CAS API Data
Program Configuration Data
Source Format Configurations
Slate provides pre-built templates for the necessary source formats needed to configure record and application creation and updating as well as document processing.
Data Source Formats
In Progress
Per the Liaison API Support team 1/12/2024: Unfortunately, applicants have the ability to decide whether or not their information gets released to schools before their submission. If an applicant selects "No" for this release, then they will not show as in progress in WebADMIT and will not trigger that application.selected.file business event.
Application
Resources
CAS Source Format Mapping (from Liaison) is Liaison’s
Documents
The document source format provided by Slate for the CAS API integration is “special” and doesn’t function the way other source formats do:
There should only be one Document source format no matter how many CAS applications are being integrated; unlike the other source formats, the documents source format should not be copied and duplicated. It can be used for all Liaision documents.
The source format appears to look at the filename of the PDF document that is sent from the CAS API to match with person and application records. For this reason, it is important not to change the file name as written in the endpoints provided by Liaison. (The exception is the text between the brackets to replace with the name of the CAS, e.g. PTCAS or CASPA).
Configurations
To set up the documents source format you only need to configure the Prompt Value Mappings (there are no field value mappings or other source format components to edit). Each prompt is the document type or subtype from Liaision and should be matched to whatever material type within Slate works for the school’s processes.
Document Subtypes
There are two kinds of documents for the CAS API; those that are organization-level (types) and those that are program-level (subtypes).
Organization level documents include transcripts, foreign credential evaluations, and any material required by the CAS (e.g., license or certification documents).
They should be considered “person-scoped” in Slate terminology, as they are part of the student’s profile in the CAS which is sent to all programs where they apply.
Program level documents include things required by our specific program (as configured in the configuration portal), and might include a resume, personal statment, etc.
Evaluations are also considered program-level, as they are specific to an application and some CASs do not require them (but allow a program to require them).
They should be considered application-scoped (or program-scoped) in Slate terminology, as they are specific to that application program/start-term/etc.
To determine what program needs to be mapped, review the configuration portal for the document types required by the program (available in the export file from the configuration portal). Then obtain the document subtype file from the API to match the document type to the document subtype “code.”
Instructions for identifying program-level document subtypes and the organization-level document types are available from Liaison here: https://help.liaisonedu.com/Integration/CAS_API/CAS_Slate_Integration/Working_with_Source_Formats_and_Mapping/06_Mapping_Your_Document_Source_Format
This table is a summary of the document types that have been used at Tufts in our API integrations.
Document Type/SubType | Response Level | Business Event | Description | CAS |
|---|---|---|---|---|
fullAppPDF | program | A comprehensive generated PDF including all information provided by the applicant in filling out the application. (option to remove race/ethnicity) | VMCAS | |
evaluation | program |
| A letter of recommendation. | PTCAS, SOPHAS, CASPA, VMCAS |
transcriptunofficial | organization |
| An unofficial transcript uploaded by the applicant. | PTCAS, SOPHAS, CASPA |
transcriptofficial | organization |
| An official transcript delivered directly to Liaison by the issuing institution. | PTCAS, SOPHAS, CASPA, VMCAS |
vendorTranscriptEval | organization |
| An official foreign transcript evaluation delivered directly to Liaison by the evaluation agency (WES, ECE). | PTCAS, SOPHAS, CASPA, VMCAS |
cv-resume |
| Resume/CV | CASPA | |
personal-statement |
| Essay/personal statement | ||
statement-of-purpose-and-objectives |
| Essay/personal statement | SOPHAS | |
other |
| Other misc. documents (optional for the applicant) | SOPHAS | |
clinical-professional | program |
| CASPA | |
unofficial-transcript | WebAdMIT | CAS Electronic Transcript (formatted like full app PDF but only containing the GPA Overview and sub-panels from WebAdMIT) | PTCAS | |
FullAppPDF | WebAdMIT | Custom PDF from WebAdMIT containing specific panels and sub-panels w/o any other documents from the application | SOPHAS, PTCAS |
FullAppPDF
The FullAppPDF document type available from the CAS API process contains the following (confirmed 3/15/2024):
Biographic information (use PDFtype=reviewer to remove race/ethnicity)
Academic History
Supporting Information
Custom Questions (CAS)
Custom Questions (Program/Designation)
Prerequisite Courses (if available)
Evaluations
Applicant Uploaded Documents (CAS/Application Level)
Applicant Uploaded Documents (Program Level)
This document type is not customizable and is only available as-delivered. Because it does not break up documents into separate PDFs, it is not ideal for most school processes. If using a full application PDF exported out Liaison to review applications in the Reader, it may be preferable to obtain a more custom full application PDF from WebAdMIT.
0 Comments