Implement Grades Journey using SITS integration

  1. In System Admin, under Integrations, select Building Blocks.
  2. Select Installed Tools.
  3. Locate Blackboard Grade Journey Service and select Settings.
  4. Using the sections below, configure properties under each group of settings.

Assignment and grade column settings (incoming data)

Configure the following properties:

  • Schedule Job
    • Set Job Status - select Disabled
    • CRON Schedule - N/A
    • Provisioning Content Area - choose the default folder where the gradable items will be created, unless they are overridden in the transaction.
    • Content Item Provisioning Check - This setting defines the matching rule for provisioned content items. The options are:
      • No Restriction: Always adds items from the feed as new content items.
      • One-time only: Adds any given item one time only (used for LIS).
      • Update Matches By Name: Adds item on first pass and updates based on match by content item title during subsequent imports.
    • Gradable Item Provisioning Check - This setting defines the matching rule for provisioned manual grade columns or grade columns created as a result of the provisioned content items. The options are:
      • Update Matches By Name: Adds items on first pass and updates them based on match by content item title during subsequent imports.
      • Update Matches By Metadata: Adds items on first pass and updates them based on match of the value stored in a metadata attribute called "Type" included in the optional data list of the item input data record during subsequent imports.
  • Result Transfer Settings, File Format, and Grade Column Settings do not apply to REST.

When finished, select Submit.

Grade extract settings (outgoing data)

Configure the following properties:

  • Integration
    • Integration Type - Choose SITS Integration. SITS Integration results in three outgoing files, a summary, an assessment file, and a reassessment file.
    • CRON Schedule - Choose how often the background extracts occur. For example, the extracts occur each hour with this value set to 0 0/60 * 1/1 * ? *
    • Rounding Number - Choose the maximum number of fractional digits for a score.
    • Extract Value for Unmarked Assessments - Choose the null value you want to unmarked or ungraded items to return.
    • Column Filter - Select this option if the approval and extract columns list should be limited to a specified comma separated list of grade column names when provisioning is disabled. The purpose of this setting is to allow the extract to contain only those columns that need to be reported.
    • External Grade Column Only - Select this option if the approval and extract columns list should be limited to course external grade column, that is, the column in grade center marked as External Grade.

      This setting takes precedence over the Column Filter setting.

    • Provisioning Enabled - Select this setting if the approval and extract columns list should be limited to those imported as part of the Content Item and Gradable Item provisioned from 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 is included in the report:
      EXTERNAL_COURSE_KEY|STUDENT_ID|BATCH_UID|TITLE|MARK|GRADE|EXTENDED_DATA
  • Extract Course Role Requirement
    • Course Roles - Specify the course role required for a user to be able to approve grades (i.e. instructor).
    • Institutional Roles - Specify the institutional role required for a user to be able to approve grades (i.e. grade approver).
    • Access Denied Message - Enter a message for users who attempt to extract grades but do not have appropriate permission.
  • Result Transfer Settings
    • PostWebservice Endpoint - Specify the endpoint for the grades post.
    • TestingRestWebservice Endpoint - Ignore this setting (generally).
  • REST (Outgoing) Security Settings
    • Enable Secure REST API - Enable this setting if the endpoint will implement the security. If enabled, also set:
      • Shared Secret - Enter the shared key.
      • API Key - Enter the API key.
      • Timestamp Range - Do not set.
      • Timestamp Parameter - Enter the parameter for the timestamp.
      • MAC Parameter - Enter the MAC parameter.
      • API Key Parameter - Enter the API key parameter.
  • Grade Approval and Transfer Settings
    • Grade Approval Required - Enable this setting if you want grades to be approved at the column or grade level.
    • Show History Page? - Enable this setting if you do not want grade-level approval and want the history page shown when you extract from the course.
    • Perform Extract Button Enabled? - Enable this setting to allow graders to run the extract immediately.
    • Schedule Extract Button Enabled? - Enable this setting to allow graders to schedule/approve the extraction.
    • Lock on Approval? - Enable this setting to switch the grade center to read-only so grades cannot be modified after extraction.

When finished, select Submit.

Notification settings

If desired, return to the Settings menu and edit notification settings.

REST API security settings (incoming data security)

Configure the following properties:

  • REST Outgoing Security Settings
    • Enable Secure REST API - Enable this setting if the incoming endpoints will implement the security.
    • IP Filter - Enable the filter for any incoming IPs. If this setting is enabled, also set:
      • Shared Secret - Enter the shared key.
      • API Key - Enter the API key.
      • Timestamp Range - Do not set.
      • Timestamp Parameter - Enter the parameter for the timestamp.
      • MAC Parameter - Enter the MAC parameter.
      • API Key Parameter - Enter the API key parameter.

When finished, select Submit.

Logging levels

Configure the following properties:

  • Logging Configuration
    • Log Verbosity - Configure this setting to determine the level of logging to the /logs/custom/bbc-GradeyJourney.log file. The default value is INFO, but you may want to add DEBUG for troubleshooting purposes. Production configuration should be set to INFO unless debugging.

Run a validation test

  1. Navigate to System Admin > Grades Extract Settings (Outgoing Data).
  2. Update the transfer method to Local and set the path to a local folder that can be read, updated, and deleted from the user running Blackboard Learn. Choose SITS Integration based on your needs. Select Submit.
  3. In Settings, select Assignment and Grade Column Settings (Incoming Data).
  4. Update Receive Input Files via FTP to Disabled and set the Path to a local folder that can be read, updated, and deleted from the user running Blackboard. Select Submit.
  5. Create a weighted grade column in the course using a flat file. Create the user files for the enrollments.
  6. Log in to Learn as the instructor and go to the course.
  7. Navigate to the Grade Center. The new weighted grade column should appear there.
  8. Create an assignment and map it 100% to the weighted column.
  9. Enter grades for the enrollments.
  10. In the Manage menu, select Grade Approval and Transfer.
  11. Select the Extract and Schedule button at the course, grade column, or grade level.
  12. If the extract was successful, the file or files appear in the extract folder.
  13. If the extract was not successful, consult the log in <bb home>/custom/log/bbgs-GradeJourney.log.