Access Keys:
Skip to content (Access Key - 0)

Subject Management API - General Information and Key Processes

Please note that this page and related pages are being developed as part of the CIM Courses Project and are subject to change.

The Subject Management API - General Information and Key Processes was built as part of the CIM Courses Project. This article describes the general information and key processes of Subject Management API.

Table of Contents:

Subject Management API Overview

The Subject Management API was developed to provide endpoints to retrieve and update subject to data CTSS (Container/ Template Subject Structure) tables. It also generates subject notifications in the form of email for term plan update and the backfill queue records for the backfill process to update the CIS and MITSIS tables.  

API portal documentation

The documentation for the endpoints the Subject Management API serves can be accessed via the following links:

  • IS&T API developer portal, under section API reference there is a link to access the MIT Subjects API documentation in the Anypoint Platform API Live Portal (production tier)

For those who have access to the Anypoint Exchange within the Anypoint Platform, you can use the following links to directly access the documentation in the live portal:

Available endpoints

The following are lists of available get and post endpoints. For more detailed description of the usage and the data retrieved for the get endpoints, please refer to the API portal documentation.

Get endpoints

/subjects/courses/{subjectCode}/numbers
/subjects/courses/{subjectCode}/numbers/{subjectNumber}
/subjects/courses/{subjectCode}/numbers/{subjectNumber}/terms/{termCode}
/subjects/containers/{containerId}/terms/{termCode}/displayControlsAndUrls
/subjects/containers/{containerId}/templates/{templateId}
/subjects/containers/{containerId}/terms/{termCode}/enrollableSubjects
/subjects/homeInstitutions/{homeInstitutionId}/homeOrganizationUnits
/subjects/homeInstitutions/{homeInstitutionId}/homeOrganizationUnits/{homeSchoolId}/homeSubjects/{homeSubjectId}/terms/{termCode}
/subjects/termPlans/nextOfferedYears
/subjects/homeSubjects/{homeSubjectId}
/subjectCodes/{subjectCode}
/subjectAttributes
/subjectAttributes/{attributeCode}
/gradingModes
/gradingModes/{gradingModeCode}
/gradingModeTypes
/gradingModeTypes/{typeCode}
/subjects/containers/{containerId}/templates
/subjects/containers/{containerId}/terms/{termCode}/displayControls/optionValues
/subjects/containers/{containerId}/templates/{templateId}/requisites"
/subjects/managementConfigurations

Post endpoints

/subjects
/subjects/containers/{containerId}/effectiveTerms/{effectiveTerm}
/subjects/containers/{containerId}/termPlans
/subjects/containers/{containerId}/terms/{termCode}/enrollableSubjects
/subjects/containers/{containerId}
/subjects/containers/{containerId}/displayControlsAndUrls
/subjects/containers/{containerId}/requisites
/subjects/containers/{containerId}/resetEffectiveTerm
/subjects/containers/{containerId}/notifications

Sample JSON for post endpoints

The following are some sample json requests for post endpoints available via subject management API:

  1. Create Subject Post endpoint 
    uri: /subjects

    Show/hide create subject json

  1. Edit Subject Post Endpoint 
    uri: /subjects/containers/{containerId}/effectiveTerms/{effectiveTerm}

    Show/hide edit subject json

  2. Term plan Post Endpoint 
    uri: /subjects/containers/{containerId}/termPlans

    Show/hide term plan post json

  3. Display Control Post Endpoint 
    uri: /subjects/containers/{containerId}/displayControlsAndUrls

    Show/hide display control post json

  4. Requisite Update Post Endpoint 
    uri: /subjects/containers/{containerId}/requisites

    Show/hide requisite post json

  5. Deactivate Subject Post Endpoint 
    uri: /subjects/containers/{containerId}

    Show/hide deactivate post json

  6. Reactivate Subject Post Endpoint 
    uri: /subjects/containers/{containerId}

    Show/hide reactivate post json

  1. Backdate Effective From Term Post Endpoint 
    uri: /subjects/containers/{containerId}/resetEffectiveTerm

    Show/hide backdate effective from term post json

  2. Subject Notification Post endpoint 
    uri: /subjects/containers/{containerId}/notifications

    Show/hide subject notification post json

  3. Enrollable Subject Post endpoint 
    uri: /subjects/containers/{containerId}/terms/{termCode}/enrollableSubjects

    Show/hide enrollable subject post json

