Skip to main content
pdf?stylesheet=default
Blackboard Help

RESTful Web Services Implementation

Implement Grades Journey Using RESTful Web Services

  1. In System Admin, under Blackboard Building, select Building Blocks.
  2. Click 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.
    • Gradable Item Provisioning Check - Choose one:
      • Update Matches - If you want provisioning to update the due date and point possible for any matching items
      • One Time Only - If you want to provision a course once.
      • No Restriction - If you want no restrictions on provisions.
  • Result Transfer Settings, File Format, and Grade Column Settings do not apply to REST.

When finished, click Submit.

Grade Extract Settings (Outgoing Data)

Configure the following properties:

  • Integration
    • Integration Type - Choose REST Integration.
    • 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.
  • 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, click 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. Secure REST must be enabled, the REST provisioning functionality will not work unless it is enabled.
    • 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, click 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 PostWebservice Endpoint to <your server url>/webapps/bbgs-GradeJourney-BBLEARN/app/admin/apitest/receiveRestGradeExtract
  3. Click Submit.
  4. If you are using a self-signed certificate, you will need to export the certificate and upload it into the JDK keystore in <jdk home>/jre/lib/security and restart.
  5. Manually create a course and add some enrollments. Ensure that the instructor has the roles required to approve grades.
  6. Create a manual grade column in the course using a tool to post the REST transaction. You can use tools such as curl or SOAP UI. There is also a tool in the system called Grades Journey REST API Tester.
  7. Mark the column with Extract=Y.
  8. Log in to Learn as the instructor and go to the course.
  9. Navigate to the Grade Center. The new weighted grade column should appear there.
  10. Create an assignment and map it 100% to the weighted column.
  11. Enter grades for the enrollments.
  12. In the Manage menu, select Grade Approval and Transfer.
  13. If the extract is successful, the transaction is logged in the log file located in <bb home>/logs/custom/bbgs-GradeJourney.log. The status of the grades, columns, and course should say extracted.
  14. If the extract was not successful, consult this same log.