Documentation

ContentMigration extends AbstractBaseApi

Canvas LMS Content Migrations API

Provides functionality to manage content migrations in Canvas LMS. Content migrations enable importing and exporting course content from various sources including course copies, ZIP files, QTI packages, and Common Cartridge files.

Supports multiple contexts: Account, Course, Group, and User

Tags
see
https://canvas.instructure.com/doc/api/content_migrations.html

Table of Contents

Constants

STATE_COMPLETED  = 'completed'
STATE_FAILED  = 'failed'
STATE_PRE_PROCESSED  = 'pre_processed'
STATE_PRE_PROCESSING  = 'pre_processing'
Workflow state constants
STATE_RUNNING  = 'running'
STATE_WAITING_FOR_SELECT  = 'waiting_for_select'
TYPE_CANVAS_CARTRIDGE  = 'canvas_cartridge_importer'
Migration type constants
TYPE_COMMON_CARTRIDGE  = 'common_cartridge_importer'
TYPE_COURSE_COPY  = 'course_copy_importer'
TYPE_MOODLE_CONVERTER  = 'moodle_converter'
TYPE_QTI_CONVERTER  = 'qti_converter'
TYPE_ZIP_FILE  = 'zip_file_importer'
EXPONENTIAL_BACKOFF_THRESHOLD  = 60
Polling configuration constants
INITIAL_POLLING_INTERVAL_MULTIPLIER  = 1.2
MAX_POLLING_INTERVAL  = 10

Properties

$attachment  : array<string, mixed>|null
Attachment api object for the uploaded file (may not be present for all migrations)
$dateShiftOptions  : array<string, mixed>|null
Date shift options (if applicable)
$errors  : array<string|int, string>|null
Error messages (if any)
$finishedAt  : DateTime|null
When the migration finished
$id  : int|null
The unique identifier for the migration
$migrationIssuesUrl  : string|null
API url to the content migration's issues
$migrationType  : string|null
The type of content migration
$migrationTypeTitle  : string|null
The name of the content migration type
$preAttachment  : array<string, mixed>|null
File uploading data for pre-processing
$progressPercentage  : int|null
Progress percentage (if available)
$progressUrl  : string|null
The api endpoint for polling the current progress
$selectData  : array<string, mixed>|null
Selection data for selective imports
$settings  : array<string, mixed>|null
Migration settings
$startedAt  : DateTime|null
When the migration started
$userId  : int|null
The user who started the migration
$workflowState  : string|null
Current state of the content migration
$apiClient  : HttpClientInterface
$methodAliases  : array<string|int, mixed>
Define method aliases

Methods

