Provisioning interface
This interface will provision (i.e. create/update) gradable items and/or gradebook columns in Blackboard Learn.
Web service definition
| Purpose | Create / Update gradable items and/or gradebook columns. |
| Description | Creates gradable items/gradebook columns from a supplied list of JSON data. Note that it will not create gradable items for a course if items have already been created. When creating a gradable item, it will create a gradable item using the parameters from the interface that can then be filled out manually to complete the set-up. The items will be created in the default or folder specified. |
| Endpoint | /webapps/bbgs-GradeJourney-BBLEARN/app/REST/gradableItemsAPI |
| Method | POST |
| Parameters | Optional security parameters: apikey, timestamp, mac |
| JSON structure | The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.
course_id, item_type, name, instructions, anonymous, group, contentAreaName,available,colour,attempts,tracked,startDate,endDate, dueDate,poins,optionalData |
| Returns | JSON List of status codes for the courses and assignments which were processed:
course_id = course id processed The HTTP Status code will also be set as follows: 201 Created - on success 401 Unauthorized - if auth fails 412 Precondition Failed - if the course has already been populated with items, so if any course in the list fails, the rest will succeed but the 412 will be returned 500 Error - any other errors |
| Example Data | [{"course_id":"course_001","item_type":"ASSIGNMENT","name":"assignment name","instructions":"assignment instructions.","anonymous":false,"group":false,"contentAreaName":"Subject Outline Tool Items", "available":true,"colour":"","attempts":1,"tracked":false,"startDate":"2013-04-07","endDate":"2013-04-07","dueDate":"2013-04-07","points":100.0, "extract":false, "optionalData":"key1\u003dvalue1:key2\u003d value2"}] |
| Example Response | [{"name":"assignment name","message":"Course not found","status":"ERROR", "course_id":"course_001"}] |
Provisioning element definition
| Element Name | Description | Required | Type and max size |
|---|---|---|---|
| Course_Id | Course_id identifying the course to which this grade mode applies | Yes | String (256 chars) |
| Name | Title of the gradable item | Yes | String (333 chars) |
| Item_type | Type of gradable item to create
ASSIGNMENT - assignment TEST - test SURVEY - survey DISCUSSION_BOARD - new gradable discussion board WIKI - new gradable wiki BLOG - new gradable blog JOURNAL - new gradable journal SELF_AND_PEER_TEST - new self and peer assessment MANUAL_COLUMN - manual entry column WEIGHTED_COLUMN - weighted column TOTAL_COLUMN - total column Note that that any new items in the future will need to be evaluated any will likely require changes to address. |
Yes | String (333 chars) |
| Instructions | Instructions | No | String (2000 chars) |
| Anonymous | True/false | No | Boolean (Default false) |
| Group | True/false | No | Boolean (Default false) |
| ContentAreaName | Default "Subject Outline Tool Items" | No | String (255 chars) |
| Available | True/false | No | Boolean (Default false) |
| Colour | Name or hex string | No | String (10 chars) |
| Attempts | -1 for unlimited | No | Int (Default -1) |
| Tracked | True/false | No | Boolean (Default false) |
| StartDate | Display from date | No | Date* |
| EndDate | Display until date | No | Date* |
| DueDate | Due date | No | Date* Note that for variable dates, this value will not be passed as it is optional. |
| Points | Points Possible | No | Float (Default 100.0) |
| GradeSchema | Grade schema (this is the name as it exists in Bb). Note that this schema may have been created using the web service as available from the Grade Journey B2 or in the system. | No | String (333 chars) |
| SequenceNum | Sequence display order number | No | Int |
| Extract | Y/N - If yes, this column will be extracted from the extraction tool | No | Boolean (Default false) |
| Mapping | For a weighted column, specify the mappings. Default is nothing so that it can be performed manually.
This should be the gradable item name/percentage pairs separated by a column. For example, Assignment 1=30,Test 1=30,Assignment 2=40 For a total column, specify just the columns that should be included in the total. For example, Assignment 1, Test 1, Assignment 2, Final Grade |
No | String (333 chars) |
| OptionalData | Key/value pairs with each set of pairs separated by a colon, and key/values separated by an equal sign. For example: key1=value1:key2=value2 | No | String(2000 chars) |
Grade extract interface
The purpose of this interface is to extract gradebook data for the SIS system.
Web service definition
| Purpose | The purpose of this interface is to extract gradebook data for the SIS system. |
| Description | Extracts grade data as a list of JSON data. |
| Endpoint | As specified by Endpoint |
| Method | POST |
| Parameters | Optional security parameters: apikey, timestamp, mac |
| JSON structure | The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.
Students: external_course_key,student_id,batch_uid,title,mark,grade Footer: schedule_dt, record_count Note that for a merged course, a separate export for each external_course_key will exist for each section. |
| Returns | JSON List of status codes for the courses which were processed:
course_id = course id processed |
| Example Data | [{"grades":[{"external_course_key":"course_001","student_id":"1234","batch_uid":"jstudent1","title":"Final External Grade","grade":"A","mark":160, "optionalData":"key1\u003dvalue1:key2\u003d value2"},{"external_course_key":"course_001","student_id":"4567","batch_uid":"jstudent2","title":"Administrative Override","grade":"","mark":"", "optionalData":"key1\u003dvalue1:key2\u003d value2"}],"footer":[{"schedule_dt":"2014-05-28 00:13:18.294","record_count":"2"}]}] |
| Example Response | [{"external_course_key":"course_001","message":"All records processed successfully","status":"SUCCESS"}] |
Grade extract element definition
| Field Header | Description | Required | Type and max size |
|---|---|---|---|
| EXTERNAL_COURSE_KEY | The batch_uid for the course | Yes | String (256 chars) |
| STUDENT_ID | The student id for the student | Yes | String (256 chars) |
| BATCH_UID | The batch_uid for the student | Yes | String (256 chars) |
| TITLE | Title of the grade column | Yes | String (333 chars) |
| MARK | The mark | Yes | Float |
| GRADE |
The grade To return the score as a percentage, use Grade.PERCENTAGE_SCORE. |
Yes | String (32 chars) |
| OPTIONAL_DATA | Any optional data fields passed in | No | |
| SCHEDULE_DT | Schedule datetime | Yes | Datetime |
| RECORD_COUNT | Record count | Yes | Float |
Grade schema interface
The purpose of this interface is to create new gradebook schemas. This is optional.
Web service definition
| Purpose | The purpose of this interface is to create new gradebook schemas. |
| Description | Creates grade schemas. |
| Endpoint | /webapps/bbgs-GradeJourney-BBLEARN/app/REST/gradeSchemasAPI |
| Method | POST |
| Parameters | Optional security parameters: apikey, timestamp, mac |
| JSON structure | The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.
Title - The name of the schema. Symbols - the code/value pairs for the schema. OptionalData - any optional data to store with the schema. |
| Returns | JSON List of status codes for the courses which were processed:
name = name of schema created |
| Example Data | [{"title":"OverrideGrade","symbols":"SU\u003d99:US\u003d0","optionalData":"key1\u003dvalue1:key2\u003dvalue2"}] |
| Example Response | [{"course_id":"","name":"OverrideGrade","status":"OK","message":"GradeSchema successfully created"}] |
Grade schema element definition
| Field Header | Description | Required | Type and max size |
|---|---|---|---|
| Title | Title of the grading schema | Yes | String (333 chars) |
| Symbols | Symbols in a list with (optional) lower bound | No | String (2000 chars) |
| OptionalData | Key/value pairs with each set of pairs separated by a comma, and key/values separated by an equal sign. For example: key1=value1,key2=value2 | No | String (2000 chars) |
Authorization
This interface will support two options for securing the API either or both may be used:
1. Secure REST API: uses a shared secret and an MD5 hash algorithm to generate a key which must be used to allow access to the REST endpoints.
2. IP Filter: Limits the servers which can communicate to the REST API to specific IP addresses. Multiple IP addresses can be listed separated by semi-colons. If IP addresses are limited, In order for the API test page to function, the BbLearn application server must be included in the list.
- Shared Secret: the shared secret is a series of characters used in the encryption scheme to generate the hash. This secret must be used on the sending side to generate the hash value.
- API Key: this is a set of characters which is passed along in the URL as a key value. It becomes encrypted into the hash and then is validated against the hash upon receipt.
- TimeStamp Range: this value indicates the length of time the URL is valid. The timestamp is sent as part of the query string parameters and included in the hash. Upon receipt, the timestamp value is compared against the current timestamp and if the difference in time exceeds the range limit, the request is denied.
- MAC Parameter: this value determines what query string parameter contains the MAC hash value.
- API Key Parameter: this value determines what query string parameter contains the API key value.
- IP Filter: a semi-colon delimited list of IP addresses that are allowed to access the API.
To properly authenticate users, the trusted system must be able to generate a valid MAC (message authentication code) to send with the SSO request. This MAC is used to determine the integrity of an SSO request. The steps required to generate a secure MAC are as follows:
- Sort the parameters API Key, Timestamp alphabetically by parameter name.
- Concatenate the parameter values by the sorted parameter names into a single string.
- Append the Shared Secret to the string obtained from Step 2.
- Encrypt the string into a 16-byte string using the MD5 algorithm.
- Convert the 16-byte string into a 32-byte alphanumeric (hexadecimal) string to make it URL-friendly.
