This page describes the common field definitions that are available for inclusion in the grade extract payload. The actual field definition that should be placed in the Data Value field can be found at the bottom of each "description" cell.
- Course Fields
- User Fields
- Grade Fields
- Grade Center Item Fields
- Membership Fields
- Static Value Field
- Special Derived Values
Course Fields
| Field | Description |
|---|---|
| Primary Key | The internal Blackboard identifier for the course. This value is an auto-incrementing integer that is generated by the Blackboard schema when a course is created and generally has no meaning outside of Blackboard. Course.getId |
| External Course Key | A non-user-facing unique identifier that is generally populated via Snapshot or similar integration. If a course is created through the GUI, the “External Course Key” will match the “Course Id.” This field is also known as the batch_uid. Course.getBatchUid |
| Classification | The title of the classification of this course. Course.getClassification.getTitle |
| Course Id | The unique, user-facing identifier for the course. Course.getCourseId |
| Availability | “Y” if the course record is available, “N” if it is unavailable. Course.getIsAvailable |
| Type | “FULL” for normal courses, “COMMUNITY” for organizations. Other values may exist for internal courses, such as “SYSTEM;” however, grades from these courses would not exist. Course.getServiceLevelType.toFieldName |
| Create Date | The date the course was created. Course.getCreatedDate |
| Modified Date | The date the course was last modified. Note that this only refers to the modification of the course record itself and NOT any content, assignments, etc. Course.getModifiedDate |
| Title | The user-facing title or “course name” of the course. Course.getTitle |
| Category Ids | Delimited list of all course category Ids (if any) for the course. The sub-delimiter is configured in the extract properties. Example (assuming pipe sub-delimiter): Course.CATEGORY_IDS |
| Category Names | Delimited list of all course category names (if any) for the course. The sub-delimiter is configured in the extract properties. Example (assuming pipe sub-delimiter): Course.CATEGORY_NAMES |
User Fields
| Field | Description |
|---|---|
| Primary Key |
User.getId |
| External Person Key | A non user facing unique identifier that is generally populated via Snapshot or similar integration. If a user is created through the GUI, the “External Person Key” will match the “User Id”. This field is also known as the batch_uid. User.getBatchUid |
| Business Phone 1 | Primary business phone for the user. User.getBusinessPhone1 |
| Business Phone 2 | Secondary business phone for the user. User.getBusinessPhone2 |
| Company | Company of the user. User.getCompany |
| Country |
User.getCountry |
| Department | Department of the user. User.getDepartment |
Email address of the user. User.getEmailAddress | |
| Last Name | User’s last or “family” name. User.getFamilyName |
| First Name | User’s first or “given” name. User.getGivenName |
| Home Phone 1 | Primary home phone of the user. User.getHomePhone1 |
| Home Phone 2 | Secondary home phone of the user. User.getHomePhone2 |
| Availability | “Y” if the user record is available, “N” if it is unavailable. User.getIsAvailable |
| Job Title | User’s job title. User.getJobTitle |
| Last Login Date | Date of the user’s last successful login to the system. If the user has never logged in, this value will be empty. User.getLastLoginDate |
| Middle Name | User’s middle name. User.getMiddleName |
| Mobile Phone | User’s mobile phone number. User.getMobilePhone |
| Student Id | Student Id attribute of the user record. Not that this value is NOT guaranteed to be unique in the system. Only username and external person key are guaranteed unique fields. User.getStudentId |
| Title | Title of the user. Ex: Mr. Mrs. Dr. User.getTitle |
| User Id | The unique, user-facing identifier of the user. Also known as the username. User.getUserName |
| Institution Role Ids | Colon delimited list of all institution role Ids for the user. The primary role id will be first, followed by all of the secondary role Ids (if any) for that user. User.INSTITUTION_ROLE_IDS |
| Institution Role Names | Colon delimited list of all institution role names for the user. The primary role name will be first, followed by all of the secondary role names (if any) for that user. User.INSTITUTION_ROLE_NAMES |
| Primary Institution Role Id | The Id of the primary institution role for the user. User.PRIMARY_INSTITUTION_ROLE_ID |
| Primary Institution Role Name |
User.PRIMARY_INSTITUTION_ROLE_NAME |
| Secondary Institution Role Ids | Colon delimited list of all secondary role Ids (if any) for the user. User.SECONDARY_INSTITUTION_ROLE_IDS |
| Secondary Institution Role Names | Colon delimited list of all secondary role names (if any) for the user. User.SECONDARY_INSTITUTION_ROLE_NAMES |
| System Role Ids | Colon delimited list of all system role Ids for the user in the DEFAULT domain. The primary system role id will be first, followed by all of the secondary system role Ids (if any) for that user. User.SYSTEM_ROLE_IDS |
| System Role Names | Colon delimited list of all system role names for the user in the DEFAULT domain. The primary system role name will be first, followed by all of the secondary system role names (if any) for that user. User.SYSTEM_ROLE_NAMES |
| Primary System Role Id | Id of the primary system role for the user. User.PRIMARY_SYSTEM_ROLE_ID |
| Primary System Role Name | Name of the primary system role for the user. User.PRIMARY_SYSTEM_ROLE_NAME |
| Secondary System Role Ids | Colon delimited list of all secondary system role Ids (if any) for the user in the DEFAULT domain. User.SECONDARY_SYSTEM_ROLE_IDS |
| Secondary System Role Names | Colon delimited list of all secondary system role names (if any) for the user in the DEFAULT domain. User.SECONDARY_SYSTEM_ROLE_NAMES |
Grade Fields
The fields in this section are used to access information related to a student's grade on a particular item (or column) from the Blackboard Learn Grade Center.
| Field | Description |
|---|---|
| Primary Key | The internal Blackboard identifier for the grade. This value is an auto-incrementing integer that is generated by the Blackboard schema when a user is created and generally has no meaning outside of Blackboard. Grade.getId |
| Attempt Grade | The visual grade of the latest attempt against the gradable item for the enrollment. If the grade is not an assignment or assessment, there will only be one attempt. Grade.getAttemptGrade |
| Attempt Score | The decimal points of the latest attempt against the gradable item for the enrollment. Grade.getAttemptScore |
| Attempt Date | The date the attempt was created. For assessments and assignments, this is the date the item was created by the learner. For manually entered grades (i.e. entered directly in the Grade Center spreadsheet), this is the date the instructor provided the grade. Note that this should NOT be confused with the instructor-entered override date, which is a different field. Grade.getLastAttemptDate |
| Attempt Status | The numeric representation of the attempt status:
Grade.getStatus |
| Manual Grade | The display value of a manually overridden grade for the student. If the grade was not manually overridden, this value will be empty. Grade.getManualGrade |
| Manual Score | The decimal points of a manually overridden grade for the student. If the grade was not manually overridden, this value will be empty. Grade.getManualScore |
| Display Grade | The value of the grade as it is displayed in the Grade Center. This value accounts for multiple attempts and manually overridden grades. In most cases, this is the value that you want to include in the extract. Grade.getSchemaValue |
| Display Score | The decimal point value of the grade in the Grade Center. This value accounts for multiple attempts and manually overridden grades. In most cases, this is the value that you want to include in the extract. Grade.getScoreValue |
| Exempt Indicator | “Y” if the grade has been exempted by the instructor, “N” otherwise. Grade.isExempt |
| Extract Date | The date and time that the extract ran. Grade.getGradeExtractDate |
| Null Grade Indicator | “Y” if the grade does not exist, “N” otherwise. Grade.isNullGrade |
| Manual/Override Grade Indicator | “Y” if the grade has been manually overridden by the instructor, “N” otherwise. Grade.isOverridden |
| Modified Date | The date the the grade was last modified. Grade.getGradeModifiedDate |
| Override Date | The date the grade was overridden by the instructor. Note that this is NOT the same as just a manually assigned grade through the Grade Center spreadsheet, but the date an actual override grade was specified (added or updated). Grade.getOverrideDate |
Grade Center Item Fields
The fields in this section apply to the items (or columns) of the Grade Center.
| Field | Description |
|---|---|
| Primary Key | The internal Blackboard identifier for the gradable item. This value is an auto-incrementing integer that is generated by the Blackboard schema when a user is created and generally has no meaning outside of Blackboard. Item.getId |
| External Grade Indicator | “Y” if the item is the external grade for the course. “N” otherwise. Note that there can only be one item marked as the external grade per course. Item.IS_EXTERNAL_GRADE |
| Display Description | The user-facing description of the gradable item. Item.getDescriptionForDisplay.getText |
| Display Column Name | The display column name is a required value in the Blackboard grade center and will be the value that is displayed to end-users UNLESS a display title has been provided. Item.getDisplayColumnName |
| Points Possible | Decimal number representing the number of possible points for the gradable item. Item.getDisplayPoints |
| Display Title | The display title is not required; however, if it is provided for an item in the grade center, it will be displayed to end users in place of the “display column name”. Item.getDisplayTitle |
Membership Fields
| Field | Description |
|---|---|
| Primary Key | The internal Blackboard identifier for the enrollment. This value is an auto-incrementing integer that is generated by the Blackboard schema when a user is created and generally has no meaning outside of Blackboard. Member.getId |
| Availability | “Y” if the enrollment record is available, “N” if it is unavailable. Member.getIsAvailable |
| Enrollment Date | The date the user was enrolled in the course. Note that this value may be null if the enrollment date was not explicitly provided with the integration. Member.getEnrollmentDate |
| Modified Date | The date the enrollment record was last modified. Member.getModifiedDate |
| Last Access Date | The date the user last accessed the course. This value will be null if the user has not accessed the course. Member.getLastAccessDate |
Static Data Field
| Field | Description |
|---|---|
| Static Value | Allows the inclusion of static content to the column mapping, where XXX is the value of the static content to be included. This field allows special characters to be included as part of the static value. The special characters need to be configured as their encoded value. For example: ::static::XXX |
Special Derived Values
The fields in this section are special fields that derive their values from other fields.
| Field | Description |
|---|---|
| Grade.PERCENTAGE_SCORE | This value will contain the points divided by the points possible only if it can be calculated. Otherwise, it will be blank. |
| Grade.LETTER_GRADE | This value will be the schema value only if a letter is present. Otherwise, it will be blank. |
| Item.EXTERNAL_SEQNUM | This value will be the value specified in the external sequence mapping. |
| User.OPTIONAL_DATA:XXX | This value will be the value of the user enrollment optional data as specified in XXX. Ex: If the inbound provisioning is passing an optional data field COHORT with the user enrollment data, the implementation to include in the extract would be: User.OPTIONAL_DATA: COHORT |
| Grade.OPTIONAL_DATA:XXX | This value will be the value of the grade optional data as specified in XXX. Ex: If the inbound provisioning is passing an optional data field PartTerm with the gradeable item, the implementation to include in the extract would be: Grade.OPTIONAL_DATA:PartTerm |
| Grade.getCategoryName | This value will be the grade category name (i.e. Assignment). |
| User.EXTRACTOR_BATCH_UID | This value will be the batch_uid of the user who approved the extraction. |
| User.EXTRACTOR_USER_ID | This value will be the user id of the user who approved the extraction. |
| User.EXTRACTOR_FULLNAME | This value will be the full name of the user who approved the extraction. |
| User.EXTRACTOR_EMAIL | This value will be the email of the user who approved the extraction. |
| User.GRADER_FULLNAME | This value will be the full name of the last grader of the gradable item. |
| User.GRADER_EMAIL | This value will be the email of the last grader of the gradable item. |
| Course.TERM_CODE | This value will be the Name of the term the course section is associated with. |
| X::regEx:Y | The value will be the result of the regular expression specified by Y for the field X. Ex: Course.getBatchUid::regEx:^.*?_(.*?) where the course batch_uid is 202210_12345 would return 12345 |
| Grade.getPostedDate | This value will be the posted date (for Ultra courses). |
| Term.getSourceId | This value will be the Source ID of the term the course is associated with. |
