SAO Integration Module

Overview

The Veracross SAO Integration module allows certain information submitted through The Enrollment Management Association (Formerly known as “SSAT”)’s Standard Application Online (SAO) to be imported into the Veracross Admissions module. This allows schools to capture applicant information in a way that is seamless in allowing applicants to apply via Enrollment Management Association, but manage it from the central Veracross system so all data processing occurs in one place.

The integration involves both:

• A fully automated nightly data sync (the data points are seen below), plus also
• Access to a special SAO-data importer template that Veracross clients may choose to use whenever they want (often used to import the test scores for Prospects who complete the test via SAO but may not apply).
  • Note: This importer type includes CRM data for the child (Name, Contact Info, Address), which is over and above the standard “Test Scores” importer component of the test scores module, which does not include CRM data. To learn more about the free (no extra cost) importer features of the “Test Scores” module, read more here.

Please note, this integration is designed to support data synchronization for anyone who inquires or applies to your school via SAO. If they apply or inquire to your school via SAO, then relevant data (CRM, checklist, test scores, relationships, etc.) are synchronized in Veracross. The inquiry/application threshold is fundamental to this integration. If you wish to import test scores or other data for people who haven't applied or inquired to your school via SAO, then consider closely whether this integration is an appropriate solution for your needs.

Integration & Setup Requirements

Integration requirements consists of a set of credentials provided by SAO to schools and a questionnaire that communicates to Veracross the mapping values of SAO to the Veracross system (e.g. how do SAO checklist items map to Veracross checklist items?).

Credentials

The following credentials must be provided from SAO:

• API Key
• API Secret
• School Code

Questionnaire

The school must complete an SAO Integration Questionnaire provided by Veracross. This questionnaire details how the admissions data gathered from the SAO common app maps to the specific records provided by the Veracross Admissions module. Admission offices should complete this questionnaire with their Account Managers to ensure all necessary information is captured.

When working through the SAO Integration Questionnaire it is particularly important to discuss Admission Checklist items. Checklist items in Veracross Admissions are a very important part of the Admissions process flow because they are how the candidate’s progress is tracked through the application process. Discuss with the Account Manager the best possible mapping from SAO checklist items to Veracross checklist items to ensure all relevant information is captured, updated, and maintained.

SAO Mapping Reference

When the integration process between SSAT and Veracross has been set up a new query will be available on the System homepage under the Veracross Integrations section. This query displays a list of all the SAO values and how they map to Veracross table names and description. Work with the Account Manager to verify the mapping, especially Admission checklist items.

A Note About Grade Levels
Grade levels are imported as part of the SSAT module. However, because SSAT has a standard grade level convention, Veracross pre-configures the grade level mapping based on what it can infer about the school’s grade information.

A Note About Test Takers who fail to Inquire/Apply

Due to the fact the Test Scores API supplied by EMA is constructed with only Folio ID as a way to match CRM data; in conjunction with the fact that CRM (registration) data is only supplied by EMA if and when someone inquires/applies; this sync can therefore only import data about test takes who have also inquired/applied. If your school have a large number of people take the test without formally inquiring/applying through EMA, then this integration may not be a great value: The value is especially located in the ability to sync anyone who inquires/applies through SAO. Read more under the section paragraph of this section below.

Data Matching & Syncing Process Overview

SAO integration scripts run each morning at 6:30am UTC. At this time all activity conducted by a candidate from the previous day is synced with the appropriate Admissions records in Veracross.

Activity conducted through SAO is recorded as Admission History Log records. Log records are added during the morning update to the Admission History Log table which is accessible from the Activity Log tab on the Admission Candidate record. These records are intended to provide an overview of what information was added from SSAT and when. Each log record receives the “SSAT Sync” event type and the Notes section records the specific information that was added from one of the four major data sources imported from SAO:

• Admission Inquiries
• Applications (referred to as Registrations in SAO)
• Admission Files
• Test Score information

Daily SAO syncs can be viewed from the “Recent SSAT Sync Updates” query located on the Admissions homepage.

Additionally, the originating data source for admission records will also indicate whether the data came from SAO. Data sources that came from SAO will be prefixed with “SSAT” and then include specific information about the what type of information it is (e.g. SSAT Inquiries Prospect). Recording the data source of the Admissions information allows schools to query on which applicants applied through the SAO Common App.

Additionally, the “Update User” for any SAO sync will be record as “vc.admissions” meaning that if you look at audit logs or update user in a query and see “vc.admissions” there’s a very strong likelihood that the update in question came via the SAO automated synchronization.

Note: The synchronization ceases once the applicant’s Role is changed to “Future Student” or “Student”, or if there’s an application with a particular status (Configurable – see more info below), or if there’s an enrollment record for the current year with any status other than “Declined Enrollment” or “Withdrawn.” SSAT data is not imported or received for anyone in any of the above circumstances. 