__callStatic()  : mixed
Magic method to handle function aliases
__construct()  : mixed
BaseApi constructor.
all()  : array<string|int, static>
Get all pages of results
create()  : self
Create a new content migration in the default account context
createCourseCopy()  : self
Create a course copy migration
createCourseCopyWithDateShift()  : self
Create a course copy with date shifting
createInContext()  : self
Create a new content migration in a specific context
createSelectiveCourseCopy()  : self
Create a selective course copy migration
fetchByContext()  : array<string|int, ContentMigration>
List content migrations for a specific context
fetchByContextPaginated()  : PaginatedResponse
Get paginated content migrations for a specific context
find()  : self
Get a single content migration by ID (not supported - use findByContext instead)
findByContext()  : self
Get a single content migration by ID in a specific context
get()  : array<string|int, static>
Get first page of results
getAccountMigrators()  : array<string|int, Migrator>
List available migration systems in account context
getAssetIdMapping()  : array<string, array<string, string>>
Get asset ID mapping (course context only)
getAttachment()  : array<string, mixed>|null
getCompletionPercentage()  : int|null
Get current completion percentage
getFileUploadError()  : string|null
Get file upload error message if any
getFinishedAt()  : DateTime|null
getId()  : int|null
getMigrationIssues()  : array<string|int, MigrationIssue>
Get migration issues
getMigrationIssuesUrl()  : string|null
getMigrationType()  : string|null
getMigrationTypeTitle()  : string|null
getMigrators()  : array<string|int, Migrator>
List available migration systems
getPreAttachment()  : array<string, mixed>|null
getProgress()  : Progress|null
Get the Progress object for this migration
getProgressUrl()  : string|null
getSelectiveData()  : array<string|int, mixed>
Get selective import data
getSettings()  : array<string, mixed>|null
getStartedAt()  : DateTime|null
getUserId()  : int|null
getWorkflowState()  : string|null
hasFileUploadError()  : bool
Check if file upload had an error
importCommonCartridge()  : self
Create a Common Cartridge import migration
importZipFile()  : self
Create a ZIP file import migration
isCompleted()  : bool
Check if the migration is completed
isFailed()  : bool
Check if the migration has failed
isFileUploadPending()  : bool
Check if file upload is required and pending
isFinished()  : bool
Check if the migration is finished (completed or failed)
isRunning()  : bool
Check if the migration is running
isWaitingForSelect()  : bool
Check if the migration is waiting for selection
paginate()  : PaginationResult
Get paginated results with metadata
processFileUpload()  : self
Process file upload for migration if needed
refresh()  : self
Refresh the migration data from the API
setApiClient()  : void
Set the API client
setAttachment()  : void
setFinishedAt()  : void
setId()  : void
setMigrationIssuesUrl()  : void
setMigrationType()  : void
setMigrationTypeTitle()  : void
setPreAttachment()  : void
setProgressUrl()  : void
setSettings()  : void
setStartedAt()  : void
setUserId()  : void
setWorkflowState()  : void
update()  : self
Update content migration in the default account context
updateInContext()  : self
Update content migration in a specific context
waitForCompletion()  : self
Wait for the migration to complete
waitForState()  : self
Wait for the migration to reach a specific state
castValue()  : DateTime|mixed
Cast a value to the correct type
checkApiClient()  : void
Check if the API client is set, if not, instantiate a new one
convertPaginatedResponseToModels()  : array<string|int, static>
Helper method to convert paginated response data to model instances
createConfiguredHttpClient()  : HttpClient
Create an HttpClient with configured middleware
createPaginationResult()  : PaginationResult
Helper method to create PaginationResult from paginated response
getEndpoint()  : string
Get the API endpoint for this resource
getPaginatedResponse()  : PaginatedResponse
Helper method to get paginated response from API endpoint
populate()  : void
Populate the object with new data
toDtoArray()  : array<string|int, mixed>
Convert the object to an array
buildMultipartData()  : array<string|int, array<string, mixed>>
Build multipart data for file upload

Constants

STATE_PRE_PROCESSING

Workflow state constants

public mixed STATE_PRE_PROCESSING = 'pre_processing'

STATE_WAITING_FOR_SELECT

public mixed STATE_WAITING_FOR_SELECT = 'waiting_for_select'

TYPE_CANVAS_CARTRIDGE

Migration type constants

public mixed TYPE_CANVAS_CARTRIDGE = 'canvas_cartridge_importer'

TYPE_COMMON_CARTRIDGE

public mixed TYPE_COMMON_CARTRIDGE = 'common_cartridge_importer'

TYPE_MOODLE_CONVERTER

public mixed TYPE_MOODLE_CONVERTER = 'moodle_converter'

EXPONENTIAL_BACKOFF_THRESHOLD

Polling configuration constants

private mixed EXPONENTIAL_BACKOFF_THRESHOLD = 60

INITIAL_POLLING_INTERVAL_MULTIPLIER

private mixed INITIAL_POLLING_INTERVAL_MULTIPLIER = 1.2

Properties

$attachment

Attachment api object for the uploaded file (may not be present for all migrations)

public array<string, mixed>|null $attachment = null

$dateShiftOptions

Date shift options (if applicable)

public array<string, mixed>|null $dateShiftOptions = null

$errors

Error messages (if any)

public array<string|int, string>|null $errors = null

$finishedAt

When the migration finished

public DateTime|null $finishedAt = null

$migrationIssuesUrl

API url to the content migration's issues

public string|null $migrationIssuesUrl = null

$migrationType

The type of content migration

public string|null $migrationType = null

$migrationTypeTitle

The name of the content migration type

public string|null $migrationTypeTitle = null

$preAttachment

File uploading data for pre-processing

public array<string, mixed>|null $preAttachment = null

