MNV Gateway

Course Pull

Course pull is used to retrieve a list of courses which are led by an instructor. To do this the Gateway needs the following set of information:

  • URL of the LMS which contains the course information
  • LMS username for the instructor
  • LMS SSO key for the instructor (for Blackboard this is provided through a Building Block).

The process for a Course Pull is as follows:

  1. Tool Provider calls the Course Pull end point with the above information
  2. Tool Provider is issued a Job ID
  3. Tool Provider calls the job status end point with the provided Job ID to check status.
  4. When the job is complete the Gateway will send the data object back to the Tool Provider in the job status call.

To start the process the Tool Provider must POST the following JSON object to the Gateway. Be advised that this end point is secured through HTTP Basic Authentication and credentials must be provided.

REQUEST:
 - POST /job/course
 - HEADER:
         Content-Type: application/json
         Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

 - BODY:
    {
      "tool_consumer_url": "iclicker.blackboard.com",
      "tool_consumer_username": "msmith",
      "tool_consumer_sso_key": "AfaOSSUPe1Wt"
    }

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": {
            "async": true,
            "job_id": "68e0b68c2a2515fea376b62da12bf367"
        },
        "message": null,
        "status": 200,
        "time": null
    }

The Tool Provider may then use the Job Status endpoint to retrieve the status of the job. This endpoint is also protected by HTTP Basic Authentication. For more information see Retrieving Results.

REQUEST:
 - GET /job/d80eb2ec2c2e2cf8775cf36d0da7bca4
 - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

RESPONSE:
 - BODY:
     {
         "error": 0,
         "data": null
         "message": null,
         "status": 200,
         "time": 6.71,
         "job_status_message": "Job is still queued",
         "job_status_code": 4
     }

Eventually the data will be returned from the Job Service:

REQUEST:
 - GET /job/d80eb2ec2c2e2cf8775cf36d0da7bca4
 - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

RESPONSE
 - BODY
    {
        "job_status_message": "Job is complete",
        "job_status_code": 4,
        "data": [
            {
                "name": "Chemistry 101",
                "course_uuid": "a98d136ddb7e4b77a7cdef58fd622759",
                "course_id": "CHEM101-1",
                "description": null
            },
            {
                "name": "Chemistry 201",
                "course_uuid": "c547e2e418274c03a54f74726d53708c",
                "course_id": "CHEM201-2",
                "description": null
            },
            {
                "name": "Chemistry 101",
                "course_uuid": "620ff3bcf9834b0dbae70e53238ffecc",
                "course_id": "CHEM101-2",
                "description": null
            }
        ],
        "error": 0,
        "message": null,
        "status": 200,
        "time": "5.93 sec"
    }

As seen above the 'data' object will contain a list of courses for which the user is an instructor. Since the Gateway doesn't store any specific course information, the 'courseUUID' is the ID coming from the LMS The 'courseUUID' is also used during the Roster Pull Job to specify the course to pull the roster for.

See Retrieving Results for more info on the job 'data' wrapper object.