Troubleshooting Your Integration

CAS API Subscriptions

The CAS API is the Liaison tool that enables the automated, event-driven delivery of CAS application data and documents to Slate for import. Event-driven delivery is established by creating subscriptions that will deliver payloads formatted in a user-specified format to a user-specified destination in response to user-specified business events. Establishing CAS API subscriptions involves interacting with the API from the command line. Once established, a CAS API subscription may run into trouble attempting to deliver payloads to the specified destination. Common issues encountered with the CAS API are listed below. For more guidance on establishing a CAS API subscription to deliver data and documents to Slate, review our Setting Up the CAS API documentation.

Delivery Failures

Once established, a CAS API subscription may run into trouble attempting to deliver payloads to the specified destination. The most common types of CAS API subscription delivery errors are listed below, along with the cause of the delivery error and the recommended solution to enable the CAS API to successfully deliver files to the user-specified destination.

In the event of a delivery failure, the CAS API will do two things:

Delivery failure email notifications. The email address attached to the subscription will receive an email notification for each payload that the CAS API fails to deliver. The email notification will include some details about the payload it was trying to deliver, the event that triggered the delivery, the destination it was trying to deliver to, and the nature of the failure itself. It is a best practice to review these notifications and double-check your destination to ensure it is properly configured to receive payloads from the CAS API.
CAS API automatic retry. Whenever the CAS API fails to deliver a payload, the CAS API's automatic retry feature kicks in. If the CAS API can't deliver to the user-specified destination, it waits a few seconds and then tries again. If it fails again, it will wait a little longer and then tries another time. The CAS API will repeatedly retry in this manner, waiting longer each time for a period of about 3.5 days. In other words, the CAS API won't give up until it's tried its hardest to deliver the payload. With each retry, the CAS API will send an additional email notification if the delivery fails. There should be a sufficient warning when a destination becomes unreachable for you to resolve the issue with the destination so that the CAS API can successfully deliver application data and documents. Experience has shown that, in most cases, delivery failures are intermittent, and the CAS API successfully delivers payloads on a retry attempt.

Error Message	Cause	Solution
No such file (see screenshot below)	The target folder doesn't exist on the SFTP.	One of the following: Create the target folder. This target folder should exactly match the location and name that is specified in the CAS API subscription. Delete the existing CAS API subscription and create a new one that is configured to deliver files to the correct Slate SFTP folder. For example, if your Slate SFTP folder is “/incoming/liaison/businesscas/”, your CAS API subscription’s “sftpBaseDirectory” value should be “/incoming/liaison/businesscas/”. For more information, see Locating SFTP Folders.

Error Message

Cause

Solution

No such file

(see screenshot below)

The target folder doesn't exist on the SFTP.

One of the following:

Create the target folder. This target folder should exactly match the location and name that is specified in the CAS API subscription.
Delete the existing CAS API subscription and create a new one that is configured to deliver files to the correct Slate SFTP folder. For example, if your Slate SFTP folder is “/incoming/liaison/businesscas/”, your CAS API subscription’s “sftpBaseDirectory” value should be “/incoming/liaison/businesscas/”.

For more information, see Locating SFTP Folders.

Error Message	Cause	Solution
Auth fail (see screenshot below)	The Slate service account credentials (username, password) entered by the user in the CAS API subscription are not correct.	Each of the following: Confirm the Slate SFTP credentials. Delete the existing CAS API subscription. Recreate the subscription with the correct credentials. For more information, see Creating a CAS API Subscription.

Error Message

Cause

Solution

Auth fail

(see screenshot below)

The Slate service account credentials (username, password) entered by the user in the CAS API subscription are not correct.

Each of the following:

Confirm the Slate SFTP credentials.
Delete the existing CAS API subscription.
Recreate the subscription with the correct credentials.

For more information, see Creating a CAS API Subscription.

Error Message	Cause	Solution
Connection refused (see screenshot below)	Too many files were sent to the Slate SFTP at once and the Slate SFTP refused one or more.	No action is needed. The CAS API automatically retries delivery after waiting for a short period. The CAS API will keep retrying the delivery, waiting longer between each try, until it is successful or ~3.5 days have elapsed.

Error Message

Cause

Solution

Connection refused

(see screenshot below)

Too many files were sent to the Slate SFTP at once and the Slate SFTP refused one or more.

No action is needed.

The CAS API automatically retries delivery after waiting for a short period.
The CAS API will keep retrying the delivery, waiting longer between each try, until it is successful or ~3.5 days have elapsed.