Equivalency and Scheduling Relationship Processing

Overview

Equivalency and scheduling relationship are two major kinds of relationships that can be established between subjects. In our Container/Template Subject Structure (CTSS), equivalency (EQ) and scheduling relationship (SR) are maintained between containers. The subject data for the equivalency and scheduling relationship are stored in 2 database tables: SUBJECT_CONTAINER_EQUIV and SUBJECT_CONTAINER_RELATION. In order to facilitate an easy presentation of the detail processing, I would refer the main container (the subject being updated) as the container, the equivalent container as equivalent(EQ) subject and the scheduling relationship container as scheduling relationship(SR) subject respectively in the following sections.

We can add, update, bookend and delete equivalencies(EQ) and scheduling relationships (SR) of a container in CTSS. Bookending is a term we used to refer to the operation of modifying the THRU_TERM to end an EQ or SR. The subject management API provides multiple endpoints to perform these operations:

  • The subject create endpoint allows caller to add the EQ and/or SR to a new container
  • the subject edit and reactivation endpoints allow adding, updating, bookending, and deleting EQ and/or SR to an existing container
  • the subject deactivation endpoint sets the THRU_TERM of all SR subjects as the last active term of the container.

Although we have multiple endpoints to modify the EQ and/or SR of a container, they all share the same logic for updating the EQ and SR data. The logic is implemented in Mule config files: subjects-update-equivalent-subjects.xml and subjects-update-subject-relationship.xml. The entry flow for EQ update is EquivalentSubjects-update-subject-equivalent-subjects-flow in subjects-update-equivalent-subjects.xml, while the entry flow for SR update is SubjectRelationships-update-subject-relationship-subjects-flow in subjects-update-subject-relationship.xml.
The logic is implemented in Mule config files: subjects-update-equivalent-subjects.xml and subjects-update-subject-relationship.xml. The entry flow for EQ update is EquivalentSubjects-update-subject-equivalent-subjects-flow in subjects-update-equivalent-subjects.xml, while the entry flow for SR update is SubjectRelationships-update-subject-relationship-subjects-flow in subjects-update-subject-relationship.xml.

When a request contains a change to the existing EQ and/or SR of a container, the Subject Management API determines the actual EQ and/or SR subjects to be added, bookended or removed from the container by the reflexive and transitive propagation. In EquivalentSubjects-update-subject-equivalent-subjects-flow Mule flow, transformer class EquivalentSubjectUpdateTransformer is included to perform the reflexive and transitive equivalencies processing to compose the lists of EQ to be added, updated and deleted. Similarly, transformer class SubjectRelationshipUpdateTransformer referenced in Mule flow SubjectRelationships-update-subject-relationship-subjects-flow performs the same function for SR subjects.Details of the reflexive and transitive propagation processing will be covered in details in subsequent topics.

Validations

The validation logic for equivalency(EQ) and scheduling relationship(SR) can be found in Mule config files: subject-equivalent-subjects-validator.xml and subject-subject-relationship-validator.xml respectively. The details of the validation rules can be found in the document Subject Management API - System rules.

Reflexive Equivalencies and Scheduling Relationship Propagation

One of the business rules in CTSS is that EQs and SRs between two subject must be reflexive, meaning if Container A is equivalent to Container B, then Container B must be equivalent to Container A. Because of this rule, when an EQ or SR subject is added to or removed from a container, the Subject Management API adds or removes the equivalency or scheduling relationship of the container from the EQ or SR subject as well. Even though the update is initiated from one container, the propagation results in updating EQ and/or SR of both containers and incrementing the version numbers for templates of both the container(s).

The following are some use cases how this propagation logic works in different operations:
Show/hide EQ reflexive use cases

Transitive Equivalencies and Scheduling Relationship Propagation

