MIT Subject Management API - System Rules
Please note that this page and related pages are being developed as part of the CIM Courses Project and are subject to change.
This page is intended to specify the needs and validations of the mit-subjects API. This API is the single gateway to create and edit MIT subjects and was developed as part of the CIM Courses Project.
# | Data Element | Grouping | Required | Validation | Notes | |
---|---|---|---|---|---|---|
Subject Code | Subject | Yes | Must be a valid value in STVSUBJ | - | ||
Subject Number | Subject | Yes | Must be in regular expression format: [A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9] [A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9] Must be alphanumeric, 1 to 3 or 4 characters. 3 if subj_code is 3 characters otherwise 4. if subject_code = 'SP': - if dept = FAS, subject number must start with 8 - if dept = ISP, subject number must start with 3 - if dept = PXL, subject number must start with 1 |
-Expects uppercase values and numbers -Currently only check subject number not exceeding 4 characters long |
||
Subject Key (Subject Code + Number) |
Subject | N/A | -Checks if identical Subject Key exists in table SUBJECT_TMPL_REG_INSTANCE - if identical subject key exists in SUBJECT_TMPL_REG_INSTANCE, API will return an error if SUBJECT_CONTAINER is different and SUBJECT_CONTAINER.last_active_term of the retrieved subject is null or later than the template effective from term |
Listed as separate data element for validation purposes only #work - impacted by (de/re)activation? |
||
(Subject Type + Code) | Subject | Yes | If subject type is cross reg, STVDEPT.STVDEPT_COLL_CODE of the dept associated with the subject code must equal to Z | |||
Subject Type | Subject | Yes | Must be in approved list of values | List of values listed in Business Rules KB article | ||
Effective Terms | Subject | Yes | -Must be a valid term in SGBGP_TERM -Comprised of Effective From term and Effective Through terms -Effective From term must be less than or equal to the Effective Through Term -Effective From term must not equal to Effective From term of any SUBJECT_TEMPLATE record that belongs to same container id -Effective Through term must be greater than or equal to Effective From Term -Effective Through term must not equal to Effective Through term of any SUBJECT_TEMPLATE record that belongs to same container id -Effective Terms of a template must not overlapped with effective terms of another SUBJECT_TEMPLATE record that belongs to same container e.g. Adding template effective from 2017FA through 2018SP to Container A will result in error if Container A has a template effective 2018FA-999999 |
|||
Subject Title | Subject | Yes | Cannot be longer than 255 characters | #work - special character handling? | ||
Transcript Title | Subject | Yes | -Cannot be longer than 30 characters -Must be equal or shorter than Subject Title |
- | ||
Alternate Title | Subject | No | Cannot be longer than 255 characters | #work - special character handling? | ||
Department Code | Subject | Yes* | -Must be a valid value in STVDEPT -Must match mapping in STVSUBJ *If Subject Type is "Cross Registration", Department must be empty *if Subject Code is 'SP', the department must of one of the following: FAS,PXL,ISP |
-Valid values for department codes for SP subjects are defined in element: sp.subjects.valid.departments in properties file | ||
Status | Subject | -Must be equal to one of the following: Active, Inactive |
Hardcoded values | |||
Variable Unit | Units | Yes | Database field is variable_units - must be "Y" or "N" | - | ||
Fixed Units - Lecture | Units | Yes* | -Must be not be greater than zero if variable_units = "Y" -Must be in range of [0-99] if variable_units = "N" *Required if variable_units = "N" |
- | ||
Fixed Units - Laboratory | Units | Yes* | -Must be not be greater than zero if variable_units = "Y" -Must be in range of [0-99] if variable_units = "N" *Required if variable_units = "N" |
- | ||
Fixed Units - Preparation | Units | Yes* | -Must be not be greater than zero if variable_units = "Y" -Must be in range of [0-99] if variable_units = "N" *Required if variable_units = "N" |
- | ||
Credit Limit | Units | Yes* | -Must be not be greater than zero if variable_units = "Y" -Must be in range of [0-99] if variable_units = "N" *Required if variable_units = "N" |
- | ||
Total Units | Units | Yes* | Auto-calculated to be the sum of Lecture, Laboratory, and Preparation units if subject is a fixed-units subject -Must be not be greater than zero if variable_units = "Y" -Must be in range of [0-99] if variable_units = "N" *Required if variable_units = "N" |
|||
Subject Level | Level | Yes | -validating against table SATURN.STVLEVL | |||
Attribute Code | Attributes | No | -Attribute Code must match a value in STVATTR -Need to have at least 1 cross-listed subject if SWE attribute is entered -Attribute SUPR must be included if attribute THES or attribute UROP is present -URN Attribute must be entered if subject number = URN |
Old attributes can be saved - STVATTR has no field to flag a field as old or out of use | ||
UG Degree Audit Lab Units | Attribute | No | -if entered, the value must be between 1 and 12. | |||
Grading Scheme | Grading | Yes | -Must have at least one entry -Must contain at least one entry for each of the required grading type(s). The required grading type(s) are determined by retrieving all entries from STVGM_TYP with STVGM_TYP.GMOD_TYPE_REQUIRED equals to 'Y' |
- | ||
Grading Mode | Grading | Yes | Must match a valid value in STVGMOD | - | ||
Grading Type | Grading | Yes | -Must match a valid value in STVGM_TYP -Must be a valid type allowed for the Grading Mode entered -If FSEM attribute is present, must be a valid type for the Grading Mode - GMOD_TYPE_FRESHMAN_IND -Certain Grading Types can only appear once in the Grading Scheme. The grading type(s) that can only appear once are determined by retrieving all entries from STVGM_TYP with STVGM_TYP.GMOD_TYPE_REPEAT_IND equals to 'N' |
- | ||
Cross-listed Collaborative Indicator | Cross-listed | No | -Currently will default to false if cross-listed subject key is present and the corresponding collaborative indicator is null or empty space -Currently will be set as false if the input value is not 'Y' or 'N' or true or false |
|||
Cross-listed Subject Code | Cross-listed | No | Must be a valid value in STVSUBJ | - | ||
Cross-listed Subject Number | Cross-listed | No | -Must be in regular expression format [A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9] -Must prefixed with 8, 3, or 1 respectively for FAS, ISP and PXL departments' special (SP) subjects |
-SP dept prefix valid values are configured in elements: sp.subjects.FAS.subject.prefix; sp.subjects.ISP.subject.prefix; sp.subjects.PXL.subject.prefix in properties file | ||
Cross-listed Subject Key |
Cross-listed | No | -Subject Key must not already exist in SUBJECT_TMPL_REG_INSTANCE for a different container -Subject key must not equal to the main subject key |
|||
Equivalent Subject Key | Equivalent | No | -Subject Key(container id) must exist in SUBJECT_CONTAINER -Must not equal to the edited subject |
|||
Equivalent Effective From Term | Equivalent | No | -Must be earlier than the equivalent effective thru term -Must not be earlier than the effective from term of the earliest template of the edited subject -Must not be earlier than the effective from term of the earliest template of the equivalent subject |
|||
Equivalent Effective Thru Term | Equivalent | No | -Must be later than the equivalent effective from term | |||
Equivalent Effective Terms | Equivalent | No | -If a equivalent subject has more than one set of equivalent effective terms, they must not overlap with each other | |||
Subject Relationship Subject Container | Scheduling Relation | No | -Container id must exists in SUBJECT_CONTAINER -Must not equal to the edited subject |
|||
Subject Relationship Type | Scheduling Relation | No | -Must be equal to one of the following types: SR | -valid values for subject relationship types are defined in element: subject.relationships.types in properties file | ||
Subject Relationship Effective From Term | Scheduling Relation | No | -Must be earlier than or equal to the scheduling relationship effective thru term -Must not be earlier than the effective from term of the earliest template of the edited subject -Must not be earlier than the effective from term of the earliest template of the scheduling relationship(SR) subject -If the edited subject is inactive, must not be later than the last active term of the edited subject -If the scheduling relationship(SR) subject is inactive, must not be later than the last active term of the SR subject |
|||
Subject Relationship Effective Thru Term | Scheduling Relation | No | -Must be later than or equal to the scheduling relationship effective from term -Must not be later than the effective thru term of the last template of the edited subject -Must not be later than the effective thru term of the last template of the scheduling relationship(SR) subject -If the edited subject is inactive, must not be later than the last active term of the edited subject -If the scheduling relationship(SR) subject is inactive, must not be later than the last active term of the SR subject |
|||
Subject Relationship Effective Terms | Scheduling Relation | No | -If a Scheduling Relation subject has more than one set of scheduling relation effective terms, they must not overlap with each other | |||
Term Plan Offered Terms | Term Plan | Yes* | -One of the followings must have the value set as Y: isOfferedFall, isOfferedIAP, isOfferedSpring, isOfferedSpring for regular subjects | |||
Term Plan Frequency | Term Plan | Yes* | -Required for Standard Subjects - Valid values for frequency are: EVERY,IRREG,ODD,EVEN,RESUME_ANNUAL_ODD,RESUME_ANNUAL_EVEN |
-Valid values for term plan frequency are defined in element: term.plan.valid.frequency.values in properties file | ||
Term Plan Duration | Term Plan | Yes* | -Required for Standard Subjects - Valid values for duration are: H1,P,F,H2 |
|||
Term Plan Duration First Week | Term Plan | No | -Required only if duration equals to P(artial) - Must be greater than 0 and less than the value of Term Plan Duration Last Week |
|||
Term Plan Duration Last Week | Term Plan | No | -Required only if duration equals to P(artial) - Must be greater than 0 and greater than the value of Term Plan Duration Last First |
|||
Display Control | Display Control | Yes* | -At least one entry is required for Standard Subject | |||
Display Control Term Type | Display Control | Yes* | -At least one entry is required for Standard Subject -Must be equal to one of the following: FA, JA, SP, or SU -Must match with the terms specified for Term Plan Offered Term -Cannot enter more than 1 entry for the same term type |
-Valid values for term types for display control are defined in element: display.control.valid.termTypes in properties file | ||
Display Control Online Subject Listing Faculty Source | Display Control | Yes* | -At least one entry is required for Standard Subject -Must be equal to one of the following: CF, IA, OT |
-Valid values for online subject listing faculty source for display control are defined in element: display.control.valid.OSL.SOURCE in properties file | ||
Display Control Online Subject Listing Faculty Display Value | Display Control | No | -Required when Online Subject Listing Faculty Source equals to OT -Values entered will be ignored if Online Subject Listing Faculty Source is CF or IA |
|||
Catalog Faculty | Display Control | No | -Currently will throw an error when it is null or empty and the catalog faculty preface is not null and empty | |||
Catalog Faculty Preface | Subject | No | -valid values are "I" or 'C' | |||
Roll Faculty Indicator | Subject | No | -valid values are 'P' or 'L' | |||
Gradable Schedule Type | Grading | No | -must exist in saturn.STVSCHD_TYPE | |||
Subject Description | Description | Yes* | -required for standard subject | |||
Enrollment Limitation - limit | Enrollment Limitations | No | -must be numeric | -Currently used for Freshman Seminar Max Enrollment | ||
Enrollment Limitation - lottery | Enrollment Limitations | No | -if entered, must be equal to true, false, Y, N, null or empty space | -Currently not used in SCASUBJI or CIM Feed, so validation of this field has not been fully tested | ||
No Listener | Enrollment Limitations | No | -if entered, must be equal to true, false, Y, N, null or empty space | -Currently not used in SCASUBJI or CIM Feed, so validation of this field has not been fully tested | ||
Preferences - Custom Preference | Enrollment Limitations | No | -Currently used for the enrollment limitations in free-text format for non freshman seminar subjects | |||
Restrictions | Enrollment Limitations | No | -Currently used for enrollment limitations in text format for freshman seminar | |||
Freshman Seminar | Freshman Seminar | No | -Required if a subject has FSEM attribute -At least one seminar detail record with Type=Leader must be entered for subject with FSEM attribute -API will return an error when seminar details data is included for a subject that does not have a FSEM attribute |
|||
Seminar Details - Name | Freshman Seminar | No | -Required for each seminar detail entry | |||
Seminar Details - Department | Freshman Seminar | No | -must be entered if type is Leader | |||
Seminar Details - Type | Freshman Seminar | No | -Valid values are: Leader or Co-leader | -Valid values for department codes for SP subjects are defined in element: fsem.faculty.type in properties file | ||
Seminar Details - Bio Sketch | Freshman Seminar | No | -must be entered if type is Leader | |||
Seminar Details - Kerberos Id | Freshman Seminar | No | -Must be in regular expression format: [0-9a-zA-Z\_] -must not exceed 8 characters |
|||
Home Institution Code | Cross Registration | No | -required if subject type is Cross Registration -must exist in sfpmgr.XREG_VV_HOME_INSTITUTION |
|||
Home Organization Unit | Cross Registration | No | -required if subject type is Cross Registration and Home Institution Code is 'H' (Harvard) -must exist in sfpmgr.XREG_MIT_SUBJECT_CODE_LKP |
|||
Home Subject Id | Cross Registration | No | -required if subject type is Cross Registration -cannot have duplicate entry in sfpmgr.XREG_SUBJECT for same subject id and home institution code |
|||
Other API Error Handling
-If the API gets a THES attribute without a SUPR attribute, the API will throw an error
-If the API gets a UROP attribute without a SUPR attribute, the API will throw an error
-If the API gets an SWE attribute on a subject that has no child cross-listed subject numbers, the API will throw an error
-If the API gets a subject with a "URN" subject number and a UROP attribute but no "URN" attribute, the API will throw an error
Subject Management Documentation Index
The Subject Management Documentation Index is the central listing for documentation pertaining to Subject Management.