Error Message	Cause	Solution
[com.jcraft.jsch.JSchException: timeout: socket is not established] (see screenshot below)	Too many files were sent to the Slate SFTP at once and the Slate SFTP refused one or more.	No action is needed. The CAS API automatically retries delivery after waiting for a short period. The CAS API will keep retrying the delivery, waiting longer between each try, until it is successful or ~3.5 days have elapsed.

Error Message

Cause

Solution

[com.jcraft.jsch.JSchException: timeout: socket is not established]

(see screenshot below)

Too many files were sent to the Slate SFTP at once and the Slate SFTP refused one or more.

No action is needed.

The CAS API automatically retries delivery after waiting for a short period.
The CAS API will keep retrying the delivery, waiting longer between each try, until it is successful or ~3.5 days have elapsed.

Error Message	Cause	Solution
[4: Access Denied] (see screenshot below)	The path restriction settings on the Slate service account’s SFTP access prevented the CAS API from successfully delivering files to the Slate SFTP.	Remove the path restriction settings on the Slate service account’s SFTP access

Error Message

Cause

Solution

[4: Access Denied]

(see screenshot below)

The path restriction settings on the Slate service account’s SFTP access prevented the CAS API from successfully delivering files to the Slate SFTP.

Remove the path restriction settings on the Slate service account’s SFTP access

Access Denied error

Confirming Successful Delivery in Slate

It’s possible to confirm directly within Slate if a payload from a failed delivery has been successfully delivered in a subsequent delivery attempt. The CAS API delivery error email includes identifiers that are also present in the filenames of the delivered payloads. You can use these identifiers to search for the delivered payload using Slate’s SFTP Explorer or Source Format Source history. Follow these steps:

Determine the identifiers based on the type of payload. For the standard subscriptions, the following file naming conventions are in place:
- Application data: “<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>”
- Full Application PDF document: “<casApplicantId>_<programId>_fullAppPDF__<applicationId>”
- CAS-level applicant-uploaded document: “<casApplicantId>__<documentSubType>__<fileId>”
- Program-level applicant-uploaded document: “<casApplicantId>_<programId>_<documentSubType>__<fileId>”
- Letter of recommendation document: “<casApplicantId>_<programId>_<docType>__<fileId>”
- Transcript document: “<casApplicantId>__<docType><transcriptType>_<collegeAttendedId>_<fileId>”
- Official foreign transcript evaluation document: “<casApplicantId>__<docType>_<collegeAttendedId>_<fileId>”
Collect those identifiers from the CAS API delivery failure email.
If the file was sent recently, search for the file in Slate’s SFTP Explorer. To do so:
1. Navigate to the appropriate directory for incoming CAS payloads
2. Use the search field and search for the identifiers from the email
Search for the file in Source Format’s Source history. To do so:
1. Navigate to the appropriate Source Format.
2. Use the search field in the list of Sources and search for the identifiers from the email.
  
  Important: The Source search uses exact matching – so a partial string search won’t work. You’ll have to recreate the filename exactly to effectively search for it in the Source history (e.g., “BusinessCAS _app_12345_98765…”).

Unauthorized Error

Establishing CAS API subscriptions involves interacting with the API from the command line. The CAS API uses modern authentication and authorization standards to ensure that users can only access data they’re authorized to access and perform actions they’re authorized to perform. There are several possible causes for a user to receive an “unauthorized error” message when interacting with the CAS API.