One of the business rules in CTSS is that EQ and SR relationships must be transitive. This means that if Subject A is equivalent to both Subject B and Subject C, then Subject B must be equivalent to both Subject A and Subject C, and Subject C must be equivalent to both Subject A and Subject B. The Subject Management API enforces this rule when adding or removing EQs and SRs. For each subject being added or removed as an EQ or SR, the API looks up its existing EQs or SRs, and adds or removes EQs or SRs for them as well.

The following are some use cases how this propagation logic works in different operations:
Show/hide SR transitive use cases

Impact of Deactivation in Subject Equivalency and Scheduling Relationship

When a container is deactivated, the Subject Management API sets the thru_term of all SR subjects as the last active term (deactivation effective term minus 1 term) of the container to indicate that the SR(s) have ended.

However, the container's equivalencies (EQ) with other subject(s) are not bookended - i.e. the thru_term(s) of all EQ subjects are kept intact. The following illustrates a use case when a container with EQ and SR is deactivated:
Show/hide EQSR deactivate use case

In addition, an inactive/deactivated container can be added as a EQ subject to another container.

Special Handling of Equivalent and Scheduling Relationship subject in Backfill Queue Generation

Instead of representing the EQ and SR subjects data in the backfill queue record as the way the data is stored in the CTSS tables (EQ and SR are between containers), the Subject Management API includes all the subject id(s) - both main and cross listed subjects that are effective based on the EQ and/or SR from/thru term) in the PREV_DATA and NEW_DATA elements in the backfill queue record. Also, a separate backfill queue record with BACKFILL_PROCESS_TYPE as SR is generated when a subject with SR is updated. For more details, please refer to the kb page: Subject Management API Backfill Queue Generation

Grading Mode Mandate Processing

Overview

The grading mode mandate processing is added to the subject management API to support the initiative to apply experimental grading mode to subjects appropriately based on user-defined criteria. The processing involves automatically adding the experimental grading mode to subjects whose properties meet user-defined criteria, as well as removing the experimental grading mode from subjects whose properties no longer meet the criteria.

Processing Details

Processing Logic

The subject management API does not contain code to look into the subjects' properties to determine whether the experimental grade mode is to be added for a subject. Instead, it executes a query against the stv_grd_opt_rules table in saturn to get a list of valid experimental grading mode that can be applied to subjects. Then, it calls the stored procedure: SXP_GMOD_PKG.GET_GMOD_MANDATE_GMOD which returns the experimental grade mode and its effective terms applicable to the edited subject template. The stored procedure is called after the Subject Management API has completed the updating of CTSS tables and before the subject backfill queue records are generated. The reason for this order of processing is that the stored procedure needs to access the updated data to determine the experimental grading mode(s) to be applied to the subject.

After making the call, the subject management API performs the following operations:

  • delete all SUBJECT_TMPL_GMOD records associated with experimental grading mode(s) for the subject template
  • checks if experimental grading mode data is returned by the stored procedure. If data is returned, then the subject management API will add the experimental grading mode to the CTSS and add the grading mode to the gradingModes element in the NEW_DATA property of the subject backfill queue record. In addition, if the effective terms for the experimental grading mode does not match with editing template effective terms, the subject management API additional will create additional new subject templates and the corresponding backfill queue records for the new templates to reflect the change. To better illustrate the processing, please see the following use case:
    1.  Subject A currently has a template effective 2017FA-999999.
    2. User edits the subject A and adds a Science Core attribute PHY2 to Subject A effective 2018FA.
    3. The subject management API processes the update request to create a new template for Subject A effective 2018FA-99999.
    4. The subject management API then calls the grading mode mandate stored procedure which returns grading mode/type Y /Z to be applied to Subject A effective 2019FA-999999.
    5. The subject management API then updates the THRU_TERM of the 2018FA template to 2018SU.
    6. Then, the API creates a new template effective 2019FA-999999 for subject A, with the experimental grading mode added to the list of valid grading modes/types  of the template.
    7. Two backfill queue records are generated: one for template effective 2018FA-2018SU and one for template effective 2019FA-999999.
Technical Details
Mule Flows

The grading mode mandate processing logics can be found in the Mule config file subject-common.xml. There are two top-level flows created for endpoints to invoke to perform the grading mode mandate processing:

  • GmodMandate-processing-for-create-update-backdate-reactivate - to integrate with subject create, edit, reactivate, and backdate post endpoints to handle the grading mode mandate processing
  • GmodMandate-process-for-term-plan - to integrate with the term plan post endpoint to handle the grading mode mandate processing.