Record Matching

One of the main goals with the third party integration with SAO is to minimize the duplicate record creation that often occurs with Admissions data. To help with this process Veracross applies a number of matching strategies to existing records in the system before new records are added. These matching strategies are the same for both admission inquiry and admission application data.

There are three ways in which matching is applied to Admission Candidates (in order):

1. If the new Admission Candidate has an Admission History record where the admission data source is SAO and the Folio ID (unique ID assigned to a candidate in SAO) matches, then all new information will be synced with that record. To be clear, the data provided by EMA includes something called a "Registration ID" and a separate "Folio ID". Their format is similar and the IDs are frequently in the same range, however, this integration is based on Folio ID, not registration ID. 
2. If a candidate already has a Person record in Veracross that has a matching Folio ID and a data source of either SAO Inquiries Prospect or SAO Registration Applicant, then the existing Person record will be updated. Merge history records are also reviewed at this time to ensure the correct person record is updated. Admission History records will also be updated if the year applying for is the same as the new inquiry. If they have an Admission History record for a previous year, then a new one will be inserted.
3. If the first name, last name, and date of birth match an existing Person record in Veracross then that existing record is updated with the new information from SAO. For this reason, it is recommended that these three fields on the pre-application be required.

If none of these matching checks find existing records in Veracross, then a new Person record is added with the appropriate person role, an Admission History record is created for the current admissions year applying for, and an Initial Inquiry Event record is created if it does not already exist.

Households

A similar process is followed for inserting new Household records. If a Household record with a matching Folio ID and a data source of “SAO Household” is found that Household record is updated. If no match is found, a new Household record is created for the candidate.

Record Syncing

Similar to matching records, Veracross also applies rules to updating and syncing future data that is brought in from SAO. All data is synced on initial import only. If the information pulled in from SAO does not match an existing person record, then a new record for a person and/or household is inserted into the database. From that point on all data imported from SAO that matches existing records in the Veracross database will only update values that do not already exist on the Veracross records. In other words, all information present on the Veracross record will be maintained and only new information (i.e. unpopulated fields) that SAO can provided is added to the Veracross record, except for a few key exceptions: Contact information (phone number, email address) will be resynced because there are some circumstances, though rare, where that information can be updated in SAO after initial submission. “Requesting FA” will only be re-synced on the first sync of the admissions year because on the one hand, you may wish to update “Requesting FA” in Veracross for someone who has applied through SAO, but on the other hand you may wish to have that updated again to match SAO if someone has re-applied the following year.

The sync process occurs during the daily SAO data sync regardless of whether a new record was just created.

Relationships

An exception to this record syncing process is updating relationship information. Relative information that already exists in Veracross is maintained on the record even if SAO provides different information (e.g. Veracross has relationship “father” and new SAO data provides “step-father,” the Veracross information will be maintained). However, missing relationship information will always be created between admission candidates and relatives. If the Veracross record has an unspecified relationship such as None Specified, Unspecified Relative, or Other and the data from SAO is providing more specific information about the person, then the relationship information is updated. Before a relationship is updated, however, the new information presented from SAO is verified against inferences that can be made based on the person’s inclusion in a household. This ensures that relationship data is updated and maintained accurately.

Identifying records that have been affected by the SAO automated sync

The unique identifying “Folio ID” is recorded as a part of the Person Merge History – Legacy ID field in order to support other possible integrations in addition to this SAO integration.

The way to identify records that originated in SAO is by looking at the input user for a person. That will be set as vc.admissions. Depending on the specific case, it will also generally be helpful to look at the Admissions Source field on the Admission History record; as a default, that will be set as “SSAT” but this is configurable to some extent.

The only comprehensive way to analyze the whole complement of records updated or affected by the SAO sync is to look at the “Recent SSAT Syncs” report in Veracross.

Data Import (Specific Details)

As a default, data is updated in Veracross for any registrant who has been updated in SAO within the last 48 hours. The SAO API provides all records, but for performance reasons Veracross only acts on or update records updated in the past 2 days. It would be limited to simply updates “in the past day” but the sync process can potentially take hours depending on the number of records being updated; a 48 hour window guarantees that oddly-timed updates aren’t missed by the nightly sync process.

If a Registration sync fails for any reason (a timeout, or any other server error) that is logged and re-tried the following day until it is successful, regardless of the 2 day window.

If this module is being implemented for the first time in the middle of an admissions season, Veracross can specially run the sync for all records in the admissions year, not only those updated in the past 48 hours.

CRM/Demographic/Contact Info:

For both Inquiries and Applications, the following Household and Person information is synced on initial data import only, that is, only if the SAO sync is inserting a record for a Household or a Person.

HOUSEHOLD

