Originally posted on 6/11/2013 on the Valence Developer Blog by Sarah-Beth Bianchi.
In this week's API Cookbook recipe, we demonstrate how to add a new user to the Learning Environment using Brightspace APIs. In this scenario, a student has enrolled and can log in to the institution's portal, which acts as a student information system and a single sign-on mechanism for the LMS. When the user signs in to the portal, we need to check if the user exists in the LMS. If the user doesn't exist, we should add that user to the LMS, enroll them in their courses, and then proceed with authentication - all in a process that is invisible for the user. This scenario assumes that the portal passes along the appropriate data for user creation and enrollment.
Whenever a student logs in to the portal, we need to check if that user already exists in the LMS by searching for either the OrgDefinedId or the UserName via the User APIs. Let's look at an example of a student with the UserName NCage:
GET /d2l/api/lp/1.0/users/?userName=NCage200 OK{"OrgId":6606,"UserId":10222,"FirstName":"Nicolas","MiddleName": null,"LastName":"Cage","UserName":"NCage","ExternalEmail":"NCage@test.com","OrgDefinedId":"NCage","UniqueIdentifier":"NCage","Activation":{"IsActive":true},"DisplayName":"Nicolas Cage"}
This user already exists in the LMS, so the system should proceed with authenticating the user.
Now let's look at an example where a student does not exist in the LMS:
GET /d2l/api/lp/1.0/users/?userName=IElba404 Not Found{"Errors":[{"Message": "Resource Not Found"}]}
In this case, we need to add this new user:
POST /d2l/api/lp/1.0/users/{"OrgDefinedId": "IElba","FirstName": "Idris","MiddleName": "","LastName": "Elba","ExternalEmail": "IElba@test.com","UserName": "IElba","RoleId": 578,"IsActive": true,"SendCreationEmail": "true"}200 OK{"OrgId":6606,"UserId":20216,"FirstName":"Idris","MiddleName":"","LastName":"Elba","UserName":"IElba","ExternalEmail":"IElba@test.com","OrgDefinedId":"IElba","UniqueIdentifier":"IElba","Activation":{"IsActive":true},"DisplayName":"Idris Elba"}
Tip: If you happen to be unfamiliar with what RoleId that you should assign to the user, you can retrieve a RoleId list:
GET /d2l/api/lp/1.0/roles/200 OK[{"Identifier":"578","DisplayName":"End User","Code":"End User"},{"Identifier":"579","DisplayName":"Resource Creator","Code":null},{"Identifier":"580","DisplayName":"Administrator","Code":null}]
Once the user is added to the LMS, we can retrieve a list of all enrollments for that user. For example, we can retrieve this list for the user we just added:
GET /d2l/api/lp/1.0/enrollments/users/20216/orgUnits/200 OK{"PagingInfo": {"Bookmark": "6609","HasMoreItems": false},"Items": [{"OrgUnit": {"Id": 6606,"Type": {"Id": 1,"Code": "Organization","Name": "Organization"},"Name": "Dev","Code": null},"Role": {"Id": 578,"Code": "End User","Name": "End User"}}}]}
Now let's enroll the user in their first course:
POST /d2l/api/lp/1.0/enrollments/{"OrgUnitId": 6609,"UserId": 20216,"RoleId": 578}200 OK{"OrgUnitId":6609,"UserId":20216,"RoleId":578,"IsCascading":false}
This concludes the basics of creating a new user using the Valence Learning Framework APIs.