Content Migrations API

BETA: This API resource is not finalized, and there could be breaking changes before its final release.

API for accessing content migrations and migration issues

A MigrationIssue object looks like:

{
    // the unique identifier for the issue
    id: 370663

    // API url to the content migration
    content_migration_url: "https://example.com/api/v1/courses/1/content_migrations/1"

    // Description of the issue for the end-user
    description:  "Questions in this quiz couldn't be converted"

    // Current state of the issue: active, resolved
    workflow_state: "active"

    // HTML Url to the Canvas page to investigate the issue
    fix_issue_html_url "https://example.com/courses/1/quizzes/2"

    // Severity of the issue: todo, warning, error
    issue_type: "warning"

    // Link to a Canvas error report if present (If the requesting user has permissions)
    error_report_html_url: "https://example.com/error_reports/3"

    // Site administrator error message (If the requesting user has permissions)
    error_message: "admin only message"

    // timestamps
    created_at: "2012-06-01T00:00:00-06:00",
    updated_at: "2012-06-01T00:00:00-06:00",

}

A ContentMigration object looks like:

{
    // the unique identifier for the migration
    id: 370663,

    // the type of content migration
    migration_type: common_cartridge_importer,

    // the name of the content migration type
    migration_type_title: "Canvas Cartridge Importer",

    // API url to the content migration's issues
    migration_issues_url: "https://example.com/api/v1/courses/1/content_migrations/1/migration_issues",

    // attachment api object for the uploaded file
    // may not be present for all migrations
    attachment: {url:"https://example.com/api/v1/courses/1/content_migrations/1/download_archive"},

    // The api endpoint for polling the current progress
    progress_url: "https://example.com/api/v1/progress/4",

    // The user who started the migration
    user_id: 4,

    // Current state of the content migration: pre_processing pre_processed running waiting_for_select completed failed
    workflow_state: "running",

    // timestamps
    started_at: "2012-06-01T00:00:00-06:00",
    finished_at: "2012-06-01T00:00:00-06:00",

    // file uploading data, see {file:file_uploads.html File Upload Documentation} for file upload workflow
    // This works a little differently in that all the file data is in the pre_attachment hash
    // if there is no upload_url then there was an attachment pre-processing error, the error message will be in the message key
    // This data will only be here after a create or update call
    pre_attachment:{upload_url: "", message: "file exceeded quota", upload_params: {...}}

}

A Migrator object looks like:

{
    // The value to pass to the create endpoint
    "type":"common_cartridge_importer",

    // Whether this endpoint requires a file upload
    "requires_file_upload":true,

    // Description of the package type expected
    "name":"Common Cartridge 1.0/1.1/1.2 Package",

    // A list of fields this system requires
    "required_settings":[]
}

List migration issues MigrationIssuesController#index

GET /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues

Returns paginated migration issues

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues \ 
    -H 'Authorization: Bearer <token>'
Returns a list of MigrationIssues

Get a migration issue MigrationIssuesController#show

GET /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

Returns data on an individual migration issue

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \ 
    -H 'Authorization: Bearer <token>'
Returns a MigrationIssue

Update a migration issue MigrationIssuesController#update

PUT /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

Update the workflow_state of a migration issue

Request Parameters:

  • workflow_state

    Set the workflow_state of the issue, only 'active' and 'resolved' accepted

Example Request:

curl -X PUT https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \ 
     -H 'Authorization: Bearer <token>' \ 
     -F 'workflow_state=resolved'
Returns a MigrationIssue

List content migrations ContentMigrationsController#index

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/courses/:course_id/content_migrations

Returns paginated content migrations

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations \ 
    -H 'Authorization: Bearer <token>'
Returns a list of ContentMigrations

Get a content migration ContentMigrationsController#show

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/courses/:course_id/content_migrations/:id

Returns data on an individual content migration

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<id> \ 
    -H 'Authorization: Bearer <token>'
Returns a ContentMigration

Create a content migration ContentMigrationsController#create

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

POST /api/v1/courses/:course_id/content_migrations

