Association Service - MNV Gateway

The Gateway stores user association between Tool Consumers and Tool Providers. This allows the Tool Provider to greatly simplify how their users are stored since they no longer need to worry about the LMS that the user is coming from. To do this the Gateway uses a special Association workflow in order to capture unique Tool Provider user identification which is described below.

To enable this process the Tool Provider must expose an "Association" endpoint which the user will be redirected to with an assoc_token in the POST. The Tool Provider must log in the user and call the Gateway with the provided assoc_token to that the user may be associated in the Gateway.

It is important to note that the User will likely get into this workflow when attempting to perform a tool launch. When Gateway detects that the user is unknown it will pause the tool launch and start the Association workflow.

The process for association is as follows:

User attempts to perform a Launch
Gateway detects that the user is unknown

Gateway pauses the initial launch and redirects the user to the Tool Provider's Association page by POSTing the following form to the Tool Provider (the courseId and instructor parameters are examples and would have been specified in the original launch request):

<form action="http://tool-provider.com/associate_user?courseId=123&instructor=555" method="post" enctype="application/x-www-form-urlencoded" >
    <input type="hidden" name="assoc_token" value="Association53fb693a065004.48592062" />
    <input type="hidden" name="tp_user_id" value=""/>
    <input type="hidden" name="tc_user_id" value="ea918c08a3874091a2644e72109ea898"/>
    <input type="hidden" name="tc_role" value="urn:lti:role:ims/lis/Learner"/>
    <input type="hidden" name="tc_first_name" value="Joe"/>
    <input type="hidden" name="tc_last_name" value="Smith"/>
    <input type="hidden" name="tc_email" value="joe.smith@university.edu"/>
</form>

The Tool Provider logs in or creates a new account for their user and POSTs the user ID back to the Gateway /v1/associate endpoint along with the assoc_token. this must contain an array of "associations" even if only one is being passed back:
```
{
    "associations": [
        {
            "association_token": "Association53fb693a065004.48592062",
            "tool_provider_user_id": "5"
        }
    ]
}
```
The Gateway will reply with a response, the Tool Provider likely does not need to take action based on the mnv_user_id:
```
{
    "error": 0,
    "data": {
        "action": "Successfully associated your tool_provider_user_id",
        "mnv_user_id": 54348
    },
    "message": null,
    "status": 200
}
```

Finally the Tool Provider redirects the user back to the Gateway by submitting a form, via POST, with the assoc_token to the /v1/association_launch endpoint in the Gateway:

    <form id="tp_user_association" action="//gateway.mnv-tech.com/v1/association_launch?authType=basic&amp;courseId=123&amp;gw-d=1" method="post" enctype="application/x-www-form-urlencoded">
        <input type="hidden" name="assoc_token" id="assoc-token" value="Association53fb693a065004.48592062"/>
    </form>

This ends the Association Workflow from the Tool Provider's perspective.

Next the Gateway will look up the assoc_token from the redirect and rebuild the initial launch request.

IMPORTANT NOTE: This will initiate the Launch service all over again (picking up at step 3), so look to the Launch Service documentation to understand the flow at this point.

Batch Association

The batch user association process is similar to the single user association process except for the following differences...

The Tool Provider POSTs an array of their user IDs to the Gateway /v1/associate endpoint along with matching association tokens (obtained from a Roster Pull):

{
    "associations": [
        {
            "association_token": "Association5453d395c226c9.31195596",
            "tool_provider_user_id": "QuasarDJ"
        },
        {
            "association_token": "Association5453d395c22763.08354509",
            "tool_provider_user_id": "J-Lo"
        }
     ]
 }

The Gateway will reply with a response, the Tool Provider likely does not need to take action based on the array of mnv_user_id values:

{
    "error": 0,
    "data": {
        "action": "Successfully associated tool_provider_user_id(s)",
        "association_result": [
            {
                "status": "success",
                "message": "success",
                "tool_provider_user_id": "QuasarDJ",
                "mnv_user_id": 6
            },
            {
                "status": "success",
                "message": "success",
                "tool_provider_user_id": "J-Lo",
                "mnv_user_id": 9
            }
        ]
    },
    "message": "Successfully associated tool_provider_user_id(s)",
    "status": 200,
    "time": null
}

In the case where there are errors, the Gateway will reply with a response, the Tool Provider likely does not need to take action based on the array of mnv_user_id values, but may provide some useful information regarding failed associations. This request object...

{
    "associations": [
        {
            "association_token": "Association53fb693a065004.48592062",
            "tool_provider_user_id": "SL-User-200"
        },
        {
            "association_token": "Association12ab493a065c23.83464937",
            "tool_provider_user_id": "SL-User-512"
        },
        {
            "association_token": "Association5453d1c3edf1c5.45531491",
            "tool_provider_user_id": "J-Rod"
        }
     ]
 }

...may result in the following response...

{
    "error": 2,
    "data": {
        "action": "Errors detected during association, see 'association_result' array for info.",
        "association_result": [
            {
                "status": "failure",
                "message": "Token was not found or has previously been used.",
                "tool_provider_user_id": "SL-User-200",
                "mnv_user_id": null
            },
            {
                "status": "failure",
                "message": "Token was not found or has previously been used.",
                "tool_provider_user_id": "SL-User-512",
                "mnv_user_id": null
            },
            {
                "status": "success",
                "message": "success",
                "tool_provider_user_id": "J-Rod",
                "mnv_user_id": 8
            }
        ]
    },
    "message": "Errors detected during association, see 'data' object for info.",
    "status": 200,
    "time": null
}