Skip to main content

Concepts

Flow of Events in the Admissions Process​

DoD publishes events that represent changes to an applicant's data to synchronize data at OCAS with the college. These events are published through the Peek API endpoint as they occur. The diagram below shows a high-level flow of events that occur during the admissions process. It includes the various state changes of Applications, Program Choices, and Offers. See Synchronizing State for more details on possible states.

Consuming API Endpoints​

All endpoint calls need an JWT Bearer token provided in the HTTP Header (see Authentication). The token is obtained from the token endpoint and is valid for 60 minutes, so we recommend caching this token and re-using it until it nears expiration, before fetching a new token. The diagram below shows a common flow for endpoint calls.

Receiving Inbound Events​

Inbound events must be polled from the events endpoint. Multiple events can be retrieved at once, but you must send back an ACK for each event to indicate you have received it. You might decide to process each event one at a time immediately, or save them to your own internal queue, and process them later. Without sending the ACK to API, we would send you back the same event forever until it's "acknowledged".

Below is a sequence diagram of a possible polling service that is continuously running (idle). Every X minutes, the service could receive a wake up trigger to fetch and process all inbound SIS events. The diagram has two loops, one that keeps checking for the next batch of 100 events, and an inner loop that processes each event, making sure to send back the ACK when done.

In the loop as you process events it will be important to perform an idempotence check to ensure you have not already processed the event (based on the event's unique identifier). This will handle the unexpected case where a given event is already processed in your system but there is a service interruption that prevents the Acknowledgement from reaching OCAS.

Event and Record Correlation​

Each event will be transmitted along with the applicationNumber of the applicant to which the event applies. It will also include the id of the record being changed. For example, an Education record will include a unique identifier when it is first sent to the college, either as part of the larger Application object or as a separate Education record when it is added for an already-submitted application. Subsequent updates to that Education record will include that same unique identifier to distinguish it from other Education records attached to the application.

This is particularly important for the Delete event of a record. For example, when an Education record is deleted, you will receive the EducationDeleted event and instead of resending the full body of the Education record, only the id property is included. This applies to OntarioAcademicData, InternationalAcademicData, ProgramChoice, Education, SupportingDocument, ApplicantCredential, Course, ApplicantProficiency, and ApplicantProficiencySubScore records.

Something to consider is that this will likely require some data load as part of a go-live. Since these IDs are not included in Coltrane today, it would be necessary to retrieve and store them for any active applications at the time of cutover so that you will be able to process any delete events on records originally loaded from Coltrane.

College-Assigned IDs​

Optionally, Domestic on Demand supports exchanging program choice and offer data using the College's own identifiers for Program Intakes and Offers.

If so desired, the college can provide OCAS their unique identifiers for program intakes as part of program catalogue data. If available, OCAS will include the intakeSisIdentifier in the ProgramChoice model. The college can then use that value to lookup the related program intake (as opposed to using the compound business key of collegeCode, programCode, campusCode, delivery, and startDate).

Likewise, if an Offer is sent that includes the intakeSisIdentifier, OCAS will use that key to match the program choice in the application using that value. If not matched, the Offer will be considered an alternate offer.

Additionally, Offer records support the college specifying a offerSisIdentifier. When included, OCAS will record this value on the offer record and echo it back in subequent OfferAccepted events as the offerSisIdentifier on the ProgramChoice model

Event Sequencing​

Events for a given application number are expected to be processed in the order in which they are published, as determined by the id of the event (higher values of id indicate events published more recently). This id is global and not scoped to applications (e.g. two sequential events for an application may have large gaps in the increment of id).

In the event of errors loading or processing events for a given application it does not preclude the college from continuing to load events for other applications. While it is at the discretion of the college, it is still recommended to resolve errors with application event loading as soon as possible to avoid the possibility of affected applicants put at a disadvantage for considerations of offers of admission.

Applications API Endpoint​

Under normal conditions, all applicant data should be retrieved through the GET /events endpoint. The GET /applications endpoint is intended to be used as a means to guarantee sync between OCAS and your SIS. In the legacy Coltrane solution, colleges have a means to request a retrigger of a given application number which requires the College to contact our IT support. The GET /applications endpoint is a self-service alternative to that. A call to it for a given application will return the entire snapshot of that application data.

Alternate Offers​

When a college sends an offer to a program/intake that is not on the application, this is considered an Alternate Offer. Because there is no program choice from the applicant on record initially related to this Offer there are some unique considerations:

  1. Alternate Offers do not generate a ProgramChoiceAdded event. Behind the scenes there is no program choice record for an alternate offer until the applicant accepts that offer
  2. If the applicant does not accept the Offer, you will not receive a ProgramChoiceDeleted event related to the Alternate Offer
  3. If the applicant does accept the offer, triggering an OfferAccepted event, and on a future date declines the Offer (triggering a OfferDeclined event) then you will need the programChoiceId to process the decline. This is included in the OfferAccepted event model, id in the ProgramChoice model, and so it will be necessary to capture this value from the OfferAccepted event.

Transcripts and Grades​

Unlike in Coltrane, grades from Ontario High Schools and International Credential Evaluators are grouped within an applicantCredential object. This object will identify the school that issued the transcript, typically the school the student is currently attending or most recently attended, identified by the schoolCode (the school MIDENT). This is distinct from the midentCode on a course which represents the school where the student earned the credit. The midentCode is not part of the business key of an applicantCredential and can be updated through a CourseUpdated event to a different school which may not match school in the parent applicantCredential object.