Create a content migration. If the migration requires a file to be uploaded the actual processing of the file will start once the file upload process is completed. File uploading works as described in the File Upload Documentation except that the values are set on a pre_attachment sub-hash.

For migrations that don't require a file to be uploaded, like course copy, the processing will begin as soon as the migration is created.

You can use the Progress API to track the progress of the migration. The migration's progress is linked to with the progress_url value.

The two general workflows are:

If no file upload is needed:

  1. POST to create

  2. Use the Progress specified in progress_url to monitor progress

For file uploading:

  1. POST to create with file info in pre_attachment

  2. Do file upload processing using the data in the pre_attachment data

  3. GET the ContentMigration

  4. Use the Progress specified in progress_url to monitor progress

Request Parameters:

  • migration_type
    string

    The type of the migration. Use the Migrator endpoint to see all available migrators. Default allowed values: canvas_cartridge_importer, common_cartridge_importer, course_copy_importer, zip_file_importer, qti_converter, moodle_converter

  • pre_attachment[name]
    string

    Required if uploading a file. This is the first step in uploading a file to the content migration. See the File Upload Documentation for details on the file upload workflow.

  • pre_attachment[*]

    (optional) Other file upload properties, See File Upload Documentation

  • settings[source_course_id]
    string

    (optional) The course to copy from for a course copy migration. (required if doing course copy)

  • settings[folder_id]
    string

    (optional) The folder to unzip the .zip file into for a zip_file_import. (required if doing .zip file upload)

  • settings[overwrite_quizzes]
    boolean

    (optional) Whether to overwrite quizzes with the same identifiers between content packages

  • settings[question_bank_id]
    integer

    (optional) The existing question bank ID to import questions into if not specified in the content package

  • settings[question_bank_name]
    string

    (optional) The question bank to import questions into if not specified in the content package, if both bank id and name are set, id will take precedence.

  • date_shift_options[shift_dates]
    boolean

    (optional) Whether to shift dates

  • date_shift_options[old_start_date]
    yyyy-mm-dd

    (optional) The original start date of the source content/course

  • date_shift_options[old_end_date]
    yyyy-mm-dd

    (optional) The original end date of the source content/course

  • date_shift_options[new_start_date]
    yyyy-mm-dd

    (optional) The new start date for the content/course

  • date_shift_options[new_end_date]
    yyyy-mm-dd

    (optional) The new end date for the source content/course

  • date_shift_options[day_substitutions][x]
    integer

    (optional) Move anything scheduled for day 'x' to the specified day. (0-Sunday, 1-Monday, 2-Tuesday, 3-Wednesday, 4-Thursday, 5-Friday, 6-Saturday)

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/content_migrations' \ 
     -F 'migration_type=common_cartridge_importer' \ 
     -F 'settings[question_bank_name]=importquestions' \ 
     -F 'date_shift_options[old_start_date]=1999-01-01' \ 
     -F 'date_shift_options[new_start_date]=2013-09-01' \ 
     -F 'date_shift_options[old_end_date]=1999-04-15' \ 
     -F 'date_shift_options[new_end_date]=2013-12-15' \ 
     -F 'date_shift_options[day_substitutions][1]=2' \ 
     -F 'date_shift_options[day_substitutions][2]=3' \ 
     -F 'date_shift_options[shift_dates]=true' \ 
     -F 'pre_attachment[name]=mycourse.imscc' \ 
     -F 'pre_attachment[size]=12345' \ 
     -H 'Authorization: Bearer <token>'
Returns a ContentMigration

Update a content migration ContentMigrationsController#update

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

PUT /api/v1/courses/:course_id/content_migrations/:id

Update a content migration. Takes same arguments as create except that you can't change the migration type. However, changing most settings after the migration process has started will not do anything. Generally updating the content migration will be used when there is a file upload problem. If the first upload has a problem you can supply new pre_attachment values to start the process again.

Returns a ContentMigration

List Migration Systems ContentMigrationsController#available_migrators

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/courses/:course_id/content_migrations/migrators

Lists the currently available migration types. These values may change.

Returns a list of Migrators