Error Message	Possible Causes	Solution
Unauthorized	Expired auth token sent in the "Authorization" header. CAS API auth tokens expire after one hour.	Retrieve a new auth token by calling the POST /v1/auth/token endpoint (https://api.liaisonedu.com/reference...ecurity/signIn). Ensure that the auth token returned by that call is passed in subsequent calls to other endpoints as a header with the key “Authorization”.
Unauthorized	User account isn't authorized to access the targeted IDs (applicationFormId, organizationId, or programId). CAS API account access is provisioned at certain scopes and for specific combinations of IDs. IDs are different between environments: an organization will likely have a different organizationId in prelaunch than in production.	Retrieve the IDs to which the user account has authorized access by calling the GET /v1/accounts/info endpoint (https://api.liaisonedu.com/reference...etAccountsInfo). Review the original request to ensure that the target IDs (applicationFormId, organizationId, or programId) are among those to which the user account has authorized access.
Unauthorized	User account isn't authorized to access that scope of request. CAS API endpoints are scoped by applicationForm, organization, and program. CAS API accounts are provisioned at certain scopes. An organization-level user may not interact with an applicationForm-scoped endpoint (one that only specifies the applicationForm). A program-level user may not interact with applicationForm-scoped or organization-scoped endpoints, and may only interact with program-scoped endpoints (where applicationFormId, organizationId, and programId are all specified).	Retrieve the user account information by calling the GET /v1/accounts/info endpoint (https://api.liaisonedu.com/reference...etAccountsInfo). The “userLevel” value in the response to that call indicates what scopes of data the user account is authorized to access. A user account with “association” level access will be able to make a call to any endpoint at any scope. A user account with “institution” or “organization” level access can make calls to endpoints that specify an organization ID in the url string (e.g. GET /v1/applicationForms/{applicationFormId}/organizations/{organizationId}/programs), but cannot make calls to endpoints that only specify an application form ID (e.g. GET /v1/applicationForms/{applicationFormId}/programs). A user account with “program” level access can make calls to endpoints that specify a program ID in the url string (e.g. GET /v1/applicationForms/{applicationFormId}/organizations/{organizationId}/programs/{programId}), but cannot make calls to endpoints that only specify an application form ID (e.g. GET /v1/applicationForms/{applicationFormId}/programs) or an application form ID and an organization ID (e.g. GET /v1/applicationForms/{applicationFormId}/organizations/{organizationId}/programs).

Destination Health Check Error

When you post a subscription through the CAS API, the API will send an empty, auto-generated test file to the destination system before the subscription is created to confirm that the destination system is correctly set up (i.e., a health check). If you receive the following error: "Error - the connection test failed. Please verify the connection parameters and the path template," an adjustment needs to be made.

Verify the following:

Your credentials (Slate service account username and password) are correct in the subscription.
The target folder exists in the SFTP Explorer. For example, if your Slate SFTP folder is “/incoming/liaison/businesscas/”, your CAS API subscription’s “sftpBaseDirectory” value should be “/incoming/liaison/businesscas/”.
Path restrictions on the Slate service account are correctly adjusted or removed.

Data Load

Once the CAS API delivers application data to Slate, additional steps are required to configure how that data will be imported into Slate. See Slate’s Knowledge Base for more information. Some common issues that users have encountered are listed below, along with recommended troubleshooting steps that can be followed to identify and resolve the issue.

Issue	Troubleshooting Steps
Application records aren't being created	Confirm that the CAS API subscriptions are successfully delivering files to the Slate SFTP. Confirm that application events have been triggered in the CAS Applicant Portal in the appropriate environment to cause the delivery of files to the Slate SFTP. Confirm that the Source Format has Remap Active set to Active. Confirm that the Source Format has an Import Path/Mask setting established that will retrieve files from the Slate SFTP. Confirm that App: Round is mapped. Application records won't be created in Slate without this mapping. Review any pre-mapped fields that have been unmapped. Specifically, confirm that the mappings to the Slate-delivered custom fields called CAS/Liaison Application ID and CAS/Liaison Person ID have not been removed.
Incoming records are overwriting each other	Double-check that the CAS/Liaison Person ID and CAS/Liaison Application ID fields are mapped. These fields are pre-mapped in the standard Source Format. Review your static value round mappings to confirm that incoming application data will behave as you intend. Confirm that Slate's External ID field isn't mapped to the same source field as the CAS/Liaison Person ID (casApplicantId).
Not all incoming data is loading into Slate	Confirm that all fields are mapped. Data in fields that aren't mapped won't be loaded. Confirm that all incoming values are mapped. Unmapped values won't be loaded to Prompt-type fields in Slate. Double-check the Safe/Unsafe settings on the Source Format. Safe Source Formats won't overwrite existing person-scoped data. Review the Slate documentation for more information.

Issue

Troubleshooting Steps

Application records aren't being created

Confirm that the CAS API subscriptions are successfully delivering files to the Slate SFTP.
Confirm that application events have been triggered in the CAS Applicant Portal in the appropriate environment to cause the delivery of files to the Slate SFTP.
Confirm that the Source Format has Remap Active set to Active.
Confirm that the Source Format has an Import Path/Mask setting established that will retrieve files from the Slate SFTP.
Confirm that App: Round is mapped. Application records won't be created in Slate without this mapping.
Review any pre-mapped fields that have been unmapped. Specifically, confirm that the mappings to the Slate-delivered custom fields called CAS/Liaison Application ID and CAS/Liaison Person ID have not been removed.

Incoming records are overwriting each other

Double-check that the CAS/Liaison Person ID and CAS/Liaison Application ID fields are mapped. These fields are pre-mapped in the standard Source Format.
Review your static value round mappings to confirm that incoming application data will behave as you intend.
Confirm that Slate's External ID field isn't mapped to the same source field as the CAS/Liaison Person ID (casApplicantId).

Not all incoming data is loading into Slate

Confirm that all fields are mapped. Data in fields that aren't mapped won't be loaded.
Confirm that all incoming values are mapped. Unmapped values won't be loaded to Prompt-type fields in Slate.
Double-check the Safe/Unsafe settings on the Source Format. Safe Source Formats won't overwrite existing person-scoped data. Review the Slate documentation for more information.

Document Load

Once the CAS API delivers application documents to Slate, additional steps are required to configure how those documents will be imported into Slate. See Slate’s Knowledge Base for more information. Some common issues that users have encountered are listed below, along with recommended troubleshooting steps that can be followed to identify and resolve the issue.

Issue	Troubleshooting Steps
Documents aren't being loaded to Slate	Confirm that the All CAS by Liaison - Applications Source Format is active, Remap Active, and the application and person records for the missing documents have been created in Slate. Documents will only be loaded to existing Slate records. Confirm that the documents are being delivered to the Slate SFTP's /incoming/liaison/ directory. Only PDF files delivered to that directory will be loaded into Slate as Materials. Confirm that the documents are being delivered with exactly the filename pattern specified in the documentation. The Slate import process parses the filename for specific elements; files that don't match the file naming convention won't be successfully loaded. Confirm that the documents were delivered between 2:30 – 10:30 AM ET. Documents will only be imported into Slate hourly between 2:30 – 10:30 AM ET. If a document was delivered at 12 PM ET it won't be loaded to Slate until the following day at 2:30 AM ET. Confirm that no value has been set for the Source Format's Import Path/Mask field. Review the Slate documentation for more information. Confirm that the Source Format's value mapping has been completed. Only document type values that are mapped to Slate Material Codes will be loaded. Note that the Force Process Pickup and Force Process Import functions will not work for this Source Format since it is not actually a data feed.

Issue

Troubleshooting Steps

Documents aren't being loaded to Slate

Confirm that the All CAS by Liaison - Applications Source Format is active, Remap Active, and the application and person records for the missing documents have been created in Slate. Documents will only be loaded to existing Slate records.
Confirm that the documents are being delivered to the Slate SFTP's /incoming/liaison/ directory. Only PDF files delivered to that directory will be loaded into Slate as Materials.
Confirm that the documents are being delivered with exactly the filename pattern specified in the documentation. The Slate import process parses the filename for specific elements; files that don't match the file naming convention won't be successfully loaded.
Confirm that the documents were delivered between 2:30 – 10:30 AM ET. Documents will only be imported into Slate hourly between 2:30 – 10:30 AM ET. If a document was delivered at 12 PM ET it won't be loaded to Slate until the following day at 2:30 AM ET.
Confirm that no value has been set for the Source Format's Import Path/Mask field. Review the Slate documentation for more information.
Confirm that the Source Format's value mapping has been completed. Only document type values that are mapped to Slate Material Codes will be loaded.
Note that the Force Process Pickup and Force Process Import functions will not work for this Source Format since it is not actually a data feed.

Notes About Document Load

Since the All CAS by Liaison - Documents source format is not actually a data feed, you will not see records appear for this source format, nor will you see Fields to map in the Remap configurations.
Only document types mapped to a valid Slate material type will be imported. PDFs associated with unmapped document types will remain in the SFTP directory until they are mapped (and imported) or purged.
If a document is mapped to a school-scoped material, but the school record with which the document is associated does not exist (either because it was deleted, not successfully created, or updated), the document will be sent to Batch Acquire for manual processing after 3 days.
Sometimes applicants send or upload oversized documents or a huge batch of documents. Both cases may put the PDF documents sent by the CAS API over the limit for the Slate integration (32MB). Unfortunately, Slate doesn't currently notify you when an oversized document is received in the SFTP. We recommend you periodically check the SFTP Explorer to see if there are documents that haven't processed. If any are over 32MB, you can click the filename to download the file and use Slate's Batch Acquire to attach the document to the applicant record. Batch Acquire has a maximum file size of 64MB.

For more information, also see the Slate Knowledge Base.