Gradebook Extracts are fully automated extracts that do not require grades to be approved to be included in the extract. To access the Grade Extract Settings for a gradebook extract:

  1. Sign in to Blackboard.
  2. Access the Administrator panel.
  3. Select Platform Extensions from Cloud Management.
  4. Choose Edit Settings from the Grade Export v2 menu.
  5. Choose the magnifying glass in the Configure column on the GRADEBOOK_EXTRACT row you want to configure.

This will give you access to the Grade Extract Settings tab. This tab has six expandable sections.

  • General Settings—set the integration type, set the schedule, and indicate the valid grades
  • Term Filter—indicate which terms will be included in the extract
  • Course Filter—indicate which courses will be included in the extract
  • Column Filter—indicate which grade columns will included in the extract
  • Column Mapping—set the mapping of field names to the Blackboard data that will be extracted
  • Result Transfer Settings—input the institution location where the extract files will be delivered

General Settings

  1. Choose the Integration Type.
    • NORMAL Integration: delimited file format
    • REST Integration: Grades Journey-specific JSON format
    • Legacy Banner Integration: Legacy Banner REST API  format
  2. The CRON Schedule determines how often the approved grades file is extracted. Enter a valid 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. Specify a comma-separated list of grades that will be considered valid grade values in the Valid Grades field. These should be letter grades, not numbers. If a grade value is not valid, it is not included in the extract and triggers an email notification. Records that are excluded from the extract because they are invalid are added to a file that is attached to the email notification.

    If you leave this box blank, all grades are considered valid.

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

 

Term Filter

  1. Turn on the Enabled toggle to filter the extract by term.
  2. Select ADD or DELETE to add or delete rows.
  3. In the TERM column, select the terms by which you want to filter the extract. Only courses associated with the selected terms will be included in the extract.
  4. Enter an effective date and a stop date in the appropriate columns. Data will be extracted from courses that are associated with the given term if the current date is between the effective date and the stop date. The dates can be left blank and the extract will not be date-limited.

Course Filter

Courses to be included in the extract must meet all of the configured criteria.

  1. Turn on the Only Available Courses toggle to only include data from available courses in the gradebook extract.
  2. Search for courses that will be included in the grade extract. Put in your search parameters, and any courses that are returned will be included. You can search based on:
    • Batch UID
    • Course ID
    • Course Name
    • Data Source Key
    • Term
    • Course Creation Date
    • Course Date Range
  3. Enter a comma-separated list of course IDs that you do not want to be included in the gradebook extract in the Course Exclusion List box.

Column Filter

The column filter is used to determine which grade columns are extracted.

  • Column Filter Fill in this box if you want to extract only specific columns 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 extract only the external grade column (in Original courses) or overall grade (in Ultra courses). This setting takes precedence over the Column Filter setting and the Provisioning Enabled setting. If you have this selected, it is the only grade column that will be extracted.
  • Provisioning Enabled Select this checkbox if you want to extract only grade columns imported as part of the gradable items provisioned from the SIS. This setting takes precedence over the Column Filter setting.
  • Include only rows since last run Select this check box if you want to only include grade column records where the grade value has changed since the last extract.
  • Exclude ‘All’ calculated columns Select this checkbox in combination with the previous column filter to prevent calculated columns f rom being included in the grade extract when the column value changes.
  • Exclude ‘All’ records having empty grades Select this checkbox to prevent records with no grade value from being included in the gradebook extract.
  • 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 field is left empty, a default list of fields will be passed in the extract.

More on the default extract

An example mapping is:

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

Additional Column Mapping

Turn on the Enable toggle for each of the following Additional Data fields if you want to include them in the extract:

  • Last Attendance Date The last date an assignment or assessment attempt has been created. The header value can be modified by updating the EXTRACTION KEY field. The default value is last_attendance_date.
  • Instructor Feedback The comment provided by the instructor or approver on a calculated grade column. The header value can be modified by updating the EXTRACTION KEY field. The default value is instructor_comment. This setting will not normally apply to the Gradebook extract given the Instructor Feedback is supplied within the approval workflow.

Result Transfer Settings

NORMAL Integration option

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.

    More on transfer methods.

  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
  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 ( “ ).

REST integration option

Result Transfer Settings

  1. Specify the endpoint for the grades to be posted in the Post Webservice Endpoint field.
  2. Enter the maximum number of records to be included in one transaction in the Maximum Rest Records field. 

Rest (Outgoing) Security Options

Select Yes to Enable Secure REST API. If enabled, also set a Security Mechanism.

OAuth 1.0
  • Shared Secret: enter the OAuth shared secret
  • API Key: enter the OAuth API key
MAC Security

More on MAC Security

  • Shared Secret: enter the shared secret
  • API Key: enter the API key
  • Timestamp parameter: enter the parameter that will indicate the timestamp value in the query string
  • MAC parameter: enter the parameter that will indicate the MAC value in the query string
  • API Key Parameter: enter the parameter that will indicate the MAC value in the query string
OAuth 2.0

Grade Export will make a request to the REST token URL configured endpoint. Authorization will be sent as a request header. Grant type will be client_credentials and sent in the request body: grant_type: "client_credentials".

  • REST Key: Enter the key that will be used to access the API
  • REST Secret: Enter the secret that will be used to access the API
  • REST Token URL: Enter the URL that will be used to request an access token

Select Submit to save your choices.