Permissions Required for GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/

[Mike]

Hi,

Which account permissions are required for the call: GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/, using parameters, version = 1.2 and ouTypeId = 3 and D2L version 10.3. We're successfully able to get this function working on our test environment but NOT on our development environment and we're having trouble determining which permission settings are required. Our development instance returns the message "403 / Not Authorized".

Mike

[Desire2Learn Staff: Viktor]

Typically, one way we recommend isolating role permissions involved is to start with a User/Role that has no privileges, and then begin to add privileges mixed in with calls to determine the mix of roles required for your individual needs. Another methodology is to start with the tokens for a user "of the type that you'd expect to do this activity", but if you run into situations like yours where you have a role on one back-end service that's supposed to be the same as the "same" role on another back-end service, but you're noticing different outcome, then it can be more challenging to debug (you're then down to isolating the differences in role permissions on both services, and the same effort can often be more easily done by starting with a role with no privileges and moving forward).

Interrogating aspects of the orgstructure (like getting lists of parents, children, descendants, ancestors, org unit types, and so on) are typically administrative functions and the role permissions are associated with the Org Unit Editor and Org Unit Type Editor tools. As such, the role permissions around this functionality don't likely distinguish between reading operations and writing operations, because what they model is "you either have access to the tool, or you don't". 

Consequently, you likely don't want to work with use cases that depend on "end users" requiring the ability to use this functionality, because you likely don't want to afford "end users" the ability to edit your org structure.

[Mike]

Enabling the "Can Create and Edit Org Units" permission seems to have fixed the problem but it was a non-intuitive solution as we were performing a read-only request.

[Desire2Learn Staff: Viktor]

I'm glad this worked for you.

The user role permissions structure existed for a long time before the Learning Framework APIs, and the LF API design was explicitly done to expose functionality that would be scoped based on the user's abilities on whose behalf the API calls were being made.

What this means in practice is the LF API's behaviour is aligned with the user-interaction model directly with their LMS web sessions, and the back-end service is built as a collection of tools on top of a platform. Role permissions apply to these tools, bound by a user's role and the various org unit types that form the context of where the user attempts to make use of the tool.

Accordingly, some tools have very thick-grained sets of permissions because in the web-UI the tool only really gets used by a certain class of users in constrained situations. This is especially true of tools providing administrative functionality. In the use-cases for direct-access users, there probably wasn't particularly ever an expressed need for people to use the org unit editor tool or org unit type editor tool in a read-only way: our clients using the tool through a web session are using it for org structure management, requiring read-write access primarily.

This does have an effect on the way the APIs work, and is the primary reason that client-app or client-service designers should think firmly about modelling their designs on what an LMS user in front of their web browser is likely to do: the platform makes it easy to automate, aggregate, or provide remote information around these kinds of tasks, but the minute you want to provide functionality to a client app or service that isn't directly aligned with what that user could do using the web UI, you run into these kinds of difficulties.

There are ways to get past most of these general kinds of issues, but they're typically not elegant: it's a matter of the Learning Framework APIs just not being primarily designed for those kinds of usage models.

That said, as we continue to listen to how our clients are using the LF APIs, and we continue to work on them, we are concentrating more and more on building out better support for "administrative script/app/service" type design models (including things like bulk-data access, expressive administrative functions that can be done in few steps as opposed to many, and so on). It turned out that many more clients than we anticipated exactly wanted to use this platform for these kind of administrative needs, and now we're moving to try and build out the use-cases we're learning from these clients.

--

V.