The major difference in logic between these 2 top level flows is the GmodMandate-processing-for-create-update-backdate-reactivate flow invokes the grading mode mandate stored procedure only once, while the GmodMandate-process-for-term-plan may invoke the stored procedure more than one time depending on the number of templates the term plan post endpoint is updating for the request. Whether the stored procedure is called once or multiple times, the returned data will be formatted into a string (comma-separated list) stored in flow variable: flowVars.gmodMandateOutput.

Transformer class GradingModeMandateUpdateTransformer was developed to compose the list of experimental grading mode to be inserted to and deleted from existing templates, the list of new templates to be created, and the list of backfill queue records to be generated so the subsequent processes in the flows can update the CTSS tables and generate the backfill records accordingly.

Stored Procedure

Stored procedure: sxp_gmod_pkg.get_gmod_mandate_gmod was developed by the GMOD mandate project team to determine the experimental grading mode to be applied to a subject template. The stored procedure takes the template id as the in parameter and returns a string as output. The output is formatted as a comma-separated list, and each item in the list contains data of an experimental grading mode that needs to be added to the subject. Each item comprises of 4 data components and the data components are formatted in the following order: the grading mode code, grading mode type, effective from term and effective through term of the experimental grading mode. The data components in each item are separated by hyphen. Here is a sample output with only one experimental grading mode:Y-Z-2019FA-999999.

If experimental grading mode does not apply to the subject, the stored procedure will return a null as output.

Developer notes

The following are some additional notes for developers:

  • processing of multiple mandate experimental grading modes with each at different effective terms is implemented in Subject Management API, though currently (3/5/2019) only one experimental grading mode is returned from the stored procedure.
  • The Subject Management API is configured to catch the exception for calls to the stored procedure. This is to ensure that the updating of the subject data proceeds even an exception is encountered with the grading mode mandate stored procedure. The API just treated it as there is no experimental grading mode to be applied to the subject.
Impact to the backfill queue generation and backfill processing

The subject create, edit, reactivate and backdate effective term endpoints have the possibility of generating more than one backfill records after the implementation of the grading mode mandate processing. The components in the NEW_DATA for all backfill records generated for each post request are the same, except the effectiveTerms and gradingModes of subjectTemplate component.

Impacted endpoints

Gmod mandate is calculated for the following endpoints

Gmod mandate processing is implemented in the following endpoints:

  • create subject endpoint
  • edit subject endpoint
  • subject reactivation endpoint
  • term plan update endpoint
  • backdate subject effective term endpoint
Gmod mandate is not calculated for the following endpoints

The following endpoints are updating subject data components that are deemed unlikely to cause mandate grading mode to be applied to the subject. Therefore, these endpoints have not implemented gmod mandate processing:

  • display control data update endpoint
  • requisite data update endpoint
  • deactivate subject endpoint

Known Issues

There are some known issues with the current implementation of the gmod mandate processing:

  • backdate effective term update is not working for subject with attribute that is going to trigger insertion of the mandate gmod to the subject (CD-2218)
  • PREV_DATA of the backfill queue records might not be populated correctly for the update and reactivate endpoints if the request involves subjects renumbering, or changes to the EQ or SR data and adding an attribute that triggers the creation of additional templates for the experimental grading mode. The incorrect PREV_DATA may cause problem in the backfill process in updating legacy tables (CD-2206).

Backfill Queues Generation

Overview

Subject Management API is the single gateway to create and edit subject data in Container/Template Subject Structure(CTSS) tables. For each request to update CTSS, the subject management API generates backfill queue records for the backfill process to update the MITSIS and CIS table accordingly.

What is the purpose of the backfill queues generated by the Subject Management API?

The backfill process uses the data in the backfill queues to update the legacy subject tables.

How/when is the backfill queue generated?

Each backfill queue record is generated by the Subject Management API whenever CTSS is updated via any post endpoint in the Subject Management API.

Where does the data in the queue record come from?

All of the subject data comes from the CTSS tables. No data is taken from the legacy tables.

