The approval workflow, if enabled, is configured to run on a specific schedule and automatically extracts the grades that have been approved. To access the Grade Extract Settings for the approval workflow:

  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 APPROVAL_WORKFLOW row.

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

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

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.

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.

Extract Course Role Settings

  1. Turn on the Enable Submitter Workflow toggle to add an additional step to the workflow where grades are submitted to an approver (for example, a teaching assistant submits the grades for the instructor to approve).
  2. 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). If desired, also specify any additional Institutional Roles that are required to approve grades (such as Grade Approver). A user with any of these roles will be able to approve grades.

  3. For Roles Required to Submit, specify the course roles that will be required for a User to be able to launch the approval process to submit grades (such as Teaching Assistant). If desired, also specify any additional Institutional Roles that are required to submit grades (such as Grade Submitter). A user with any of these roles will be able to submit grades.

    This setting will only display if the Submitter Workflow is enabled.

  4. The access denied message should not be filled in here; the custom access denied message is now entered on the Configure Roles screen.

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

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

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

Fill in the following fields:

  • 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

Grade Approval and Transfer Settings

Grade Approve 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 enable the Extract button 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. 

    The extract button will always be enabled  for administrators.

  3. Select Submit Grades Button Enabled? to enable the Submit button for Submitters. 

    If the submitter workflow is disabled, this checkbox will be hidden.

    The submit button will always be enabled for administrators if the submitter workflow is enabled.

  4. Select Only allow approvals for submitted grades to prevent grades with a status different than submitted from being approved or unapproved.

    If the submitter workflow is disabled, this checkbox will be hidden.

  5. Select Enable Instructor Feedback if the Instructor Feedback column should be available to instructors in the Grade Approval area on grades associated with calculated and manual columns.
  6. Select Allow course search for Grade Approvers? if the Advanced Search link should be visible to instructors in the Grade Approval area so they can search for a different course they are assigned to.

  7. Select Approve Grades button enabled? to enable the Approve grades button for approvers.

    The Approve button will always be enabled for administrators.

  8. Select Only allow unapprovals with reason message? to prevent grades from being unapproved in the Grade Approval and Transfer tool if a reason has not been entered.

    If the submitter workflow is disabled, the checkbox will be hidden.

  9. Select Limit child course access to only submitters or approvers to limit submitters or approvers to only seeing students at the grade level for child courses that they are assigned to.
  10. Select Restrict operations to the grade level to disable all grade approval actions at the course and grade column level. Submitters and approvers will only be able to take action at the grade level.
  11. The Launch directly to grade level setting is for an upcoming feature for the approval workflow and should not be selected.
  12. 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 value is a letter, then it returns a letter grade; otherwise, it will return 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 (Original)

The following options apply only to the Original course experience. The options available for the Ultra course experience are covered in the next section.

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

    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.

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

  • Page Title: 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
  • 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 locking, even if unapproved grades exist

  • 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

    System Administrator is the only role that will always be able to access the full Grade Transfer and Approval page.

Grade Center Read-Only (Ultra)

The following options apply only to the Ultra course experience. The options available for the Original course experience are covered in the preceding section.

You can lock the course grades center and redirect users trying to access grades to a read only page. For Lock on Approval, you have the following options:

  • Immediately On Approval: this option does not apply to the Ultra Read-Only view

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

    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.

    You can unlock the course temporarily if necessary after the locking job is complete.

  • Disabled: do not lock the grades center.

Turn on the Enhanced Read-Only Features toggle to set up the Lock Grade Column Name and time to lock course for Ultra courses.

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

None of the other Enhanced Read-Only Features will apply to Ultra Courses.

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.