On your computer or operating system, ensure that cURL is installed properly on your computer or operating system.

OS X & Linux (Ubuntu)

cURL should already be installed and run from the Terminal application.

cURL may already be installed. If not already installed, run the following command with a user that has sudo privileges:

sudo apt-get install curl

After installing cURL, test the installation by typing the following command on a terminal or command prompt:

curl --version

If successfully installed, the version of cURL should be displayed.

Windows

If you are planning to use Windows as your import server you should consider using PowerShell instead of cURL for your production import tool. PowerShell is native to Windows and should result in a more reliable import script than using cURL and a batch file. We only recommend using cURL on Windows for testing purposes. Learn how to install PowerShell on Windows.

Practice using the API before adding the complexity of a script.

1. In the “tmp” directory, create a CSV file name \P\P\P\Pthat will create a basic course. The file name is case sensitive. Or, you can also use this example file: test_course.csv
2. Open a terminal command prompt and change directory into the “tmp” directory.
3. Run the command below replacing <api_token> with the API token you created earlier and <canvas_fqdn> with the domain name you use to access Canvas (example: institution_name.test.instructure.com):

curl -F attachment=@test_course.csv -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports.json?import_type=instructure_csv'

Upon success, you should receive a string of JSON back from the server that indicates the import has been created and provides an ID for the import job. The JSON will look something like:

{"created_at":"2014-02-27T13:03:39Z","ended_at":null,"updated_at":"2014-02-27T13:03:39Z","progress":0,"id":6670997,"workflow_state":"created","data":{"import_type":"instructure_csv"}}

The "id" and "workflow_state" parameters are important pieces of information to know as you develop your script. Their absence or value could indicate a problem. If you did not get an "id" parameter, or your "workflow_state" tag is anything other than created, you will need to troubleshoot the cause before proceeding.

Note: When this command is complete, you'll need the "id" parameter to check the status of an import.

An important part of the automated import process is to know the status of your previous import before processing your next import.

If you decide to do a standard import, you must fix the previous import before processing your next import because information may be lost from the failed/incomplete import job. If you are using full batch imports, the state is still important because you do not want to start your next full batch until the preceding batch has finished. Depending on your update frequency, size of import, and other factors, a full batch import could easily overrun your time window.

Run the following command with these replacements:

• Replace <api_token> with the API token created earlier
• Replace <canvas_fqdn> with your Canvas domain
• Replace <import_id> with the ID from your test file import

curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'

The command should return a JSON response that contains the status and result if the import is complete. The following is an example of result of the command run in the previous step:

{"created_at":"2014-02-27T13:03:39Z","ended_at":"2014-02-27T13:03:39Z","updated_at":"2014-02-27T13:03:39Z","progress":100,"id":6670997,"workflow_state":"imported","data":{"import_type":"instructure_csv","supplied_batches":["course"],"counts":{"accounts":0,"terms":0,"abstract_courses":0,"courses":1,"sections":0,"xlists":0,"users":0,"enrollments":0,"groups":0,"group_memberships":0,"grade_publishing_results":0}}}

Here are a few key points to consider regarding the JSON results:

progress: In a running job, the "progress" parameter indicates the percentage complete for the job. When a job is done running, the progress will be 100 percent.

workflow_state: The "workflow_state" parameter indicates the current state of a running job. In most cases, a successfully completed job will indicate a state of "imported." If you see anything other than "imported" or "importing," you will need to stop here and troubleshoot the cause before proceeding.

• If the state is "importing," try running the command again until the state returns "imported".
• If the state is "imported_with_messages" or "failed_with_messages," check the contents of "processing_warnings" or "processing_errors".