Upload zip with CSVs without using the OneRoster app UI

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

DataDescription
Partner
District
CSV File
User CredentialsThese 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:

  1. 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:
HeaderValue
Content-typeapplication/json
Acceptapplication/json
AuthorizationBasic 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
  1. 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]
  2. 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 a zip file

3. Handle the response

There are several http codes that might be received in the response:

500An application error has occurred. There's no more the client can do except perhaps warn warn Gooru of this
404 Not FoundCheck 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 UnauthorizedCheck 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 RequestCheck 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 ErrorCheck 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 OKThis 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