Outcome Groups API
API for accessing learning outcome group information.
Learning outcome groups organize outcomes within a context (or in the global "context" for global outcomes). Every outcome is created in a particular context (that context then becomes its "owning context") but may be linked multiple times in one or more related contexts. This allows different accounts or courses to organize commonly defined outcomes in ways appropriate to their pedagogy, including having the same outcome discoverable at different locations in the organizational hierarchy.
While an outcome can be linked into a context (such as a course) multiple times, it may only be linked into a particular group once.
An OutcomeGroup object looks like:
{
// the ID of the outcome group
"id": 1,
// the URL for fetching/updating the outcome group. should be treated as opaque
"url": "/api/v1/accounts/1/outcome_groups/1",
// an abbreviated OutcomeGroup object representing the parent group of this
// outcome group, if any. omitted in the abbreviated form.
"parent_outcome_group": null,
// the context owning the outcome group. may be null for global outcome groups.
// omitted in the abbreviated form.
"context_id": 1,
"context_type": "Account",
// title of the outcome group
"title": "Outcome group title",
// description of the outcome group. omitted in the abbreviated form.
"description": "Outcome group description",
// A custom GUID for the learning standard.
"vendor_guid": "customid9000",
// the URL for listing/creating subgroups under the outcome group. should be
// treated as opaque
"subgroups_url": "/api/v1/accounts/1/outcome_groups/1/subgroups",
// the URL for listing/creating outcome links under the outcome group. should be
// treated as opaque
"outcomes_url": "/api/v1/accounts/1/outcome_groups/1/outcomes",
// the URL for importing another group into this outcome group. should be
// treated as opaque. omitted in the abbreviated form.
"import_url": "/api/v1/accounts/1/outcome_groups/1/import",
// whether the current user can update the outcome group
"can_edit": true
}
An OutcomeLink object looks like:
{
// the URL for fetching/updating the outcome link. should be treated as opaque
"url": "/api/v1/accounts/1/outcome_groups/1/outcomes/1",
// the context owning the outcome link. will match the context owning the
// outcome group containing the outcome link; included for convenience. may be
// null for links in global outcome groups.
"context_id": 1,
"context_type": "Account",
// an abbreviated OutcomeGroup object representing the group containing the
// outcome link.
"outcome_group": null,
// an abbreviated Outcome object representing the outcome linked into the
// containing outcome group.
"outcome": null,
// whether this outcome has been used to assess a student in the context of this
// outcome link. In other words, this will be set to true if the context is a
// course, and a student has been assessed with this outcome in that course.
"assessed": true,
// whether this outcome link is manageable and is not the last link to an
// aligned outcome
"can_unlink": null
}
Redirect to root outcome group for context OutcomeGroupsApiController#redirect
GET /api/v1/global/root_outcome_group
url:GET|/api/v1/global/root_outcome_group
GET /api/v1/accounts/:account_id/root_outcome_group
url:GET|/api/v1/accounts/:account_id/root_outcome_group
GET /api/v1/courses/:course_id/root_outcome_group
url:GET|/api/v1/courses/:course_id/root_outcome_group
Convenience redirect to find the root outcome group for a particular context. Will redirect to the appropriate outcome group’s URL.
Get all outcome groups for context OutcomeGroupsApiController#index
GET /api/v1/accounts/:account_id/outcome_groups
url:GET|/api/v1/accounts/:account_id/outcome_groups
GET /api/v1/courses/:course_id/outcome_groups
url:GET|/api/v1/courses/:course_id/outcome_groups
Get all outcome links for context OutcomeGroupsApiController#link_index
GET /api/v1/accounts/:account_id/outcome_group_links
url:GET|/api/v1/accounts/:account_id/outcome_group_links
GET /api/v1/courses/:course_id/outcome_group_links
url:GET|/api/v1/courses/:course_id/outcome_group_links
Show an outcome group OutcomeGroupsApiController#show
GET /api/v1/global/outcome_groups/:id
url:GET|/api/v1/global/outcome_groups/:id
GET /api/v1/accounts/:account_id/outcome_groups/:id
url:GET|/api/v1/accounts/:account_id/outcome_groups/:id
GET /api/v1/courses/:course_id/outcome_groups/:id
url:GET|/api/v1/courses/:course_id/outcome_groups/:id
Update an outcome group OutcomeGroupsApiController#update
PUT /api/v1/global/outcome_groups/:id
url:PUT|/api/v1/global/outcome_groups/:id
PUT /api/v1/accounts/:account_id/outcome_groups/:id
url:PUT|/api/v1/accounts/:account_id/outcome_groups/:id
PUT /api/v1/courses/:course_id/outcome_groups/:id
url:PUT|/api/v1/courses/:course_id/outcome_groups/:id
Modify an existing outcome group. Fields not provided are left as is; unrecognized fields are ignored.
When changing the parent outcome group, the new parent group must belong to the same context as this outcome group, and must not be a descendant of this outcome group (i.e. no cycles allowed).
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
title | string |
The new outcome group title. |
|
description | string |
The new outcome group description. |
|
vendor_guid | string |
A custom GUID for the learning standard. |
|
parent_outcome_group_id | integer |
The id of the new parent outcome group. |
Example Request:
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
-X PUT \
-F 'title=Outcome Group Title' \
-F 'description=Outcome group description' \
-F 'vendor_guid=customid9000' \
-F 'parent_outcome_group_id=1' \
-H "Authorization: Bearer <token>"
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
-X PUT \
--data-binary '{
"title": "Outcome Group Title",
"description": "Outcome group description",
"vendor_guid": "customid9000",
"parent_outcome_group_id": 1
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>"
Delete an outcome group OutcomeGroupsApiController#destroy
DELETE /api/v1/global/outcome_groups/:id
url:DELETE|/api/v1/global/outcome_groups/:id
DELETE /api/v1/accounts/:account_id/outcome_groups/:id
url:DELETE|/api/v1/accounts/:account_id/outcome_groups/:id
DELETE /api/v1/courses/:course_id/outcome_groups/:id
url:DELETE|/api/v1/courses/:course_id/outcome_groups/:id
Deleting an outcome group deletes descendant outcome groups and outcome links. The linked outcomes themselves are only deleted if all links to the outcome were deleted.
Aligned outcomes cannot be deleted; as such, if all remaining links to an aligned outcome are included in this group’s descendants, the group deletion will fail.
Example Request:
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
-X DELETE \
-H "Authorization: Bearer <token>"
List linked outcomes OutcomeGroupsApiController#outcomes
GET /api/v1/global/outcome_groups/:id/outcomes
url:GET|/api/v1/global/outcome_groups/:id/outcomes
GET /api/v1/accounts/:account_id/outcome_groups/:id/outcomes
url:GET|/api/v1/accounts/:account_id/outcome_groups/:id/outcomes
GET /api/v1/courses/:course_id/outcome_groups/:id/outcomes
url:GET|/api/v1/courses/:course_id/outcome_groups/:id/outcomes
A paginated list of the immediate OutcomeLink children of the outcome group.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
outcome_style | string |
The detail level of the outcomes. Defaults to “abbrev”. Specify “full” for more information. |
Create/link an outcome OutcomeGroupsApiController#link
POST /api/v1/global/outcome_groups/:id/outcomes
url:POST|/api/v1/global/outcome_groups/:id/outcomes
PUT /api/v1/global/outcome_groups/:id/outcomes/:outcome_id
url:PUT|/api/v1/global/outcome_groups/:id/outcomes/:outcome_id
POST /api/v1/accounts/:account_id/outcome_groups/:id/outcomes
url:POST|/api/v1/accounts/:account_id/outcome_groups/:id/outcomes
PUT /api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id
url:PUT|/api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id
POST /api/v1/courses/:course_id/outcome_groups/:id/outcomes
url:POST|/api/v1/courses/:course_id/outcome_groups/:id/outcomes
PUT /api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id
url:PUT|/api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id
Link an outcome into the outcome group. The outcome to link can either be specified by a PUT to the link URL for a specific outcome (the outcome_id in the PUT URLs) or by supplying the information for a new outcome (title, description, ratings, mastery_points) in a POST to the collection.
If linking an existing outcome, the outcome_id must identify an outcome available to this context; i.e. an outcome owned by this group’s context, an outcome owned by an associated account, or a global outcome. With outcome_id present, any other parameters (except move_from) are ignored.
If defining a new outcome, the outcome is created in the outcome group’s context using the provided title, description, ratings, and mastery points; the title is required but all other fields are optional. The new outcome is then linked into the outcome group.
If ratings are provided when creating a new outcome, an embedded rubric criterion is included in the new outcome. This criterion’s mastery_points default to the maximum points in the highest rating if not specified in the mastery_points parameter. Any ratings lacking a description are given a default of “No description”. Any ratings lacking a point value are given a default of 0. If no ratings are provided, the mastery_points parameter is ignored.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
outcome_id | integer |
The ID of the existing outcome to link. |
|
move_from | integer |
The ID of the old outcome group. Only used if outcome_id is present. |
|
title | string |
The title of the new outcome. Required if outcome_id is absent. |
|
display_name | string |
A friendly name shown in reports for outcomes with cryptic titles, such as common core standards names. |
|
description | string |
The description of the new outcome. |
|
vendor_guid | string |
A custom GUID for the learning standard. |
|
mastery_points | integer |
The mastery threshold for the embedded rubric criterion. |
|
ratings[][description] | string |
The description of a rating level for the embedded rubric criterion. |
|
ratings[][points] | integer |
The points corresponding to a rating level for the embedded rubric criterion. |
|
calculation_method | string |
The new calculation method. Defaults to “decaying_average” if the Outcomes New Decaying Average Calculation Method FF is ENABLED then Defaults to “weighted_average”
Allowed values: |
|
calculation_int | integer |
The new calculation int. Only applies if the calculation_method is “weighted_average”, “decaying_average” or “n_mastery”. Defaults to 65 |
Example Request:
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \
-X PUT \
-H "Authorization: Bearer <token>"
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes.json' \
-X POST \
-F 'title=Outcome Title' \
-F 'display_name=Title for reporting' \
-F 'description=Outcome description' \
-F 'vendor_guid=customid9000' \
-F 'mastery_points=3' \
-F 'calculation_method=decaying_average' \
-F 'calculation_int=65' \
-F 'ratings[][description]=Exceeds Expectations' \
-F 'ratings[][points]=5' \
-F 'ratings[][description]=Meets Expectations' \
-F 'ratings[][points]=3' \
-F 'ratings[][description]=Does Not Meet Expectations' \
-F 'ratings[][points]=0' \
-H "Authorization: Bearer <token>"
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes.json' \
-X POST \
--data-binary '{
"title": "Outcome Title",
"display_name": "Title for reporting",
"description": "Outcome description",
"vendor_guid": "customid9000",
"mastery_points": 3,
"ratings": [
{ "description": "Exceeds Expectations", "points": 5 },
{ "description": "Meets Expectations", "points": 3 },
{ "description": "Does Not Meet Expectations", "points": 0 }
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>"
Unlink an outcome OutcomeGroupsApiController#unlink
DELETE /api/v1/global/outcome_groups/:id/outcomes/:outcome_id
url:DELETE|/api/v1/global/outcome_groups/:id/outcomes/:outcome_id
DELETE /api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id
url:DELETE|/api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id
DELETE /api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id
url:DELETE|/api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id
Unlinking an outcome only deletes the outcome itself if this was the last link to the outcome in any group in any context. Aligned outcomes cannot be deleted; as such, if this is the last link to an aligned outcome, the unlinking will fail.
Example Request:
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \
-X DELETE \
-H "Authorization: Bearer <token>"
List subgroups OutcomeGroupsApiController#subgroups
GET /api/v1/global/outcome_groups/:id/subgroups
url:GET|/api/v1/global/outcome_groups/:id/subgroups
GET /api/v1/accounts/:account_id/outcome_groups/:id/subgroups
url:GET|/api/v1/accounts/:account_id/outcome_groups/:id/subgroups
GET /api/v1/courses/:course_id/outcome_groups/:id/subgroups
url:GET|/api/v1/courses/:course_id/outcome_groups/:id/subgroups
A paginated list of the immediate OutcomeGroup children of the outcome group.
Returns a list of OutcomeGroup objectsCreate a subgroup OutcomeGroupsApiController#create
POST /api/v1/global/outcome_groups/:id/subgroups
url:POST|/api/v1/global/outcome_groups/:id/subgroups
POST /api/v1/accounts/:account_id/outcome_groups/:id/subgroups
url:POST|/api/v1/accounts/:account_id/outcome_groups/:id/subgroups
POST /api/v1/courses/:course_id/outcome_groups/:id/subgroups
url:POST|/api/v1/courses/:course_id/outcome_groups/:id/subgroups
Creates a new empty subgroup under the outcome group with the given title and description.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
title | Required | string |
The title of the new outcome group. |
description | string |
The description of the new outcome group. |
|
vendor_guid | string |
A custom GUID for the learning standard |
Example Request:
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/subgroups.json' \
-X POST \
-F 'title=Outcome Group Title' \
-F 'description=Outcome group description' \
-F 'vendor_guid=customid9000' \
-H "Authorization: Bearer <token>"
curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/subgroups.json' \
-X POST \
--data-binary '{
"title": "Outcome Group Title",
"description": "Outcome group description",
"vendor_guid": "customid9000"
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>"
Import an outcome group OutcomeGroupsApiController#import
POST /api/v1/global/outcome_groups/:id/import
url:POST|/api/v1/global/outcome_groups/:id/import
POST /api/v1/accounts/:account_id/outcome_groups/:id/import
url:POST|/api/v1/accounts/:account_id/outcome_groups/:id/import
POST /api/v1/courses/:course_id/outcome_groups/:id/import
url:POST|/api/v1/courses/:course_id/outcome_groups/:id/import
Creates a new subgroup of the outcome group with the same title and description as the source group, then creates links in that new subgroup to the same outcomes that are linked in the source group. Recurses on the subgroups of the source group, importing them each in turn into the new subgroup.
Allows you to copy organizational structure, but does not create copies of the outcomes themselves, only new links.
The source group must be either global, from the same context as this outcome group, or from an associated account. The source group cannot be the root outcome group of its context.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
source_outcome_group_id | Required | integer |
The ID of the source outcome group. |
async | boolean |
If true, perform action asynchronously. In that case, this endpoint will return a Progress object instead of an OutcomeGroup. Use the progress endpoint to query the status of the operation. The imported outcome group id and url will be returned in the results of the Progress object as “outcome_group_id” and “outcome_group_url” |
Example Request:
curl 'https://<canvas>/api/v1/accounts/2/outcome_groups/3/import.json' \
-X POST \
-F 'source_outcome_group_id=2' \
-H "Authorization: Bearer <token>"