• Household Name
• Address Lines 1, 2, and 3
• City
• State
• Postal Code
• Country

PERSON

• First Name
• Middle Name
• Last Name
• Nick Name
• Name Suffix
• Place of Birth
• Date of Birth
• Gender

New people will be added to Veracross as well if they appear in the SAO data but don’t currently exist in Veracross. For instance, if the family is able to add a second parent or another relative in SAO, that will be added to Veracross as a result.

The following Per-person field (which is inherited by the Application, and the Financial Aid Module in Veracross) will be set on the first sync of the admissions year for a candidate.

• “Requesting Financial Aid” will be synced on the first import of that prospect or applicant’s info for the admissions year, enabling staff to remove the “Requesting Financial Aid” setting in Veracross if needed. The way this is synced from SAO is year-specific meaning if the applicant requested FA for 17-18, and that was removed in Veracross, and then requests FA later when applying for 18-19, that will be re-imported for 18-19.

RELATIONSHIPS

• Missing relationships will be added
• Existing relationships won’t be updated.  (“Step Father” won’t be changed to “Father”)

The following information is updated every sync with SAO if the person currently exists in Veracross, and the fields are blank at the time of the sync:

PERSON

• Home phone
• Mobile phone
• Email 1 (Note, Email 2 for the applicant was a part of the sync until January 2017 when it was removed from the procedure. Going forward, Email 2 will never be populated by the SAO sync)
• Ethnicity
• Languages
• Job Title (Not imported for applicants; only imported for parents)

The following Person fields are updated to match SAO even if they are currently populated in Veracross; this is how a “cold” applicant for last year can be updated as an “active” applicant for the current admissions year by the SAO sync:

• Year Applying For (will be updated on each sync to match the active SAO admissions year for applicants/prospects)
• Grade Applying For (will be updated on each sync to match the grade level provided by SAO data)

Admissions Info:

INQUIRIES

(The primary goal of the inquiry syncing process is to create new admission records (including Households) and Initial Inquiry “event” records if they do not already exist, and import the child’s information and give the role of “Prospect”. If they do exist, then the matching and syncing steps listed above are followed for adding and updating data.)

• All information listed above in the “Record Matching” and “Data Import (Specific Details)” sections above represents the complete list of data imported for Inquiries.
• Folio ID is set for Prospects
• An Inquiry Event is added for the prospect
• Their role is set as Prospect

APPLICATIONS (referred to as Registrations in SAO)

(Applications build off the information imported during the Inquiries stage and adds more information about the applicant and his/her family such as school organizations, application records, and checklist items.) 

• All information listed above in the “Record Matching” and “Data Import (Specific Details)” sections above represents the complete list of data imported for Inquiries.
• Folio ID is set for Applicants

> New Information on existing records

• Country of Citizenship marked as “primary citizenship” for the applicant.
• Updates foreign exchange information (field name: I20) if the SAO app has the Visa application field selected.
• Person roles will be updated and old person roles such as applicant former will be removed.
• For relatives: parent employer information such as job title, if it does not already exist.

> New Records Added
For every application that is imported from SAO additional records may be inserted if they do not already exist:

• Organizations
  One such record is school organizations (e.g. previously attended schools). Before a new Organization record is added, first the legacy ID and data source is examined on existing Organization records to see if it already exists. If this does not find a match, then the Organization city and state/provinces of Organization record with the Organization Type “School” are checked. If no Organization record is found, a new one is inserted and Organization membership created.
• Application records When a candidate completes the registration process in SSAT that is the time in which a new Application record is inserted into Veracross if it does not already exist.

> Updates to existing records

• Checklist items. Checklist items are always updated in Veracross as part of the Application record. If the checklist item is Incomplete in Veracross, but SAO says that it’s complete (according to the Mapping, as noted above) then that checklist item is marked Complete in Veracross. As checklist items are completed in SSAT the checklist item “completed date” is also updated in Veracross. This will only be done if there is no date currently entered for that checklist item in Veracross (we don’t overwrite a “completed date” if on the off chance a checklist item is “incomplete” but already has a completed date filled).

ADMISSIONS FILE 

• The Admission File is the pdf version of the standard application online from SAO. This file is associated with the Application record for the candidate and is available on the “SSAT Files” tab. A new file will be associated whenever new information is added to the Registration form in SAO. The old Registration file will be removed if a new version is available.
• The admissions file naming convention allows the old one to be retained and a new one year-over-year to be received.

TEST SCORES

The Test Scores component of the import can import 2 possible data types: Standardized Test and Standardized Test Score. If an SAO Test record is not in the system for a given applicant, it will be imported with its scores. Additionally, if the SAO test already exists – but only has a partial score profile for whatever reason – the missing scores will be imported. Duplicates are aggressively checked for based on same person/test type/date and same person/test/score type, and we won’t import duplicate tests or scores, but it’s possible that some new edge case not previously considered may make its way in.

