UUIDs in JSON files

All JSON configuration files must contain a UUID (universally unique identifier) to link the on-disk JSON file to the corresponding object in the database. This looks like:

{
    "uuid": "cef0cbf3-6458-4f13-a418-ee4d7e7505dd"
}

When you make new questions, assessments, etc, you will need to add a UUID to the the JSON file. These can be generated by https://www.uuidtools.com/generate/v4 (use version-4 for random UUID).

When do you need a new UUID?

As your course is constructed, you may run into scenarios that require you to change the UUID listed within a JSON file. Below, we've listed some common instances of when the UUID should or shouldn't be changed.

  • Editing information within a JSON file: no new UUID needed. For example, if you add another Instructor to a infoCourseInstance.json, or delete a question in an infoAssessment.json, then you must not change the UUID. This is because PrairieLearn uses the UUID to know that it's still the same course instance or assessment and you just want to make a change to it. If you do inadvertently change the UUID in this way, changing it back will revert everything to the way it was with no data loss.

  • Renaming a directory: no new UUID needed. For example if you rename a question or assessment directory, then you should leave the UUID the same, so that PrairieLearn will know that this is the same object but just with a new name.

  • Copying a directory: needs a new UUID. For example, if you copy an existing question or assessment to make a new one, then you will need a new UUID for the new object, so that PrairieLearn can distinguish it from the original.

  • Moving a directory: needs a new UUID. For example, if you move an assessment between course instances or if you move a question between courses, then you will need a new UUID for the object in its new location, so that PrairieLearn will know that this object should not be associated with the original.

If you copy questions or assessments from a different course and don't give them new UUIDs, then a local development copy of PrairieLearn running on your own machine may not be able to detect that you have not changed the UUIDs. This will only be detected when you sync your course to the production PrairieLearn server, at which point it will give an error.

If you incorrectly change the UUID in a infoCourseInstance.json file when you didn't mean to, then you will get a sync error like:

Error: UUID 0339b989-d1f2-4f96-bcba-8717c68a64a9 from assessment exam1 in Sp18 already in use in different course instance (possibly in a different course)

An error like the one above can be fixed by reverting the UUID in the infoCourseInstance.json file back to its old value (which you can get from the git history).

Bulk addition of UUIDs

To add a UUID to all the JSON files in a course you can run the included generate_uuids.py Python script.

This script will add a UUID to the start of every JSON file that doesn't currently have one, so it's safe to run it multiple times. You will then need to commit and push these changes to GitHub.

To use the script, run:

cd <path_to_PrairieLearn>
cd tools
python generate_uuids.py <path_to_course_directory>

For example, python generate_uuids.py ~/git/pl-tam212.

If you're using the Docker container, you can avoid downloading the script by running:

docker run --rm -v /path/to/course:/course prairielearn/prairielearn python /PrairieLearn/tools/generate_uuids.py /course

Bulk replacement of UUIDs

Danger warning: To change all UUIDs in a course, you can use the above generate_uuids.py script with the --new argument. This can delete your entire course.