What subjects are included in the backfill queue records?

The subject id(s) (subject code + number) that are included meet the following criteria:

  1. must be one of the following:
    1. main subject 
    2. the cross listed subject
    3. any subject(s) that have equivalencies and/or scheduling relationships with the main container
    4. any subject(s) that have equivalencies and/or scheduling relationships with EQ and/or SR subjects (subjects included in item c)
  2. For main, cross listed, EQ and SR subjects, the subjects either have to be active or has been removed from an active subject within a defined number of years relative to the MITSIS backfill gate. The defined number of years here is configured via secure properties: mitsis.past.data.retention.year and this property applies only to backfill queue generation process. Also, the MITSIS backfill gate is the CONFIG_VALUE defined in SUBJECT_MGMT_CONFIG table for a record with CONFIG_CODE equals to mitsisBackfillAllowedUptoYear.

How are the backfill queue records structured?

Each post endpoint generates at least one regular backfill record that are saved into the SUBJECT_BACKFILL_QUEUE table. It also generates multiple usedKey records - one for each subject included in the regular backfill record. The usedKey records are saved into the SUBJECT_BACKFILL_QUEUE_USEDKEY table. If the subject container in the backfill record has scheduling relationship with other subject(s), a separate regular backfill record with BACKFILL_PROCESS_TYPE = 'SR' and its corresponding usedKey records are also generated. All backfill regular records generated for each post update will have the same API_REF_ID.

The number and type of backfill queue records created by each request depends on the endpoint being called and the characteristics of the subject being edited.

  1. Display control and term plan post endpoints: generates backfill queue records with BACKFILL_PROCESS_TYPE='TP'.
  2. Create, Edit and reactivate subject post endpoints: each request generates a backfill queue record with BACKFILL_PROCESS_TYPE=null. If edited subject has scheduling relationships (SR) with other subjects, a backfill record with BACKFILL_PROCESS_TYPE as 'SR' is also generated.
  3. Deactivation post endpoint: normally generates the same types of backfill queue records as the edit endpoint except when the deactivation effective term is the same as the subject creation term, a backfill record with BACKFILL_PROCESS_TYPE = 'SD' will be created
  4. Requisite post endpoint: generates backfill queue records with BACKFILL_PROCESS_TYPE='RQ'
  5. Backdate (SCASUBJB) post endpoint: generates backfill queue records with BACKFILL_PROCESS_TYPE='BD', backfill queue record with BACKFILL_PROCESS_TYPE as 'SR' will be generated if subject has scheduling relationships with other subjects.

What are the major components in each backfill queue records that provides data necessary for the backfill process?

The post endpoints calculates the data required for the backfill processing and update the data to the PREVIOUS_DATA and NEW_DATA elements in the SUBJECT_BACKFILL_QUEUE record. Both are defined as CLOB in the database and the data in both elements are formatted as JSON. The PREVIOUS_DATA is a SNAPSHOT of what the edited subject looks like before the update and the NEW_DATA represents what the data of the edited subject will be after the update with its related subject(s). All post endpoints will invoke a subject search before any update processing to create a flow variable: flowVars.subjectTemplateSearchResults and use that to compose the PREV_DATA element. Depending on the post endpoint being invoked, the Subject Management API will use either flow variable that saved the request json data as basis to compose the NEW_DATA component. The details in the PREVIOUS_DATA and NEW_DATA for will roughly follow the format of the elements in the flow variables used to compose the PREVIOUS_DATA and NEW_DATA with the following exceptions:

  1. url data is included, other display control data is not included
  2. "crossListSubjects" : the main subject id is added to the list of cross list subjects
  3. "equivalentSubjects": To update the legacy table SCREQIV properly, the backfill process needs a different set of information than the CTSS equivalency data (data stored in SUBJECT_CONTAINER_EQUIV). The backfill needs to know about the subjects that are equivalent in the CTSS (direct equivalency), but it also needs to know about the prior equivalencies of any of the equivalent subjects (indirect equivalency). Example: Subject A used to be equivalent to Subject B. An equivalency is now added between Subject A and Subject C. Since A's equivalency with B has ended, the CTSS will not consider B and C equivalent, but the backfill process needs B to be included in the equivalency cluster. Because the backfill needs all of the subject numbers involved, the equivalencies are listed by subject number rather than container. All of the main and crosslisted numbers from the relevant templates of any of the directly or indirectly equivalent containers are included. The relevant templates are those whose effective term range overlap with the term range of the equivalency. When the same number is on consecutive templates, the information is consolidated into a single entry.
  4. "subjectRelationships": The subject relationships are listed by subject number rather than container. All of the main and crosslisted numbers from the relevant templates of the containers in the subject relationship are included. The relevant templates are those whose effective term range overlap with the term range of the relationship. When the same number is on consecutive templates, the information is consolidated into a single entry.
  5. "pastSubjectData" : this section exists in the NEW_DATA of the backfill queue for subject edit and reactivate endpoints. It includes all the cross listed, equivalent and subject relationship subject ids that are outside of the respective effective terms and do not exist in respective components in the subject template sections. The effective terms of each subject here are also consolidated.

