From 372c25e6a690953a3319fe506d53300e4c6d40f4 Mon Sep 17 00:00:00 2001 From: Lucas Song Date: Tue, 16 Apr 2024 10:09:22 -0700 Subject: [PATCH 1/4] add restructuring --- docs/.vuepress/config.js | 20 +++++++++++++++---- docs/README.md | 10 ++++++++-- docs/admin-cloud-functions/README.md | 3 +++ .../append-to-admin-claims.md | 0 .../associate-assessment-uid.md | 0 .../create-administrator-account.md | 0 .../create-guest-docs-for-google-users.md | 0 .../create-new-family.md | 0 .../create-student-account.md | 0 .../mirror-orgs.md | 0 .../remove-from-admin-claims.md | 0 .../select-best-run.md | 0 .../set-uid-custom-claims.md | 0 .../soft-delete-user-assignment.md | 0 .../soft-delete-user-external-data.md | 0 .../soft-delete-user.md | 0 .../sync-assignment-created.md | 0 .../sync-assignment-deleted.md | 0 ...nc-assignments-on-administration-update.md | 0 .../sync-assignments-on-user-update.md | 0 .../sync-clever-orgs.md | 0 .../README.md | 2 +- .../assessment-cloud-functions/mirror-docs.md | 15 ++++++++++++++ 23 files changed, 43 insertions(+), 7 deletions(-) create mode 100644 docs/admin-cloud-functions/README.md rename docs/{cloud-functions => admin-cloud-functions}/append-to-admin-claims.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/associate-assessment-uid.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/create-administrator-account.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/create-guest-docs-for-google-users.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/create-new-family.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/create-student-account.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/mirror-orgs.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/remove-from-admin-claims.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/select-best-run.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/set-uid-custom-claims.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/soft-delete-user-assignment.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/soft-delete-user-external-data.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/soft-delete-user.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/sync-assignment-created.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/sync-assignment-deleted.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/sync-assignments-on-administration-update.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/sync-assignments-on-user-update.md (100%) rename docs/{cloud-functions => admin-cloud-functions}/sync-clever-orgs.md (100%) rename docs/{cloud-functions => assessment-cloud-functions}/README.md (89%) create mode 100644 docs/assessment-cloud-functions/mirror-docs.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 99244a6..76588df 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -13,7 +13,7 @@ export default defineUserConfig({ theme: defaultTheme({ logo: "https://vuejs.press/images/hero.png", - navbar: ["/databases/", "/workflows/", "/cloud-functions/","/internationalization/"], + navbar: ["/databases/", "/workflows/", "/admin-cloud-functions/", "assessment-cloud-functions", "/internationalization/"], sidebar: [ { text: "Databases", @@ -34,10 +34,22 @@ export default defineUserConfig({ children: getChildren("./docs/dashboard-components"), }, { - text: "Cloud Functions", - link: "/cloud-functions/", + text: "Assessment Cloud Functions", + link: "/assessment-cloud-functions/", collapsable: false, - children: getChildren("./docs/cloud-functions"), + children: getChildren("./docs/assessment-cloud-functions"), + }, + { + text: "Local Functions", + link: "/local-functions/", + collapsable: false, + children: getChildren("./docs/local-functions"), + }, + { + text: "Admin Cloud Functions", + link: "/admin-cloud-functions/", + collapsable: false, + children: getChildren("./docs/admin-cloud-functions"), }, { text: "Internationalization", diff --git a/docs/README.md b/docs/README.md index 6d0ac58..242d966 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,8 +5,14 @@ actions: - text: Databases link: /databases/ type: secondary - - text: Cloud Functions - link: /cloud-functions/ + - text: Admin Cloud Functions + link: /admin-cloud-functions/ + type: secondary + - text: Assessment Cloud Functions + link: /assessment-cloud-functions/ + type: secondary + - text: Local Functions + link: /local-functions/ type: secondary - text: Workflows link: /workflows/ diff --git a/docs/admin-cloud-functions/README.md b/docs/admin-cloud-functions/README.md new file mode 100644 index 0000000..8f71f96 --- /dev/null +++ b/docs/admin-cloud-functions/README.md @@ -0,0 +1,3 @@ +# Admin Cloud Functions + +Admin Cloud functions serve an important role on the ROAR platform. They are hosted on the platform's Google Firebase projects. They are built in TypeScipt using the Google Admin SDK. As such, each function has unrestricted access to the databases. diff --git a/docs/cloud-functions/append-to-admin-claims.md b/docs/admin-cloud-functions/append-to-admin-claims.md similarity index 100% rename from docs/cloud-functions/append-to-admin-claims.md rename to docs/admin-cloud-functions/append-to-admin-claims.md diff --git a/docs/cloud-functions/associate-assessment-uid.md b/docs/admin-cloud-functions/associate-assessment-uid.md similarity index 100% rename from docs/cloud-functions/associate-assessment-uid.md rename to docs/admin-cloud-functions/associate-assessment-uid.md diff --git a/docs/cloud-functions/create-administrator-account.md b/docs/admin-cloud-functions/create-administrator-account.md similarity index 100% rename from docs/cloud-functions/create-administrator-account.md rename to docs/admin-cloud-functions/create-administrator-account.md diff --git a/docs/cloud-functions/create-guest-docs-for-google-users.md b/docs/admin-cloud-functions/create-guest-docs-for-google-users.md similarity index 100% rename from docs/cloud-functions/create-guest-docs-for-google-users.md rename to docs/admin-cloud-functions/create-guest-docs-for-google-users.md diff --git a/docs/cloud-functions/create-new-family.md b/docs/admin-cloud-functions/create-new-family.md similarity index 100% rename from docs/cloud-functions/create-new-family.md rename to docs/admin-cloud-functions/create-new-family.md diff --git a/docs/cloud-functions/create-student-account.md b/docs/admin-cloud-functions/create-student-account.md similarity index 100% rename from docs/cloud-functions/create-student-account.md rename to docs/admin-cloud-functions/create-student-account.md diff --git a/docs/cloud-functions/mirror-orgs.md b/docs/admin-cloud-functions/mirror-orgs.md similarity index 100% rename from docs/cloud-functions/mirror-orgs.md rename to docs/admin-cloud-functions/mirror-orgs.md diff --git a/docs/cloud-functions/remove-from-admin-claims.md b/docs/admin-cloud-functions/remove-from-admin-claims.md similarity index 100% rename from docs/cloud-functions/remove-from-admin-claims.md rename to docs/admin-cloud-functions/remove-from-admin-claims.md diff --git a/docs/cloud-functions/select-best-run.md b/docs/admin-cloud-functions/select-best-run.md similarity index 100% rename from docs/cloud-functions/select-best-run.md rename to docs/admin-cloud-functions/select-best-run.md diff --git a/docs/cloud-functions/set-uid-custom-claims.md b/docs/admin-cloud-functions/set-uid-custom-claims.md similarity index 100% rename from docs/cloud-functions/set-uid-custom-claims.md rename to docs/admin-cloud-functions/set-uid-custom-claims.md diff --git a/docs/cloud-functions/soft-delete-user-assignment.md b/docs/admin-cloud-functions/soft-delete-user-assignment.md similarity index 100% rename from docs/cloud-functions/soft-delete-user-assignment.md rename to docs/admin-cloud-functions/soft-delete-user-assignment.md diff --git a/docs/cloud-functions/soft-delete-user-external-data.md b/docs/admin-cloud-functions/soft-delete-user-external-data.md similarity index 100% rename from docs/cloud-functions/soft-delete-user-external-data.md rename to docs/admin-cloud-functions/soft-delete-user-external-data.md diff --git a/docs/cloud-functions/soft-delete-user.md b/docs/admin-cloud-functions/soft-delete-user.md similarity index 100% rename from docs/cloud-functions/soft-delete-user.md rename to docs/admin-cloud-functions/soft-delete-user.md diff --git a/docs/cloud-functions/sync-assignment-created.md b/docs/admin-cloud-functions/sync-assignment-created.md similarity index 100% rename from docs/cloud-functions/sync-assignment-created.md rename to docs/admin-cloud-functions/sync-assignment-created.md diff --git a/docs/cloud-functions/sync-assignment-deleted.md b/docs/admin-cloud-functions/sync-assignment-deleted.md similarity index 100% rename from docs/cloud-functions/sync-assignment-deleted.md rename to docs/admin-cloud-functions/sync-assignment-deleted.md diff --git a/docs/cloud-functions/sync-assignments-on-administration-update.md b/docs/admin-cloud-functions/sync-assignments-on-administration-update.md similarity index 100% rename from docs/cloud-functions/sync-assignments-on-administration-update.md rename to docs/admin-cloud-functions/sync-assignments-on-administration-update.md diff --git a/docs/cloud-functions/sync-assignments-on-user-update.md b/docs/admin-cloud-functions/sync-assignments-on-user-update.md similarity index 100% rename from docs/cloud-functions/sync-assignments-on-user-update.md rename to docs/admin-cloud-functions/sync-assignments-on-user-update.md diff --git a/docs/cloud-functions/sync-clever-orgs.md b/docs/admin-cloud-functions/sync-clever-orgs.md similarity index 100% rename from docs/cloud-functions/sync-clever-orgs.md rename to docs/admin-cloud-functions/sync-clever-orgs.md diff --git a/docs/cloud-functions/README.md b/docs/assessment-cloud-functions/README.md similarity index 89% rename from docs/cloud-functions/README.md rename to docs/assessment-cloud-functions/README.md index 20a073f..99e5568 100644 --- a/docs/cloud-functions/README.md +++ b/docs/assessment-cloud-functions/README.md @@ -1,3 +1,3 @@ -# Cloud Functions +# Assessment Cloud Functions Cloud functions serve an important role on the ROAR platform. They are hosted on the platform's Google Firebase projects. They are built in TypeScipt using the Google Admin SDK. As such, each function has unrestricted access to the databases. diff --git a/docs/assessment-cloud-functions/mirror-docs.md b/docs/assessment-cloud-functions/mirror-docs.md new file mode 100644 index 0000000..21e67e0 --- /dev/null +++ b/docs/assessment-cloud-functions/mirror-docs.md @@ -0,0 +1,15 @@ +# Mirroring Functions + +## Mirror Users + +## Mirror Districts + +## Mirror Schools + +## Mirror Classes + +## Mirror Groups + +## Helper Functions + +### Mirror Docs \ No newline at end of file From 7b00be089698e6084d25d32c6190378a4a27fd72 Mon Sep 17 00:00:00 2001 From: Lucas Song Date: Tue, 16 Apr 2024 10:11:02 -0700 Subject: [PATCH 2/4] add local fx readme --- docs/local-functions/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/local-functions/README.md diff --git a/docs/local-functions/README.md b/docs/local-functions/README.md new file mode 100644 index 0000000..c0131a8 --- /dev/null +++ b/docs/local-functions/README.md @@ -0,0 +1,3 @@ +# Local Functions + +Functions that may be run locally to perform operations on the administration or assessment databases. \ No newline at end of file From e6527fba1251186679cdde00b5210f0387151d9c Mon Sep 17 00:00:00 2001 From: Lucas Song Date: Tue, 16 Apr 2024 12:40:35 -0700 Subject: [PATCH 3/4] add docs --- .../assessment-cloud-functions/mirror-docs.md | 74 ++++++++++++++++++- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/docs/assessment-cloud-functions/mirror-docs.md b/docs/assessment-cloud-functions/mirror-docs.md index 21e67e0..df7589d 100644 --- a/docs/assessment-cloud-functions/mirror-docs.md +++ b/docs/assessment-cloud-functions/mirror-docs.md @@ -1,15 +1,85 @@ # Mirroring Functions +The mirroring functions are used to prevent our two stores from getting out of sync. + ## Mirror Users +The `MirrorUsers` function copies over any userdata that is created or updated in the administration database to the assessment database. As our assessment database cannot retain any personal identifiable information, we pass in an array of fields that are to be excluded in the copy. These include: + +``` +- studentData: {} +- name: String +- email: String +- assignments: [] +``` + +**Trigger:** When a user is written to the admin database (`users/{roarUid}`) + +**Logic:** The logic in this mirror function simple takes in the currDocData (the updated document data that triggered the call), parses out `grade`, `schoolLevel`, `birthMonth` and `birthYear` from the student's `studentData` object, and uses the `mirrorDoc` function to copy the data over. + ## Mirror Districts +When a district is created, updated, or deleted, we want to trigger any necessary changes to assignments for users in that district. For example, suppose a district adds a new school to its `schools` field. We want to make sure that all users in the new school receive assignments for any administration assigned to a district. Here we enumerate the possible changes to a district document: + +1. New document created - no action necessary, no administrations will have been assigned +2. Adding new schools to the `schools` field - handled in the else if (currData) block + - +3. Removing schools from the `schools` field - handled in the else if (currData) block +4. Adding new groups to the `subGroups` field - handled in the else if (currData) block +5. Removing groups from the `subGroups` field - handled in the else if (currData) block +6. Entire document deleted - handled in the else block below + ## Mirror Schools +When a school is created, updated, or deleted, we want to trigger any necessary changes to assignments for users in that district. For example, suppose a school adds a new class to its ``classes`` field. We want to make sure that all users in the new class receive assignments for any administration assigned to the school. Here we enumerate the possible +changes to a school document: + +1. New document created - handled in the if (currData && !prevData) block +2. Adding new schools to the ``classes`` field - handled in the else if (currData) block +3. Removing schools from the ``classes`` field - handled in the else if (currData) block +4. Adding new groups to the ``subGroups`` field - handled in the else if (currData) block +5. Removing groups from the ``subGroups`` field - handled in the else if (currData) block +6. Changing the ``districtId`` field - handled in the else if (currData) block +7. Entire document deleted - handled in the else block below + ## Mirror Classes -## Mirror Groups + +When a class is created, updated, or deleted, we want to trigger any necessary changes to assignments for users in that class. For example, suppose a class changes its ``schoolId`` field. We want to make sure that all users in the class receive assignments for the new school and changes to a school document: + +1. New document created - handled in the if (currData && !prevData) block +2. Adding new groups to the ``subGroups`` field - handled in the else if (currData) block +3. Removing groups from the ``subGroups`` field - handled in the else if (currData) block +4. Changing the ``districtId`` field - handled in the else if (currData) block +5. Changing the ``schoolId`` field - handled in the else if (currData) block +6. Entire document deleted - handled in the else block below + +## Mirror Groups + + +When a family is created, updated, or deleted, we want to trigger any necessary changes to assignments for users in that family. For example, suppose a family changes its ``subGroups`` field. We want to make sure that all users in those subGroups receive assignments for the family. Here we enumerate the possible changes to a family document: + +1. New document created - handled in the if (currData && !prevData) block +2. Adding new groups to the ``subGroups`` field - handled in the else if (currData) block +3. Removing groups from the ``subGroups`` field - handled in the else if (currData) block +4. Changing the ``parentGroupId`` field - handled in the else if (currData) block +4. Changing the ``parentOrgType`` field - handled in the else if (currData) block +5. Changing the ``familyId`` field - handled in the else if (currData) block +6. Entire document deleted - handled in the else block below ## Helper Functions -### Mirror Docs \ No newline at end of file +### Mirror Doc + +The mirrorDoc function is a helper function used extensively throughout the mirroring functions. It takes in 3 parameters: + +- `event`: The event that triggers the mirror function. This can be a write, update, or delete. +- `excludeFields`: Fields to exclude from the mirror operation. This is pertinent for mirror operations that may contain PID. +- `additionalData`: Additional fields to copy over to the write + +The logic for this function checks to see if the triggering event is from a document being deleted, created, or updated. + +If a document is being updated, it will remove the excluded fields passed in with a call to the lodash `_omit` function. Then, we will add any fields added in `additionalData` and use a `.set` function to update the new document in the `gse-roar-assessments` store. + +### getClassesAndSubGroupsFromSchool + From 21c52900d55e8c47ee2b480e01048f3d1007b2d5 Mon Sep 17 00:00:00 2001 From: Lucas Song Date: Tue, 16 Apr 2024 13:18:18 -0700 Subject: [PATCH 4/4] add mirrorFamily --- docs/assessment-cloud-functions/mirror-docs.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/assessment-cloud-functions/mirror-docs.md b/docs/assessment-cloud-functions/mirror-docs.md index df7589d..4d87df6 100644 --- a/docs/assessment-cloud-functions/mirror-docs.md +++ b/docs/assessment-cloud-functions/mirror-docs.md @@ -67,6 +67,16 @@ When a family is created, updated, or deleted, we want to trigger any necessary 5. Changing the ``familyId`` field - handled in the else if (currData) block 6. Entire document deleted - handled in the else block below +## Mirror Familes + + +When a family is created, updated, or deleted, we want to trigger any necessary changes to assignments for users in that family. For example, suppose a family changes its ``subGroups`` field. We want to make sure that all users in those subGroups receive assignments for the family. Here we enumerate the possible changes to a family document: + +1. New document created - no action necessary +2. Adding new groups to the ``subGroups`` field - handled in the else if (currData) block +3. Removing groups from the ``subGroups`` field - handled in the else if (currData) block +4. Entire document deleted - handled in the else block below + ## Helper Functions ### Mirror Doc