I was looking at the Users API on the D2L API reference site:
http://docs.valence.desire2learn.com/res/user.html
And there does not appear to be a way to find a user by email address.
Is there a way to do this with the current API?
You can fetch user records from the .../users/ route using either the organization-defined ID, or the user login name properties. Additionally, you can fetch the user record for a user identified by the LMS UserID property. You cannot currently easily retrieve a user record based on another property in the user record: you'd need to fetch entire collection of users and then sort through for the record with the email address you're looking for. With most organizations, this is not at all ideal because of the number of users involved.
Generally improvements to the API of this nature are on the development roadmap, however there isn't a specifically deployment plan in place for an enhancement on this particular use-case. That said, enhancements to the routes to search for fundamental data objects (users, org units) are identified as having strong value by clients and that's a primary driver in determining priority for improvements..
Related
My application deals with multi-user, multi-tenant Microsoft Graph calendar data and I need to keep a record of unique calendars and events.
I can't find very detailed information on this in the documentation. It does say the Ids are unique per user/mailbox (for calendar) and per calendar (for event Ids), and obviously they have to be.
But if the user and tenant boundary is crossed, can I assume each calendar Id and event Id I obtain from any user in any tenant via Microsoft graph is unique, so I won't encounter two different calendars/events with the same Ids?
Yes they should be unique in the world see https://learn.microsoft.com/en-us/office/client-developer/outlook/mapi/pidtagentryid-canonical-property . Basically the Id used by the Graph (and EWS) contains the PidTagEntryId along with various routing flags and info but that underlying id should always mean they are unique. However be careful with the ical uid which won't be unique
I've been using /d2l/api/lp/1.4/enrollments/myenrollments/ to get a list of enrollments for the current user. Now, I want to just get the enrollments where the user is in an instructor role. So, I'm trying to use:
/d2l/api/lp/1.4/enrollments/users/{userId}/orgUnits/?roleId=105
When I use that, I get an empty list of Items back, with or without the roleId specified.
My expectation is that just calling it without the roleId would return the same list as /d2l/api/lp/1.4/enrollments/myenrollments/. But, I always get an empty list, except when I log in as a system administrator. Only in that case do I get anything back.
Does anyone have any suggestions on what I might be doing wrong?
The various my* API calls specifically exist to provide end users to fetch back details about the system that they should know, but segregated from information they shouldn't (that's available through the more general routes for a particular area). Enrollments is a good example of this. And end-user should be able to see their own enrollments, but they should not have generalized access to enrollment records. In particular, the D2L system treats the D2L user role belonging to an enrollment as fairly privileged information, and a side effect of this is that it's not generally visible to end users.
One way that applications and services can cope with achieving goals that the end-user cannot themselves perform is to have set up a "service account" that the app can use to make calls of an administrative nature, to fetch back data that they can use in the business logic around presenting information to end users. In this particular case, you could, for example use the service account to make calls about a user's enrollments, and then present the user with logic that could filter the list of their enrollments by "these are the student ones, and these are the ones where you're a teacher, and a tutor, and so forth".
But you'd also need to carefully consider the implications of this type of activity in balance against the intentions of the client LMS's policies and administration. Even this level of information may be giving away too much to end users, in the eyes of a client LMS administrator.
Using a service account to let an app make administrative level calls must always be done with great care around the issue of information/functional leakage to end users.
I'm working on migrating from SOAP to valence API. I'm having some problems with a few calls like getting users (All users, based on role, by userID, etc) and grades (All variations).
I see an empty list returned with no items. There's no error of any kind. When I try to get the data using SOAP, I get the desired data.
I've checked the permissions for "Search for Students", so technically, I should be getting something when I try to get all users or by role id of students. What else am I missing here...
The D2LWS service's authentication mechanism puts the API caller in the position of being a privileged caller. The Valence Learning Framework APIs use a different auth model: the user ID/Key tokens that identify a user get employed by the back-end to restrict the functionality of calls. That is: the authenticated user should have access to the same functionality and data as the user would get through the web UI, and no more.
In this particular case, the calls succeed: they send back all the elements in the result set that your calling user has privileges to see -- none of them.
This is almost certainly an issue with the role privileges afforded to your calling user, and debugging the permissions around calls can be challenging. The Valence project's documentation provides a walkthrough topic on investigating role permissions that might shed let on a possible approach here, especially with respect to the calls to gain access to user records (or properties that appear in user records).
As the walkthrough discusses, there are various aspects to making the general call to /d2l/api/lp/{version}/users/ that bring permissions into play:
If you're trying to filter with a query parameter, does the calling user context have permissions to use the data on which you want to filter
Does the calling user context have permission to see properties affected by User Information Privacy settings
Does the calling user have permission to search for all the user roles they need to, in order find users in the result set
The users call operates on the root organization unit, so the permissions the calling user requires must be set on the organization org unit type.
By contrast, the Grades-related API calls operate not on the root organization unit, but typically on course offerings, sections, or groups. The permissions surrounding the calls there will get checked in the associated org unit types, so the calling user will need the right permissions against those types. Additionally, many of the calls related to course offerings (also sections and groups) require that the calling user be enrolled in the org unit in question (and in some cases, explicitly enrolled, not merely enrolled by cascading enrollment).
If you're sure that your calling user context does give you access to these things (and allows you access to this data through the web UI), and you still see a mismatch like this when you're calling through the API, then you may have uncovered a defect of some kind and you should please ask your organization's support contact, or your account manager, to open a support ticket to report that through Desire2Learn's support desk.
Is there some way that I can retrieve the roleId of the current user context regardless of that user's role permissions within the LMS?
For example, I would like to programatically determine if a user is a 'student', 'teacher', etc. I know this can be done if the authenticated user has access to user roles but obviously a 'student' role would not possess such credentials.
Any insight into this matter would be greatly appreciated!
With many organizations the assigned role of a user's enrolment is considered sensitive information by the organization (for example, imagine the case where the organization wants to set up multiple roles for particular pay grades of instructors), and does not want the roles to be visible outside a small group of administrative users. Accordingly, there may not be a reliable way for a users to determine their own roleIds assigned to them within an organization unit (course, department, faculty, and so forth), let alone the roles assigned to other users.
Our typical recommendation is that client applications focus first on attempting actions that a user should be able to accomplish based on their access in the webUI: in some cases, this could involve a user characterizing their own general role in a context ("Are you a student in this course? An instructor? A Teaching Assistant?") or it could involve simply attempting actions and gracefully taking action based on results ("I'm sorry, you don't have permission to do/see that").
The various API calls that return an Enrollment.OrgUnitUser structure will contain role information for enrollments; notably the MyEnrollments API call does not return such a structure (it's intention was to be a "safe" call that any user could make to fetch back the list of their own enrollments with potentially privileged information redacted).
i have a order catalogue web site and i want to create a REST API so people can create their own apps and Add an Order or Update an existing order:
Lets say an order has:
OrderId
Product
Quantity
ShippingType
So i need some API to allow someone to send in a new order (orderid would be blank as that would be in the response).
How do you deal with passing in items like Product or Shipping type. These are tables in my db and are keyed off their own specific primary key id. Should the NewOrder API ask for a string name for these fields, should it ask for the id. If it asked for the ID, that would assume they would have to call the GiveMeProductList() method upfront (which gives you the name and id of all product as a dataset).
What is the standard for dealing with this?
Martin Fowler has a good post about the steps toward the glory of REST that you might find useful to come up with REST API.
The media type that I use for sending this information to the server can handle both scenarios, Id and Code/Name. If the user enters the product code manually then I send up the code, if the user asks to pick from a list then I provide the list and send back the Id.