Transcripts Transfer Design
Overview
A student can enroll in online courses at multiple colleges. One college will be designated as their "home" college, with the remainder being "teaching" colleges, or non-home colleges where they (may) take classes.
The API Gateway will expose a public URI that will invoke this Transcript Transfer service. The service will copy transcript data from the teaching college to the student's home college as outlined below.
Business Case
- When the service is invoked using a public URL, we need to copy transcript transfer data from a teaching college to the home college. This is not an automatic or scheduled execution, but one that runs upon request.
API Gateway
The Service Router, Service Conductor, and Service Workers for the Transcript Transfer public service are detailed below.
Service Router
Authorization and service routing (URI) for the Transcript Transfer public service are described below.
Authorization
Proper OAuth 2.0 credentials are required to access all endpoints. The caller must have the following security scope(s);
SISDATA_R
SISDATA_W
TRANSCRIPT-TRANSFER
Transcript Transfer Gateway URI
The path pattern below will be exposed to access the service:
/transcriptTransfer**
URI Request Parameters
| Parameter | Required? | Description |
|---|---|---|
| teachingSchoolMISCode | Required | MIS code of teaching college from which to pull transcript data. |
| afterDate | Required | Retrieve transcript transfers that occur on or after this date (YYYY-MM-DD). |
| beforeDate | Required | Retrieve transcript transfers that occur on or before this date (YYYY-MM-DD). |
An example with inputs parameters:
/transcriptTransfer?teachingSchoolMISCode=001&afterDate=2017-12-31&beforeDate=2018-06-15
This URI will initiate the below Transcript Transfer Workflow
Service Conductor
The Service Conductor has the following workflow and task definitions for the Transcript Transfer service defined below.
Workflow Definitions
There is one workflows for the Transcript Transfer service:
- Transcript Transfer Workflow
Transcript Transfer Workflow
This workflow is started by the service-router in order to process the URI. It is responsible for copying student transcripts from the teaching college to each student's home college.
Workflow Input
| Parameter | Description |
|---|---|
| teachingSchoolMISCode | MIS code of teaching college to pull transcript data from |
| afterDate | Retrieve transcript transfers that occurs on or after this date (YYYY-MM-DD). |
| beforeDate | Retrieve transcript transfers that occurs on or before this date (YYYY-MM-DD). |
Note: The input parameters can equate to a large set of transcripts to process. The design must accommodate this potential load.
Task Definitions
The Transcript Transfer service has two workflow tasks and two event handlers associated with it:
- Get Data for PagedResources Task
- Cycled PageResources Task
- Handle list of transcript transfer records event
- Handle a single transcript event
Get Data for PagedResources Task
As a generic task, the URL points to and retrieves a PagedResources
Task Input
| Parameter Name | Description |
|---|---|
| url | complete URL w/ path and params to get HATEOAS data |
Task Properties
- Course Exchange API URL to retrieve transcript transfer data
- OAuth security credentials for course exchange API
Service Worker
- Do an HTTP GET call to $input.url
- Set JSON results in context output
Implementation Note
- Although new, this should be a generic and re-usable task for handling PagedResources data beyond transcript transfer record usage.
Cycle PagedResources Task
This task loops through all pages passed as input and raises an event for each page to be processed.
Task Input
| Parameter Name | Description |
|---|---|
| data | JSON representation of a PagedResources |
| eventName | name of event raised for each page of data |
The task input 'data' should come from the above Get Data for PagedResources
Task Properties
Service Worker
- Loop through each page of $input.data
- Do a GET call on $input.data.getNextLink()
- Raise EVENT to named event in $input.eventName and pass as input JSON results of call above for one page of data
Implementation Note
- Although new, this should be a generic and re-usable task for handling PagedResources data beyond transcript transfer record usage.
Handle list of transcript transfer records
This is an event handler task to handle a list or page of transcript transfer records. This will break the list of items/rows into individual processing calls by raising an event.
Task Input
| Parameter Name | Description |
|---|---|
| data | JSON for a single page, with the content being a list of Transcript Transfer items |
| eventName | name of event raised for each item of data |
Task Properties
- If we use a Fork/Join, maybe the number of threads as a property?
Service Worker
- Loop through each item in $input.data
- Raise EVENT to named event in $input.eventName and pass as input JSON results of above single transcript transfer item
Implementation Note
- This version, the page is broken into individual rows and each row will be handled individually. In the future we may want to group the processing to be an array of tasks. This event handler plans for that future growth.
- We may want to use Conductor's Fork Task and Join Task to process the list in parallel threads. Running in parallel, this should be significantly faster.
Handle a single transcript
This is an event handler task to handle a single transcript transfer data row. This handles the core logic of what to do with a single transcript transfer item.
The orchestration of calls includes:
- calling the eTranscript API
- this in turn calls the college-adaptor
- calling the course-exchange API to update the transcript transfer status record
Task Input
| Parameter Name | Description |
|---|---|
| data | JSON for a single Transcript Transfer item |
Task Properties
- eTranscript API URL to send transcript transfer data
- Course Exchange API URL to retrieve transcript transfer data
- OAuth security credentials for course exchange API
Service Worker
- Process Transcript Transfers: call to eTranscript API passing it $input.data
- Each call will block until the eTranscript process is complete and the record is copied to the home college (using college-adaptor)
- Update Transcript Transfers: call to course-exchange-API passing it output from the call above
Implementation Note
Service Workers
For deployment, all service workers will be deployed to the shared-services env + private subnet. This model allows using the centralized service-worker from the api-gateway stack.
Response
An example return from a call to this gateway endpoint will return:
{
"numberOfProcessedRecords" : 100,
"errorMessage" : ""
}