What is the most efficient why to get all Instructor enrolments for a user, using the Valence API.
Currently I am using this:
/d2l/api/lp/1.0/enrollments/users/{userid}/orgUnits/?roleid={Instructor}
That is the correct call to use for this information. You can further filter the returned list to a particular org unit type with ?orgUnitTypeId={ouTypeId}, if you only want to see course offerings. This can be useful, for example, to filter out all Groups and Sections from the list that would also get returned in the call that you use, or any custom org units where the user is enrolled as an 'Instructor' role that's not strictly a course (like a Department, Faculty, or other custom org unit).
If you want to see all the enrollments for a user where the enrolled role is 'Instructor' (provided you pass in the role ID for 'Instructor'), then your API is the one you want.
Related
We decided to have some User Groups completely under programmatic control.
Which parameters to use when creating a Group Category, so that:
neither number of groups nor number of students is known in advance
no automatic group creation
auto enrollment not allowed
self enrollment not allowed
?
You should be able to accomplish this with these steps (I am assuming your back-end service supports the LP API contracts of at least version 1.3 and forward):
Create a group category for the groups you want to build in the future like this. In the GroupCategoryData structure you provide to this call, you can use these property settings:
Set EnrollmentStyle to 0 or NumerOfGroupsNoEnrollment (sic: note the mis-spelling).
Set EnrollmentQuantity to null
Set AutoEnroll and RandomizeEnrollments to false
Set MaxUsersPerGroup to null
Set NumberOfGroups to the number of groups you want to create off the start within this group category: you can create 1 and then delete it after the group category creation.
You should get back a GroupCategoryData fetch-form structure that contains an array of any initial Group org unit IDs created within this group category, and containing the GroupCategoryId for this new category.
When you want to create a group for the category, provide the group category ID from the previous step in the POST route to create the group.
To enroll users into these groups, you can use the standard create-enrollment call and provide the standard EnrollmentData structure. You'll need to provide the org unit ID for the group, the user ID for the user to enroll, and the role ID for the role you want the user to have in the group. You should also set IsCascading to false here.
Note that, if your back-end service only has v1.2 of the LP API or older, then these instructions will vary slightly (read the enrollment topic in the API reference carefully).
I'm a bit confused on how we are supposed to update a group using the Valence API.
According to documentation, "Name,Code & Description" are required for updating, but the FETCH group block only returns "GroupID,Name, Description and Enrollments". If Group Code is not returned in the fetch, what value are we supposed to use in the update block if we only want to update the name? Since description is provided I can just feed that back, but what am I supposed to do about code ... just lose that data?
Perhaps there a way to send an update that will update only specific fields in the update block? When I omit fields from the update block I currently receive an error (ie in the case I only want to update the name).
The Code property for Groups is intended to be the "org-defined code" for the group (for a course offering, this is often called the "course code"), the one that might appear in the organization's SIS system, for example.
Because groups in Desire2Learn's Learning Suite are considered "org units", when you create one, you need to provide it with an appropriate org-defined code (Code) -- if your organization doesn't use org-defined codes for groups, then you can decide to systematically use some other kind of data by convention (a name, a descriptive string, and so on). You are correct that's inconvenient for the Fetch form of the GroupData structure not to provide this value for you, but the value will be accessible to callers through the organization structure routes (because the newly created group is just an special kind of org unit).
In Learning Suite v10.2 (LP API v1.3+) and later, you can use a single GET call to fetch back the properties for an org unit. In versions prior to v10.2, you will need to fetch the list of parents for the group to get a parent org unit ID, or if you already know the org unit ID for the course offering that owns the group you can use that; then you use that org unit ID to fetch its list of children: your group will be in that list. The OrgUnit and OrgUnitProperties structures both contain the Code property that you need here.
As an instructor user, what Valence Learning Framework API calls must I make to fetch back a list of all the students (only) enrolled in one of my courses?
There are two principal ways to get a list of the people enrolled in a D2L LE class org unit; the right call you should use depends most upon the back-end LMS's configuration that you're working with:
GET /d2l/api/le/{ver}/{orgUnitId}/classlist/
This will retrieve all the users enrolled in the org unit that the system has configured to appear in the class; in some organizations, this might consist of students only, but it's most likely that this call will mix in instructors, tutors, and the like as well as students. So this might, or might not, be appropriate for your needs.
One thing you can try in combination with this route to distinguish students from others in the course is to focus on those who are gradeable; make the classlist call, and then for each user in the classlist, request a grade value for a known grade item. If the user is a student or other role that is participating in the course and being graded, you will know from that second call; non-gradeable users will not have grade values associated with their enrollment. This will help you focus on the aspects of the person's enrollment in the course without necessarily focussing on the details of their enrolled role (some organizations treat role information as sensitive).
GET /d2l/api/lp/{ver}/enrollments/orgUnits/{orgUnitId}/users/?roleId={roleId}
This call will retrieve all the users enrolled in the org unit, and you can filter the retrieved list by role ID (so you can list only "student" users, by their role Id). If the organization has more than one kind of student role, then you will need to know that so you can fetch all the possible student roles. Or, you can simply make the call without the roleId query parameter and filter the results after fetching based on the embedded role information you get back.
However, your instructor user may not have the right permissions to make this call; some organizations limit the access to the enrollment information calls like this to administrative users only.
Note that using the grade object method to determine if user is a student will, by default, only returns 20 items. You can override by specifying pageSize parameter with the call, but you may run in to the same permissions issue if you do not have the appropriate permissions.
http://docs.valence.desire2learn.com/res/grade.html#get--d2l-api-le-(version)-(orgUnitId)-grades-(gradeObjectId)-values-
In the user api docs it is mentioned that to change the user's role at the organization level we need to use the schema "PUT /d2l/api/lp/(D2LVERSION: version)/users/(D2LID: userId)"
This requires UpdateUserData JSON block as input, but the UpdateUserData JSON block does not have a role id in it. How, then, will we pass the new role of the user?
Role applies to a particular level in the organization so is not an intrinsic property of a user but rather property of the relationship between a user and the org or user and the org unit (department, course etc).
So you could delete and then create the user’s enrollment at the org level . (Id for the org level is retrieved with org info call )
The operation to delete the enrollment is on the enrollment page. And the operation to create the enrollment is on the same page.
However, it is NOT typical for a user to have no enrollment at the org level (e.g. if there was a connection interrupt between delete and create it is not clear what that state of not being enrolled in the org would mean)
I am not sure this fits your application, but, more typical than adding and removing enrollments at the org level is to add and remove them in a particular org level. That way the user always has a presence in the org, but, you can govern permissions via that org unit.
Supposing various type of users, like 'normal', 'medium' and 'premium' each one with different permissions.
a kind of permission on permission.
for example:
only a registered users can post
a normal user can post 1 post per month
a medium user can post 5 posts per month
a premium user can post unlimited posts per month
and some other attributes.
what you suggest?
I would suggest you look at can can.
If you are set on rolling your own "role system", then what I would logically do is create a model for a class called Role, and set up permissions and levels in that class, and have a relationship between Users and different Roles.
For example, you could have a Role object named "Normal" with attributes like allowed_posts = 1 etc.
And in your users table (in the database), you would have a column called role_id, which would be set to the ID of the normal role in your roles table.