$progressPercentage

Progress percentage (if available)

public int|null $progressPercentage = null

$progressUrl

The api endpoint for polling the current progress

public string|null $progressUrl = null

$selectData

Selection data for selective imports

public array<string, mixed>|null $selectData = null

$settings

Migration settings

public array<string, mixed>|null $settings = null

$startedAt

When the migration started

public DateTime|null $startedAt = null

$userId

The user who started the migration

public int|null $userId = null

$workflowState

Current state of the content migration

public string|null $workflowState = null

$methodAliases

Define method aliases

protected static array<string|int, mixed> $methodAliases = ['get' => ['fetch', 'list', 'fetchAll'], 'all' => ['fetchAllPages', 'getAll'], 'paginate' => ['getPaginated', 'withPagination', 'fetchPage'], 'find' => ['one', 'getOne']]

Methods

__callStatic()

Magic method to handle function aliases

public static __callStatic(string $name, array<string|int, mixed> $arguments) : mixed
Parameters
$name : string
$arguments : array<string|int, mixed>
Tags
throws
InvalidArgumentException

__construct()

BaseApi constructor.

public __construct(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

all()

Get all pages of results

public static all([array<string, mixed> $params = [] ]) : array<string|int, static>
Parameters
$params : array<string, mixed> = []

Query parameters

Return values
array<string|int, static>

createCourseCopy()

Create a course copy migration

public static createCourseCopy(int $targetCourseId, int $sourceCourseId[, array<string, mixed> $options = [] ]) : self
Parameters
$targetCourseId : int

The course to copy content TO

$sourceCourseId : int

The course to copy content FROM

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
self

createCourseCopyWithDateShift()

Create a course copy with date shifting

public static createCourseCopyWithDateShift(int $targetCourseId, int $sourceCourseId, string $oldStartDate, string $newStartDate[, array<string, mixed> $options = [] ]) : self
Parameters
$targetCourseId : int

The course to copy content TO

$sourceCourseId : int

The course to copy content FROM

$oldStartDate : string

Original course start date (Y-m-d)

$newStartDate : string

New course start date (Y-m-d)

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
self

createInContext()

Create a new content migration in a specific context

public static createInContext(string $contextType, int $contextId, array<string, mixed>|CreateContentMigrationDTO $data) : self
Parameters
$contextType : string

Context type (accounts, courses, groups, users)

$contextId : int

Context ID

$data : array<string, mixed>|CreateContentMigrationDTO

Migration data

Tags
throws
CanvasApiException
Return values
self

createSelectiveCourseCopy()

Create a selective course copy migration

public static createSelectiveCourseCopy(int $targetCourseId, int $sourceCourseId, array<string, array<string|int, string|int>> $selections[, array<string, mixed> $options = [] ]) : self
Parameters
$targetCourseId : int

The course to copy content TO

$sourceCourseId : int

The course to copy content FROM

$selections : array<string, array<string|int, string|int>>

Items to copy (e.g., ['assignments' => [1, 2, 3]])

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
self

fetchByContext()

List content migrations for a specific context

public static fetchByContext(string $contextType, int $contextId[, array<string, mixed> $params = [] ]) : array<string|int, ContentMigration>
Parameters
$contextType : string

'accounts', 'courses', 'groups', or 'users'

$contextId : int

Account, Course, Group, or User ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, ContentMigration>

fetchByContextPaginated()

Get paginated content migrations for a specific context

public static fetchByContextPaginated(string $contextType, int $contextId[, array<string, mixed> $params = [] ]) : PaginatedResponse
Parameters
$contextType : string

'accounts', 'courses', 'groups', or 'users'

$contextId : int

Account, Course, Group, or User ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
PaginatedResponse

find()

Get a single content migration by ID (not supported - use findByContext instead)

public static find(int $id[, array<string|int, mixed> $params = [] ]) : self
Parameters
$id : int

Content migration ID

$params : array<string|int, mixed> = []

Optional query parameters

Tags
throws
CanvasApiException
Return values
self

findByContext()

Get a single content migration by ID in a specific context

public static findByContext(string $contextType, int $contextId, int $id) : self
Parameters
$contextType : string

Context type (accounts, courses, groups, users)

$contextId : int

Context ID

$id : int

Content migration ID

Tags
throws
CanvasApiException
Return values
self

get()

Get first page of results

public static get([array<string, mixed> $params = [] ]) : array<string|int, static>
Parameters
$params : array<string, mixed> = []

Query parameters

Return values
array<string|int, static>

getAssetIdMapping()

Get asset ID mapping (course context only)

public static getAssetIdMapping(int $courseId, int $migrationId) : array<string, array<string, string>>
Parameters
$courseId : int

Course ID

$migrationId : int
Tags
throws
CanvasApiException
Return values
array<string, array<string, string>>

getAttachment()

public getAttachment() : array<string, mixed>|null
Return values
array<string, mixed>|null

getCompletionPercentage()

Get current completion percentage

public getCompletionPercentage() : int|null
Tags
throws
CanvasApiException
Return values
int|null

Percentage (0-100) or null if not available

getFileUploadError()

Get file upload error message if any

public getFileUploadError() : string|null
Return values
string|null

getFinishedAt()

public getFinishedAt() : DateTime|null
Return values
DateTime|null

getMigrationIssuesUrl()

public getMigrationIssuesUrl() : string|null
Return values
string|null

getMigrationType()

public getMigrationType() : string|null
Return values
string|null

getMigrationTypeTitle()

public getMigrationTypeTitle() : string|null
Return values
string|null

getMigrators()

List available migration systems

public static getMigrators(string $contextType, int $contextId) : array<string|int, Migrator>
Parameters
$contextType : string

Context type (accounts, courses, groups, users)

$contextId : int

Context ID

Tags
throws
CanvasApiException
Return values
array<string|int, Migrator>

getPreAttachment()

public getPreAttachment() : array<string, mixed>|null
Return values
array<string, mixed>|null

getProgressUrl()

public getProgressUrl() : string|null
Return values
string|null

getSelectiveData()

Get selective import data

public getSelectiveData([string|null $type = null ]) : array<string|int, mixed>
Parameters
$type : string|null = null

The type of content to enumerate

Tags
throws
CanvasApiException
Return values
array<string|int, mixed>

getSettings()

public getSettings() : array<string, mixed>|null
Return values
array<string, mixed>|null

getStartedAt()

public getStartedAt() : DateTime|null
Return values
DateTime|null

getWorkflowState()

public getWorkflowState() : string|null
Return values
string|null

hasFileUploadError()

Check if file upload had an error

public hasFileUploadError() : bool
Return values
bool

importCommonCartridge()

Create a Common Cartridge import migration

public static importCommonCartridge(int $courseId, string $filePath[, array<string, mixed> $options = [] ]) : self
Parameters
$courseId : int

The course to import content TO

$filePath : string

Path to the .imscc file

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
self

importZipFile()

Create a ZIP file import migration

public static importZipFile(int $courseId, string $filePath[, array<string, mixed> $options = [] ]) : self
Parameters
$courseId : int

The course to import content TO

$filePath : string

Path to the .zip file

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
self

isCompleted()

Check if the migration is completed

public isCompleted() : bool
Return values
bool

isFailed()

Check if the migration has failed

public isFailed() : bool
Return values
bool

isFileUploadPending()

Check if file upload is required and pending

public isFileUploadPending() : bool
Return values
bool

isFinished()

Check if the migration is finished (completed or failed)

public isFinished() : bool
Return values
bool

isRunning()

Check if the migration is running

public isRunning() : bool
Return values
bool

isWaitingForSelect()

Check if the migration is waiting for selection

public isWaitingForSelect() : bool
Return values
bool

processFileUpload()

Process file upload for migration if needed

public processFileUpload(string $filePath) : self

This handles the 3-step file upload process for migrations that require files. Should be called after create() if the migration has pre_attachment upload data.

Parameters
$filePath : string

Path to the file to upload

Tags
throws
CanvasApiException
Return values
self

setAttachment()

public setAttachment(array<string, mixed>|null $attachment) : void
Parameters
$attachment : array<string, mixed>|null

setFinishedAt()

public setFinishedAt(DateTime|null $finishedAt) : void
Parameters
$finishedAt : DateTime|null

setMigrationIssuesUrl()

public setMigrationIssuesUrl(string|null $migrationIssuesUrl) : void
Parameters
$migrationIssuesUrl : string|null

setMigrationType()

public setMigrationType(string|null $migrationType) : void
Parameters
$migrationType : string|null

setMigrationTypeTitle()

public setMigrationTypeTitle(string|null $migrationTypeTitle) : void
Parameters
$migrationTypeTitle : string|null

setPreAttachment()

public setPreAttachment(array<string, mixed>|null $preAttachment) : void
Parameters
$preAttachment : array<string, mixed>|null

setProgressUrl()

public setProgressUrl(string|null $progressUrl) : void
Parameters
$progressUrl : string|null

setSettings()

public setSettings(array<string, mixed>|null $settings) : void
Parameters
$settings : array<string, mixed>|null

setStartedAt()

public setStartedAt(DateTime|null $startedAt) : void
Parameters
$startedAt : DateTime|null

setUserId()

public setUserId(int|null $userId) : void
Parameters
$userId : int|null

setWorkflowState()

public setWorkflowState(string|null $workflowState) : void
Parameters
$workflowState : string|null

updateInContext()

Update content migration in a specific context

public static updateInContext(string $contextType, int $contextId, int $id, array<string, mixed>|UpdateContentMigrationDTO $data) : self
Parameters
$contextType : string

Context type (accounts, courses, groups, users)

$contextId : int

Context ID

$id : int

Migration ID

$data : array<string, mixed>|UpdateContentMigrationDTO

Update data

Tags
throws
CanvasApiException
Return values
self

waitForCompletion()

Wait for the migration to complete

public waitForCompletion([int $maxWaitSeconds = 300 ][, int $intervalSeconds = 2 ]) : self
Parameters
$maxWaitSeconds : int = 300

Maximum time to wait in seconds (default: 300)

$intervalSeconds : int = 2

Polling interval in seconds (default: 2)

Tags
throws
CanvasApiException
Return values
self

waitForState()

Wait for the migration to reach a specific state

public waitForState(string $targetState[, int $maxWaitSeconds = 300 ][, int $intervalSeconds = 2 ]) : self
Parameters
$targetState : string

The state to wait for

$maxWaitSeconds : int = 300

Maximum time to wait in seconds (default: 300)

$intervalSeconds : int = 2

Polling interval in seconds (default: 2)

Tags
throws
CanvasApiException
Return values
self

castValue()

Cast a value to the correct type

protected castValue(string $key, mixed $value) : DateTime|mixed
Parameters
$key : string
$value : mixed
Tags
throws
Exception
Return values
DateTime|mixed

checkApiClient()

Check if the API client is set, if not, instantiate a new one

protected static checkApiClient() : void

convertPaginatedResponseToModels()

Helper method to convert paginated response data to model instances

protected static convertPaginatedResponseToModels(PaginatedResponse $paginatedResponse) : array<string|int, static>
Parameters
$paginatedResponse : PaginatedResponse
Return values
array<string|int, static>

getEndpoint()

Get the API endpoint for this resource

protected static getEndpoint() : string
Return values
string

getPaginatedResponse()

Helper method to get paginated response from API endpoint

protected static getPaginatedResponse(string $endpoint[, array<string|int, mixed> $params = [] ]) : PaginatedResponse
Parameters
$endpoint : string

The API endpoint path

$params : array<string|int, mixed> = []

Query parameters for the request

Return values
PaginatedResponse

populate()

Populate the object with new data

protected populate(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>
Tags
throws
Exception

toDtoArray()

Convert the object to an array

protected toDtoArray() : array<string|int, mixed>
Return values
array<string|int, mixed>

buildMultipartData()

Build multipart data for file upload

private buildMultipartData(array<string, mixed> $uploadParams, string $filePath, resource|null &$fileResource) : array<string|int, array<string, mixed>>
Parameters
$uploadParams : array<string, mixed>

Upload parameters from pre_attachment

$filePath : string

Path to the file to upload

$fileResource : resource|null

Reference to store the file resource

Tags
throws
CanvasApiException
Return values
array<string|int, array<string, mixed>>

Multipart data array


        
On this page

Search results