One Roster Step by Step Setup

This guide helps a client use the OneRoster import platform. It is meant to be read completely.

Request client id and client key

In order to access to the platform, it is necessary for the user to have in possession a client id and a client key. To obtain them, the user must contact Gooru directly. Gooru will ask for some information, including the client's email.

📘

A client id is a GUUID (for more information, read https://en.wikipedia.org/wiki/Globally_unique_identifier) and it look like this: 1a3794be-c509-4e55-aaf0-dbd2c6ec645c

Log in into the platform

  1. Enter OneRoster app
1137
  1. Type or copy-paste your client id and your client key.
  2. Click on Log in

❗️

After I clicked on Log in, I still am in the same screen and a message "Invalid user" appears

The message appears because the pair client id and client key didn't match in the database. Please, be certain that you didn't mistyped them, and try again. If the error persists, please contact Gooru.

Home screen

  1. Upon arrival, you'll see something like the following picture. However, if this is your first time accessing the platform, you'll see an empty list.

📘

Regarding Logging out

You can logout by clicking on the Logout button at the top of the screen

689

The uuid column is a unique identifier generated automatically after a zip has been uploaded.

The list is sorted by the Uploaded at field, from most recent to less recent

  1. To upload a new zip, click on New

Uploading zips

  1. Upon arrival to the New screen, you'll see the following form:
937

If you want to go back to the Index screen, click on Index.

  1. To upload a zip it must comply with the following rules:
    2.1. It shouldn't exceed 200 megabytes.
    2.2. It should contain at least one csv file.
    2.3. All csv files from the zip must comply with the OneRoster standards specified here: https://www.imsglobal.org/lis/imsOneRosterv1p0/imsOneRosterCSV-v1p0.html.

  2. Once you're ready to upload a zip file, you must enter both the Partner field and the District field to enable the Choose File button

  3. Once enabled, click on it. A window will be displayed. Select just one zip file.

  4. Once selected, the upload will begin immediately. A progress bar will display show you how much percentage of the file has been uploaded.

🚧

DO NOT CLOSE THE BROWSER WINDOW

Do not close your browser's window or tab. Leave it open so the file can be completely uploaded.

  1. After the file has been uploaded, you will notice that a link View migration progress here will appear on the page in the bottom-left corner:
932
  1. If you click on the link, a new tab will open in your browser and you'll be in the Migration process screen

Migration Process Screen

  1. Upon arrival, you will see this table:
1176
ResourceSaved records (OneRoster DB)Failed records (OneRoster DB)Total Records (OneRoster DB)Exported records (Gooru)Failed records (Gooru)Total records (Gooru)
Type of the resource. For example: orgs refers to the records present in the orgs.csv fileThe number of records for the resource type which were saved to an intermediate database (not yet exported to Gooru)The number of records for the resource type which couldn't be saved to an intermediate database. This is due to the record missing data or having invalid data.

If at least one record couldn't be saved, it will be possible to click on the number in the cell (it will act as a link). This will prompt the download of a text-plain which contain all validation errors for each rejected resource.

This way, you can fix the issues and upload again
The total number of records that will be processed. This number doesn't change during the migration process.The number of records that have been successfully exported into Gooru. This number starts increasing after all valid resources are migrated into the intermediate database.The number of records that couldn't be exported into Gooru. Notice that if a record failed the fist validation and wasn't saved into the intermediate database, then the platform won't try to export it into Gooru at all. This number then refers to all those valid records which, for some reason, failed to be exported into Gooru.

If at least one record couldn't be exported, it will be possible to click on the number in the cell (it will act as a link). This will prompt the download of a zip file which contains at least one text-plain file with the exporting errors for each rejected resource.
The number of records which had been exported plus the number of records which failed the export. It's the sum of the previous two columns

If one of the csv files contained more than 500 records which are invalid (couldn't be saved into the database), then the migration process will be aborted completely. This will mean that no more csv files will be processed and that no exportation into Gooru will happen for any of the records contained in the uploaded csv files. This also includes those records which could be saved before the abortion.

A message will appear beneath the table if an abortion has ocurred:

1174

In this example, the file orgs.csv had more than 500 invalid records

As the message says, the user can fix the issues in the csvs and upload the zip again.

🚧

The re-uploaded zip MUST also contain those records that didn't present any issues the during the first migration, because there's no way of knowing if they got migrated into the database or not.

🚧

What if no abortion happened but I still had some invalid records?

You can fix them in the csvs and re-upload your zip. Records are matched first using the sourcedId value. If an existing database record matches the sourcedId of one of the csv records, then the database one will be updated. If not, then it will be created.

However, the update may fail if the csv matching record is missing or has invalid data. If this is the case, the existing database record will remain untouched.