The following are some samples JSON(s) that show the data stored in the PREVIOUS_DATA and NEW_DATA elements:

  1. JSON used to update PREVIOUS_DATA for backfill queue record with BACKFILL_PROCESS_TYPE=null
    Show/hide PREVIOUS_DATA for BACKFILL_PROCESS_TYPE=null
  2. JSON used to update NEW_DATA for backfill queue record with BACKFILL_PROCESS_TYPE=null
    Show/hide NEW_DATA for BACKFILL_PROCESS_TYPE=null
  3. JSON used to update PREVIOUS_DATA for backfill queue recod with BACKFILL_PROCESS_TYPE='SR'
    Show/hide PREVIOUS_DATA for BACKFILL_PROCESS_TYPE='SR'
  4. JSON used to update NEW_DATA for backfill queue record with BACKFILL_PROCESS_TYPE='SR'
    Show/hide NEW_DATA for BACKFILL_PROCESS_TYPE='SR'

Is different post endpoint set different value for the BACKFILL_PROCESS_TYPE ?

Yes..and No..Some endpoints will generate backfill records with a specific value set for BACKFILL_PROCESS_TYPE, but some endpoints will generate backfill records with the same value set for BACKFILL_PROCESS_TYPE. The following details the endpoints and the specific BACKFILL_PROCESS_TYPE value it will set for the backfill queue records the endpoint generated:

What are the corresponding usedKey records associated with each backfill queue record?

For each backfill queue record, there are one to more associated records in the SUBJECT_BACKFILL_QUEUE_USEDKEY table (with the same QUEUE_ID). These records are used by the backfill process to quickly identified all subjects involved in an update triggered via a queue record. The following are possible usedKey records that will be generated by a post endpoint call:

  1. Main subject id :
    1. main subject id in current template has relationship type set as 'M'.
    2. main subject id in the PREVIOUS_DATA and pastSubjectData component in the NEW_DATA has relationship type set as 'C'
  2. Cross list subjects : both current and past cross list subject id(s) in the PREVIOUS_DATA and pastSubjectData component, and the main subject id(s) in the PREVIOUS_DATA and pastSubjectData has relationship type set as 'C'.
  3. Equivalent Subjects(EQ) : current and past EQ subject id(s) in the PREVIOUS_DATA and pastSubjectData component has relationship type set as 'E'.
  4. Equivalent and Scheduling Related (EQSR/SR) subjects : current and past EQSR subject id(s) in the PREVIOUS_DATA and pastSubjectData component, has relationship type set as 'S'.

More detailed information

More detailed information about the backfill records generated via the subject management API endpoints can be found in attached document

Error Handling

Validation and bad request errors

For get requests, the subject management API returns a 400 response if it cannot find the resource that matches the criteria in the request. The cause for not being able to locate the data can be

  • the requested subject or the requested subject and term data does not exist in the system
  • the request criteria has incorrect data.

For post requests, the subject management API validates the subject data in the request json to ensure the update does not violate the subject management business rules. If there is any validation error, the API returns a 400 response with a list of errors in the response body. The API also writes the error into the API_PROCESS_LOG table.

Exception Handling Mechanism

For each request, the subject management API initiates separate transactions for

  • the updating of the CTSS and the subject backfill queue tables
  • the updating of the API_PROCESS_LOG table

