{"_id":"578d129bbd9f40200058dcbd","project":"56439dfe9eebf70d00490d54","parentDoc":null,"user":"55dd6b48a649eb170083b97a","category":{"_id":"578d127ed9c55c2000d4f213","__v":0,"project":"56439dfe9eebf70d00490d54","version":"56439dff9eebf70d00490d57","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T17:31:42.071Z","from_sync":false,"order":20,"slug":"one-roster","title":"One Roster"},"version":{"_id":"56439dff9eebf70d00490d57","project":"56439dfe9eebf70d00490d54","__v":26,"createdAt":"2015-11-11T19:58:55.144Z","releaseDate":"2015-11-11T19:58:55.144Z","categories":["56439dff9eebf70d00490d58","56439e17c92c470d002dec71","564ce88e802cd02100444274","564d07ff3657c43500bf1d33","564d0a312da1982d00b19b64","564d2aa92da1982d00b19b8c","564d30a8b88a37210082253e","564d362c2da1982d00b19ba0","569d664371e3650d00acf018","569d7eacec29360d00f667c9","569d8006ec29360d00f667cb","569d855e0306a10d00ce99b9","569d91d571e3650d00acf04c","569d91eeceb7510d00f2a6a3","569e8c262d320817003b806d","569e8f802d320817003b8072","56b038c914dfea0d0007cf05","5717b4f0681bb41900fc575a","5718e0a4cd483219007c2c9a","571924c8e967cb1700d078e9","571e2648edc4a92b00a4cc65","576a677a6f15260e001f899b","576c5eaf5738570e00ff070f","578d127ed9c55c2000d4f213","579f90927ebe9b0e00059c50","582c0af888708a0f00570a69"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":false,"codename":"","version_clean":"1.0.0","version":"1"},"__v":2,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-18T17:32:11.840Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request client id and client key\"\n}\n[/block]\nIn 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. \n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"A client id is a GUUID (for more information, read [https://en.wikipedia.org/wiki/Globally_unique_identifier](https://en.wikipedia.org/wiki/Globally_unique_identifier)) and it look like this: *1a3794be-c509-4e55-aaf0-dbd2c6ec645c*\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Log in into the platform\"\n}\n[/block]\n1. Enter [OneRoster app](https://oneroster.gooru.org/) \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/50ACoO2JRAqQYQUp0JYr_OneRoster%20-%20Login.PNG\",\n        \"OneRoster - Login.PNG\",\n        \"1137\",\n        \"390\",\n        \"#347ab2\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n2. Type or copy-paste your *client id* and your *client key*.\n3. Click on **Log in**\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"After I clicked on Log in, I still am in the same screen and a message \\\"Invalid user\\\" appears\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Home screen\"\n}\n[/block]\n1. 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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You can logout by clicking on the **Logout** button at the top of the screen\",\n  \"title\": \"Regarding Logging out\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/NNm73ixThOrAIBqDviNe_Screenshot%20from%202016-07-15%2012-57-41.png\",\n        \"Screenshot from 2016-07-15 12-57-41.png\",\n        \"689\",\n        \"798\",\n        \"#457bbd\",\n        \"\"\n      ],\n      \"caption\": \"The uuid column is a unique identifier generated automatically after a zip has been uploaded.\\n\\nThe list is sorted by the Uploaded at field, from most recent to less recent\"\n    }\n  ]\n}\n[/block]\n2. To upload a new zip, click on **New**\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Uploading zips\"\n}\n[/block]\n1. Upon arrival to the **New** screen, you'll see the following form:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/y7l6CFScROySV7rq4MwG_Screenshot%20from%202016-07-15%2013-02-32.png\",\n        \"Screenshot from 2016-07-15 13-02-32.png\",\n        \"937\",\n        \"477\",\n        \"#416bb1\",\n        \"\"\n      ],\n      \"caption\": \"If you want to go back to the Index screen, click on **Index**.\"\n    }\n  ]\n}\n[/block]\n2. To upload a zip it must comply with the following rules:\n  2.1. It shouldn't exceed 200 megabytes.\n  2.2. It should contain at least one *csv* file.\n  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.\n\n3. 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\n4. Once enabled, click on it. A window will be displayed. Select just one zip file.\n5. Once selected, the upload will begin immediately. A progress bar will display show you how much percentage of the file has been uploaded.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Do not close your browser's window or tab. Leave it open so the file can be completely uploaded.\",\n  \"title\": \"DO NOT CLOSE THE BROWSER WINDOW\"\n}\n[/block]\n6. 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:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/86AeovjRkKAbQyHAkgi7_Screenshot%20from%202016-07-15%2013-11-43.png\",\n        \"Screenshot from 2016-07-15 13-11-43.png\",\n        \"932\",\n        \"556\",\n        \"#925035\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n7. If you click on the link, a new tab will open in your browser and you'll be in the **Migration process screen**\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Migration Process Screen\"\n}\n[/block]\n1. Upon arrival, you will see this table:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/OvNFiOzRGjsDu0qeR1FA_Screenshot%20from%202016-07-15%2013-17-11.png\",\n        \"Screenshot from 2016-07-15 13-17-11.png\",\n        \"1176\",\n        \"540\",\n        \"#4370b6\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Resource\",\n    \"0-0\": \"Type of the resource. For example: *orgs* refers to the records present in the *orgs.csv* file\",\n    \"h-1\": \"Saved records (OneRoster DB)\",\n    \"h-2\": \"Failed records (OneRoster DB)\",\n    \"h-3\": \"Total Records (OneRoster DB)\",\n    \"h-4\": \"Exported records (Gooru)\",\n    \"h-5\": \"Failed records (Gooru)\",\n    \"h-6\": \"Total records (Gooru)\",\n    \"0-1\": \"The number of records for the resource type which were saved to an intermediate database (not yet exported to Gooru)\",\n    \"0-2\": \"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.\\n\\nIf 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.\\n\\nThis way, you can fix the issues and upload again\",\n    \"0-3\": \"The total number of records that will be processed. This number doesn't change during the migration process.\",\n    \"0-4\": \"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.\",\n    \"0-5\": \"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.\\n\\nIf 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.\",\n    \"0-6\": \"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\"\n  },\n  \"cols\": 7,\n  \"rows\": 1\n}\n[/block]\nIf 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.\n\nA message will appear beneath the table if an abortion has ocurred:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e3f3000-Screenshot_from_2016-07-21_15-41-22.png\",\n        \"Screenshot from 2016-07-21 15-41-22.png\",\n        1174,\n        127,\n        \"#fc1519\"\n      ],\n      \"caption\": \"In this example, the file `orgs.csv` had more than 500 invalid records\"\n    }\n  ]\n}\n[/block]\nAs the message says, the user can fix the issues in the csvs and upload the zip again. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"What if no abortion happened but I still had some invalid records?\",\n  \"body\": \"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.\\n\\nHowever, 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.\"\n}\n[/block]","excerpt":"This guide helps a client use the OneRoster import platform. It is meant to be read completely.","slug":"step-by-step-setup","type":"basic","title":"One Roster Step by Step Setup"}

One Roster Step by Step Setup

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

[block:api-header] { "type": "basic", "title": "Request client id and client key" } [/block] 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. [block:callout] { "type": "info", "title": "", "body": "A client id is a GUUID (for more information, read [https://en.wikipedia.org/wiki/Globally_unique_identifier](https://en.wikipedia.org/wiki/Globally_unique_identifier)) and it look like this: *1a3794be-c509-4e55-aaf0-dbd2c6ec645c*" } [/block] [block:api-header] { "type": "basic", "title": "Log in into the platform" } [/block] 1. Enter [OneRoster app](https://oneroster.gooru.org/) [block:image] { "images": [ { "image": [ "https://files.readme.io/50ACoO2JRAqQYQUp0JYr_OneRoster%20-%20Login.PNG", "OneRoster - Login.PNG", "1137", "390", "#347ab2", "" ] } ] } [/block] 2. Type or copy-paste your *client id* and your *client key*. 3. Click on **Log in** [block:callout] { "type": "danger", "title": "After I clicked on Log in, I still am in the same screen and a message \"Invalid user\" appears", "body": "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." } [/block] [block:api-header] { "type": "basic", "title": "Home screen" } [/block] 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. [block:callout] { "type": "info", "body": "You can logout by clicking on the **Logout** button at the top of the screen", "title": "Regarding Logging out" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/NNm73ixThOrAIBqDviNe_Screenshot%20from%202016-07-15%2012-57-41.png", "Screenshot from 2016-07-15 12-57-41.png", "689", "798", "#457bbd", "" ], "caption": "The uuid column is a unique identifier generated automatically after a zip has been uploaded.\n\nThe list is sorted by the Uploaded at field, from most recent to less recent" } ] } [/block] 2. To upload a new zip, click on **New** [block:api-header] { "type": "basic", "title": "Uploading zips" } [/block] 1. Upon arrival to the **New** screen, you'll see the following form: [block:image] { "images": [ { "image": [ "https://files.readme.io/y7l6CFScROySV7rq4MwG_Screenshot%20from%202016-07-15%2013-02-32.png", "Screenshot from 2016-07-15 13-02-32.png", "937", "477", "#416bb1", "" ], "caption": "If you want to go back to the Index screen, click on **Index**." } ] } [/block] 2. 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. 3. 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 4. Once enabled, click on it. A window will be displayed. Select just one zip file. 5. Once selected, the upload will begin immediately. A progress bar will display show you how much percentage of the file has been uploaded. [block:callout] { "type": "warning", "body": "Do not close your browser's window or tab. Leave it open so the file can be completely uploaded.", "title": "DO NOT CLOSE THE BROWSER WINDOW" } [/block] 6. 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/86AeovjRkKAbQyHAkgi7_Screenshot%20from%202016-07-15%2013-11-43.png", "Screenshot from 2016-07-15 13-11-43.png", "932", "556", "#925035", "" ] } ] } [/block] 7. If you click on the link, a new tab will open in your browser and you'll be in the **Migration process screen** [block:api-header] { "type": "basic", "title": "Migration Process Screen" } [/block] 1. Upon arrival, you will see this table: [block:image] { "images": [ { "image": [ "https://files.readme.io/OvNFiOzRGjsDu0qeR1FA_Screenshot%20from%202016-07-15%2013-17-11.png", "Screenshot from 2016-07-15 13-17-11.png", "1176", "540", "#4370b6", "" ], "caption": "" } ] } [/block] [block:parameters] { "data": { "h-0": "Resource", "0-0": "Type of the resource. For example: *orgs* refers to the records present in the *orgs.csv* file", "h-1": "Saved records (OneRoster DB)", "h-2": "Failed records (OneRoster DB)", "h-3": "Total Records (OneRoster DB)", "h-4": "Exported records (Gooru)", "h-5": "Failed records (Gooru)", "h-6": "Total records (Gooru)", "0-1": "The number of records for the resource type which were saved to an intermediate database (not yet exported to Gooru)", "0-2": "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.\n\nIf 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.\n\nThis way, you can fix the issues and upload again", "0-3": "The total number of records that will be processed. This number doesn't change during the migration process.", "0-4": "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.", "0-5": "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.\n\nIf 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.", "0-6": "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" }, "cols": 7, "rows": 1 } [/block] 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/e3f3000-Screenshot_from_2016-07-21_15-41-22.png", "Screenshot from 2016-07-21 15-41-22.png", 1174, 127, "#fc1519" ], "caption": "In this example, the file `orgs.csv` had more than 500 invalid records" } ] } [/block] As the message says, the user can fix the issues in the csvs and upload the zip again. [block:callout] { "type": "warning", "body": "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." } [/block] [block:callout] { "type": "warning", "title": "What if no abortion happened but I still had some invalid records?", "body": "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.\n\nHowever, 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." } [/block]