Configure the Gradebook Extract

After the Grade Export feature has been enabled successfully, you must configure the gradebook extract settings.

Configure the Grade Extract Settings for Grade Export

Sign in to Blackboard Learn with a user account with system admin privileges.
Access the Admin Panel.
Select Platform Extensions under Cloud Management.
Choose Edit Settings from the context menu for Grade Export V1.
Be sure the Grade Export Availability toggle is enabled. You will see a Grades Journey Features toggle that is not enabled; the text contains more information about the Grades Journey extension that is available with a paid engagement.

Select the Grade Extract Settings tab and choose the NORMAL Integration Integration type.

The Grade Extract settings are divided into six expandable sections.

General Settings	Set the integration format type, enable the extraction, and set the schedule.
Column Filter	Set the grade columns that will be displayed in the approval workflow.
Column Mapping	Set the mapping of the field names to the Blackboard Learn data extracted.
Extract Course Role Settings	Set the roles that can approve or extract grades.
Result Transfer Settings	Set the institution location (SFTP) where the extract will be delivered.
Grade Approval and Transfer Settings	Set the Approval workflow options, grade display, Read-Only options for Original courses, and LTI location.

General Settings

Integration Type	NORMAL: Delimited file format (choose this setting for the Grade Export feature) REST (Grades Journey-specific JSON format)
Enabled?	Toggle on to have the process run on the configured CRON schedule.
CRON Schedule	Enter a CRON expression to determine the frequency of the background extracts. Example: 0 0 * 1 / 1 * ? * (every hour)
Rounding number	Choose the maximum number of decimal places you want to appear for the score (or the Grade.getAttempt.Score method is used if custom mapping is used)
Extract Value for Unmarked Assessments	Choose the null value you want to be returned for unmarked, ungraded items or fields that have no value stored (for example, "0" or "no value").

Column Filter

Only one filter option can be used at a time.

Column Filter	If the approval and extract columns list displayed to the instructor should be limited to specific grade columns when provisioning is disbled, enter a comma-separated list of the grade column names here. The purpose of this setting is to allow the extract to contain only those columns that need to be reported.
External Grade Column or Overall Grade Only	Select if the approval and extract columns list displayed to the instructor should be limited to the course external grade column (the column marked in the grade center as External Grade). NOTE: This setting takes precedence over the Column Filter guide.
Provisioning Enabled	Select if the approval and extract columns list displayed to the instructor should be limited to those imported as part of the gradable items provisioned from the SIS.

Column Mapping

Enter a list of name/value pairs separated by a pipe symbol to identify the grade column data fields to include for each record in the report. If left empty, a default list of fields will be passed in the extract.

An example mapping:

external_course_key=Course.getBatchUid|External_person_key=User.getBatchUid|student_id=User.getStudentId|column=Item.getDisplayColumnName|grade=Grade.getSchemaValue

Default extract example:

Extract Course Role Settings

Roles Required to Approve	Course Roles: Specify the course roles that will be required for a user to be able to launch the approval process to approve grades (i.e., Instructor). Institution Roles: Optionally, specify additional Institutional Roles that are also required (i.e., Grade Approver)
Access Denied Message	Enter the message that should be displayed for users who attempt to launch the approval process but do not have the correct roles.

Result Transfer Settings (NORMAL Integration Method)

Result Transfer Settings

Filename Mask	Set the pattern for the extract filename. (When the Transfer Type is set to Combined File, the filename will have "combined_" added to the front of it.)
Transfer Method	Set to SFTP.
Transfer Type	Set the Transfer Type. Each File will result in one extract file per course being transferred individually. Combined File will send one file with all Approved rows for all courses. NOTE: A manual extract from within a course will generate a course-specific extract file.
Use Windows EOL	Enable if this will be processed on a Windows environment requiring Windows EOL.
Server	Enter the URL or IP of the SFTP server.
Port	Enter the SFTP server port (typically 22).
Username	Enter the SFTP username.
Password	Enter the SFTP password.
Path	Enter the path for the extract file.

Extract File Format (NORMAL Integration Method)

Field Delimiter	The delimiter to use for the extract file. The default is a pipe ( \| ).
Field Qualifier	The character to use if the data extracted contains the delimiter. The default is double quotes ( " ).
Format for Dates	Formatting for any date fields included in the extract. Uses Java SimpleDateFormat.

Grade Approval and Transfer Settings

Grade Approval Required	Enable if you want grades to be approved at the column or grade level.
Perform Extract Button Enabled?	Enable if you want graders/instructors to be able to run the extract immediately. An extract will only be generated and sent when the Transfer Type is set to Each File.
Approve Grades Button Enabled?	Enable to allow any course role configured as an approver to have an active Approve Grades button in the workflow.

Grade Center Read-Only

The Read-Only view will only apply to the Original course experience.

Lock on Approval?

Immediately on Approval: lock course grade center and redirect users to the Read-Only page immediately after a grade for that course is approved by the Approver.
After Grade Column Due Date: lock course grade center and redirect user to the Read-Only page after the selected grade column due date has been reached.
NOTE: if this option is selected, an additional configuration field to indicate the name of the grade column for which the due date needs validation for the course(s) grade center to be locked will be displayed.
Disabled: Do not lock course grade center.

Enhanced Read-Only Features

Page Title	Optionally, enter a title that will appear on the Grade Center Read-only view page
Lock Grade Column Name	Enter the grade column whose due date will be used to determine if the grade center will be read-only.
Time to keep unlocked manually unlocked courses (Hours)	Optionally, enter a value for how long (in hours) a manually unlocked course will remain unlocked before automatically being locked.
Time to automatically lock down the Grade Center (Hours)	Optionally, enter a value for how long (in hours) the grade center must be locked down after the approval of grades event occurs.
Lock on Approval Exception (Hours)	Optionally, enter a value for how long (in hours) a role with Approver privileges can still access the grade center after the locking event.
Lock Unapproval Exception (Hours)	Optionally, enter a value for how long (in hours) a role with Submitter privileges can still access the grade center after the locking event if unapproved grades exist.
Course Role not affected by lock	Optionally, select the course role(s) that will not be redirected to the grade center read-only view page and will still be able to access the full Grade Transfer and Approval page even if it is locked. NOTE: System Administrator is the only role that will always be able to access the full Grade Transfer and Approval page.

Select one or more placements

Specify the LTI placements that will be used to run Grade Approval and Transfer tool from Original and Ultra courses. The required placements are Instructor Tool and System Tool.

Click Submit to save all your settings.

Field Definition Methods