Skip to main content

Configure the Grade Extract

After you have successfully activated the Grade Export feature, you must configure the grade extract settings.

Configure the Grade Extract Settings for Grade Export

  1. Sign in to Blackboard.

  2. Access the Administrator Panel.

  3. Select Platform Extensions from Cloud Management.

  4. Choose Edit Settings from the context menu for Grade Export v2.

    The Grade Export v2 menu expanded to show Edit Settings, which is highlighted in orange.

  5. Be sure the Grade Export Availability toggle is selected. A Grades Journey Features toggle will appear that you cannot select; the text contains more information about the Grades Journey extension that is available with a paid engagement. For more information about the additional features available with Grades Journey, please contact your account representative.

  6. 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

  1. Choose NORMAL Integration for Integration Type.

  2. The CRON schedule determines how often the approved grades file is extracted. Turn on the Enabled? toggle if you want the process to run on the indicated CRON Schedule, then enter the CRON expression to specify the frequency of the extract.

  3. In the Decimal Places field, enter the number of digits that will be displayed after the place for score values. The value is truncated, not rounded, and the default is five.

  4. Enter the null value to be returned for ungraded, unmarked items or fields that have no value being store in the Extract Value for Unmarked Assessments field (for example, “0” or “noValue”).

  5. Enter a valid date format mask in the Format for date column field. This format will be used for any date values included in the extract. Use Java SimpleDateFormat .

Column Filter

The column filter is used to determine which grade columns are displayed to graders for approval. Only one filter option can be active at a time.

  • Column Filter Fill in this box if you want to display only specific columns to graders when provisioning is disabled. Enter the columns in a comma-separated list of column names. The purpose of this setting is to allow the extract to contain only those columns that need to be reported.

  • External Grade Column (Original) or Overall Grade (Ultra) Only Select this checkbox if you want to display only the external grade column (in Original courses) or overall grade (in Ultra courses) to graders. This setting takes precedence over the Column Filter setting and the Provisioning Enabled setting.

  • Provisioning Enabled Select this checkbox if you want to display only grade columns imported as part of the gradable items provisioned from the SIS to graders. This setting takes precedence over the Column Filter setting.

  • Column Metadata Validation If you choose Provisioning Enabled, a Column Metadata Validation box appears. Optionally, enter a set of key/value pairs and their expected number of occurrences in the grade column metadata to determine if the course can be extracted. If these parameters are not met, the system will return an error, and data from the course will not be extracted.

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 this box is 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:

EXTERNAL_COURSE_KEY|STUDENT_ID|BATCH_UID|TITLE|MARK|GRADE|EXTENDED_DATA
GE_ORIG_DEM|54321|demo_student2|Final Grade|85|B|Y|
GE_ORIG_DEM|12345|demo_student1|Final Grade|95|A|Y|

Extract Course Role Settings

  1. For Roles Required to Approve, specify the course roles that will be required for a User to be able to launch the approval process to approve grades (such as Instructor).

  2. If desired, also specify any additional Institution Roles that are required to approve grades (such as Grade Approver).

    A user with any of these roles will be able to approve grades.

Result Transfer Settings (NORMAL Integration Method)

Result Transfer Settings

  1. In the Filename Mask field, set the pattern for the file extract name. When the Transfer Type is set to Combined File, “combined_ “ is added to the beginning of the file name.

  2. Choose the Transfer Method. SFTP is the most common and its settings are described in these steps.

  3. Choose the Transfer Type.

    • Each file results in a single extract file per course being transferred individually

    • Combined file results in one file will all approved rows for all courses

      Note

      A manual extract will generate a course-specific extract file.

  4. Enable Use Windows EOL if this will be processed on a Windows environment requiring Windows EOL.

  5. Enter the URL or IP to the SFTP server in the Server field.

  6. Enter the SFTP server port (typically 22) in the Port field.

  7. Enter the SFTP username in the Username field.

  8. Enter the SFTP password in the Password field.

  9. Enter the path for the extract files in the Path field.

Extract File Format

  1. Enter the Field Delimiter to use for the extract file. The default is a pipe ( | ).

  2. Enter the Field Qualifier. This is the character to use if the data extracted contains the delimiter. The default is a double quote ( “ ).

Grade Approval and Transfer Settings

  1. Enable Grade Approval Required to enable grade approval at the column or grade level. If this is not enabled, grades can only be approved at the course level.

  2. Select Extract Grades Button Enabled to make the Extract button appear for approvers. Graders will be able to run the extract immediately. For a NORMAL integration, the extract will only be generated and sent when the Transfer Type is set to Each File.

    Note

    The Extract button will always be enabled for Grade Approver Admin users.

  3. Select Approve Grades button enabled? to make the Approve grades button appear for approvers.

    Note

    The Approve button will always be enabled for Grade Approver Admin users.

  4. The Launch directly to grade level setting is for an upcoming feature for the approval workflow and should not be selected.

  5. Select Include Unposted Grades to include grades that have not been posted in the grade extract. This does not include manual columns or columns where grades have been overridden but not posted yet.

Grade Display Value Configuration

Set the grade value to display in the Approval workflow:

  • Grade Letter: if the schema is a letter, returns a letter grade; otherwise, returns an empty string

  • Schema Value: returns the grade column Primary display

  • Percentage Score: returns the calculated percentage score

  • Secondary Schema Value: returns the grade column Secondary display (only applies to Original courses)

  • Score Value: returns the score value

Grade Center Read-Only

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

You can lock the course grades center and redirect users trying to access grades to a read only page. For Lock on Approval, choose one of three options:

  • Immediately On Approval: lock the grades center immediately after a grade for that course is approved by the approver

  • After Grade Column Due Date: lock the grades center after the selected grade column due date has been reached

    Note

    If this option is selected, you must enable Enhanced Read-Only Features and enter the name of the grade column whose due date will be used to determine when the grade center will be locked in the Lock Grade Column Name box.

  • Disabled: do not lock the grades center

Enhanced Read-Only Features

Turn on the Enhanced Read-Only Features toggle to set up additional read-only features for Original courses.

  • Page Title: optionally, enter a page title for the read-only page

  • Lock Grade Column Name: enter the name of the grade column whose due date will be used to determine when the grade center will be locked

  • Time to lock course: optionally, enter a time for the locking job to run. If no time is entered, the job will run at midnight.

  • Time to keep unlocked manually unlocked courses (Hours): optionally enter a value for how long (in hours) a manually unlocked course shall remain unlocked before automatically being locked again

  • 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 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

  • Course Role not affected by lock: select 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 the Grade Approval and Transfer tool from Original and Ultra courses. The Instructor Tool and the System Tool are required placements. Select Launch in New Window to have the LTI open in a separate window.

Select Submit to save all your choices.