This guide can be used as a tutorial for uploading a zip containing OneRoster-standarized CSVs without the aid of the user-interface provided by the Gooru's OneRoster application.
Bear in mind that the code we're using to build and make the request is written in Ruby, but it should be easily replicated in another programming language
1. Gather the information
We'll need the following information to build the request
Data | Description |
---|---|
Partner | |
District | |
CSV File | |
User Credentials | These consist of a client id and a client key. A client should have them. |
2. Make the request
This is the Ruby code that allows us to make the request that successfully uploads a zip with the csvs and which then proceeds with the migration/exporting of records:
require 'rest_client'
payload = {
zip_upload: {
partner: 'Partner Name',
district: 'District Name',
filename: File.open('path/to/file_containing_csvs.zip', 'r')
}
}
RestClient.post 'https://oneroster.gooru.org/zip_uploads',
payload,
{
content_type: :json,
accept: :json,
Authorization: 'Basic ************'
}
There are several details that are worth mentioning:
- For this code to run, Ruby 2+ is needed. Also, the rest-client gem should be installed (https://github.com/rest-client/rest-client).
2.Three request headers must be specified:
Header | Value |
---|---|
Content-type | application/json |
Accept | application/json |
Authorization | Basic followed by the base 64 encoded client id and client key. For example, if client id equals 1111 and client key equals 2222 , we'll need to join both values with a : in between: 1111:2222 . Then we have to encode them using base 64. This gives MTExMToyMjIy . That means that our Authorization header must look like Basic MTExMToyMjIy |
- It may not be evident in the code, so here but the names of the keys of the payload must be:
zip_upload[partner]
,zip_upload[district]
,zip_upload[filename]
- The request must be sent as multipart. In the Ruby example code, the rest-client gem recognizes that a file is present in the payload, and sets
multipart true
automatically, but in other languages/tools this might need to be specified.
The request takes too long to complete
Depending on how much your zip file has, and how fast is your Internet connection, this request will take some time to be completed.
File restriction
The limit on the file size is
200 MB
. The file must also be azip
file
3. Handle the response
There are several http codes that might be received in the response:
500 | An application error has occurred. There's no more the client can do except perhaps warn warn Gooru of this |
404 Not Found | Check the url in the request: it might have been mistyped. Also, check that the HTTP method used in the request is POST . If everything is correctly specified and you're still getting 404 , please contact Gooru |
401 Unauthorized | Check that you're correctly submitting the Authorization header. Check that you are submitting the correct encoded credentials. If you think everything is ok on your end, please contact Gooru |
400 Bad Request | Check that your request has ALL of the fields in the payload, and that they have the specified format (zip_upload[partner] and so). |
422 Validation Error | Check that all of the fields in the request have a value. This differs from 400 because you might have the payload correctly formatted with all the fields, but some field may have no value (For example `zip_upload[district] might be empty and it shouldn't) |
200 OK | This response is the nice one. It should have a body, in JSON, which looks like this:{"zip_upload": { "id":96, "uuid": "ff9efe89-9b46-4961-b693-525236578994"}} .This is just information regarding the upload you just did. If you want to view the progress on the migration, you could use the received uuid like this:https://oneroster.gooru.org/zip_uploads/ Where <uuid> is the uuid of the zip upload you just did. However, you'll need to use the UI and be logged in to enter the link |