Enrollment API Question.... Custom Roles?

[samson_chung]

Hey all,

I have been playing around with this endpoint here.

Enrollments - Canvas LMS REST API Documentation 

One thing I am a bit confused by this is.... how do I enroll a Custom Role?

According to the documentation.

Allowed values: StudentEnrollment, TeacherEnrollment, TaEnrollment, ObserverEnrollment, DesignerEnrollment

But... the GUI allows me to 'Add a role'.... let's say I would like to add a 'Student Advisor' role and I would like to enroll some users of this type into selected courses... How would I go about doing that via the Endpoint?

Thanks,

Sc.

[James]

 @samson_chung  

Use the numeric role_id for the custom role. If you don't know the ID, you can get it from the list roles endpoint of the Roles API.

I just added a tutor custom role through the GUI and Canvas used the StudentEnrollment base type, which is what our tutor role is based off of, but then it used the role_id for the tutor custom roll.That's the only identifying information in the request that would let Canvas know it's a tutor role.

Further confirming this is what you want to do, the documentation for the enroll a user endpoint of the Enrollments API says:

enrollment[role_id] Assigns a custom course-level role to the user.

In theory, you should/could use the base type for the custom role as enrollment[type] as it says it's required. However, that's followed by a note that explains what it does when it's not included, so that makes you question whether or not it's actually required. It is supposed to infer it from something, but the something is a bad link and part of the sentence is missing. When you look at the source code, it says enrollment[role], but that has been deprecated. The source code also looks like it uses role_id to get the role, which makes sense since role is deprecated. I would include the type just to be safe.

[samson_chung]

Thanks, I've taken a look at the role_id and have beeing playing with it....

 @James ‌, you are right, I've just tested the the endpoint via Postman..... It worked like a charm...

What I have also discovered it that the enrollment[type] is very strange...

As a test, I've left it out completely during two post test... it seems the system will automatically look up the type based on the role id.

So for a role where I have based it on a Student, the type returned in the JSON is StudentEnrollment.. While for a role where i have based it on a Teacher, the type returned is TeacherEnrollment.

I am wondering.... if I know the role IDs of all my roles, does that mean the 'Required field' of Enrollment[Type] is actually optional?

[James]

 @samson_chung  

That's what it seemed like based on the descriptions. It feels like someone wrote the API to only support the standard types, then decided they needed custom roles so they added the role_id and deprecated the role, but didn't update the rest of the instructions.

I don't speak Ruby fluently and didn't have time to track down every possibility, but you could check out the source code (click on the little link to the right of the endpoint header). For example, next to "Enroll a user" is EnrollmentsApiController#create in small gray font. When you click on that, it will open up the Enrollments API Controller. Then do a search for "def create" to find the create function.

[sourjya_sen]

Thank you James. This was super helpful and pointed me to the right direction.

Would you know how to get a list of Course level roles via the API? When I do a GET request to /accounts/1/roles, it is only fetching me the Account Level roles and not the Course roles. The documentation page doesn't say how to go about this.

Reagrds,

Sourjya

[samson_chung]

Thanks for the repsonse,

Another option I've since discovered and have decided to use more... is the SIS Integration via CSV. 

Since custom role is supported via a String, it just made it much easier and less of an issue to look up role IDs. 

However, this led to a new problem with Canvas. It seems a user can be in multiple roles within a course and the system would behave differently depending on how that user is enrolled into the course.

If user A is enrolled into Course 123 as a teacher and a student via the GUI, the rights for the last enrolled role is the one the system uses. 

However, if A is enrolled using the Integration, it becomes a union of the rights between the two roles. 

I have yet to test this again with the API, as this created a bigger issue for me in which I have to review my integration and add in a group of delete enrollments to the enrollments.