MNV Gateway

Roster Pull

Roster pull is used to pull a list of students that are in a course for a particular LMS. To do this the Gateway needs the following set of information:

  • URL of the LMS which contains the roster information
  • LMS username for the instructor
  • LMS SSO key for the instructor (for Blackboard this is provided through a Building Block).
  • LMS course ID (will be provided in the Course Pull).

The process for pulling a Roster is a 2 part process. First you must obtain a course ID by pulling a Course List. Then using that course ID a roster can be pulled. Belows outlines only how to pull a roster as the Course Pull is covered elsewhere.

  1. Call the /job/roster end point using HTTP Basic Authentication and providing the above information.
  2. The Gateway will respond with a Job ID.
  3. Tool Provider checks status of the Job.
  4. Job data (roster) is returned back to the Tool Provider.

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/roster
 - HEADER:
         Content-Type: application/json
         Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

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

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": {
            "async": true,
            "job_id": "b6da173224d50ff8ff028f0e6e5ca219"
        },
        "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/b6da173224d50ff8ff028f0e6e5ca219
 - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

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

Roster Return Object

As the roster must account for multiple users states the object that it returns requires some additional explination.

Below is an example of a full Request/Response. Notice that the 'data' response object contains an array of user objects. The user can have 2 disparate states.

  1. Associated - User will have a "tool_provider_user_id" and "association_token" will be null
  2. Unknown - User will have an "association_token" and "tool_provider_user_id" will be null.
REQUEST:
 - GET /job/b6da173224d50ff8ff028f0e6e5ca219
 - HEADER:
    Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": [
            {
                "lms_user_id": "scott",
                "lms_uuid": "f45cfe925ed742e38c5c5328fc92a817",
                "first_name": "Scott",
                "last_name": "Hudnall",
                "email": "",
                "username": "scott",
                "tool_provider_user_id": "456",
                "association_token": null
            },
            {
                "lms_user_id": "cristiano.schembri",
                "lms_uuid": "7935ba27dc8d4c679c1b24dea54f87aa",
                "first_name": "Cristiano",
                "last_name": "Schembri",
                "email": "cristiano.schembri@saplinglearning.com",
                "username": "cristiano.schembri",
                "tool_provider_user_id": "963",
                "association_token": null
            },
            {
                "lms_user_id": "jared.student",
                "lms_uuid": "c96354a5428c4855aa1ad1376d1e8333",
                "first_name": "Jared",
                "last_name": "Student",
                "email": "",
                "username": "jared.student",
                "tool_provider_user_id": "27",
                "association_token": null
            },
            {
                "lms_user_id": "jordan.one",
                "lms_uuid": "dae9a058f56a4ff08a04e8e9c22844f5",
                "first_name": "Jordan",
                "last_name": "One",
                "email": "jordan.one@fake.com",
                "username": "jordan.one",
                "tool_provider_user_id": "10374",
                "association_token": null
            }
        ],
        "message": null,
        "status": 200,
        "time": 6.08,
        "job_status_message": "Job is complete",
        "job_status_code": 4
    }

Associating Users

The Tool Provider can use information from the roster to do a bulk user association. More information on Bulk Association can be found in Association.