These transactions are independent of the cim inbound feed and backfill processing. When the subject management API encounters an exception while processing a post request, the exception is handled via exception strategy: API_Item_Exception _Strategy which rolls back all updates to the CTSS and backfill queue tables. The API then records the exception by inserting a record with this exception information to the API_PROCESS_LOG table which is encapsulated in a separate transaction (logics in flow : API-process_log-add-all-process-log-entries).

Besides the API_Item_Exception_Strategy, the API_Process_log_Exception_Strategy is created for the Subject Management API to handle the exception encounters when updating the API_PROCESS_LOG. The API_Process_log_Exception_Strategy updates the error information to the response only without recording the error in the API_PROCESS_LOG.

All exception strategies implemented for subject management API can be found in Mule config file: exception-handlers.xml.

Troubleshooting

The following are information that will help troubleshoot when there is problem or error when the API is updating the subject data:

  • API includes the validation errors and exception in the response, which gives additional information about the error. 
    {
    "errorCode": 400,
    "errorMessage": "error",
    "errorDetails": [
        {
            "message": "Error: Invalid main subject code and number : 1.TT13 already exists "
        }
    ],
    "apiRefId": 21922
}
  • For each post request, the API inserts records to the SUBJECT_API_PROCESS_LOG table to record the processing details of the request.The processing details being recorded include validation errors (if applicable), exception (if applicable), and also subject components being updated (like an EQ is added). All SUBJECT_API_PROCESS_LOG records generated for a post request have a common reference - a unique api reference number. The API reference number is acquired from a sequence (SUBJECT_API_PROCESS_LOG_ID_SEQ) by the API for each post request, and is included in the response of each post request .
  • The reference number is also used to populate the API_REF_ID of subject_backfill_queue record when the API generates the backfill record for the request. The CIM inbound feed processing and backfill processing also record this reference number in the logging/supporting tables (like SUBJECT_BACKFILL_LOG, SUBJECT_CIM_INBOUND_EXT_OPS, etc) generated via these processes. We can have the full picture of each update request for a particular subject by looking up the logging tables generated by all these 3 processes with the same reference number.
  • The SUBJECT_API_PROCESS_LOG records can also be searched by subject container and record creation time to locate information of a particular request.

Term Plan and Display Control Update Processing

Separate endpoints for term plan and display control endpoints are developed to cater to the requirement of the term plan app, which updates term plan and display control data effective for an academic year. Depending on the effective terms of the change and the effective terms of the existing templates, updating term plan and display control data for an academic year might involve updating one to multiple templates at the same time.

Besides updating the term plan and display control data, the term plan and display control update endpoints also compose and update the data needed to generate the subject notifications to the SUBJECT_NOTIFICATION_SUPPORT table.

Subject Notification Processing

The subject notification endpoint retrieves the notification data from the SUBJECT_NOTIFICATION_SUPPORT table for the notification id(s) in the request and generate the relevant subject notifications. After the notifications are processed, the endpoint will delete the record from the SUBJECT_NOTIFICATION_SUPPORT table. If there is an error when generating the notifications, the error information is included in the response and a record with the error is inserted to the API_PROCESS_LOG.

The design to have a separate endpoint is that the term plan and display control update endpoints set up the data, while a separate endpoint generates the notifications. The de-coupling of the processes ensures that the failure of sending the notifications will not impact the update of the term plan or display control data.

For more details about the notification emails generated by Term Plan edits, refer to the Term Plan User Interface KB page.

Requisite Update Processing

A separate endpoint is created for requisite updating. For more information, please refer to the subject requisites page

Subject Management Documentation Index

The Subject Management Documentation Index is the central listing for documentation pertaining to Subject Management.

IS&T Contributions

Documentation and information provided by IS&T staff members →

Last Modified:

April 05, 2019

Get Help

Request help
from the Help Desk
Report a security incident
to the Security Team
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
Feedback
This product/service is:
Easy to use
Average
Difficult to use
This article is:
Helpful
Inaccurate
Obsolete
Adaptavist Theme Builder (4.2.3) Powered by Atlassian Confluence 3.5.13, the Enterprise Wiki