REST API how to associate to blueprint course

[wjlane]

We are trying to automate the process of associating courses to blueprint courses.  The workflow we want to implement is to have a form in our website where the director of elearning submits a csv file which creates the associations.  We already have something similar for creating assignments.  To achieve this we are looking at "Update associated courses"  (https://canvas.instructure.com/doc/api/blueprint_courses.html#method.master_courses/master_templates...) but I assume we must be missing something simple because whatever we try it returns "The specified resource does not exist".  The documentation provides the following path :

PUT /api/v1/courses/:course_id/blueprint_templates/:template_id/update_associations

We're assuming the issue relates to the course or blueprint_template id.  It seems unlikely to me that the course id and the course_ids_to_add would be the same.  So should the course id be the blueprint course id?  If that is the case then what is the template_id and where would we find that?

https://somewhere.beta.instructure.com/api/v1/courses/5475/blueprint_templates/6641/update_associati...

If anyone has any experience or insight into this it would be greatly appreciated.

N.B The above url is used in Postman and consequently it will make the necessary substitutions to ensure the url format is valid (e.g the ending will be &course_ids_to_add%5B%5D=5475 but have left as is for clarity).

[MattHanes · Accepted solution]

I just tested this out since I'm going to probably have to start using this at some point. According to the API documentation, the "template id" for now is just the word "default". Here's what the documentation says:

Using 'default' as the template_id should suffice for the current implmentation (as there should be only one template per course). However, using specific template ids may become necessary in the future

So in the Put command, you're deciding what courses to associate with a blueprint course. All the association stuff happens in the blueprint course so the "course_id" is the course id for the blueprint. The "courses ids to add" array lists all the courses you want associated with the blueprint.

For example, if the blueprint course is 1111 and you want to associate course 1112 then the url in Postman will look like this:

[wjlane]

Thanks Matt that was exactly the snippet I was missing.  I see now it is explained further up the page.  My bad for not seeing that.

[themidiman]

 @MattHanes , Is this still endpoint working as intended as you see it? Any time I'm attempting to run an API call with this endpoint it's giving me the HTML contents of the Canvas error page in the response rather than a JSON object. Here's my Postman setup:

The HTML in the response amounts to the standard Canvas Error page:

I know it says 'Beta' on the API docs, but if you're getting the same thing then I'm wondering if this is a support issue that needs to be filed?

Thanks!

[MattHanes]

It's still working for me. I can't see your entire URL in your screenshot but I'm guessing that's where the error is.

[aaron_bahmer]

 @MattHanes , I'm glad I came across your post. It really clears things up about the course_id and blueprint_id situation.

I'm having a different learning issue here, though, perhaps you can help me identify the error of my way.

First, I have an existing course, formerly associated with BP "A". I have broken the association and can verify through both BP "A"s association list and the course settings which no longer show the BP tie. I have also reset the course.

I believe I have a correctly constructed URI and have tried both a PowerShell script and Postman to invoke the command. I'm getting the same response either way: The remote server returned an error: (422) Unprocessable Entity.

I'm working in my beta instance and the command URI looks like this:

/api/v1/courses/990/blueprint_templates/default/update_associations?course_ids_to_add[]=445‍

• 990 is the course id of BP "B" -- and the course resides in the top-most account on our system, nicely rooted above the account where the course lives.
• 445 is the course id of my existing course I wish to associate with BP "B"
• I have the plural "templates"

I just don't know what else to check. :smileysilly: Thanks for any suggestions!

[MattHanes]

My only guess is maybe you're using POST instead of PUT? I think that the Unproccessable Entity error usually means the API got data that didn't match what it was expecting.

Canvas usually spits out a 400 error if something is wrong like the blueprint and associated course not being in the same account structure. That error usually reads "invalid courses to add".

[aaron_bahmer]

Thanks for that suggestion. I confirmed I'm using PUT. Sigh. I guess this gets a ticket!

[MattHanes]

Could you add a Postman screenshot like Jeffrey did below? Maybe we can catch something that way. Just make sure to block out your token like we did in our screenshots.

[aaron_bahmer]

I've moved to a different course from previous post, same error. Token is set properly.

[themidiman]

Here's another look at the same setup in Postman with the full URL:

Here's the full text of the request URL

https://<canvas_instance_domain>/api/v1/courses/1008844/blueprint_template/default/update_associations?course_ids_to_add[]=1008845‍‍

Thanks!

[MattHanes]

Yeah, the URL should be blueprint_templates and not blueprint_template.  They used the plural. Just add an 's' and it should work.

[themidiman]

That's the issue. Thanks! I'm embarrassed to admit I didn't see this earlier as I'm usually pretty detail oriented. I just needed a second pair of eyes. :smileycool:

[MattHanes]

No worries! Happens to us all :smileygrin:

[aaron_bahmer]

 @MattHanes ,

Through recent work with the API and Blueprints and Canvas support, it has been determined that in order to establish an association of a course to a blueprint, you MUST include the template_id of the blueprint course rather than "deafult" as suggested in a previous post. That API call to the URI should look something like:

{base url}/api/v1/courses/990/blueprint_templates/3/update_associations?course_ids_to_add[]=1905‍‍

I've tested this and it works. Now, I am encountering this issue: https://community.canvaslms.com/message/96863-re-blueprint-api-if-courses-are-associated-through-the... 

[MattHanes]

Oh I'm glad that worked! I wonder why default still works for me though...
It looks like you have to send a separate call to start the sync:

POST /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations

Blueprint Courses - Canvas LMS REST API Documentation 

[cbirdsong]

So I need to add a batch of courses via the Runner function in Postman. The Blueprint course id is listed in the URL, and the list of associated course ID's will be in a CSV file I attach to the run. It sounds like for the API call listed in the Canvas docs, the ":course_id" is for the associated courses & the ":template_id" is the Blueprint id?  This is what is listed in the Canvas documentation. url:PUT|/api/v1/courses/:course_id/blueprint_templates/:template_id/update_associations  

And then I need to have a header in the CSV file at the top of the column of course id's that says "course_id" to match what's in the line above? I understand the basic premise but it's the context that I just want to be sure I'm getting correct.

Thanks! This will save us SOOOO much work if I can get this going.

[aaron_bahmer]

Cynthia,

Your Postman skills surpass mine if you are going to use Runner! Good luck.

This is an example URI that I use:

/api/v1/courses/990/blueprint_templates/3/update_associations?course_ids_to_add[]=1905

• where 990 is the course ID of my blueprint course
• where 3 is the template ID from my blueprint course
• where 1905 is the course ID that I want to apply the blueprint to

Since course_ids_to_add[] is an array, you may be able to add more than one course at a time. Use a comma list? =1905,1906,2154. I'm not sure how that works.

After you've added all your courses to the template, you need to force it to synch, something like:

/api/v1/courses/990/blueprint_templates/3/migrations

• where 990 is the course ID of my blueprint course
• where 3 is the template ID from my blueprint course

[cbirdsong]

Lol, this will be my FIRST time using Postman & Runner for anything other than learning/testing, so fingers crossed I don't break something!! And if we didn't have like 300 courses to associate, I could use the comma delimited in-line option but I'd be there forever! Thanks for the clarification on the template/course id - that's how I understood it as well.