Test Scores are provided via their own API feed, and the only person-identifying data in this feed that Veracross is able to use is the Folio ID. This means that if a potential admissions candidate has taken the SAO test and chosen to provide their test scores to the school, but hasn’t provided an Inquiry or an Application to the school, those test scores will not be imported – because without an Inquiry or an Application, the automated importer can’t sync up a Folio ID for that record in Veracross; and without a Folio ID the test scores cannot be imported.

> New Information

There are four test score values that are imported from SAO: reading, verbal, qualitative, and total grade. For each value the following levels are also imported: scaled score, scaled score percentile rank, and scaled score percentile rank by grade level.

All score values, score levels, and score data (i.e. score received) are added to the test score record.

> New Records Added

If a Test Score record does not already exist for the candidate then a new record is created. If a record does exist, but no test score information has been recorded, all new score information will be added to that record. All existing data on a test score record will be maintained even if new test score information is received from SAO.

Data that’s not imported

As of Spring 2018, EMA has added a number of new features that are not supported.

• EMA now allows applications for the current year, next year (previously supported) and year after that. As of 2018 Veracross still only supports imports for the “Next Year”.
• EMA introduced some new test types and profile types in 2018. Those are not included in the automated sync as of 2018 either.

Additionally, there are a small amount of demographic and personal data SSAT tracks that Veracross currently does not import, listed in detail below:

Admission Candidate Information:

• Current school is not imported for “inquiries”, it is only imported for “Registrations” (aka Applicants). See above.
• Interests

Related People Information:

• Employer
• Education
• Relationships between relatives

Stopping the synchronization from running

When the data for a given candidate first starts to arrive from EMA, the source of the data (EMA) is the “truth” for that record. But at some point, Veracross becomes the “truth,” as Veracross is the SIS and the place where admissions decisions are made and enrollment proceeds.

Defining how and when that shift occurs – when EMA ceases to be the “truth” for the data and the Veracross data instead becomes the “truth” – is a challenge because exceptions (especially for midyear entry, or for when contact info might need to be updated) might result in different scenarios needing to operate differently.

The following scenarios will completely stop the synchronization of the data which, as noted above, is usually “Regularly Updated” (Contact Info if blank, missing application, updates to checklist items, etc.). So if the following conditions exist, that data is no longer updated for the candidate:

• If the candidate’s role is Student or Future Student
• If there is an Enrollment record for the current year with any Enrollment Status other than “EN: Declined” or “RE: Withdrawn/Withdrawing”. That is, if the Enrollment Record exists for the current year, and the Enrollment status is “EN: Pending Enrollment,” then the sync will cease for that person. This is to handle midyear enrollment after an application is accepted. Only “Declines” or “Withdrawals” to enrollment can then enable the sync to begin again.
• Configurable: If the Application Status is in a particular category. E.g. If the application is “Accepted” for the next school year, your configuration might be set up to cause the sync to stop. Ask your account manager to enable this for particular Application Status Categories.

Things to look out for

• Address information is not updated for existing records. If an existing candidate is matched with EMA data on First/Last/Birthdate (for an initial sync) or matched on Folio ID (for an ongoing sync) but their address is blank or wrong in Veracross, that will remain blank or wrong in Veracross.
• People who apply via SAO but also enter the Veracross database via other means can make the process much more complicated depending on the specific scenario. There are at least 4 possible ways to get Admissions and test score data into Veracross for people who might have applied via EMA in addition to the automated sync module:
  • Manually keying in data, for instance if the family filled out an offline form of some sort
  • If the family has applied for the current admissions year in the Admission Portal
  • Using the manual importer available at import.veracross.com/{school_name}. There is an SAO import type, used to add Candidates and their Test Scores to Veracross. Update user = vc.admissions if this is used. Note, this import type does not support home address data as of February 2017. Three benefits of this import type are (a) the Veracross template fits the format of the data provided by SAO, (b) This import type adds people to the database, not just test scores, and (c) This import type includes the Folio ID used later if the automated sync is run. In combination with the automated nightly sync, this manual importer has the benefit of adding people and test scores to Veracross earlier than they would come via the automated sync; but given that address isn’t imported, and parents aren’t included, this sync could potentially cause more issues than it might solve for your admissions department.
  • Using the manual importer available at import.veracross.com/{school_name} there is a specific Test Score import type that can be used. This can not add people to Veracross; it can only add test scores for people already in the database. For schools using the SAO automated sync, it’s unlikely this import type will be used for SAO test scores.
  • Note, on all the possible sources of “test scores” data, the system runs robust duplicate-avoidance checking to attempt to avoid inserting the same test or score more than once. Each of the three possible sources of tests/test scores data searches for the same person/date/scores and if it already exists, no duplicate is added.