diff --git a/.commitlintrc.json b/.commitlintrc.json new file mode 100644 index 0000000..0e12ed0 --- /dev/null +++ b/.commitlintrc.json @@ -0,0 +1,23 @@ +{ + "extends": ["@commitlint/config-conventional"], + "rules": { + "header-max-length": [2, "always", 72], + "type-enum": [ + 2, + "always", + [ + "feat", + "fix", + "docs", + "style", + "refactor", + "perf", + "test", + "build", + "ci", + "chore", + "revert" + ] + ] + } +} diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..3293aa9 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,20 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.md] +# Markdown sometimes uses trailing spaces for hard breaks. We disable hard +# breaks at the lint level (no-trailing-spaces.br_spaces=0) so this stays safe. +trim_trailing_whitespace = true + +[*.{yml,yaml,json}] +indent_size = 2 + +[Makefile] +indent_style = tab diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ca4f79b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,29 @@ + + +## Summary + + + +## Type of change + +* [ ] New page +* [ ] Edit to existing page +* [ ] Rename / move +* [ ] Tooling / CI / config +* [ ] Other (describe) + +## Pre-merge checklist + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full conventions. + +* [ ] Every new page has YAML frontmatter with `description:` +* [ ] Every `` tag has a non-empty `alt=""` attribute +* [ ] New files use lowercase kebab-case names (no `README (3).md` style) +* [ ] Every new page is referenced from the appropriate `SUMMARY.md` +* [ ] Internal terminology uses **Toolkit** (not Component); customer-facing uses **toolkit** (one word) +* [ ] Commit messages follow Conventional Commits (or GitBook back-sync commits have been rewritten) +* [ ] Link check, markdown lint, spell check, and commit lint CI are green + +## Related issues / Jira tickets + + diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml new file mode 100644 index 0000000..8de0855 --- /dev/null +++ b/.github/workflows/commitlint.yml @@ -0,0 +1,21 @@ +name: Commit lint + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + commitlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run commitlint + uses: wagoid/commitlint-github-action@v6 + with: + configFile: .commitlintrc.json + # GitBook back-sync commits land directly on master, not via PRs, + # so PRs are dev-authored and must follow Conventional Commits. + failOnWarnings: false diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml new file mode 100644 index 0000000..d2c5ac5 --- /dev/null +++ b/.github/workflows/link-check.yml @@ -0,0 +1,49 @@ +name: Link check + +on: + pull_request: + paths: + - '**/*.md' + - '**/SUMMARY.md' + - '.github/workflows/link-check.yml' + - '.lycheeignore' + push: + branches: [master] + paths: + - '**/*.md' + - '**/SUMMARY.md' + workflow_dispatch: + schedule: + # Weekly Monday 09:00 UTC sweep so external link rot surfaces even + # when no PR is open. + - cron: '0 9 * * 1' + +jobs: + lychee: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run lychee + uses: lycheeverse/lychee-action@v2 + with: + # --no-progress keeps logs clean + # --base resolves root-relative links against the repo root + # --exclude-mail skips mailto: links + # --accept skips 429 rate-limits as non-failures + args: >- + --no-progress + --base . + --exclude-mail + --accept 200,206,429 + './**/*.md' + fail: true + format: markdown + output: lychee-report.md + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: lychee-report + path: lychee-report.md diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..2d24240 --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,31 @@ +name: Markdown lint + +on: + pull_request: + paths: + - '**/*.md' + - '.markdownlint.json' + - '.markdownlintignore' + - '.github/workflows/markdown-lint.yml' + push: + branches: [master] + paths: + - '**/*.md' + - '.markdownlint.json' + - '.markdownlintignore' + workflow_dispatch: + +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@v18 + with: + config: .markdownlint.json + globs: | + **/*.md + !node_modules + !**/SUMMARY.md diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml new file mode 100644 index 0000000..499089d --- /dev/null +++ b/.github/workflows/spellcheck.yml @@ -0,0 +1,29 @@ +name: Spell check + +on: + pull_request: + paths: + - '**/*.md' + - 'cspell.json' + - '.github/workflows/spellcheck.yml' + push: + branches: [master] + paths: + - '**/*.md' + - 'cspell.json' + workflow_dispatch: + +jobs: + cspell: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run cspell + uses: streetsidesoftware/cspell-action@v6 + with: + config: cspell.json + files: | + **/*.md + inline: warning + strict: false diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 0000000..ba98515 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,10 @@ +# Hosts that block bots or rate-limit aggressively. lychee will not flag +# these as broken even if they return non-200. +^https://insite\.atlassian\.net/ +^https://.+\.hubspotlinks\.com/ +^https://www\.linkedin\.com/ +^https://twitter\.com/ +^https://x\.com/ + +# Local-only references inside example snippets +^file:// diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..4e44875 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,25 @@ +{ + "default": true, + + "MD003": { "style": "atx" }, + "MD004": { "style": "asterisk" }, + "MD007": { "indent": 2 }, + "MD010": { "code_blocks": false }, + "MD026": { "punctuation": ".,;:" }, + "MD040": true, + + "MD013": false, + "MD024": { "siblings_only": true }, + "MD025": false, + "MD033": false, + "MD034": false, + "MD036": false, + "MD041": false, + "MD046": false, + "MD060": false, + + "MD001": false, + + "no-hard-tabs": true, + "no-trailing-spaces": { "br_spaces": 0 } +} diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 0000000..78282de --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,4 @@ +node_modules +.git +SUMMARY.md +**/SUMMARY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3735b2f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to the Shift iQ docs + +This repository is the source for [docs.shiftiq.com](https://docs.shiftiq.com/). Most edits land here from one of two places: the GitBook web editor (synced back to `master` automatically) and pull requests opened directly against this repo. Either way, the conventions below apply. + +## Commit messages + +Use [Conventional Commits](https://www.conventionalcommits.org/) for any commit you write yourself: + +```text +(): +``` + +* `type` is one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. +* `scope` is optional and lowercase — typically the section being edited (`topics`, `contributors`, `releases`, etc.). +* `description` is lowercase, imperative ("add", not "added"), no trailing period, ~50 chars max. + +### GitBook auto-commits + +When you publish from the GitBook web editor, GitBook generates commits with subjects like `GITBOOK-80: No subject`. **Do not leave those subjects in place when merging the back-sync branch into `master`.** + +Either: + +1. Rebase the GitBook branch locally and rewrite the subjects to follow Conventional Commits before merging, or +2. Squash the back-sync into a single Conventional Commits message that describes what changed. + +The current `master` history has 178 `GITBOOK-XX: No subject` commits. They make changelog mining impossible. Don't add to that count. + +## Page conventions + +### Frontmatter + +Every page should have YAML frontmatter with at least a `description`. GitBook uses it for search snippets and social-share previews. + +```yaml +--- +description: One sentence describing the page, ~150 chars max +--- +``` + +### Image alt text + +Every `` tag must have a non-empty `alt` attribute. GitBook inserts `` by default — fix the alt text before merging. + +```html +
Sites portal layout
+``` + +### File names + +Use lowercase kebab-case file names that match the page title (`how-to-publish-a-course.md`, not `README (3).md` or `HowToPublishACourse.md`). When the GitBook editor generates a `README (N).md` style file, rename it before merging — for example, `git mv "README (4).md" "oct-29-version-25.6-is-live.md"` and update the relevant `SUMMARY.md`. + +### SUMMARY.md + +Each space (`contributors/`, `topics/`, `developers/`, `guides/`, `releases/`, `staff/`, `starters/`, `operations/`, `embeds/`) has its own `SUMMARY.md`. When you add a new page, add it to the appropriate `SUMMARY.md` in the same PR. + +### Terminology + +The internal vocabulary is **Toolkit** (Domain / Plugin / Utility / Shell), not **Component**. The customer-facing UI calls it a **toolkit** (one word). Don't write "tool kit". + +## Reviewing + +Before requesting review: + +* [ ] Commit messages follow Conventional Commits (or, for back-syncs, the GitBook subjects have been rewritten). +* [ ] New pages have YAML `description:` frontmatter. +* [ ] New images have descriptive `alt=""` attributes. +* [ ] Renamed or moved pages have their references updated in `SUMMARY.md` and in any pages that link to them. +* [ ] The link-check CI is green. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 0000000..b9e6d58 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,80 @@ +# Contributors + +One-page onboarding for anyone editing the Shift iQ docs repo. Read this before your first PR. For commit message format, frontmatter, alt text, and naming conventions, see [CONTRIBUTING.md](CONTRIBUTING.md). + +## What this repo is + +This repository is the source for [docs.shiftiq.com](https://docs.shiftiq.com/). The build is driven by GitBook: each top-level folder is a separate GitBook **space**, and each space has its own `SUMMARY.md` that defines its navigation. + +## The spaces + +| Folder | Audience | Public? | +|---|---|---| +| `topics/` | Customers (help center) | ✅ | +| `guides/` | Customers (role-based walkthroughs) | ✅ | +| `developers/` | Integrators (API and integrations) | ✅ | +| `releases/` | Customers (changelog) | ✅ | +| `starters/` | Customers (onboarding announcements) | ✅ | +| `contributors/` | Internal staff (architecture, conventions, toolkits) | ❌ | +| `staff/` | Internal staff (private notes, job descriptions) | ❌ | +| `operations/` | Internal staff (infrastructure, ops runbooks) | ❌ | +| `embeds/` | Snippet storage for embedded content | n/a | + +If you are not sure which space a new page belongs in, the easiest test is: **"who is the reader?"** Customer-facing → `topics/`, `guides/`, or `releases/`. Internal → `contributors/` or `staff/`. + +## How GitBook sync works + +GitBook is the source of truth for *published* content, but commits flow both ways: + +1. A writer edits a page in the GitBook web editor. +2. GitBook pushes a commit to this repo's `master` branch with subject `GITBOOK-XX: No subject`. +3. A developer can also push commits directly. Conventional Commits subject lines (see [CONTRIBUTING.md](CONTRIBUTING.md)) are preferred. + +When you back-sync a GitBook branch, **rewrite the `GITBOOK-XX: No subject` commits to follow Conventional Commits before merging.** The current `master` history has 178 of them — don't add to that count. + +## Working locally + +Clone, branch, edit, push, open a PR. There is no build step to run locally — GitBook does the build on its side. But two checks are worth running before you push: + +### Link check + +The repo has a lychee workflow (`.github/workflows/link-check.yml`) that runs on every PR. To run it locally: + +```bash +docker run --rm -v "$PWD:/work" -w /work lycheeverse/lychee \ + --no-progress --base . --exclude-mail \ + --accept 200,206,429 \ + './**/*.md' +``` + +Or install the CLI: `cargo install lychee` (or `brew install lychee`). + +### Markdown lint + +GitBook tolerates a lot, but inconsistent headings show up in the rendered sidebar: + +```bash +npx markdownlint-cli '**/*.md' --ignore node_modules +``` + +## Conventions checklist + +Before opening a PR: + +* [ ] Every new page has YAML frontmatter with at least `description:`. +* [ ] Every `` tag has a non-empty `alt=""` attribute. +* [ ] New files use lowercase kebab-case names — no `README (3).md` style autogenerated names. +* [ ] Every new page is referenced from the appropriate `SUMMARY.md` in the same PR. +* [ ] Internal terminology uses **Toolkit** (Domain / Plugin / Utility / Shell) — not **Component**. +* [ ] Customer-facing copy uses **toolkit** (one word). +* [ ] Commit messages follow Conventional Commits, or back-sync GitBook commits have been rewritten. + +## Where things live + +* **Images**: each space has its own `.gitbook/assets/` folder. Reference them with relative paths. +* **OpenAPI specs**: under `developers/api-v1/` and `developers/api-v2/` — rendered by GitBook's `builtin:openapi` block. +* **Spaces' SUMMARY.md**: each top-level folder has one. The root `SUMMARY.md` is just a directory of the eight spaces. + +## When you get stuck + +Read the relevant `README.md` for that space — most have a one-line `description:` plus a short intro. If a page looks wrong, blame the `git log` and ask the original author. If a page is a stub (look for the `> **Draft**` callout or `Coming soon` page), it is a known gap waiting for a subject-matter expert. diff --git a/SUMMARY.md b/SUMMARY.md index 4439a14..3f072d4 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,3 +1,14 @@ # Table of contents -* [Page](README.md) +* [Shift iQ Documentation](README.md) + +## Spaces + +* [Topics (Help Center)](topics/README.md) +* [Guides](guides/README.md) +* [Developers](developers/README.md) +* [Contributors](contributors/README.md) +* [Releases](releases/README.md) +* [Starters](starters/README.md) +* [Operations](operations/README.md) +* [Staff](staff/README.md) diff --git a/contributors/.gitbook/assets/adding-certificatelayouts-to-achievements-01.png b/contributors/.gitbook/assets/adding-certificatelayouts-to-achievements-01.png new file mode 100644 index 0000000..d789561 Binary files /dev/null and b/contributors/.gitbook/assets/adding-certificatelayouts-to-achievements-01.png differ diff --git a/contributors/.gitbook/assets/architecture-01.png b/contributors/.gitbook/assets/architecture-01.png new file mode 100644 index 0000000..c022323 Binary files /dev/null and b/contributors/.gitbook/assets/architecture-01.png differ diff --git a/contributors/.gitbook/assets/architecture-02.png b/contributors/.gitbook/assets/architecture-02.png new file mode 100644 index 0000000..4a7fe47 Binary files /dev/null and b/contributors/.gitbook/assets/architecture-02.png differ diff --git a/contributors/.gitbook/assets/architecture-03.png b/contributors/.gitbook/assets/architecture-03.png new file mode 100644 index 0000000..4ec2dc8 Binary files /dev/null and b/contributors/.gitbook/assets/architecture-03.png differ diff --git a/contributors/.gitbook/assets/architecture-04.png b/contributors/.gitbook/assets/architecture-04.png new file mode 100644 index 0000000..e9a1d37 Binary files /dev/null and b/contributors/.gitbook/assets/architecture-04.png differ diff --git a/contributors/.gitbook/assets/architecture-05.png b/contributors/.gitbook/assets/architecture-05.png new file mode 100644 index 0000000..58aaa28 Binary files /dev/null and b/contributors/.gitbook/assets/architecture-05.png differ diff --git a/contributors/.gitbook/assets/define-custom-fields-01.png b/contributors/.gitbook/assets/define-custom-fields-01.png new file mode 100644 index 0000000..4b1110f Binary files /dev/null and b/contributors/.gitbook/assets/define-custom-fields-01.png differ diff --git a/contributors/.gitbook/assets/define-custom-fields-02.png b/contributors/.gitbook/assets/define-custom-fields-02.png new file mode 100644 index 0000000..c3db231 Binary files /dev/null and b/contributors/.gitbook/assets/define-custom-fields-02.png differ diff --git a/contributors/.gitbook/assets/define-custom-fields-03.png b/contributors/.gitbook/assets/define-custom-fields-03.png new file mode 100644 index 0000000..3abcb7c Binary files /dev/null and b/contributors/.gitbook/assets/define-custom-fields-03.png differ diff --git a/contributors/.gitbook/assets/git-branches-01.png b/contributors/.gitbook/assets/git-branches-01.png new file mode 100644 index 0000000..a96c7da Binary files /dev/null and b/contributors/.gitbook/assets/git-branches-01.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-01.png b/contributors/.gitbook/assets/git-pull-requests-01.png new file mode 100644 index 0000000..a56e8aa Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-01.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-02.png b/contributors/.gitbook/assets/git-pull-requests-02.png new file mode 100644 index 0000000..3388005 Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-02.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-03.png b/contributors/.gitbook/assets/git-pull-requests-03.png new file mode 100644 index 0000000..ecad701 Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-03.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-04.png b/contributors/.gitbook/assets/git-pull-requests-04.png new file mode 100644 index 0000000..69a53f8 Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-04.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-05.png b/contributors/.gitbook/assets/git-pull-requests-05.png new file mode 100644 index 0000000..b34d336 Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-05.png differ diff --git a/contributors/.gitbook/assets/git-pull-requests-06.png b/contributors/.gitbook/assets/git-pull-requests-06.png new file mode 100644 index 0000000..e872c39 Binary files /dev/null and b/contributors/.gitbook/assets/git-pull-requests-06.png differ diff --git a/contributors/.gitbook/assets/global-tenant-file-upload-01.png b/contributors/.gitbook/assets/global-tenant-file-upload-01.png new file mode 100644 index 0000000..e10d593 Binary files /dev/null and b/contributors/.gitbook/assets/global-tenant-file-upload-01.png differ diff --git a/contributors/.gitbook/assets/global-tenant-file-upload-02.png b/contributors/.gitbook/assets/global-tenant-file-upload-02.png new file mode 100644 index 0000000..8cec9f7 Binary files /dev/null and b/contributors/.gitbook/assets/global-tenant-file-upload-02.png differ diff --git a/contributors/.gitbook/assets/global-tenant-file-upload-03.png b/contributors/.gitbook/assets/global-tenant-file-upload-03.png new file mode 100644 index 0000000..6c11468 Binary files /dev/null and b/contributors/.gitbook/assets/global-tenant-file-upload-03.png differ diff --git a/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-01.png b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-01.png new file mode 100644 index 0000000..0636ec2 Binary files /dev/null and b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-01.png differ diff --git a/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-02.png b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-02.png new file mode 100644 index 0000000..4f24395 Binary files /dev/null and b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-02.png differ diff --git a/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-03.png b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-03.png new file mode 100644 index 0000000..c1ce073 Binary files /dev/null and b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-03.png differ diff --git a/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-04.png b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-04.png new file mode 100644 index 0000000..6c24dbf Binary files /dev/null and b/contributors/.gitbook/assets/how-to-configure-a-new-certificate-layout-04.png differ diff --git a/contributors/.gitbook/assets/introduction-01.png b/contributors/.gitbook/assets/introduction-01.png new file mode 100644 index 0000000..c915992 Binary files /dev/null and b/contributors/.gitbook/assets/introduction-01.png differ diff --git a/contributors/.gitbook/assets/introduction-02.png b/contributors/.gitbook/assets/introduction-02.png new file mode 100644 index 0000000..6158607 Binary files /dev/null and b/contributors/.gitbook/assets/introduction-02.png differ diff --git a/contributors/.gitbook/assets/introduction-03.png b/contributors/.gitbook/assets/introduction-03.png new file mode 100644 index 0000000..08c4f35 Binary files /dev/null and b/contributors/.gitbook/assets/introduction-03.png differ diff --git a/contributors/.gitbook/assets/introduction-04.png b/contributors/.gitbook/assets/introduction-04.png new file mode 100644 index 0000000..54cbe15 Binary files /dev/null and b/contributors/.gitbook/assets/introduction-04.png differ diff --git a/contributors/.gitbook/assets/introduction-05.png b/contributors/.gitbook/assets/introduction-05.png new file mode 100644 index 0000000..80a09b5 Binary files /dev/null and b/contributors/.gitbook/assets/introduction-05.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-01.png b/contributors/.gitbook/assets/obsolete-timeline-01.png new file mode 100644 index 0000000..7c16482 Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-01.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-02.png b/contributors/.gitbook/assets/obsolete-timeline-02.png new file mode 100644 index 0000000..afb8fc2 Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-02.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-03.png b/contributors/.gitbook/assets/obsolete-timeline-03.png new file mode 100644 index 0000000..3ad3836 Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-03.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-04.png b/contributors/.gitbook/assets/obsolete-timeline-04.png new file mode 100644 index 0000000..ee2980f Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-04.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-05.png b/contributors/.gitbook/assets/obsolete-timeline-05.png new file mode 100644 index 0000000..57b3ec2 Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-05.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-06.png b/contributors/.gitbook/assets/obsolete-timeline-06.png new file mode 100644 index 0000000..72436cb Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-06.png differ diff --git a/contributors/.gitbook/assets/obsolete-timeline-07.png b/contributors/.gitbook/assets/obsolete-timeline-07.png new file mode 100644 index 0000000..5de5f94 Binary files /dev/null and b/contributors/.gitbook/assets/obsolete-timeline-07.png differ diff --git a/contributors/.gitbook/assets/queries-01.png b/contributors/.gitbook/assets/queries-01.png new file mode 100644 index 0000000..d1e18e5 Binary files /dev/null and b/contributors/.gitbook/assets/queries-01.png differ diff --git a/contributors/.gitbook/assets/queries-02.png b/contributors/.gitbook/assets/queries-02.png new file mode 100644 index 0000000..c9088c7 Binary files /dev/null and b/contributors/.gitbook/assets/queries-02.png differ diff --git a/contributors/.gitbook/assets/queries-03.png b/contributors/.gitbook/assets/queries-03.png new file mode 100644 index 0000000..bfde75a Binary files /dev/null and b/contributors/.gitbook/assets/queries-03.png differ diff --git a/contributors/.gitbook/assets/queries-04.png b/contributors/.gitbook/assets/queries-04.png new file mode 100644 index 0000000..bf7f547 Binary files /dev/null and b/contributors/.gitbook/assets/queries-04.png differ diff --git a/contributors/.gitbook/assets/queries-05.png b/contributors/.gitbook/assets/queries-05.png new file mode 100644 index 0000000..a2f9d41 Binary files /dev/null and b/contributors/.gitbook/assets/queries-05.png differ diff --git a/contributors/.gitbook/assets/queries-06.png b/contributors/.gitbook/assets/queries-06.png new file mode 100644 index 0000000..e74088f Binary files /dev/null and b/contributors/.gitbook/assets/queries-06.png differ diff --git a/contributors/.gitbook/assets/sites-01.png b/contributors/.gitbook/assets/sites-01.png new file mode 100644 index 0000000..e59ee82 Binary files /dev/null and b/contributors/.gitbook/assets/sites-01.png differ diff --git a/contributors/.gitbook/assets/skillscheck-publishing-01.png b/contributors/.gitbook/assets/skillscheck-publishing-01.png new file mode 100644 index 0000000..bbcda9f Binary files /dev/null and b/contributors/.gitbook/assets/skillscheck-publishing-01.png differ diff --git a/contributors/.gitbook/assets/survey-content-font-colours-01.png b/contributors/.gitbook/assets/survey-content-font-colours-01.png new file mode 100644 index 0000000..f427c09 Binary files /dev/null and b/contributors/.gitbook/assets/survey-content-font-colours-01.png differ diff --git a/contributors/.gitbook/assets/survey-content-font-colours-02.png b/contributors/.gitbook/assets/survey-content-font-colours-02.png new file mode 100644 index 0000000..347afd7 Binary files /dev/null and b/contributors/.gitbook/assets/survey-content-font-colours-02.png differ diff --git a/contributors/.gitbook/assets/survey-content-font-colours-03.png b/contributors/.gitbook/assets/survey-content-font-colours-03.png new file mode 100644 index 0000000..79e2c12 Binary files /dev/null and b/contributors/.gitbook/assets/survey-content-font-colours-03.png differ diff --git a/contributors/SUMMARY.md b/contributors/SUMMARY.md index f20c4d3..dab698b 100644 --- a/contributors/SUMMARY.md +++ b/contributors/SUMMARY.md @@ -3,19 +3,43 @@ ## Getting Started * [Contributor Documentation](README.md) -* [Components](getting-started/components/README.md) - * [Utility Components](getting-started/components/utility-components/README.md) - * [Metadata](getting-started/components/utility-components/metadata.md) - * [Security](getting-started/components/utility-components/security/README.md) - * [Setting Up New Organizations](getting-started/components/utility-components/security/setting-up-new-organizations/README.md) - * [Organization Specific Settings (Advanced Configuration)](getting-started/components/utility-components/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md) - * [Existing Organization Customization](getting-started/components/utility-components/security/setting-up-new-organizations/existing-organization-customization.md) - * [Impersonations](getting-started/components/utility-components/security/impersonations.md) - * [Permissions](getting-started/components/utility-components/security/permissions.md) - * [Permissions (Proposed Improvement)](getting-started/components/utility-components/security/permissions-proposed-improvement.md) - * [Organization Collections](getting-started/components/utility-components/security/organization-collections.md) - * [Setup](getting-started/components/utility-components/setup/README.md) - * [Colours](getting-started/components/utility-components/setup/colours.md) + +## Toolkits + +* [Toolkits](toolkits/README.md) + * [Metadata](toolkits/metadata.md) + * [Records](toolkits/records/README.md) + * [Certificate Layouts](toolkits/records/certificate-layouts/README.md) + * [Global tenant file upload](toolkits/records/certificate-layouts/global-tenant-file-upload.md) + * [How to configure a new certificate layout](toolkits/records/certificate-layouts/how-to-configure-a-new-certificate-layout.md) + * [Infrastructure notes (developers only)](toolkits/records/certificate-layouts/infrastructure-notes-developers-only.md) + * [Adding CertificateLayouts to Achievements](toolkits/records/certificate-layouts/adding-certificatelayouts-to-achievements.md) + * [Reports](toolkits/reports/README.md) + * [Monitors](toolkits/reports/monitors.md) + * [Queries](toolkits/reports/queries.md) + * [Report types](toolkits/reports/report-types.md) + * [Security](toolkits/security/README.md) + * [Setting Up New Organizations](toolkits/security/setting-up-new-organizations/README.md) + * [Organization Specific Settings (Advanced Configuration)](toolkits/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md) + * [Existing Organization Customization](toolkits/security/setting-up-new-organizations/existing-organization-customization.md) + * [Granting admin permissions to roles](toolkits/security/setting-up-new-organizations/granting-admin-permissions-to-roles.md) + * [Granting portal or design permission to roles](toolkits/security/setting-up-new-organizations/granting-portal-or-design-permission-to-roles.md) + * [General system alerts and what they are used for](toolkits/security/setting-up-new-organizations/general-system-alerts-and-what-they-are-used-for.md) + * [Other alerts and notifications for toolkits](toolkits/security/setting-up-new-organizations/other-alerts-and-notifications-for-toolkits.md) + * [Impersonations](toolkits/security/impersonations.md) + * [Permissions](toolkits/security/permissions.md) + * [Permissions (Proposed Improvement)](toolkits/security/permissions-proposed-improvement.md) + * [Organization Collections](toolkits/security/organization-collections.md) + * [Setup](toolkits/setup/README.md) + * [Colours](toolkits/setup/colours.md) + * [Sites](toolkits/sites/README.md) + * [SkillsCheck: publishing a course or product to skillscheck.ca](toolkits/sites/skillscheck-publishing-course-product.md) + * [Standards](toolkits/standards/README.md) + * [Ideas](toolkits/standards/ideas/README.md) + * [Competency (outcome) score calculations](toolkits/standards/ideas/competency-outcome-score-calculations.md) + * [Define custom fields for standard output document headers](toolkits/standards/define-custom-fields-for-standard-output-document-headers.md) + * [Workflows](toolkits/workflows/README.md) + * [Survey content font colours](toolkits/workflows/survey-content-font-colours.md) ## Values @@ -43,11 +67,19 @@ ## Conventions * [API conventions](conventions/api-conventions.md) +* [Architecture](conventions/architecture.md) * [Database naming conventions](conventions/database-naming-conventions.md) * [Folder structure and project names](conventions/folder-structure-and-project-names.md) +* [Git branches](conventions/git-branches.md) +* [Git pull requests](conventions/git-pull-requests.md) +* [Introduction](conventions/introduction.md) +* [Migrate CRUD to CQRS+ES](conventions/migrate-crud-to-cqrs-es.md) +* [Obsolete timeline changes](conventions/obsolete-timeline-changes.md) * [README files](conventions/readme-files.md) +* [Source code](conventions/source-code.md) * [Style guide](conventions/style-guide.md) * [Task list comment tokens](conventions/task-list-comment-tokens.md) +* [Terminology](conventions/terminology.md) * [Version numbers](conventions/version-numbers.md) * [Video recommendations](conventions/video-recommendations.md) diff --git a/contributors/architecture/coming-soon.md b/contributors/architecture/coming-soon.md index 670c1b6..faed03b 100644 --- a/contributors/architecture/coming-soon.md +++ b/contributors/architecture/coming-soon.md @@ -1,2 +1,14 @@ -# Coming soon! +--- +description: Placeholder — architecture documentation is in progress +--- +# Coming soon + +The Architecture section is not yet populated. Planned content includes: + +* High-level system map showing how the InSite and Shift apps relate. +* Modular monolith boundaries and the bounded contexts each toolkit owns. +* CQRS+ES service bus topology and message flow. +* Front-end composition model (shells, lobbies, portals). + +If you need any of this in the meantime, ask in the team channel and we will prioritize the relevant page. diff --git a/contributors/conventions/architecture.md b/contributors/conventions/architecture.md new file mode 100644 index 0000000..872e2e9 --- /dev/null +++ b/contributors/conventions/architecture.md @@ -0,0 +1,109 @@ +--- +description: >- + How InSite source code is organized into the God, Shift iQ, and General + systems, and the future-state architecture we are working toward +--- + +# Architecture + +## Overview + +Source code for the software developed by InSite can be organized into three (3) broad systems: + +
Overview diagram showing InSite source code split into three systems: God (green), Shift iQ (yellow), and General (grey)
+ +**Shift iQ** is a multitenant enterprise software system, and its source code depends heavily upon **general-purpose** source code that is written and maintained by InSite developers. General code is not specific to any part of Shift iQ, and therefore has no dependencies on Shift iQ code. + +Octopus is the name of the CI/CD automation system used by InSite, and it has root-level access to every instance of the Shift iQ system. For this reason, it useful to think of source code here as operating in **god-mode**, because it can modify any and all aspects of any and all Shift iQ partitions. Typically, source code in Octopus is developed in PowerShell scripts, but Octopus supports other languages also. Outside PowerShell scripts in Octopus, source code that operates in god-mode includes the Polaris web application, because it operates outside Shift iQ and has dependencies on the Shift iQ API. In addition, we have started to implement source code for platform-wide maintenance purposes (e.g., [DEV-9308](https://insite.atlassian.net/browse/DEV-9308)). + +For the purposes of this documentation (at least initially), these conventions are used: + +* "God-mode" is abbreviated "God" and is color-coded green. +* "Shift iQ" is abbreviated "Shift" and is color-coded yellow. +* "General-purpose" is abbreviated "General" and is color-coded grey. + +## System Dependencies + +By design, source code in the **God** system (written and maintained by InSite developers) is tightly coupled to the **Shift** system. The purpose of God code is to implement functionality that spans all instances of the Shift platform. Typically, this functionality relates to administrative and infrastructure needs, but it can relate to user-facing functionality also. + +The largest amount of source code is in the Shift system, and it is tightly coupled to code in the General system. + +It is important to understand (and strictly enforce) both these dependencies. + +| **God** | **Shift iQ** | **General** | +| --- | --- | --- | +| **Instances:** One instance of this software is deployed to Development, Sandbox, and Production environments. This instance is granted access to all Shift partitions. | **Instances:** Multiple instances of this software are deployed to Development, Sandbox, and Production environments. Each instance is referred to as a "partition" (or "tenant"). | **Instances:** One instance of this software is deployed to Development, Sandbox, and Production environments. This instance is shared by all Shift partitions. | +| **Dependencies:** Shift code and General code must never have any upstream reference to God code. In other words, Shift partitions do not know God system exist, and therefore the Shift system cannot have any knowledge of (or dependency on) source code implemented in the God system. | **Dependencies:** An instance of Shift system must never have any upstream, downstream, or lateral dependency on any other instance. In other words, a partition does not know that any other partition exists, and therefore cannot have any knowledge of (or dependency on) another partition. This guarantees each partition is 100% isolated from all other partitions. | **Dependencies:** General code must never have any upstream reference to Shift code. In other words, General code does not know that Shift exists, and therefore cannot have any knowledge of (or dependency on) any part of the Shift system - including its API, user interface, database schema, and so on. | +| **Confidentiality:** For security reasons, God code must be managed in private repositories only. | **Confidentiality:** Most Shift code is managed in private repositories, although some public access might be granted. For example, customers might be granted access to API contract class libraries. | **Confidentiality:** In principle, General code should be available in public repositories as open source, and should be useful to developers implementing their own systems for their own customers. | + +## Project Dependencies + +You can see the system dependencies more clearly in the following diagram, which shows the dependencies between all projects in the [InSite Code repository](https://github.com/InSite/Code). The color-coding here is especially helpful. (Custom projects are colored purple.) + +> Note: Test projects are omitted for clarity, because they (potentially) reference everything everywhere. Redundant dependency arrows are omitted for simplicity. For example, if A depends on both B and C, and B depends on C, then an arrow is shown from A to B, and from B to C. The arrow from A to C is implied, and therefore not necessary to include in the diagram. + +
Current-state project dependency graph for the InSite Code repository, colour-coded by system (God, Shift, General, Custom)
+ +## Constructive Criticism + +Historically, InSite has not had a cohesive, focused design/implementation strategy for General source code or God source code. Therefore, code for both systems exists in different projects with different names and different namespaces, each of which has evolved at a different pace, depending on the needs driving it, and depending on the version of .NET that the code is written to target. + +This problem is clearly observed in the project dependency diagram above. For example: + +* General code appears in projects (and namespaces) with names that start "InSite.", "Shift.", "Common.", "Engine.", and "Atom.". +* God code appears in projects with names that start "Shift." and "Polaris.". + +Basically, the approach to General code and God code has not been carefully planned, and it is important to takes steps to correct this, so that we have a more disciplined approach going forward. This is important for many reasons, including overall system security, stability, reliability, performance, operational maintenance, and developer sanity! + +## Overview Revisited (Future State) + +I propose a "reset" in our thinking about General source code and God source code. No immediate steps are necessary here, but we can formalize a design of the desired "future state". In other words, we should have a clear picture of the overall system software architecture that we are working toward. + +To help clear and reset our thinking about General code and God code, the Overview diagram can be reimagined this way, with some added context for further clarity: + +
Proposed future-state overview with God renamed to Archon (Arc) and General renamed to Tekton (Tek), each system split into API, UI, and Terminal components
+ +### God = Archon + +Given the responsibility of the code in this system, I suggest the name Archon (abbreviated **Arc**). [Archon](https://en.wikipedia.org/wiki/Archon) is a Greek word that means "ruler". + +This name is short and descriptive, and helps ensure a clear distinction between Shift application features and super-user, god-mode, platform-wide maintenance and administration features. + +In the short term, this code would include platform-wide maintenance operations related to IIS and GoDaddy, as well as Polaris.UI (Site Builder) for website content management and hosting. In the future, this can also include centralization of platform-wide configuration settings and password management for platform administrators with user accounts that span multiple partitions. + +### General = Tekton + +Given the responsibility of the code in this system, I suggest the name Tekton (abbreviated **Tek**). [Tekton](https://en.wikipedia.org/wiki/Tekt%C5%8Dn) is a Greek word that means "toolmaker" or "craftsman". + +This name is short and descriptive, and it helps ensure a clear distinction between Shift application features (per-partition) and reusable general-purpose features (platform-wide). Also, it is separate from all names previously given to General code, which helps reset our thinking about exactly what source code does (or does not) belong here. + +### API, UI, and Terminal + +Notice I propose an API, and a UI, and a Terminal component in all 3 systems. Here is my rationale for this: + +* Many experienced software architects recommend console-first as an application development best-practice, and I am inclined to agree this is an excellent idea. Some of the best and most successful software systems in the world were initially designed and implemented as terminal (console) applications. GUIs and APIs were implemented afterward. (Git is one such example.) + +Historically, we have taken a UI-first approach to our software development work. This has led to an imperfect architecture, with a lot of source code in layers where it does not belong (e.g., persistence logic in the presentation layer), and this makes the system more complex and more difficult to test. + +In an ideal, perfect-world, future state, all functions in the UI should be available also in the API and in the console - which ensures a simpler, cleaner, and more testable architecture. Therefore, I propose a Terminal console app in all 3 core InSite systems. + +## Project Dependencies Revisited (Future State) + +To understand more clearly how the current state evolves to the future state (eventually!), this diagram shows the proposed dependencies between projects in the [InSite Code repository](https://github.com/InSite/Code), with small boxes to show how existing projects move into the future state. + +For example, in this future state we will see: + +* The existing Polaris.UI project is renamed to Site Builder. The Around project becomes a component within Site Builder, where it belongs. If the BCPVPA and CMDS website projects still exist, then they are components within the Site Builder code base also. +* Any and all "custom" code is implemented as Plugin source code. This includes integrations to third-party systems, and extensions to Shift functionality implemented for specific organizations. Such code is permitted to have dependencies on Shift source code, but Shift code cannot have any dependencies on Plugin code. (Note: A class in the Shift code can depend on an interface to an external system, for example, but the implementation of that interface would be required to exist in Plugin code.) +* God code (i.e., the Archon system) provides platform-wide tools for InSite administrators and developers. For instance, it might perform data-integrity checks on all Shift partitions, propagate password changes for user accounts, and so on. (It is useful to note that Octopus could be configured to perform all such tasks, but in some cases these tasks will be easier to implement and maintain with our own source code.) +* .NET Framework code will remain for a long time. When there is opportunity, such code can be ported to .NET Standard libraries, where it can be referenced by both .NET Core and .NET Framework projects. + +
Proposed future-state project dependency graph showing where existing projects move under Archon, Shift, Tekton, and Plugin
+ +### Clean Architecture + +The Clean Architecture pattern still has a role within the architecture of the system. Dependencies between classes in the UI, API, Service, and Contract libraries should be organized with Clean Architecture principles in mind. It is not always possible to follow these principles in a modular monolith, but when it is possible to do so, it is a good idea. + +
Clean Architecture dependency rule diagram showing inward-only dependencies between UI, API, Service, and Contract layers
+ +(More documentation is coming!) diff --git a/contributors/conventions/git-branches.md b/contributors/conventions/git-branches.md new file mode 100644 index 0000000..1badc3e --- /dev/null +++ b/contributors/conventions/git-branches.md @@ -0,0 +1,182 @@ +--- +description: >- + The purpose of each branch in the InSite Code repository, and the naming + conventions for each branch +--- + +# Git branches + +This article describes the purpose for each branch in the InSite Code repository, and the naming conventions for each branch. + +
Branch model diagram showing master, hotfix, develop, and release branches with their parent-child relationships
+ +## master + +The **master** branch contains the code running in the Production and Sandbox environments. + +## hotfix + +The **hotfix** branch is used to quickly patch Production releases. It is based on the **master** branch. + +Any and all merges into the **master** branch require approval from at least two InSite developers. In other words, no individual developer is able to commit changes to the **master** branch without another developer's review and approval of the commit(s) in a Pull Request. + +Therefore, all hotfixes to Production are implemented in the **hotfix** branch. + +When a hotfix is complete, it is merged into both **master** and **develop** (or the upcoming **release** branch), and **master** is tagged with an updated version number. + +### fix + +Each new fix may reside in its own branch. (Fix branches are optional). + +All **fix** branches use the **hotfix** branch as their parent branch. + +A **fix** branch is typically a local branch only. If it requires collaboration between multiple developers, or if you want a backup on GitHub, then you can commit such branches to the remote repository. + +The name for a **fix** branch should follow this convention: + +* `fix/developer/issue` + +... where "developer" is your first name (lower case) and "issue" is a Jira issue number or a Sentry issue number. + +For example: + +* `fix/daniel/dev-2942` +* `fix/daniel/insite-22` + +## develop + +The **develop** branch contains the code running in the Development environment. This is the "work-in-progress" for the next release. + +### feature + +Each new feature may reside in its own branch. (Feature branches are optional). + +All **feature** branches use the **develop** branch as their parent branch. + +A **feature** branch is typically a local branch only. If it requires collaboration between multiple developers, or if you want a backup on GitHub, then you can commit such branches to the remote repository. + +> Note: **feature** branches never interact directly with **hotfix** or **master**. + +The name for a **feature** branch should follow this convention: + +* `feature/developer/issue` + +... where "developer" is your first name (lower case) and "issue" is a Jira issue number or a Sentry issue number. + +For example: + +* `feature/adam/dev-1586` +* `feature/adam/dev-2286` +* `feature/oleg/dev-2704` + +### release + +When the **develop** branch has acquired enough features for a release (or a predetermined release date is approaching), you fork a **release** branch from the **develop** branch, tagged with the version number. + +Creating this branch starts the next release cycle, so no new features are added after this point. Only bug fixes, documentation generation, and other release-oriented tasks are committed to a **release** branch. + +When the **release** branch is ready for release to Production, the **release** branch is merged into **master** and tagged with the version number. In addition, of course, it is merged back into develop, which may have progressed since the release was initiated. + +Using a dedicated branch to prepare releases makes it possible for one developer to polish the current release while another developer works on features for the next release. Also, this approach helps to clearly define development phases. For example, it is easy to say, "This week we are preparing for version 22.5," and see this in the structure of the repository. + +The name for a **release** branch should follow this convention: + +* `release/version` + +... where "version" is the version number. + +For example: + +* `release/v22.3` +* `release/v22.4` +* `release/v22.5` + +## Workflow examples + +The [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) describes the process that we follow for branches in this repository. + +### Process for feature development + +1. Create a local feature branch + * `git checkout develop` + * `git checkout -b feature/alice/dev-1234` +2. Code changes are completed on the local feature branch. +3. Merge local feature to develop branch. + * `git checkout develop` + * `git merge feature/alice/dev-1234` + * `git push` +4. Delete local feature branch. + * `git branch -d feature/alice/dev-1234` + +### Process for unstable release (development work in progress) + +1. `git checkout develop` +2. `git pull` +3. Build and deploy to the Development environment. + +### Process for stable pre-release + +1. Create a new release branch + * `git checkout develop` + * `git checkout -b release/v22.1` + * `git merge develop` +2. Build and deploy to the Development and Sandbox environments. + +### Process for final stable release + +1. Create a Pull Request to merge release/v22.1 into master. +2. Review and approve Pull Request. +3. Merge commits into master. +4. Create a Release (i.e. tag the master branch with the version number). +5. `git checkout master` +6. Build and deploy to the Sandbox and Production environments. +7. Recreate the hotfix branch from master. + * `git branch -d hotfix` + * `git push origin --delete hotfix` + * `git branch hotfix` +8. Delete the release branch. + * `git branch -d release/v22.1` + * `git push origin --delete release/v21.1` + +### Process for hotfix development + +1. Create a local fix branch. + * `git checkout hotfix` + * `git checkout -b fix/alice/dev-5678` +2. Code changes are completed on the local fix branch. +3. Push local fix branch to origin + * `git push -u origin fix/alice/dev-5678` +4. Create a pull request for code review and approval. +5. After the pull request is approved and your fix branch is merged into the hotfix branch, delete your fix branch and merge the hotfix branch into the develop branch. + * `git branch -d fix/alice/dev-5678` + * `git checkout hotfix` + * `git pull origin hotfix` + * `git checkout develop` + * `git pull origin develop` + * `git checkout -b merge-hotfix-into-develop` + * `git merge hotfix` + * (fix merge conflicts, if any) + * `git push origin merge-hotfix-into-develop` +6. Create a Pull Request to merge the merge-hotfix-into-develop branch. + +## Pre-release week + +The week leading up to the release of a new version to Production is "Pre-Release Week", and this has some characteristics outside our normal workflow. + +1. Code in the **develop** branch is not deployed to any environment. +2. Code in the **release** branch is deployed to the Development environment and to the Sandbox environment. +3. When the new version is ready to deploy to Production: + 1. The **release** branch is merged into the **master** branch and the **hotfix** branch. + 2. The normal build and deployment workflow resumes: the **develop** branch is deployed to the Development environment; the **hotfix** branch is deployed to **Sandbox** and then to **Production**. + +**Please Note:** + +This means features and fixes in the develop branch are not visible in any environment during pre-release week, and cannot be made available to users (outside our Local environments). + +If there is a request from someone to see some new feature or fix from the **develop** branch then the requester needs to wait until after pre-release week, when the **develop** branch is deployed to the Development environment. + +During pre-release week only: + +* Code changes for issues assigned to "**Fixes (Development)**" are implemented in the **develop** branch. +* Code changes for issues assigned to "**Fixes (Production)**" are implemented in the **release** branch. +* Therefore, any fixes needed for the pending release should be assigned to "**Fixes (Production)**". diff --git a/contributors/conventions/git-pull-requests.md b/contributors/conventions/git-pull-requests.md new file mode 100644 index 0000000..4346143 --- /dev/null +++ b/contributors/conventions/git-pull-requests.md @@ -0,0 +1,102 @@ +--- +description: >- + How to implement, submit, and review code changes through Git pull requests + and the GitHub review process +--- + +# Git pull requests + +The general approach to managing branches in GitHub is described here: + +* [Managing Branches in GitHub](git-branches.md) + +More details about pull requests (**PR**) and the review process are described here: + +* [https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) + +Details about how the Github actions automatically build and test are found here: + +* Rapid Test Feature Branch +* [https://insite.atlassian.net/wiki/spaces/PD/pages/110133249/Rapid+Test+Feature+Branch#Github-Failure-Recovery](https://insite.atlassian.net/wiki/spaces/PD/pages/110133249/Rapid+Test+Feature+Branch#Github-Failure-Recovery) + +### Steps to implement and submit code changes for resolving a Jira issue (as a **developer**) + +1. Create a new local feature branch. For example: **feature/alice/dev-1234** +2. Implement the requested changes to the code in the local feature branch. +3. Commit changes to the local feature branch and push the commit to GitHub. +4. Create a new Pull Request (PR) to the base branch:\ + \- Select the **hotfix** branch for hotfixes.\ + \- Select the **develop** branch for the current development tasks. +5. If you want someone specific to review your change then assign them as reviewer(s) in your Pull Request. +6. The PR description should contain the list of links to Jira issues to which this PR is related to. +7. The reviewer may post a comment requesting some improvement to your code before approving the Pull Request. In this case, implement the improvement in your local feature branch (e.g. **feature/alice/dev-1234**), commit the change, and push the commit again to GitHub. +8. In some cases you might prefer to resolve multiple Jira issues in one feature branch and then submit one Pull Request for all of them together. Ideally, each Pull Request should be relatively small, so the review does not take too much effort, therefore consider this option carefully. +9. Do not push commits for the new issues into the PR where the review process was already started +10. f it is needed to close PR where was started the review then please specify the reason for this + +### Steps to approve a pull request (as a **reviewer**) + +1. A Pull Request must be approved by at least one person (who is not the developer) before it can be merged. Note the review process can be started by multiple people. +2. Sign in to GitHub, select the repository, and click the **Pull requests** tab. +3. Select the Pull Request that you are ready to review. +4. Click the **Files changed** tab. +5. If the code looks good, then click **Review changes** and approve the changes. +6. If the code needs to be improved, then post a comment on the lines that need to be improved, and then request changes from **Review changes** +7. Wait for the developer to make the requested improvements or to explain the reasons for leaving the code as it is. +8. Review changes/explanations, and if something still needs improvement/clarification then continue the discussion. Otherwise, if everything is done, then approve changes. +9. After the **Pull Request** is approved by all reviewers then the developer who has merge permissions merges the code. + +### Steps for the reviewer to make changes he/she decided to implement while were reviewing the code + +1. During the PR review, the reviewer found some issues not related to the PR that he/she wants to fix/implement +2. In this case, create either a child task for the current task or a new task +3. Make sure the new task and the original task are linked either as a child issue or via “Link Issue” button: + +
Jira issue screen showing the Link Issue button used to relate a child task back to the original task
+4. Push your changes and create a new PR for this new task + +### Jira and PR requests + +Once we are ready to perform the pull request on our code: + +1. <…> + +After our code is reviewed and completed: + +1. <…> + +## Example + +### Developer Workflow + +Here is the git command to create a check out a new local feature branch: + +* `git checkout -b feature/aleksey/dev-1234` + +After I have implemented my changes, here are the git command to commit and push my change to GitHub: + +* `git add *` +* `git commit -m DEV-1234` +* `git push origin feature/aleksey/dev-1234` + +After my changes are pushed, then I click this button to create a new PR: + +
GitHub Compare & pull request button shown after pushing a new feature branch
+ +Then select a base branch and click **Create pull request**: + +
GitHub Open a pull request screen showing the base-branch selector and the Create pull request button
+ +### Reviewer Workflow + +Select the required PR + +
GitHub Pull requests tab listing open PRs for the reviewer to select
+ +Comment on the line: + +
GitHub Files changed tab showing an inline review comment attached to a specific line of code
+ +Request changes: + +
GitHub Review changes dialog with Request changes selected to ask the developer for revisions
diff --git a/contributors/conventions/introduction.md b/contributors/conventions/introduction.md new file mode 100644 index 0000000..c5a21e5 --- /dev/null +++ b/contributors/conventions/introduction.md @@ -0,0 +1,377 @@ +--- +description: >- + Naming and URL conventions for primary and secondary API endpoints, queries, + commands, and the general-purpose React UI endpoints +--- + +# Introduction + +## API Endpoints + +Primary API endpoints provide access to basic core functions that store and search data. + +Secondary API endpoints provide all other functionality. + +The same general approach and naming patterns should apply to all API endpoints, primary and secondary. + +### Collection Names + +An API endpoint represents a collection of items. It has a URL that follows this pattern: + +* api/component/collection + +**Component** is a singular noun that identifies a logical module within the platform, and **Collection** is a plural noun that identifies a subset of data within the module. For example: + +* api/contact/groups + +If the items in a collection represent relationships, and if the relationship type is not assigned its own discrete noun, then the collection name is a hyphenation of the names of the items in the relationship. + +For example, suppose we have a many-to-many relationship between groups and users, where each group can contain many users, and each user can join many groups. + +* If the relationship is named "Membership" in the data model, then the expected collection name is "memberships". +* Otherwise, if the relationship has no singular-form noun in the data model (i.e., its database table name is GroupUser) then the collection name in the corresponding API endpoint is "users-groups" or "groups-users". + +### Collection Operations + +The following table defines basic operations for a typical collection. + +| HTTP Method | Type | Purpose | Verb | URL Stem (example) | +| ----------- | ------- | ---------------------------------- | ------- | ------------------ | +| GET | Query | Get a collection of items | Collect | api/contact/groups | +| POST | Command | Create a new item in a collection | Create | api/contact/groups | + +The following table defines additional operations for a typical collection. + +| HTTP Method | Type | Purpose | Verb | URL Stem (example) | +| ----------- | ------- | -------------------------------------- | ------ | ------------------------- | +| GET | Query | Find matching items in a collection | Search | api/contact/groups/search | +| GET | Query | Count the items in a collection | Count | api/contact/groups/count | +| POST | Command | Download a collection | Export | api/contact/groups/export | +| POST | Command | Upload a collection | Import | api/contact/groups/import | +| POST | Command | Delete a list of items in a collection | Purge | api/contact/groups/purge | + +### Item Names + +An API endpoint that represents a single item in a collection has a URL that follows this pattern: + +* api/component/collection/id + +**Component** is a singular noun, and **Collection** is a plural noun, and **ID** uniquely identifies a specific item in the collection. For example: + +* api/contact/groups/123 + +Typically, the unique identifier for an item is a GUID value; an integer value is used here for the sake of brevity. + +### Item Operations + +The following table defines basic operations for a typical item. + +| HTTP Method | Type | Purpose | Verb | URL Stem (example) | +| ----------- | ------- | -------------------------------- | -------- | ---------------------- | +| GET | Query | Get an item from a collection | Retrieve | api/contact/groups/123 | +| PUT | Command | Update an item in a collection | Modify | api/contact/groups/123 | +| DELETE | Command | Delete an item from a collection | Delete | api/contact/groups/123 | + +The following table defines additional operations for a typical item. + +| HTTP Method | Type | Purpose | Verb | URL Stem (example) | +| ----------- | ----- | -------------------------------------------------- | ------ | ---------------------- | +| HEAD | Query | Check for the existence of an item in a collection | Assert | api/contact/groups/123 | + +### Item Composites + +If an item represents a composite object, then parts of the object are located with URLs that look like this: + +* api/contact/groups/123/addresses +* api/contact/groups/123/memberships + +## Naming Conventions + +Whenever possible, a class that implements a command or a query follows these naming conventions. + +Specifically, the readability of code is improved when we apply the same meaning to Type and Verb in command names and query names. For example, a class named CreateWidget must be a command (not a query) that creates a new item in a collection of widgets. + +This can be summarized in the following tables. + +### Queries + +A query is implemented in C# and in JavaScript as a class. The class name starts with one of these verbs: + +| Verb | Purpose | Method | Input | +| -------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- | +| Assert | Check for the existence of one specific item in a collection using its primary key (return a true/false Boolean) | HEAD | Uri | +| Collect | Find matching items in a collection (return a list of models, suitable for outline and edit forms in a UI) | GET or POST | Uri or Body | +| Count | Count the list of matching items in a collection (return an integer) | GET or POST | Uri or Body | +| Retrieve | Find one specific item in a collection using its primary key (return a model) | GET | Uri | +| Search | Find matching items in a collection (return a list of lightweight models intended for search results, combo boxes, lookups, etc.) | GET or POST | Uri or Body | + +This convention helps improve readability because the purpose of a query is clearly documented by its name. + +A C# query class should implement the `IQuery` interface. This ensures the data type of the result is explicitly defined at compile-time. + +Optionally, the query class name may be prefixed with the word "Query". + +For example, these query class names follow the convention: + +* AssertSurvey : Query\ +* CollectVehicles : Query\> +* CountSurveys : Query\ +* RetrieveLogbook : Query\ +* SearchGroups : Query\> +* QueryCountAssessmentAttempts : Query\ + +These query class names do not follow the convention: + +* GetWidget +* ListAnimals + +#### Query Results + +A query result can be any C# data type, including both value types and reference types. Therefore, a consistent naming convention for query result classes may be difficult to maintain. In general, the following guidelines are optional. + +| Query | Result | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Assert | Boolean | +| Collect | A class that represents the result for a Collect query should have the suffix "Model". This helps to express the purpose of the result: i.e., a heavyweight response containing a collection of fully-hydrated data transfer object models. | +| Count | Integer | +| Retrieve | A class that represents the result for a Retrieve query should have the suffix "Model". This helps to express the purpose of the result: i.e., a heavyweight response containing a single fully-hydrated data transfer object model. | +| Search | A class that represents the result for a Search query should have the suffix "SearchResult". This makes its purpose clear. For example: GroupSearchResult. | + +### Commands + +A command is implemented in C# and in JavaScript as a class. The class name must be a verb-noun phrase. Any verb is acceptable, excluding the 6 verbs listed above, which are reserved for queries. + +If the purpose of a command is listed in the table below, then the corresponding verb is preferred. For example, the preferred name for a command to create a new group is `CreateGroup`. + +| Verb | Purpose | Method | Input | +| ------ | ----------------------------------------------- | ------ | ----- | +| Create | Create a single new item in a collection | POST | Body | +| Delete | Delete a single existing item from a collection | DELETE | Uri | +| Export | Download multiple items from a collection | POST | Body | +| Import | Upload multiple items to collection | POST | Body | +| Modify | Update a single existing item in a collection | PUT | Body | +| Purge | Delete multiple items from a collection | POST | Body | + +"Add" and "Remove" have the same basic meaning as "Create" and "Delete". For the sake of consistency, if the verbs Add and Remove are used, then it should be for the purpose of connecting and disconnecting existing items (or adding and removing objects within an aggregate). + +For example, AddUserToGroup is the name of a command to connect a user to a group. The verb Add in this scenario helps to express the purpose of this command: no new user is created, and no new group is created. Similarly, RemoveUserFromGroup is a command to disconnect a user from a group; the user is not deleted, and the group is not deleted. + +## URL Conventions for React UI + +In addition to the naming conventions above, there are two general-purpose API endpoints, designed specifically for the purpose of client code in a React user interface: + +* api/react/queries +* api/react/commands + +The React UI can use the queries endpoint to run any query, and it can use the commands endpoint to execute any command. + +### Using api/react/queries + +This general-purpose endpoint is designed to handle any query, where the query is implemented as a class that derives from `Query`. It correctly handles variations on the query name. For example, all of these URLs run the same query and return the same result: + +* api/react/queries?q=AssertAreYouAlive +* api/react/queries?q=assertAreYouAlive +* api/react/queries?q=assert-are-you-alive +* api/react/queries?q=assert\_are\_you\_alive +* api/react/queries?q=QueryAssertAreYouAlive +* api/react/queries?q=query-assert-are-you-alive +* api/react/queries?q=query\_assert\_are\_you\_alive + +When the UI needs a new query from the API, the procedure to implement a new query is three simple steps: + +1. Define a query with a strongly typed return value. +2. Implement a function to execute the query. +3. Register the function. + +Here is an example: + +#### Step 1. Define a query class and a result class + +For example, these two classes might be written in a Contract library. + +```csharp +public class SearchDistinctBirthdateYears : Query +{ + public int? SinceYear { get; set; } + public int? BeforeYear { get; set; } +} + +public class DistinctBirthdateYear +{ + public int Year { get; set; } + public int Count { get; set; } +} +``` + +#### Step 2. Implement a function to execute the query + +For example, this function might be added to a Search class in a Service library. + +```csharp +public DistinctBirthdateYear[] Execute(SearchDistinctBirthdateYears query) +{ + using var db = CreateDbContext(); + + return db.Persons + .AsNoTracking() + .Where(x => x.Birthdate.HasValue) + .AsQueryable(); + + if (query.SinceYear.HasValue) + people = people.Where(x => query.SinceYear <= x.Birthdate!.Value.Year); + + if (query.BeforeYear.HasValue) + people = people.Where(x => x.Birthdate!.Value.Year < query.BeforeYear); + + return people + .GroupBy(x => x.Birthdate!.Value.Year) + .Select(x => new DistinctBirthdateYear + { + Year = x.Key, + Count = x.Count() + }) + .ToArray(); +} +``` + +#### Step 3. Register the function + +For example, this line of code might be added to the Search class constructor from Step 2. + +```csharp +RegisterQuery(q + => Execute((SearchDistinctBirthdateYears)q)); +``` + +> **Historical Note**: InSite code has always included the concept of a Query class, but we have used the term "Filter" instead of "Query" for this purpose. The term "Query" is more accurate, and more consistent with common conventions in CQRS+ES implementations. +> +> Essentially, the properties of a query define the criteria to apply to the data source. After the result set for a query is determined (e.g., the rows in a table that match the criteria), the term "Filter" is used to specify a more precise subset of rows and columns to be taken from the result set. Pagination, for example, is one attribute of a Filter. +> +> In other words, a Filter is not a Query. Instead, a Filter is a property of a Query. It will take some time for us to adjust to this change in terminology. + +### Securing api/react/queries + +Permissions are defined as security settings in `appsettings.json` (In future, permissions may be stored and managed in the database, but this is a simple interim solution.) + +Each permission is an object with four properties: + +* **Type**: This is always "Http" for API access permissions. +* **Access**: This is a comma-separated list of HTTP Methods (i.e., Head, Get, Put, Post, Delete). +* **Resources**: This is an array of resource names. +* **Roles**: This is an array of role names. + +The resource name for a query is derived from the full name of the C# class that implements it. For example, suppose we have a query class in the namespace "Shift.Service.Billing" named "SearchInvoices"; the name of the resource for this query is "shift/service/billing/search-invoices". Here is a permission that allows the Tester role to run this query (and only this query): + +```json +{ + "Type": "Http", + "Access": "Post", + "Resources": [ "shift/service/billing/search-invoices" ], + "Roles": [ "Tester" ] +} +``` + +Here is a permission that allows the Accountant role to run all queries in the Billing namespace: + +```json +{ + "Type": "Http", + "Access": "Post", + "Resources": [ "shift/service/billing" ], + "Roles": [ "Accountant" ] +} +``` + +Resource names are calculated from query names at run-time (using reflection), so there is no requirement to register or define resource names for queries in any part of the system. The API includes this method for our own internval developer use, so we can see the full list of available resource names, based on the queries implemented in the code: `GET api/debug/resources` + +#### Resource Identifiers and Role Identifiers + +API access permissions defined in appsettings.json use resource names and role names (not identifiers) so they are easy to read and understand. At run-time, the system generates a v5 UUID for each resource name and each role name, and it uses this UUID value internally to identify each resource and role. + +> Note: Version 5 UUIDs are deterministic. This means the v5 UUID calculated for the role name "Tester" is always the same. + +### Using api/react/commands + +This general-purpose endpoint is designed to handle any Timeline command, where the command is implemented as a class that derives from `Command`. It correctly handles variations on the command name. For example, all of these URLs execute the same command: + +* api/react/commands?c=CreateGroup +* api/react/commands?c=createGroup +* api/react/commands?c=create-group +* api/react/commands?c=create\_group + +When the UI needs a new query from the API, the procedure to implement a new command is the same procedure that we follow to implement any new command that follows the CQRS+ES pattern. + +## Monitoring and Measuring API Usage + +This is NOT yet implemented, but is it very important to do so. I propose the following requirements for our implementation: + +* For every API key issued, monitor the number of incoming API requests, the size of each request, and the size of each response. If possible, monitor the execution time for each request. +* Include `X-Request-Count` in every API response header, so clients are able to monitor their usage. +* Use the request size, response size, and (if possible) execution time to calculate the Cost for each request. +* Include `X-Request-Cost` in every API response header, so clients are able to monitor their usage. +* Determine a reasonable quota (i.e., rate limit), in terms of Request Count and Request Cost for API keys. +* Determine an algorithm for automatically replenishing the quota for an API key. +* Include `X-Request-Quota-Remaining` in every API response header, so clients can plan and measure their API usage. +* When an API key exceeds its quota, the API must respond with `403 Forbidden (Quota Exceeded)`. + +## Getting Started with the Shift API + +Here are the steps to confirm the Shift API is working in your local environment. + +Step 1. Create a secret key in the Shift database. + +```sql +USE E01_Local_Shift; + +-- Get the UUID for a specific organization. +DECLARE @organizationCode VARCHAR(10) = 'demo'; +DECLARE @organizationId UNIQUEIDENTIFIER = (SELECT OrganizationIdentifier FROM accounts.QOrganization WHERE OrganizationCode = @organizationCode); + +-- Get the UUID for a specific person. +DECLARE @userEmail VARCHAR(254) = 'daniel@shiftiq.com'; +DECLARE @userId UNIQUEIDENTIFIER = (SELECT UserIdentifier FROM identities.QUser WHERE Email = @userEmail); +DECLARE @personId UNIQUEIDENTIFIER = (SELECT PersonIdentifier FROM contacts.QPerson WHERE UserIdentifier = @userId AND OrganizationIdentifier = @organizationId); + +-- To simplify testing, delete all existing secrets, and insert one specific secret. Force it to expiry one hour in the future. +TRUNCATE TABLE contacts.TPersonSecret; +INSERT INTO contacts.TPersonSecret +( PersonIdentifier, SecretIdentifier, SecretType, SecretName, SecretLifetimeLimit, SecretValue, SecretExpiry ) +VALUES +( @personId, NEWID(), 'Token', 'Authentication', 30, 'Secret key for ' + @userEmail + ' to access ' + @organizationCode, DATEADD( HOUR, 1, GETUTCDATE() ) ); + +-- Confirm the secret exists. +SELECT * FROM contacts.TPersonSecret; +``` + +Step 2. Start the API. + +
Introduction 01
+ +Step 3. Start Insomnia and edit the Base Environment settings. Confirm your host is correct. + +
Introduction 02
+ +Step 4. Send the request named "Get API status" (`api/status`) to confirm the API is running. This is a health-check endpoint, and it does not require authentication or authorization. + +Step 5. Click the Body tab for the request named "Generate API token" (`api/token`). Confirm your secret is correct. + +
Introduction 03
+ +Step 6. Send the `api/token` request. Copy and paste the response (an encoded JWT) to your Base Environment settings. + +
Introduction 04
+ +Step 7. Use the request named "Test authorization header" (`api/debug/token`) to confirm the API correctly decodes your Bearer authorization token. + +
Introduction 05
+ +### Next Steps + +These endpoints are available to test and explore the API: + +* `api/debug/paths` - List all the available endpoints. This is determined using reflection on the literal constants by Endpoints in the Contract library. +* `api/debug/resources` - List all resources for which permissions are specified. These are determined by the Permissions section in appsettings.json. +* `api/debug/permissions` - List all permissions granted. These are determined by the Permissions section in appsettings.json. + + + diff --git a/contributors/conventions/migrate-crud-to-cqrs-es.md b/contributors/conventions/migrate-crud-to-cqrs-es.md new file mode 100644 index 0000000..24011fa --- /dev/null +++ b/contributors/conventions/migrate-crud-to-cqrs-es.md @@ -0,0 +1,85 @@ +--- +description: >- + Concepts and a step-by-step pattern for migrating a CRUD entity to a CQRS+ES + Timeline aggregate +--- + +# Migrate CRUD to CQRS+ES + +## Queries + +A query in a CQRS implementation can be thought of as a system message that is handled by a handler or subscriber. In CQRS, the architecture is often designed to separate the handling of commands (which modify state) from queries (which read state). Here's a more detailed explanation: + +### Key Concepts in CQRS + +1. **Commands**: These are messages that represent an intent to change the state of the system. Commands are typically handled by command handlers, which process the command and apply the necessary changes to the write model. +2. **Queries**: These are messages that represent a request to read data from the system. Queries are handled by query handlers, which retrieve and return the data from the read model. +3. **Read Model**: The read model (or projection) is an optimized view of the data designed specifically for querying. It is kept in sync with the write model (often using events in an event-sourced system) to reflect the current state. + +### Handling Queries + +* **Query Handlers**: In a CQRS implementation, a query handler is responsible for processing a query message. The handler retrieves the necessary data from the read model and returns the result to the caller. +* **Subscribers**: While the term "subscriber" is more commonly used in the context of event handling (where components subscribe to events and react to them), in some architectures, the concept of handling queries can also be seen as subscribing to query messages. + +### Example + +Consider an e-commerce system using CQRS: + +* **Command**: `PlaceOrderCommand` is sent to a command handler to place a new order. The handler processes this command and updates the write model. +* **Event**: `OrderPlacedEvent` is generated as a result of the command and is published to update projections or read models. +* **Query**: `GetOrderDetailsQuery` is sent to a query handler to retrieve the details of an order. The handler queries the read model (e.g., a denormalized table or a projection) and returns the order details. + +## Projections + +In a CQRS (Command Query Responsibility Segregation) implementation, the term "projection" is used to refer to a table or other data structure that stores information about the current state of the system. Projections are read models that are built from the event stream (event sourcing) or from other sources of data to provide an optimized, read-only view of the data, tailored to specific query needs and are continuously updated to reflect the latest state of the system. + +Here's a more detailed explanation: + +1. **Projections**: Projections are created by processing events and transforming them into a format that is optimized for querying. Each projection is typically designed to support specific queries or views in the system. The process of creating and updating projections is known as "event projection" or "view generation". +2. **Read Models**: In CQRS, the read model is a general term for any data structure that is used to serve read queries. Projections are a type of read model. The read model can be in the form of SQL tables, NoSQL documents, in-memory data structures, etc. Projections specifically refer to read models that are built from event streams. +3. **Current State**: When referring to the current state of the system, projections are often used because they provide an up-to-date view of the data based on the latest events. These projections are continuously updated as new events are processed. + +### Example Scenario + +Imagine an e-commerce system using CQRS and event sourcing. When an order is placed, several events are generated (e.g., `OrderPlaced`, `ItemAddedToOrder`, `OrderShipped`). Projections are created to provide different views of the data, such as: + +* **Order Summary Projection**: A table that stores summarized information about each order, such as order ID, customer ID, total amount, and status. +* **Inventory Projection**: A table that stores the current inventory levels for each product. +* **Customer Orders Projection**: A table that stores a list of orders for each customer. + +These projections are updated whenever relevant events are processed, ensuring they reflect the current state of the system. + +### Note + +A projection table in a CQRS implementation can be considered a type of "memoization". I have never seen the term "memoization" used in any article on the topic of CQRS, but it is a helpful term when we think about projection tables, and this Wikipedia article describes the concept better than many articles written about CQRS. [https://en.wikipedia.org/wiki/Memoization](https://en.wikipedia.org/wiki/Memoization) + +## Timeline Implementation Pattern + +In reality, the insert, update, and delete methods in an entity Store class implement commands to change the state of an entity. + +The clue to a possible solution lies inside the previous statement... + +Suppose the state of an entity is modified **only** by one of these methods, and not by any another method outside the Store. + +In theory, this means we can rewrite the Insert, Update, and Delete methods in a Store class so they generate and send Timeline commands - instead of writing directly to the database. + +In theory, this means we can substantially decrease the impact of migrating a CRUD entity to a Timeline aggregate, because the code that invokes these methods does not require any modification. + +Here are the steps I followed in my initial experiment, using the Membership entity as the subject of the experiment: + +1. Improve the MembershipStore class so the number of Insert, Update, and Delete operations is as small as possible. Ideally, there should be no more than one of each. (Sometimes it is useful to have Insert and Update combined into one Save method.) +2. Search existing stored procedures and code to ensure there are no write operations on the old CRUD table outside the MembershipStore class. +3. Create a new projection table contacts.QMembership. +4. Copy existing rows from the old CRUD table contacts.Membership to the new projection table. +5. Drop the old CRUD table. +6. Create a view on the projection table to mimic the existence of the old CRUD table. This ensures existing views, stored procedures, and classes that read from the original table continue to work with no modification. +7. Refactor the MembershipStore class into a command generator class. Instead of writing directly to the Membership collection through DbContext, the methods in this class generate and send Timeline commands. + 1. Implement a new aggregate class: MembershipAggregate + 2. Implement new command classes, as required by the new command generator. + 1. Add a Command Receiver. + 3. Implement new change classes for the new commands. + 1. Add a Change Projector. + 4. Implement a new MembershipStore class to write to the projection table. + 5. Implement a maintenance action to generate all the log.Change entries needed to reproduce the data in the new projection table. After this is done, we should be able to replay all changes for all membership aggregates to produce a table with data that exactly matches the original CRUD table. + +Implementation time for this experiment: 3:24 PM to 5:19 PM = 115 minutes diff --git a/contributors/conventions/obsolete-timeline-changes.md b/contributors/conventions/obsolete-timeline-changes.md new file mode 100644 index 0000000..cb635c2 --- /dev/null +++ b/contributors/conventions/obsolete-timeline-changes.md @@ -0,0 +1,44 @@ +--- +description: >- + How to handle obsolete timeline Changes - either ignoring them or upgrading + them to a newer version +--- + +# Obsolete timeline changes + +We have two kinds of obsolete Changes: + +1. The Change can be ignored (we either don't use it at all or we push new changes that replace the old one) +2. The Change should be upgraded to a newer version + +## The Change can be ignored + +1. Delete the obsolete C# Change class and the related C# code +2. Create the list of obsolete changes +3. Register this list in the Projector's class constructor: + +
Obsolete timeline 01
+4. Add a new Handle method for SerializedChange to the Projector class: + +
Obsolete timeline 02
+5. Add a new When method to the State class, it will intercept all obsolete changes: + +
Obsolete timeline 03
+ +## The Change should be upgraded to a new version + +Lets assume we have the change **AttemptStarted1** and it needs to be marked as obsolete because we introduced a new change **AttemptStarted2** + +1. Make **AttemptStarted1** as a private nested class of **AttemptStarted2** and implement a new Upgrade method that will convert AttemptStarted1 to AttemptStarted2: + +
Obsolete timeline 04
+2. Delete all functionality related to **AttemptStarted1** +3. In the AttemptChangeProjector register AttemptStarted1 as an obsolete change: + +
Obsolete timeline 05
+4. Add a new Handle method in the Projector class that will upgrade **AttemptStarted1** to **AttemptStarted2** and call Handle for **AttemptStarted2**: + +
Obsolete timeline 06
+5. Add a new When method to AttemptState that will upgrade **AttemptStarted1** to **AttemptStarted2** and call When for **AttemptStarted2**: + +
Obsolete timeline 07
diff --git a/contributors/conventions/source-code.md b/contributors/conventions/source-code.md new file mode 100644 index 0000000..7ee43d0 --- /dev/null +++ b/contributors/conventions/source-code.md @@ -0,0 +1,199 @@ +--- +description: >- + Naming and coding conventions for InSite source code, including telemetry, + options and settings, lines of code, regions, TypeScript, and third-party code +--- + +# Source code + +## Introduction + +Some of the naming conventions documented here are new, and some are revised from older existing conventions. + +Existing code and existing database objects are **not** expected to follow these conventions perfectly. New code and new database objects should follow these conventions whenever possible. + +Historically, our naming conventions have been driven by the [Clean Architecture](https://matthewrenze.com/presentations/clean-architecture/) pattern, especially the organization of our source code into packages. As we transition from Microsoft .NET Framework to Microsoft .NET Standard and .NET Core, we are taking the opportunity to begin to follow a [Vertical-Slice Architecture](https://www.youtube.com/watch?v=_1rjo2l17kI) (VSA) pattern instead. + +> In reality, much of the Shift iQ code base is already organized like a [Modular Monolith](https://www.milanjovanovic.tech/blog/what-is-a-modular-monolith), and VSA is a better fit for this purpose. + +Recent changes and improvements to naming conventions are also motivated by the need to design and implement code that is easier to read, easier to test, and better aligned with CQRS+ES patterns and principles. + +VSA improves maintainability and flexibility because changes and improvements to an application feature are localized within its vertical slice. In other words, VSA does a better job of keeping tightly coupled classes in close proximity to one another, rather than spreading them across many different layers, in many different packages, where the stratification of layers and packages is determined by the technical responsibility rather than product feature or use case. + +Refer to this article for a good explanation of VSA and its benefits: + +[https://www.ghyston.com/insights/architecting-for-maintainability-through-vertical-slices](https://www.ghyston.com/insights/architecting-for-maintainability-through-vertical-slices) + +### Legacy Code Standards (PDF) + +Here is a copy of the InSite coding standard initially drafted and published in 2010. It was updated in January 2025, but time did not permit a careful review. Therefore, a careful review and revision of this PDF is still pending; when this is done, the standards should be extracted into Confluence pages here. + +## Telemetry + +### Serilog + +The physical path to the Serilog log file follows this convention: + +`C:\Base\Data\{Partition}\{Environment}\Logs\{Package}.Serilog-.txt` + +Note the trailing hyphen in the file name. This improves the readability of log file names when rolling intervals are enabled. + +### Sentry + +The physical path to the Sentry log file follows this convention: + +`C:\Base\Data\{Partition}\{Environment}\Logs\{Package}.Sentry.txt` + +When an error is reported to Sentry, it is understood that this identifies a problem that requires a solution. (For example, the solution may be a security improvement, a bug fix, or a performance optimization.) An error in Sentry is Resolved only after the problem is solved. + +If the cause of an error in Sentry is understood, but there is no immediate need for a solution (perhaps because it occurs infrequently, and/or more occurrences of the error are needed to obtain more information for an optimum solution), then - at a minimum - our code should be improved as follows: + +1. Catch the exception that causes the error. +2. Instead of sending the message to Sentry as an Error, send it as a Warning message (or as an Information message). + +In effect, this serves as documentation for the knowledge that the problem is identified, its impact is understood to be low, and messages related to the problem will be monitored at a lower priority. If the problem begins to occur more frequently, or its impact becomes more severe, then this decision can be revisited, and then perhaps enough information for a solution is available. + +### Options and Settings + +Use the suffix `Options` or `Settings` to name a class that relates to configuration. For example: + +* `AppSettings` +* `DatabaseOptions` + +The choice between the suffixes `Options` and `Settings` depends on context and usage. + +* Use `Options` if the class is used with DI and `IOptions`, or if it uses the Options Pattern in .NET Core. +* Otherwise use `Settings`. + +## Source Code + +### Recommendations + +* A file should **contain one class**. Multiple classes within the same file is discouraged. +* A **class name should be a noun**, according to its domain and architectural meaning. +* A **function name should be a verb** or verb-phrase, according to its context and what it does. +* A function should be **as small as possible**. +* A function should have an **explicit intent**, both in its name and code. +* A function should **do one thing only** and do it well. One thing means one level of abstraction (manipulating strings is one level, manipulating business rules is another level), or when nothing else can be extracted and meaningfully reused in another function or method. +* Methods in a class should be **organized per level of abstraction**, where the methods used by a method sit directly below it. +* Choose **descriptive names**, for **small functions**, that **do one thing**. +* A function should have **at most 3 arguments**. If we need more than 3 and if they are conceptually related, then we should group them in an object. +* Avoid output arguments (i.e., arguments to output data from a function). +* Avoid Boolean arguments. Use two functions instead. +* Comply to Command Query Segregation principles. Either: + * Do something (**change state**), **or** + * Get something (**return information** about an object), + * and **not both**! +* Avoid returning an error code. Instead, **throw an exception**. +* Ideally, the block inside a conditional or inside a loop should be **one line long**: a function call that is correctly named and therefore documents itself. +* Avoid platform-dependent code. For example, use `Path.DirectorySeparatorChar` rather than assuming a forward-slash (Linux and MacOS) or a backward-slash (Windows) in code that interacts with file system paths. + +A method invocation with a long parameter list that exceeds the length of one line of text should separate the parameter list: one parameter per line, with consistent indentation. + +* Each parameter is clearly visible and easy to identify +* It is easy to add, remove, or reorder parameters +* It is simple to spot differences in code reviews +* Consistent vertical alignment improves scanning + +For example: + +```csharp +SomeMethod( + parameterOne, + parameterTwo, + parameterThree, + parameterFour +); +``` + +### Lines of Code + +1. Ideally, a single line of code should not exceed 120 characters. In VS Code you can add this to display a guideline on the right page margin: `"editor.rulers": [120]` +2. A function should not exceed the number of lines of text that fit on the screen. In other words, no vertical scrolling should be necessary to read a function from start to finish. + +### Regions + +1. If the number of lines of code in a class is less than 200 then the class should **not** contain any code regions. +2. If the number of lines of code in a class is much larger than 200 then organize the code into logical regions. When possible, these logical groups should be based upon categorical organization rather than functional organization (i.e., business subdomain rather than method type). Either is acceptable, but categorical organization is preferred, because it helps guide refactoring when a large class needs to be broken down into multiple smaller classes. + + For example, functional organization looks like this: + + * Initialization and Loading + * UI Event Handling + * Database Operations + + ... whereas categorical organization looks like this: + + * Candidates + * Forms + * Registrations +3. The code behind a user interface control (ASCX) should be broken down into these groups: + + * region Control State = Model(s) + * region Security + * region Initialization and Loading + * region Binding Models to Controls (control setters) + * region Binding Controls to Models (control getters) + * region UI Navigation + * region UI Event Handling + * region Validation and Integrity + * region Database Operations + * region Sending Commands + * region (Other) +4. It should be possible (at least in theory) to refactor some of these regions into separate classes. + + For example, consider the user control `ExamMarkGrid.ascx`. The code-behind class is a **Controller** because it contains only Web.UI code (`System.Web.UI, InSite.Common.Web.UI, Telerik.Web.UI`). All its methods are small and simple. The methods themselves are not sorted alphabetically, but rather in order of their corresponding controls on the page. Also notice this class contains less than 200 LOC. + + The file `ExamMarkGridModel.cs` contains a separate class with NO dependencies on any Web.UI library. It encapsulates the logic that is needed by the ExamMarkGrid control. Because this class has no `Web.UI` dependencies, it can (in theory) be moved down the stack into the InSite.Application layer, where its methods might become useful to other parts of the system. Also notice this class contains less than 200 LOC. + +### TypeScript + +1. Do not use **any** type.\ + The compiler will complain if you try, this is intentional. +2. Terminate the operator with semicolon\ + Typescript allows omitting a semicolon in most cases, however, I think we should always use a semicolon to avoid confusion.\ + `doSomething();` +3. Always wrap the code block in braces, even if it is one-line code.\ + `if (isLoading) {`\ + `return;`\ + `}` +4. Use a Pascal Case for TSX file names:\ + `AdminGradebookSearch.tsx` +5. Use Camel Case for TS, CSS and JSON file names:\ + `gradebookSearch.ts` +6. Use a Pascal Case for class names, interface names and components:\ + `interface Props {`\ + `...`\ + `}`\ + `export default function AdminGradebookSearchCriteria(...`\ + `...` +7. Use a Camel Case for variable names, parameters, and function names:\ + `function doSomething(param1: string) {`\ + `const localVariable1 = "hello world";`\ + `}` +8. Use underscore when the global variable is defined:\ + `let _queryResult: QueryResult | null = null;` +9. Give preference to function declarations over function expressions where it is possible and reasonable:\ + `function doSomething() {`\ + `...`\ + `}`\ + **vs**\ + `const doSomething = () => {`\ + `...`\ + `}` +10. Use double quotes to specify string literals:\ + `const stringValue1 = "value in double quotes";`\ + It can be convenient if we want to copy JavaScript objects to JSON because JSON requires text to be enclosed in double quotes. + +### Third-Party Source Code + +Never integrate source code that is private property owned by another company, unless: + +1. We have a license that permits us to do so, and +2. An InSite manager has reviewed and approved the decision. + +This is necessary to ensure InSite is always in compliance with copyright laws and intellectual property laws. + +Never integrate source code that is subject to a license that requires changes to the license for InSite source code. This is necessary to ensure InSite is always in compliance with copyright laws and intellectual property laws. + +Do not integrate a new third-party component without first reviewing the decision with the team. This is necessary to ensure we do not introduce unnecessary risk to the overall quality of the system (e.g., its security, stability, maintainability, etc.). diff --git a/contributors/conventions/style-guide.md b/contributors/conventions/style-guide.md index a515c06..bc2dde0 100644 --- a/contributors/conventions/style-guide.md +++ b/contributors/conventions/style-guide.md @@ -75,7 +75,7 @@ When it is possible to do so, buttons that perform destructive actions should be The prompt for confirmation of a destructive action should look like this: -
+
Image
## Tooltips @@ -94,9 +94,9 @@ Tooltips provide brief, contextual help for UI elements. They should be concise, **Punctuation:** * **Do not use ending punctuation** (like periods) **for short phrases or fragments**.\ - &#xNAN;_Example: "Displays on the learner's dashboard"_ + &#xNAN;_Eexample: "Displays on the learner's dashboard"_ * **Use a period** if the tooltip is a complete sentence.\ - &#xNAN;_Example: "This text appears under the achievement title."_ + &#xNAN;_Eexample: "This text appears under the achievement title."_ **Grammar:** diff --git a/contributors/conventions/task-list-comment-tokens.md b/contributors/conventions/task-list-comment-tokens.md index c225176..9eeb74d 100644 --- a/contributors/conventions/task-list-comment-tokens.md +++ b/contributors/conventions/task-list-comment-tokens.md @@ -22,8 +22,6 @@ Here is a list of color-coded tokens used the source code for this platform. // WTF: WHAT THE ****? ``` - - 🟠 **ORANGE** code works but is not right: ```csharp @@ -41,7 +39,7 @@ Here is a list of color-coded tokens used the source code for this platform. // SMELLS: Same as FIXME. ``` - \ +\ 🔵 **BLUE** code works but needs more features or more explaining: ```csharp @@ -55,7 +53,7 @@ Here is a list of color-coded tokens used the source code for this platform. The [Task List](https://learn.microsoft.com/en-us/visualstudio/ide/using-the-task-list?view=vs-2022) tool in Visual Studio lets you track code comments that use tokens like `TODO` and `HACK` or custom tokens. For example: -
+
Contributor 01
## VS Code @@ -65,4 +63,4 @@ VS Code does not natively support Task List comment tokens in the same way as Vi You can define additional tags in the extension settings, and you can also define your own styles, regexes, and folders to include/exclude. For example: -
+
Contributor 02
diff --git a/contributors/conventions/terminology.md b/contributors/conventions/terminology.md new file mode 100644 index 0000000..a23a30d --- /dev/null +++ b/contributors/conventions/terminology.md @@ -0,0 +1,113 @@ +--- +description: >- + Key terms in our lexicon for designing, building, and managing the software, + including libraries, namespaces, entities, and URLs +--- + +# Terminology + +Here are some of the key terms in our lexicon for designing, building, and managing the software. + +| **Term** | **Meaning** | +| --- | --- | +| **Partition** | A partition is a separate instance of the system, dedicated to a specific customer (or subset of customers. Aliases for this term include "Enterprise" (sometimes used by InSite in the past) and "Tenant" (used by Octopus). | +| **Environment** | An environment is a configured instance of the system designed for a specific purpose. Environments are isolated from one another to ensure stability, consistency, and the ability to perform tasks without interference across different phases of a release cycle. There are four (4) environments:
  1. Local: This is an offline environment used by programmers to develop, test, and debug system changes.
  2. Development: This is an online testing environment used by QA teams to validate the system's functionality, performance, and reliability for a new release.
  3. Sandbox: This is a staging environment that mimics the production environment to validate deployment processes, simulate real-world scenarios, and test patches for a hotfix release.
  4. Production: This is the live system accessible to customers and end-users.
| +| **Library** | A library is a source code project that defines and/or implements classes for reuse in other projects. There are four (4) types of library:
  1. Base or Common: Implements basic reusable classes with no third-party dependencies.
  2. Toolbox: Implements advanced reusable classes with third-party dependencies.
  3. Contract: Defines and implements settings, rules, and constraints.
  4. Service: Implements logic specific to an application (e.g., persistence, domain).
Historically, InSite libraries used naming conventions from Clean Architecture terminology. These older conventions are in the process of being replaced with conventions that are more suitable for a vertical slice architecture (i.e., the modular monolith pattern), which is a better representation of how we organize source code in our platform. | +| **Base** or **Common** | A common library implements general-purpose functionality where third-party dependencies are not permitted. A base (or common) library:
  • Targets .NET Standard 2.0 for maximum reusability.
  • Contains zero dependencies on third-party libraries.
| +| **Toolbox** | A toolbox library implements general-purpose functionality where third-party dependencies are permitted and potentially necessary. A toolbox library:
  • Targets .NET Standard 2.0 if possible, otherwise targets .NET Core 9.0. Targets .NET Framework 4.8 only if it is not possible to target .NET Standard or .NET Core.
  • May contain dependencies on third-party libraries.
| +| **Contract** | A contract library defines the rules and constraints to help enforce consistency, validate inputs, and/or specify obligations and guarantees between different parts of the code. A contract library:
  • Defines interfaces.
  • Implements classes for configuration settings.
  • Implements classes for request/response data types (i.e., input and output classes).
  • Targets .NET Standard 2.0 for maximum reusability.
  • Contains zero dependencies on third-party libraries.
Ideally, classes are plain old class objects (POCO) and data transfer objects (DTO). Constant literals and enumeration types are also appropriate in a contract library. | +| **Service** | A service library implements the features for a specific application. A service library:
  • Targets .NET Core 9.0 for maximum power and flexibility. Target .NET Standard only if it is useful and easy. If it is not possible to target .NET Core or .NET Standard for any reason, then target .NET Framework 4.8.
  • May contain dependencies on third-party libraries.
| + +Here is a summary of the main considerations for each type of **Library**: + +| | **Base (Common)** | **Toolbox** | **Contract** | **Service** | +| --- | --- | --- | --- | --- | +| **Target Build** (in order of preference) | .NET Standard 2.0 | .NET Standard 2.0
.NET Core 9.0
.NET Framework 4.8 | .NET Standard 2.0 | .NET Core 9.0
.NET Framework 4.8 | +| **Dependencies** on Third-Party Libraries | Not Permitted | Permitted | Not Permitted | Permitted | +| **Directories** (typical focus for root-level folders) | Technical Aspects
e.g., Cache; IO; Mail; Sql; Text; Threading; Time; Web | Technical Aspects | Business Modules
e.g., Assessment; Billing; Contact; Learning; Survey; Workflow | Business Modules | + +> Please note the InSite codebase is highly dependent on [Newtonsoft.Json](https://www.newtonsoft.com/json) for serialization, therefore this is the only exception to rules that disallow third-party library references. + +## Namespaces + +Here is a guideline for namespace structure: + +| | | +| --- | --- | +| Functional Scope | Application; Infrastructure; Kernel | +| Layer (or Purpose) | Common (or Base or Fabric); Contract; Toolbox; Service (Data (or Persistence or Storage); State (or Domain); Process (or Logic or Business or Application)); Api; Sdk; Test (or Lab); Terminal (or Maintenance); UI (or Presentation) | +| Component Type | Composition; Feature; Internal; Plugin; Utility | +| Component | **Composition**: (none listed)
**Feature**: Achievement, Assessment; Billing; Calendar; Contact; Content; Course; Gradebook; Job; Location; Logbook; Message; Report; Site (Shell); Standard; Survey; Workflow
**Internal**: (none listed)
**Plugin**: Integration; Variant
**Utility**: Metadata; Security; Setup; Timeline | +| Subcomponent | There is no fixed list here. Subcomponents vary per component. For example, the Message component might have subcomponents that include Templates, Mailouts, and Recipients. | + +In general (and if possible), a C# namespace should follow this convention: + +`[developer].[scope]..[component-type].[component].[subcomponent]` + +> `[layer]` and/or `[purpose]` should be included in the namespace. These are not assigned a fixed location within the namespace segmentation because the product architecture determines the structure of project assemblies in the solution, and this structure decides the best placement of purpose and layer names within the space. + +For example, in a traditional clean architecture pattern with horizontal layers based on technical function, namespaces might look like this: + +* Product.Persistence.Contact.Groups +* Product.Persistence.Contact.People +* Product.Application.Contact.Groups +* Product.Application.Contact.People +* Product.UI + +In a modular monolith architecture with vertical slices based on business category, namespaces might look like this: + +* Product.Contact.Service.Groups.Data +* Product.Contact.Service.Groups.Process +* Product.Contact.Service.People.Data +* Product.Contact.Service.People.Process +* Product.Contact.UI + +The name of a C# assembly should follow the same convention. Ideally, an assembly name should have a layer or purpose as its suffix. + +*** + +Here is the convention decided in DEV-10637: + +**Assembly.ComponentType.Component.Subcomponent.Layer** + +… where: + +* **ComponentType** = Internal | Composition | Feature | Plugin | Utility +* **Component** = (varies by component type; if ComponentType = Feature then Component = toolkit) +* **Subcomponent** (varies by component; if component = Feature then subcomponent = aggregate) +* **Layer** = (optional; only needed when the layer is not already specified in the Assembly name; if needed then = Common | Contract | Toolbox | Service | Api | Sdk | Test | Lab | Terminal | UI) + +*** + +For the sake of example, so we can see how these conventions look and feel, I have applied them to the InSite.Test project as an experiment. + +[https://github.com/InSite/code/pull/5793](https://github.com/InSite/code/pull/5793) + +In this example: + +* Assembly = InSite.Test +* Component Type = Internal | Composition | Feature | Utility +* Subcomponent = (varies by component type) +* Layer = (omitted because "Test" is in the Assembly name, and this is the purpose of all classes in all namespaces contained by this assembly) + +> Notice I have added a Readme file to each subfolder in the project to help us remember the purpose of each main subfolder. If this proves to be a good idea, then we can continue with this approach and add Readme files to each Subcomponent sub-subfolder also. + +## Entities + +The mapping between SQL Server database table names and C# entity class names is formally defined in the database table `metadata.TEntity`. You can use this search page to explore the data in this table: + +[https://dev-demo.shiftiq.com/ui/admin/database/entities/search](https://dev-demo.shiftiq.com/ui/admin/database/entities/search) + +## URLs + +Here are the correct terms for each type of URL: + +1. [**https://example.com/hello**](https://example.com/hello) = **Absolute URL** (or fully qualified URL). Contains the complete address with scheme, domain, and path. +2. **/hello** = **Root-relative URL** (or absolute path). Starts with a forward slash and is relative to the domain root. +3. **hello** = **Relative URL** (or relative path). Relative to the current directory/location. + +For example, if you are currently at `https://example.com/docs/guide.html` then: + +* The absolute URL works from anywhere +* The root-relative URL `/hello` would resolve to `https://example.com/hello` +* The relative URL `hello` would resolve to `https://example.com/docs/hello` diff --git a/contributors/conventions/version-numbers.md b/contributors/conventions/version-numbers.md index a8c1a33..59d25dc 100644 --- a/contributors/conventions/version-numbers.md +++ b/contributors/conventions/version-numbers.md @@ -37,8 +37,8 @@ The Release number in a message submitted to Sentry includes only the first 3 se This improves the readability and management of Sentry issues. Also, it enables us to mark an issue “Resolved until next release”, which fits with our daily automated deployments to Development and Sandbox. -
+
Image (1) (1)
Here is a code sample to show how this is achieved: -
+
Image (2)
diff --git a/contributors/domains/coming-soon.md b/contributors/domains/coming-soon.md index 670c1b6..4fcf620 100644 --- a/contributors/domains/coming-soon.md +++ b/contributors/domains/coming-soon.md @@ -1,2 +1,13 @@ -# Coming soon! +--- +description: Placeholder — domain (design) documentation is in progress +--- +# Coming soon + +The Design / Domains section is not yet populated. Planned content includes: + +* Domain models for each of the 12 domain toolkits (Billing, Booking, Competency, Content, Directory, Evaluation, Learning, Messaging, Progress, Reporting, Workflow, Workspace). +* Aggregate boundaries, key invariants, and the events each aggregate emits. +* Cross-domain relationships and the rules that govern them. + +If you need any of this in the meantime, ask in the team channel and we will prioritize the relevant page. diff --git a/contributors/getting-started/components/utility-components/README.md b/contributors/getting-started/components/utility-components/README.md deleted file mode 100644 index 99f5a12..0000000 --- a/contributors/getting-started/components/utility-components/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Utility Components - diff --git a/contributors/getting-started/components/utility-components/security/README.md b/contributors/getting-started/components/utility-components/security/README.md deleted file mode 100644 index 3ebfc6f..0000000 --- a/contributors/getting-started/components/utility-components/security/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Security - diff --git a/contributors/getting-started/components/utility-components/setup/README.md b/contributors/getting-started/components/utility-components/setup/README.md deleted file mode 100644 index cbec55f..0000000 --- a/contributors/getting-started/components/utility-components/setup/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Setup - diff --git a/contributors/implementation/back-end/README.md b/contributors/implementation/back-end/README.md index 955a3ee..8bcc081 100644 --- a/contributors/implementation/back-end/README.md +++ b/contributors/implementation/back-end/README.md @@ -1,2 +1,18 @@ -# Code generation +--- +description: >- + Back-end implementation notes: API endpoints, CQRS+ES, and code generation +--- +# Back end + +The back end of the Shift iQ platform is an ASP.NET Web API built around a CQRS + Event Sourcing core. This section collects implementation notes for contributors working on it. + +## In this section + +* [Add a new set of API endpoints](add-a-new-set-of-api-endpoints.md) — the end-to-end checklist for a new endpoint family. + +See also: + +* [API conventions](../../conventions/api-conventions.md) +* [Database naming conventions](../../conventions/database-naming-conventions.md) +* [Migrate CRUD to CQRS+ES](../../conventions/migrate-crud-to-cqrs-es.md) diff --git a/contributors/implementation/back-end/add-a-new-set-of-api-endpoints.md b/contributors/implementation/back-end/add-a-new-set-of-api-endpoints.md index e3f203f..3aa9aed 100644 --- a/contributors/implementation/back-end/add-a-new-set-of-api-endpoints.md +++ b/contributors/implementation/back-end/add-a-new-set-of-api-endpoints.md @@ -16,7 +16,7 @@ Before you start, navigate to `ui/admin/metadata/entities/search` in your local When you find the entity definition, make special note of the Component, Subcomponent, and Entity Name. -
+
Back end 01
### Prepare the code generator @@ -48,7 +48,7 @@ Open your file explorer and navigate to the output folder. You should see 3 subf * **Contract**: Query and command classes, request and response classes, DTO classes * **Service**: Classes to read and write database entities, and adapters for entity/model conversion -
+
Back end 02
## Integrate the new classes @@ -65,7 +65,7 @@ For example. copy File, FileActivity, and FileClaim folders * from **Output/Contract/Content/Files** * to **code/src/library/Shift.Sdk/Contract/Content/Files** -
+
Code generation 01
Build the solution to ensure no compiler errors. @@ -80,11 +80,11 @@ Copy from the output folder to the Service project. For example, copy the Data folder * from **Output/Service/Content/Files** -* to **code/src/library/Shift.Service/Conent/Files** +* to **code/src/library/Shift.Service/Content/Files** -
+
Code generation 02
-In the output folder, navigate to the Service/Orchecestration subfolder and open the TableDbContext class. +In the output folder, navigate to the Service/Orchestration subfolder and open the TableDbContext class. Find the entity type configuration code and copy this to TableDbContext in the Shift.Service library. @@ -119,9 +119,9 @@ Copy from the output folder to the Api project. For example, copy the Data folder * from **Output/Api/Content/Files** -* to **code/src/library/Shift.Api/Conent/Files** +* to **code/src/library/Shift.Api/Content/Files** -
+
Code generation 03
Build the solution to ensure no compiler errors. @@ -139,13 +139,13 @@ The generated code provides some guidance and advice, but the details are for yo For example: -
+
Back end 04
### Remove organization identifier properties from models Every API request is authenticated with an access key that identifies the user and the organization submitting the request. Therefore, the organization identifier is not needed in an API response, because it is redundant to the client. -
+
Back end 03
### Rename Identifier suffixes to Id in model property names @@ -192,5 +192,4 @@ Open the Shift collection in Insomnia, and add requests to test and confirm the For example: -
- +
Code generation 04
diff --git a/contributors/implementation/front-end/README.md b/contributors/implementation/front-end/README.md index 5bf49bd..d49b65c 100644 --- a/contributors/implementation/front-end/README.md +++ b/contributors/implementation/front-end/README.md @@ -1,3 +1,14 @@ +--- +description: Front-end implementation notes for InSite.UI and Shift.UI +--- + # Front end -### Test DEV-10789 \ No newline at end of file +The Shift iQ front end is split into two web apps: **InSite.UI** (the administrator surface) and **Shift.UI** (the learner / portal surface). This section collects implementation notes for contributors working on either one. + +## In this section + +* [InSite.UI](insite.ui/README.md) — the administrator interface. + * [Navigation](insite.ui/ui-navigation.md) +* [Shift.UI](shift.ui/README.md) — the learner and portal interface. + * [Search](shift.ui/ui-search.md) diff --git a/contributors/implementation/front-end/insite.ui/README.md b/contributors/implementation/front-end/insite.ui/README.md index 0712928..a9807dd 100644 --- a/contributors/implementation/front-end/insite.ui/README.md +++ b/contributors/implementation/front-end/insite.ui/README.md @@ -42,15 +42,15 @@ Interface layouts should be optimized for conversion while providing sufficient # Admin page layout guidelines -- [Admin Portal](#admin-portal) - - [Simple Input Screens](#simple-input-screens) - - [Outline Pages](#outline-pages) - - [Cards with Search Results](#cards-with-search-results) - - [Cards with Inputs](#cards-with-inputs) +* Admin Portal + * [Simple Input Screens](#simple-input-screens) + * [Outline Pages](#outline-pages) + * [Cards with Search Results](#cards-with-search-results) + * [Cards with Inputs](#cards-with-inputs) On this page we focus on describing a set of guidelines on how to place buttons on different screens in different *boxes* from the admin site. -> **Note** +> **Note** > This is just a **Draft**. Let us all collaborate on achieving the best possible outcome and create the best standards together for button placement. --- @@ -59,11 +59,12 @@ On this page we focus on describing a set of guidelines on how to place buttons **Description:** -Every normal input screen like **Create**, **Edit**, **Change/Update (from Outline)** or **Delete** can be done using this approach: -- Input fields are implemented in different cards with additional titles and description (if necessary). -- Main action buttons for **Saving/Updating** or **Canceling** should be placed in the **bottom left**. +Every normal input screen like **Create**, **Edit**, **Change/Update (from Outline)** or **Delete** can be done using this approach: -⚠️ If screens are longer and buttons don’t fit, try to make the buttons **sticky at the bottom of the screen**. +* Input fields are implemented in different cards with additional titles and description (if necessary). +* Main action buttons for **Saving/Updating** or **Canceling** should be placed in the **bottom left**. + +⚠️ If screens are longer and buttons don’t fit, try to make the buttons **sticky at the bottom of the screen**. [Reference: Position sticky button bar (bottom)](https://codepen.io/jaakritso/pen/zMXRaw) **Examples:** @@ -73,14 +74,14 @@ Every normal input screen like **Create**, **Edit**, **Change/Update (from Outli | ![Edit Seat — bottom-left Save/Cancel](https://github.com/user-attachments/assets/54583a6f-9a36-4a9e-9a3a-b1607c4f8c29) | ![Schedule a New Class — bottom-left Save/Cancel](https://github.com/user-attachments/assets/3947dbb0-9449-4abd-b84e-bda3e912ba41) | | ![Describe Class — bottom-left Save/Cancel](https://github.com/user-attachments/assets/af93fba0-142d-484c-87bf-251f60eb87dd) | ![Delete Person — bottom-left Delete/Cancel](https://github.com/user-attachments/assets/c597d148-d60e-497e-b652-3eecffd289dc) | - ## Outline Pages **Description:** -An outline page displays combined information for a specific *Toolkit Object*. -- The practice so far: keep all **outline object control buttons** on the **top left**. -- The entirety of the information is locked within one card and separated with grouping dividers. +An outline page displays combined information for a specific *Toolkit Object*. + +* The practice so far: keep all **outline object control buttons** on the **top left**. +* The entirety of the information is locked within one card and separated with grouping dividers. **Examples:** @@ -90,27 +91,26 @@ An outline page displays combined information for a specific *Toolkit Object*. |---|---| | ![Class Outline — top-left action buttons](https://github.com/user-attachments/assets/45c1c5bc-06f8-439f-bdf8-86358a5cbb47) | ![Outline — 2020 ISO Policies with top-left action buttons](https://github.com/user-attachments/assets/9deaf45e-5aa3-405e-9148-004ccb7d8b58) | - ## Cards with Search Results **Description:** -Some cards may gather and display data in a *Search Results* way. These cards usually: -- Have a **Card Title** or **Filter** on the **top left**. -- Include additional **Action Buttons** (e.g., Downloading, Adding to results) on the **top right**. -- Item rows may include action links/buttons such as **View/Edit/Delete**, placed on the **right side** of the item row. +Some cards may gather and display data in a *Search Results* way. These cards usually: + +* Have a **Card Title** or **Filter** on the **top left**. +* Include additional **Action Buttons** (e.g., Downloading, Adding to results) on the **top right**. +* Item rows may include action links/buttons such as **View/Edit/Delete**, placed on the **right side** of the item row. | | | |---|---| | image | image | | image | image | - ## Cards with Inputs **Description:** -Some cards, in addition to regular **Save/Update/Delete** actions, may have extra actions such as adding data to a *Toolkit Object*. +Some cards, in addition to regular **Save/Update/Delete** actions, may have extra actions such as adding data to a *Toolkit Object*. Example: a card with an **Upload** button. (Placement for this is still under discussion.) **Examples:** @@ -133,7 +133,6 @@ Example: a card with an **Upload** button. (Placement for this is still under di The topic was discussed here: [DEV-5903: Upgrade UI\Desktops\Admin\Courses2\Manage.aspx from B3 to B5 Closed](https://insite.atlassian.net/browse/DEV-5903) - If the form has nested tabs then: @@ -144,4 +143,4 @@ If the form has nested tabs then: ## Delete -For delete checkbox we need to use +For delete checkbox we need to use diff --git a/contributors/implementation/front-end/insite.ui/ui-navigation.md b/contributors/implementation/front-end/insite.ui/ui-navigation.md index b39e97f..d2a2528 100644 --- a/contributors/implementation/front-end/insite.ui/ui-navigation.md +++ b/contributors/implementation/front-end/insite.ui/ui-navigation.md @@ -19,7 +19,7 @@ The proposed solution uses two new interfaces and the class **ReturnUrl**. 1. The screen should implement two additional interfaces: **IOverridesParent** and **IHasParentLinkParameters** -``` +```text public partial class Lock : BaseScreenUserControl, IOverridesParent, IHasParentLinkParameters { ``` @@ -27,7 +27,7 @@ The proposed solution uses two new interfaces and the class **ReturnUrl**. 1. Implement methods **GetParent** and **GetParentLinkParameters**.\ Below is an example from Lock.ascx screen -``` +```text WebRoute IOverridesParent.GetParent() => GetParent(); @@ -39,14 +39,14 @@ Methods **GetParent** and **GetParentLinkParameters** are members of **BaseScree 1. If it is required to redirect back to the parent screen manually then **GetReturnUrl** method can be used -``` +```text CancelButton.NavigateUrl = GetReturnUrl("panel=results"); ``` 1. When it is needed to generate the link with "return url" then the class **ReturnUrl** can be used.\ Below is an example from Responses/Outline.ascx -``` +```text LockLink.NavigateUrl = new ReturnUrl($"session={queryString.Session}") .GetRedirectUrl($"/admin/surveys2/responses/lock?session={queryString.Session}"); UnlockLink.NavigateUrl = new ReturnUrl($"session={queryString.Session}") @@ -55,4 +55,4 @@ Methods **GetParent** and **GetParentLinkParameters** are members of **BaseScree ### Notes -1. The approach is changed in Shift.UI project \ No newline at end of file +1. The approach is changed in Shift.UI project diff --git a/contributors/implementation/front-end/shift.ui/README.md b/contributors/implementation/front-end/shift.ui/README.md index 265c30b..d3aca9f 100644 --- a/contributors/implementation/front-end/shift.ui/README.md +++ b/contributors/implementation/front-end/shift.ui/README.md @@ -15,55 +15,64 @@ This documentation assumes familiarity with React and JavaScript/TypeScript fund ### Core Tools **Visual Studio Code** -- Primary code editor for the project -- Download: [https://code.visualstudio.com/download](https://code.visualstudio.com/download) -- **Tip**: Master keyboard shortcuts to significantly improve development efficiency + +* Primary code editor for the project +* Download: [https://code.visualstudio.com/download](https://code.visualstudio.com/download) +* **Tip**: Master keyboard shortcuts to significantly improve development efficiency **Node.js** -- Required for React compilation and build processes -- Install the latest LTS version: [https://nodejs.org/en/download/prebuilt-installer/current](https://nodejs.org/en/download/prebuilt-installer/current) + +* Required for React compilation and build processes +* Install the latest LTS version: [https://nodejs.org/en/download/prebuilt-installer/current](https://nodejs.org/en/download/prebuilt-installer/current) ### Frontend Technologies **TypeScript** -- Primary language for type-safe development -- All application code is written in TypeScript + +* Primary language for type-safe development +* All application code is written in TypeScript **Vite Build Tool** -- Modern build tool optimized for frontend development -- Project created with "React + TypeScript" template -- Documentation: [https://vitejs.dev/guide/](https://vitejs.dev/guide/) + +* Modern build tool optimized for frontend development +* Project created with "React + TypeScript" template +* Documentation: [https://vitejs.dev/guide/](https://vitejs.dev/guide/) ### Key Libraries **React Router** -- Handles client-side routing and navigation between pages -- Documentation: [https://reactrouter.com/start/data/installation](https://reactrouter.com/start/data/installation) + +* Handles client-side routing and navigation between pages +* Documentation: [https://reactrouter.com/start/data/installation](https://reactrouter.com/start/data/installation) **React Bootstrap** -- Bootstrap component implementations for React -- Provides consistent UI components and styling -- Documentation: [https://react-bootstrap.netlify.app/docs/getting-started/introduction](https://react-bootstrap.netlify.app/docs/getting-started/introduction) + +* Bootstrap component implementations for React +* Provides consistent UI components and styling +* Documentation: [https://react-bootstrap.netlify.app/docs/getting-started/introduction](https://react-bootstrap.netlify.app/docs/getting-started/introduction) **DND Kit** -- Modern drag-and-drop functionality -- Documentation: [https://dndkit.com/](https://dndkit.com/) + +* Modern drag-and-drop functionality +* Documentation: [https://dndkit.com/](https://dndkit.com/) **Jest Testing Framework** -- Unit testing and test automation -- Documentation: [https://jestjs.io/](https://jestjs.io/) + +* Unit testing and test automation +* Documentation: [https://jestjs.io/](https://jestjs.io/) ## Project Architecture ### Repository Location -- **Repository**: [https://github.com/InSite/Code](https://github.com/InSite/Code) -- **Project Path**: `/src/ui/Shift.UI` + +* **Repository**: [https://github.com/InSite/Code](https://github.com/InSite/Code) +* **Project Path**: `/src/ui/Shift.UI` ### Directory Structure The `/src` folder contains the complete React application with the following organization: -``` +```text /src ├── /api # API integration layer ├── /cache # Custom caching implementation @@ -80,52 +89,64 @@ The `/src` folder contains the complete React application with the following org #### Key Directories Explained **`/src/api`** -- Contains integration code for Shift API (v2) and InSite API (v1) -- Note: v1 API is only used in local development environment + +* Contains integration code for Shift API (v2) and InSite API (v1) +* Note: v1 API is only used in local development environment **`/src/cache`** -- Custom cache implementation for optimizing data retrieval and storage + +* Custom cache implementation for optimizing data retrieval and storage **`/src/contexts`** -- React context components for global state management + +* React context components for global state management **`/src/components`** -- Reusable UI components shared across multiple pages -- Global components that maintain consistency throughout the application + +* Reusable UI components shared across multiple pages +* Global components that maintain consistency throughout the application **`/src/helpers`** -- Application constants, configuration values, and utility functions -- Common functionality used across different parts of the application + +* Application constants, configuration values, and utility functions +* Common functionality used across different parts of the application **`/src/hooks`** -- Custom React hooks that encapsulate reusable stateful logic -- Shared across multiple components for consistent behavior + +* Custom React hooks that encapsulate reusable stateful logic +* Shared across multiple components for consistent behavior **`/src/layouts`** -- Layout components that define page structure -- Currently includes `AdminHomeLayout` based on `AdminHome.master` from InSite.UI + +* Layout components that define page structure +* Currently includes `AdminHomeLayout` based on `AdminHome.master` from InSite.UI **`/src/models`** -- TypeScript interfaces and type definitions -- Ensures type safety across the application + +* TypeScript interfaces and type definitions +* Ensures type safety across the application **`/src/routes`** -- Page components organized by route structure -- Each page has its own dedicated folder (e.g., `/client/admin/home` → `/src/routes/admin/home`) + +* Page components organized by route structure +* Each page has its own dedicated folder (e.g., `/client/admin/home` → `/src/routes/admin/home`) **`/src/routes/_shared`** -- Custom components containing business logic shared between pages -- Reusable page-specific functionality + +* Custom components containing business logic shared between pages +* Reusable page-specific functionality ## Application Flow ### Development Environment -- React development server runs on **http://localhost:3000** via Vite -- Hot module replacement for efficient development workflow + +* React development server runs on **http://localhost:3000** via Vite +* Hot module replacement for efficient development workflow ### Production Environment -- Application is bundled into optimized JavaScript files -- Deployed to `/source/InSite.UI/React` subfolder as a single JS bundle + +* Application is bundled into optimized JavaScript files +* Deployed to `/source/InSite.UI/React` subfolder as a single JS bundle ### Page Navigation Process @@ -136,22 +157,24 @@ When navigating to any page, the application follows this sequence: 2. **Entity-Specific Data**: Loads data specific to the current page/entity (e.g., user information, content data) 3. **Authentication Check**: Monitors API responses for authentication status - - HTTP 401/403 responses trigger automatic redirect to ASP.NET WebForms login page - - Ensures secure access to authenticated content + * HTTP 401/403 responses trigger automatic redirect to ASP.NET WebForms login page + * Ensures secure access to authenticated content ## Getting Started ### Initial Setup 1. **Open Terminal** - - Use PowerShell, Command Prompt, or VSCode integrated terminal + * Use PowerShell, Command Prompt, or VSCode integrated terminal 2. **Navigate to Project Directory** + ```bash cd /src/ui/Shift.UI ``` 3. **Install Dependencies** + ```bash npm install ``` @@ -159,19 +182,23 @@ When navigating to any page, the application follows this sequence: ### Development Commands **Start Development Server** + ```bash npm run dev ``` -- Launches the development server with hot reload -- Application available at http://localhost:3000 + +* Launches the development server with hot reload +* Application available at http://localhost:3000 **Build for Production** + ```bash npm run build ``` -- Compiles and optimizes the React application -- Outputs production-ready files to `/source/InSite.UI/React` folder -- Creates minified, optimized bundles for deployment + +* Compiles and optimizes the React application +* Outputs production-ready files to `/source/InSite.UI/React` folder +* Creates minified, optimized bundles for deployment ### Development Workflow @@ -182,15 +209,16 @@ npm run build ## Best Practices -- **Type Safety**: Leverage TypeScript for better code quality and developer experience -- **Component Reusability**: Use the `/src/components` directory for shared UI elements -- **Custom Hooks**: Extract reusable logic into custom hooks in `/src/hooks` -- **API Integration**: Keep API calls organized in the `/src/api` directory -- **Testing**: Write tests using Jest to ensure code reliability +* **Type Safety**: Leverage TypeScript for better code quality and developer experience +* **Component Reusability**: Use the `/src/components` directory for shared UI elements +* **Custom Hooks**: Extract reusable logic into custom hooks in `/src/hooks` +* **API Integration**: Keep API calls organized in the `/src/api` directory +* **Testing**: Write tests using Jest to ensure code reliability ## Troubleshooting If you encounter issues: + 1. Ensure Node.js LTS version is installed 2. Clear node_modules and reinstall: `rm -rf node_modules && npm install` 3. Check that all required dependencies are properly installed diff --git a/contributors/implementation/front-end/shift.ui/ui-search.md b/contributors/implementation/front-end/shift.ui/ui-search.md index 69d86e3..741196a 100644 --- a/contributors/implementation/front-end/shift.ui/ui-search.md +++ b/contributors/implementation/front-end/shift.ui/ui-search.md @@ -9,9 +9,9 @@ description: >- I’ll be using Gradebook Search screen as an example 1. Create an interface for the API Row model (ApiGradebookMatch) and API Query model (ApiSearchGradebooks)\ -
+
Search api models
2. Add search and download methods to the controller object: -
+
Search api functions
3. Go to cacheKey.ts and add a new unique key to the union type CacheKey @@ -19,8 +19,8 @@ I’ll be using Gradebook Search screen as an example This folder will contain code related to Gradebook Search form 5. Create a new file GradebookRow.ts with interface GradebookRow and the function toGradebookRow\ - - GradebookRow provides properties used by Result Grid. - - toGradebookRow converts ApiGradebookMatch to GradebookRow + * GradebookRow provides properties used by Result Grid. + * toGradebookRow converts ApiGradebookMatch to GradebookRow 6. Create a new file GradebookCriteria.ts with the interface GradebookCriteria and functions defaultGradebookCriteria and toApiSearchGradebooks @@ -33,4 +33,4 @@ I’ll be using Gradebook Search screen as an example 10. Create a new file GradebookSearch.tsx that joins Search, Result, and Download components. 11. Add a new Search form to routes in the file /src/routes/formRoutes.tsx: -
\ No newline at end of file +
Search menu
diff --git a/contributors/implementation/reference.md b/contributors/implementation/reference.md index d2ae2da..21b1eff 100644 --- a/contributors/implementation/reference.md +++ b/contributors/implementation/reference.md @@ -15,7 +15,4 @@ Clearly, every software system has a "Contributor API", so it is unfortunate the By adopting this convention, we make it immediately clear whether documentation is intended for those _integrating with_ the system versus those _building on_ the system. In turn, this helps reduce confusion and ensures contributors can easily locate the technical depth they need for internal development work. - -
Contributor APIInternal interface for team members modifying and maintaining the systemhttps://docfx.shiftiq.com/
Developer APIExternal public interface for developers and integrators extending the systemhttps://docs.shiftiq.com/developers/api-v2/introduction
- diff --git a/contributors/getting-started/components/README.md b/contributors/toolkits/README.md similarity index 50% rename from contributors/getting-started/components/README.md rename to contributors/toolkits/README.md index 6e237b8..039e528 100644 --- a/contributors/getting-started/components/README.md +++ b/contributors/toolkits/README.md @@ -1,22 +1,24 @@ --- -hidden: true +description: >- + Internal documentation describing Shift iQ features so administrators and + developers can perform advanced tasks, troubleshoot, and assist customers --- -# Components +# Toolkits -### Purpose +## Purpose -The Components documentation is intended for internal use. Its purpose is to describe Shift iQ features in such a way that administrators and developers can understand the steps to perform more advanced tasks when learning the system, troubleshooting issues, and/or assisting customers with their accounts. +The Toolkits documentation is intended for internal use. Its purpose is to describe Shift iQ features in such a way that administrators and developers can understand the steps to perform more advanced tasks when learning the system, troubleshooting issues, and/or assisting customers with their accounts. -> Note: The term **Toolkit** will be deprecated because it sounds a little too technical. In business contexts we will use these terms in its place: **App**, **Plugin**, and **Utility**. +> Note: The term **Toolkit** will be deprecated because it sounds a little too technical. In business contexts we will use these terms in its place: **Domain**, **Plugin**, **Utility**, and **Shell**. > -> The term **App** is considered synonymous with **Feature Set**, and the term Feature Set may be abbreviated **Features** or **Feature** in documentation and code. +> The term **Domain** is considered synonymous with **App** and **Feature Set**, and the term Feature Set may be abbreviated **Features** or **Feature** in documentation and code. > -> From a technical perspective, App (or Feature), Plugin, and Utility are component types, where a “component” is understood to be a logical, high-level, module (i.e., a vertical slice of features). The Shift iQ platform contains several components, and each component represents a bounded context of the overall application domain. For example, the Contact component contains functionality related to contact information management. +> From a technical perspective, Domain, Plugin, Utility, and Shell are toolkit types, where a “toolkit” is understood to be a logical, high-level, subsystem (i.e., a vertical slice of features). The Shift iQ platform contains several toolkits, and each toolkit represents a bounded context of the overall application domain. For example, the Contact toolkit contains functionality related to contact information management. > > Refer to this article for a technical discussion of the modular (vertical) software architecture pattern: [Modular Monolithic Architecture](https://medium.com/design-microservices-architecture-with-patterns/microservices-killer-modular-monolithic-architecture-ac83814f6862) -### Convention +## Convention The steps to perform an application task should be described in such a way that anyone can follow the steps as a test case to confirm the behaviour of the system meets expectations. @@ -26,12 +28,12 @@ Try to apply a consistent approach to all public customer-facing help topics. > Note: Many articles on the topic of software help documentation reference Stripe as an excellent example. While authoring and reviewing help content for Shift iQ, if you want to see an example of best practices applied to a real-world documentation site, then visit [Stripe Docs](https://docs.stripe.com/) and [Stripe API Reference](https://docs.stripe.com/api). -#### Content Structure +### Content structure Help topics are structured like this: -* Component - * Subcomponent (or Part) +* Toolkit + * Subsystem (or Part) * Task (a brief sentence phrased as an imperative) For example: @@ -42,7 +44,7 @@ For example: > Note: We might want to group tasks into scenarios; this will become clear as documentation evolves. -### Help Topic Checklist +## Help topic checklist Each page in the internal documentation here is intended for platform administrators and developers. @@ -55,72 +57,84 @@ In both places we should follow the same general principles. Here is a checklist * [ ] The content can include screen captures and/or videos. This is optional, and can be very useful when it eliminates a lot of text that would otherwise need to be written. * [ ] The content includes links that cross-reference to related documentation, where applicable. * [ ] The content does not include any personal information (e.g., email addresses, phone numbers). -* [ ] If a developer changes a part of the system related to the help topic, then anyone (business or technical) can follow the steps to confirm the system’s behaviour is not broken by the change. In other words, the content for the help topic can serve as a test case and as a feature description . +* [ ] If a developer changes a part of the system related to the help topic, then anyone (business or technical) can follow the steps to confirm the system’s behaviour is not broken by the change. In other words, the content for the help topic can serve as a test case and as a feature description. * [ ] The URL for a help topic is readable and SEO-friendly. (This applies to external documentation only.) -### Components (Toolkits) = Apps (or Features), Plugins, and Utilities +## Toolkits = Domains, Plugins, Utilities, and Shells -Each component is a subsystem within the platform. (Technical software architecture documentation often uses the term “module” for this concept. Shift iQ is a modular platform.) Each component contains one or more subcomponents (or parts), and each subcomponent relates to one or more domain entities. +Each toolkit is a subsystem within the platform. (Technical software architecture documentation often uses the term “module” for this concept. Shift iQ is a modular platform.) Each toolkit contains one or more subsystems, and each subsystem relates to one or more domain entities. -> For example, the Contact component contains subcomponents such as Groups, People, and Memberships. Within the Groups subcomponent are specific domain entities such as Group, GroupAddress, and GroupSetting. +> For example, the Contact toolkit contains subsystems such as Groups, People, and Memberships. Within the Groups subsystem are specific domain entities such as Group, GroupAddress, and GroupSetting. > -> As another example, the Security component contains a Users subcomponent, which contains entities for individual user accounts, connections between users, login failures, and authenticated user sessions. +> As another example, the Security toolkit contains a Users subsystem, which contains entities for individual user accounts, connections between users, login failures, and authenticated user sessions. Shift iQ contains: -* **17 Feature Components** -* **2 Plugin Components** -* **4 Utility Components** +* **12 Domain Toolkits** +* **2 Plugin Toolkits** +* **7 Utility Toolkits** +* **3 Shell Toolkits** -
+### Domains -#### Features (Apps) +**Domains** (aka Features or Apps) deliver end-user features to learners, instructors, and administrators. -**Features** deliver end-user features to learners, instructors, and administrators. +1. Billing +2. Booking +3. Competency +4. Content +5. Directory +6. Evaluation +7. Learning +8. Messaging +9. Progress +10. Reporting +11. Workflow +12. Workspace -1. Achievement -2. Assessment -3. Billing -4. Calendar -5. Contact -6. Content -7. Course -8. Gradebook -9. Job -10. Location -11. Logbook -12. Message -13. Report -14. Site -15. Standard -16. Survey -17. Workflow - -#### Plugins +### Plugins **Plugins** implement integration with external third-party platforms and customizations for specific partitions (or tenants) and organizations. 1. Integration -2. Variant +2. Extension -#### Utilities +### Utilities **Utilities** are intended for internal use by platform administrators and developers for system setup, instrumentation, and telemetry. Some limited access may be granted to some customers. -1. Metadata (platform and database structure) -2. Security (accounts and permissions) -3. Setup -4. Timeline (CQRS+ES backbone and service bus) +1. Diagnostic +2. Internal +3. Lab +4. Metadata (platform and database structure) +5. Security (accounts and permissions) +6. Setup (configuration) +7. Timeline (CQRS+ES backbone and service bus) + +### Shells + +**Shells** are responsible for composition of front-end and back-end features from multiple subsystems to deliver unified, session-aware views for client applications. They act as a bridge between domain-specific subsystems and the user interface, assembling contextual models such as user session state, dashboard metadata, and cross-subsystem summaries. Shells are not responsible for business logic or data ownership, but instead coordinate and shape data from underlying services to support runtime experience delivery, particularly for dynamic front-end rendering and role-based navigation. + +1. Lobby +2. Me +3. Portal (orchestration) -#### Component Aliases +### Toolkit aliases For technical reasons, the following names have aliases: -* Calendar also known as Events and/or Schedule +* Billing also known as Invoices and/or Payments and/or Sales +* Booking also known as Calendar and/or Events and/or Schedule * Cases also known as Issues +* Competency also known as Standards * Content also known as Assets +* Directory also known as Contacts * Learning also known as Courses +* Messaging also known as Messages +* Progress also known as Records * Timeline also known as Logs and/or Bus * Note: Commands, queries, and changes (aka events) are parts of the service bus implementation +* Workflow also known as Surveys +* Workspace also known as Sites and/or Pages In a future release, it may become worthwhile to consider a stricter alignment between the business (UI) and technical (API) lexicons for the platform. diff --git a/contributors/getting-started/components/utility-components/metadata.md b/contributors/toolkits/metadata.md similarity index 60% rename from contributors/getting-started/components/utility-components/metadata.md rename to contributors/toolkits/metadata.md index 30807c2..818825b 100644 --- a/contributors/getting-started/components/utility-components/metadata.md +++ b/contributors/toolkits/metadata.md @@ -1,12 +1,16 @@ +--- +description: "Execute these 3 scripts to setup ASP.NET session state. They are located in the InSite repository under:" +--- + # Metadata ## Database Setup ### One-Time Initial Setup -Execute these 3 scripts to setup ASP.NET session state: +Execute these 3 scripts to setup ASP.NET session state. They are located in the InSite repository under: -* `C:\\Base\\Repos\\InSite\\Infrastructure\\Scripts\\Database\\Session State` +* `\Infrastructure\Scripts\Database\Session State` 1. `Setup-SessionState-1.sql` is executed in SQL Server Management Studio 2. `Setup-SessionState-2.ps1` is executed on a PowerShell command prompt @@ -16,9 +20,9 @@ Using SQL Server Management Studio create a new login named `IIS APPPOOL\\InSite ### Restore Database Backup -An anonymized backup copy of the database is located here: +An anonymized backup copy of the database is located in your local backups folder, for example: -* C:\Base\Data\Databases\Backups\Local.bak +* `\Local.bak` You can use Microsoft SQL Server Management Studio to restore the database. @@ -28,17 +32,23 @@ Alternatively, you can execute a script from PowerShell or from a Windows comman Note: If you have already added the PowerShell profile from Local Skip this part. -#### PowerShell Command Prompt (Dan) +#### PowerShell setup -Edit your PowerShell profile so it includes an alias for the InSite Maintenance console application, and so it includes functions to restore the database from a backup, switch between master and develop databases, execute SQL upgrade scripts. +Edit your PowerShell profile so it includes an alias for the InSite Maintenance console application, plus functions to restore the database from a backup, switch between master and develop databases, and execute SQL upgrade scripts. -``` -Set-Alias -Value "C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\bin\\Debug\\InSite.Maintenance.exe" -Name "insite" +Substitute `` and `` for the absolute paths on your machine. + +```powershell +$MaintenanceExe = "\Code\Apps\Source\InSite.Maintenance\bin\Debug\InSite.Maintenance.exe" +$UpgradeScripts = "\Code\Apps\Source\InSite.Maintenance\Scripts\Upgrades" +$BackupsFolder = "" -function Sql-Restore { insite restore-databases -b C:\\Base\\Data\\Databases\\Backups } +Set-Alias -Value $MaintenanceExe -Name "insite" + +function Sql-Restore { insite restore-databases -b $BackupsFolder } function Sql-Switch { insite switch-databases } -function Sql-Mark { insite mark-scripts -p C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\Scripts\\Upgrades } -function Sql-Upgrade { insite upgrade-scripts -p C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\Scripts\\Upgrades } +function Sql-Mark { insite mark-scripts -p $UpgradeScripts } +function Sql-Upgrade { insite upgrade-scripts -p $UpgradeScripts } ``` From a PowerShell command prompt, you can restore two copies of the SQL Server database backup file with this command: @@ -49,40 +59,42 @@ To switch between **master** and **develop** copies of the database: * `Sql-Switch` -#### Windows Command Prompt (Aleksey) +#### Windows command-prompt setup -1. Create four CMD files: - * Upgrade.cmd. This command should be used to run SQL upgrade scripts - * Mark.cmd. This command should be used to mark SQL upgrade scripts as executed in case the script file(s) already was applied during development. - * Switch.cmd. Switch from one environment to another, for example, from **dev** to **hotfix**. - * Restore.cmd. Restore the database backup. -2. Example of **Upgrade.cmd** +If you prefer the Windows command prompt over PowerShell, create four CMD files. In each one, substitute `` and `` for the absolute paths on your machine. -``` -C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\bin\\Debug\\InSite.Maintenance.exe upgrade-scripts -p D:\\Projects\\InSite\\Repos\\Code\\Apps\\Source\\InSite.Maintenance\\Scripts\\Upgrades +1. Create four CMD files: + * **Upgrade.cmd** — runs SQL upgrade scripts. + * **Mark.cmd** — marks SQL upgrade scripts as executed (use when the script file was already applied during development). + * **Switch.cmd** — switches from one environment to another (for example, **dev** to **hotfix**). + * **Restore.cmd** — restores the database backup. +2. Example of **Upgrade.cmd**: + +```cmd +"\Code\Apps\Source\InSite.Maintenance\bin\Debug\InSite.Maintenance.exe" upgrade-scripts -p "\Code\Apps\Source\InSite.Maintenance\Scripts\Upgrades" pause ``` -Where **-p** specifies where upgrade scripts located +Where **-p** specifies the folder that contains the upgrade scripts. -1. Example of **Mark.cmd** +1. Example of **Mark.cmd**: -``` -C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\bin\\Debug\\InSite.Maintenance.exe mark-scripts -p C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\Scripts\\Upgrades +```cmd +"\Code\Apps\Source\InSite.Maintenance\bin\Debug\InSite.Maintenance.exe" mark-scripts -p "\Code\Apps\Source\InSite.Maintenance\Scripts\Upgrades" pause ``` -1. Example of **Switch.cmd** +1. Example of **Switch.cmd**: -``` -C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\bin\\Debug\\InSite.Maintenance.exe switch-databases +```cmd +"\Code\Apps\Source\InSite.Maintenance\bin\Debug\InSite.Maintenance.exe" switch-databases pause ``` -1. Example of **Restore.cmd** +1. Example of **Restore.cmd**: -``` -C:\\Base\\Repos\\InSite\\Code\\Apps\\Source\\InSite.Maintenance\\bin\\Debug\\InSite.Maintenance.exe restore-databases -b C:\\Base\\Data\\Databases\\Backups +```cmd +"\Code\Apps\Source\InSite.Maintenance\bin\Debug\InSite.Maintenance.exe" restore-databases -b "" pause ``` @@ -96,7 +108,7 @@ You can add parameter **-c true** so that the utility restores the database only 3. Make sure `InSite_develop` is your default database. 4. Open a new Query in SQL Server Management Studio and run below scripts. -``` +```text USE master; GO EXEC sp_configure 'clr enabled' ,1 @@ -115,7 +127,7 @@ GO 1. Run **Sql-Upgrade** or **Upgrade.cmd** to apply all the latest upgrade scripts. 2. Run below queries to create a default user. -``` +```text use InSite go @@ -153,9 +165,9 @@ For this purpose run **Sql-Mark** #### Scenario 3. -Dan just provided the latest backups and I need to restore them. +The infrastructure team just provided the latest backups and I need to restore them. -For this purpose run **Sql-Restore** +For this purpose run **Sql-Restore**. #### Scenario 4. diff --git a/contributors/toolkits/records/README.md b/contributors/toolkits/records/README.md new file mode 100644 index 0000000..fb585ac --- /dev/null +++ b/contributors/toolkits/records/README.md @@ -0,0 +1,7 @@ +--- +description: The list of typical achievement types supported by the Records toolkit +--- + +# Records + +Here is the list of typical achievement types: Achievement, Assessment, Assignment, Award, Badge, Certificate, Certification, Course, Community Service, Competency, Co-Curricular, Degree, Diploma, Fieldwork, License, and Membership. diff --git a/contributors/toolkits/records/certificate-layouts/README.md b/contributors/toolkits/records/certificate-layouts/README.md new file mode 100644 index 0000000..c76a133 --- /dev/null +++ b/contributors/toolkits/records/certificate-layouts/README.md @@ -0,0 +1,14 @@ +--- +description: >- + How to achieve a custom full certificate background from one file, and the + prerequisites for doing so +--- + +# Certificate layouts + +In order to achieve a custom full certificate background from one file we need to proceed with some steps in the production environment (or any other environment). + +**Prerequisites** + +* We need to have access/permissions to global tenant +* We need to have access/permissions to desired tenant diff --git a/contributors/toolkits/records/certificate-layouts/adding-certificatelayouts-to-achievements.md b/contributors/toolkits/records/certificate-layouts/adding-certificatelayouts-to-achievements.md new file mode 100644 index 0000000..79a36b7 --- /dev/null +++ b/contributors/toolkits/records/certificate-layouts/adding-certificatelayouts-to-achievements.md @@ -0,0 +1,24 @@ +--- +description: >- + End-to-end setup for providing users a downloadable certificate on course + completion, from template upload to gradebook hooks +--- + +# Adding CertificateLayouts to Achievements + +If a tenant wants to provide users with a downloadable certificate upon completion of a course, here is how that is set up: + +1. Have Dev create the fillable certificate template from a tenant-supplied png or from our own templates (not sure how dev does this, but Dan did it for CPTBC's 2022 ASR Certificate). +2. Upload the .png file to [https://global.insite.com/admin/assets/files/browse](https://global.insite.com/admin/assets/files/browse), **tenant folder/images/certificates.** (Create the folders if needed, see pic below.) +3. Have Dev insert a config record in the **CredentialLayout** table in the database pointed to the uploaded template. (Future update: UI for the CredentialLayout table so dev not needed for this step.) +4. Create an achievement in **Records/Achievement Setup**, edit it to add the new certificate under **Credential Layout**, and make note of the achievement's unique identifier for step 6 if this will be linked to a v1 course lesson. +5. Create or edit a **gradebook** to link the achievement to the whole book (v2 courses only?) or a grade item (v1 or v2 courses). Separate grade items in the gradebook can have separate achievements too, if desired. +6. Hook the gradebook item to the desired course asset using the **Hook/Integration Code** feature. Most v1 courses also have a final "Print your certificate" lesson of some kind with a link for the user to download their certificate. Suggested body content for this lesson is: + + `` **** Click to here to access your certificate: `XYZ CertificateAdding certificatelayouts to achievements 01
diff --git a/contributors/toolkits/records/certificate-layouts/global-tenant-file-upload.md b/contributors/toolkits/records/certificate-layouts/global-tenant-file-upload.md new file mode 100644 index 0000000..fc0d0b9 --- /dev/null +++ b/contributors/toolkits/records/certificate-layouts/global-tenant-file-upload.md @@ -0,0 +1,37 @@ +--- +description: >- + How to upload a new certificate layout background image using the global + tenant, and verify it on the server +--- + +# Global tenant file upload + +First of all wee need to upload our new Certificate Layout using global tenant to this location: + +[https://e02.insite.com/ui/admin/assets/files/browse](https://global.insite.com/ui/admin/assets/files/browse) + +Select Library → Tenants → \[desired tenant code] → Images (if not existing please create) → Certificates (if not existing please create) + +Example for IECBC tenant + +
Global tenant file upload 01
+ +Example for COTBC tenant + +
Global tenant file upload 02
+ +We upload our desired background certificate layout in that location: + +Example with COTBC tenant + +
Global tenant file upload 03
+ +To check if the background image is properly uploaded we follow this URL: + +**https://\-\.insite.com/library/tenants/\/images/certificates/\.\** + +**Example COTBC:** [https://sandbox-cotbc.insite.com/library/tenants/cotbc/images/certificates/NCOT202022.png](https://sandbox-cotbc.insite.com/library/tenants/cotbc/images/certificates/NCOT202022.png) + +***For best practices it is best to avoid special characters and space bars in file naming*** + +Once we are sure that the the image is correctly uploaded to the server we need to Configure Directly on the tenant admin page one more thing in the Admin Record pages. diff --git a/contributors/toolkits/records/certificate-layouts/how-to-configure-a-new-certificate-layout.md b/contributors/toolkits/records/certificate-layouts/how-to-configure-a-new-certificate-layout.md new file mode 100644 index 0000000..64401c7 --- /dev/null +++ b/contributors/toolkits/records/certificate-layouts/how-to-configure-a-new-certificate-layout.md @@ -0,0 +1,135 @@ +--- +description: >- + Step-by-step guide to creating a new certificate layout, including the JSON + configuration and how to link it to an achievement +--- + +# How to configure a new certificate layout + +Under our desired Tenant go to Records → Certificate Layouts + +
How to configure a new certificate layout 01
+ +If you want to edit a layout then select a layout code, but if you want to create completely new layout then we should select '**Add New Certificate Layout**'. It looks scary but it is not. + +
How to configure a new certificate layout 02
+ +Write the JSON for your new certificate. You need these properties: type, background, elements. + +**Example of JSON Data:** + +```json +{ + "type": "custom", + "title": "2022 National Competencies for OTs in Canada", + "background": "/library/tenants/cotbc/images/certificates/NCOT2022.png", + "elements": [ + { + "type": "text", + "value": "{User.Name}", + "h_align": "Center", + "font": { + "name": "Helvetica", + "style": "Bold", + "size": 90, + "color": "Black" + }, + "layout": { + "x": 0.2, + "y": 0.47, + "width": 0.60742, + "height": 0.08227 + } + }, + { + "type": "text", + "value": "on {Assignment.CompletedOn:MMMM d, yyyy}", + "h_align": "Left", + "font": { + "name": "Calibri", + "size": 80, + "color": "Black" + }, + "layout": { + "x": 0.43, + "y": 0.74, + "width": 0.644, + "height": 0.129 + } + } + ], + "Variables": { + "Assignment.CompletedOn": "Jan 1, 2000", + "User.Name": "Test Learner" + } +} +``` + +**JSON Configuration explanation:** + +**Type:** "custom" - so that the system knows we are dealing with custom layout and we will assign values like user full name or date. + +**Title:** Add the "title" of our custom Certificate layout + +**Background:** Add the URL for our certificate "background" E.g. `/library/tenants/cotbc/images/certificates/NCOT2022.png` - always check if the image of the URL is correct + +**Elements:** - here is a bit complicated structure so the best thing is to copy paste it all together and just change desired values: + +```json +{ + "type": "text", + "value": "{User.Name}", + "h_align": "Center", + "font": { + "name": "Helvetica", + "style": "Bold", + "size": 90, + "color": "Black" + }, + "layout": { + "x": 0.2, + "y": 0.47, + "width": 0.60742, + "height": 0.08227 + } + }, +``` + +First part/section of elements as we is is of type text and it's value will be user name - it will be pulled directly out from our system. We se that the alignment will be center. We can specify the font face like Arial or Helvetica, font style for example Italic, Bold, Normal. The layout section will describe the x and y position on the generated certificate. This is a bit of test and see type of situation. change values and generate sampled certificate to see it the alignment is correct. + +```json +{ + "type": "text", + "value": "on {Assignment.CompletedOn:MMMM d, yyyy}", + "h_align": "Left", + "font": { + "name": "Calibri", + "size": 80, + "color": "Black" + }, + "layout": { + "x": 0.43, + "y": 0.74, + "width": 0.644, + "height": 0.129 + } + } +``` + +Second part is about time of completion. The structure is exactly the same as the first part. Here we just describe the date time element value font size face and position. If we want to add additional values we need to confirm with dev team what other values can we present on Certificate layout. + +
How to configure a new certificate layout 03
+ +**Insert a new record in the Certificate Layout table (achievements.TCredentialLayout) - deprecated** + +Edit the Achievement in the Records toolkit, and select the new Certificate Layout. + +After we successfully added our new Certificate Layout we should be able to edit our desired Achievement Template with a Drop Down selection + +
How to configure a new certificate layout 04
+ +The URL in the Portal to view your certificate for a achievement looks like this: + +**/ui/portal/records/credentials/certificate?achievement=f44dbb20-6916-4733-be3d-ae9900eb1b0f\&type=html** + +Notice the GUID is the Identifier for the Achievement Setup in the Records toolkit. diff --git a/contributors/toolkits/records/certificate-layouts/infrastructure-notes-developers-only.md b/contributors/toolkits/records/certificate-layouts/infrastructure-notes-developers-only.md new file mode 100644 index 0000000..0cbc89f --- /dev/null +++ b/contributors/toolkits/records/certificate-layouts/infrastructure-notes-developers-only.md @@ -0,0 +1,32 @@ +--- +description: >- + Developer setup for the Microsoft SSRS certificate-generation utility, plus + proposed improvements to the certificate workflow +--- + +# Infrastructure notes - developers only + +If you are working in your local environment then you need to pull the "Microsoft SSRS" repo from GitHub, and configure the web application in your local IIS. + +The Microsoft SSRS web application is a lightweight utility that is responsible for generating certificate output files (PDF and PNG). + +* Site Name = Microsoft SSRS +* Host Name = [local-ssrs.insite.com](http://local-ssrs.insite.com/) +* Port 443 +* Physical Path = D:\Base\Repos\InSite\Microsoft.SSRS\Source + +You can test with this URL: + +* [https://local-ssrs.insite.com/certificates/certificatetest.aspx](https://local-ssrs.insite.com/certificates/certificatetest.aspx) + +## Proposed Improvements + +The following code and database changes are recommended to simplify the process for adding new certificates, and to decrease the need for developer intervention: + +1. Rename the table from "achievements.TCredentialLayout" to "records.TCertificateLayout". +2. Implement web forms to search/create/edit/delete rows in the database table where certificate layouts are stored. +3. Eliminate the need for an administrator to remember the syntax for the Portal page URL where a user views and downloads the certificate associated with a v1 Course Activity. + * admin/courses/resources/edit + * Remove the Certificate tab from the Content panel + * Add to the Settings tab (in the Course panel) a new field "Certificate Layout", with a drop-down list that allows you to select a Certificate Layout + * Modify the v1 Course Outline page in the Portal so that when you click the Action button for a Certificate asset, it navigates to the page /ui/portal/records/credentials/certificate diff --git a/contributors/toolkits/reports/README.md b/contributors/toolkits/reports/README.md new file mode 100644 index 0000000..b9fd7e0 --- /dev/null +++ b/contributors/toolkits/reports/README.md @@ -0,0 +1,15 @@ +--- +description: >- + How the Reports toolkit exposes platform data through monitors, queries, and + report types +--- + +# Reports + +The Reports toolkit is the read-side surface for platform data. It packages saved queries and presentation rules so administrators can answer operational questions without writing SQL. + +This section covers: + +* [Monitors](monitors.md) — long-running watches that surface anomalies and threshold breaches. +* [Queries](queries.md) — saved parameterized queries that back the reports. +* [Report types](report-types.md) — the catalog of report shapes available to administrators. diff --git a/contributors/toolkits/reports/monitors.md b/contributors/toolkits/reports/monitors.md new file mode 100644 index 0000000..96ee457 --- /dev/null +++ b/contributors/toolkits/reports/monitors.md @@ -0,0 +1,19 @@ +--- +description: >- + Summary of the tools and techniques used to monitor the health of the Shift + iQ platform +--- + +# Monitors + +Here is a summary of the tools and techniques used to monitor the health of the Shift iQ platform: + +* [UptimeRobot](https://status.shiftiq.com) monitors uptime 24x7x365. +* [Sentry](https://insite-systems.sentry.io) monitors errors and warnings, as well as overall application performance metrics. +* Microsoft IIS logs all incoming HTTP requests. +* [SmarterStats](https://stats.insite.com) analyzes IIS logs for comprehensive web traffic analytics. +* The InSite Timeline engine is a CQRS+ES implementation that logs every change to every aggregate in the application domain. + +## SmarterStats + +Note the SmarterStats server requires a reset from time to time. (After Microsoft Windows installs an update, it sometimes "forgets" to restart all the services in Windows, and a Windows admin needs to manually do that.) When a reset is needed, a server administrator on our end needs to do this. diff --git a/contributors/toolkits/reports/queries.md b/contributors/toolkits/reports/queries.md new file mode 100644 index 0000000..ef57fc5 --- /dev/null +++ b/contributors/toolkits/reports/queries.md @@ -0,0 +1,49 @@ +--- +description: How to run a dynamic SQL query from the admin reports area +--- + +# Queries + +## Dynamic SQL Query + +Go to: (depending on the environment): + +* [https://global.insite.com/admin/reports/queries/sql](https://global.insite.com/admin/reports/queries/sql) +* [https://sandbox-global.insite.com/admin/reports/queries/sql](https://sandbox-global.insite.com/admin/reports/queries/sql) +* [https://dev-global.insite.com/admin/reports/queries/sql](https://dev-global.insite.com/admin/reports/queries/sql) + +You should see something like this: + +
Queries 01
+ +In the large Text Area insert the SQL Code: + +
Queries 02
+ +And click Execute + +
Queries 03
+ +Results for the SQL Query will display in the Results panel. + +
Queries 04
+ +If you scroll right you will notice column names: + +
Queries 05
+ +To download the Query results, click on the **Download** button in the **Results** panel. + +### Example: Assessment Attempts + +```sql +select * from logs.Change where AggregateIdentifier = 'INSERT ASSESSMENT ATTEMPT UNIQUE IDENTIFIER' order by changetime desc +``` + +OR + +```sql +select * from logs.Change where AggregateIdentifier = 'INSERT ASSESSMENT ATTEMPT UNIQUE IDENTIFIER' +``` + +
Queries 06
diff --git a/contributors/toolkits/reports/report-types.md b/contributors/toolkits/reports/report-types.md new file mode 100644 index 0000000..d67ee44 --- /dev/null +++ b/contributors/toolkits/reports/report-types.md @@ -0,0 +1,25 @@ +--- +description: The types of reports available in the platform and their relative cost +--- + +# Report types + +**Last Search**. The system automatically stores the criteria for your "last search" on every search page. You can select your own Criteria to Filter the Results, select your own Columns for the Results (and the Download spreadsheet), and your "last search" is always loaded by the system whenever you revisit a search page. These reports are universal and free to customers. + +**Saved Search**. You can save your Criteria Filter and Column Download settings on every Admin Search page. These reports are also universal and free to customers. + +**Ad Hoc Report**. This is a report built by an administrator using the Ad Hoc Report Builder form. Input from a developer is needed only to add a requested table to the list of available tables for ad hoc reporting. This is done one time only, and is then available to all customers, making these reports free to all customers (immediately following the initial one-time setup). + +**Ad Hoc Query**. This is a SQL query copied and pasted into a query page that is accessible to InSite Admins only. The size and complexity of a typical report of this type is extra small. Put simply, this is a cheap, throwaway $5 report. + +**Saved Ad Hoc Query**. Each customer can have a library of saved Ad Hoc Query reports, which they can run themselves, on demand. These are $5 reports also. + +**Summary Report**. This is a panel on a page in the application designed to answer questions about the data through summaries of that data. A summary might be a table that displays counts per status, a time series graph, a frequency distribution chart, a pivot table with multiple row and column dimensions, or some other tabular or visual representation of summary data. Examples can be found throughout the Admin UI. + +**Custom Search**. As a general rule, Custom Search reports should be avoided, but the size and complexity here is still small. A typical search page needs about 4h of development time. + +**Scheduled Report**. Reports that are especially large and/or computation-intensive must be scheduled to run outside peak business hours. The size and complexity of a Scheduled Report can vary widely, therefore development effort varies widely, and might require anywhere from 5 minutes to 5 days, depending on the details. + +**SSRS**. This is a Microsoft SQL Server Reporting Services report. It might be developed for a specific customer, or it might be developed for the core InSite product. Currently, we have SSRS reports for NCSHA and Northern Mat only. + +**BI**. This is a Microsoft Power BI report. Microsoft BI is the next evolution of SSRS. We have some customers inquiring about this option; therefore, it is a topic for future research. Currently we have no BI reports. diff --git a/contributors/toolkits/security/README.md b/contributors/toolkits/security/README.md new file mode 100644 index 0000000..e192de8 --- /dev/null +++ b/contributors/toolkits/security/README.md @@ -0,0 +1,16 @@ +--- +description: >- + How the Security utility toolkit handles user accounts, permissions, + impersonations, and per-organization setup +--- + +# Security + +The Security toolkit owns identity and access for the platform: user accounts, roles, permissions, impersonations, and the organization-level configuration that wires these together. + +Use the pages in this section when you need to: + +* Provision a new organization or customize an existing one — see [Setting Up New Organizations](setting-up-new-organizations/README.md). +* Grant a staff member temporary access to another user's session — see [Impersonations](impersonations.md). +* Understand or audit which roles can do what — see [Permissions](permissions.md) and [Permissions (Proposed Improvement)](permissions-proposed-improvement.md). +* Trace how a user's organization membership controls visible data — see [Organization Collections](organization-collections.md). diff --git a/contributors/getting-started/components/utility-components/security/impersonations.md b/contributors/toolkits/security/impersonations.md similarity index 88% rename from contributors/getting-started/components/utility-components/security/impersonations.md rename to contributors/toolkits/security/impersonations.md index cdd4b50..0d57db3 100644 --- a/contributors/getting-started/components/utility-components/security/impersonations.md +++ b/contributors/toolkits/security/impersonations.md @@ -1,3 +1,9 @@ +--- +description: >- + How to grant and use the Impersonate permission so staff can act on behalf of + another user +--- + # Impersonations ### Adding Impersonate Permissions to an Organization @@ -11,10 +17,6 @@ On the **Admin Home Page**, select **Settings** Toolkit Select the **Actions** counter and under the Criteria tab search for **Action URL = impersonate**\ Click on the Action URL (**ui/portal/accounts/users/impersonate**) - - Under the **Permissions** tab, select **Add Permission** - - Select the **Group** within the **Organization** that you would like to give this permission to and select **Save** diff --git a/contributors/getting-started/components/utility-components/security/organization-collections.md b/contributors/toolkits/security/organization-collections.md similarity index 82% rename from contributors/getting-started/components/utility-components/security/organization-collections.md rename to contributors/toolkits/security/organization-collections.md index 4beca6e..c5f1e09 100644 --- a/contributors/getting-started/components/utility-components/security/organization-collections.md +++ b/contributors/toolkits/security/organization-collections.md @@ -1,3 +1,7 @@ +--- +description: Global admins can override the default Gender list in a users contact record and it can be added for a specific tenant if needed. +--- + # Organization Collections ### Define Custom Gender list @@ -26,13 +30,12 @@ When creating a New Document on the portal, there are 6 types of documents that * Occupation Profile * Skills Checklist -We are able to customize this list for Orginazations so they they only see the document types they are using. +We are able to customize this list for Organizations so they they only see the document types they are using. -In the **Accounts** Toolkit, open the **Orginazations** counter and search for the Orginaztation you would like to update the list for. +In the **Accounts** Toolkit, open the **Organizations** counter and search for the Organization you would like to update the list for. Under the **Collections** tab, select **Standards/Document/Type** from the dropdown menu below the **Collection** field. -Click on the Plus icon \ next to the Item field, this will create the text boxes where you can enter the document types required by the Orginazation. After adding the required documents, click **Save**. +Click on the Plus icon \ next to the Item field, this will create the text boxes where you can enter the document types required by the Organization. After adding the required documents, click **Save**. Only the documents you added to the **Standards/Document/Type** list will appear in the New Document field on the portal. - diff --git a/contributors/getting-started/components/utility-components/security/permissions-proposed-improvement.md b/contributors/toolkits/security/permissions-proposed-improvement.md similarity index 98% rename from contributors/getting-started/components/utility-components/security/permissions-proposed-improvement.md rename to contributors/toolkits/security/permissions-proposed-improvement.md index be1614f..9b69dc4 100644 --- a/contributors/getting-started/components/utility-components/security/permissions-proposed-improvement.md +++ b/contributors/toolkits/security/permissions-proposed-improvement.md @@ -1,3 +1,9 @@ +--- +description: >- + Design sketch for a more expressive permission model based on three explicit + attributes +--- + # Permissions (Proposed Improvement) ## Permission Overview diff --git a/contributors/getting-started/components/utility-components/security/permissions.md b/contributors/toolkits/security/permissions.md similarity index 77% rename from contributors/getting-started/components/utility-components/security/permissions.md rename to contributors/toolkits/security/permissions.md index 1490594..ab61175 100644 --- a/contributors/getting-started/components/utility-components/security/permissions.md +++ b/contributors/toolkits/security/permissions.md @@ -1,3 +1,9 @@ +--- +description: >- + How to check whether an identity user holds a specific TAction permission and + use the result to gate UI elements +--- + # Permissions #### ClaimType.Action Permissions @@ -14,7 +20,7 @@ Create Group: `contacts.Group entry` table > Best by SQL script -Add accounts to this Group, and insert ActionIdentifire with GroupIdentifire in: `contacts.TGroupAction` table +Add accounts to this Group, and insert ActionIdentifier with GroupIdentifier in: `contacts.TGroupAction` table After that you can simply check like this: diff --git a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/README.md b/contributors/toolkits/security/setting-up-new-organizations/README.md similarity index 93% rename from contributors/getting-started/components/utility-components/security/setting-up-new-organizations/README.md rename to contributors/toolkits/security/setting-up-new-organizations/README.md index 14620cc..e6c9bbc 100644 --- a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/README.md +++ b/contributors/toolkits/security/setting-up-new-organizations/README.md @@ -1,3 +1,9 @@ +--- +description: >- + End-to-end checklist for provisioning a new customer organization in Jira, + Microsoft Teams, and Shift iQ +--- + # Setting Up New Organizations ### New Account Setup in Jira @@ -36,7 +42,7 @@ * Automatically grant Portal (learner) access to self-registered users - select if account doesn’t want to review self-registered new user accounts before they have access to a portal (if selected, ensure account is configured to give something to new users, not just a blank portal; if unselected, ensure account has the **AccessRequested** alert configured) * Settings card can be ignored * - * **Advanced** subtab, see [Advanced configuration](../../../../../components/utility-components/security/setting-up-new-organizations/broken-reference/) topic + * **Advanced** subtab, see [Organization Specific Settings (Advanced Configuration)](organization-specific-settings-advanced-configuration.md) topic * Configuration for desired New User Journey * * Do they want the New Users tab visible or not diff --git a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/existing-organization-customization.md b/contributors/toolkits/security/setting-up-new-organizations/existing-organization-customization.md similarity index 92% rename from contributors/getting-started/components/utility-components/security/setting-up-new-organizations/existing-organization-customization.md rename to contributors/toolkits/security/setting-up-new-organizations/existing-organization-customization.md index 8325244..d46688a 100644 --- a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/existing-organization-customization.md +++ b/contributors/toolkits/security/setting-up-new-organizations/existing-organization-customization.md @@ -1,3 +1,9 @@ +--- +description: >- + Per-organization customizations that exist outside the standard configuration + options, grouped by toolkit +--- + # Existing Organization Customization | **Organization** | **Toolkit** | **Customization and how it works** | diff --git a/contributors/toolkits/security/setting-up-new-organizations/general-system-alerts-and-what-they-are-used-for.md b/contributors/toolkits/security/setting-up-new-organizations/general-system-alerts-and-what-they-are-used-for.md new file mode 100644 index 0000000..ff709a8 --- /dev/null +++ b/contributors/toolkits/security/setting-up-new-organizations/general-system-alerts-and-what-they-are-used-for.md @@ -0,0 +1,47 @@ +--- +description: >- + Reference for the general system alerts sent by the platform, who receives + them, their purpose, and the variables each one supports +--- + +# General system alerts and what they are used for + +## System Alerts that go to all Users + +These Alerts are sent by the system to all users, regardless if they are added to a specific customer's Message Alerts or not. In the case of the UserAccountWelcomed alert, it's a good idea to add this to each new Org so they can customize it to their branding and workflows. + +**Note:** Once any of our Message templates has been added to a customer's account as an alert, it can no longer be duplicated or used as a notification. + +| **Alert Information** | **Purpose and Notes** | **Variables that work with it** | +| --- | --- | --- | +| **UserAccountWelcomed**
Default Subject: User Account Approved - Welcome!
Goes to: Users | This notification is sent to a user when an admin grants them access to the platform. It can also be sent manually to the user at any time. (It isn't sent to users who are granted access when they create their own accounts.) | FirstName, Email, CompanyTitle, SignInUrl, PasswordInstruction, PasswordInstruction:en, PasswordInstruction:fr, Password | +| **UserAccountCreated**
Default Subject: User Account Registered
Goes to: User | This notification is sent to any user who self-registers for a new account, confirming receipt of the registration information. | Name, Email, Phone, City, Province, CompanyTitle | +| **UserRegistrationSubmitted**
Default Subject: Account Created
Goes to: Subscribers | This notification is sent to admin subscribers after a new user account is created by another administrator. | ApprovalUrl, City, Email, FirstName, LastName, Name, Organization, Phone, Province, RegistrationUrl, Thumbprint | +| **UserOTPActivationCode**
Default Subject: Your verification code from InSite
Goes to: User | This alert is sent to any user who has multi-factor authentication enabled and is logging in, and it includes a one-time use code. | ConfirmationCode, Organization | +| **UserEmailVerificationRequested**
Default Subject: Email Verification Requested
Goes to: User | This notification is sent to every user that self registers for their own account that is automatically granted access. | AppUrl, Organization, UserEmail, UserIdentifier, VerifyEmailUrl | +| **PasswordResetRequested**
Default Subject: Password Reset Requested
Goes to: User | This alert is sent to any user that requests a password reset. | ResetUrl | +| **PasswordChanged**
Default Subject: Password Changed
Goes to: User | This alert is sent to any user that changes their password. | UserEmail, EventTime, BrowserAddress | +| **ApplicationAccessGranted**
Default Subject: Application Access Granted
Goes to: User | This notification is sent to a user when access is granted to the platform after being requested. | ApproverEmail, ApproverName, Organization, UserAccess, UserFirstName | +| **UserEmailSubscriptionModified**
Default Subject: Mailing List Subscriptions Modified
Goes to: User | This notification is sent to any user who modifies their own mailing list group memberships. (Configured in each List group.) | RecipientName, RecipientMemberships | +| **UnsubscribeSuccess**
Default Subject: Successfully Unsubscribed
Goes to: User | This notification is sent to any user who unsubscribes themselves from all marketing emails from an organization. | UserEmail, Organization, ResubscribeUrl | + +## System Alerts that go to Admin Subscribers + +These alerts should be added to every new customer, with at least one of their admins as a subscriber. Also suggest updating the subject or contents to include text indicating it's coming from Shift iQ and why. + +| **Alert Information** | **Purpose and Notes** | **Variables that work with it** | +| --- | --- | --- | +| **HelpRequested**
Default Subject: Workflow Assignment - Help Requested
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a portal user completes the Shift iQ Support request form. (update Subject to: A Shift iQ user is requesting support) | BrowserAddress, BrowserName, Organization, RequestDescription, RequestSummary, RequestUrl, UserEmail, UserEmployer, UserName, UserPhone | +| **AuthenticationAlarmTriggered**
Default Subject: Authentication Failed (Brute-Force Login Attempt)
Goes to: Admin Subscribers | This alert is sent to admin subscribers when a user fails multiple attempts to sign in to the platform. | FailedLoginCount, Organization, SignInUrl, UserEmail, UserHostAddress | +| **ApplicationAccessRequested**
Default Subject: Application Access Requested
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a user requests access to the platform in the lobby. (If access has been removed from an existing user, they can ask for it back with this.) | AppUrl, Organization, SourceUrl, UserEmail, UserIdentifier, UserName
ApproveAccessUrl also works here, but isn't listed; this takes admins to the ui/admin/contacts/people/approve-access screen | + +## Other Available Alerts not currently being used by any customers + +| **Alert Information** | **Purpose and Notes** | **Variables that work with it** | +| --- | --- | --- | +| **PersonCommentFlagged**
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a flag is added to any comment on any contact record. | AuthorFirstName, AuthorLastName, AuthorEmail, TopicFirstName, TopicLastName, TopicEmail, CommentText | +| **EmployerGroupCreated**
Goes to: Admin Subscribers | This notification is sent to admin subscribers when an Employer group is created. | GroupName | +| **EventVenueChanged**
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a group is selected or changed as the venue for an event. | GroupIdentifier, GroupName, EventIdentifier, EventDate, EventName, EventNumber | +| **CredentialCreated**
Sent to: Users, if added to an org (ADD WITH CAUTION, once added, it can't be turned off and will send for every achievement) | This notification is sent to any user that is assigned or granted an achievement. | AchievementName, AchievementType, LearnerEmail, LearnerFirstName, LearnerIdentifier, LearnerLastName | +| **UserAccountCreated**
Goes to: Admin Subscribers | This notification is sent to admin subscribers after a new user account is created by another administrator. | Name, Email, Phone, City, Province, CompanyTitle | +| **IssueOwnerChanged**
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a case owner is assigned or changed on any case. | IssueNumber, IssueType, IssueStatus, IssueSummary, OwnerFirstName, OwnerLastName, OwnerEmail | diff --git a/contributors/toolkits/security/setting-up-new-organizations/granting-admin-permissions-to-roles.md b/contributors/toolkits/security/setting-up-new-organizations/granting-admin-permissions-to-roles.md new file mode 100644 index 0000000..a583aea --- /dev/null +++ b/contributors/toolkits/security/setting-up-new-organizations/granting-admin-permissions-to-roles.md @@ -0,0 +1,54 @@ +--- +description: >- + Admin toolkit permissions to grant to admin and design roles, including + permissions to grant with caution and route-level permissions +--- + +# Granting admin permissions to roles + +These Permissions are needed for general Admin toolkit access if the customer is using that toolkit: + +* Toolkits (must add for all admin and design roles) +* Admin/Assessments +* Admin/Assessments/Attempts (only if admins should see attempts) +* Admin/Assessment/Quizzes (for typing speed and data entry quiz access) +* Admin/Contacts +* Admin/Courses +* Admin/Events +* Admin/Events/Classes (must add if giving access to Events) +* Admin/Invoices (sales toolkit, all but Payments tile) +* Admin/Jobs +* Admin/Messages +* Admin/Payments (visibility of Payments tile in sales toolkit) +* Admin/Records +* Admin/Records/Achievements (must add to allow admins to work with Achievements) +* Admin/Reports +* Admin/Sites +* Admin/Standards +* Admin/Surveys +* Admin/Surveys/Responses (must add to allow admins to see respondent names for non-confidential responses, except for COTBC and CPTBC) +* Admin/Workflow +* Impersonate (only if admins should be able to impersonate other users) + +These Permissions should be granted with caution, and only when needed (most are already available to Operators, so don't need to be added even to Platform Admin groups): + +* Admin/Assets - for glossary and labels access +* Admin/Assets/Uploads - for uploads card access +* Admin/Assets/Contents – for Contents tile visibility, not sure what this really does +* Admin/Surveys/Responses/Change (only if admins should be allowed to edit survey responses, currently only NCSHA doing this) +* Admin/Events/Exams – only for STBC use +* Admin/Accounts – operators can access Accounts on Utilities dropdown +* Admin/Settings – operators can access Setup on Utilities dropdown +* Admin/Integrations – operators can access Integrations on Utilities dropdown, if an org needs access, use a custom tile to get admins to ui/admin/integrations/api-requests/search and then give them permissions on the two forms as per below. +* Admin/Testers - controls visibility of 2 additional tiles on Integrations card, mostly for STBC support +* Admin/Polaris – only for Insite website editors, being moved elsewhere so will be obsolete + +In addition, there are these, where permission can be given directly to a role by editing the route itself from /ui/admin/platform/routes/search (it can't be granted using the Grant Permission button in the Group): + +* admin/records/gradebooks/outline/create-scores – visibility of Create Scores button in gradebook +* ui/admin/assessments/attempts/grade - not sure what this controls but Inspire graders have been added to this in e06 +* admin/assessments/attempts/grade/regrade – visibility of the Regrade button on attempts with manually graded questions +* ui/admin/contacts/people/edit/socialinsurancenumber – shows SIN field unmasked +* ui/admin/contacts/people/upload/update – allows admins to update existing contacts using the upload contacts form; without it they can only add new contacts (grant with caution, one customer used this to change a bunch of their contacts to first name = F and last name = L) +* ui/admin/integrations/api-requests/search and ui/admin/integrations/api-requests/outline – for admins that need to search and view their API calls, create custom admin tile as well +* ui/admin/messages/emails/search – visibility of Emails tile on Messages home screen diff --git a/contributors/toolkits/security/setting-up-new-organizations/granting-portal-or-design-permission-to-roles.md b/contributors/toolkits/security/setting-up-new-organizations/granting-portal-or-design-permission-to-roles.md new file mode 100644 index 0000000..b549d5c --- /dev/null +++ b/contributors/toolkits/security/setting-up-new-organizations/granting-portal-or-design-permission-to-roles.md @@ -0,0 +1,31 @@ +--- +description: >- + Portal and Design permissions to grant to roles, including which groups each + permission should be given to +--- + +# Granting portal or design permission to roles + +## Portal Permissions + +Note: Although "Portal" is a permission, it does not need to be granted to any role, as all users already have Portal access by default. The other Portal permissions do need to be granted to both Portal and Admin groups that want to access the specific functionality from the Portal side. (In other words, these prevent a portal user without permission from accessing the related action paths even if they have obtained the direct URL.) + +* Portal - not needed, all users already have access to subactions controlled by this permission +* Portal/Appointments - for any customer using Appointments in Events, allows portal users to search appointments off the Calendar, give to admin and portal calendar groups +* Portal/Classes - for any customer using Classes in Events, give to admin and registrant groups +* Portal/Contacts - for any customer using the portal contacts search screen; currently only Inspire and CAMLPR regulators +* Portal/Jobs - for any customer using Jobs, give to admin, candidate and employer groups + * Portal/Jobs/Candidates - give to admin and candidate groups + * Portal/Jobs/Employers - give to admin and employer groups +* Portal/Logbooks - give to admin, leaner and validator groups + +## Design Permissions + +These are meant to be restricted versions of our existing toolkits, for specific roles like Logbook validators, Attempt assessors, Gradebook instructors, and (soon) Content authors. Roles with these permissions see a custom view of the Admin home page, and can't navigate to other admin views. + +* Design/Attempts - not sure what this was intended for +* Design/Gradebooks - for Instructors to view their students in a class, and view/update their grades\ + Design/GradingAssessors - for assessment questions that require manual grading +* Design/Progressions - not sure what this was intended for +* Design/Users - not sure what this was intended for +* Design/Validators - for Logbook validators to review and validate logbook entries diff --git a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md b/contributors/toolkits/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md similarity index 97% rename from contributors/getting-started/components/utility-components/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md rename to contributors/toolkits/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md index c2e5421..266b0ac 100644 --- a/contributors/getting-started/components/utility-components/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md +++ b/contributors/toolkits/security/setting-up-new-organizations/organization-specific-settings-advanced-configuration.md @@ -1,9 +1,5 @@ # Organization Specific Settings (Advanced Configuration) - - - - * Assessments * LockPublishedQuestions (true/false) * DisableStrictQuestionCompetencySelection (true/false) @@ -38,16 +34,14 @@ [**Organization Specific Settings**](https://e02.insite.com/ui/admin/accounts/organizations/search) - - #### LockPublishedQuestions (true/false) -If this setting is set to "true" and Admin is not able to edit a question that has been published. The edit icon () will not be visisble. If setting is set to "false" then the edit icon () will be visible. +If this setting is set to "true" and Admin is not able to edit a question that has been published. The edit icon () will not be visible. If setting is set to "false" then the edit icon () will be visible. * **Page URL:** /ui/admin/assessments/banks/outline * **Page URL:** /ui/admin/assessments/forms/workshop -``` +```text "LockPublishedQuestions": false, ``` @@ -57,7 +51,7 @@ This setting allows Administrators to attach Competencies to a question that is * **Page URL:** /ui/admin/assessments/questions/change -``` +```text "DisableStrictQuestionCompetencySelection": true, ``` @@ -65,7 +59,7 @@ This setting allows Administrators to attach Competencies to a question that is * **Page URL:** /ui/admin/assessments/questions/change -``` +```text "EnableQuestionSubCompetencySelection": true, ``` @@ -77,7 +71,7 @@ If **AttemptGradingAssessor** is set to “**true**”, then a Group = Role for * **Page URL:** /ui/admin/assessments/attempts/reports/search -``` +```text "AttemptGradingAssessor": true, ``` @@ -91,7 +85,7 @@ When the Setting is Set to "False", all rubric scores are cleared when an attemp * **Page URL:** /ui/admin/assessments/attempts/grade -``` +```text "RubricReGradeKeepInitialScores": false, ``` @@ -105,7 +99,7 @@ When the setting is set to “true”, then Full Name and Person Code will be vi **Page URL:** /ui/admin/assessments/assessor/grade -``` +```text "ShowPersonNameToGradingAssessor": false ``` @@ -113,23 +107,15 @@ When the setting is set to “true”, then Full Name and Person Code will be vi [**Organization Specific Settings**](https://global.insite.com/ui/admin/accounts/organizations/search) - - #### OrganizationIndustry (Industry Specialist) * **Page URL:** /ui/admin/contacts/people/edit * Display Custom Fields card in users contact record - - * Display Jobs Access checkbox - - #### Full Name Policy - - The Full Name Policy allows Organizations to specify the pattern to be used for Full Names in Shift iQ * {First} {Last} @@ -139,7 +125,7 @@ The Full Name Policy allows Organizations to specify the pattern to be used for **Example:** -``` +```text "FullNamePolicy": "{First} {Middle} {Last}" ``` @@ -151,7 +137,7 @@ When **AutomaticGroupJoin** is set with a **Group Unique Identifier**, every con **Example:** -``` +```text "AutomaticGroupJoin": "0c57b958-d894-4ff1-be42-b0050009fc1f" ``` @@ -169,31 +155,23 @@ If the org wants to have their own terminology used instead of “Person Code” [**Organization Specific Settings**](https://global.insite.com/ui/admin/accounts/organizations/search) - - #### ShowUnapplicableSeats (true/false) Display all seats or only seats applicable to user during Class Registration. * **Page URL:** /ui/portal/events/classes/register - - #### DisableClassExams (true/false) -Dsiplay/Hide Assessment Form column and Exam Password +Display/Hide Assessment Form column and Exam Password * **Page URL:** /ui/admin/events/classes/outline - - #### AllowUsersRegisterEmployees (true/false) Display/Hide the Register Employees button -* **Page URL:** ui/protal/classes/outline - - +* **Page URL:** ui/portal/classes/outline #### AllowUserAccountCreationDuringRegistration (true/false) @@ -201,57 +179,41 @@ Display/Hide the Register New Employee link during class registration. * **Page URL:** /ui/portal/events/classes/register-employee - - #### CompanySelectionAndCreationDisabledDuringRegistration (true/false) Allow or Disallow the selection and creation of Employers during class registration. * **Page URL:** /ui/portal/events/classes/register - - #### AllowClassRegistrationFields (true/false) Turn on/off the Class Settings tab, so that administrators can set what fields should be visible/hidden and editable/non-editable during class registration. Each class can be customized. * **Page URL:** /ui/admin/events/classes/outline - - #### Class Registration Account Panel We are able to add/remove fields under the Accounts panel on the Class Registration page. -To add/remove fields, open the Organization settings and select the different fields under the Fileds and Class Registration tab. - - +To add/remove fields, open the Organization settings and select the different fields under the Fields and Class Registration tab. ### Portals [**Organization Specific Settings**](https://global.insite.com/ui/admin/accounts/organizations/search) - - #### ShowMyDashboard (true/false) * **Page URL:** /ui/portal/reports/dashboard/account-settings - - ### Surveys [**Organization Specific Settings**](https://global.insite.com/ui/admin/accounts/organizations/search) - - * **EnableUserConfidentiality (true/false)** * **Page URL:** /ui/admin/surveys/forms/outline * **LockUserConfidentiality (true/false)** * **Page URL:** /ui/admin/surveys/forms/outline - - ### Integrations [**Organization Specific Settings**](https://global.insite.com/ui/admin/accounts/organizations/search) @@ -260,7 +222,7 @@ To add/remove fields, open the Organization settings and select the different fi Sends Eligibility status of class registrants to Prometric. -``` +```text "Prometric": { "ClientCode": "ProgramID", "UserName": "UserName", @@ -268,47 +230,37 @@ Sends Eligibility status of class registrants to Prometric. }, ``` - - The ProgramID, UserName and Password needs to be provided to Shift iQ by Prometric or the Organization using Prometric. #### SCORM SCORM Cloud login credentials (**AppId** and **Secret Key**) can be found here: [https://app.cloud.scorm.com/sc/user/Apps](https://app.cloud.scorm.com/sc/user/Apps) -``` +```text "ScormCloud": { "UserName": "", "Password": "" } ``` - - ### Sign-In Page After the 25.1 release (February 19, 2025), the Google and Microsoft Sign-In buttons will be customizable per organization. **URL: /ui/lobby/signin** - - -``` +```text "SignIn": { "AllowGoogleSignIn": false, "AllowMicrosoftSignIn": false } ``` - - ### NCSHA In the fall, NCSHA will request that this setting is turned to true so their users can see the newly published reports. Shortly after Jan 1 of each year, change this setting back to FALSE so users can’t see the newly previous year. Also add the new year as a period early in the new year. - - -``` +```text "NCSHA": { "ShowLastYearToEveryone": false }, diff --git a/contributors/toolkits/security/setting-up-new-organizations/other-alerts-and-notifications-for-toolkits.md b/contributors/toolkits/security/setting-up-new-organizations/other-alerts-and-notifications-for-toolkits.md new file mode 100644 index 0000000..e68b92f --- /dev/null +++ b/contributors/toolkits/security/setting-up-new-organizations/other-alerts-and-notifications-for-toolkits.md @@ -0,0 +1,40 @@ +--- +description: >- + Reference for toolkit notifications and alerts, where each is configured, who + receives it, and the variables it supports +--- + +# Other alerts and notifications for toolkits + +**Notifications (must be added as a Notification, not as an Alert):** Configurable in each asset, can add multiple versions of the same notification if the customer wants different text or different admin subscribers for different assets. Use the new "BCC admin subscribers" option if adding Admin Subscribers to any notification or alert that goes to a Learner/User by default. + +| **Notification Information** | **Purpose and Notes** | **Variables that work with it** | +| --- | --- | --- | +| **AssessmentAttemptStarted**
Goes to: Admin Subscribers
Configured in each **form** | This notification is sent to admin subscribers when any learner starts any assessment attempt. | LearnerEmail, LearnerName, AssessmentFormName | +| **AssessmentAttemptCompleted**
Goes to: Admin Subscribers
Configured in each **form** | This notification is sent to admin subscribers when any learner completes any assessment attempt. | LearnerEmail, LearnerName, AssessmentFormName, AssessmentAttemptScore | +| **CourseStalled**
Goes to: Learners and/or Admin Subscribers, depending on how configured in course
Configured in each **course** | This notification is sent to a learner and/or admin subscribers when a learner hasn't made progress on a course for the specified time. | AppUrl, CourseName, CourseStarted, LearnerIdentifier, LearnerFirstName, LearnerLastName | +| **CourseCompleted**
Goes to: Learners and/or Admin Subscribers, depending on how configured in course
Configured in each **course** | This notification is sent to a learner and/or admin subscribers when a course is completed. | AppUrl, CourseName, CourseStarted, LearnerIdentifier, LearnerFirstName, LearnerLastName | +| **ResponseConfirmed**
Goes to: Survey respondents
Configured in each **survey** | This notification is sent to a survey respondent when they submit their survey response. | AppUrl, CurrentYear, OrganizationName, SurveyFormName, Tenant, UserEmail, UserFullName, UserIdentifier, UtcNow | +| **ResponseStarted**
Goes to: Admin subscribers
Configured in each **survey** | This notification is sent to admin subscribers when a survey response is started. | AppUrl, CurrentYear, OrganizationName, SurveyFormName, Tenant, UserEmail, UserFullName, UserIdentifier, UtcNow | +| **ResponseCompleted**
Goes to: Admin subscribers
Configured in each **survey** | This notification is sent to admin subscribers when a survey response is started. | AppUrl, CurrentYear, OrganizationName, SurveyFormName, Tenant, UserEmail, UserFullName, UserIdentifier, UtcNow | +| **ProgramStalled**
Goes to: Learners and/or Admin Subscribers
Configured in each **program** | This notification is sent to a learner and/or admin subscribers when a learner hasn't made progress on a program for the specified time. | LearnerFirstName, LearnerLastName, ProgramName, ProgramStarted | +| **ProgramCompleted**
Goes to: Learners and/or Admin Subscribers
Configured in each **program** | This notification is sent to a learner and/or admin subscribers when a program is completed. | LearnerFirstName, LearnerLastName, ProgramName, ProgramStarted | +| **ProgressCompleted**
Goes to: Admin subscribers
Configured in each **grade item** | This notification is sent to admin subscribers when a grade item is completed. | LearnerEmail, LearnerName, GradeItemName, GradeItemScore | +| **LogbookModified**
Goes to: Learner or Logbook Validators, depending on how configured in logbook
Configured in each **logbook** | This notification is sent to a learner and/or admin subscribers when a logbook entry is created or modified. | ActorName, ActorRole, AppUrl, LogbookTitle, LogbookUrl, ModificationType, OrganizationCode | +| **LogbookJoined**
Goes to: Learner by default
Configured in each **logbook** | This notification is sent to a learner when they are added to a logbook. | ActorName, AppUrl, LogbookTitle, LogbookUrl, ModificationType, OrganizationCode, OrganizationName | + +**Alerts** that are triggered by every instance of occurrence, **if customer is using that toolkit**, or in the case of Admin Subscriber ones, if added to customer's list of alerts with at least one subscriber: + +| **Alert Information** | **Purpose and Notes** | **Variables that work with it** | +| --- | --- | --- | +| **RegistrantContactInformationChanged**
Goes to: Admin Subscribers for every registration where contact info is changed | This notification is sent to admin subscribers when any contact information is updated during a class registration. | ContactLoginName, ContactEmail, EventName, ContactChangedFields | +| **PersonCodeNotEntered**
Goes to: Admin Subscribers if Person Code unknown box is checked during registration, even if it isn't required | This notification is sent to admin subscribers when a class registration was completed without a Person Code. | EventTitle, CandidateName, CandidateEmail, CandidatePhone, RegistrantEmail, RegistrantName, RegistrantPhone | +| **RegistrationInvitation**
Goes to: Registered By person for a waitlist spot, when an admin clicks the Send Invitation button on the waitlisted registration | This notification is sent to the person who requested a class waitlist spot when the Send Invitation button is clicked. | CandidateFullName, ClassTitle, RegistrationEndTime, ClassRegistrationLink, ClassStartTime, ClassAchievement | +| **RegistrationInvitationExpired**
Goes to: Registered By person when invite expires (~48 hours after it is sent + overnight expiry utility) or an admin manually marks the registration as "Invitation Declined" | This notification is sent to the person who requested a class waitlist spot when the registration invitation has expired or been marked as declined. | CandidateFirstName, CandidateLastName, CandidateEmail, ClassTitle, ClassRegistrationLink | +| **RegistrationComplete**
Goes to: Registered By and Registrant (if different) | This notification is sent to the person who completed a class registration and to the registrant as well, if different. | CandidateName, CandidateEmail, CandidateStreet1, CandidateCity, CandidateProvince, CandidatePostalCode, EmployerStatus, CandidateBirthdate, CandidateTradeworkerNumber, CandidateWorkBasedHoursToDate, CandidatePhone, CandidateIsEnglishFirstLanguage, EmergencyContactName, EmergencyContactPhone, EmergencyContactRelationship, EmployerName, EmployerContactName, EmployerContactPhone, EmployerContactEmail, EmployerStreet1, EmployerCity, EmployerProvince, EmployerPostalCode, InvoiceNumber, EventTitle, EventDate, EventTime, VenueName, VenueStreet1, VenueCity, VenueProvince, VenuePostalCode, SeatTitle, SeatPrice, RegistrantEmail, RegistrantName, RegistrantPhone, CandidateAuthenticationDetails, PersonCode | +| **AddedToWaitlist**
Goes to: Registered By for waitlist requests | This notification is sent to the person who completes any waitlist request for any class. | WaitlistedBy, CandidateFullName, CandidateEmail, ClassTitle, ClassStartTime, ClassAchievement, Employer, Organization | +| **ClassScheduled**
Goes to: SkillsCheck purchaser of online class products | This notification is sent to any user who purchases an online class product. (SkillsCheck only.) | CustomerEmail, CustomerFullName, ClassEventUrl, ClassEventName | +| **JobsCandidateAppliedForOpportunity**
Goes to: Admin Subscribers (NEEDS FIX: should go to jobs.TOpportunity.ApplicationEmail) | This notification is sent to admin subscribers when a Candidate applies for an opportunity. | JobPosition, CandidateFirstName, CandidateLastName, CandidatePhoneNumber, CandidateEmailAddress, CandidateUrl | +| **JobsCandidateContactRequested**
Goes to: Candidate when employer clicks on Connect button | This notification is sent to the Candidate when an Employer asks to be connected with them. | CompanyName, CandidateFirstName, CandidateLastName, EmployerName, EmailAddress, Message | +| **InvoicePaid**
Goes to: every User who completes any Bambora payment transaction | This notification is sent to any user who completes any payment transaction. | CustomerEmail, CustomerFullName, InvoiceAmount, InvoiceDrafted, InvoicePaid, InvoiceStatus, InvoiceSubmitted, InvoiceNumber | +| **IssueOwnerChanged**
Goes to: Admin Subscribers | This notification is sent to admin subscribers when a case owner is assigned or changed on any case. | IssueNumber, IssueType, IssueStatus, IssueSummary, OwnerFirstName, OwnerLastName, OwnerEmail | diff --git a/contributors/toolkits/setup/README.md b/contributors/toolkits/setup/README.md new file mode 100644 index 0000000..390d087 --- /dev/null +++ b/contributors/toolkits/setup/README.md @@ -0,0 +1,11 @@ +--- +description: Configuration values that vary by environment +--- + +# Setup + +The Setup utility holds configuration values that vary between environments — colours, branding, feature flags, and similar tenant-level switches. + +This section covers: + +* [Colours](colours.md) — the palette tokens consumed by the portal theme. diff --git a/contributors/getting-started/components/utility-components/setup/colours.md b/contributors/toolkits/setup/colours.md similarity index 88% rename from contributors/getting-started/components/utility-components/setup/colours.md rename to contributors/toolkits/setup/colours.md index 6513b56..6910a56 100644 --- a/contributors/getting-started/components/utility-components/setup/colours.md +++ b/contributors/toolkits/setup/colours.md @@ -1,3 +1,7 @@ +--- +description: "Here are the colour codes we use in our UI:" +--- + # Colours ### Bootstrap 5 @@ -27,4 +31,3 @@ Here are the colour codes for the Shift iQ brand: \#577786 ### Preview - diff --git a/contributors/toolkits/sites/README.md b/contributors/toolkits/sites/README.md new file mode 100644 index 0000000..39269d4 --- /dev/null +++ b/contributors/toolkits/sites/README.md @@ -0,0 +1,27 @@ +--- +description: How to customize the support page and use wallpaper images in the Sites toolkit +--- + +# Sites + +## Support Page + +Here are the steps to customize the text on the support page: + +1. Open the **Sites** toolkit and select the **Sites** counter. +2. Select the **Title** for the **Portal**. +3. Create a new **Page**, under the **Root**, called **Support Page**. +4. Under the **Page Setup** tab, rename the **Page Slug (URL Segment)** to **support**. + +To Customize the summary on the Support page, add text to the Summary tab of the page in Sites. + +To add customized text on the Support page, add text to the Body tab of the page in Sites. + +## Wallpaper Images + +If you want to use one of the existing wallpaper images for a portal tile, go to:\ +[https://global.insite.com/admin/files/browse](https://global.insite.com/admin/files/browse) and select **Wallpapers** + +There is no download option; if you want a copy of one of the image files there, click on it and choose the Open button. The image you selected will download to your download folder. + +
Sites 01
diff --git a/contributors/toolkits/sites/skillscheck-publishing-course-product.md b/contributors/toolkits/sites/skillscheck-publishing-course-product.md new file mode 100644 index 0000000..c5b9cca --- /dev/null +++ b/contributors/toolkits/sites/skillscheck-publishing-course-product.md @@ -0,0 +1,54 @@ +--- +description: >- + Steps for configuring organization settings and publishing a course or product + to the skillscheck.ca web page +--- + +# SkillsCheck — steps for publishing a course/product to the skillscheck.ca web page + +**Organization Settings:** + +1. When an Class is created the Venue is one of the required fields during setup. Since SkillsCheck Courses/Assessments are online, we created a Venue called [Online Course](https://dev-skillscheck.shiftiq.com/ui/admin/contacts/groups/edit?contact=e72736b3-deb7-40ba-b3c0-b1c501448f67) and this Venue will be added for all classes being created from the SkillsCheck webpage. The group GUID needs to be added under the advanced Organization settings next to `"ProductClassEventVenueGroup"` . +2. The purchaser needs to be added to a admin role with permissions to see the instructor's gradebook. Create a group with the appropriate permissions and add the The group GUID needs to be added under the advanced Organization settings next to `"ProductCustomerGroup"`. All users creating an account from the SkillsCheck webpage will be added to the group. + +```json +"Sales": { + "ProductClassEventVenueGroup": "e72736b3-deb7-40ba-b3c0-b1c501448f67", + "ProductCustomerGroup": "397ff7ac-a8eb-4a04-8bf0-b1b900e29086" + }, +``` + +
Skillscheck publishing 01
+ +**Course/Assessment/Group creation instructions:** + +1. Create the Course +2. Attach a Gradebook to the Course + 1. Note: If a Gradebook isn't attached to the course, it will not be available to be selected when creating the product for the SkillsCheck web page. +3. Create a Group with the same name as the Course + 1. _**Example:** Course Name = **Carpenter: Window Framing** so then the Group Name = **Carpenter: Window Framing**_ + 2. Group Type = Role + 3. Group Tag = Course +4. Publish the Course to the Portal and add the Group to the Privacy of the Course + 1. Adding the Privacy for the course needs to be done from the Sites toolkit after Course has been published. +5. Create the Product in the Sales toolkit. + 1. Add Product Name = Same as the Course/Group name + 2. Add Description + 3. Select the Course tied to the Product + 4. Add the Price for the product + 5. Add Product Image + 6. Save changes +6. Publish Product to Web page when ready. + +{% hint style="info" %} +**IMPORTANT NOTE:** + +The Course, Group and Product names should all match. Example:\ +**Course Name:** Indoor Painter\ +**Group Name:** Indoor Painter\ +**Product Name:** Indoor Painter +{% endhint %} + +Dev tasks for SkillsCheck: + +* [DEV-8651](https://insite.atlassian.net/browse/DEV-8651) - Implement Skills Check (Closed) diff --git a/contributors/toolkits/standards/README.md b/contributors/toolkits/standards/README.md new file mode 100644 index 0000000..51a1591 --- /dev/null +++ b/contributors/toolkits/standards/README.md @@ -0,0 +1,14 @@ +--- +description: >- + How the Standards toolkit (aliased Competency) models frameworks, outcomes, + and document output +--- + +# Standards + +The Standards toolkit (aliased **Competency** internally) models frameworks, occupations, outcomes, and the documents that print from them. + +This section collects internal notes for contributors working on Standards: + +* [Define custom fields for standard output document headers](define-custom-fields-for-standard-output-document-headers.md) — adding header fields without touching the schema. +* [Ideas](ideas/README.md) — design sketches that have not yet been implemented, including outcome-score calculations. diff --git a/contributors/toolkits/standards/define-custom-fields-for-standard-output-document-headers.md b/contributors/toolkits/standards/define-custom-fields-for-standard-output-document-headers.md new file mode 100644 index 0000000..9fee9ad --- /dev/null +++ b/contributors/toolkits/standards/define-custom-fields-for-standard-output-document-headers.md @@ -0,0 +1,19 @@ +--- +description: >- + How global admins customize the content fields of the Document module for a + specific tenant +--- + +# Define custom fields for standard output document headers + +Global admins can modify the content fields of Document module on _admin/utilities/tenants/edit_ screen in _Collections_ section for a specific tenant if needed. The _Standards/Document/Content_ collection of Global tenant contains the default fields used when a new tenant is created: + +
Define custom fields 01
+ +Global admins can override the default items for each tenant. Open the Collections panel in the tenant you want to edit and define new collections. + +
Define custom fields 02
+ +Go to the Utilities/Labels table and add labels for your new fields: + +
Define custom fields 03
diff --git a/contributors/toolkits/standards/ideas/README.md b/contributors/toolkits/standards/ideas/README.md new file mode 100644 index 0000000..bb57545 --- /dev/null +++ b/contributors/toolkits/standards/ideas/README.md @@ -0,0 +1,12 @@ +--- +description: >- + Design sketches for the Standards toolkit that have not yet been implemented +--- + +# Ideas + +This folder holds design sketches for the Standards toolkit. The pages here are proposals, not shipped behaviour — treat them as a starting point for discussion rather than reference documentation. + +Current sketches: + +* [Competency (outcome) score calculations](competency-outcome-score-calculations.md) — a proposal for rolling outcome scores up through a framework. diff --git a/contributors/toolkits/standards/ideas/competency-outcome-score-calculations.md b/contributors/toolkits/standards/ideas/competency-outcome-score-calculations.md new file mode 100644 index 0000000..d399f36 --- /dev/null +++ b/contributors/toolkits/standards/ideas/competency-outcome-score-calculations.md @@ -0,0 +1,95 @@ +--- +description: >- + Working notes on supporting competency (outcome) score calculations in Shift + iQ for competency-based education +--- + +# Competency (outcome) score calculations + +## Objective + +**Full support of CBE in Shift iQ requires the ability to calculate scores for competencies.** + +_This page is still being developed and will require team collaboration. This page was developed (partially) from conversations in this issue:_ [DEV-1656](https://insite.atlassian.net/browse/DEV-1656) - Investigate the method of Outcome score calculations that Canvas uses (Closed) + +## Success metrics + +Project goals and metrics to determine success. + +| **Goal** | **Metric** | +| --- | --- | +| An existing customer will use Shift iQ to calculate competency scores (USU, _other_?). | Customer feedback will demonstrate ease of use when configuring outcome scores. _Qualitative_. | +| Post-Secondary institution(s) will use Shift iQ to calculate competency scores. | Increased revenue through acquisition of new customer(s) in 2023. _Quantitative._ | + +## Assumptions + +* While this feature has not been requested _directly_ from our customers, there is an assumption through conversations with customers (USU, CBExchange etc.) that this is a core feature for a true Competency-based LMS. + * _We are assuming that having this functionality in place will make the core product more valuable to our prospective (and some of our existing) customers._ + * _Waiting for customers to completely drive requirements and a solution to this problem has not proven successful. We should have an MVP in place to prove that this is possible in Shift._ +* We _**do not**_ need to be tightly aligned to Canvas. Rather, we can use Canvas to understand how an LMS has implemented outcome / competency calculations, ensuring it works for Shift / our customers at all times. +* Note: we documented a related issue with Logbooks where it was hypothesised that we should display the most recent status of validated competencies instead of the "highest". However, as noted during investigation in the comments of this task - we should heed caution with changing the logic here and ensure alignment with assessments: + * [https://insite.atlassian.net/browse/DEV-10528](https://insite.atlassian.net/browse/DEV-10528) + * _**Some analysis competed via the above issue that should be incorporated into this document.**_ + +## Requirements + +General requirements / child-issues can be created here: [CANCELLED-1016](https://insite.atlassian.net/browse/CANCELLED-1016) - Implement Outcome (Competency) score calculations (To Do) + +| **Requirement** | **User Story** | **Importance** | **Jira Issue** | **Notes** | +| --- | --- | --- | --- | --- | +| Calculation of competency scores must not impact how existing customers use Shift iQ (those that _do not_ require this functionality). | As an existing Admin using Shift iQ, I should be able to continue to use the product without interruption so that my processes are not negatively interrupted. | HIGH | | | +| Determine how outcomes will be organized in Shift iQ and what entities (gradebook scores, attempts and etc) will be used to calculate the outcome score. | | | | | +| Determine what types of calculation will be implemented for purposes of competency calculation | | | | [https://community.canvaslms.com/t5/Canvas-Basics-Guide/What-are-Outcomes/ta-p/75#calculation\_methods](https://community.canvaslms.com/t5/Canvas-Basics-Guide/What-are-Outcomes/ta-p/75#calculation_methods) This link provides example calculations and definitions to support implementation of different calculation types. | + +## Supporting Resources + +Add links, documents etc. that support development or help the team more deeply understand the context of this feature. + +**Canvas outcome score calculations:** [https://community.canvaslms.com/t5/Canvas-Basics-Guide/What-are-Outcomes/ta-p/75#calculation\_methods](https://community.canvaslms.com/t5/Canvas-Basics-Guide/What-are-Outcomes/ta-p/75#calculation_methods) + +**Files provided by Neal from USU:** + +From the email sent on "Fri 10/8/2021 1:25 PM" + +* _Canvas Outcomes 2019-2020:_ Example of the report that MPH has been receiving after much data manipulation. +* _Outcome\_results\_csv_: The Canvas account-level CSV "Outcome results" report. +* _Outcomes-Fall\_2020\_HEP-6550…_: The Mastery Gradebook CSV export, from Canvas at the course level. +* _Outcome\_export_: All outcomes from the KHS subaccount +* _Student\_assignment_: The Canvas account-level "Student Compentency" report. + +Attached files: + +* Canvas Outcomes - 2019-2020.xlsx +* student_assignment_outcome_map_csv_08_Oct_2021_420220211008-104587-xr30si.csv +* Outcomes-Fall_2020_HEP-6550-LO1_XL.csv +* outcome_results_csv_07_Feb_2020_396320200207-9660-vo4qya.csv +* outcome_export_csv_08_Oct_2021_420120211008-106631-1dlzsuu.csv + +From the email sent on "Mon 10/18/2021 5:20 PM": + +> Amy Carpenter tracked down the outcomes reporting that our Biology department is doing using Canvas outcomes data. They have put a lot more time and effort into massaging their reports than MPH, so I felt it would be good to add them to the list of examples to refer to for current institutional outcomes reporting needs. +> +> Their outcomes data website is a beauty to behold: [https://biology.usu.edu/assessment\_files/undergrad\_assessment/outcomes\_data](https://can01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbiology.usu.edu%2Fassessment_files%2Fundergrad_assessment%2Foutcomes_data&data=04%7C01%7Caleksey%40insite.com%7C231f4dd25b8e4822cb0d08d9928dc548%7C926e6a06be7e47539a3f50d1842137ca%7C0%7C0%7C637701960153920373%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=AembdjVPgMYXeRuaEe%2FTXqKXmsKCe9V1S64aZ6WNyi4%3D&reserved=0) +> +> * It's worth noting that this was spearheaded by one of the faculty we worked with for the original CBE project that brought us all together. She would probably be a great collaborator to bring into our conversations. +> +> Also attached is a spreadsheet that our data specialist, Meghan Lewis, helped put together, which helped lead to the reports on the site above. + +Attached file: + +* Biology Outcomes - 202040.xlsx + +## User interaction and design + +## Open Questions + +| **Question** | **Answer** | **Date Answered** | +| --- | --- | --- | +| How will we ensure that the calculation methods implemented meet the needs of prospective customers? | | | +| What calculation methods are easiest to implement from a development perspective? | Number of times, Most recent score, and Highest score are simplest and should likely be implemented together first. _(While the above 3 are easiest to implement, it is likely that "Decaying Average" has the most value to our customers)._ | December 14, 22' | +| We can store competency scores within gradebooks, for example, but I don't know exactly how (or if) this relates to outcome score calculations (Dan). | **KYLE FU** | | +| …if we **did** support outcome score calculations, then where would this be visible to a learner or to an administrator within Shift iQ? And what would you expect it to look like? (Dan) | **KYLE DEVELOP MOCKUP(S)\*\*** | | + +## Out of Scope + +* Occasionally there is discussion about **whether or not a question should evaluate multiple competencies**, and in the past the **decision has always been "no"** for the sake of simplicity. diff --git a/contributors/toolkits/workflows/README.md b/contributors/toolkits/workflows/README.md new file mode 100644 index 0000000..c389e2d --- /dev/null +++ b/contributors/toolkits/workflows/README.md @@ -0,0 +1,11 @@ +--- +description: How the Workflows toolkit drives surveys, branching, and notifications +--- + +# Workflows + +The Workflows toolkit (aliased as **Surveys** in the customer-facing UI) owns the engine that runs forms, branching logic, and the notifications triggered as respondents move through them. + +This section collects internal notes on configuring workflow content: + +* [Survey content font colours](survey-content-font-colours.md) — how the font-colour overrides interact with the portal theme. diff --git a/contributors/toolkits/workflows/survey-content-font-colours.md b/contributors/toolkits/workflows/survey-content-font-colours.md new file mode 100644 index 0000000..36a6abe --- /dev/null +++ b/contributors/toolkits/workflows/survey-content-font-colours.md @@ -0,0 +1,39 @@ +--- +description: How to change the font colour of answer options and question text in a survey +--- + +# Survey content font colours + +How to change the font color of the **Answer Options** in an **Survey**: + +* Open the **Survey** and click on the **Content** tab. +* Under the **Page Header** tab, click the **Edit** button. +* Add the following code: + + ```css + + ``` + +* You can change the color by typing the color name (e.g. black, red, blue) or adding the HTML color code (e.g. #060606, #F90F0F, #0F0FF9) after "**color:**". + * For example: `color: blue` or `color: #060606` +* Click **Save.** + +
Survey content font colours 01
+ +> **Please note:** Adding this code to the survey will change the color for **all** answer options in the survey. + +How to change the font color of the **Question Text** in a **Survey**: + +* Open the **Survey** and under the **Questions** tab, click the Pencil icon next to the question you want to change the font color for. +* Add the following code in the **Question Text** field:\ + `add text here` +* Add your question text between `"color:black">` and `Survey content font colours 02
+ +
Survey content font colours 03
diff --git a/contributors/tools/ide.md b/contributors/tools/ide.md index 04e7233..3998b5a 100644 --- a/contributors/tools/ide.md +++ b/contributors/tools/ide.md @@ -1,7 +1,11 @@ -# IDE +--- +description: Recommended IDEs and tools for working on the Shift iQ codebase +--- -VS Code +# IDE -Visual Studio 2022 +The following editors and tools are in active use on the Shift iQ codebase: -Insomnia +* **Visual Studio 2022** — primary IDE for the .NET back end. +* **Visual Studio Code** — preferred editor for the front-end TypeScript / React code and for editing documentation. +* **Insomnia** — REST/GraphQL client used to exercise the API while developing endpoints. diff --git a/contributors/tools/sql-server-reporting-services.md b/contributors/tools/sql-server-reporting-services.md index 71de215..99cd0a5 100644 --- a/contributors/tools/sql-server-reporting-services.md +++ b/contributors/tools/sql-server-reporting-services.md @@ -1,3 +1,7 @@ +--- +description: To open an RPTPROJ file (SQL Server Reporting Services project) in Visual Studio 2022, you'll need to install the appropriate extension, because +--- + # SQL Server Reporting Services To open an RPTPROJ file (SQL Server Reporting Services project) in Visual Studio 2022, you'll need to install the appropriate extension, because SSRS support is not included by default. diff --git a/cspell.json b/cspell.json new file mode 100644 index 0000000..eff78a7 --- /dev/null +++ b/cspell.json @@ -0,0 +1,136 @@ +{ + "version": "0.2", + "language": "en,en-GB,en-CA", + "ignorePaths": [ + "node_modules/**", + ".git/**", + "**/SUMMARY.md", + "**/.gitbook/**", + "embeds/fr.md" + ], + "ignoreRegExpList": [ + "/]+>[\\s\\S]*?/g", + "/href=\"[^\"]+\"/g", + "/id=\"[^\"]+\"/g", + "/\\[[^\\]]+\\]\\([^)]+\\)/g", + "/`[^`\\n]+`/g", + "/[A-Za-z0-9]{20,}/g", + "/[A-Z][a-z]+(?=[A-Z]){3,}/g", + "/'[A-Za-z0-9+/=]{12,}'/g", + "/\"[A-Za-z0-9+/=]{12,}\"/g" + ], + "words": [ + "AHRI", + "AICC", + "Addemdums", + "Aleksey", + "Archon", + "Atlassian", + "Bambora", + "BCPVPA", + "Calibri", + "COTBC", + "blockchain", + "Bootstrap", + "CMDS", + "commitlint", + "CQRS", + "cspell", + "Dapper", + "datatypes", + "DEVOPS", + "Gradebook", + "gradebook", + "gradebooks", + "Gradebooks", + "HubSpot", + "iQ", + "InSite", + "insite", + "Insomnia", + "Invigilator", + "Keyera", + "Likert", + "likert", + "Lobby", + "Logbook", + "logbook", + "logbooks", + "Logbooks", + "lychee", + "Mailgun", + "markdownlint", + "Microservices", + "monolith", + "monolithic", + "Moodle", + "multitenant", + "NBCC", + "NCSHA", + "FIPPA", + "HACP", + "imsmanifest", + "lxrmerge", + "Octopus", + "RCABC", + "CPTBC", + "IECBC", + "JHSC", + "Kalantri", + "LETSI", + "LINQ", + "LTSC", + "Muratori", + "NCOT", + "RTWS", + "Rustici", + "SSDT", + "STBC", + "Serilog", + "changedbowner", + "unprojected", + "openapi", + "OpenAPI", + "Polaris", + "Postgres", + "PowerShell", + "rptproj", + "scorm", + "SCORM", + "shadcn", + "Shift iQ", + "shiftiq", + "ShiftiQ", + "SkillsCheck", + "SpotLite", + "ssrs", + "SSRS", + "TAction", + "TanStack", + "Tekton", + "Tempo", + "toolkit", + "Toolkit", + "toolkits", + "Toolkits", + "uuid", + "UUIDs", + "wenyan", + "xAPI", + "xlsx", + "Zustand" + ], + "ignoreWords": [ + "ANQJH", + "CAMLPR", + "CPQRUVGC", + "Fuptl", + "Gbpvy", + "Ztmu", + "dlzsuu", + "Eupp", + "Addendums" + ], + "flagWords": [], + "allowCompoundWords": true +} diff --git a/developers/api-v1/api-reference/README.md b/developers/api-v1/api-reference/README.md index c9d30eb..22644dd 100644 --- a/developers/api-v1/api-reference/README.md +++ b/developers/api-v1/api-reference/README.md @@ -1,6 +1,12 @@ --- +description: >- + Reference for the v1 API. Endpoints below are generated from the v1 OpenAPI + specification. icon: brackets-curly --- # API Reference +The endpoints below are generated from the v1 OpenAPI specification. Pick an endpoint to see its parameters, request body, and response schema. + +> v1 is in maintenance mode. New integrations should target [API v2](../../api-v2/introduction.md). diff --git a/developers/api-v2/authentication/README.md b/developers/api-v2/authentication/README.md index cdb288f..9afbc6e 100644 --- a/developers/api-v2/authentication/README.md +++ b/developers/api-v2/authentication/README.md @@ -35,7 +35,7 @@ Secure cookie authentication may be preferred in some specific integration scena Authentication cookies incorporate several security features to protect user data and prevent unauthorized access. These security features include the following: * The `Secure` flag ensures the cookie is only transmitted over encrypted HTTPS connections, preventing interception during communication between clients and the server. -* The `HttpOnly` attribute prevents client-side scripts from accessing the cookie through JavaScript, mitigating cross-site scripting (XSS) attacks.* The `SameSite` attribute helps prevent cross-site request forgery (CSRF) attacks by restricting the cookie to same-site contexts or explicitly allowing cross-site usage.* An expiration date limits the cookie's lifespan. +* The `HttpOnly` attribute prevents client-side scripts from accessing the cookie through JavaScript, mitigating cross-site scripting (XSS) attacks.*The `SameSite` attribute helps prevent cross-site request forgery (CSRF) attacks by restricting the cookie to same-site contexts or explicitly allowing cross-site usage.* An expiration date limits the cookie's lifespan. * Domain and path restrictions limit where the cookie can be used and where it can be accessed. * The cookie value is signed with a cryptographically secure digital signature, and then encrypted for additional privacy and security. @@ -53,7 +53,7 @@ To authenticate a request, provide the secret in the `Authorization` header of t `Secret wJalrXUtnFEMI0O6JX5MCkmbs6JqPcx3` Client secrets are generated using cryptographically strong random number generators, ensuring they have sufficient entropy to resist brute-force attacks and are statistically unique across different client applications. + * The secrets are typically long, random strings that are computationally infeasible to guess or derive through cryptanalysis.* The secrets are designed to be treated as sensitive credentials with proper lifecycle management, including secure generation, storage, rotation, and revocation capabilities. Client secret authentication is limited in scope because it requires the ability to securely store and protect the secret, which is feasible only for confidential clients like server-side applications. Bearer tokens have more sophisticated security features (e.g., shorter lifespans, scoped permissions, easy revocation) — this is why bearer authentication is preferred and required for most API endpoints throughout the platform. - diff --git a/developers/api-v2/authentication/how-to-generate-an-access-token-with-a-long-lifetime.md b/developers/api-v2/authentication/how-to-generate-an-access-token-with-a-long-lifetime.md index 230396b..313e159 100644 --- a/developers/api-v2/authentication/how-to-generate-an-access-token-with-a-long-lifetime.md +++ b/developers/api-v2/authentication/how-to-generate-an-access-token-with-a-long-lifetime.md @@ -9,7 +9,7 @@ By default, API access tokens expire after 24 hours. For automated processes, sc ## Endpoint -``` +```text POST /v2/{partition}/security/tokens/generate ``` diff --git a/developers/api-v2/introduction.md b/developers/api-v2/introduction.md index 8374d48..a332e04 100644 --- a/developers/api-v2/introduction.md +++ b/developers/api-v2/introduction.md @@ -21,7 +21,7 @@ For details on API keys, bearer tokens, and other authentication methods, see [A Login, click your name at the top right, and click **My Profile**: -
+
V2 01
## OpenAPI Specification @@ -29,7 +29,7 @@ The API is described using the [OpenAPI Specification](https://github.com/OAI/Op The OAS for the Shift API looks like this: -
+
V2 02
Browse the full specification via the API Reference link below, or download it as JSON for use in your own applications. diff --git a/developers/api-v2/navigating-the-api.md b/developers/api-v2/navigating-the-api.md index 53f3357..7a0e0e9 100644 --- a/developers/api-v2/navigating-the-api.md +++ b/developers/api-v2/navigating-the-api.md @@ -4,4 +4,3 @@ icon: brackets-curly --- # Endpoints - diff --git a/developers/api-v2/rate-limits-and-throttling.md b/developers/api-v2/rate-limits-and-throttling.md index 1842831..cdfe5df 100644 --- a/developers/api-v2/rate-limits-and-throttling.md +++ b/developers/api-v2/rate-limits-and-throttling.md @@ -12,8 +12,8 @@ The system incorporates a dynamic throttling mechanism designed to maintain fair The throttling system operates on a token bucket model with two core components: -- **Rate Limit**: A maximum quota of requests allocated to each developer -- **Request Cost**: Each API request consumes a portion of your quota based on its resource intensity +* **Rate Limit**: A maximum quota of requests allocated to each developer +* **Request Cost**: Each API request consumes a portion of your quota based on its resource intensity When you make a request, the associated cost is deducted from your available quota. Your quota automatically replenishes at a steady rate over time, ensuring continuous access while preventing burst abuse patterns. @@ -21,15 +21,15 @@ When you make a request, the associated cost is deducted from your available quo If your request is throttled due to insufficient remaining quota, the API will return a `403 Forbidden` response with the status message "Rate Limit Exceeded." Your application should implement robust error handling to gracefully manage this scenario by: -- Catching the 403 response code -- Implementing exponential backoff or scheduled retry logic -- Deferring the request until quota has been replenished +* Catching the 403 response code +* Implementing exponential backoff or scheduled retry logic +* Deferring the request until quota has been replenished **Monitoring Your Usage** To help you proactively manage your API consumption and avoid throttling, every response includes informative headers: -- **`X-Request-Cost`**: A floating-point value indicating the exact quota amount consumed by the current request -- **`X-Rate-Limit-Remaining`**: Your current remaining quota balance (only included when throttling is active for your account) +* **`X-Request-Cost`**: A floating-point value indicating the exact quota amount consumed by the current request +* **`X-Rate-Limit-Remaining`**: Your current remaining quota balance (only included when throttling is active for your account) By monitoring these headers, you can build intelligent rate-limiting logic into your application and optimize request patterns to stay within your allocated quota. diff --git a/developers/integrations/power-bi.md b/developers/integrations/power-bi.md index c55d3a1..cc383ef 100644 --- a/developers/integrations/power-bi.md +++ b/developers/integrations/power-bi.md @@ -29,7 +29,7 @@ If you are working with the API for the first time, then always start in the Dev Sign in and visit the My Profile page. If your account is enabled for development and integration work with the API then you'll see a Developer Settings panel on this page. -
+
Power bi 1 (1)
If you don't see a Developer Settings panel then contact your LMS administrator to have this enabled for your account. @@ -37,7 +37,7 @@ If you don't see a Developer Settings panel then contact your LMS administrator Visit the My Profile page and click the key beside the API Access Token label in the Developer Settings section. The system will create a token that you can copy to your clipboard with a single mouse-click. -
+
Power bi 2
## Step 3: Create a data source in Power BI @@ -45,7 +45,7 @@ Start the Power BI Desktop app on your computer and create a new report. When you are prompted for a data source, select "Get data from another source". In the "Get Data" dialog box, select "Web". -
+
Power bi 3
In the "From Web" dialog box, select "Advanced" and input the settings for the URL parts and the HTTP request header. @@ -64,13 +64,13 @@ You can input the entire, fully-qualified URL for an API endpoint as a single UR Here is an example for reference: -
+
Power bi 4
-## That's it! +## That's it Click "OK", and the data source is ready to use in Power BI. -
+
Power bi 5
## Next steps: explore and experiment diff --git a/developers/integrations/single-sign-on.md b/developers/integrations/single-sign-on.md index 07df1b6..cdec2e6 100644 --- a/developers/integrations/single-sign-on.md +++ b/developers/integrations/single-sign-on.md @@ -31,7 +31,7 @@ Refer to this article for details: [LTI as a SSO Mechanism](https://www.imsgloba An LTI launch message submitted for SSO access to Shift iQ looks something like this: -
+
Lti launch
The LTI Launch message is signed with a secure digital signature, using [HMAC-SHA1](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha1?view=net-7.0) or [HMAC-SHA256](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha256?view=net-7.0), with a secret key that is shared between the two systems. diff --git a/developers/resources/date-and-time-values.md b/developers/resources/date-and-time-values.md index ed87997..27e1261 100644 --- a/developers/resources/date-and-time-values.md +++ b/developers/resources/date-and-time-values.md @@ -115,7 +115,7 @@ DateTimeOffset parsed = DateTimeOffset.Parse(serialized); Check out this service in the API: -
+
V2 04
You can practice with your own input values to see exactly how they are parsed and interpreted by the server. For example: diff --git a/embeds/en.md b/embeds/en.md index cc4e667..0b89ec2 100644 --- a/embeds/en.md +++ b/embeds/en.md @@ -1,38 +1,40 @@ +--- +description: Contextual help (or in-context help) refers to assistance that appears directly within the user interface - at the point where users need it. +--- + # about Contextual help (or in-context help) refers to assistance that appears directly within the user interface - at the point where users need it. Alternative terms commonly used for this include: -- Embedded help - help content built into the interface itself -- Progressive disclosure - revealing information gradually as needed -- Microcopy - short, helpful text snippets within the UI -- Contextual guidance - assistance provided based on the user's current context +* Embedded help - help content built into the interface itself +* Progressive disclosure - revealing information gradually as needed +* Microcopy - short, helpful text snippets within the UI +* Contextual guidance - assistance provided based on the user's current context Specific types of contextual help include: -- Tooltips (hover or click-triggered explanations) -- Inline help text -- Field hints or placeholder text -- Progressive onboarding flows -- Contextual callouts or popovers +* Tooltips (hover or click-triggered explanations) +* Inline help text +* Field hints or placeholder text +* Progressive onboarding flows +* Contextual callouts or popovers The term "contextual help" is widely recognized in UX design and technical writing communities as it emphasizes that the help is relevant to the user's immediate context and task, rather than requiring them to navigate away to a separate help section or documentation. - *** ui/lobby/eula ## Terms of Use - -Thanks for using our products and services ("Services"). The Services are provided by InSite Information Systems Corp. (IIS Corp.) under the trademarks InSite, SkillsCheck, SkillsPassport and Shift iQ, located at 1055 West Hastings Street, Suite 300, Vancouver, BC V6E 4P1 Canada. - -Our Services are diverse, so sometimes additional terms or product requirements (including age requirements) may apply. Additional terms will be available with the relevant Services, and those additional terms become part of your agreement with us if you use those Services. - -By using our Services, you are agreeing to these terms. Please read them carefully. - -Click here for the full Terms of Use. - -**Disclaimer:** IIS Corp. does not guarantee the accuracy of any information captured or generated using our Services, nor the qualifications, credentials, or suitability of any person(s) using or identified through our Services. Users are solely responsible for verifying all information and conducting due diligence as needed. +Thanks for using our products and services ("Services"). The Services are provided by InSite Information Systems Corp. (IIS Corp.) under the trademarks InSite, SkillsCheck, SkillsPassport and Shift iQ, located at 1055 West Hastings Street, Suite 300, Vancouver, BC V6E 4P1 Canada. + +Our Services are diverse, so sometimes additional terms or product requirements (including age requirements) may apply. Additional terms will be available with the relevant Services, and those additional terms become part of your agreement with us if you use those Services. + +By using our Services, you are agreeing to these terms. Please read them carefully. + +Click here for the full Terms of Use. + +**Disclaimer:** IIS Corp. does not guarantee the accuracy of any information captured or generated using our Services, nor the qualifications, credentials, or suitability of any person(s) using or identified through our Services. Users are solely responsible for verifying all information and conducting due diligence as needed. *** ui/portal/eula @@ -125,4 +127,4 @@ If it turns out that a particular term is not enforceable, this will not affect The laws of British Columbia, Canada, will apply to any disputes arising out of or relating to these terms or the Services. All claims arising out of or relating to these terms or the Services will be litigated exclusively in the federal or state courts of Vancouver, BC, Canada, and you and InSite consent to personal jurisdiction in those courts. -For information about how to contact InSite, please visit the Contact Us page on our web site. \ No newline at end of file +For information about how to contact InSite, please visit the Contact Us page on our web site. diff --git a/embeds/fr.md b/embeds/fr.md index 16ee6c3..3847f29 100644 --- a/embeds/fr.md +++ b/embeds/fr.md @@ -1,28 +1,31 @@ +--- +description: Contextual help (or in-context help) refers to assistance that appears directly within the user interface - at the point where users need it. +--- + # about Contextual help (or in-context help) refers to assistance that appears directly within the user interface - at the point where users need it. Alternative terms commonly used for this include: -- Embedded help - help content built into the interface itself -- Progressive disclosure - revealing information gradually as needed -- Microcopy - short, helpful text snippets within the UI -- Contextual guidance - assistance provided based on the user's current context +* Embedded help - help content built into the interface itself +* Progressive disclosure - revealing information gradually as needed +* Microcopy - short, helpful text snippets within the UI +* Contextual guidance - assistance provided based on the user's current context Specific types of contextual help include: -- Tooltips (hover or click-triggered explanations) -- Inline help text -- Field hints or placeholder text -- Progressive onboarding flows -- Contextual callouts or popovers +* Tooltips (hover or click-triggered explanations) +* Inline help text +* Field hints or placeholder text +* Progressive onboarding flows +* Contextual callouts or popovers The term "contextual help" is widely recognized in UX design and technical writing communities as it emphasizes that the help is relevant to the user's immediate context and task, rather than requiring them to navigate away to a separate help section or documentation. - *** ui/lobby/eula ## Terms of Use - + # Conditions d'utilisation Merci d'utiliser nos produits et services (les « Services »). Les Services sont fournis sous les marques de commerce InSite et Shift iQ par InSite Information Systems Corp. (IIS Corp.), société située au 1055 West Hastings Street, Suite 300, Vancouver, BC V6E 4P1 Canada. @@ -33,11 +36,10 @@ Parce que nos Services sont diversifiés, il arrive que d'autres conditions ou e Cliquez ici pour consulter [les conditions d'utilisation complètes](/ui/lobby/eula). - *** ui/portal/eula -# Conditions d'utilisation +# Conditions d'utilisation (Portail) Merci d'utiliser nos produits et services (les « Services »). Les Services sont fournis sous les marques de commerce InSite et Shift iQ par InSite Information Systems Corp. (IIS Corp.), société située au 1055 West Hastings Street, Suite 300, Vancouver, BC V6E 4P1 Canada. @@ -125,4 +127,4 @@ S'il s'avère qu'une condition en particulier n'est pas exécutoire, cela ne nui Les lois de la Colombie-Britannique, au Canada, s'appliqueront à tout différend qui découle des présentes ou des Services ou qui s'y rapportent. Toutes les réclamations découlant des présentes ou des Services ou s'y rapportant seront défendues exclusivement devant des tribunaux fédéraux ou provinciaux de Vancouver (C.-B.), au Canada, et InSite et vous acceptez la compétence personnelle de ces tribunaux. -Pour savoir comment communiquer avec InSite, rendez-vous sur la page Contact Us de notre site Web. \ No newline at end of file +Pour savoir comment communiquer avec InSite, rendez-vous sur la page Contact Us de notre site Web. diff --git a/guides/README.md b/guides/README.md index 79c70cd..82371bc 100644 --- a/guides/README.md +++ b/guides/README.md @@ -10,4 +10,3 @@ icon: book ## Demonstrations
Experience the system as a learnerlearner-card.pnglearner-walkthrough.md
Experience the system as an instructorinstructor-card.pnginstructor-walkthrough.md
Experience the system as an administratoradministrator-card (1).pngadministrator-walkthrough.md
- diff --git a/guides/learning-content/scorm-and-xapi/adding-scorm-content-to-a-course.md b/guides/learning-content/scorm-and-xapi/adding-scorm-content-to-a-course.md index cee685f..90cc670 100644 --- a/guides/learning-content/scorm-and-xapi/adding-scorm-content-to-a-course.md +++ b/guides/learning-content/scorm-and-xapi/adding-scorm-content-to-a-course.md @@ -10,7 +10,7 @@ Adding a SCORM package to a course in Shift iQ is a simple process. Add a Link activity to a module in your course. -
+
Scoop 01
### Step 2 @@ -20,7 +20,7 @@ If an SCO library is not already created for your organization, the system will Click the link to open your SCO library. -
+
Scoop 02
### Step 3 @@ -28,23 +28,22 @@ Upload your SCORM package. Click the button to choose a file on your computer, and click the button to add your SCORM package to your library. -
+
Image (3)
The system will generate a SCORM package identifier for you automatically. It converts the name of your file to lowercase, and replaces non-alphanumeric characters to hyphens. This ensures the identifier is web-friendly. Copy this to your clipboard. -
+
Image (4)
### Step 4 Paste the SCORM package identifier into the field labelled "SCORM Package ID". -
+
Image (2)
### Step 5 Save your changes, preview the course in Shift, and click the Launch button to confirm your content is displayed. -
- -
+
Image (1)
+
Image
diff --git a/guides/learning-content/scorm-and-xapi/versions.md b/guides/learning-content/scorm-and-xapi/versions.md index ee79ec8..afb4e82 100644 --- a/guides/learning-content/scorm-and-xapi/versions.md +++ b/guides/learning-content/scorm-and-xapi/versions.md @@ -112,11 +112,11 @@ Just like smartphones have evolved from basic devices to powerful computers, eLe #### **If you want very advanced features:** -3. **SCORM 2004 3rd or 4th Edition** - For complex course navigation and prerequisites. +1. **SCORM 2004 3rd or 4th Edition** - For complex course navigation and prerequisites. #### **If you're forward-thinking:** -4. **xAPI + cmi5** - For comprehensive learning analytics and modern learning experiences. +1. **xAPI + cmi5** - For comprehensive learning analytics and modern learning experiences. #### **Special situations:** diff --git a/guides/role-based-guides/administrator-walkthrough.md b/guides/role-based-guides/administrator-walkthrough.md index a0fbcbb..0294a7b 100644 --- a/guides/role-based-guides/administrator-walkthrough.md +++ b/guides/role-based-guides/administrator-walkthrough.md @@ -28,7 +28,7 @@ The administrator dashboard contains everything needed to quickly view critical Depending on the configuration of the system for your organization account, an administrator might have access to any (or all!) of these features: -
+
Admin experience 11
> Administrator Note: Email notifications are disabled in all Sandbox environments. @@ -36,7 +36,7 @@ Depending on the configuration of the system for your organization account, an a Return to the home screen at any time by clicking the Home button, or **Admin** on the breadcrumb trail. Navigate to any toolkit by clicking on the left menu OR on the tile on the main admin work area. -
+
Admin experience 01
Shift iQ is delivered using role-based access control, meaning different features, functionality and information is displayed to administrators based on their on the permissions and roles in the system. @@ -44,13 +44,13 @@ Shift iQ is delivered using role-based access control, meaning different feature When you click on a toolkit, you're presented with tiles showing the different types of data available there. For example, the **Contacts** toolkit shows that there are 36 **People**, 17 **Employers**, 9 **Roles** (Permissions), etc. -
+
Admin experience 02
Click the **People** card to start exploring. The **People** -> **Search** page has a tab for search **Criteria** and search **Results**. This page is powerful for searching for anything related to a person. Note: If you have a set of search criteria that you use regularly, you can save it to be used again and again. -
+
Admin experience 03
Try searching for all **People** associated with the **Safety Training Employer**. On the People Search **Criteria** page, click on the **Group** field and select **Safety Training Employer**. Click on the **Search** button at the bottom of the screen. @@ -58,7 +58,7 @@ You can see on the **Results** tab that there are currently 33 people associated View more columns by selecting which ones you want on the Criteria tab. -
+
Admin experience 04
Form the search results tab, edit a person to view all the information the system has about him. This is called the Person Record. From the person record you can: @@ -141,7 +141,7 @@ Insert an additional assessment into the Privacy Awareness FIPPA course Click on Course Catalogue -> Privacy Awareness FIPPA course to see the changes that you’ve made to the course and to try it out. -
+
Admin experience 05
## Assessments and Certifications @@ -161,7 +161,7 @@ Configure the Privacy Awareness FIPPA course to follow the logic above. * [ ] Log out and log back in as Jane Learner. View the course to see the lock on the course outline * [ ] Proceed through the learning activity to test -
+
Admin experience 06
## Communication and Learner Engagement @@ -176,7 +176,7 @@ Notifications are sent automatically by the system based on system events, or co 3. Click the Add New Notification link at the top of the page 4. Create some sample content and save your notification. -
+
Admin experience 07
Attach your notification to a course: @@ -200,7 +200,7 @@ To send a message to a contact: A complete history of changes to a contact including the dates of any messages sent and the content of those messages is available on the Person -> Details tab. -
+
Admin experience 08
## Tracking and Reporting @@ -217,7 +217,7 @@ A complete history of changes to a contact including the dates of any messages s 5. **Standards**: Shows average scores for each competency in your framework. This can highlight the strengths and weaknesses of your training program. Note, you can also toggle this to a learner view to see this report by individual learner. 6. **Downloads**: Download any of this data to share or for external analysis. -
+
Admin experience 09
### View or export learner records from the person record @@ -237,4 +237,4 @@ A complete history of changes to a contact including the dates of any messages s 6. The **Grade items** tab will give an overview of the grade items you have set up. You can add, remove, or change the scoring settings of your gradebook here 7. Export records using the **Summary List** button -
+
Admin experience 10
diff --git a/guides/role-based-guides/instructor-walkthrough.md b/guides/role-based-guides/instructor-walkthrough.md index f54fe45..3ca7ed7 100644 --- a/guides/role-based-guides/instructor-walkthrough.md +++ b/guides/role-based-guides/instructor-walkthrough.md @@ -1,5 +1,5 @@ --- -description: This instructor experience walkthrough is demonstrates gradebook features +description: Instructor walkthrough demonstrating gradebook features --- # Instructor experience @@ -21,7 +21,7 @@ Our team has configured a sample organization for demo and training purposes. Yo The sample organization is named Safety Training Authority (STA). It is configured with an **Instructor Dashboard** that includes links to the **Course Catalog** and the **Instructor Gradebook**. -
+
Instructor experience 01
> Administrator Note: In the STA demo organization, this instructor is granted access to multiple areas of the system. The visibility of navigation cards on the dashboard is managed with role-based access permissions. For example, if you are assigned to a role with permission granted to an area of the system, then the launch card for that area is visible on your dashboard — otherwise it is not visible to you. @@ -31,7 +31,7 @@ The **Course Catalog** displays the same information for an instructor that it d When you navigate to the **Instructor Gradebook** you'll see an administrative view of the system, with limited access to gradebook administration. For example: -
+
Instructor experience 02
An instructor can see an Instructor Gradebook for every course they teach. This limits their view to a confined learner population. Instructors can: @@ -45,13 +45,13 @@ An instructor can see an Instructor Gradebook for every course they teach. This 1. Click the Summary List button to export these results to .xlsx format 4. View personal information of learners in their class, as well as achievements those learners have earned, other courses in which they are registered, and learning records associated with that learner. 1. Click on the learner’s name to view records. -5. View scores for groups of learners scores on specific grade items by clicking on the Grade Items tab. +5. View scores for groups of learners scores on specific grade items by clicking on the Grade Items tab. 6. Print a Grade Report for each learner -
+
Instructor experience 03
Instructors can navigate back to the admin homepage by clicking the Home icon in the upper right or the Admin link in the breadcrumb trail. They can navigate back to the portal by clicking on the Portal shortcut, or back to the My Dashboard view through the link in the dropdown menu under their name. -
+
Instructor experience 04
diff --git a/guides/role-based-guides/learner-walkthrough.md b/guides/role-based-guides/learner-walkthrough.md index e8a4d33..abf0713 100644 --- a/guides/role-based-guides/learner-walkthrough.md +++ b/guides/role-based-guides/learner-walkthrough.md @@ -25,7 +25,7 @@ You can navigate to the Dashboard page any time by clicking your name at the top > Administrator Note: Your organization account can be configured so this page is the default home page for all your learners. -
+
Learner experience 01
The navigation menu in the left panel provides learners with quick and easy access to everything they need. @@ -44,7 +44,7 @@ In addition to allowing your learners to browse your e-learning catalogue for se Here, for example, here an administrator has published a library of online courses (Course Catalog) as well as event registrations (Enroll in a Course) in the learning portal: -
+
Learner experience 02
Please note, in the STA demo organization: @@ -63,7 +63,7 @@ Here is a suggested activity to try for yourself: * [ ] On the Assessments tab, view the results of your assessments * [ ] A complete list of completed Lessons and Assessments can be found on the Grades tab -
+
Learner experience 03
## Explore class enrollments diff --git a/operations/README.md b/operations/README.md index 5ed6db8..895e7ab 100644 --- a/operations/README.md +++ b/operations/README.md @@ -1,3 +1,7 @@ +--- +description: "We’re working on something great! This page isn’t quite ready yet, but content is on the way." +--- + # Operations #### 🚧 This page is under construction diff --git a/releases/SUMMARY.md b/releases/SUMMARY.md index 2b784c1..b267a4d 100644 --- a/releases/SUMMARY.md +++ b/releases/SUMMARY.md @@ -6,25 +6,21 @@ ## October 2025 -* [Oct 29: Version 25.6 is live!]() +* [Oct 29: Version 25.6 is live!](oct-29-version-25.6-is-live.md) ## September 2025 -* [Sep 10: Version 25.5 is live!]() +* [Sep 10: Version 25.5 is live!](sep-10-version-25.5-is-live.md) ## July 2025 -* [July 16: Version 25.4 is live!]() -* [July 9: Version 25.4 is in pre-release]() +* [July 16: Version 25.4 is live!](july-16-version-25.4-is-live.md) +* [July 9: Version 25.4 is in pre-release](july-9-version-25.4-in-pre-release.md) ## June 2025 -* [June 20: Welcome to the changelog]() +* [June 20: Welcome to the changelog](june-20-welcome-to-the-changelog.md) ## May 2025 * [May 28: Version 25.3 is live!](may-2025/may-28-version-25.3-is-live.md) - -## Archive - -* [Notes for previous releases](archived-release-notes.md) diff --git a/releases/archived-release-notes.md b/releases/archived-release-notes.md deleted file mode 100644 index c71e23c..0000000 --- a/releases/archived-release-notes.md +++ /dev/null @@ -1,873 +0,0 @@ -# Archived Release Notes - -## v25.2 - April 9, 2025 - -Here's a summary of the updates and improvements in this release: - -* UI improvements for ui/portal/logbooks/outline-entry: show as two columns -* Improve Archive functionality for Contacts -* Improve field selection on admin/records/logbooks/add-fields -* Improve mandatory question warnings in Surveys -* Improve adding Program Tasks using dropdowns -* Improve Competencies on Dashboard -* Create new Added to Waitlist Alert -* Allow Body content to appear on Home pages -* Improve Gradebook feature of Add Learners to display and filter registration statuses -* Add 'Admin Notes' tab to surveys -* Implement Group Enrollment, as a Group -* Improve gradebooks search and outline to warn of locked gradebooks without achievements -* Improve Duplicate Survey to include Branches, Conditions and Respondent Attributes -* Hide \+ button on Class Outline page for certain Registration Statuses -* Display the Respondent Attribute if it was added to a survey question -* Improve Message Disabled functionality in Message toolkit -* Resolve a potential problem in our JSON serialization logic -* Remove ability to add Skill Rating during validation when no Skill Ratings are associated with Competencies -* Fix Admins can duplicate an Alert and edit Internal Name -* Improve the alignment of Action URLs and Controller Paths to toolkit naming conventions -* Move the delete button on Person Edit screen -* Add two new Statuses and change StatusSubCategory column name -* Add sentinel value to Message when Sender is deleted -* Implement IsIgnoredModifyFieldChange to ignore obsolete ModifyField changes -* Implement the universal entry point for all async method calls that need to be run synchronously -* Allow MFA and Password Reset notifications to be sent out of Sandbox and Dev -* Improve the Sites toolkit Visible Tabs field -* Implement method to add "Trial" badges to tiles -* Update the default text for Messages Content Authoring -* Fix JSON download for Surveys -* Implement API endpoints to generate cookie authentication tokens -* Improve new Recent feature to include dashboards and other improvements -* Investigate Mailgun Webhooks to improve deliverability reporting in Shift iQ -* Implement courses to the timeline engine -* Class creation improvements -* Add Survey as part of the Class registration process -* Fix problems on Survey Answer page -* Simplify AssemblyInfo source code files -* Update Microsoft App Registration Credentials - -## v25.1 - February 19, 2025 - -Here's a summary of the updates and improvements in this release: - -* Improve Standards So That The Type Of A Standard Is Determined By Its Depth In The Hierarchy That Contains It -* Implement Expand And Collapse All Hierarchy In Course Outline -* Improve Screen For Reviewing Users Requesting System Access -* Improve The Registrations Count In The Class Search Download -* Improve Calendar By Allowing Admins To Select The Color Of Appointments And Classes -* Improve Wording In Portal Class Registration Panel For Single Seat Classes -* Change When Temporary Passwords Are Assigned To Contact Records -* Add A Duplicate Button To The Content Tab And The Content Editor Screen -* Improve Registrantcontactinformationchanged Alert To Include Changes To Current Employer Of Participant -* Improvements To The Standard Outline Portal Page -* Add File Format Example For Markdown On The Add Set Page -* Allow Impersonations on MFA Mandatory contacts -* Retire Smartermail: All Outgoing Application Email Messages Must Be Sent Through Mailgun -* Improve Process To Create Senders -* Improve Composed Essay Question In Assessments To Hide Content Editor Features In Kiosk Mode -* Improve Direction Of Tab Key Navigation When Entering Scores In A Gradebook -* Improve Sites Search Page, Create Page And Outline Page -* Increase Character Limit To Employer/Program Field -* Improve Rubrics When Associated With Attempts -* Add Profile Picture Selection Functionality My Profile Screenv -* Use Timeline For The “Person History” -* Implement New Membership History Button On Membership Tab Of Contact Record -* Prevent Overwriting Of Personal Details During Class Waitlisting -* Implement Ability To Roll Up Competency Number Of Hours To Area In A Logbook -* Improve Force Complete Button On The Attempt View Page -* Improve Number Of Hours Column In Logbooks So Each Org Can Label It As Desired -* Implement A New Form That Helps Troubleshoot Data In The Standards Toolkit -* Add Org Setting To Display Or Hide Learner Name When Grading Attempts -* Add Org Setting For Assessment Attempt Re-Grade To Keep Or Reset Initial Scores -* Implement An Attempt View Page For Typing Speed And Data Entry Quizzes -* Replace Windows Authentication With SQL Authentication In All Environments For All Databases -* Improve Create New Standard Screen To Make Title A Required Field And Remove Ability To Modify Posted Date -* Improve Portal Classes Search Page To Add Search Field From Course Catalog Page -* Replace The Usage Of Non-Timeline Standards And Validations With The Timeline Version -* Improve Login Screen To Make Visibility Of MS/Google Buttons Org Setting -* Improve Message Variables For The Registrationinvitation Alert -* Improve Alert Editor To Display Message Variables -* Move Send Email Button In Contact Record -* Implement Around 3 Calendar Add-In In Shift iQ -* Implement A Validation Rule To Disallow Uploading Empty Documents -* Add Warning To Message Content Editor If Scheduled Mailout -* Align The Labels On Notifications Tabs In The Different Toolkits -* Change How Typing & Data Accuracy % Score Is Displayed On Gradebook -* Move The Delete Button On Assessment Attempts Search Screen And Re-Arrange Cards -* Rework Sitepacket Class To Make It Read-Only And Thread-Safe -* Refactor Examtaker Login Functionality -* Improve Achievements Search Screen To Add Person Code And Sort Options -* Improve Our Moodle Integration With Support For More Event Types -* Improve Group Search Screen URLs For Groups By Tag -* Add A Feature So We Can Enable/Disable Large Database Command Reporting To Sentry -* Improve The Database Command Monitor So It Captures The Identity Of The User And The URL Of The Page -* Add Organization Role Search Field To Criteria And Download Tab -* Improve Portal View Of Case For Candidate Attachments -* Add Case Type Finder To Portal Person Search Criteria Tab -* Remove Old Blockchain Pages, Alerts, And Contacts Download Columns -* Update Copyright Date To 2025 In All Website Page Footers -* Add Attendance Status And Date It Was Updated To Event Payments Report -* Configure An Octopus Pipeline To Refresh The Development And Sandbox Environments For Moodle -* Add Class Times To Class Search Results Grid -* Increase The SCORM Package Upload Limit From 250MB To 500MB -* Improve Navigation From The Edit Group Form So It Doesn't Update The URL -* Remove Unused Collections From Database And UI -* Improvements To Ui/Admin/Standards/Troubleshoot - -## v24.7 - December 18, 2024 - -Here's a summary of the updates and improvements in this release: - -* Improve Classes By Adding Registration Settings From Achievements -* Improve The Merge Process In Contacts To Include Comments -* Archive H5P Code From Shift iQ -* Implement A Categories Check Box List On The Manage Course Form -* Implement A Feature To Assign A Course To A Catalog -* Improvements To Portal Help UI -* Adjust The Binding Of The Accessrevokedby/Accessgrantedby Fields Of The Person Record -* Disable MFA For All Exam Login Screens -* Implement A New Search Form For Connections Between Users -* Retire Around V2 And V3.1 -* Improve Data Entry Quizzes To Allow Multiple Pages -* Implement Timeline (Standards) -* Identify And Archive Unused Nuget Packages -* Remove The Remaining References To System.Identitymodel.Tokens.Jwt -* Implement A Validation Rule To Disallow Uploading Empty Documents -* Improve The Navigation Menu On The Course Catalog Viewer -* Test And Debug Consolidated Screens For Programs -* Improve Survey Responses Search Screen -* Extract SCORM Cloud API Dependencies From The Shift Application Code -* Resurrect The UI Control That Displays Recently Visited Pages -* Improve Display Of Documents Grid -* Improve The Rendering Of Inline Help Content -* Option To Make MFA Default To Mandatory For All New And Existing Users -* Improve Item Scores Report And Add New Alternate Report -* Cosmetic Tweaks And Small Improvements To Our Public Facing Help Documentation For Shift iQ -* Add Approval Status To Registration Create Screen As A Dropdown Field -* Prevent Eligible Checkbox From Being Checked -* Improve The Portal Page Browser So It Supports The Catalog Layout Control -* Implement Support For Coloured Flags On Courses -* Improve Portal People Search So Filterable By Case Status -* Improve Case Search To Allow Bulk Close And Status Effective Date Searches -* Remove DOB, Middle Name, Address, And Phone Number From Prometric API -* Improve Portal Help Content Panel To Behave Like Admin Help Panel -* Remove All Remaining Blockchain Functionality -* Improve Portal Support Form To Prevent Duplicate Sends And Long Text Blocks -* Third Party Pen Test Reporting -* Improve The Uploads Search Screen -* Decrease Size Of Large Database Commands -* Create A New Database For The Remote Connection -* Find And Fix The Cause Of A Problem In The Timeline Command API -* Improve MFA Cookie -* Fix Error Message When Clicking On Sign-in Button On Website -* Investigate The Issue Why The Browser Does Not Use Cached CSS Files -* Fix Rendering Of Text Answers In Survey Responses Search Criteria -* Fix Registrationinvitationexpired Alert Problems -* Fix Date Modified Search Fields On Messages Search Screens -* Fix Prometric API Credentials Not Found -* Repair A Problem With Side Content Panel In The Portal -* Fix A Problem With The Query String On The Catalog Form -* Fix Lingering Issues With Message Placeholders Using Mailgun Sender - -## v24.6 - October 30, 2024 - -Here's a summary of the updates and improvements in this release: - -* Improve Help Text On New Survey Outline Instructions Subtab -* Hide The Input Fields For Assessment Specification Weight On Success/Failure -* Add Missing Option To Bulk-Expiry Tool For Credentials -* Relabel Issue To Case On Portal Screen -* Improve Regulator View Of Portal Search To Add Criteria For Documents -* Improve Workflow Attachment Requests So They Can Be Edited -* Investigate Timeline (Standards) -* Single-Question Quizzes Improvements -* Implement A New .NET 8 Console Application For Platform-Wide Maintenance Commands -* Test And Debug Microsoft Authentication -* Test And Debug Google Authentication -* Update Country List With Current ISO Standards -* Improve Survey Outline To Bypass Responses/Complete Step -* Remove Tradeworker Number Field From Contact Record -* Implement Options For Configuring Mandatory And Optional Breaks In A STATIC Assessment -* Prevent Paid Invoice From Being Deleted -* Improve Survey Question Panel So Questions With Large Numbers Of Options Are Collapsed -* Implement One-Click Unsubscribe Options For Marketing Emails Sent Through Shift iQ -* Improve Portal Response Review To Hide Branches They Didn't Travel Down -* Implement Help Text When Building An Assessment In Courses V2 -* Improve Prerequisite(S) In Courses To Provide More Info To Admin Doing Configuration -* Add An Option To Download Text Answers To Survey Report -* Improve Survey Form Contents Tab And Instruction Placement -* Fix And Improve Code Functionality In Course V2 -* An Operator Should Be Able To Archive (Delete) A Message Even When It Has Mailouts -* Fix Admins Can't Filter Survey Responses By Respondent -* Fix "Person Code" Reference On Contact Combine Screen -* Fix User Uploaded Docs To Another Users Case -* Fix System.Web.Httpunhandledexception GET /Ui/Portal/Assessments/Attempts/Answer -* Fix System.Web.Httpunhandledexception POST /Ui/Portal/Assessments/Attempts/Answer -* Solve A Problem With The Unarchive Feature -* Fix System.Web.Httpunhandledexception POST /Ui/Admin/Assessments/Questions/Analysis -* Drop Down Menu Formatting Error (Competency) On Workshop Pages -* Fix Revoke Access Feature In Accounts/Users/Search -* Fix System.Argumentexception POST /Api/Validate -* Fix Learner/Assessor Feedback Not Saved When Assessment Attempt Is Submitted -* Fix Timeline Post Randomly Failing -* Fix Missing Assessment Attempts Data -* Fix Occupation Field On The Job Opportunities Page -* Fix Sorting And Display Issue On The /Ui/Admin/Sales/Payments/Search Page -* Show The Class Schedule Card In The Catalog -* Repair A Display Problem For The Select Organization Link In The Navigation Menu -* Fix Image Usage In Assessment Bank -* Fix Display Issue When Completing Typing Speed Quiz -* Fix Cases Search And Download Errors -* Fix Field 'Startandenddates' Already Exists In Journal Setup - -## v24.5 - September 9, 2024 - -Here's a summary of the updates and improvements in this release: - -* Improve Case Attachments To Open In New Tab In Browser -* Improve Fault-Tolerance For Clock Skew In JSON Web Tokens Generated By Our Platform -* Improve Regulator View Of Portal Screens -* Remove Content Delivery Platform Options From Courses -* Resolve A Problem Caused By Faulty Logic In Microsoft's EDM Loader -* Implement Data Capture For A Typing Test -* Rename Issue To Cases -* Hide The Display Hierarchy Button On The Standard Outline Page -* Insert Tab For Question Creation And Editing -* Improve Build Message Function To Allow Selection Of Existing Newsletters As Templates -* Improve Assessment Attempt Analysis Report To Have Option To Include Pending Attempts -* Make The Billing Address On The Pay Invoice Screen Organization Specific -* Add Status To A Profile -* Add Print Button On Portal For Non-Event Purchases -* Add Person Code To Criteria And Download Tabs -* Improve The Assessment PDF Download To Include Likert Question Type -* Add Support For Adding An Online Meeting Link (Eg. Teams, Zoom) To Class Outline And RegistrationComplete Notification -* Implement Ability To Attach One Gradebook To Multiple Classes -* Prevent Paid Invoice From Being Deleted -* Improve Group Expiry And Group Membership Expiry Automation -* Display When A Rubric Is Attached To A Question In An Assessment Bank -* Improve Logbook Outline Admin Screen To Allow Groups To Be Assigned, In Addition To Individual Learners -* Implement Option To Automatically Generate An Invoice For Any User Joining A Group -* Improve Receipts To Add An Issued To Section And Rework Layout -* Improve Create And Edit Invoices -* Fix Spelling Error In Redirect URL In Messages Toolkit -* Fix Course Lesson Not Being Added Correctly -* Fix Survey Question Numbers Not Showing -* Fix Product Description Display Issue On Product Search Page -* Fix Product Image Not Updating After Uploading A New Image -* Fix Warning Messages In Surveys -* Fix Redirection When Clicking On Cases Under The More Info Button -* Fix Answer Points Column In The Assessment Attempt Analysis Report -* Fix Admins Can See Other Org Groups On Search And Reports Screen -* Fix Competency Not Saved When Moving Questions Between Assessment Sets -* Fix Response Session Starting For Closed/Archived Surveys -* Fix Edits And Regrades Do Not Save After Editing Existing Assessment Question -* Fix Timeout On /Ui/Admin/Messages/Emails/Search -* Fix The Bug In Cachepagestatepersister -* Fix Error Message That Appears When Making Edits On The Specification/Form Workshop Pages - -## v24.4 - July 10, 2024 - -Here's a summary of the updates and improvements in this release: - -* Improve Sitemap Tab Of Page Outline To Be Vertical Tree Structure -* Replace All Remaining From-Thru Criteria Fields With Since-Before -* Remove Required Fields For LXR Uploads -* Fixed Employer Not Recorded When Adding Yourself To Class Waiting List -* Fixed Achievement Expiry Date Not Showing When Manually Granting Achievement -* Fix Add Achievement Issues In Programs -* Fix The Sender For This Email Is Smartermail But Instead Must Be Mailgun. -* Include Rational Added To Questions -* Fix Document Not Set To Private When Uploading From The Portal -* Resolve Minor Issues With The User Session Search Page -* Fix When Event Max Capacity Is Set '0', Registrations Are Still Allowed -* Fix Instructor View Of Gradebook When No Users Are Assigned To A Class -* Fix Permission Matrix Download -* Fix Instructor Gradebook View -* Remove Warning Message If Specification Filter Type Is Not Used -* Fix The Cause Of An Unexpected Problem With Expired Credentialsv -* Fix Welcome Email Placeholders -* Remove Asset Type & # From Competency List -* Fix Warning Message Display Issue -* Fix Display Issue In An Assessment Bank -* Allow Users To Bypass The /Ui/Portal/Assessments/Attempts/Start Page When Starting An Assessment Request From A Course -* Fix Time-Sensitive Safety Certificate Expiry Notifications Are Not Carbon Copied To Followers -* Fix Spelling Error In Contact Record -* Fix Bank View Specification Question Limit Not Reflecting Changes On Workshop View Specification -* Fix Information Added To Fields Not Saving When Creating An Assessment Form -* Create A Query For Learners Who Meet The Criteria To Get Achievement But Weren't Granted Achievement -* Improve Class List Report And Instructor View To Include Class Times -* Create New Membershipreason Table To Allow For Multiple Referrals From Same Employer -* Save Grading Assessor Scoring On Next Button Click -* Improve Attachments Uploaded Via Survey Responses To Be Private By Default -* Improve Person Code So Each Org Can Label It As Desired -* Improve Validation Of Senders When Configuring Notification -* Search And Replace "<%#Eval(" -* Add Type Dropdown To Logbook Entry Screen -* Remove Asset Type & # From Competency List On New Logbook Entry -* Add Progress Bar To Each Line Of The Progress Panel On The Portal View Of A Logbook -* Add Download Button To Assessment Feedback Page -* Add Ability To Lock A Logbook -* Add Download Button To User/Portal View Of Logbook -* Add Search Criteria And Download Fields -* Implement Method For Attaching Images And Files To Messages That Is Supported By Mailgun -* Replace Smartermail Notification With Mailgun Notification In Attempthelper -* Improve Grading Assessor Search Page -* Add Exemplar To Composed Response Question Types -* Add Auto-Unlock For The Rubric When It Doesn't Have Related Attempts -* Add Ability To Duplicate A Rubric -* Second Iteration Of The Assessment Attempt Analysis Report Download -* Rename Second Tags In Standards Toolkit To Flags -* Improve The Upload People Page For Commonly Used Person And User Columns - -## v24.3 - May 22, 2024 - -Here's a summary of the updates and improvements in this release: - -* Increase the minimum number of characters required by our PasswordStrength Policy -* Display Help URL in action Search Results -* Replace the Font Awesome icon selector with a Text Box -* Add cancelled status back to class status list -* Display the link to view completed competencies on Home Page -* Add a session/view state timer to our Admin content editor screens -* Improve Unsubscribe page so users don't need password or system access -* Improve LXR upload function -* Improve contact report page to include cards for Surveys, Assessment Attempts and Issues -* Add Surveys tab for Issues created using a Survey -* Timeline (Contacts - Person) Implementation -* Timeline (Contacts - User) Implementation -* Implement conditions for release of Program Achievements on the Ui/Admin/Records/Programs/Outline page -* Improve code regarding Surveys in multiple Courses -* Improve the new build message feature on the Registrations search page -* Improve tab navigation in Assessments -* Improve Jobs experience and education entries to have country dropdown -* Upgrade from Around V2.4 to Around V3.2 -* Ad-Hoc Attempt Report should display scores when competencies are connected at answer option level -* Improve the Competency Progress Report so an alternate Framework can be selected -* Eliminate buffer tables for Learner Assessment Attempts -* Relabel the Invoice button in an Issue to More Info -* Continue initial implementation of Open Badges 1edtech Standard -* Add class time to RegistrationComplete alert -* Add class date and time to RegistrationInvitation alert -* Improve to display Employer at time of Registration instead of Current Employer -* Implement search function on Portal for users -* Improve Reports button in Contact Record -* Implement Grade Items panel for instructor view of Gradebooks -* Add download button to Aggregates/Outline page -* Improve Classes search by adding instructors as a search criteria -* Prevent overwriting of personal details during Class Registration -* Improve accessibility of Assessment feedback by adding checkmarks and X's to indicate correct and incorrect responses -* Improve adding comments on Admin/Assessments/Questions/Change page - -## v24.2 - April 3, 2024 - -Here's a summary of the updates and improvements in this release: - -* UI Improvements for third-party assessments -* Fix minor scrolling issue on ui/admin/courses/managev -* Fix Links Feature in Messages Toolkit -* Fix Markdown Content Editor Create Link & Insert Image buttons -* Fix Survey Closed Instructions not displaying to respondents -* Improve search criteria for third party assessments -* Country Combobox Values now are Guid instead of texts -* Fix 3rd party Assessment not allowed multiple attempts -* Fix No redirection on Program tiles -* Fix error when uploading set using Markdown -* Improve Survey Message Configuration so Admin can return to Survey Messages tab when done -* Improve the reliability of the certificate builder -* Fix bug in the multi-select question type -* Improve Logbook Edit Entry screen with the same changes as the Add Entry screen -* Improve the portal support form -* Fix UI elements not pulling translated text from labels table -* Hide all references to Fax number from our UI -* Fix Rubrics Delete page URL incorrect -* Fix Not able to update Rubric with no Assessment Attempts -* Fix Learner Permissions for adding a Logbook Entry -* Fix translation issue on learning portal -* Automatically enable the email address for new candidates loaded from Direct Access -* Create Assessor view of Attempt Grade page -* Fix Points not showing in Question metadata when scoring is done by rubric -* Introduce authorization for CommandApi through OAuth2 (JWT token) -* Make the configuration setting for course outline width visible in the Admin UI -* Allow randomization of automated group-membership assignment to survey respondents -* Modify automatic group membership assignment for survey respondents -* Allow an administrator to enable/disable learner comments on a course -* Improve Survey Question text so admin side displays like portal side -* Standard (Competency) External Title -* Re-implement the validation improvements when new exam events are scheduled through the API -* Resolve minor issues on the Course Catalog page -* Remove confusing URLs from organization account settings -* Rework functionality for Assigning Gradebooks to Assessments -* Implement performance optimizations -* Improve History pages to move Aggregate info to a tab and visible to platform admins only -* urvey Outline Messages Tab: Rename "Assign Messages" button and add Edit Pencil -* Implement ability to build a Message from Class Registrations search page -* Refactor MFA -* Move Question Difficulty field from Banks Search to Questions Search -* Add Country list dropdown from Jobs to Contact Addresses as a Find modal, not a combobox -* Add Accommodations to Class Events (currently only in Exam Events) -* Survey Outline Messages Tab: Rework Add Newsletter buttons be Add Notification buttons -* Improve how Employer is displayed in Contact Record history -* Implement the solution for the ordering question type -* Add a history to a gradebook -* Assign an assessment attempt to a grading assessor -* Add Download button to aggregates/outline page -* Improve posted date for comments in the Assessment and Classes Toolkits -* Fix Surveys so new Options Questions are added to unlocked response sessions -* Add ability for admins to download a copy of a learner's certificate -* Survey Outline Messages Tab: Add a preview of message content -* Improve Portal Support page and related Help Requested alert message - -## v24.1 - February 14, 2024 - -Here's a summary of the updates and improvements in this release: - -* Hide Private Option From Comments In Contacts -* Review CRM API Call For Individual Event -* Increase Pin Size For Hotspot Questions -* Allow Multiple Select Responses For Hotspot Questions -* Enable "Not Eligible" Prometric API Call -* Remove Action Required Section From Applicant Portal -* Display Occupational Interest Field In Class Registrations -* Improve Prometric Start URL To Allow Inclusion Of Person Code And Exam Password -* Add A Group Function Criteria Filter To /Ui/Admin/Contacts/Memberships/Search -* Improve The Layout Of The Request Data And Response Data When Viewing API Log Entries -* Updates To The NCAS/Prometric API Call -* Pull Incoming API Call From Smarterstats -* Pull Incoming API Call From Smarterstats -* Display Person Code On Profile -* Improvements To Document Functionality -* Allow Shift.API To Use Custom Port Numbers -* Improvements To The Assessment Attempt Analysis Report Download -* Restrict Ability To Start An Exam Or Survey If The Related Gradebook Is Locked -* Registration Search: Improve Downloads Tab -* Programs Improvements -* Add Employer To Auto-Created Issues -* Add Ad Hoc Message Template To Issue Send Correspondence -* Add A Message Variable To The Messages Toolkit -* Automatically Add Users To Group When Added On People/Create Page -* Remove "Are You Sure You Want To Progress" Warning -* Add Privacy Settings To A Class -* Implement The Solution For A New Assessment Question Type: Audio Recording (Composed Voice) -* Update How Rubrics Are Displayed On The Attempt View Page -* Add Request Candidate Contact Button To Ui/Portal/Jobs/Employers/Candidates/View Screen -* Implement Configurable Option To Link Survey Question Or Completion To Invoice Creation -* Simplify Issue Comments -* Improve How Competency Frameworks Can Be Modified For Logbooks -* Standardize The Breadcrumb Trails On The Portal -* Add Person Code To The Event Registration Payments Report -* Display The Area For The Competency Assigned To A Question -* Jobs Improvements -* Improvements To My Dashboard So It Is Configurable By Organization -* Add Search Fields To Assessments Attempts Search Page -* Improve Event Status Tags To Have In Progress Based On Class Dates, Not Gradebook Attachment -* Improve Ui/Portal/Accounts/Change-Password Screen -* Implement Ability To Hide Register Employees Button For Classes -* Improve /Ui/Survey/Respond/Search To Be Like Other Portal Search Screens -* Replace Collection Color Picker And Enable It To Display In UI Competency Frameworks - -## v23.7 - December 6, 2023 - -Here's a summary of the updates and improvements in this release: - -* Built-In Link To The Progress Report And Scores To The Course Outline Page In The Portal -* Course Prerequisites - All Determiner And Grade Item Failed -* Fix Typo On Waitlist Invitation Expired Warning -* Add A Label For Tasks Achievements -* Display All Task Related Learners Achievements In The Achievement Tab -* Automate Blockchain.Ui Build And Deployment Using Build Mapping -* Automate Shift.Api Build And Deployment Using Build Mapping -* Automate Engine.Api Build And Deployment Using Build Mapping -* Improvements To The Add To Waitlist Page -* Remove Courses V1 Code From Shift iQ -* Improvements To /Ui/Admin/Standards/Documents/Analysis -* Improvements To Standalone Assessments -* Add Prometric Integration To The UI -* Change The Portal/Issue Permission To Point At Member, Not Owner -* Relabel Contact Code To Person Code -* Move Content Tab To First Position On Message Outline -* Display Who Registered Or Waitlisted A User For A Class -* Change Instrument Dropdown Options -* Programs I Improvements -* Implement A New Assessment Question Type: Hot Spot (Image Captcha) -* Streamline Layout Of Job Candidate Admin Screen -* Align Action Urls To Toolkit Names (Portal) -* Extend The Time Limit For MFA -* Improve User Creation Options On /Admin/Accounts/Organizations/Edit -* Change Contacts Search Screen So It Defaults To Not Archived - -## v23.6 - October 25, 2023 - -Here's a summary of the updates and improvements in this release: - -* Connect Assessment Attempt Answers To Gradebook Grade Items -* Add Difficulty To Search Criteria On Banks -* Modify Summary Tab On Assessment Form -* Modify Summary Tab On Assessment Banks -* Add Question Type To Question Search Criteria -* Standards Analysis Improvements - Text Matching -* Improve Job Candidates For Use By Other Customers -* Improve Job Opportunities For Use By Other Customers -* Add Tiles For Message Types To /ui/admin/messages/home -* Implement Reporting For Competencies Tied To Answer Options In Assessments -* Implement Solution To Display Assessment Questions In A Grid (Similar To Likert Questions) -* Implement A Feature For Third-Party Assessment Of A Learner -* Add Item To Issue History -* Add Sales To Contact Record And Issues -* Improvements To Invoices Search Page On Portal -* Add Columns To The Invoices Search Page -* Improvements To Drafting Invoices -* Program Outline Improvements - Add A Content Tab -* Implement The Portal UI For Programs -* Improve The Admin UI For Programs -* Add Passing Score Settings To Information Displayed On Grade Items Grid -* Integration With Prometric -* Improve Course Completed Notifications To Be Configurable -* Implement New Method Publish An Assessments On Portal -* Implement Ability To Ignore A Score From Calculation -* Improve System Access Tab On Person Editor Screen - -## v23.5 - August 30, 2023 - -Here's a summary of the updates and improvements in this release: - -* Allow Survey Respondent Attribute Values To Reference Home Address Fields -* Eliminate Possible Synchronization Problems With Our Appsettings.Json Config File -* Dashboard Fixes For V23.5 -* Update Tradeworker ID To Person Code On The Event Registration Search Page -* Improve The Handling For Unexpected Exceptions That Occur In The Direct Access API -* Investigate How To Display Assessment Questions In A Grid (Similar To Likert) -* Modify The Multi-Correct Question Type To Allow Us To Relate Answer Options To Competencies -* Allow Assessment Authors To Assign An Assessment Question And A Question Option To Any Competency In The Framework -* Investigate Use Of Tags And Labels In UI -* Update The Code That Interfaces With The Direct Access API -* Add An API Method For CRM To Add A New Exam Event Outside The Context Of A Candidate Registration -* Ensure The Rapid Test Server Logs Exceptions To Sentry -* Modify The Default Height Of Combo Box Modals -* Modify The API For Registration Of New Exam Event Candidates -* Replace ITA Tradeworker Number With Person Code When Merging Contacts -* Add Fields To The Issue Comment Screen -* Enforce Input Rules Around Learner ID Or Tradeworker Number During Registration -* Add Tradeworker Number Field To Person Editor UI -* Use A Survey To Open A New Issue -* Tighten Security On The Production Server -* Improvement To Change Invoice Details Page -* Improve "Sections As Tabs" Feature In Assessments Forms To Display One Question At A Time -* Link Attachments Between Issues And Person/Edit So They Show On Both -* Add Send Email To Issue /Ui/Admin/Issues/Send-Email -* Rename Registration Counters In Events Toolkit -* Implement A New Form In The Portal To Add A New Contact Person -* Implement A Feature That Allows Users To Retake An Assessment After Successfully Completing it -* Jobs Improvements / Fixes -* Clarify Search Workflow -* Add Left Hand Panels On Portal -* Move The New Button On Portal Screens Over To The Activity Menu -* Change Breadcrumb Trail & Page Name To Show Specific Document Type -* Remove Download Button From NOS Tool -* Secure Access To Survey Response Sessions, Started And Locked -* Modify Privacy On Issue Comments -* Add Search Criteria To Admin/Assessments/Question/Search -* Add Schedule Mailout Button To Mailouts Tab -* Upgrade Admin Forms To Bootstrap 5 23.5.1 -* Get An H5P Demo Fully Operational In Shift -* Rework Reports Home Screen -* Improve Pagehelper.Autobindheader Function -* Implement Improvements To Posted Date For Comments -* Improvements To 'Edit Progress' For Boolean Scores In Gradebooks -* Hold Seat For Waitlisted User When Invitation Is Sent To Register For A Class -* Move New Button When Creating Blocks In Sites Toolkit -* Move Payments And Invoices To New Class When Leaner Is Moved -* Implement Improvements To Rubrics To Support Searching Of Composed Response Questions -* Implement My Assessments Panel For My Dashboard -* Improve Administration Features In The Events Toolkit -* Implement Functionality For An Admin/Instructor To Grade Composed Response Questions In Shift -* Enforce Privacy Settings In Courses V2 At The Course Level - -## v23.4 - June 14, 2023 - -Here's a summary of the updates and improvements in this release: - -* Implement A Feature To Allow An Administrator To Grant An Achievement For A Logbook -* Move Buttons At Top Of Contact Record Screen -* Translate Message Content Into Multiple Languages -* Send Email Notification When An Issue Owner Is Changed -* Add Date Fields To Survey Response Search Page -* Add Download Button To Learner Grades Page -* Improve Integration Between Contacts And Messages -* Improve The UI For Adding Comments To A Person -* Allow Each Referrer To View Their Own Contact People -* Use Issues To Manage Account Status Workflows -* Add New Criteria For Searching People -* Associate A Default Language With A User -* Attach Existing Gradebooks To Classes -* Include The Order Number On Invoice/Receipt -* Simplify The Order Number -* Improve The Logbook Entry Search Form -* New Prerequisite Type: All Prerequisite Must Be Fulfilled To Trigger An Activity -* Implement Method For Admins To Edit Survey Responses -* Add A New Portal Form That Allows Employers To View More Information About Employees -* Implement A Feature To Display Related Assessment Questions In Separate Tabs - -## v23.3 - May 5, 2023 - -Here's a summary of the updates and improvements in this release: - -* Improve Assessments In Courses V2 When Multiple Attempts Are Allowed. -* Fix Modify/Created Dates In Job Opportunities -* Hide Option To Delete Question Versions -* Upgrade Admin Forms To Bootstrap 5 -* Fix Event Link On /Ui/Admin/Events/Registrations/Search -* Fix Date Selector Not Clearing When Removing Date -* Fix Jobs/Candidates/Search Screen -* Implement Improvements To The New API Endpoint For Microsoft CRM -* Add Person Code And Email To Downloads Tab -* Implement Support For A More Robust Version Numbering Convention -* Hide The Option To Open SCORM Content In An Embedded Frame -* Improve Multiple Language Support For Document And Video Activities Inside Courses -* Improve The Address Panel On The Edit Person Form -* Employers Status As At Time When The Credential Was Granted In Achievement Report -* Add Categories To Class Registrations -* Additional Search Criteria In Class Registrations -* Improve Download Button For Survey Feedback -* Remove "New" Button From The UI For Courses V1 -* Remove Course V1 Test Drives From Shift iQ -* Display All Achievements In Courses, Not Just Ones With A Certificate Layout -* Implement Solution For Embedded Camera Access Directly Through Toolkits -* Improvements And Fixes To My Dashboard -* Improve Assessment Question Delete Page -* Add Key Settings To Create New Survey Form -* Track Who Did The Registration For An Event/Class -* Improvements To Registrations In Events -* Hide Period Filter Dropdown If Hide Period Is Checked -* Implement Ui/Portal/Attempts/Search - -## v23.2 - March 24, 2023 - -Here's a summary of the updates and improvements in this release: - -* Improve Access Control Rules For Jobs Toolkit Forms In The Portal -* Distinguish Candidate Portfolio From Employer Company Profile -* Upgrade Admin Outline Page From B3 To B5 23.2.2 -* Plan API Improvements For Microsoft CRM Integration -* Jobs Toolkit: Portal/Jobs/Employers/Candidates - Update The Following Custom IECBC UI Pages To Work With The New DAL -* Candidate Options For Portal/Jobs/Candidates/My-Portfolio -* Candidate Screens For Their Portfolio And For Opportunities View/Search/Apply -* Portal/Jobs/Employers Candidate Search And View Screens -* Jobs Toolkit: Portal/Jobs - Implement A New ASP.NET Master Page To Be Used For New And Upgraded Portal Forms In This Toolkit -* Jobs Toolkit: Admin/Jobs - Upgrade The Following Admin UI Pages From B3 To B5 And Ensure They Work For Both Jobconnect And FAST Job Boards -* Jobs Toolkit: Admin/Accounts/Users - Implement A New Form To Facilitate The Review And Approval Of New User Accounts -* Jobs Toolkit: Admin/Standards/Occupations - Add New Input Fields For Industry And A User-Friendly Alias -* Jobs Toolkit: Admin/Contacts/Groups - Add New Input Fields For Industry, Email, And Web Site -* Jobs Toolkit: Admin/Contacts/Groups - Implement The Photos Panel -* Jobs Toolkit: Admin/Contacts/Groups - Add A Multi-Select Check Box List For Group Tags -* Jobs Toolkit: Database - Implement Database Schema Improvements -* Upgrade Admin Outline Page From B3 To B5 23.2.1 And 23.2.2 -* Implement Possibility To Define Or Edit Phone On Ui/Portal/Mfa -* Add Group Status As A Search Criteria In Achievements -* Upgrade Admin/Records/Programs/Outline From Bootstrap 3 To 5 -* Fix Font View Issue On The Portal When Viewing Assessments -* Implement Solution To Add NA Option To Number Fields On Surveys -* Upgrade Ui/Desktops/Custom/Iecbc/Jobconnect/Myprofile/View.Aspx And Edit -* Implement Notifications Triggered By Course Completed Or Course Stalled -* Reconcile Standards/Documents/Search Fields With Search Result Columns -* Migrate Admin/Messages/Contents/Edit Page From MVC To Web Forms -* Person/Edit/Files: Throttle Image Size -* Implement Social Integration / Sharing Of Achievements On Linkedin. - -## v23.1 - February 10, 2023 - -Here's a summary of the updates and improvements in this release: - -* Hide Admin Link from Admin Master Page -* Add Icons for CMDS Master Page -* Upgrade Outline Pages to Bootstrap 5 -* Implement Ability to Create and Display Events Via a Calendar for Admin 23.1.2 -* Hide Test Drive from Ui/Admin/Courses/Home -* Implement UI Revisions to Logbooks -* Refactor the Authentication Code on The Sign in Form -* Critical Improvements and Fixes to My Dashboard 23.1.1 -* Rename Urls for Groups and Standards Outline Into "Manage" -* Implement Ability to Create And Display Events Via A Calendar on Portal -* Add Home Button to Portal -* Add the Number of Search Result on Search Results Page -* Improvements to Labels on MFA Screen -* Implement SAML SSO -* Add Portal Site to Breadcrumb Trail -* Implement the First Iteration of an Equation Editor -* Reword Warning on /Admin/Messages/Subscribers/Delete -* Upgrade Design Certificate Page Into Bootstrap 5 -* Remove Password Expiry Reminder Functionality From /Ui/Portal/Profile -* Implement an Admin Screen to Allow Upload of a SCORM Package to SCORM Cloud Via API -* Implement Ability for an Admin to Remove Enrollments From a Course -* Consolidate Membership Fields on Details and Settings Tabs -* Add Breadcrumbs With Links Instead Of Subtitle on Portal Start Attempt Page -* Possibility to Get Statistics (Count, Sum, Mean and Etc.) on Columns Report Builder -* Implement Timeline for Contact Groups - -## v22.8 - December 16, 2022 - -Here's a summary of the updates and improvements in this release: - -* Class Now Displayed on the Class Registration List Until the End of the Registration Deadline Date and Time -* UI Improvements for Ui/Admin/Events/Exams/Search -* Improvements to Download Panel -* Implemented Bracketed Percentage Prerequisite in Courses v2 -* Blockchain Transaction Coordinator -* Upgrade Search Pages to Bootstrap 5 -* Implemented Improvements to Assessments -* Integrate Into the Course Outline Page a New Feature to Upload a Microsoft Word Document and Convert to Markdown, Using Pandoc -* Move Access Granted to Person Table so Granting Access to One Org Doesn't do Same to Another Org -* Fix Indexing Issues On www.Shiftiq.Com Website -* Improvements to Blockchain Implementation -* Hide Global Admin Contact Records From Tenant Contact Toolkits -* Implement Improvements to 'Edit Progress' Function in Gradebooks -* Enable & Enforce Module-Level & Unit-Level Prerequisites in the Portal UI -* Upgrade Portal/Attempts UI From Bootstrap V3 To V5 -* Add Google Map Support for Admin/Contacts/People/Report Page -* Improvements to Timeline Engine for Contacts -* Improvements in Assigning Gradebook Periods -* Replace Tenant with Organization -* Implement Ability to Search For Users in a Gradebook -* Implement Logbook Notifications -* Modify the Code so That all Alert Messages are Sent Using Mailgun Rather Than Smartermail -* Improvements for Student Grades Report - Add Learning Mastery (Outcomes) Area -* Add Possibility to Save/Upload Conditions for Reports -* Began Implementation of Micro-Credentials and My Dashboard -* Rename Resources Labels into Achievements On Customer Screens - -## v22.7 - November 4, 2022 - -Here's a summary of the updates and improvements in this release: - -* Add Toggle to Learner Activity Report to Switch Between Learners and Courses -* Remove "New [Object]' Links on Dashboard (Home) Toolkit Pages -* Implement a New Web Form to Convert Files from Microsoft Word to Markdown -* Change labels of panels on /ui/portal/profile -* Optimize JS and CSS Resource Bundling -* Improvements to Blockchain Implementation: -* Improvements to Verification Webpage UI -* Improve Certificate Publication Process in Admin Pane -* Add Internal Transaction Processing Service -* JC Connect Employer Role to Custom JC Employer Table -* Implement Bootstrap 5 Search Pages -* Upgrade Admin/Programs/Help to Bootstrap 5 -* Rework Outcomes Panel on Person Edit Page -* Update API to Send No Show Information to Internal Systems -* Indicate When a Candidate has a Training Provider Contact Added to their Registration -* Build ARC Exam Confirmation Emails -* Prevent Editing of Published Questions in Bank > Outline (Questions panel and Forms panel) -* Scheduling UI Improvements -* Search Exams Scheduled by Form Name on the Events > Exams and Events >> Registrations page -* Bank Commentaries Page - Search Criteria and Download additions -* Upgrade Portal/Attempts UI from Bootstrap v3 to v5 -* If Validators Could Add Learners Also Have Ability to Delete Them -* Different Ways to Show Empty Panel's Content on Person Edit -* Add "Add Newsletter" Button on Survey Outline -* Move Fields from Users table to Persons Table -* Add Achievement Label to Filter Credentials -* Implement JSON Upload and Download of All Assets in Courses v2 -* Make Picking One Slider Mandatory for New Registrants -* Improvements for Students Grade Report - Header of Report -* Implement Download|Upload JSON for Standards Settings - -## v22.6 - September 23, 2022 - -Here's a summary of the updates and improvements in this release: - -* Marks Sent to Training Providers - Show the Number of Questions in a Form -* Online Exam SEB Browser Confirmation -* Make Requirement That All Class Events Need to Have a Training Provider Contact -* Bar Chart of GAC Averages or of Competency Averages -* Select a Training Provider and Display All Exam Writes: By Form Name Written by Candidates Associated with That Training Provider -* Add "Jump to Question" Function on Bank Commentaries Page -* Default Search Criteria in Portal Documents to Display Documents Only -* Add Pop-Up Modal Window to Documents: Add Competencies Screen -* JC Fix Employer Records to Remove Custom Tables -* If an Exam is Changed from Online Exam to Paper 'Expected Distribution Date' Should Appear on JSON File Sent to BC Mail Plus -* Disable OK Button After Successful Upload of Exam Attempt with Warning Message -* Add Search Criteria in Add Ons: BC Mail Distributions Search Criteria to Include 'Expected Distribution Date' -* Add Search Criteria in Add Ons: BC Mail Distributions Search Criteria to Include 'Undistributed Exams' That Have Passed the 'Expected Distributed Exam Date' -* Default Search Criteria in Portal Documents to Display Documents Only -* Add Onto Detailed Rental Day Report -* Add Link to Create Occupational Profile from the Job Comparison Tool -* Simplify Invoice/Receipt Number -* Add Support of Period on Gradebook Creation -* Download Button Should be Disabled When No Certificate is Attached to an Achievement -* Implement Translated Glossary Terms to Show in English Content -* Show Scores (and Outcomes) Counters on Records Dashboard -* Give Admins Ability to Change Payment Status and Payment Date -* Integrate into Gradebooks Outline Page Outcomes Panel and Show There the Content of Learning Mastery Page for the Gradebook -* Improve Workflow to Publish a v2 Course to Portal -* Limit the Number of Hours a Learner Can Enter for a Competency to the Number of Hours for the Overall Log Entry -* Enable Validation Requirement in Logbook Setup -* Continue to Upgrade V1 to V2 courses for Tenants: General Courses v2 Improvements - * Default Passing Score in Gradebook Overwrites Assessment Score. - * When Adding a New Gradable Activity to a Gradebook from Activity Setup: Records the System Should Take Defaults from the Assessment Setup - * Change Language on "Course Outline" Button - * Implement Courses v2 Learner Enrollment -* Logbooks UI - * Add Filter on Logbooks Assigned - * A Learner is Not Able to Delete an Invalidated Logbook Entry - * Learners Logbooks Counter Only Counts Logbooks if They Have a Result - * Implement Validator's Instructor's Logbooks (Search) Screen - * Implement Validator's Logbook Screen - Possibility to Add Learners - * Implement View Screen for Validated (or Locked) Log Entry - * Implement Delete Validator Screen - * Implement Validator's Search Journals Screen - * Implement Validator's Logged Entries Search - * Implement Validator's Logged Competencies Search - -## v22.5 - July 29, 2022 - -Here's a summary of the updates and improvements in this release: - -* Have Screen Stay in the Same Place When User Deletes a Competency From the Document -* Improvements for Student Count by Trades Report -* Set BC As Default Province for Class Registration -* Select Radio Button Value in Seats Panel of Portal Class Registration if Only One is Available for Selection -* Show City for Employer in Brackets in Dropdown List -* Improvements for Admin/Contacts/Groups/Search -* Allow Search on Users Who Have Been Granted an Achievement -* Add Option to Override Attempt Completed Field When Marking -* Creation of Parent Training Provider with Campuses Associated -* Remove Space Between Exam ID and Asset Number in Distribution JSON Record -* In the Forms Tile - Add a Filter to View Only Unpublished Forms -* In the Asset Table - Show on Which Form the Question Appears -* In the Question Tile- Add a Filter to View Questions That Have Been Edited Within a Specified Time Period -* In Workshop Views- Add a Filter to View Only Questions That Have Been Edited Within a Specified Time Period/Per Form/ Per Bank -* Omit Anything Except Lowest Level Competencies from Bulleted Lists -* Add Tooltips to The Document > Content > Edit Screens on The Portal -* Auto-fill Purpose of Job field in Job Description -* Pricing Options Settings: Track If it was Self-Registration or on Behalf -* Following Fields Are Now Editable in Published Assessment Forms - * Form Tab: Form Name, Code, Hook/Integration Code - * Content Tab: Content Title, Summary, Diagram Book, Reference Materials, Materials for Distribution / Online. - * Addendum: Attachments - -## v22.4 - June 17, 2022 - -Here's a summary of the updates and improvements in this release: - -* Improvements To Select Uploaded Image Window When Editing a Question -* Add Bank Search: Active and Inactive -* Reports: Show the Number of Questions in The Form (per GAC & per Competency) -* Add "Jump to Question" for Comments on The Bank View > Comments Panel -* Candidate Comments Link: Create an Icon on the Left Side Instead in the Workshop Pages -* Improve & Integrate New Programs Tool -* Introduce Periods for Gradebooks -* Auto-Select Framework When Adding Competencies to a Document -* Add Trash Icon to All Competency Levels in the Competencies Panel of the Document -* Set The Portal Print Defaults to Match the Default Print Settings on The Admin Screen -* Implement Second Iteration of Standards Framework Content Edit Features for Courses II -* Allow One Person to Register Multiple People with a Single Payment -* Generate Email Address Field Value for New Contacts Without Email -* Logbooks User Interface Improvements -* Implement: Snapshot feature for Admin/Registrations/Classes/Search -* Add Occupation Profile as Option Under the Relationships Panel -* Improve & Integrate New Programs Tool -* Expand the Download Section by Default -* Add Bank Status: Active & Inactive -* Improvements to Select Uploaded Image Window When Editing a Question -* Implement Triggers to Assign Users to Specific Groups Based on Trigger Criteria -* Region & Registrations (Add Region to Search Criteria) -* Automate the Assignment of Members to Students & Apprentices Groups -* Change Shipping Location and/or Physical Location of Exam -* Learning Centre Student-Body Report -* Summary Class Lists Report diff --git a/releases/README (2).md b/releases/july-16-version-25.4-is-live.md similarity index 97% rename from releases/README (2).md rename to releases/july-16-version-25.4-is-live.md index aa96eac..78b5189 100644 --- a/releases/README (2).md +++ b/releases/july-16-version-25.4-is-live.md @@ -2,7 +2,7 @@ description: Version 25.4 was released to the Production environment today --- -# July 16: Version 25.4 is live! +# July 16: Version 25.4 is live This next update introduces a series of meaningful improvements that reflect ongoing enhancements to the platform, along with feedback we've received from customers. Each change is designed to improve visibility, reduce unnecessary steps, and give you more control across key workflows. diff --git a/releases/README (2) (1).md b/releases/july-9-version-25.4-in-pre-release.md similarity index 100% rename from releases/README (2) (1).md rename to releases/july-9-version-25.4-in-pre-release.md diff --git a/releases/README (1).md b/releases/june-20-welcome-to-the-changelog.md similarity index 100% rename from releases/README (1).md rename to releases/june-20-welcome-to-the-changelog.md diff --git a/releases/may-2025/may-28-version-25.3-is-live.md b/releases/may-2025/may-28-version-25.3-is-live.md index 7680efa..a719d68 100644 --- a/releases/may-2025/may-28-version-25.3-is-live.md +++ b/releases/may-2025/may-28-version-25.3-is-live.md @@ -2,7 +2,7 @@ description: Version 25.3 was released to the Production environment today --- -# May 28: Version 25.3 is live! +# May 28: Version 25.3 is live Here's a summary of the updates and improvements: diff --git a/releases/README (4).md b/releases/oct-29-version-25.6-is-live.md similarity index 66% rename from releases/README (4).md rename to releases/oct-29-version-25.6-is-live.md index 1d7eb38..8ca9bc1 100644 --- a/releases/README (4).md +++ b/releases/oct-29-version-25.6-is-live.md @@ -2,7 +2,7 @@ description: Version 25.6 was released to the Production environment today --- -# Oct 29: Version 25.6 is live! +# Oct 29: Version 25.6 is live This update includes meaningful improvements across workflows, catalogs, and logbooks, reflecting ongoing enhancements to the platform and feedback from our customers. Each change focuses on simplifying day-to-day tasks, improving visibility, and maintaining the platform’s reliability. @@ -19,8 +19,6 @@ This update includes meaningful improvements across workflows, catalogs, and log These updates make the Shift iQ platform even more responsive and efficient for both administrators and learners. -➡️ [Click here to view the full release notes](https://dm96xp04.na3.hubspotlinks.com/Ctc/DR+113/dM96xP04/VX3c782fqvv2W6Y6CB25F6KJTW97gBTk5FdkRyN3Bm-6Y5kBVzW5BWr2F6lZ3lXW40403-6NDnzHW5n7s6T5Jv9LRW3K4Cds5HSnnqW6yc5926WYBC-W7d0Psq2LkJT2VKVstv2twTN8W77xdz62kdKtqW3L_GHB7Ch8-NW3VCyZ97psx8vTPT-h1QqDt2W1RmWBB5V0ssVN3XGHzGb7WhYW1cMtJB1N0kLVW8SxYVR3SG81fW1qpZhF8y81zgW2Ggpkn8WZHzFW4pR_3L4R-YQMW6YHGX52JV2-KW3_GLS-4dZf5zN504bkhjKmMxW1vb0Dx1qNmRdW3k7XCX8b_GmXW6ZNsZp7bmJy8N2Q4Rd48-QnWW5BKrqg3XVP0vW7ScDvD61lx_1W4k9DwY96knDHN5WN7SJY12qyW84Qnzv1yymJvN8Qf9YFws3JtW1m9FmN6kvCwwW91x_4S4VBNCLW91MRLz74TMB0W4_yl9Q4xq6ptf90bJbC04) - **Next Release** * Shift iQ version 25.7 is scheduled for release on December 17. diff --git a/releases/README (3).md b/releases/sep-10-version-25.5-is-live.md similarity index 86% rename from releases/README (3).md rename to releases/sep-10-version-25.5-is-live.md index 82828a2..5ac1741 100644 --- a/releases/README (3).md +++ b/releases/sep-10-version-25.5-is-live.md @@ -2,10 +2,10 @@ description: Version 25.5 was released to the Production environment today --- -# Sep 10: Version 25.5 is live! +# Sep 10: Version 25.5 is live -This latest release includes many improvements driven by direct feedback from our community. These include: +This latest release includes many improvements driven by direct feedback from our community. These include: * More class and event registration search features for easier sorting and filtering * Improved functionality for the setup and customization of training registration workflows -* New features for developers and integrators to generate and refresh their own API access tokens \ No newline at end of file +* New features for developers and integrators to generate and refresh their own API access tokens diff --git a/staff/README.md b/staff/README.md index fa7665c..0cfced3 100644 --- a/staff/README.md +++ b/staff/README.md @@ -1,3 +1,9 @@ +--- +description: Private workspace for internal Shift iQ staff notes +--- + # Staff -Testing... +This space holds private, internal notes for Shift iQ staff. Pages here are not part of the public help center and may be incomplete, out of date, or experimental. + +If you are looking for contributor documentation, see the [Contributors](../contributors/README.md) space instead. diff --git a/staff/SUMMARY.md b/staff/SUMMARY.md index 18ee643..1e252ce 100644 --- a/staff/SUMMARY.md +++ b/staff/SUMMARY.md @@ -1,3 +1,11 @@ # Table of contents * [Staff](README.md) + +## Job descriptions + +* [Technical Job Descriptions](job-descriptions/README.md) +* [Chief Technology Officer](job-descriptions/chief-technology-officer.md) +* [DevOps Engineer](job-descriptions/devops-engineer.md) +* [Software Developer](job-descriptions/software-developer.md) +* [Software Engineer](job-descriptions/software-engineer.md) diff --git a/staff/job-descriptions/README.md b/staff/job-descriptions/README.md index 965b482..f6d94e1 100644 --- a/staff/job-descriptions/README.md +++ b/staff/job-descriptions/README.md @@ -1,3 +1,9 @@ +--- +description: >- + The roles that make up a technical group at Shift iQ, plus the distinction + between software developer and software engineer +--- + # Technical Job Descriptions A technical group is typically comprised of these roles (listed alphabetically): diff --git a/staff/job-descriptions/chief-technology-officer.md b/staff/job-descriptions/chief-technology-officer.md index 4a63304..47e368a 100644 --- a/staff/job-descriptions/chief-technology-officer.md +++ b/staff/job-descriptions/chief-technology-officer.md @@ -1,3 +1,7 @@ +--- +description: The Chief Technology Officer leads the company to effectively use technology to meet its objectives. +--- + # Chief Technology Officer ### Summary diff --git a/staff/job-descriptions/devops-engineer.md b/staff/job-descriptions/devops-engineer.md index 4cd1ec9..d6cc461 100644 --- a/staff/job-descriptions/devops-engineer.md +++ b/staff/job-descriptions/devops-engineer.md @@ -1,3 +1,7 @@ +--- +description: The DevOps Engineer uses their understanding of computer hardware and software infrastructure, cloud computing, application development, and +--- + # DevOps Engineer ### Summary diff --git a/staff/job-descriptions/software-developer.md b/staff/job-descriptions/software-developer.md index da9453e..42b2e8b 100644 --- a/staff/job-descriptions/software-developer.md +++ b/staff/job-descriptions/software-developer.md @@ -1,3 +1,7 @@ +--- +description: Software developers use their knowledge of programming languages to design and implement software applications. +--- + # Software Developer ### Summary diff --git a/staff/job-descriptions/software-engineer.md b/staff/job-descriptions/software-engineer.md index 4c61d9e..df252ad 100644 --- a/staff/job-descriptions/software-engineer.md +++ b/staff/job-descriptions/software-engineer.md @@ -1,10 +1,14 @@ +--- +description: Software engineers use engineering principles to design, develop, maintain, test, and evaluate software, including computers or other devices +--- + # Software Engineer ### Summary Software engineers use engineering principles to design, develop, maintain, test, and evaluate software, including computers or other devices containing software. They are knowledgeable in multiple programming languages. Typically, software engineers use their science and math skills to analyze problems and develop solutions methodically. -Software engineers create, execute, and manage all components of a producte during the development lifecycle. This responsibility also requires them to communicate and delegate tasks within a team. Collaboration is essential to deliver functioning and effective software adequately. They may also be responsible for refining past designs to correct defects or address new and changing client needs. +Software engineers create, execute, and manage all components of a product during the development lifecycle. This responsibility also requires them to communicate and delegate tasks within a team. Collaboration is essential to deliver functioning and effective software adequately. They may also be responsible for refining past designs to correct defects or address new and changing client needs. ### Essential Skills @@ -33,7 +37,7 @@ To ensure the end product meets the clients' and users' expectations, software e | Recommend policy and procedure changes to improve operations | Recommend policy and procedure changes to improve operations | Conduct systems analysis and recommend policy and procedure changes to improve operations | |

Architecture

| | | | Develop a persistent and creative approach to problem-solving | Develop a persistent and creative approach to problem-solving | Develop a persistent and creative approach to problem-solving. | -| Suggest improvements to the web architecture for our products. | Improve opon the web architecture for our products. | Assist with defining and implementing improvements to the platform's architecture and infrastructure. | +| Suggest improvements to the web architecture for our products. | Improve open the web architecture for our products. | Assist with defining and implementing improvements to the platform's architecture and infrastructure. | | Follow documented best practices to ensure system coherence, scalability, and development efficiency | Suggest improvements to system coherence, scalability, and development efficiency. | Help evolve the architecture and infrastructure of the system to ensure coherence, scalability, and development efficiency. | |

Implementation

| | | | Assist with development of API | Under direction of the senior engineer, develop and maintain new back-end and front-end features | Develop and maintain new back-end and front-end features. | diff --git a/starters/README.md b/starters/README.md index e701a32..38a0056 100644 --- a/starters/README.md +++ b/starters/README.md @@ -3,7 +3,7 @@ description: Welcome to the Shift iQ documentation portal. icon: book-open --- -# Welcome! +# Welcome This is your home base for everything you need to understand, use, and integrate with **Shift iQ**. Whether you're just getting started or you are a seasoned power user, this portal is designed to help you navigate our platform with confidence. diff --git a/topics/.gitbook/assets/font-color-html-tag-example-1.png b/topics/.gitbook/assets/font-color-html-tag-example-1.png new file mode 100644 index 0000000..dbad225 Binary files /dev/null and b/topics/.gitbook/assets/font-color-html-tag-example-1.png differ diff --git a/topics/.gitbook/assets/font-color-html-tag-example-2.png b/topics/.gitbook/assets/font-color-html-tag-example-2.png new file mode 100644 index 0000000..a53e3a0 Binary files /dev/null and b/topics/.gitbook/assets/font-color-html-tag-example-2.png differ diff --git a/topics/.gitbook/assets/font-color-html-tag-rendered.png b/topics/.gitbook/assets/font-color-html-tag-rendered.png new file mode 100644 index 0000000..2fea2b7 Binary files /dev/null and b/topics/.gitbook/assets/font-color-html-tag-rendered.png differ diff --git a/topics/.gitbook/assets/survey-answer-options-color-rendered.png b/topics/.gitbook/assets/survey-answer-options-color-rendered.png new file mode 100644 index 0000000..f427c09 Binary files /dev/null and b/topics/.gitbook/assets/survey-answer-options-color-rendered.png differ diff --git a/topics/.gitbook/assets/survey-bold-italic-rendered.png b/topics/.gitbook/assets/survey-bold-italic-rendered.png new file mode 100644 index 0000000..8221c91 Binary files /dev/null and b/topics/.gitbook/assets/survey-bold-italic-rendered.png differ diff --git a/topics/.gitbook/assets/survey-bold-italic-source.png b/topics/.gitbook/assets/survey-bold-italic-source.png new file mode 100644 index 0000000..8bcf476 Binary files /dev/null and b/topics/.gitbook/assets/survey-bold-italic-source.png differ diff --git a/topics/.gitbook/assets/survey-question-text-color-edit.png b/topics/.gitbook/assets/survey-question-text-color-edit.png new file mode 100644 index 0000000..347afd7 Binary files /dev/null and b/topics/.gitbook/assets/survey-question-text-color-edit.png differ diff --git a/topics/.gitbook/assets/survey-question-text-color-rendered.png b/topics/.gitbook/assets/survey-question-text-color-rendered.png new file mode 100644 index 0000000..79e2c12 Binary files /dev/null and b/topics/.gitbook/assets/survey-question-text-color-rendered.png differ diff --git a/topics/SUMMARY.md b/topics/SUMMARY.md index e97a753..6853682 100644 --- a/topics/SUMMARY.md +++ b/topics/SUMMARY.md @@ -270,6 +270,6 @@ * [Download Responses](surveys/survey-responses/download-responses.md) * [Survey Reporting](surveys/survey-responses/survey-reporting.md) -## Sales +## Billing * [Sales](sales.md) diff --git a/topics/_SUMMARY_.md b/topics/_SUMMARY_.md deleted file mode 100644 index d1c8223..0000000 --- a/topics/_SUMMARY_.md +++ /dev/null @@ -1,274 +0,0 @@ - -## Assessments - -* [Overview](assessments/overview.md) -* [Creating Banks and Question Sets](assessments/create-bank/README.md) - * [How to use the Assessment Toolkit](assessments/create-bank/how-to.md) - * [Creating a new bank](assessments/create-bank/create-new-bank.md) - * [Adding Questions](assessments/create-bank/add-question.md) - * [Choosing Question Types](assessments/create-bank/question-types.md) - * [Download and Uploading Assessment Banks](assessments/create-bank/exam-json.md) - * [Create Tables within Assessment Questions and Answers Options](assessments/create-bank/create-tables.md) - * [Downloading Assessment Sets (*.md)](assessments/create-bank/downloading-sets.md) - * [Upload Assessment Sets](assessments/create-bank/upload-assessment-sets.md) - * [Set Question Settings, Rationale and Prerequisites/Triggers](assessments/create-bank/question-settings.md) - * [How to Print a Question Bank/Assessment Form to PDF](assessments/create-bank/print-bank-pdf.md) - * [Reordering Questions and Sets](assessments/create-bank/reordering-questions-and-sets.md) -* [Creating Exam Specifications & Forms](assessments/specifications-forms/README.md) - * [Using Specifications](assessments/specifications-forms/using-specifications.md) - * [Creating a Specification](assessments/specifications-forms/creating-specification.md) - * [Applying Specification Criteria](assessments/specifications-forms/specification-criteria.md) - * [Creating a Form](assessments/specifications-forms/creating-a-form.md) - * [Adding Questions to a Form](assessments/specifications-forms/add-questions-form.md) - * [Adding Reference Materials to a Form](assessments/specifications-forms/reference-materials.md) - * [Creating Tabs in an Assessment Form](assessments/specifications-forms/creating-tabs.md) - * [Adding Timers to Tabs](assessments/specifications-forms/adding-timers-to-tabs.md) -* [Editing Assessment Questions and Forms](assessments/editing-forms/README.md) - * [Review exam Form details prior to publishing](assessments/editing-forms/review-exam-form.md) - * [Advanced question searches](assessments/editing-forms/search-for-questions.md) - * [How to publish an assessment form](assessments/editing-forms/publish-exam-form.md) - * [How to test an Exam Form](assessments/editing-forms/test-exam-form.md) - * [Pre-Publish an Assessment Form](assessments/editing-forms/pre-publish-exam-form.md) - * [Edit Assessment Questions](assessments/editing-forms/edit-questions.md) - * [Manually Analyze Assessment Attempts](assessments/editing-forms/analyze-exam-attempts.md) - * [Working with Images in Assessments](assessments/editing-forms/editing-images.md) -* [Safe Exam Browser (SEB)](assessments/safe-exam-browser/README.md) - * [Organization Checklist for SEB errors](assessments/safe-exam-browser/seb-error-checklist.md) -* [Moving Assessment Banks (and retain Competency mapping)](assessments/moving-assessment-banks.md) -* [Single-Question Quizzes](assessments/single-question-quizzes/README.md) - * [Typing Speed Quiz](assessments/single-question-quizzes/typing-speed-quiz.md) - * [Data Entry Quiz](assessments/single-question-quizzes/data-entry-quiz.md) - * [View Single-Question Quiz Attempts](assessments/single-question-quizzes/single-question-attempts.md) - -## Contacts - -* [Overview](contacts/overview.md) -* [Adding New Contacts](contacts/adding-new-contacts/README.md) - * [Upload Contacts](contacts/adding-new-contacts/upload-contacts.md) - * [User Self-Registration](contacts/adding-new-contacts/user-self-registration.md) - * [Adding access to bulk upload contacts](contacts/adding-new-contacts/bulk-upload-contacts.md) -* [Creating and Managing Groups](contacts/group-management/README.md) - * [Create a New Group and Adding People to the Group](contacts/group-management/adding-new-group.md) - * [Editing or Deleting Groups](contacts/group-management/edit-groups.md) -* [Editing Contacts](contacts/editing-contacts/README.md) - * [Adding Impersonate Permission](contacts/editing-contacts/impersonate-permissions.md) - * [Password Resets](contacts/editing-contacts/password-resets.md) - * [Searching Contacts](contacts/editing-contacts/searching-contacts.md) - * [Review and Edit a Contact](contacts/editing-contacts/review-details.md) - * [Understanding Permissions and Roles](contacts/editing-contacts/edit-permissions.md) - * [Access Control and Roles Settings](contacts/editing-contacts/access-control.md) - * [Archive Users](contacts/editing-contacts/archive-users.md) - -## Courses - -* [Overview](courses/overview.md) -* [Creating and Editing Courses](courses/create-course/README.md) - * [How to Add and Remove Units, Modules and Lessons in a Course](courses/create-course/adding-lesson.md) - * [Publishing a Course to your Learner Portal](courses/create-course/publish-course.md) - * [Setting Prerequisites](courses/create-course/setting-prerequisites.md) - * [Setting up Course Notifications](courses/create-course/course-notifications.md) - * [Adding Hyperlinks and Videos](courses/create-course/add-hyperlinks-videos.md) - * [Changing font color of the Course](courses/create-course/changing-font-color.md) - * [Adding Privacy Settings to a Course](courses/create-course/course-privacy-settings.md) - * [Adding a Course Image](courses/create-course/adding-course-image.md) -* [Adding and Editing Lesson Content](courses/add-content/README.md) - * [Add Course Content](courses/add-content/add-course-content.md) - * [Adding Images](courses/add-content/adding-images.md) - * [Adding Links](courses/add-content/adding-links.md) - * [Adding an Embedded Video](courses/add-content/embedding-video.md) - * [Add New Lesson From Microsoft Word](courses/add-content/lesson-from-word.md) -* [Working with SCORM and Shift iQ Courses](courses/scorm-courses/README.md) - * [How to Upload a SCORM Course to SCORM](courses/scorm-courses/upload-scorm-course.md) - * [SCORM Cloud connection settings](courses/scorm-courses/scorm-settings.md) - * [Embedding a SCORM package in your Shift iQ Course](courses/scorm-courses/adding-scorm-courses.md) - * [Uploading SCORM with different Languages](courses/scorm-courses/scorm-multi-lingual.md) - -## Events - -* [Overview](events/overview.md) -* [Schedule a New Exam Event](events/schedule-exam/README.md) - * [Create a New Exam Event](events/schedule-exam/create-a-new-exam-event.md) -* [Schedule a New Class](events/schedule-new-class/README.md) - * [How to Create a New Class](events/schedule-new-class/create-class.md) - * [Add and Edit Class Information](events/schedule-new-class/class-information.md) - * [Manually Adding/Removing Registrations](events/schedule-new-class/adding-registrations.md) - * [Assign Gradebook to Class](events/schedule-new-class/assign-gradebook.md) - * [Add Seating to a Class](events/schedule-new-class/add-seating-to-class.md) - * [Adding Content](events/schedule-new-class/adding-content.md) - * [Class Privacy](events/schedule-new-class/class-privacy.md) - * [Class Settings](events/schedule-new-class/class-settings.md) - * [Publish Class Registration](events/schedule-new-class/publish-class-registration.md) - * [Adding Class Registration Tile on Portal Page](events/schedule-new-class/add-registration-tile.md) -* [Using Classes for Exam setup](events/classes-for-exams/README.md) - * [Assign Assessments](events/classes-for-exams/assign-assessments.md) - * [Login Credentials for Exam](events/classes-for-exams/login-credentials-for-exam.md) - * [Exam Login Page](events/classes-for-exams/exam-login-page.md) -* [What Learners see on the Class Registration Portal Page](events/class-registration.md) - -## Cases - -* [Overview](cases/overview.md) -* [Creating Cases](cases/creating-cases.md) -* [Editing Cases](cases/edit-cases/README.md) - * [Search for an Case](cases/edit-cases/search-case.md) - * [View Case History](cases/edit-cases/case-history.md) - * [Download Case JSON File](cases/edit-cases/download-case-json.md) - * [Send Email from an Case](cases/edit-cases/send-email-from-case.md) - * [Case Reports](cases/edit-cases/case-reports.md) -* [Case Documents](cases/case-documents.md) -* [Case Comments](cases/case-comments/README.md) - * [Adding Comments](cases/case-comments/adding-comments.md) - * [Editing and Deleting Comments](cases/case-comments/editing-comments.md) - -## Jobs - -* [Overview](jobs/overview.md) -* [Candidates](jobs/candidates.md) -* [Employers](jobs/employers.md) -* [Job Opportunities](jobs/job-opportunities.md) -* [Job Applications](jobs/job-applications.md) - -## Messages - -* [Overview](messages/overview.md) -* [Sending mailouts](messages/sending-mailouts/README.md) - * [Schedule Delivery](messages/sending-mailouts/schedule-delivery.md) - * [Delivery Report](messages/sending-mailouts/delivery-report.md) -* [Managing recipients](messages/managing-recipients/README.md) - * [Add Subscribers/Recipients](messages/managing-recipients/add-recipients.md) - * [Create new Mailing List](messages/managing-recipients/new-mailing-list.md) - * [Unsubscribe from Messages](messages/managing-recipients/unsubscribe.md) -* [Authoring messages](messages/authoring-messages/README.md) - * [Create New Message](messages/authoring-messages/create-new-message.md) - * [Markdown Reference](messages/authoring-messages/markdown-reference.md) - * [Message Placeholders](messages/authoring-messages/message-placeholders.md) - * [Editing and Formatting Message Contents](messages/authoring-messages/edit-contents.md) -* [Organizing messages](messages/organizing-messages/README.md) - * [Search for existing Message](messages/organizing-messages/search.md) - -## Records - -* [Overview](records/overview.md) -* [Creating and Configuring Gradebooks](records/gradebooks/README.md) - * [Creating a New Gradebook](records/gradebooks/new-gradebook.md) - * [Editing Gradebook Settings](records/gradebooks/gradebook-settings.md) - * [Adding and Configuring Grade Items](records/gradebooks/grade-items.md) - * [Managing Learners in a Gradebook](records/gradebooks/learners-gradebook.md) - * [Learner Progress and Scores](records/gradebooks/gradebook-scores.md) - * [Gradebook Achievements](records/gradebooks/gradebook-achievements.md) - * [Gradebook Comments and Periods](records/gradebooks/gradebook-comments-periods.md) - * [Instructor Gradebook Views](records/gradebooks/instructor-gradebook.md) -* [Creating and Granting Achievements](records/achievements/README.md) - * [Create New Achievement Template](records/achievements/define-achievement.md) - * [Editing Achievement Templates](records/achievements/edit-achievement-template.md) - * [Manually Granting Achievements](records/achievements/manually-grant-achievement.md) - * [Achievement Layouts for Printed Certificates](records/achievements/achievement-layouts.md) - * [Searching and Editing Achievements](records/achievements/search-edit-achievements.md) -* [Programs and Periods](records/programs-and-periods/README.md) - * [Purpose of Programs and How to Create Them](records/programs-and-periods/create-program.md) - * [Editing and Managing Programs](records/programs-and-periods/edit-program.md) - * [Creating and Managing Gradebook Periods](records/programs-and-periods/gradebook-periods.md) -* [Working with Logbooks](records/logbooks/README.md) - * [Creating New Logbooks](records/logbooks/create-logbooks.md) - * [Managing Logbook Settings and Content](records/logbooks/edit-logbooks.md) - * [How Learners Create and Edit Logbook Entries](records/logbooks/logbook-entry.md) - * [Validating Logbook Entries](records/logbooks/logbook-validation.md) -* [Blockchain Certificate Management](records/blockchain/README.md) - * [Overview of Shift iQ's Blockchain Based Certificate Manager](records/blockchain/certificate-manager.md) - * [Creating and Connecting a Blockchain Wallet to Shift iQ](records/blockchain/blockchain-wallet.md) - * [Login With Blockchain](records/blockchain/login-with-blockchain.md) - -## Sites - -* [Overview](sites/overview.md) -* [Creating Beautiful Web Sites and Learner Portals](sites/new-portal/README.md) - * [Host and Edit a Public Website using Shift iQ](sites/new-portal/create-website.md) - * [Have One or More Portals for Your Customers](sites/new-portal/create-portal.md) - * [Creating Contents for Your Sites](sites/new-portal/create-site-contents.md) - * [Using the Sitemap tab to Navigate Site Administration](sites/new-portal/sitemap.md) - * [Add Portal Tile Pictures or Icons](sites/new-portal/tile-pics.md) - * [List of Portal Tile URLs Customers will Love](sites/new-portal/portal-tile-urls.md) -* [Publishing and Privacy Settings](sites/publish-privacy/README.md) - * [Portal Permissions](sites/publish-privacy/portal-permissions.md) - * [Publishing Site Pages](sites/publish-privacy/publish-site-page.md) -* [Managing Website and Portal Contents](sites/edit-site-contents/README.md) - * [Adding and Editing Site and Block Content](sites/edit-site-contents/content-editing.md) - * [Adding Images](sites/edit-site-contents/adding-images.md) - * [Adding a Hyperlink to Images](sites/edit-site-contents/adding-url-to-images.md) - * [Adding Links](sites/edit-site-contents/adding-links.md) - * [Upload Document](sites/edit-site-contents/upload-document.md) - * [Delete Site Page](sites/edit-site-contents/delete-site-page.md) - * [Preview Contents](sites/edit-site-contents/preview-contents.md) - * [Adding an Embedded Video](sites/edit-site-contents/adding-video.md) - * [Customized Help Requests](sites/edit-site-contents/portal-support-customize.md) - * [Changing URLs and Page Slugs](sites/edit-site-contents/change-url.md) - -## Standards - -* [Overview](standards/overview.md) -* [Creating Standards](standards/create-standards/README.md) - * [Options for Adding Standards](standards/create-standards/add-standard.md) - * [Manage Frameworks using the Outline View](standards/create-standards/manage-standards-outline.md) - * [Framework settings and details](standards/create-standards/framework-settings.md) -* [Managing and Editing Standards](standards/edit-standards/README.md) - * [Manually enter alternate language text](standards/edit-standards/alternate-language.md) - * [Numbering a Single Standard](standards/edit-standards/number-single-standard.md) - * [Re-order in the Outline view](standards/edit-standards/re-order-in-outline-view.md) - * [Searching Standards](standards/edit-standards/searching-standards.md) - * [Bulk update numbering](standards/edit-standards/bulk-update-numbering.md) - * [Delete in Outline view](standards/edit-standards/delete-in-outline-view.md) - * [Reorder within a Standard](standards/edit-standards/reorder-within-standard.md) - * [Use Google Translate to enter alternate language text](standards/edit-standards/use-google-translate.md) - * [Change Standard Type](standards/edit-standards/change-standard-type.md) - * [Occupations](standards/edit-standards/occupations.md) - * [Competencies in a document print in an illogical structure](standards/edit-standards/competencies-print.md) -* [Relationships](standards/relationships/README.md) - * [Types of relationships](standards/relationships/types-of-relationships.md) - * [Add a relationship](standards/relationships/add-a-relationship.md) - * [Remove downstream relationships](standards/relationships/remove-downstream.md) - * [Remove upstream relationships](standards/relationships/remove-upstream.md) -* [Creating and Editing Documents](standards/documents/README.md) - * [Publishing Documents on the Portal](standards/documents/publish-document.md) - * [Translation Tips](standards/documents/translation-tips.md) - * [Printing and Downloading](standards/documents/printing-and-downloading.md) - * [Working in the Administrator View](standards/documents/administrator-view.md) - * [Publishing Document Analysis Tools on the Portal](standards/documents/document-analysis.md) - -## Surveys - -* [Overview](surveys/overview.md) -* [Configuring survey questions](surveys/question-configuration/README.md) - * [Question Types](surveys/question-configuration/question-types.md) - * [Likert Questions](surveys/question-configuration/likert-questions.md) - * [Configure Radio Button, Dropdown, or Check Box Questions](surveys/question-configuration/configure-option-questions.md) - * [Edit, Copy or Delete a Question](surveys/question-configuration/edit-question.md) - * [Adding a Break Question](surveys/question-configuration/adding-a-break-question.md) - * [Adding a Break Page](surveys/question-configuration/adding-a-break-page.md) - * [Terminating a Survey](surveys/question-configuration/terminating-a-survey.md) - * [Adding Videos and Hyperlinks](surveys/question-configuration/add-videos-hyperlinks.md) - * [Replacing a Survey Question in an existing Survey](surveys/question-configuration/replace-question.md) - * [Changing Fonts and Colors](surveys/question-configuration/changing-fonts-and-colors.md) -* [Creating survey forms](surveys/create-survey/README.md) - * [Download Survey in JSON (*.json) format](surveys/create-survey/download-surveys.md) -* [Configuring a survey form](surveys/configure-survey-details/README.md) - * [Details Tab](surveys/configure-survey-details/details-tab.md) - * [Searching for a survey](surveys/configure-survey-details/searching-surveys.md) - * [Survey Outline](surveys/configure-survey-details/survey-outline.md) - * [Translations Tab](surveys/configure-survey-details/translations-tab.md) - * [Conditions Tab](surveys/configure-survey-details/conditions-tab.md) - * [Branches Tab](surveys/configure-survey-details/branches-tab.md) - * [Summaries Tab](surveys/configure-survey-details/summaries-tab.md) -* [Managing survey invitations](surveys/survey-messages/README.md) - * [Survey Invitation](surveys/survey-messages/survey-invitation.md) - * [Workflow Notifications](surveys/survey-messages/workflow-notifications.md) -* [Providing instructions to respondents](surveys/instructions-respondents/README.md) - * [Adding Home/Return to Course buttons at end of Survey](surveys/instructions-respondents/adding-buttons.md) -* [Managing survey responses](surveys/survey-responses/README.md) - * [Search Responses](surveys/survey-responses/search-responses.md) - * [View Responses](surveys/survey-responses/view-responses.md) - * [Download Responses](surveys/survey-responses/download-responses.md) - * [Survey Reporting](surveys/survey-responses/survey-reporting.md) - -## Sales - -* [Sales](sales.md) diff --git a/topics/assessments/create-bank/README.md b/topics/assessments/create-bank/README.md index 007c73d..a77a6bc 100644 --- a/topics/assessments/create-bank/README.md +++ b/topics/assessments/create-bank/README.md @@ -1,4 +1,8 @@ -# Creating Banks and Question Sets - -Question Banks are used to organize collections of related questions that are to be used together on an exam form. -They may be organized by competency, standard, topic, occupation, course, program or any grouping that best reflects your assessment needs. +--- +description: Question Banks are used to organize collections of related questions that are to be used together on an exam form. +--- + +# Creating Banks and Question Sets + +Question Banks are used to organize collections of related questions that are to be used together on an exam form. +They may be organized by competency, standard, topic, occupation, course, program or any grouping that best reflects your assessment needs. diff --git a/topics/assessments/create-bank/add-question.md b/topics/assessments/create-bank/add-question.md index b748c05..bd8994d 100644 --- a/topics/assessments/create-bank/add-question.md +++ b/topics/assessments/create-bank/add-question.md @@ -1,20 +1,26 @@ -# Adding Questions - -Questions in an Assessment Bank must belong to a **set** in the Bank, and the Bank must contain **at least one set** before questions can be added. A Bank can contain **multiple sets** with multiple questions in each set. Sets are typically used to organize questions in a bank by competency **Area** of a **Standard Framework**, but can also be used to organize questions in other ways, if desired. +--- +description: Questions in an Assessment Bank must belong to a set in the Bank, and the Bank must contain at least one set before questions can be added. +--- + +# Adding Questions + +Questions in an Assessment Bank must belong to a **set** in the Bank, and the Bank must contain **at least one set** before questions can be added. A Bank can contain **multiple sets** with multiple questions in each set. Sets are typically used to organize questions in a bank by competency **Area** of a **Standard Framework**, but can also be used to organize questions in other ways, if desired. **Creating a Set:** + * Click on the Questions tab, then click on the Add button on the right hand side of the screen. * Select Set to create the first question set. * Add your Set Name (This name uniquely identifies this question set within the bank) and click the Save button. -* The question set has now been created and details for the set will be displayed. +* The question set has now been created and details for the set will be displayed. **Creating Questions in a Set:** + * Click on the Add button and select Question. * Select a [**Question Type**](/help/assessments/create-bank/question-types) -* Input the Question text, including uploading any [**images**](/help/assessments/editing-forms/editing-images) -* Input any text and/or images for each of the Question Answer Options. - * Point Values and Cut Scores may be provided for each answer. -* Additional answer options can be added by clicking on the **Add new option** button. +* Input the Question text, including uploading any [**images**](/help/assessments/editing-forms/editing-images) +* Input any text and/or images for each of the Question Answer Options. + * Point Values and Cut Scores may be provided for each answer. +* Additional answer options can be added by clicking on the **Add new option** button. * Click the **Save** button to save your changes. -The question has now been created will be displayed. [**Changes**](/help/assessments/editing-forms/edit-questions) can be made to the question by selecting the **Edit** icon. Continue adding questions and sets as needed to populate the bank. +The question has now been created will be displayed. [**Changes**](/help/assessments/editing-forms/edit-questions) can be made to the question by selecting the **Edit** icon. Continue adding questions and sets as needed to populate the bank. diff --git a/topics/assessments/create-bank/create-new-bank.md b/topics/assessments/create-bank/create-new-bank.md index 7cd4420..478f999 100644 --- a/topics/assessments/create-bank/create-new-bank.md +++ b/topics/assessments/create-bank/create-new-bank.md @@ -1,5 +1,9 @@ -# Creating a new bank - +--- +description: Question Banks are used to organize collections of related questions that are to be used together on an exam form. +--- + +# Creating a new bank + Question Banks are used to organize collections of related questions that are to be used together on an exam form. They may be organized by competency, standard, topic, occupation, course, program or any grouping that best reflects your assessment needs. Select **Assessments** Toolkit on the portal homepage and then select the **Banks** Counter. @@ -9,11 +13,13 @@ At the top of the **Search Banks** page, click on **Add New Bank**. ![add-bank.png](https://e02.insite.com/files/sites/e02/create-new-bank/add-bank.png) From the dropdown menu at the top of the page you are able to select one of the following options: + * **One new bank:** Create a brand new Assessment Bank from the beginning. -* **Duplicate copy of existing bank:** If you have an existing Assessment Bank you wan to use as your framework, you can duplicate the existing bank. +* **Duplicate copy of existing bank:** If you have an existing Assessment Bank you wan to use as your framework, you can duplicate the existing bank. * **Upload one new bank from file:** Assessment banks can by uploaded by using a JSON File -If you selected to create **One new bank**, complete the following fields: +If you selected to create **One new bank**, complete the following fields: + 1. **Bank Type:** In the Bank Type Field, Advanced is preselected as this is the only option currently available. 2. **Add Bank Title (Required Field):** A descriptive user-friendly title for the bank. 3. **Add Bank Name (Required Field):** A short name that identifies the bank internally for filing purposes. @@ -22,6 +28,7 @@ If you selected to create **One new bank**, complete the following fields: 6. Select **Save**. If you selected to create a **Duplicate copy** of existing bank, complete the following fields: + 1. **Bank:** Select the Bank from the dropdown list that you want to duplicate. 2. **Bank Type:** In the Bank Type Field, Advanced is preselected as this is the only option currently available. 3. **Add Bank Title (Required Field):** A descriptive user-friendly title for the bank. @@ -31,17 +38,19 @@ If you selected to create a **Duplicate copy** of existing bank, complete the fo 7. Select **Save**. If you selected to **Upload one new bank from file**, complete the following fields: -1. Click on the **Magnifying Glass** icon next to the **Select and Upload Bank JSON File** field and select the JSON file. -2. Once file is selected, it the content of the JSON file will be displayed in the **Uploaded JSON** field. + +1. Click on the **Magnifying Glass** icon next to the **Select and Upload Bank JSON File** field and select the JSON file. +2. Once file is selected, it the content of the JSON file will be displayed in the **Uploaded JSON** field. 3. Select the **Save** button for the Assessment Bank to be uploaded and created. ![upload-json-file-2.png](https://e02.insite.com/files/sites/e02/create-new-bank/upload-json-file-2.png) -The Bank has now been created and details for the bank will be displayed under the Bank tab of the Assessment. -Changes can be made to editable fields on this page. +The Bank has now been created and details for the bank will be displayed under the Bank tab of the Assessment. +Changes can be made to editable fields on this page. + * **Standards:** The formal standard evaluated by questions in the bank * **Bank Name:** The name that uniquely identifies the bank for internal filing purposes * **Level:** The type and number for a discrete skill level * **Edition:** The edition of this bank (e.g. Year and Month) * **Bank Title:** The descriptive title for the bank -* **Summary:** The purpose or executive summary for the bank +* **Summary:** The purpose or executive summary for the bank diff --git a/topics/assessments/create-bank/create-tables.md b/topics/assessments/create-bank/create-tables.md index de4413d..de65779 100644 --- a/topics/assessments/create-bank/create-tables.md +++ b/topics/assessments/create-bank/create-tables.md @@ -1,3 +1,7 @@ +--- +description: Columns can be created within an Assessment Question and the Answer Options.\ +--- + # Create Tables within Assessment Questions and Answers Options Columns can be created within an Assessment Question and the Answer Options.\ @@ -5,13 +9,13 @@ To add columns to the Assessment Question, use the below template/formula:\ Column 1 | Column 2 | Column 3 | Column 4--|--|--|--Column 1 | Column 2 | Column 3 | Column 4Column 1 | Column 2 | Column 3 | Column 4Column 1 | Column 2 | Column 3 | Column 4Column 1 | Column 2 | Column 3 | Column 4Column 1 | Column 2 | Column 3 | Column 4\ \*\*\*\ Question will display as follow:\ -![](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table.png)\ +![Assessment questions table](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table.png)\ \ To add columns in the Answer Options, use the | symbol to create the columns.\ \ Example:\ A. 1|in.B. 10|in.C. 5|in.D. 15|in.\ -![](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-1.png)\ +![Assessment questions table 1](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-1.png)\ \ In the Settings Panel when editing a question, below Option Layout, select Table from the drop down menu. Click on the Add New Column button to create the columns. Select the Alignment (Left, Right or Center) and add the column Style. Select Save after changes were made.\ Style Options: @@ -23,11 +27,11 @@ Style Options: * x-wide\
-![](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-4.png)\ +![Assessment questions table 4](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-4.png)\ \ \ The Answer Options will display as follow:\ -![](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-5.png)\ +![Assessment questions table 5](https://e02.insite.com/files/sites/e02/create-tables/assessment-questions-table-5.png)\ \ \ Names can be added to the columns in the Answer Options by adding the headings in the Name field under Option Layout.
diff --git a/topics/assessments/create-bank/downloading-sets.md b/topics/assessments/create-bank/downloading-sets.md index 0e0c890..134e2d2 100644 --- a/topics/assessments/create-bank/downloading-sets.md +++ b/topics/assessments/create-bank/downloading-sets.md @@ -1,3 +1,7 @@ +--- +description: Select the Assessment Toolkit from the Admin Home Page. +--- + # Downloading Assessment Sets (\*.md) #### Downloading Assessment Sets (\*.md) @@ -12,4 +16,4 @@ Once Assessment bank is selected, click on the **Question** tab. Click on the Download button and select **# Shift iQ Markdown Outline (\*.md)** -The **Markdonw (\*.md)** file will be downloaded to the **Download** folder on your computer.
+The **Markdown (\*.md)** file will be downloaded to the **Download** folder on your computer.
diff --git a/topics/assessments/create-bank/exam-json.md b/topics/assessments/create-bank/exam-json.md index 5046886..4da4ca7 100644 --- a/topics/assessments/create-bank/exam-json.md +++ b/topics/assessments/create-bank/exam-json.md @@ -1,5 +1,9 @@ -# Download and Uploading Assessment Banks - +--- +description: Select the Assessment Toolkit from the Admin Home Page. +--- + +# Download and Uploading Assessment Banks + ## Downloading an Assessment Bank to a JSON file Select the **Assessment** Toolkit from the Admin Home Page. @@ -8,7 +12,7 @@ Select the **Banks** counter. Search for the **Bank** you want to duplicate and select the bank in the **Results** panel. -Click on the **Bank Name** to open the Assessment. +Click on the **Bank Name** to open the Assessment. When the Assessment bank is open, click on the **Download JSON** button. You will be redirected to the Download confirmation page. Review the information and click on **Download** button. @@ -24,4 +28,4 @@ Select **Upload one new bank from file** from the dropdown menu at the top of th Click on the magnifying glass icon () next to the **Select and Upload Bank JSON File** field and select the downloaded **JSON** file you want to upload. -Click the **Save** button. +Click the **Save** button. diff --git a/topics/assessments/create-bank/how-to.md b/topics/assessments/create-bank/how-to.md index 922aac6..c41c78c 100644 --- a/topics/assessments/create-bank/how-to.md +++ b/topics/assessments/create-bank/how-to.md @@ -1,3 +1,7 @@ +--- +description: Creating an Assessment Form involves a structured approach. +--- + # How to use the Assessment Toolkit Creating an Assessment Form involves a structured approach. Below, you’ll find a summary of the steps to follow in order to create your Assessment Form. This workflow will guide you through adding questions to your question bank, creating a clear specification for your assessment, and then using that specification to build a well-organized and effective Assessment Form. diff --git a/topics/assessments/create-bank/print-bank-pdf.md b/topics/assessments/create-bank/print-bank-pdf.md index 92328e0..8625a15 100644 --- a/topics/assessments/create-bank/print-bank-pdf.md +++ b/topics/assessments/create-bank/print-bank-pdf.md @@ -1,3 +1,7 @@ +--- +description: _See below the steps to generate a PDF document that lists all the questions in an Assessment Bank, including comments by administrators._ +--- + # How to Print a Question Bank/Assessment Form to PDF ## How to Print a Question Bank to PDF @@ -41,7 +45,7 @@ Under **Print Options** (Print Settings) check the boxes “**Include Images** At the bottom of the Print Form page, there are 4 print options available: * **Print Form** - A PDF download containing all the Questions in the Form. -* **Print Addendum** - A PDF download containing all the Addemdums attached to the Assessment Form. +* **Print Addendum** - A PDF download containing all the Addendums attached to the Assessment Form. * **Print Form (internal)** - A PDF download containing all the questions in the Form, including administrator comments. * **Print Form (compact)** - A PDF download containing all the answers to the Questions in the Form. diff --git a/topics/assessments/create-bank/question-settings.md b/topics/assessments/create-bank/question-settings.md index 59d3541..c68d508 100644 --- a/topics/assessments/create-bank/question-settings.md +++ b/topics/assessments/create-bank/question-settings.md @@ -64,7 +64,7 @@ To add a Prerequisites, click on the **New Prerequisite** button. Under the **Le Under the **Unlocks Course Activity** heading: -* Select the lesson you want to unlock based on the Correct/Incorrct answer the learner provided. +* Select the lesson you want to unlock based on the Correct/Incorrect answer the learner provided. Click **Save**\
diff --git a/topics/assessments/create-bank/question-types.md b/topics/assessments/create-bank/question-types.md index 10b5720..c8f2a64 100644 --- a/topics/assessments/create-bank/question-types.md +++ b/topics/assessments/create-bank/question-types.md @@ -1,3 +1,7 @@ +--- +description: Shift iQ allows for a wide variety of assessment question types, including multiple choice, true/false, multiple correct, composed response +--- + # Choosing Question Types Shift iQ allows for a wide variety of assessment question types, including multiple choice, true/false, multiple correct, composed response (voice recording or typed essay), drag-and-drop reordering, matching, hotspot and Likert. @@ -13,7 +17,7 @@ Shift iQ allows for a wide variety of assessment question types, including multi * **Composed Voice:** Learners can capture their verbal response to a question. This question type is associated with a scoring Rubric and is graded manually by an administrator / instructor. Configuration options include: * Limit Number of Attempts * Limit Response Time (Seconds)
- * **Composed Essay:** Learners can capture their reponse by typing their asnwer in the text box field below the question. This question type is associated with a scoring Rubric and is graded manually by an administrator / instructor.
+ * **Composed Essay:** Learners can capture their response by typing their answer in the text box field below the question. This question type is associated with a scoring Rubric and is graded manually by an administrator / instructor.
* **Multiple True/False:** Allows the learner to select True/False in response to a series of statements. Calculation Methods include: * All or Nothing * Equally Weighted @@ -24,7 +28,7 @@ Shift iQ allows for a wide variety of assessment question types, including multi * Equally Weighted * Correct Minus Incorrect * Limited Correct
-* **Likert Question Type:** This is a dynamic question type often included on surveys to assess variables such as sentiment, satisfaction, quality, or likelihood. For standardized exams, this question type can be used for third party assessmsent purposes or where answers options are not binary in nature. +* **Likert Question Type:** This is a dynamic question type often included on surveys to assess variables such as sentiment, satisfaction, quality, or likelihood. For standardized exams, this question type can be used for third party assessment purposes or where answers options are not binary in nature.
* **Hotspot Question Type:** Any image can be uploaded for use with this question type. Configuration Options Include: diff --git a/topics/assessments/create-bank/reordering-questions-and-sets.md b/topics/assessments/create-bank/reordering-questions-and-sets.md index 289b47e..f43511b 100644 --- a/topics/assessments/create-bank/reordering-questions-and-sets.md +++ b/topics/assessments/create-bank/reordering-questions-and-sets.md @@ -1,3 +1,7 @@ +--- +description: After Questions are created in a Set, administrators are able to reorder those questions if needed. +--- + # Reordering Questions and Sets #### Reordering Questions diff --git a/topics/assessments/create-bank/upload-assessment-sets.md b/topics/assessments/create-bank/upload-assessment-sets.md index 78fc7a2..1c35d8a 100644 --- a/topics/assessments/create-bank/upload-assessment-sets.md +++ b/topics/assessments/create-bank/upload-assessment-sets.md @@ -1,3 +1,7 @@ +--- +description: Select the Assessment Toolkit from the Admin Home Page. +--- + # Upload Assessment Sets ## Uploading Assessment Sets in Markdown (.md/.txt) @@ -6,7 +10,7 @@ Select the **Assessment** Toolkit from the Admin Home Page. Select the **Banks** counter. -Search for the **Bank** you where you want to uplaod the **Set** and select the bank in the **Results** tab. +Search for the **Bank** you where you want to upload the **Set** and select the bank in the **Results** tab. Once Assessment bank is selected, click on the **Question** tab. @@ -16,7 +20,7 @@ Add the **Question Set** name in the **Set Name** field. Under **Upload Question Items** select **Shift iQ Markdown** in the **File Format** field. -In the **Upload Shift iQ Markdown** field click on the **Folder** icon (:folder-open:) and slect the **Markdown** file you want to upload. The file format can be a Text file (_.txt) or a Markdown file (_.md). +In the **Upload Shift iQ Markdown** field click on the **Folder** icon (:folder-open:) and select the **Markdown** file you want to upload. The file format can be a Text file (_.txt) or a Markdown file (_.md). * _Download an example here:_ [_**Shift iQ Markdown Sample**_](https://e02.insite.com/files/web/a226650b-be69-431c-b584-af9e010c5d8f/set-upload-example.txt) @@ -32,7 +36,7 @@ Select the **Assessment** Toolkit from the Admin Home Page. Select the **Banks** counter. -Search for the **Bank** you where you want to uplaod the **Set** and select the bank in the **Results** tab. +Search for the **Bank** you where you want to upload the **Set** and select the bank in the **Results** tab. Once Assessment bank is selected, click on the **Question** tab. @@ -42,7 +46,7 @@ Add the **Question Set** name in the **Set Name** field. Under **Upload Question Items** select **LXR Merge** in the **File Format** field. -In the **Upload Shift iQ Markdown** field click on the **Folder** icon (:folder-open:) and slect the **LXR Merge** file (\*.lxrmerge) you want to upload. +In the **Upload Shift iQ Markdown** field click on the **Folder** icon (:folder-open:) and select the **LXR Merge** file (\*.lxrmerge) you want to upload. * _Download an example here:_ [_**LXR Merge Fromat Sample**_](https://e02.insite.com/files/web/1b3db2ff-e94a-460e-81e7-b103011be3d0/lxr-merge-2.txt) diff --git a/topics/assessments/editing-forms/README.md b/topics/assessments/editing-forms/README.md index e818df9..15e0555 100644 --- a/topics/assessments/editing-forms/README.md +++ b/topics/assessments/editing-forms/README.md @@ -1,3 +1,22 @@ +--- +description: >- + Review, publish, test, and update assessment forms after the question bank is + built +--- + # Editing Assessment Questions and Forms -### +Once a question bank exists, the editing-forms section covers the work that turns a draft bank into a usable, published assessment: reviewing the form, testing it, publishing it, and updating questions and form contents over time. + +## In this section + +* [Review exam Form details prior to publishing](review-exam-form.md) +* [Advanced question searches](search-for-questions.md) +* [How to publish an assessment form](publish-exam-form.md) +* [How to test an Exam Form](test-exam-form.md) +* [Pre-Publish an Assessment Form](pre-publish-exam-form.md) +* [Edit Assessment Questions](edit-questions.md) +* [Manually Analyze Assessment Attempts](analyze-exam-attempts.md) +* [Working with Images in Assessments](editing-images.md) +* [Creating a New Version of a Question](creating-a-new-version-of-a-question.md) +* [How to Add/Remove Questions from an Assessment Form](how-to-add-remove-questions-from-a-assessment-form.md) diff --git a/topics/assessments/editing-forms/analyze-exam-attempts.md b/topics/assessments/editing-forms/analyze-exam-attempts.md index 51a796e..d5e9a07 100644 --- a/topics/assessments/editing-forms/analyze-exam-attempts.md +++ b/topics/assessments/editing-forms/analyze-exam-attempts.md @@ -1,12 +1,19 @@ -# Manually Analyze Assessment Attempts - +--- +description: >- + How the system analyzes an assessment attempt automatically and how to + trigger the analysis manually +--- + +# Manually Analyze Assessment Attempts + **When an Assessment Attempt is submitted, the system automatically Analyzes a users attempt. During the Analyze process, the following occurs:** + 1. Sets final score, i.e. Pass or Fail. 2. Sets attempt tag from Venue Location Name (if being used). 3. Updates comments in Assessment from Attempt (if comments for learners are enabled). 4. Saves scores to the gradebook (if an Gradebook is attached to the Assessment Bank and Form). -Assessment Attempts with Composed Essay question types need to be Graded by an administrator after the user submits their Assessment Attempt. -After grading the Composed Essay questions, the administrator needs to click the Analyze button to instruct the system to go through Analyze steps mentioned above. +Assessment Attempts with Composed Essay question types need to be Graded by an administrator after the user submits their Assessment Attempt. +After grading the Composed Essay questions, the administrator needs to click the Analyze button to instruct the system to go through Analyze steps mentioned above. -When doing a **Force Complete** for an uncompleted Assessment Attempt, an Administrator can click the Analyze button to instruct the system to go throught the analyze process. +When doing a **Force Complete** for an uncompleted Assessment Attempt, an Administrator can click the Analyze button to instruct the system to go through the analyze process. diff --git a/topics/assessments/editing-forms/creating-a-new-version-of-a-question.md b/topics/assessments/editing-forms/creating-a-new-version-of-a-question.md index 235cf75..9e1b605 100644 --- a/topics/assessments/editing-forms/creating-a-new-version-of-a-question.md +++ b/topics/assessments/editing-forms/creating-a-new-version-of-a-question.md @@ -1,11 +1,15 @@ +--- +description: After creating questions for a bank, you may need to update or revise the questions or answer options while still keeping the original question data +--- + # Creating a New Version of a Question After creating questions for a bank, you may need to update or revise the questions or answer options while still keeping the original question data and any associated attempts intact. 1. Open the question you want to create a new version of and click the edit pencil next to the question. -2. On the right side of the page, click on the little arrow below the **Current Version** heading. +2. On the right side of the page, click on the little arrow below the **Current Version** heading. -
+
Image (6)
3. The Publication Status of the question will update to **Drafted (In Development)**. 4. You can now edit the Question Text and Answer Options as needed. The original Question and Answer Options will remain as is. @@ -13,10 +17,3 @@ After you updated the new version of that question: * If a form has a **Specification Type = Static**, the question will _not_ update automatically across the forms where it’s used. You’ll need to manually remove the old question and add the updated one. See [How to Add/Remove Questions from a Assessment Form](how-to-add-remove-questions-from-a-assessment-form.md) * If a form has a **Specification Type = Dynamic**, the question _is_ automatically updated everywhere it’s used, and those updates become immediately available to learners. - - - - - - - diff --git a/topics/assessments/editing-forms/edit-questions.md b/topics/assessments/editing-forms/edit-questions.md index ea31b9c..7edd69c 100644 --- a/topics/assessments/editing-forms/edit-questions.md +++ b/topics/assessments/editing-forms/edit-questions.md @@ -1,5 +1,9 @@ -# Edit Assessment Questions - +--- +description: Depending on the Organization setting, Administrators are able to edit existing Assessment questions. +--- + +# Edit Assessment Questions + Depending on the Organization setting, Administrators are able to edit existing Assessment questions. When editing questions that have already been published to a Form, a warning message will appear at the top of the page. ![edit-assessment-questions-1-0.png](https://e02.insite.com/files/sites/e02/edit-questions/edit-assessment-questions-1-0.png) @@ -12,6 +16,6 @@ Depending on the change that was made to the question, an Admin can choose if th ![edit-assessment-questions.png](https://e02.insite.com/files/sites/e02/edit-questions/edit-assessment-questions.png) -Any questions being edited will be available for learners who have not started a exam. If changes are made to a question, while a exam is in progress, the change will not be available to the learners. +Any questions being edited will be available for learners who have not started a exam. If changes are made to a question, while a exam is in progress, the change will not be available to the learners. -Additional information about question configuration settings can be found here +Additional information about question configuration settings can be found here diff --git a/topics/assessments/editing-forms/editing-images.md b/topics/assessments/editing-forms/editing-images.md index ce96b9d..d340c8e 100644 --- a/topics/assessments/editing-forms/editing-images.md +++ b/topics/assessments/editing-forms/editing-images.md @@ -1,5 +1,9 @@ -# Working with Images in Assessments - +--- +description: "There are two easy ways to add an image to an assessment question:" +--- + +# Working with Images in Assessments + There are two easy ways to add an image to an assessment question: **1. Drag and Drop the Image** @@ -13,32 +17,34 @@ Alternatively, you can upload the image to the Assessment Bank first. Once uploa *Note: The maximum size of an image that can be uploaded is 1 MB. If you require a bigger image to be uploaded, please contact your Shift iQ account representative.* **How to Upload an Image to the Assessment Bank** + * In the Assessment Bank, click on the Attachments tab, then click the Add Attachment button. * Next to the File field, click on the magnifying glass icon and select the image you want to upload. * Options for the Image: - * Title: You can edit the title of the image. This title will be visible to the user if they click on the image during their assessment attempt. - * Condition: Choose from the following options: - * Duplicate: If the image is a copy of an existing one. - * Edit: If the image is a version that has been edited. - * New: If the image is newly uploaded. - * Purge: If the image is no longer needed and should be removed. - * Surplus: If the image is extra or not in active use. - * Unassigned: If the image hasn’t been assigned to any specific content yet. - * Actual Dimensions: This shows the original size of the image. - * Target Online Dimensions: Here, you can specify the size at which the image should display to the learner online. - * Target Paper Dimensions: If you’re printing the assessment form for an exam, set the image size for its appearance in the printed version. - * Palette: Specify the color scheme of the image (e.g., Color, Black and White). + * Title: You can edit the title of the image. This title will be visible to the user if they click on the image during their assessment attempt. + * Condition: Choose from the following options: + * Duplicate: If the image is a copy of an existing one. + * Edit: If the image is a version that has been edited. + * New: If the image is newly uploaded. + * Purge: If the image is no longer needed and should be removed. + * Surplus: If the image is extra or not in active use. + * Unassigned: If the image hasn’t been assigned to any specific content yet. + * Actual Dimensions: This shows the original size of the image. + * Target Online Dimensions: Here, you can specify the size at which the image should display to the learner online. + * Target Paper Dimensions: If you’re printing the assessment form for an exam, set the image size for its appearance in the printed version. + * Palette: Specify the color scheme of the image (e.g., Color, Black and White). This process helps ensure that the image is uploaded properly and formatted for different viewing scenarios. **Editing or Changing an Uploaded Image** + * Under the Attachments tab, click on the edit pencil icon next to the image's Asset number. * You can edit the following details: - * Title - * Condition - * Target Online Dimensions - * Target Paper Dimensions - * Palette + * Title + * Condition + * Target Online Dimensions + * Target Paper Dimensions + * Palette * if the incorrect image was uploaded, you can replace it by clicking on the magnifying glass icon next to the Replace with File field and selecting the correct image. Keep in mind that replacing the image will remove the original image that was uploaded. * Alternatively, you can create a new version of the image without losing the original by clicking the Arrow icon under the **Current Version** heading and then uploading the new image. This way, the original image will remain intact, and the new version will be added to the image history. @@ -50,19 +56,20 @@ If the incorrect image was uploaded, you can delete it by clicking on the trash **View the Image History** -Any changes made to an image by an administrator are recorded in the system. To view the history of an image, click on the History icon below the image. This will display a record of who made changes and what changes were made. +Any changes made to an image by an administrator are recorded in the system. To view the history of an image, click on the History icon below the image. This will display a record of who made changes and what changes were made. **Image Usage Report** Each image you upload into the system keeps a record of where it’s being used. Specifically, it tracks which questions the image appears in and the date when it was added. This allows you to easily see how and when the image is being utilized across assessments, helping you stay organized and keep track of your content efficiently. -**Scan Images** +**Scan Images** The **Scan Images** button is designed to help manage and organize images associated with questions in a question bank. After migrating questions from an one bank to another, the image links associated with the questions might still point to the old bank, which can cause issues if those links are broken or if you need to update the images independently. When clicking the **Scan Images** button: + * You can quickly find any questions with image links that are still referencing the old bank. - * If the image **exists** as an attachment in the new bank, it gets a **green checkmark** (). - * If the image **doesn’t exist** as an attachment, it gets a **red exclamation** (). + * If the image **exists** as an attachment in the new bank, it gets a **green checkmark** (). + * If the image **doesn’t exist** as an attachment, it gets a **red exclamation** (). * Convert the image links to Attachments by clicking on the **Add Attachments** icon (). The images will be copied or migrated into the new Bank as an Assessment Attachment. -* You will then be able to modify, update, or manage the images without impacting the old bank or its assets. +* You will then be able to modify, update, or manage the images without impacting the old bank or its assets. diff --git a/topics/assessments/editing-forms/how-to-add-remove-questions-from-a-assessment-form.md b/topics/assessments/editing-forms/how-to-add-remove-questions-from-a-assessment-form.md index 4cca488..4aab5eb 100644 --- a/topics/assessments/editing-forms/how-to-add-remove-questions-from-a-assessment-form.md +++ b/topics/assessments/editing-forms/how-to-add-remove-questions-from-a-assessment-form.md @@ -1,3 +1,7 @@ +--- +description: 1. Open the Assessment Form and click the Action button. +--- + # How to Add/Remove Questions from a Assessment Form 1. Open the **Assessment Form** and click the **Action** button. @@ -7,21 +11,16 @@ * This will remove the question _from the form only,_ the original question will remain in the Question Bank. * If you select the checkbox next to the Bank Asset, it will delete the questions from both the Bank and the Form, including all aggregate attempt data. -
- -5. After making your selection, click **Delete**. -6. Click the **Add** button and choose **Question** (or **Existing Question**). -7. Select the checkbox next to the question you want to add to the form. -8. If you need the questions in a specific order, click the **arrow** icon and drag and drop the question into the desired position. - -
- -9. Click **Save**. -10. Click the **Action** button again and select **Publish**. -11. Choose the publication options (such as Learner/Assessor Feedback, Instructor Rationale, and Access) and click **Save**. -12. The form with the updated question(s) is now published and available for users to submit attempts.. - - +
Image (1)
+1. After making your selection, click **Delete**. +2. Click the **Add** button and choose **Question** (or **Existing Question**). +3. Select the checkbox next to the question you want to add to the form. +4. If you need the questions in a specific order, click the **arrow** icon and drag and drop the question into the desired position. +
Image (2)
+1. Click **Save**. +2. Click the **Action** button again and select **Publish**. +3. Choose the publication options (such as Learner/Assessor Feedback, Instructor Rationale, and Access) and click **Save**. +4. The form with the updated question(s) is now published and available for users to submit attempts.. diff --git a/topics/assessments/editing-forms/pre-publish-exam-form.md b/topics/assessments/editing-forms/pre-publish-exam-form.md index ad8ac0a..4751d77 100644 --- a/topics/assessments/editing-forms/pre-publish-exam-form.md +++ b/topics/assessments/editing-forms/pre-publish-exam-form.md @@ -1,3 +1,7 @@ +--- +description: An Administrator can Pre-Publish an Assessment Form for testing purposes. You will be able to complete the Assessment Form and submit your attempt. +--- + # Pre-Publish an Assessment Form An Administrator can Pre-Publish an Assessment Form for **testing** purposes. You will be able to complete the Assessment Form and submit your attempt. @@ -9,7 +13,7 @@ Pre-Publishing an Assessment: * Click on **Action** button and select **Prepublish**. * On the **Pre-Publish** page, you will see a URL on the right side, under the **Start an exam attempt** heading. Click on the URL to start your attempt.
-#### Important Notes: +#### Important Notes * The Pre-Publish URL is for **Administrator Access Only**. This link is strictly for administrative testing and review of the assessment form. Distribution to, or use by, actual assessment takers is NOT advised. Any assessment attempts completed using this link are considered to be tests and are NOT recorded by the system. * The system does not keep attempts for Forms that has an **Publication Status = Drafted**. If an attempt is submitted, while the form has an **Publication Status = Drafted**, the last thing the learner's session does is clean up after itself by deleting the attempt. There will be no record of the Pre-Published attempt. If you want to have a record of a Published attempt, then you should publish the Assessment Form as a Standalone Assessment on the Portal. (See [How to publish an exam Form](../../../ui/help/portal/assessments/editing-forms/publish-exam-form/)) diff --git a/topics/assessments/editing-forms/publish-exam-form.md b/topics/assessments/editing-forms/publish-exam-form.md index 5d58ead..7494e18 100644 --- a/topics/assessments/editing-forms/publish-exam-form.md +++ b/topics/assessments/editing-forms/publish-exam-form.md @@ -1,14 +1,18 @@ -# How to publish an assessment form - +--- +description: 1. Navigate to the Exam Form in the Form Tab. +--- + +# How to publish an assessment form + 1. Navigate to the Exam Form in the **Form** Tab. 2. Select the **Form** tab. 3. Click on **Action** button and select **Publish**. -4. Select the **Publication** settings for the Assessment Form being Published: - - **Candidate Feedback** - Allow exam candidates to submit feedback on the questions in this exam. (**Required Field**) - - **Instructor Rationale** - Show (to candidates) the rationale behind the questions in this exam for correct and/or incorrect answers. - - Set **Access** for the Exam: - - As part of a **Training Program** - The exam is delivered in the context of a specific e-learning module. - - As a **Standalone** Assessment - The exam is delivered directly to candidates. - - If **Standalone** is selected, select which group(s) should have access to this exam (Note: If the group does not currently exist, a new Permission List should be created ([**Create a New Group and Adding People to the Group**](/ui/help/portal/contacts/adding-new-group)). +4. Select the **Publication** settings for the Assessment Form being Published: + * **Candidate Feedback** - Allow exam candidates to submit feedback on the questions in this exam. (**Required Field**) + * **Instructor Rationale** - Show (to candidates) the rationale behind the questions in this exam for correct and/or incorrect answers. + * Set **Access** for the Exam: + * As part of a **Training Program** - The exam is delivered in the context of a specific e-learning module. + * As a **Standalone** Assessment - The exam is delivered directly to candidates. + * If **Standalone** is selected, select which group(s) should have access to this exam (Note: If the group does not currently exist, a new Permission List should be created ([**Create a New Group and Adding People to the Group**](/ui/help/portal/contacts/adding-new-group)). 5. Enter **Tile Tag** (The text to be used for the program tile on the portal home page) and **Icon Choice** (The [FontAwesome](https://fontawesome.com/icons?d=gallery) icon to be used for the program tile on the portal home page). -6. After all setting for the Assessment Form has been selected, click the **Publish** button. +6. After all setting for the Assessment Form has been selected, click the **Publish** button. diff --git a/topics/assessments/editing-forms/review-exam-form.md b/topics/assessments/editing-forms/review-exam-form.md index 9843637..d82eb25 100644 --- a/topics/assessments/editing-forms/review-exam-form.md +++ b/topics/assessments/editing-forms/review-exam-form.md @@ -1,11 +1,16 @@ -# Review exam Form details prior to publishing - +--- +description: Open the Assessment you wish to Review. +--- + +# Review exam Form details prior to publishing + Open the **Assessment** you wish to Review. Under the **Forms** Tab, you can review the following: -- **Questions** Tab: Ensure the exam form contains the correct question items. -- **Section** Tab Settings: You can add a Title and Summary to your Form page. The information conent you add here will appear at the top of the Assessment Form. -- **Form** Tab Settings: Review Invigilation settings including Kiosk Mode, Date Settings, Time Limit and Attempt Limit. -- **Content** Tab: Edit the Title and Sumamary of the Form. You can alos specify if a Diagram book or Reference Materials for Online Sessions is included in the From. -- **Addendum** -- **Summaries** Tab: Provides the summaries of the Taxonomies, Standards (GAC), Standards (Competency), Dificulties and Tags assigned to the Form. + +* **Questions** Tab: Ensure the exam form contains the correct question items. +* **Section** Tab Settings: You can add a Title and Summary to your Form page. The information content you add here will appear at the top of the Assessment Form. +* **Form** Tab Settings: Review Invigilation settings including Kiosk Mode, Date Settings, Time Limit and Attempt Limit. +* **Content** Tab: Edit the Title and Summary of the Form. You can also specify if a Diagram book or Reference Materials for Online Sessions is included in the From. +* **Addendum** +* **Summaries** Tab: Provides the summaries of the Taxonomies, Standards (GAC), Standards (Competency), Difficulties and Tags assigned to the Form. diff --git a/topics/assessments/editing-forms/search-for-questions.md b/topics/assessments/editing-forms/search-for-questions.md index ba2688c..2faa7a8 100644 --- a/topics/assessments/editing-forms/search-for-questions.md +++ b/topics/assessments/editing-forms/search-for-questions.md @@ -1,18 +1,22 @@ -# Advanced question searches - -Admins can perform advanced searches in the **Questions** tab by using advanced search syntax. +--- +description: Admins can perform advanced searches in the Questions tab by using advanced search syntax. +--- + +# Advanced question searches + +Admins can perform advanced searches in the **Questions** tab by using advanced search syntax. (The syntax here follows the same convention that Google uses for its advanced search.) -Under the **Question** tab, in the filter field at the top of the page, add the **parameter:value** and click the filter button. -The results will bring up all questions in the bank with the enetered **parameter:value**. +Under the **Question** tab, in the filter field at the top of the page, add the **parameter:value** and click the filter button. +The results will bring up all questions in the bank with the entered **parameter:value**. If "**parameter**" is not included in the filter field, then the **Parameter="keyword"** is assumed. -Available Parameters | Corresponding Question properties +Available Parameters | Corresponding Question properties --|-- code | Code tag |Tag taxonomy | Taxonomy difficulty | Difficulty -lig | LikeItemGroup -reference | Reference +lig | LikeItemGroup +reference | Reference diff --git a/topics/assessments/editing-forms/test-exam-form.md b/topics/assessments/editing-forms/test-exam-form.md index 78d9be5..c618116 100644 --- a/topics/assessments/editing-forms/test-exam-form.md +++ b/topics/assessments/editing-forms/test-exam-form.md @@ -1,8 +1,12 @@ +--- +description: After an Form was created for an exam, an Administrator can test the Form by Publishing or Pre-Publishing the Form. +--- + # How to test an Exam Form After an Form was created for an exam, an Administrator can test the Form by **Publishing** or **Pre-Publishing** the Form. -#### Publish the Form: +#### Publish the Form Publish the Form as a **Standalone** Form, with permissions so only the Administrator can see the From on the Portal. (See [How to publish an exam Form](../../../ui/help/portal/assessments/editing-forms/publish-exam-form/)) @@ -25,7 +29,7 @@ From the portal start the exam and review the following to ensure they are as de * Additional attempts for the exam are available as desired. * If Assessment Attempt is locked after the allocated time has run out.
-#### Pre-Publish the Form: +#### Pre-Publish the Form An Administrator can Pre-Publish an Assessment Form for **testing** purposes. You will be able to complete the Assessment Form and submit your attempt. diff --git a/topics/assessments/moving-assessment-banks.md b/topics/assessments/moving-assessment-banks.md index 38f4ebd..bac52f5 100644 --- a/topics/assessments/moving-assessment-banks.md +++ b/topics/assessments/moving-assessment-banks.md @@ -1,29 +1,37 @@ -# Moving Assessment Banks (and retain Competency mapping) - +--- +description: We've implemented the ability to move Assessment Banks from one Organization to another, and ratain the original Competency mapping. +--- + +# Moving Assessment Banks (and retain Competency mapping) + We've implemented the ability to move Assessment Banks from one Organization to another, and ratain the original Competency mapping. **Download the question bank** + 1. In the exporting organization, download the question bank by clicking on the **Download JSON** button in the **Assessment Bank**. **Download the framework and the file with hooks in it** + 1. Go to the Standards search screen in the organization from which you are exporting the framework. 2. Change your search results to search for all Standard Types, by selecting the blank option from the dropdown list. 3. Under the **Settings** heading, change the column visibility so that you can only see the Hook and Title columns. 4. Click the Search button. You will get more than you need, but it does not matter because the hooks will be unique. 5. Click on the Download tab and download all the search results. -6. In the *.csv / *.xlsx download, change the order of the columns so that **Standard Identifier** is in **Column A** and **Standard Hook** is in **Column B**. +6. In the *.csv /*.xlsx download, change the order of the columns so that **Standard Identifier** is in **Column A** and **Standard Hook** is in **Column B**. 7. Delete the 1st row in the spreadsheet and save your changes. 8. Now you can proceed to download the Competency Framework you want. **Upload the framework** *DON’T UPLOAD YOUR FRAMEWORK TO THE ORIGINAL ORGANIZATION ACCOUNT.* -1. In the new organization, open the **Standards** toolkit and then click on **Add New Standard** at the top of the page. + +1. In the new organization, open the **Standards** toolkit and then click on **Add New Standard** at the top of the page. 2. Select **Upload one new standard from a file** from the dropdown list. -3. Select the *.json file for the Competency Framework you downloaded and upload it normally. The hooks will automatically be uploaded. +3. Select the *.json file for the Competency Framework you downloaded and upload it normally. The hooks will automatically be uploaded. **Upload the bank** -1. In the new organization, open the **Assessment** toolkit and then the **Banks** tile. -2. Click on the **Add New Bank** link at the top of the page and select **Upload one new bank from a file** link from the dropdown list. -2. Select the *.json file for the **Assessment Bank** you downloaded. -3. In the **Standard Hooks** box, paste the first 2 columns (Standard Identifier, Standard Hook) of the spreadsheet that maps the hooks with the standards identifiers -4. Click the **Save**. + +1. In the new organization, open the **Assessment** toolkit and then the **Banks** tile. +2. Click on the **Add New Bank** link at the top of the page and select **Upload one new bank from a file** link from the dropdown list. +3. Select the *.json file for the **Assessment Bank** you downloaded. +4. In the **Standard Hooks** box, paste the first 2 columns (Standard Identifier, Standard Hook) of the spreadsheet that maps the hooks with the standards identifiers +5. Click the **Save**. diff --git a/topics/assessments/overview.md b/topics/assessments/overview.md index ba926a2..7546173 100644 --- a/topics/assessments/overview.md +++ b/topics/assessments/overview.md @@ -1,3 +1,9 @@ -# Overview - -The Assessments toolkit contains everything you need to assess your learners on any topic. It can be used to build everything from simple quizzes to high stakes exams tied to a competency framework. Results can be thoroughly analyzed with in-depth reporting and comparisons on question difficulty. Choose what level of feedback is offered to the learner after their attempt; ranging from no score given to detailed feedback on each question response and which competencies they've successfully proven. +--- +description: >- + Build quizzes through high-stakes exams, tie them to a competency framework, + and analyze results with item-level reporting +--- + +# Overview + +The Assessments toolkit contains everything you need to assess your learners on any topic. It can be used to build everything from simple quizzes to high stakes exams tied to a competency framework. Results can be thoroughly analyzed with in-depth reporting and comparisons on question difficulty. Choose what level of feedback is offered to the learner after their attempt; ranging from no score given to detailed feedback on each question response and which competencies they've successfully proven. diff --git a/topics/assessments/safe-exam-browser/README.md b/topics/assessments/safe-exam-browser/README.md index 239ff39..9999e42 100644 --- a/topics/assessments/safe-exam-browser/README.md +++ b/topics/assessments/safe-exam-browser/README.md @@ -1,7 +1,11 @@ +--- +description: Safe Exam Browser is a web browser environment to carry out e-assessments safely. +--- + # Safe Exam Browser (SEB) Safe Exam Browser is a web browser environment to carry out e-assessments safely. The software turns any computer temporarily into a secure workstation. It controls access to resources like system functions, other websites and applications and prevents unauthorized resources being used during an exam. To download Safe Exam Browser please visit [**https://safeexambrowser.org/download_en.html**](https://safeexambrowser.org/download_en.html) -*Please Note: Safe Exam Browser is an open source software that was not developed by InSite Information Systems. Support is familier with its basic functionality and we can answer some questions, but for most requests we advise using the Safe Exam Browswer help documentation found here [https://safeexambrowser.org/windows/win_usermanual_en.html](https://safeexambrowser.org/windows/win_usermanual_en.html)* +*Please Note: Safe Exam Browser is an open source software that was not developed by InSite Information Systems. Support is familiar with its basic functionality and we can answer some questions, but for most requests we advise using the Safe Exam Browser help documentation found here [https://safeexambrowser.org/windows/win_usermanual_en.html](https://safeexambrowser.org/windows/win_usermanual_en.html)* diff --git a/topics/assessments/safe-exam-browser/seb-error-checklist.md b/topics/assessments/safe-exam-browser/seb-error-checklist.md index f5a47fc..01aaec2 100644 --- a/topics/assessments/safe-exam-browser/seb-error-checklist.md +++ b/topics/assessments/safe-exam-browser/seb-error-checklist.md @@ -1,3 +1,7 @@ +--- +description: "Before reporting an exam issue to Shift iQ support, gather the below information:
" +--- + # Organization Checklist for SEB errors Before reporting an exam issue to Shift iQ support, gather the below information:
@@ -6,13 +10,13 @@ Before reporting an exam issue to Shift iQ support, gather the below information 2. Confirm if the venue tested the internet connection on the device that is having the issue.\ If the issue is only happening to ONE person in the class, it is an indication that it is a possible venue issue and not a Shift iQ issue. If there was an issue with Shift iQ, it will affect ALL candidates and not just one candidate. 3. Ask for the Venue’s IP Address. The Venue can open [https://whatismyipaddress.com/](https://whatismyipaddress.com/) and provide their IPv4 address.\ - ![](https://e02.insite.com/files/sites/e02/seb-error-checklist/myipaddress.png)\ + ![Myipaddress](https://e02.insite.com/files/sites/e02/seb-error-checklist/myipaddress.png)\
4. Confirm the version of SEB that venue is using.\ The current supported versions of SEB: SEB 3.3.2 up to SEB 3.7.0\ This can change, and updates can be found here: [https://safeexambrowser.org/download\_releases\_en.html](https://safeexambrowser.org/download_releases_en.html)\ Venues can see their version installed on the exam login page.\ - ![](https://e02.insite.com/files/sites/e02/seb-error-checklist/seb-version.png)\ + ![Seb version](https://e02.insite.com/files/sites/e02/seb-error-checklist/seb-version.png)\
5. Shift iQ records the SEB version used by a user after they login to their exam.\ An administrator can view the SEB versions in the following places:\ diff --git a/topics/assessments/single-question-quizzes/README.md b/topics/assessments/single-question-quizzes/README.md index 3ab12c4..a00415e 100644 --- a/topics/assessments/single-question-quizzes/README.md +++ b/topics/assessments/single-question-quizzes/README.md @@ -1,3 +1,15 @@ -# Single-Question Quizzes - -(The content is under revision. Check back soon.) +--- +description: >- + Short, single-question assessments used for typing speed, data entry, and + similar skills checks +--- + +# Single-Question Quizzes + +Single-question quizzes are short assessments built around a single, specialized question type. They are used for typing speed checks, data entry drills, and other quick skill measurements. + +## In this section + +* [Typing Speed Quiz](typing-speed-quiz.md) +* [Data Entry Quiz](data-entry-quiz.md) +* [View Single-Question Quiz Attempts](single-question-attempts.md) diff --git a/topics/assessments/single-question-quizzes/data-entry-quiz.md b/topics/assessments/single-question-quizzes/data-entry-quiz.md index 1eb35a5..5b6fcb6 100644 --- a/topics/assessments/single-question-quizzes/data-entry-quiz.md +++ b/topics/assessments/single-question-quizzes/data-entry-quiz.md @@ -1,3 +1,16 @@ -# Data Entry Quiz - -(The content is under revision. Check back soon.) +--- +description: Configure, deliver, and review the data-entry single-question quiz +--- + +# Data Entry Quiz + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* What the data-entry quiz measures and the question format it uses. +* How to create a data-entry quiz. +* How to assign it to a learner or class. +* How to view attempts and results. + + diff --git a/topics/assessments/single-question-quizzes/single-question-attempts.md b/topics/assessments/single-question-quizzes/single-question-attempts.md index c9a881d..47903e1 100644 --- a/topics/assessments/single-question-quizzes/single-question-attempts.md +++ b/topics/assessments/single-question-quizzes/single-question-attempts.md @@ -1,3 +1,15 @@ -# View Single-Question Quiz Attempts - -(The content is under revision. Check back soon.) +--- +description: View and review attempts learners have made on single-question quizzes +--- + +# View Single-Question Quiz Attempts + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* Where to find single-question quiz attempts. +* What information is recorded for each attempt. +* How to filter, search, and export attempt data. + + diff --git a/topics/assessments/single-question-quizzes/typing-speed-quiz.md b/topics/assessments/single-question-quizzes/typing-speed-quiz.md index 7e0df38..c61aeeb 100644 --- a/topics/assessments/single-question-quizzes/typing-speed-quiz.md +++ b/topics/assessments/single-question-quizzes/typing-speed-quiz.md @@ -1,42 +1,47 @@ -# Typing Speed Quiz - -The Typing Speed quiz is an assessment designed to measure how fast and accurately someone can type. The test typically involves typing a set of words or a passage of text within a specific time frame (usually measured in seconds or minutes). +--- +description: The Typing Speed quiz is an assessment designed to measure how fast and accurately someone can type. +--- + +# Typing Speed Quiz + +The Typing Speed quiz is an assessment designed to measure how fast and accurately someone can type. The test typically involves typing a set of words or a passage of text within a specific time frame (usually measured in seconds or minutes). The goal is to assess the user's words per minute (WPM) rate and their accuracy. -##### Creating a Typing Speed quiz: +##### Creating a Typing Speed quiz + * On the Admin Home screen, select the **Assessment** toolkit. * Click on the **Typing Speed** tile under the **Single-Question Quizzes** section. * Click on the **Add New Quiz** link located at the top of the page. * On the New Quiz page, fill in the required fields: - * **Quiz Name** - * Enter a descriptive name for the quiz (e.g., "Typing Speed Test 1 Minute"). - * **Time Limit (seconds)** - * Set the time limit for how long learners will have to complete the test (e.g., 60 seconds). - * **Attempt Limit** - * Set how many times learners can attempt the quiz (e.g., 1 attempt). + * **Quiz Name** + * Enter a descriptive name for the quiz (e.g., "Typing Speed Test 1 Minute"). + * **Time Limit (seconds)** + * Set the time limit for how long learners will have to complete the test (e.g., 60 seconds). + * **Attempt Limit** + * Set how many times learners can attempt the quiz (e.g., 1 attempt). * Optional Fields for setting a required performance threshold: - * **Maximum Possible Points:** - * Set the maximum number of points the quiz can be worth. - * **Points Required to Pass** - * Set the number of points needed to pass the quiz. - * **Passing Score (%)** - * Set the percentage needed to pass (e.g., 80%). - * **Passing WPM** - * Set the minimum Words Per Minute (WPM) needed to pass. - * **Passing KPH** - * Set the minimum Keystrokes Per Hour (KPH), if relevant. - * **Passing Accuracy (%)** - * Set the required accuracy percentage (e.g., 95%). + * **Maximum Possible Points:** + * Set the maximum number of points the quiz can be worth. + * **Points Required to Pass** + * Set the number of points needed to pass the quiz. + * **Passing Score (%)** + * Set the percentage needed to pass (e.g., 80%). + * **Passing WPM** + * Set the minimum Words Per Minute (WPM) needed to pass. + * **Passing KPH** + * Set the minimum Keystrokes Per Hour (KPH), if relevant. + * **Passing Accuracy (%)** + * Set the required accuracy percentage (e.g., 95%). * In the **Quiz Text** card, add the text you want the learner to type in the content box. This could be a sentence, paragraph, or set of words. * Click **Save**. -If you're allowing multiple attempts on the Typing Speed quiz, you can add different text for each attempt by clicking the **Add New Item** button. +If you're allowing multiple attempts on the Typing Speed quiz, you can add different text for each attempt by clicking the **Add New Item** button. The system will randomize the text, giving learners a new passage each time they take the quiz. For example: **Attempt 1 -> Text A:** "The quick brown fox jumps over the lazy dog." **Attempt 2 -> Text B:** "Pack my box with five dozen liquor jugs." -##### Editing a Typing Speed quiz: +##### Editing a Typing Speed quiz -##### Deleting a Typing Speed quiz: +##### Deleting a Typing Speed quiz diff --git a/topics/assessments/specifications-forms/README.md b/topics/assessments/specifications-forms/README.md index bcc207e..37e7773 100644 --- a/topics/assessments/specifications-forms/README.md +++ b/topics/assessments/specifications-forms/README.md @@ -1,3 +1,7 @@ +--- +description: Specifications and Forms are used to control the organization and availability of exams to learners +--- + # Creating Exam Specifications & Forms Specifications and Forms are used to control the organization and availability of exams to learners diff --git a/topics/assessments/specifications-forms/add-questions-form.md b/topics/assessments/specifications-forms/add-questions-form.md index 6dc2def..07f80d4 100644 --- a/topics/assessments/specifications-forms/add-questions-form.md +++ b/topics/assessments/specifications-forms/add-questions-form.md @@ -1,7 +1,11 @@ -# Adding Questions to a Form - -- Under the **Forms** tab click on the **Add** button and select **Questions** or **Add Existing Questions** -- Below **Question Items** use the checkboxes to select available question to add. -- Click **Save** +--- +description: Under the Forms tab click on the Add button and select Questions or Add Existing Questions +--- -needs more details, maybe links to adding attachments, edit questions, other content? +# Adding Questions to a Form + +* Under the **Forms** tab click on the **Add** button and select **Questions** or **Add Existing Questions** +* Below **Question Items** use the checkboxes to select available question to add. +* Click **Save** + +needs more details, maybe links to adding attachments, edit questions, other content? diff --git a/topics/assessments/specifications-forms/adding-timers-to-tabs.md b/topics/assessments/specifications-forms/adding-timers-to-tabs.md index a077c49..fda218b 100644 --- a/topics/assessments/specifications-forms/adding-timers-to-tabs.md +++ b/topics/assessments/specifications-forms/adding-timers-to-tabs.md @@ -1,32 +1,41 @@ -# Adding Timers to Tabs - -When **Sections as Tabs** is enabled and **Tab Navigation** is disabled, you can set timers for individual sections (tabs) within the assessment form. This allows you to control the time learners can spend on different parts of the assessment. +--- +description: When Sections as Tabs is enabled and Tab Navigation is disabled, you can set timers for individual sections (tabs) within the assessment form. +--- + +# Adding Timers to Tabs + +When **Sections as Tabs** is enabled and **Tab Navigation** is disabled, you can set timers for individual sections (tabs) within the assessment form. This allows you to control the time learners can spend on different parts of the assessment. There are the two options available for configuring timers: -1. **Enable Timer for Some Tabs** - This option allows you to set a timer for specific tabs within the assessment form. It’s useful if you want to give learners a break in between sections, such as during an extended exam where you allow them time to rest or stretch their legs. If this option is selected, the **Break Timer** should only be enabled for the specific tabs where you want to add a timer (e.g., between sections). This could be a short break to allow learners to relax before continuing the assessment. - -2. **Enable Timer for All Tabs** - When you enable the Tab Time Limit for all tabs, you will need to specify a time limit for each individual tab within the form. This ensures that each section has a defined time duration, and learners must complete each section within the specified time frame. For example, if your assessment has 4 sections and you want learners to spend 15 minutes on each section, you would set a 15-minute time limit for each tab. The system will automatically calculate the total time allowed to complete the entire assessment based on the time limits set for each tab. For instance, if you set a 15-minute time limit for each of four sections, the total time allowed for the whole assessment will be 60 minutes. When timers are enabled for all tabs, the Break Timer will automatically be available for each tab. +1. **Enable Timer for Some Tabs** + This option allows you to set a timer for specific tabs within the assessment form. It’s useful if you want to give learners a break in between sections, such as during an extended exam where you allow them time to rest or stretch their legs. If this option is selected, the **Break Timer** should only be enabled for the specific tabs where you want to add a timer (e.g., between sections). This could be a short break to allow learners to relax before continuing the assessment. + +2. **Enable Timer for All Tabs** + When you enable the Tab Time Limit for all tabs, you will need to specify a time limit for each individual tab within the form. This ensures that each section has a defined time duration, and learners must complete each section within the specified time frame. For example, if your assessment has 4 sections and you want learners to spend 15 minutes on each section, you would set a 15-minute time limit for each tab. The system will automatically calculate the total time allowed to complete the entire assessment based on the time limits set for each tab. For instance, if you set a 15-minute time limit for each of four sections, the total time allowed for the whole assessment will be 60 minutes. When timers are enabled for all tabs, the Break Timer will automatically be available for each tab. + +**Please Note:** When **Enable Timer for All Tabs** is selected, then you are not able to add Accommodations for an exam. -**Please Note:** When **Enable Timer for All Tabs** is selcted, then you are not able to add Accommodations for an exam. - **Steps to Set Timers for Tabs** + 1. Go to the **Specification** tab and click on the edit pencil icon next to **Form Limit**. 2. Ensure that **Sections as Tabs** is **enabled** and make sure that **Tab Navigation** is **disabled**. 3. In the **Tab Time Limit** field, select one of the following: - * **Enable Timer for Some Tabs**: Set timers for specific tabs where needed. - * **Enable Timer for All Tabs**: Set time limits for each tab across the entire assessment. + + * **Enable Timer for Some Tabs**: Set timers for specific tabs where needed. + * **Enable Timer for All Tabs**: Set time limits for each tab across the entire assessment. + 4. Click **Save** to apply the changes. 5. Click on the **Forms** tab and select the form for which you enabled the **Tab Time Limit**. 6. Click on the **Section** tab. 7. Click on the edit pencil icon next to the **Warning on Next Tab** field, found under the **Configuration** heading. 8. In the **Configuration** card, configure the following settings: - * **Warning on Next Tab:** Set a warning that notifies learners when time is running out for a specific section. - * **Break Timer:** Enable the break timer for tabs where breaks are required. - * **Time Limit (minutes):** Set the time limit for each individual tab. - * **Timer Type**: Choose if the timer should be **Enforced** or if it is **Optional** - * If **Enforced**, then learner will not be able to navigate to the next tab until the timer runs out. - * If **Optional**, then learner can choose to leave the break tab before the timer runs out. -9. Click the **Save** button. + + * **Warning on Next Tab:** Set a warning that notifies learners when time is running out for a specific section. + * **Break Timer:** Enable the break timer for tabs where breaks are required. + * **Time Limit (minutes):** Set the time limit for each individual tab. + * **Timer Type**: Choose if the timer should be **Enforced** or if it is **Optional**. + * If **Enforced**, then learner will not be able to navigate to the next tab until the timer runs out. + * If **Optional**, then learner can choose to leave the break tab before the timer runs out. + +9. Click the **Save** button. diff --git a/topics/assessments/specifications-forms/creating-a-form.md b/topics/assessments/specifications-forms/creating-a-form.md index 12e9b9b..39a360c 100644 --- a/topics/assessments/specifications-forms/creating-a-form.md +++ b/topics/assessments/specifications-forms/creating-a-form.md @@ -1,16 +1,20 @@ -# Creating a Form - -**Each Specification can have one or more Forms. Forms are used to deliver the actual questions during the exam and control the availability of the exam.** +--- +description: Each Specification can have one or more Forms. Forms are used to deliver the actual questions during the exam and control the availability of the exam. +--- -- Under the **Specification** tab select the **Specification** that you want to create the Form for. -- Click on the **Add** button and select **Form** -- Add a **Form Name** (This is the internal name used to uniquely identify this exam form for filing purposes) -- Add a **Code** (This is the form's catalog code. It defaults to N/A. Can be left as is unless a specific identifier is desired) -- Add a **Source** (Reference to the source of the content and/or configuration for this form. Can enter one if available.) - *Optional* -- Add **Origin** (Identifies the originating platform and/or record for this form. When this property is used, it should ideally contain a fully qualified URL or API path.) - *Optional* -- Add a **Time Limit** (This is the number of minutes allowed for each attempt on the exam. Enter time limit in minutes) -- Select the **Criteira** (Sets) you want included in the Form. -- Under **Like Item Groups**, select if you want the questions to be **Mutually Exclusive** or **Not Mutually Exclusive** to the Form you are creating. -- Click the **Next** button. -- All the questions that will be included in the form will be listed under **Preview Questions**. -- Click the **Save** button to create the Form. +# Creating a Form + +**Each Specification can have one or more Forms. Forms are used to deliver the actual questions during the exam and control the availability of the exam.** + +* Under the **Specification** tab select the **Specification** that you want to create the Form for. +* Click on the **Add** button and select **Form** +* Add a **Form Name** (This is the internal name used to uniquely identify this exam form for filing purposes) +* Add a **Code** (This is the form's catalog code. It defaults to N/A. Can be left as is unless a specific identifier is desired) +* Add a **Source** (Reference to the source of the content and/or configuration for this form. Can enter one if available.) - *Optional* +* Add **Origin** (Identifies the originating platform and/or record for this form. When this property is used, it should ideally contain a fully qualified URL or API path.) - *Optional* +* Add a **Time Limit** (This is the number of minutes allowed for each attempt on the exam. Enter time limit in minutes) +* Select the **Criteria** (Sets) you want included in the Form. +* Under **Like Item Groups**, select if you want the questions to be **Mutually Exclusive** or **Not Mutually Exclusive** to the Form you are creating. +* Click the **Next** button. +* All the questions that will be included in the form will be listed under **Preview Questions**. +* Click the **Save** button to create the Form. diff --git a/topics/assessments/specifications-forms/creating-specification.md b/topics/assessments/specifications-forms/creating-specification.md index 0d56c73..997ed80 100644 --- a/topics/assessments/specifications-forms/creating-specification.md +++ b/topics/assessments/specifications-forms/creating-specification.md @@ -1,19 +1,23 @@ -# Creating a Specification - +--- +description: Static Specifications can be used to generate exam Forms. This allows administrators to specific which questions should be on the Assessment Form. +--- + +# Creating a Specification + **Static Specifications can be used to generate exam Forms. This allows administrators to specific which questions should be on the Assessment Form.** -- Select **Add** under the Specifications panel. -- Choose **Static** as the **Specification Type** - - Specification Types: - - Static (Fixed identically for all attempts): A form with this specification has a fixed set of questions in a fixed sequence, which is determined by the author of the form. Every learner who starts an attempt on form with a Static specification sees exactly the same set of questions in exactly the same sequence. - - Dynamic ( Generated randomly per attempt): A form with this specification does not have a fixed set of questions. If two learners start an attempt on this type of form, then each learner may be presented with a different set of questions and/or questions in a different sequence. -- Create a **Specification Name** -- Select an optional **Consequence Type** (high, medium, low). Indicates the stakes for exam forms following this specification. -- Enter an **From Limit** on the maximum number of forms that can be generated based on this specification. -- Enter an **Question Item Limit** on the maximum number of questions allowed on each exam. -- Select the Disclosure Type (None, Partial, Full). This selection affects the information learners receive about their performance on the exam when it’s submitted. Full is best practice for exams with multiple forms and randomized questions. For non-randomized exams; not a good idea for full disclosure, use partial. -- Enter a **Passing Score (%)**, the minimum score required to pass the exam. -- Enter an **Weight on Success (%)** - If the student/candidate passes the exam, what weight is applied to the submission score? -- Enter an **Weight on Failure (%)** - If the student/candidate fails the exam, what weight is applied to the submission score? -- Select one or more **Question Sets** you would like to include. -- Click **Save** +* Select **Add** under the Specifications panel. +* Choose **Static** as the **Specification Type** + * Specification Types: + * Static (Fixed identically for all attempts): A form with this specification has a fixed set of questions in a fixed sequence, which is determined by the author of the form. Every learner who starts an attempt on form with a Static specification sees exactly the same set of questions in exactly the same sequence. + * Dynamic ( Generated randomly per attempt): A form with this specification does not have a fixed set of questions. If two learners start an attempt on this type of form, then each learner may be presented with a different set of questions and/or questions in a different sequence. +* Create a **Specification Name** +* Select an optional **Consequence Type** (high, medium, low). Indicates the stakes for exam forms following this specification. +* Enter an **From Limit** on the maximum number of forms that can be generated based on this specification. +* Enter an **Question Item Limit** on the maximum number of questions allowed on each exam. +* Select the Disclosure Type (None, Partial, Full). This selection affects the information learners receive about their performance on the exam when it’s submitted. Full is best practice for exams with multiple forms and randomized questions. For non-randomized exams; not a good idea for full disclosure, use partial. +* Enter a **Passing Score (%)**, the minimum score required to pass the exam. +* Enter an **Weight on Success (%)** - If the student/candidate passes the exam, what weight is applied to the submission score? +* Enter an **Weight on Failure (%)** - If the student/candidate fails the exam, what weight is applied to the submission score? +* Select one or more **Question Sets** you would like to include. +* Click **Save** diff --git a/topics/assessments/specifications-forms/creating-tabs.md b/topics/assessments/specifications-forms/creating-tabs.md index 36f6d20..21da2b7 100644 --- a/topics/assessments/specifications-forms/creating-tabs.md +++ b/topics/assessments/specifications-forms/creating-tabs.md @@ -1,5 +1,9 @@ -# Creating Tabs in an Assessment Form - +--- +description: "Please note: Tabs can only be enabled if the Specification Type is set to Static. Tabs cannot be enabled if the Specification Type is set to Dynamic.*" +--- + +# Creating Tabs in an Assessment Form + *Please note: Tabs can only be enabled if the Specification Type is set to Static. Tabs cannot be enabled if the Specification Type is set to Dynamic.* When an Assessment Form is created, question on the form can be presented in 2 ways to a learner: @@ -9,31 +13,33 @@ When an Assessment Form is created, question on the form can be presented in 2 w 2. **Each set in the Form is displayed as a tab in the Form:** This is better suited for longer or more complex forms where content can be logically grouped into sets. It's a good option when you want to guide the learner through a more structured flow, especially if different sets of questions require different kinds of thinking or concentration (e.g., different topics or formats like multiple-choice vs. essays). ##### Creating Tabs in an Assessment Form -1. **Create Sets and Questions in the Assessment Bank** - Begin by setting up your sets and questions in the **Assessment Bank**. Each set will contain a group of related questions. -2. **Create the Specification** - Next, create a **Specification**. This is where you define the structure of your assessment form by adding the sets you want to include. +1. **Create Sets and Questions in the Assessment Bank** + Begin by setting up your sets and questions in the **Assessment Bank**. Each set will contain a group of related questions. -3. **Add Sets to the Specification** - In the **Specification**, you’ll select the Sets that you want included in the assessment form. These sets will become sections within the form. +2. **Create the Specification** + Next, create a **Specification**. This is where you define the structure of your assessment form by adding the sets you want to include. -4. **Enable Sections as Tabs** - After creating the **Specification**, go to the **Specifications** tab and then select the **Specification** you just created. In the **Configuration** section, look for the **Sections as Tabs** option. Toggle the slider to enable this feature. +3. **Add Sets to the Specification** + In the **Specification**, you’ll select the Sets that you want included in the assessment form. These sets will become sections within the form. + +4. **Enable Sections as Tabs** + After creating the **Specification**, go to the **Specifications** tab and then select the **Specification** you just created. In the **Configuration** section, look for the **Sections as Tabs** option. Toggle the slider to enable this feature. *When you enable Sections as Tabs, each section of your form (based on the sets you've added) will appear as a tab at the top of the form. This makes the form more organized and navigable, especially if it contains multiple sections.* ![section-as-tabs.png](https://e02.insite.com/files/sites/e02/creating-tabs/section-as-tabs.png) -5. **Allow Tab Navigation (Optional)** - As an administrator, you have the option to control how users navigate between tabs. If Tab Navigation is **enabled**, both Next and Previous buttons will appear, allowing users to freely move between sections/tabs. If Tab Navigation is **disabled**, only the Next button will be visible and only forward progression through the assessment is allowed. +1. **Allow Tab Navigation (Optional)** + As an administrator, you have the option to control how users navigate between tabs. If Tab Navigation is **enabled**, both Next and Previous buttons will appear, allowing users to freely move between sections/tabs. If Tab Navigation is **disabled**, only the Next button will be visible and only forward progression through the assessment is allowed. + +*When Tab Navigation is disabled, then an addition setting can be selected to display a **Single Question per Tab**. If **Single Question per Tab** enabled then only one question is displayed on the current tab at a time.* -*When Tab Navigation is disalbed, then an addition setting can be selected to display a **Single Question per Tab**. If **Single Question per Tab** enabled then only one question is displayed on the current tab at a time.* +1. **Add the Title for each Tab** + The Administrator needs to set the **Title** for each **Tab** that is appearing on the Assessment Form. If a **Title** is not added, it will display as "Untitled" -6. **Add the Title for each Tab** - The Administratror needs to set the **Title** for each **Tab** that is appearing on the Assessment Form. If a **Title** is not added, it will display as "Untitled" - - After configuring the tabs, go to the **Forms** tab, then click on the **Section** tab. - - Next to the **Title** heading, under the **Content** Heading, click on the pencil icon (). - - Enter the desired title that you want the learner to see on the assessment form for that specific tab. - - Click on the **Save** button to save your changes. - - Repeat these steps for each tab in the assessment form to set individual titles. +* After configuring the tabs, go to the **Forms** tab, then click on the **Section** tab. +* Next to the **Title** heading, under the **Content** Heading, click on the pencil icon (). +* Enter the desired title that you want the learner to see on the assessment form for that specific tab. +* Click on the **Save** button to save your changes. +* Repeat these steps for each tab in the assessment form to set individual titles. diff --git a/topics/assessments/specifications-forms/reference-materials.md b/topics/assessments/specifications-forms/reference-materials.md index 93743bb..4aa8dd8 100644 --- a/topics/assessments/specifications-forms/reference-materials.md +++ b/topics/assessments/specifications-forms/reference-materials.md @@ -1,14 +1,18 @@ +--- +description: Administrators can add Reference Materials for Online Sessions (Acronyms, Formulas and/or a Document). +--- + # Adding Reference Materials to a Form Administrators can add **Reference Materials for Online Sessions** (Acronyms, Formulas and/or a Document). -These materials will appear to the Assessment taker at the top of the Assessmemt Attemp page. By clicking on the different icons at the top of the page, it will open the uploaded files. +These materials will appear to the Assessment taker at the top of the Assessment Attemp page. By clicking on the different icons at the top of the page, it will open the uploaded files. ![acronymformula.png](https://e02.insite.com/files/sites/e02/reference-materials/acronymformula.png) Documents: :download:Acronyms: :table:Formulas::square-root-alt: -#### Uploading the File: +#### Uploading the File * Search for the **Assessment Bank** where you want to add the reference materials. * After opening the **Assessment Bank**, click on the **Attachments** tab and then the **Add Attachment** button. @@ -26,7 +30,7 @@ Documents: :download:Acronyms: :t * Palette (Color/Black and White) * Click the **Save** button
-#### Adding the File to the From: +#### Adding the File to the From * After uploading the file to the **Assessment Bank**, select the **Form** the file need to be attached to. * Under the **Forms** tab, click on the **Addendum** tab. diff --git a/topics/assessments/specifications-forms/specification-criteria.md b/topics/assessments/specifications-forms/specification-criteria.md index 85a412f..5d9ce5a 100644 --- a/topics/assessments/specifications-forms/specification-criteria.md +++ b/topics/assessments/specifications-forms/specification-criteria.md @@ -1,19 +1,23 @@ -# Applying Specification Criteria - +--- +description: Once the Specification has been created, you can apply filtering criteria to refine which questions are displayed on the exam Form. +--- + +# Applying Specification Criteria + **Once the Specification has been created, you can apply filtering criteria to refine which questions are displayed on the exam Form. Filtering criteria can be applied to all questions or to each question set in the bank.** -- Navigate to the **Specification Panel** and click on **Add Criteria**. -- Select the **Question Set** to which this criteria applies. Questions that match the criteria here will become available to include on forms. -- Select the **Filter Type**: - - **Include All Questions:** All questions from the question set will be included in the form, up to the -question item limit indicated (Ex. A set with 12 questions and a limit of 6 would select 6 questions +* Navigate to the **Specification Panel** and click on **Add Criteria**. +* Select the **Question Set** to which this criteria applies. Questions that match the criteria here will become available to include on forms. +* Select the **Filter Type**: + * **Include All Questions:** All questions from the question set will be included in the form, up to the +question item limit indicated (Ex. A set with 12 questions and a limit of 6 would select 6 questions from this set) - - **Question Tag Filter:** Tags applied to questions in the bank can be used to refine the questions + * **Question Tag Filter:** Tags applied to questions in the bank can be used to refine the questions selected.(Ex “t1:1” means select one question with the tag “t1” from this set) - - **Pivot Table Filter.** This feature will allow for questions to be selected across several criteria (Ex. Questions that are aligned to a particular competency AND of a certain difficulty) -- Configure **Question Set Weight**. The desired weighting for the question set to which this criterion applies, within the overall specification. The sum of all question set weights for the criteria in a specification must equal 1 (i.e. 100 percent). -- Confiqure **Question Item Limit**. The maximum number of question items allowed on an exam form from this question set. -- Click on **Save** + * **Pivot Table Filter.** This feature will allow for questions to be selected across several criteria (Ex. Questions that are aligned to a particular competency AND of a certain difficulty) +* Configure **Question Set Weight**. The desired weighting for the question set to which this criterion applies, within the overall specification. The sum of all question set weights for the criteria in a specification must equal 1 (i.e. 100 percent). +* Configure **Question Item Limit**. The maximum number of question items allowed on an exam form from this question set. +* Click on **Save** **Important Note:** The **Set Weight** stores the value entered by an administrator in **GAC %** column on **Workshop** page and helps calculate the values for the **Pivot Table Filter**, and then the **Pivot Table Filter** will determine the set number of questions on the form. In other words, the **Set Weight** only makes sense when the **Filter Type** in the Specification is set to **Filter with Pivot Table**. @@ -25,4 +29,4 @@ The value in the **Question Limit** only affects the set of form questions when Once the **Specification** has been completed, proceed to creating a **Form**. **Specification**: Set of rules that questions adhere to. -**Form**: How the questions are displayed. +**Form**: How the questions are displayed. diff --git a/topics/assessments/specifications-forms/using-specifications.md b/topics/assessments/specifications-forms/using-specifications.md index 565435e..6c661b6 100644 --- a/topics/assessments/specifications-forms/using-specifications.md +++ b/topics/assessments/specifications-forms/using-specifications.md @@ -1,15 +1,18 @@ -# Using Specifications - -Every Bank will contain at least ONE Specification. Specifications provide the rules that determinewhich questions will be contained on an exam Form. The same Specification may be used for multiple Forms, or there may be a different specification for each Form. +--- +description: Every Bank will contain at least ONE Specification. Specifications provide the rules that determine which questions will be contained on an exam Form. +--- + +# Using Specifications + +Every Bank will contain at least ONE Specification. Specifications provide the rules that determine which questions will be contained on an exam Form. The same Specification may be used for multiple Forms, or there may be a different specification for each Form. ![specification.png](https://e02.insite.com/files/sites/global/using-specifications/specification.png) ![specification-2.png](https://e02.insite.com/files/sites/global/9844/specification-2.png) - **Important Note when using Filter Type in Specifications:** The **Set Weight** stores the value entered by an administrator in **GAC %** column on **Workshop** page and helps calculate the values for the **Pivot Table Filter**, and then the **Pivot Table Filter** will determine the set number of questions on the form. In other words, the **Set Weight** only makes sense when the **Filter Type** in the Specification is set to **Filter with Pivot Table**. The **Set Weight** is not used in question filtering, even when **Filter Type** is **Filter with Pivot Table**. The **Pivot Table Filter** only applies to the questions filter while the **Set Weight** is only used to store the value that was used to calculate the **Pivot Table Filter** values. -The value in the **Question Limit** only affects the set of form questions when the **Filter Type** is set to **Include All Questions**. **Set Weight** is not applicable and has no effect on the creation, delivery, or marking of the form if the **Filter Type** is set to **Include All Questions**. +The value in the **Question Limit** only affects the set of form questions when the **Filter Type** is set to **Include All Questions**. **Set Weight** is not applicable and has no effect on the creation, delivery, or marking of the form if the **Filter Type** is set to **Include All Questions**. diff --git a/topics/cases/case-comments/README.md b/topics/cases/case-comments/README.md index 4ff3d84..3b2189f 100644 --- a/topics/cases/case-comments/README.md +++ b/topics/cases/case-comments/README.md @@ -1,3 +1,12 @@ -# Case Comments - -(The content is under revision. Check back soon.) +--- +description: Add, edit, and delete comments attached to a case +--- + +# Case Comments + +Comments give administrators and supervisors a running thread of notes against an individual case. This section covers adding new comments and editing or removing ones already on the case. + +## In this section + +* [Adding Comments](adding-comments.md) +* [Editing and Deleting Comments](editing-comments.md) diff --git a/topics/cases/case-comments/adding-comments.md b/topics/cases/case-comments/adding-comments.md index 9c2bb40..857ab50 100644 --- a/topics/cases/case-comments/adding-comments.md +++ b/topics/cases/case-comments/adding-comments.md @@ -1,17 +1,22 @@ -# Adding Comments - +--- +description: Open the case that you need to add a comment for and click on the Comments tab. +--- + +# Adding Comments + Open the case that you need to add a comment for and click on the **Comments** tab. Click on the **New Comment** button. In the **Comment** card add the following information: + * **Text** - In the Text field, add the comment related to the case. * **Assigned to** - ***To be updated*** -* **Category** - Comments can be assigned a Category (e.g. Decision, Resolution, Approval). These categories are cusotmizable per organization and need to be setup by **Shift iQ Support**, please email [**support@shiftiq.com**](mailto:support@shiftiq.com) to add categories if needed. - * A **Subcategory** can be added for a Category to provide further information regarding the comment (e.g. If Category = Decision a Subcategory can be added to provide the Decision made): - * Category = Decision - * Subcategory = Membership Cancelled -* **Flag** - Color flogs can be assinged to a comment. Within your organization you can assign a value for each flag color (e.g. Red = Important, Yellow = Requires Attention, Green = Approved) +* **Category** - Comments can be assigned a Category (e.g. Decision, Resolution, Approval). These categories are customizable per organization and need to be setup by **Shift iQ Support**, please email [**support@shiftiq.com**](mailto:support@shiftiq.com) to add categories if needed. + * A **Subcategory** can be added for a Category to provide further information regarding the comment (e.g. If Category = Decision a Subcategory can be added to provide the Decision made): + * Category = Decision + * Subcategory = Membership Cancelled +* **Flag** - Color flogs can be assigned to a comment. Within your organization you can assign a value for each flag color (e.g. Red = Important, Yellow = Requires Attention, Green = Approved) * **Tag** - ***To be updated*** -Click the **Save** button. +Click the **Save** button. diff --git a/topics/cases/case-comments/editing-comments.md b/topics/cases/case-comments/editing-comments.md index 0d06287..fb29ae1 100644 --- a/topics/cases/case-comments/editing-comments.md +++ b/topics/cases/case-comments/editing-comments.md @@ -1,3 +1,7 @@ +--- +description: Open the case that you need to edit the comment for and click on the Comments tab. +--- + # Editing and Deleting Comments ### Editing an Existing Comment @@ -6,7 +10,7 @@ Open the case that you need to edit the comment for and click on the **Comments* Click on the pencil icon (:pencil-alt:) next to the existing comment. -Edit the comement or other fields you want to update. +Edit the comment or other fields you want to update. Click the **Save** button.
diff --git a/topics/cases/case-documents.md b/topics/cases/case-documents.md index 6e35ade..0e75e38 100644 --- a/topics/cases/case-documents.md +++ b/topics/cases/case-documents.md @@ -1,3 +1,7 @@ +--- +description: Open the case that you need to upload a document for and click on the Attachments tab. +--- + # Case Documents ### Upload a Document @@ -8,18 +12,18 @@ Click on the **Attach Document** button. On the **Upload Attachment** screen, administrators are able to specify what type of document they are uploading for the user, if needed, but it isn't required. -* **Document Status** - The status of a document is cusotmizable per organization and need to be setup by **Shift iQ Support**, please email [support@shiftiq.com](mailto:support@shiftiq.com) to add additional statusess if needed. +* **Document Status** - The status of a document is customizable per organization and need to be setup by **Shift iQ Support**, please email [support@shiftiq.com](mailto:support@shiftiq.com) to add additional statusess if needed. * **Document Type** - E.g. Primary ID, Travel Document. * **Document Subtype** - E.g. Driver's licence, Passport * **Description** - Add a description of the document you are uploading. -Select the document you want to upload by clicking on the magnigying glass icon (:search:) next to the **Upload Document** field. +Select the document you want to upload by clicking on the magnifying glass icon (:search:) next to the **Upload Document** field. Administrators specify when the document was received and if the document expires by adding dates to the following fields: * **Expiry Date** * **Date Received** -* **Alternete Date** +* **Alternate Date** A status of **Reviewed** and **Approved** can be added to the upload by selecting a the checkbox next to each field. This will display in document upload. @@ -49,10 +53,10 @@ On the **Request Document** screen, fill in the following fields: Click on the **Request** button. -On the user **Portal** a tile can be setup for user to access the **My Cases** portal page. On the page users will be able to see all cases where they are set as the **Member**. When a docuement is requested, it will display under the **Requests** card in the case. +On the user **Portal** a tile can be setup for user to access the **My Cases** portal page. On the page users will be able to see all cases where they are set as the **Member**. When a document is requested, it will display under the **Requests** card in the case. ![document-request.png](https://e02.insite.com/files/sites/e02/upload-or-request-a-document/document-request.png) -The user can click on the request, select the the requested document from their device's browswer and click the **Open** button. The document will be uploaded to the issue for the administrator to review. +The user can click on the request, select the the requested document from their device's browser and click the **Open** button. The document will be uploaded to the issue for the administrator to review. ![document-request-1.png](https://e02.insite.com/files/sites/e02/upload-or-request-a-document/document-request-1.png) diff --git a/topics/cases/creating-cases.md b/topics/cases/creating-cases.md index 2886d0c..cb1fe37 100644 --- a/topics/cases/creating-cases.md +++ b/topics/cases/creating-cases.md @@ -1,6 +1,10 @@ +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + # Creating Cases -### Create an Case: +### Create an Case Select the **Workflows** Toolkit on the **Admin Home** page. @@ -29,9 +33,9 @@ Once your case is created, you can attach any supporting documents by clicking o Add additional comments by clicking on **Post Comment** under the **Comments** tab
-### Create an Case using Surveys: +### Create an Case using Surveys -Administrators are able to allow users to create their own **Case** by submitting a Survey reponse. +Administrators are able to allow users to create their own **Case** by submitting a Survey response. In the **Surveys** toolkit, open the survey you want to use to create an **Case**. diff --git a/topics/cases/edit-cases/README.md b/topics/cases/edit-cases/README.md index 9d73f2e..f62554f 100644 --- a/topics/cases/edit-cases/README.md +++ b/topics/cases/edit-cases/README.md @@ -1,3 +1,7 @@ +--- +description: Search for the Case you would like to Edit (see Searching for Cases) and open the Case. +--- + # Editing Cases Search for the **Case** you would like to **Edit** (see [**Searching for Cases**](/ui/help/portal/issues/edit-issues/search-for-an-issue)) and open the **Case**. diff --git a/topics/cases/edit-cases/case-history.md b/topics/cases/edit-cases/case-history.md index f0ca2b2..5b37036 100644 --- a/topics/cases/edit-cases/case-history.md +++ b/topics/cases/edit-cases/case-history.md @@ -1,5 +1,9 @@ -# View Case History - +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + +# View Case History + Select the **Workflows** Toolkit on the **Admin Home** page. Select the **Cases** counter. You can view as little or as much information as you want on the search results page. Click on **Clear** to remove any prior search criteria before starting a new search. @@ -8,10 +12,11 @@ Fill in the **Criteria** you want to you use to search for an existing Case. Click on **Filter** button. -In the Case, under the **Details** tab, click on the **History** button. +In the Case, under the **Details** tab, click on the **History** button. An administrator will be able to see the followign History information: + * **Date and Time** a change was made. * The **Change Type**. * **User** who made the change. -* **Data** for each Change Type by clicking on the Magnifying Glass icon () +* **Data** for each Change Type by clicking on the Magnifying Glass icon () diff --git a/topics/cases/edit-cases/case-reports.md b/topics/cases/edit-cases/case-reports.md index 1e0314f..61ff1a6 100644 --- a/topics/cases/edit-cases/case-reports.md +++ b/topics/cases/edit-cases/case-reports.md @@ -1,3 +1,7 @@ +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + # Case Reports Select the **Workflows** Toolkit on the **Admin Home** page. diff --git a/topics/cases/edit-cases/download-case-json.md b/topics/cases/edit-cases/download-case-json.md index db0b374..ea1fc42 100644 --- a/topics/cases/edit-cases/download-case-json.md +++ b/topics/cases/edit-cases/download-case-json.md @@ -1,10 +1,14 @@ -# Download Case JSON File - +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + +# Download Case JSON File + Select the **Workflows** Toolkit on the **Admin Home** page. Select the **Cases** counter. -Fill in the **Criteria** you want to you use to search for an existing Case. +Fill in the **Criteria** you want to you use to search for an existing Case. ***Note:** Click on **Clear** to remove any prior search criteria.* Click on **Filter**. You will be directed to the **Results** tab. @@ -15,4 +19,4 @@ Under the **Details** tab, click on the **Download** button. On the download screen, click on the **Download** button. -Your download will be saved in your Downloads folder on your computer. +Your download will be saved in your Downloads folder on your computer. diff --git a/topics/cases/edit-cases/search-case.md b/topics/cases/edit-cases/search-case.md index cba29e5..8e337bf 100644 --- a/topics/cases/edit-cases/search-case.md +++ b/topics/cases/edit-cases/search-case.md @@ -1,3 +1,7 @@ +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + # Search for an Case Select the **Workflows** Toolkit on the **Admin Home** page. diff --git a/topics/cases/edit-cases/send-email-from-case.md b/topics/cases/edit-cases/send-email-from-case.md index 5cb6c04..e1a6650 100644 --- a/topics/cases/edit-cases/send-email-from-case.md +++ b/topics/cases/edit-cases/send-email-from-case.md @@ -1,6 +1,10 @@ -# Send Email from an Case - -Select the **Workflows** Toolki on the **Admin Home** page. +--- +description: Select the Workflows Toolkit on the Admin Home page. +--- + +# Send Email from an Case + +Select the **Workflows** Toolkit on the **Admin Home** page. Select the **Cases** counter. @@ -15,11 +19,12 @@ You will be directed to the **Results** tab. Select the case you would like to review or edit by clicking on the Pencil icon () next to the case. Under the **Details** tab, click on the **Send Email** button. This will allow you to send an email to the user listed as the **Member** of the Case. + * Select the **Sender** you want to use to send the **Email**. (Contact [support@shiftiq.com](mailto:support@shiftiq.com) to configure the list of Senders available in your account.) * Add the Email Subject. * Add the Content for your Email. * Click **Next** -You will be able to review your email before you it send out. If you need to edit the email message, click on the **Compose** tab and proseed to edit your conent. Click the **Next** button once completed. +You will be able to review your email before you it send out. If you need to edit the email message, click on the **Compose** tab and proseed to edit your content. Click the **Next** button once completed. -Click on the **Send Message** button to send your email to the user. +Click on the **Send Message** button to send your email to the user. diff --git a/topics/cases/overview.md b/topics/cases/overview.md index 6f41467..9a74509 100644 --- a/topics/cases/overview.md +++ b/topics/cases/overview.md @@ -1,3 +1,16 @@ -# Overview - -Cases is a place for your organization to record and track customer concerns. +--- +description: >- + The Cases toolkit records and tracks customer concerns from intake through + resolution +--- + +# Overview + +The **Cases** toolkit is where your organization records and tracks customer concerns. Each case captures the issue, the contact involved, related documents, a comment thread, and the workflow that drives it to resolution. + +Use the pages in this section to: + +* Create a new case — see [Creating Cases](creating-cases.md). +* Find, view history on, or update an existing case — see [Editing Cases](edit-cases/README.md). +* Attach documents to a case — see [Case Documents](case-documents.md). +* Add or edit comments on a case — see [Case Comments](case-comments/README.md). diff --git a/topics/contacts/adding-new-contacts/README.md b/topics/contacts/adding-new-contacts/README.md index 2b8194b..fd31a7c 100644 --- a/topics/contacts/adding-new-contacts/README.md +++ b/topics/contacts/adding-new-contacts/README.md @@ -1,16 +1,21 @@ -# Adding New Contacts - +--- +description: From the Admin Home Page, select Contacts toolkit. +--- + +# Adding New Contacts + From the Admin Home Page, select **Contacts** toolkit. -In the **Counters** panel, click on **People** counter. +In the **Counters** panel, click on **People** counter. Click on **Add New Person** link to create/add a new contact (Top of the page). -Provide Basic Details for the new contact person. +Provide Basic Details for the new contact person. The following fields are **Required Fields:** + * First Name * Last Name -* Email +* Email Select the checkbox next to **User Access Granted** to grant access to the user you are adding. An **Temporary Password** will automatically be generated for the user to use for their first login. A user will be required to change this password the first time they sign in. @@ -18,8 +23,8 @@ Select the permission list to which you want to assign this new user account. Click **Save** to save the new contact. -Once a new user has been added, an **Welcome Email** will automatically be sent to the user with their **Login Name** and **Temporary Password**. The user will be required to update their password when they login for the first time. +Once a new user has been added, an **Welcome Email** will automatically be sent to the user with their **Login Name** and **Temporary Password**. The user will be required to update their password when they login for the first time. -If the user does not receive the **Welome Email**, you can resend the **Welcome Email** to the user by searching for the user (see [**Searching Contacts**](/ui/help/portal/contacts/editing-contacts/searching-contacts)) and click on **System Access** tab. Click on the **Send Email** button and select Welcome. On the Send Email screen, select the Shift iQ Alerts (Mailgun) sender and review the information in the content field. You are able to make changes to the content if needed, then click the **Next** button. You will be redirected to the Confirm screen to review the message that will be sent to the user. Click **Confirm** to send the message. +If the user does not receive the **Welcome Email**, you can resend the **Welcome Email** to the user by searching for the user (see [**Searching Contacts**](/ui/help/portal/contacts/editing-contacts/searching-contacts)) and click on **System Access** tab. Click on the **Send Email** button and select Welcome. On the Send Email screen, select the Shift iQ Alerts (Mailgun) sender and review the information in the content field. You are able to make changes to the content if needed, then click the **Next** button. You will be redirected to the Confirm screen to review the message that will be sent to the user. Click **Confirm** to send the message. -##### ***Please Note:** If the contact record was created **72 hours** prior to sending the **Welcome Email**, you would need to do a **[Password Reset](/ui/help/portal/contacts/editing-contacts/password-resets)** before sending the **Welcome Email**.* +##### ***Please Note:** If the contact record was created **72 hours** prior to sending the **Welcome Email**, you would need to do a **[Password Reset](/ui/help/portal/contacts/editing-contacts/password-resets)** before sending the **Welcome Email**.* diff --git a/topics/contacts/adding-new-contacts/bulk-upload-contacts.md b/topics/contacts/adding-new-contacts/bulk-upload-contacts.md index d18d410..71ddbf4 100644 --- a/topics/contacts/adding-new-contacts/bulk-upload-contacts.md +++ b/topics/contacts/adding-new-contacts/bulk-upload-contacts.md @@ -1,3 +1,7 @@ +--- +description: Any organization's admins can upload NEW contacts with the bulk upload tool. +--- + # Adding access to bulk upload contacts Any organization's admins can upload **NEW** contacts with the bulk upload tool. However, this tool can also be used by those with permission to **bulk update** existing contacts. Typically, bulk updating should be done by Platform Administrators, or well-trained super admins, to prevent overwriting information that should be kept. Here's how our Support team can give the latter access: diff --git a/topics/contacts/adding-new-contacts/upload-contacts.md b/topics/contacts/adding-new-contacts/upload-contacts.md index eb1f9c9..9388581 100644 --- a/topics/contacts/adding-new-contacts/upload-contacts.md +++ b/topics/contacts/adding-new-contacts/upload-contacts.md @@ -1,29 +1,34 @@ -# Upload Contacts - -This feature is generally used to upload multiple **NEW** contacts records into your **Contact** toolkit. **Use with Caution if you want to update exisiting Contact records.** If any of the information in your upload spreadsheet does not match the information on a record in the system for that unique login name/email address, it will overwrite the existing information. For example, if the name in the system for user "robertdoe123@gmail.com" is Robert Doe and the spreadsheet says Bob Doe, Bob will overwrite Robert. +--- +description: This feature is generally used to upload multiple NEW contacts records into your Contact toolkit. +--- -To bulk upload contacts: +# Upload Contacts + +This feature is generally used to upload multiple **NEW** contacts records into your **Contact** toolkit. **Use with Caution if you want to update existing Contact records.** If any of the information in your upload spreadsheet does not match the information on a record in the system for that unique login name/email address, it will overwrite the existing information. For example, if the name in the system for user "robertdoe123@gmail.com" is Robert Doe and the spreadsheet says Bob Doe, Bob will overwrite Robert. + +To bulk upload contacts: 1. Create a **CSV UTF-8 (comma delimited) (.csv)** file with at least the **first name**, **last name** and **email address** of the contacts you want to add. You can upload additional information as well, if desired, such as addresses, phone numbers, account numbers, etc., and you can save an existing Excel or other spreadsheet as a CSV UTF-8 file as well. Make sure your columns have header names that can be mapped to the upload screen. ![spreadsheet-example.png](https://e02.insite.com/files/sites/global/9795/spreadsheet-example.png) -2. Go into **Contacts** toolkit and below the People counter, select **Upload Contact People**. +1. Go into **Contacts** toolkit and below the People counter, select **Upload Contact People**. -3. Select the **CSV UTF-8 (comma delimited) (.csv)** file with the contact details of the users you would like to add. +2. Select the **CSV UTF-8 (comma delimited) (.csv)** file with the contact details of the users you would like to add. Your upload file must be a spreadsheet saved as a **CSV UTF-8 (comma delimited) (.csv)** file. - -4. *Optional:* the contacts you are uploading can all be attached to a specific group if desired. Select an existing group or input the name of a new group. + +3. *Optional:* the contacts you are uploading can all be attached to a specific group if desired. Select an existing group or input the name of a new group. ![csv-file-upload.png](https://e02.insite.com/files/sites/global/9795/csv-file-upload.png) -5. If you want all the uploaded users to have system access, check the box **Approve login credentials for all uploaded contacts**. They will then be able to sign in to the system with the same permissions as the group listed in step 4. If no group is chosen, they will only have portal access and any portal tiles that have no privacy settings turned on. Note that uploaded contacts do not automatically receive a welcome email informing them of their temporary initial password. +1. If you want all the uploaded users to have system access, check the box **Approve login credentials for all uploaded contacts**. They will then be able to sign in to the system with the same permissions as the group listed in step 4. If no group is chosen, they will only have portal access and any portal tiles that have no privacy settings turned on. Note that uploaded contacts do not automatically receive a welcome email informing them of their temporary initial password. -6. Click **Next** - -7. Choose the fields into which you want to upload your contact data. +2. Click **Next** + +3. Choose the fields into which you want to upload your contact data. ***Required Fields:*** + * **Unique Identifier Type** (usually LoginName) * **Unique Identifier** (usually Email, must be unique in the upload file) * **Login Name** (usually Email, must be unique in the upload file) @@ -31,6 +36,6 @@ To bulk upload contacts: * **LastName** * **Email** -Map additional column names (addresses, phone numbers, account numbers, etc.) in your **CSV UTF-8 (comma delimited) (.csv)** spreadsheet to the desired fields in the **Upload Contacts** form. +Map additional column names (addresses, phone numbers, account numbers, etc.) in your **CSV UTF-8 (comma delimited) (.csv)** spreadsheet to the desired fields in the **Upload Contacts** form. -8. Select **Upload and Save Changes**. If there are any duplicate email addresses in your upload spreadsheet, or if an email address is already in use in our system for a user in another tenant account, you will get error messages. Update or remove those records from your **CSV UTF-8 (comma delimited) (.csv)** spreadsheet, save and close it, and repeat steps 3-7. If there are no errors, the upload will proceed, and when finished will display the first 3 and last 3 records uploaded/updated from the spreadsheet. +1. Select **Upload and Save Changes**. If there are any duplicate email addresses in your upload spreadsheet, or if an email address is already in use in our system for a user in another tenant account, you will get error messages. Update or remove those records from your **CSV UTF-8 (comma delimited) (.csv)** spreadsheet, save and close it, and repeat steps 3-7. If there are no errors, the upload will proceed, and when finished will display the first 3 and last 3 records uploaded/updated from the spreadsheet. diff --git a/topics/contacts/adding-new-contacts/user-self-registration.md b/topics/contacts/adding-new-contacts/user-self-registration.md index fbbb667..6682695 100644 --- a/topics/contacts/adding-new-contacts/user-self-registration.md +++ b/topics/contacts/adding-new-contacts/user-self-registration.md @@ -1,14 +1,18 @@ -# User Self-Registration - +--- +description: If your organization would like to allow users to create their own accounts and access some content without a manual approval step, we can configure +--- + +# User Self-Registration + If your organization would like to allow users to create their own accounts and access some content without a manual approval step, we can configure your account to do so. The user journey would be as follows: 1. The User creates their own account using the New Users tab of the login screen, adding their own email, first name, last name and password. The User is immediately granted access to your portal and any content (tiles) that have no privacy settings. The User also receives an automated system **alert**, indicating their account has been registered and approved. 2. If your organization is configured with a choice of groups a user can join (subscribe to), and the user toggles one of those groups when creating their account, they also immediately become members of that group, and can see whatever portal tiles that group has access to. The group can be configured to send **notifications** to the user (welcoming them to your account, explaining what they can access and possible next steps) and/or to your administrators (notifying them of the new user). These optional **notification** emails are hooked up in the **group** itself. -(**Note:** you can provide a link to register for a specific group or program by using a link that includes the group name: [your orginization].insite.com/ui/lobby/register?group=[group name]) +(**Note:** you can provide a link to register for a specific group or program by using a link that includes the group name: [your organization].insite.com/ui/lobby/register?group=[group name]) -3. If the group the user joins is configured with a mandatory **survey** (application form), they will be prompted to complete and submit a response upon creating their account. The survey can also be configured to send a **notification** to the user when they have submitted a response (thank you for applying, your response will be reviewed, etc.) and/or to your administrators (notifying them they have an application to review). These optional **notification** emails are hooked up in the **survey** itself. +3. If the group the user joins is configured with a mandatory **survey** (application form), they will be prompted to complete and submit a response upon creating their account. The survey can also be configured to send a **notification** to the user when they have submitted a response (thank you for applying, your response will be reviewed, etc.) and/or to your administrators (notifying them they have an application to review). These optional **notification** emails are hooked up in the **survey** itself. -4. Once the **survey response** (application) has been reviewed by an admin; the admin can remove the user from the “applicant” group and add them to another group that has access to additional or different portal tiles. Once again, the groups can be configured to send **notifications** to the user (you have been approved for x group, log in now to see additional content) and/or to other internal staff (a new learner has joined x group). These optional **notification** emails are hooked up to each group a user might be placed in. +4. Once the **survey response** (application) has been reviewed by an admin; the admin can remove the user from the “applicant” group and add them to another group that has access to additional or different portal tiles. Once again, the groups can be configured to send **notifications** to the user (you have been approved for x group, log in now to see additional content) and/or to other internal staff (a new learner has joined x group). These optional **notification** emails are hooked up to each group a user might be placed in. -All notifications must be created and configured in the **Messages** Toolkit, prior to being hooked up where needed. **Do not** add any subscribers to any notifications going to users. **Do** add subscribers to any notifications going to admins, as desired for each one. We suggest you use the internal name of the message to distinguish between them: Notification to User on completion of application, Notification to User welcoming them to x group, Notification to admin that an application has been completed, etc. +All notifications must be created and configured in the **Messages** Toolkit, prior to being hooked up where needed. **Do not** add any subscribers to any notifications going to users. **Do** add subscribers to any notifications going to admins, as desired for each one. We suggest you use the internal name of the message to distinguish between them: Notification to User on completion of application, Notification to User welcoming them to x group, Notification to admin that an application has been completed, etc. diff --git a/topics/contacts/editing-contacts/README.md b/topics/contacts/editing-contacts/README.md index a11dc58..5d30a1c 100644 --- a/topics/contacts/editing-contacts/README.md +++ b/topics/contacts/editing-contacts/README.md @@ -1,8 +1,12 @@ +--- +description: This screen contains all of the information related to each contact in Shift iQ. +--- + # Editing Contacts This screen contains all of the information related to each contact in Shift iQ. Find and update personal details, employment info, addresses, any related uploaded documents, internal comments, a history of changes to the contact record, and more on the **Persons** tab. Use the **Memberships** tab to see and edit the groups they belong to and other relationships. The **Records** tab contains links to a variety of assets the contact may have generated. Grant and control access on the **System Access** tab. -**Deleting a Contact Record:** Deleting contact records should be used with **caution**. Deleting a contact will remove the link to all of their activitity in the system and is typically only done with duplicate records that have never logged in. If it is someone who has had activity but left your organization, it is better to Archive the user and remove their access to the system using the Sign In tab. +**Deleting a Contact Record:** Deleting contact records should be used with **caution**. Deleting a contact will remove the link to all of their activity in the system and is typically only done with duplicate records that have never logged in. If it is someone who has had activity but left your organization, it is better to Archive the user and remove their access to the system using the Sign In tab. **Edit:** Make changes to any of the fields in the Person panel and click **Save**. @@ -16,7 +20,7 @@ This screen contains all of the information related to each contact in Shift iQ. #### Phone Number Auto-Configuration parameters -When an telephone number is added to a users Contact Record, Shift iQ automatically configurates the phone number based on the number of digits added: +When an telephone number is added to a users Contact Record, Shift iQ automatically configures the phone number based on the number of digits added: * If you save the record with **10 digits** in any of the phone fields, our system adds brackets around the first 3 digits, adds a space after the second bracket and adds a dash before the last four digits. **Example:** 1234567890 ![phone-number-1.png](https://e02.insite.com/files/web/a53ae6fb-9834-4fd4-960b-b09300e40d6f/phone-number-1.png) * If you put **11 digits** and save, it removes whatever the first digit is, adds brackets around the first 3 digits, adds a space after the second bracket and adds a dash before the last four digits. **Example:** 12345678901 ![phone-number-2.png](https://e02.insite.com/files/web/a53ae6fb-9834-4fd4-960b-b09300e40d6f/phone-number-2.png) diff --git a/topics/contacts/editing-contacts/access-control.md b/topics/contacts/editing-contacts/access-control.md index 5c7b9f3..bd73708 100644 --- a/topics/contacts/editing-contacts/access-control.md +++ b/topics/contacts/editing-contacts/access-control.md @@ -1,5 +1,9 @@ -# Access Control and Roles Settings - +--- +description: Find the User you want to add/remove/review Access Control or Role Settings (see Searching Contacts). +--- + +# Access Control and Roles Settings + Find the User you want to add/remove/review Access Control or Role Settings (see [**Searching Contacts**](/ui/help/portal/contacts/searching-contacts)). Click on the **System Access** tab and then under the **Sign In** tab you can review the **User Credentials**, **Access Control** and **Roles** assigned to a user. @@ -10,23 +14,26 @@ Click on the **System Access** tab and then under the **Sign In** tab you can re **Licensed:** The Licensed checkbox shows whether or not the user has agreed to the terms and conditions of use (pop-up box that appears with first login) **Impersonate the User:** -1. Login under an admin account, search for the user you would like to impersonate. + +1. Login under an admin account, search for the user you would like to impersonate. 2. Click on the **System Access** tab and then under the **Sign In** tab you can click on the **Impersonate User** button. 3. The session will be automatically routed to being logged in as that user whom you would like to impersonate. 4. Once you’re done checking for functionality and access of the user, you have to **Stop Impersonating** the user, by clicking on your name in the Menu bar. **Reset Password:** -1. Login under an admin account, search for the user that is requesting a password reset. + +1. Login under an admin account, search for the user that is requesting a password reset. 2. Click on the **System Access** tab and then under the **Sign In** tab click on the **Reset Password** button. 3. This will autogenerate the password and its confirmation. **Save** the Password and communicate the new password to the user. **Access Control:** -**Access Granted:** The Approved checkbox turns that person’s account on +**Access Granted:** The Approved checkbox turns that person’s account on **Two Step authentication:** Two-step verification is a process that involves two authentication methods performed one after the other to verify that someone or something requesting access is who or what they are declared to be. + 1. **Optional:** Allow user to choose between enabling, disabling multi-factor authentication. 2. **Mandatory:** Forces user to activate multi-factor authentication upon next successful login. 3. **Current MFA Mode:** Displays the current MFA selected. @@ -35,4 +42,4 @@ Two-step verification is a process that involves two authentication methods perf Every Organization is responsible for ‘cataloging users’ within a system so that everyone who has access to it can be properly authenticated -*It is important for better access control that the roles of identities are clear and allow easy identification of the individual who wants to access them.* +*It is important for better access control that the roles of identities are clear and allow easy identification of the individual who wants to access them.* diff --git a/topics/contacts/editing-contacts/archive-users.md b/topics/contacts/editing-contacts/archive-users.md index 585a1ec..c0fba03 100644 --- a/topics/contacts/editing-contacts/archive-users.md +++ b/topics/contacts/editing-contacts/archive-users.md @@ -1,3 +1,7 @@ +--- +description: If a user is no longer needed, or requests to remove their personal information, you are able to archive the user from the system. +--- + # Archive Users ## Archive a User diff --git a/topics/contacts/editing-contacts/edit-permissions.md b/topics/contacts/editing-contacts/edit-permissions.md index ec0a127..0a554a2 100644 --- a/topics/contacts/editing-contacts/edit-permissions.md +++ b/topics/contacts/editing-contacts/edit-permissions.md @@ -1,3 +1,7 @@ +--- +description: Managing a contact's Roles and Permissions is a key part of an Administrator's job in Shift iQ. Here are some things to keep in mind when doing so. +--- + # Understanding Permissions and Roles Managing a contact's Roles and Permissions is a key part of an Administrator's job in Shift iQ. Here are some things to keep in mind when doing so. diff --git a/topics/contacts/editing-contacts/impersonate-permissions.md b/topics/contacts/editing-contacts/impersonate-permissions.md index 64aefcc..71dedf7 100644 --- a/topics/contacts/editing-contacts/impersonate-permissions.md +++ b/topics/contacts/editing-contacts/impersonate-permissions.md @@ -1,8 +1,12 @@ -# Adding Impersonate Permission - -To add Impersonation permissions, please contact an Shift iQ administrator by subitting a [**Support Ticket**](https://insite.atlassian.net/servicedesk/customer/portal/3) or emailing [**support@shiftiq.com**](mailto:support@shiftiq.com). +--- +description: "To add Impersonation permissions, please contact an Shift iQ administrator by submitting a Support Ticket or emailing support@shiftiq.com." +--- -***Administrator Note**: When adding the **Impersonate** permission for an administrative user, it can only be added when you are logged into the Organization account that requires this permission.* +# Adding Impersonate Permission + +To add Impersonation permissions, please contact an Shift iQ administrator by submitting a [**Support Ticket**](https://insite.atlassian.net/servicedesk/customer/portal/3) or emailing [**support@shiftiq.com**](mailto:support@shiftiq.com). + +***Administrator Note**: When adding the **Impersonate** permission for an administrative user, it can only be added when you are logged into the Organization account that requires this permission.* Log into the **Organization** account that the **Impersonate** permission needs to be added to @@ -17,4 +21,4 @@ Under the **Permissions** tab, select **Add Permission** ![impersonate-permission1.png](https://e02.insite.com/files/sites/global/impersonate-permissions/impersonate-permission1.png) -Select the **Group** within the **Organization** that you would like to give this permission to and select **Save** +Select the **Group** within the **Organization** that you would like to give this permission to and select **Save** diff --git a/topics/contacts/editing-contacts/password-resets.md b/topics/contacts/editing-contacts/password-resets.md index b0b4444..e2d5e1e 100644 --- a/topics/contacts/editing-contacts/password-resets.md +++ b/topics/contacts/editing-contacts/password-resets.md @@ -1,6 +1,10 @@ +--- +description: Method 1 - User resets their own Users can also reset their own passwords by clicking the Reset my password button on the initial login window. +--- + # Password Resets -## There are 2 methods of resetting a user's password: +## There are 2 methods of resetting a user's password
diff --git a/topics/contacts/editing-contacts/review-details.md b/topics/contacts/editing-contacts/review-details.md index c53dae4..cf830ec 100644 --- a/topics/contacts/editing-contacts/review-details.md +++ b/topics/contacts/editing-contacts/review-details.md @@ -1,10 +1,14 @@ +--- +description: The Person Edit screen is one of the most frequently used screens in Shift iQ. +--- + # Review and Edit a Contact The Person Edit screen is one of the most frequently used screens in Shift iQ. It provides access to all information and activity related to a contact in one place. Whenever a contact’s name appears as a hyperlink, clicking it will take you directly to this screen. Information can be both viewed and updated on this screen. Under the :user-alt: **Person** tab: -* **Details**: the key details of a contact record, including name, email, gender, birthday, employment details, phone numbers and more; use the **Send Email** button to send correspondance directly to the contact; use the **More Info** button to access additional details about the contact; use the **History** button to view changes that have been made in the past to the contact record. +* **Details**: the key details of a contact record, including name, email, gender, birthday, employment details, phone numbers and more; use the **Send Email** button to send correspondence directly to the contact; use the **More Info** button to access additional details about the contact; use the **History** button to view changes that have been made in the past to the contact record. * **Other**: additional details about the contact, such as preferred language, time zone, honorific; also any custom fields your organization may be using, and any responses to survey questions with a Respondant Attribute that doesn't match an existing field in the contact record. * **Documents**: view and manage any attachments uploaded to a contact record, either directly, or through a survey response, workflow case or their jobs candidate portfolio. * **Addresses**: view and manage home, work, shipping and billing addresses for the contact (note that home address fields can be populated by a survey response using the **Respondant Attribute** fields; the other addresses can be copied from the **Employed By/Belongs To** group on the Details tab, if that Employer group has them). diff --git a/topics/contacts/editing-contacts/searching-contacts.md b/topics/contacts/editing-contacts/searching-contacts.md index 0648707..5aa8331 100644 --- a/topics/contacts/editing-contacts/searching-contacts.md +++ b/topics/contacts/editing-contacts/searching-contacts.md @@ -1,3 +1,7 @@ +--- +description: "You can view as little or as much information as you want on the search results page such as:" +--- + # Searching Contacts You can view as little or as much information as you want on the search results page such as: diff --git a/topics/contacts/group-management/README.md b/topics/contacts/group-management/README.md index 2b07218..903ad9d 100644 --- a/topics/contacts/group-management/README.md +++ b/topics/contacts/group-management/README.md @@ -1,3 +1,7 @@ +--- +description: Users are able to lookup specific groups that were created by going to the Contacts Toolkit on the Admin Home Page, and selecting Groups under +--- + # Creating and Managing Groups Users are able to lookup specific groups that were created by going to the **Contacts** Toolkit on the Admin Home Page, and selecting **Groups** under **Counters** panel. diff --git a/topics/contacts/group-management/adding-new-group.md b/topics/contacts/group-management/adding-new-group.md index 70698f3..5e91fce 100644 --- a/topics/contacts/group-management/adding-new-group.md +++ b/topics/contacts/group-management/adding-new-group.md @@ -1,3 +1,7 @@ +--- +description: Select the Contact toolkit on the Admin Home Page and select the Groups counter below the Contact Group heading. +--- + # Create a New Group and Adding People to the Group ## Create a New Group @@ -40,7 +44,7 @@ _Please note, these users need to already have a contact record in the system to ## Allow User Self-Registration -To allow **User Self Registration**, after creating the group, go into the **Group** and under the **Group** tab select the checkbox next to **Allow users to subscribe/unsubscribe themslevles**. By selecting the checkbox, the system adds a toggle for the group on the new user registration screen. Users are able to select the group when creating their new account on the [**New User** registration page.](../../../ui/lobby/register) +To allow **User Self Registration**, after creating the group, go into the **Group** and under the **Group** tab select the checkbox next to **Allow users to subscribe/unsubscribe themselves**. By selecting the checkbox, the system adds a toggle for the group on the new user registration screen. Users are able to select the group when creating their new account on the [**New User** registration page.](../../../ui/lobby/register) ![self-register.png](https://e02.insite.com/files/sites/global/portal-permissions/self-register.png)
diff --git a/topics/contacts/group-management/edit-groups.md b/topics/contacts/group-management/edit-groups.md index 961458b..b7999ea 100644 --- a/topics/contacts/group-management/edit-groups.md +++ b/topics/contacts/group-management/edit-groups.md @@ -1,3 +1,7 @@ +--- +description: "Note that some of the options below are only available to admins with Write and Delete access.*" +--- + # Editing or Deleting Groups *Note that some of the options below are only available to admins with Write and Delete access.* diff --git a/topics/contacts/overview.md b/topics/contacts/overview.md index 438c710..f863e30 100644 --- a/topics/contacts/overview.md +++ b/topics/contacts/overview.md @@ -1,3 +1,7 @@ +--- +description: The Contacts toolkit is where you can create and edit all the contacts and groups that exist for your organization. +--- + # Overview -The **Contacts** tool kit is where you can create and edit all the contacts and groups that exist for your organization. Contacts can be Users (your customers), who only have access to a portal, or Administrators (your coworkers), who have access to create and edit content for your Users. Permissions are also controlled here, using Group membership. Contacts can have Membership in multiple Groups; allowing for intricate relationship management and reporting. +The **Contacts** toolkit is where you can create and edit all the contacts and groups that exist for your organization. Contacts can be Users (your customers), who only have access to a portal, or Administrators (your coworkers), who have access to create and edit content for your Users. Permissions are also controlled here, using Group membership. Contacts can have Membership in multiple Groups; allowing for intricate relationship management and reporting. diff --git a/topics/courses/add-content/README.md b/topics/courses/add-content/README.md index 483ac99..c7c55ef 100644 --- a/topics/courses/add-content/README.md +++ b/topics/courses/add-content/README.md @@ -1,3 +1,17 @@ -# Adding and Editing Lesson Content - -(The content is under revision. Check back soon.) +--- +description: >- + Add and edit lesson content: text, images, links, videos, and Microsoft Word + imports +--- + +# Adding and Editing Lesson Content + +Lesson content is built up block by block: text, images, links, embedded videos, and lessons imported from Microsoft Word. This section covers each of those. + +## In this section + +* [Add Course Content](add-course-content.md) +* [Adding Images](adding-images.md) +* [Adding Links](adding-links.md) +* [Adding an Embedded Video](embedding-video.md) +* [Add New Lesson From Microsoft Word](lesson-from-word.md) diff --git a/topics/courses/add-content/add-course-content.md b/topics/courses/add-content/add-course-content.md index d48c85d..edb7608 100644 --- a/topics/courses/add-content/add-course-content.md +++ b/topics/courses/add-content/add-course-content.md @@ -1,16 +1,21 @@ -# Add Course Content - +--- +description: With your course outline now created, content can be added for each lesson. +--- + +# Add Course Content + With your course outline now created, content can be added for each lesson. -Click on the **Pencil** icon next to the **Lesson** you want to add content to. On the right side of the page, the **Lesson Content** tab will be pre-selected. You can update the **Title**, **Summary** and **Body Text** of that lesson. +Click on the **Pencil** icon next to the **Lesson** you want to add content to. On the right side of the page, the **Lesson Content** tab will be pre-selected. You can update the **Title**, **Summary** and **Body Text** of that lesson. -Once you have made the required updats, click the **Save** button. +Once you have made the required updates, click the **Save** button. Under the **Activity Setup** tab you can set your **Prerequisite** for the lesson. If a prerequisite is set, learners must satisfy these prerequisites before the activity is available to start in the course. Select a **Requirement** that learners must satisfy before the activity is considered complete. **Activity Type** lists the different lesson types you can have in a course. You can select a different lesson type by selecting the field next to the type name. + * **Lesson:** A standard lesson where learners can go through content and materials. * **Assessment:** A quiz or test to assess the learner's knowledge. * **Survey:** A survey that collects feedback or information from learners. @@ -18,11 +23,11 @@ Select a **Requirement** that learners must satisfy before the activity is consi * **Link:** A clickable link that directs learners to an external website. * **Video:** A video lesson or content that you can embed for learners to watch. * **Single-Question Quiz:** A single-question quiz could be used for either a speed typing test or a data capturing test. - * For a speed typing test, the question could be about typing a sentence or a set of characters as quickly and accurately as possible, with the test measuring typing speed or accuracy. - * For a data capturing test, the question could involve entering specific information (like text, numbers, or selections) from a given dataset, testing the learner's ability to accurately capture or transcribe data. + * For a speed typing test, the question could be about typing a sentence or a set of characters as quickly and accurately as possible, with the test measuring typing speed or accuracy. + * For a data capturing test, the question could involve entering specific information (like text, numbers, or selections) from a given dataset, testing the learner's ability to accurately capture or transcribe data. In the **Activity Name** field, you can update or rename the lesson. You have the option to make lessons adaptive by selecting **Adaptive** under **Activity Settings**. When **Adaptive** is selected, the lesson will be hidden in the course until the lesson is unlocked.. -Click **Save** button after all changes were made. +Click **Save** button after all changes were made. diff --git a/topics/courses/add-content/adding-images.md b/topics/courses/add-content/adding-images.md index 93a43fd..275fdf5 100644 --- a/topics/courses/add-content/adding-images.md +++ b/topics/courses/add-content/adding-images.md @@ -1,3 +1,7 @@ +--- +description: You are able to drag and drop a picture from file into the body of the content.\ +--- + # Adding Images You are able to drag and drop a picture from file into the body of the content.\ @@ -11,6 +15,6 @@ e.g. !\[agriculture-1.jpg]\(https://e02.insite.com/files/sites/global/adding-ima In the Course you will be able to see the picture you uploaded. -![](https://e02.insite.com/files/sites/global/adding-images-or-videos/agriculture-1.jpg)
+![Agriculture 1](https://e02.insite.com/files/sites/global/adding-images-or-videos/agriculture-1.jpg)
File types supported: .png, .gif, .jpg, .jpeg
diff --git a/topics/courses/add-content/adding-links.md b/topics/courses/add-content/adding-links.md index 67dcb9c..9028949 100644 --- a/topics/courses/add-content/adding-links.md +++ b/topics/courses/add-content/adding-links.md @@ -1,3 +1,7 @@ +--- +description: You are able to add web links or email addresses in the text of your content. +--- + # Adding Links You are able to add web links or email addresses in the text of your content. @@ -6,7 +10,7 @@ When you select Create Link, the system will create the outline needed for the l You are able to configure the link with an email address instead. You can either add a email address between the square brackets or text. Instead of adding a website, you remove the http:// and add [mailto:add email address.](mailto:support@insite.com.) The full link will be \[Click Here to Email]\(mailto:support@shiftiq.com) or \[support@shiftiq.com]\(mailto:support@shiftiq.com). The text will display as [Click Here to Email](mailto:support@shiftiq.com) or [support@shiftiq.com](mailto:support@shiftiq.com) -#### Open Link in New Browser Window: +#### Open Link in New Browser Window If you require the link you are inserting to open on in a new browser window, you can us the following link:\ \text to display\ diff --git a/topics/courses/add-content/embedding-video.md b/topics/courses/add-content/embedding-video.md index 7fdf191..33a9fba 100644 --- a/topics/courses/add-content/embedding-video.md +++ b/topics/courses/add-content/embedding-video.md @@ -1,3 +1,7 @@ +--- +description: To embed a video on a Course, you will need to upload the video to either Vimeo or You Tube. +--- + # Adding an Embedded Video To embed a video on a Course, you will need to upload the video to either **Vimeo** or **You Tube**. diff --git a/topics/courses/add-content/lesson-from-word.md b/topics/courses/add-content/lesson-from-word.md index 11392b4..6730c4a 100644 --- a/topics/courses/add-content/lesson-from-word.md +++ b/topics/courses/add-content/lesson-from-word.md @@ -1,3 +1,7 @@ +--- +description: We are working on a new feature that will simplify the process of converting a Microsoft Word document into a Shift iQ lesson, using a utility +--- + # Add New Lesson From Microsoft Word We are working on a new feature that will simplify the process of converting a Microsoft Word document into a Shift iQ lesson, using a utility called Pandoc. diff --git a/topics/courses/create-course/README.md b/topics/courses/create-course/README.md index 7b38e23..5e97423 100644 --- a/topics/courses/create-course/README.md +++ b/topics/courses/create-course/README.md @@ -1,13 +1,17 @@ -# Creating and Editing Courses - +--- +description: Select the Courses Toolkit on the Admin Home Page and then select Courses counter at the top of the page. +--- + +# Creating and Editing Courses + Select the **Courses** Toolkit on the **Admin Home Page** and then select **Courses** counter at the top of the page. -Click on **Add New Course** link at the top of the page. +Click on **Add New Course** link at the top of the page. In the **Course-Creation Tool** field, select one of the following option from the dropdown list: -**One new course:** Used to create a new course. -**Upload one new course shell from a file:** Used to upload the shell from an existing course. +**One new course:** Used to create a new course. +**Upload one new course shell from a file:** Used to upload the shell from an existing course. Add the **Course Name**. -Select **Save**. +Select **Save**. diff --git a/topics/courses/create-course/add-a-course-to-a-catalog.md b/topics/courses/create-course/add-a-course-to-a-catalog.md index 7c75e53..73499f7 100644 --- a/topics/courses/create-course/add-a-course-to-a-catalog.md +++ b/topics/courses/create-course/add-a-course-to-a-catalog.md @@ -1,3 +1,7 @@ +--- +description: "From the Course home page (/ui/admin/courses/home):" +--- + # Add a Course to a Catalog From the Course home page (/ui/admin/courses/home): diff --git a/topics/courses/create-course/add-hyperlinks-videos.md b/topics/courses/create-course/add-hyperlinks-videos.md index ef8bf41..6ca42d1 100644 --- a/topics/courses/create-course/add-hyperlinks-videos.md +++ b/topics/courses/create-course/add-hyperlinks-videos.md @@ -15,7 +15,7 @@ When you select Create Link, the system will create the outline needed for the l You are able to configure the link with an email address instead. You can either add a email address between the square brackets or text. Instead of adding a website, you remove the http:// and add [mailto:add email address.](mailto:support@shiftiq.com.) The full link will be \[Click Here to Email]\(mailto:support@shiftiq.com) or \[support@shiftiq.com]\(mailto:support@shiftiq.com). The text will display as [Click Here to Email](mailto:support@shiftiq.com) or [support@shiftiq.com](mailto:support@shiftiq.com) -#### Open Link in New Browser Window: +#### Open Link in New Browser Window If you require the link you are inserting to open on in a new browser window, you can us the following link:\ \text to display\ diff --git a/topics/courses/create-course/adding-course-image.md b/topics/courses/create-course/adding-course-image.md index dfb5fc1..f6912a7 100644 --- a/topics/courses/create-course/adding-course-image.md +++ b/topics/courses/create-course/adding-course-image.md @@ -1,3 +1,7 @@ +--- +description: An image can be added for the Course tile, when the Course is Published to the Portal. +--- + # Adding a Course Image An image can be added for the Course tile, when the Course is Published to the Portal. diff --git a/topics/courses/create-course/adding-lesson.md b/topics/courses/create-course/adding-lesson.md index 681e420..b76d4c5 100644 --- a/topics/courses/create-course/adding-lesson.md +++ b/topics/courses/create-course/adding-lesson.md @@ -1,3 +1,7 @@ +--- +description: Click on the Plus icon next to the Module where you want to add the New Lesson. +--- + # How to Add and Remove Units, Modules and Lessons in a Course ## Adding a new Lesson to a course diff --git a/topics/courses/create-course/changing-font-color.md b/topics/courses/create-course/changing-font-color.md index c8e5ebb..baca7ce 100644 --- a/topics/courses/create-course/changing-font-color.md +++ b/topics/courses/create-course/changing-font-color.md @@ -1,3 +1,7 @@ +--- +description: "How to change the content font color for an entire Course:" +--- + # Changing font color of the Course How to change the content font color for an entire Course: @@ -11,6 +15,6 @@ How to change the content font color for an entire Course: Example: color: blue / color: #060606
* Click Save. -![](https://e02.insite.com/files/sites/global/change-font-color/coursefontcolor.png)\ +![Coursefontcolor](https://e02.insite.com/files/sites/global/change-font-color/coursefontcolor.png)\ \ Please note: Adding this code to the Course Style will change the color for all content in the Course. However, if there are Assessments or Surveys attached to the Course the font color for those items will not change as those are pulling data from a different toolkit. diff --git a/topics/courses/create-course/course-notifications.md b/topics/courses/create-course/course-notifications.md index 1dc7d18..fecf61a 100644 --- a/topics/courses/create-course/course-notifications.md +++ b/topics/courses/create-course/course-notifications.md @@ -1,3 +1,7 @@ +--- +description: Administrators can setup Course Stalled Notifications and Course Completed Notifications. +--- + # Setting up Course Notifications Administrators can setup **Course Stalled Notifications** and **Course Completed Notifications**. @@ -16,7 +20,7 @@ Course stalled notifications can be sent to **Learners** and **Administrators**. * $AppUrl * $CourseName * $CourseStarted -* $LearnerIdentifie +* $LearnerIdentifier * $LearnerFirstName * $LearnerLastName
@@ -32,6 +36,6 @@ Course completion notifications can be sent to **Learners** and **Administrators * $AppUrl * $CourseName * $CourseStarted -* $LearnerIdentifie +* $LearnerIdentifier * $LearnerFirstName * $LearnerLastName
diff --git a/topics/courses/create-course/course-privacy-settings.md b/topics/courses/create-course/course-privacy-settings.md index d02ee48..15b6969 100644 --- a/topics/courses/create-course/course-privacy-settings.md +++ b/topics/courses/create-course/course-privacy-settings.md @@ -1,9 +1,13 @@ -# Adding Privacy Settings to a Course - -Privacy settings can be applied to a course to restrict access to specific users or groups, ensuring that only authorized individuals can view or participate in the course content. +--- +description: Privacy settings can be applied to a course to restrict access to specific users or groups, ensuring that only authorized individuals can view +--- + +# Adding Privacy Settings to a Course + +Privacy settings can be applied to a course to restrict access to specific users or groups, ensuring that only authorized individuals can view or participate in the course content. * In the Course click on the **Course Setup** tab, then the **Privacy Settings** tab. * Click on the **Plus** icon () under the **Groups** heading. * Search for the **Group** that you want to add and click the **Add** button. * Only users added into the selected Group(s) will be able to access this course once it has been published to the Portal. -* Click the **Save** button. +* Click the **Save** button. diff --git a/topics/courses/create-course/publish-course.md b/topics/courses/create-course/publish-course.md index 4d0287a..09dc5ce 100644 --- a/topics/courses/create-course/publish-course.md +++ b/topics/courses/create-course/publish-course.md @@ -1,10 +1,16 @@ -# Publishing a Course to your Learner Portal - +--- +description: "There are 2 ways to Publish a course to the portal:" +--- + +# Publishing a Course to your Learner Portal + There are 2 ways to Publish a course to the portal: + 1. From the Course itself; 2. From the Sites toolkit. **1. Publish a Course to the Portal, from the Course:** + * In the Course, click on the **Course Setup** tab, then the **Publication** tab. * Select the Site URL in the **Web Portal** field (organization.insite.com / organization.shiftiq.com). * Select the **Web Folder** (page) where you want to publish the course to. @@ -21,4 +27,4 @@ Courses remain visible to administrators only, unless they are **published** to * Click **Save** * The course will be **published** on the portal for users to complete. -![course-on-portal.png](https://e02.insite.com/files/sites/global/publish-course/course-on-portal.png) +![course-on-portal.png](https://e02.insite.com/files/sites/global/publish-course/course-on-portal.png) diff --git a/topics/courses/create-course/setting-prerequisites.md b/topics/courses/create-course/setting-prerequisites.md index 4243dab..d2df8bb 100644 --- a/topics/courses/create-course/setting-prerequisites.md +++ b/topics/courses/create-course/setting-prerequisites.md @@ -1,19 +1,24 @@ -# Setting Prerequisites - -By setting **Prerquisites** in a course, Learners must satisfy these prerequisites before the activity is available to start. +--- +description: By setting Prerequisites in a course, Learners must satisfy these prerequisites before the activity is available to start. +--- + +# Setting Prerequisites + +By setting **Prerequisites** in a course, Learners must satisfy these prerequisites before the activity is available to start. **Prerequisites** that can be selected: -* **Acitivity Completed** - * Select the Lesson you require the Learner to complete before the activity is availalbe to start. -* **Assessmnet Passes** - * Select the Assessment Form the user needs to pass before the activity is available to start. + +* **Activity Completed** + * Select the Lesson you require the Learner to complete before the activity is available to start. +* **Assessment Passes** + * Select the Assessment Form the user needs to pass before the activity is available to start. * **Assessment Failed** - * Select the Assessment Form the user needs to pass before the activity is available to start. + * Select the Assessment Form the user needs to pass before the activity is available to start. * **Assessment Scored** - * Select the Assessment Form and set score range the user needs to achieve before the activity is available to start. + * Select the Assessment Form and set score range the user needs to achieve before the activity is available to start. * **Question Answered Correctly** - * Select the Question Bank and Question the learner needs answer correctly before the activity is available to start. + * Select the Question Bank and Question the learner needs answer correctly before the activity is available to start. * **Question Answered Incorrectly** - * Select the Question Bank and Question the learner needs answer incorrectly before the activity is available to start. + * Select the Question Bank and Question the learner needs answer incorrectly before the activity is available to start. * **Grade Item Passed** -* **Grade Item Failed** +* **Grade Item Failed** diff --git a/topics/courses/overview.md b/topics/courses/overview.md index 50c0a84..118ca6b 100644 --- a/topics/courses/overview.md +++ b/topics/courses/overview.md @@ -1,3 +1,9 @@ -# Overview - -Create engaging content for your learners. Courses can contain lessons, surveys, assessments, pictures, videos, SCORM packages and more. Additional or alternative content can be triggered based on permission settings. +--- +description: >- + Build courses with lessons, surveys, assessments, images, videos, and SCORM + packages, with content paths driven by learner permissions +--- + +# Overview + +Create engaging content for your learners. Courses can contain lessons, surveys, assessments, pictures, videos, SCORM packages and more. Additional or alternative content can be triggered based on permission settings. diff --git a/topics/courses/scorm-courses/README.md b/topics/courses/scorm-courses/README.md index 58c6a33..640b2e5 100644 --- a/topics/courses/scorm-courses/README.md +++ b/topics/courses/scorm-courses/README.md @@ -1,3 +1,16 @@ -# Working with SCORM and Shift iQ Courses - -(The content is under revision. Check back soon.) +--- +description: >- + Upload SCORM packages, configure SCORM Cloud, and embed SCORM lessons in + Shift iQ courses +--- + +# Working with SCORM and Shift iQ Courses + +SCORM packages can be uploaded to Shift iQ and embedded inside courses, including multi-lingual variants. This section covers uploading packages, configuring the SCORM Cloud connection, embedding them, and supporting multiple languages. + +## In this section + +* [How to Upload a SCORM Course to SCORM](upload-scorm-course.md) +* [SCORM Cloud connection settings](scorm-settings.md) +* [Embedding a SCORM package in your Shift iQ Course](adding-scorm-courses.md) +* [Uploading SCORM with different Languages](scorm-multi-lingual.md) diff --git a/topics/courses/scorm-courses/adding-scorm-courses.md b/topics/courses/scorm-courses/adding-scorm-courses.md index 9566fe3..9fedecd 100644 --- a/topics/courses/scorm-courses/adding-scorm-courses.md +++ b/topics/courses/scorm-courses/adding-scorm-courses.md @@ -1,3 +1,7 @@ +--- +description: When adding a SCORM course to Sandbox or Development, if you select SCORM Course for the Link Type then it is set to Preview mode by default and +--- + # Embedding a SCORM package in your Shift iQ Course When adding a SCORM course to **Sandbox** or **Development**, if you select **SCORM Course** for the **Link Type** then it is set to **Preview** mode by default and the **Launch SCORM Course in Preview mode** is selected by default. diff --git a/topics/courses/scorm-courses/scorm-multi-lingual.md b/topics/courses/scorm-courses/scorm-multi-lingual.md index 06dfe67..39ee6c0 100644 --- a/topics/courses/scorm-courses/scorm-multi-lingual.md +++ b/topics/courses/scorm-courses/scorm-multi-lingual.md @@ -1,5 +1,9 @@ -# Uploading SCORM with different Languages - +--- +description: "Login to https://cloud.scorm.com/sc/guest/SignInForm" +--- + +# Uploading SCORM with different Languages + Login to **https://cloud.scorm.com/sc/guest/SignInForm** Select the **Organization (Realm)** you want to upload a **SCORM** course for. @@ -10,14 +14,14 @@ Click on **Add Content** (Top Right Corner) and select **Import a SCORM, AICC, x ![scorm-upload.png](https://e02.insite.com/files/sites/e02/scorm-multi-lingual/scorm-upload.png) -Specify a **Course ID** for the file you are uploading. Add the language code behind the Course ID you are adding, e.g. ***Planning-for-Your-Future-V1-en*** (for English) OR ***Planning-for-Your-Future-V1-fr*** (for French) OR ***Planning-for-Your-Future-V1-es*** (for Spanish). +Specify a **Course ID** for the file you are uploading. Add the language code behind the Course ID you are adding, e.g. ***Planning-for-Your-Future-V1-en*** (for English) OR ***Planning-for-Your-Future-V1-fr*** (for French) OR ***Planning-for-Your-Future-V1-es*** (for Spanish). Choose the **SCORM** or **xAPI** file you wish to upload by clicking on **Browse**. Once file has been selected, click **Import Course**. ![scorm-file.png](https://e02.insite.com/files/sites/e02/scorm-multi-lingual/scorm-file.png) -Once the course has been uploaded, you are able to change the Lauch behaviour in **Course Properties**. After your changes has been made, click **Save**. +Once the course has been uploaded, you are able to change the Launch behaviour in **Course Properties**. After your changes has been made, click **Save**. ![scorm-8.png](https://e02.insite.com/files/sites/global/upload-scorm-course/scorm-8.png) -The **Course ID** (e.g. Planning-for-Your-Future-V1) is what you use as the **SCORM Course ID** +The **Course ID** (e.g. Planning-for-Your-Future-V1) is what you use as the **SCORM Course ID** diff --git a/topics/courses/scorm-courses/scorm-settings.md b/topics/courses/scorm-courses/scorm-settings.md index 74fee76..9286888 100644 --- a/topics/courses/scorm-courses/scorm-settings.md +++ b/topics/courses/scorm-courses/scorm-settings.md @@ -1,3 +1,7 @@ +--- +description: "First, find the SCORM Cloud AppId for the tenant. This is in the SCORM Cloud control panel here:" +--- + # SCORM Cloud connection settings First, find the SCORM Cloud AppId for the tenant. This is in the SCORM Cloud control panel here: diff --git a/topics/courses/scorm-courses/upload-scorm-course.md b/topics/courses/scorm-courses/upload-scorm-course.md index ad73478..f05e0b0 100644 --- a/topics/courses/scorm-courses/upload-scorm-course.md +++ b/topics/courses/scorm-courses/upload-scorm-course.md @@ -1,5 +1,9 @@ -# How to Upload a SCORM Course to SCORM - +--- +description: "Login to https://cloud.scorm.com/sc/guest/SignInForm" +--- + +# How to Upload a SCORM Course to SCORM + Login to **https://cloud.scorm.com/sc/guest/SignInForm** Select the **Tenant (Realm)** you want to upload a **SCORM** course for. @@ -14,10 +18,11 @@ Specify a **Course ID** for the file you are uploading (e.g. Planning-for-Your-F ![scorm-7.png](https://e02.insite.com/files/sites/global/upload-scorm-course/scorm-7.png) -Once the course has been uploaded, you are able to change the Lauch behaviour in **Course Properties**. After your changes has been made, click **Save**. +Once the course has been uploaded, you are able to change the Launch behaviour in **Course Properties**. After your changes has been made, click **Save**. ![scorm-8.png](https://e02.insite.com/files/sites/global/upload-scorm-course/scorm-8.png) -The **Course ID** (e.g. Planning-for-Your-Future-V1) is what you use as: +The **Course ID** (e.g. Planning-for-Your-Future-V1) is what you use as: + * **Hook / Integration Code in Courses V1** -* **SCORM Course ID in Courses V2** +* **SCORM Course ID in Courses V2** diff --git a/topics/events/class-registration.md b/topics/events/class-registration.md index c96e493..620bf33 100644 --- a/topics/events/class-registration.md +++ b/topics/events/class-registration.md @@ -1,10 +1,12 @@ +--- +description: "On the Classes Search page in the Portal, users will see various statuses. The flowchart below illustrates the different statuses visible to users:" +--- + # What Learners see on the Class Registration Portal Page On the Classes Search page in the Portal, users will see various statuses. The flowchart below illustrates the different statuses visible to users: -
- - +
Class Statuses (Portal)
During the **Class Registration** process, there are 5 steps the user will move through to complete their registration: diff --git a/topics/events/classes-for-exams/README.md b/topics/events/classes-for-exams/README.md index a20de99..7d52a87 100644 --- a/topics/events/classes-for-exams/README.md +++ b/topics/events/classes-for-exams/README.md @@ -1,5 +1,5 @@ # Using Classes for Exam setup -## To enable the Exam Feature in Classes, please contact your Shift iQ Account Representative to assist with the initial setup. - -##### Shift iQ has functionality in the Classes toolkit that Organizations can use to serve up Assessment Forms to test Learner's knowledge of the Class they completed. +## To enable the Exam Feature in Classes, please contact your Shift iQ Account Representative to assist with the initial setup + +##### Shift iQ has functionality in the Classes toolkit that Organizations can use to serve up Assessment Forms to test Learner's knowledge of the Class they completed diff --git a/topics/events/classes-for-exams/assign-assessments.md b/topics/events/classes-for-exams/assign-assessments.md index bc30750..48050d7 100644 --- a/topics/events/classes-for-exams/assign-assessments.md +++ b/topics/events/classes-for-exams/assign-assessments.md @@ -1,14 +1,18 @@ +--- +description: Before attaching an Assessment Forms to a learners registration, you need to attach the required Assessment Forms to the Class. +--- + # Assign Assessments ### Attach an Assessment to Class -Before attaching an Assessment Froms to a learners registration, you need to attach the required Assessment Forms to the Class. You are able to attached multiple Assessment Forms to a class. +Before attaching an Assessment Forms to a learners registration, you need to attach the required Assessment Forms to the Class. You are able to attached multiple Assessment Forms to a class. Under the Class Setup tab, scroll down to the Assessments card and click the Add Form button. Filter for the Assessment Form you want to attach to the Class and select the Form. The selected Assessment Form will be displayed below the Add Form button. If you attached the incorrect Form, you can click the Trash Can icon () on the right side of the Form to remove it from the Class. -If more than one Assessment Forms need to be attched to the Class, follow the same process as above for each Form you want to attach. +If more than one Assessment Forms need to be attached to the Class, follow the same process as above for each Form you want to attach. ### Assign an Assessment to Learner diff --git a/topics/events/classes-for-exams/exam-login-page.md b/topics/events/classes-for-exams/exam-login-page.md index 718fabb..7542073 100644 --- a/topics/events/classes-for-exams/exam-login-page.md +++ b/topics/events/classes-for-exams/exam-login-page.md @@ -1,3 +1,7 @@ +--- +description: For learners to login for their exam, they need access to the /ui/lobby/events/login page. +--- + # Exam Login Page For learners to login for their exam, they need access to the **/ui/lobby/events/login** page. diff --git a/topics/events/classes-for-exams/login-credentials-for-exam.md b/topics/events/classes-for-exams/login-credentials-for-exam.md index b0b47fa..d5f2abc 100644 --- a/topics/events/classes-for-exams/login-credentials-for-exam.md +++ b/topics/events/classes-for-exams/login-credentials-for-exam.md @@ -1,23 +1,30 @@ -# Login Credentials for Exam - +--- +description: An Exam Specific Password is generated for a Learner at the time they complete their Class registration. +--- + +# Login Credentials for Exam + ### System-Generated Exam Passwords -An **Exam Specific Password** is generated for a Learner at the time they complete their Class registration. The password appears to a system administartor, below the learner's registration Status, under the Status column in the Class. +An **Exam Specific Password** is generated for a Learner at the time they complete their Class registration. The password appears to a system administrator, below the learner's registration Status, under the Status column in the Class. -The password is editable by a system administrator, by clicking the Pencil icon () next to the learner's registration. In the Registration card, you can update the password in the Exam Password field. Click the Save button after making any changes to the password. The new password will update and be displayed under the regisrtation Status of the learner. +The password is editable by a system administrator, by clicking the Pencil icon () next to the learner's registration. In the Registration card, you can update the password in the Exam Password field. Click the Save button after making any changes to the password. The new password will update and be displayed under the registration Status of the learner. ### Providing Exam Login details to a Learner To login to an exam, learners require the following information: + * **Learner ID (Person Code)** - * The **Learner ID (Person Code)** is in the learner's **Contact Record** and should be added to the learner's Contact Record either prior or during the registration. It can be added after registration, but if added after it will not be included in the **RegistrationCompleted** alert (see below). - * A **Learner ID (Person Code)** can also be **automatically** generated at the time a **New** Contact Record is created. Ask your Shift iQ Account Representative for further information. + * The **Learner ID (Person Code)** is in the learner's **Contact Record** and should be added to the learner's Contact Record either prior or during the registration. It can be added after registration, but if added after it will not be included in the **RegistrationCompleted** alert (see below). + * A **Learner ID (Person Code)** can also be **automatically** generated at the time a **New** Contact Record is created. Ask your Shift iQ Account Representative for further information. * **Exam Event Password** - * The **Exam Event Password** is generated at the time of registration. + * The **Exam Event Password** is generated at the time of registration. The **Learner ID** and **Exam Event Password** can be provided to learners in 2 ways: -1. After the learner completes their class registration, they receive the **RegistrationCompleted** alert with their registration details. We can add the **Exam Login** details to the **RegistrationCompleted** alert, so the learner will have their exam login details. - * The learner will **only** be able to login to their exam using the **Events Login** page, which will be provded to the learner by the Instructor/Assessor/Invigilator at the time they are taking their exam. This password will not allow them to login using the **Portal Sign In** page. - * Learners do **not** require previous **Access Granted** to Shift iQ to login for an exam, as long as they have a contact record in Shift iQ and is registered for a class. -2. The exam login details can be provided to the learners by the Instructor/Assessor/Invigilator at the time they are taking their exam. +1. After the learner completes their class registration, they receive the **RegistrationCompleted** alert with their registration details. We can add the **Exam Login** details to the **RegistrationCompleted** alert, so the learner will have their exam login details. + + * The learner will **only** be able to login to their exam using the **Events Login** page, which will be provided to the learner by the Instructor/Assessor/Invigilator at the time they are taking their exam. This password will not allow them to login using the **Portal Sign In** page. + * Learners do **not** require previous **Access Granted** to Shift iQ to login for an exam, as long as they have a contact record in Shift iQ and is registered for a class. + +2. The exam login details can be provided to the learners by the Instructor/Assessor/Invigilator at the time they are taking their exam. diff --git a/topics/events/overview.md b/topics/events/overview.md index 69fc0ed..a9b610f 100644 --- a/topics/events/overview.md +++ b/topics/events/overview.md @@ -1,3 +1,16 @@ -# Overview - -(The content is under revision. Check back soon.) +--- +description: >- + Schedule classes and exam events, manage rosters and seating, and publish + registration tiles to learner portals +--- + +# Overview + +The **Events** toolkit is where you schedule classes and exam events for your learners and manage the registrations attached to them. + +Use the pages in this section to: + +* Schedule a new exam event — see [Schedule a New Exam Event](schedule-exam/README.md). +* Schedule a new class with content, settings, and seating — see [Schedule a New Class](schedule-new-class/README.md). +* Use a class as an exam delivery container — see [Using Classes for Exam setup](classes-for-exams/README.md). +* Understand the learner view of registration — see [What Learners see on the Class Registration Portal Page](class-registration.md). diff --git a/topics/events/schedule-exam/README.md b/topics/events/schedule-exam/README.md index c1d802e..e1b63f0 100644 --- a/topics/events/schedule-exam/README.md +++ b/topics/events/schedule-exam/README.md @@ -1,3 +1,11 @@ -# Schedule a New Exam Event - -Select the **Events** toolkit on the **Admin Home Page**. +--- +description: Schedule new exam events from the Events toolkit +--- + +# Schedule a New Exam Event + +An exam event is a scheduled assessment delivered to a roster of learners. From the **Admin Home Page**, open the **Events** toolkit to schedule a new one. + +## In this section + +* [Create a New Exam Event](create-a-new-exam-event.md) diff --git a/topics/events/schedule-exam/create-a-new-exam-event.md b/topics/events/schedule-exam/create-a-new-exam-event.md index 9dcf647..fe99094 100644 --- a/topics/events/schedule-exam/create-a-new-exam-event.md +++ b/topics/events/schedule-exam/create-a-new-exam-event.md @@ -1,21 +1,26 @@ -# Create a New Exam Event - +--- +description: Select the Events toolkit on the Admin Home Page. +--- + +# Create a New Exam Event + Select the **Events** toolkit on the **Admin Home Page**. Select **Schedule a New Exam Event** in the **Administration Tool**s panel. -- Select the **Exam Type** you want to create - - Class - - Individual (Accommodated) - - Individual (Not Accommodated) - - Sitting -- Select **Exam Format** - - Online - - Paper -- **Class/Session Code** (The reference number for related training programs) -- **Billing Code** (If you require billing codes to be added, please contact your InSite Account Representative to assist. -- Add the **Start Date and Time** for the Event -- Add the **Exam Candidate Limit (Capacity)** -- Select the **Venue** for the Exam Event (The training provider, organization, or agency hosting the event) -- If the Exam Event will be in a specific **Building and Room**, add the physical location within the venue where the event occurs. -Click **Save** +* Select the **Exam Type** you want to create + * Class + * Individual (Accommodated) + * Individual (Not Accommodated) + * Sitting +* Select **Exam Format** + * Online + * Paper +* **Class/Session Code** (The reference number for related training programs) +* **Billing Code** (If you require billing codes to be added, please contact your InSite Account Representative to assist. +* Add the **Start Date and Time** for the Event +* Add the **Exam Candidate Limit (Capacity)** +* Select the **Venue** for the Exam Event (The training provider, organization, or agency hosting the event) +* If the Exam Event will be in a specific **Building and Room**, add the physical location within the venue where the event occurs. + +Click **Save** diff --git a/topics/events/schedule-new-class/README.md b/topics/events/schedule-new-class/README.md index f2824ed..03098d0 100644 --- a/topics/events/schedule-new-class/README.md +++ b/topics/events/schedule-new-class/README.md @@ -1,3 +1,22 @@ -# Schedule a New Class - -(The content is under revision. Check back soon.) +--- +description: >- + Create, configure, publish, and manage class events end-to-end +--- + +# Schedule a New Class + +A class is a scheduled event with registrations, content, settings, and a publication state. This section walks through creating a new class and configuring every aspect of it — registrations, gradebooks, seating, content, privacy, publication, and statuses. + +## In this section + +* [How to Create a New Class](create-class.md) +* [Add and Edit Class Information](class-information.md) +* [Manually Adding/Removing Registrations](adding-registrations.md) +* [Assign Gradebook to Class](assign-gradebook.md) +* [Add Seating to a Class](add-seating-to-class.md) +* [Adding Content](adding-content.md) +* [Class Privacy](class-privacy.md) +* [Class Settings](class-settings.md) +* [Publish Class Registration](publish-class-registration.md) +* [Adding Class Registration Tile on Portal Page](add-registration-tile.md) +* [Class Statuses](class-statuses.md) diff --git a/topics/events/schedule-new-class/add-seating-to-class.md b/topics/events/schedule-new-class/add-seating-to-class.md index 7acba8a..a67750a 100644 --- a/topics/events/schedule-new-class/add-seating-to-class.md +++ b/topics/events/schedule-new-class/add-seating-to-class.md @@ -1,28 +1,36 @@ -# Add Seating to a Class - +--- +description: Under the Seats panel, select Add Seat +--- + +# Add Seating to a Class + ## Seat Creation + Under the **Seats** panel, select **Add Seat** -- Add a **Seat Name** (title for the seat) -- Add **Seat Description** -- Set **Seat Price** - - Free - - Single Price - - Multiple Price Levels (Example: members pay less than non-members, see below) -- Choose whether **Taxes** apply for this seat. -- Add **Seat Agreement** (Terms & Conditions that a users needs to Agree to before moving forward with class booking) -- Select **Save** + +* Add a **Seat Name** (title for the seat) +* Add **Seat Description** +* Set **Seat Price** + * Free + * Single Price + * Multiple Price Levels (Example: members pay less than non-members, see below) +* Choose whether **Taxes** apply for this seat. +* Add **Seat Agreement** (Terms & Conditions that a users needs to Agree to before moving forward with class booking) +* Select **Save** ## Seats with Multiple Price Levels + When creating seats for a Class, different price levels can be created for different users in your Organization (Example: Members pay less than non-members). -Only users that are in the Employer group, with the Group Status specified in the seat setup, will be able to see the seat price being created. +Only users that are in the Employer group, with the Group Status specified in the seat setup, will be able to see the seat price being created. Under **Seat Price**, select the **Multiple Price Levels** option, and add the following information: -* **Price Name:** The name of the seat, this will be visible to the user when registering for a class. + +* **Price Name:** The name of the seat, this will be visible to the user when registering for a class. * **Price Amount:** The cost of the seat. * **Group Status:** Select the Group Status you are creating the seat for. - * The **Group Status** field is linked to the Group Status added to an **Employer** group. If none of your **Employer** groups have a **Group Status** set, there will be **no** options availabel to select in this field during seat creation. - * Please see **Create a New Group** for instruction on how to create a new Employer group. + * The **Group Status** field is linked to the Group Status added to an **Employer** group. If none of your **Employer** groups have a **Group Status** set, there will be **no** options availabel to select in this field during seat creation. + * Please see **Create a New Group** for instruction on how to create a new Employer group. * Click the **Add Price** button to save your changes. * Repeat the above steps to create all different levels of seats required for the Class. - -Click the **Save** button once all the required seats have been created. + +Click the **Save** button once all the required seats have been created. diff --git a/topics/events/schedule-new-class/adding-content.md b/topics/events/schedule-new-class/adding-content.md index a419caa..0749c82 100644 --- a/topics/events/schedule-new-class/adding-content.md +++ b/topics/events/schedule-new-class/adding-content.md @@ -1,3 +1,7 @@ +--- +description: Content can be added to a class to provide users with a description or additional information about the class they are registering for. +--- + # Adding Content Content can be added to a class to provide users with a description or additional information about the class they are registering for. diff --git a/topics/events/schedule-new-class/adding-registrations.md b/topics/events/schedule-new-class/adding-registrations.md index 5abed92..cb9fb3c 100644 --- a/topics/events/schedule-new-class/adding-registrations.md +++ b/topics/events/schedule-new-class/adding-registrations.md @@ -1,3 +1,7 @@ +--- +description: Under the Registration tab, Administrators are able to manually Add Registrations to a class and download different class Reports. +--- + # Manually Adding/Removing Registrations Under the **Registration** tab, Administrators are able to manually **Add Registrations** to a class and download different class **Reports**. diff --git a/topics/events/schedule-new-class/assign-gradebook.md b/topics/events/schedule-new-class/assign-gradebook.md index 62d40ae..d6ff0ee 100644 --- a/topics/events/schedule-new-class/assign-gradebook.md +++ b/topics/events/schedule-new-class/assign-gradebook.md @@ -1,33 +1,39 @@ -# Assign Gradebook to Class - +--- +description: Navigate to the Gradebooks tab in the Class you created. +--- + +# Assign Gradebook to Class + Navigate to the **Gradebooks** tab in the **Class** you created. An administrator can select to either create a **New Gradebook** or **Find Gradebook** to attach an existing Gradebook. #### New Gradebook -* Click on the **New Gradebook** button. -* Select if you want to: - * Create the One new gradebook - * Create a **Title** for the Gradebook. - * The **Class** you are creating the Gradebook in wil automatically be assigned to the new Gradebook. - * Set **Period** if required. - * Assign the **Achievement** to the Gradebook - * Select **Save** - * Duplicate copy af an existing gradebook - * Select the Gradebook you want to duplicate. - * Create a **Title** for the Gradebook. - * The **Class** you are creating the Gradebook in wil automatically be assigned to the new Gradebook. - * Set **Period** if required. - * Assign the **Achievement** to the Gradebook - * Select **Save** - * Upload one new gradebook from file - * Selct the *.json file of the Gradebook you want to upload. - * Select **Save** + +* Click on the **New Gradebook** button. +* Select if you want to: + * Create the One new gradebook + * Create a **Title** for the Gradebook. + * The **Class** you are creating the Gradebook in wil automatically be assigned to the new Gradebook. + * Set **Period** if required. + * Assign the **Achievement** to the Gradebook + * Select **Save** + * Duplicate copy af an existing gradebook + * Select the Gradebook you want to duplicate. + * Create a **Title** for the Gradebook. + * The **Class** you are creating the Gradebook in wil automatically be assigned to the new Gradebook. + * Set **Period** if required. + * Assign the **Achievement** to the Gradebook + * Select **Save** + * Upload one new gradebook from file + * Select the *.json file of the Gradebook you want to upload. + * Select **Save** #### Find Gradebook + * Click on the **Find Gradebook** button. * From the dropdown list, select the **Gradebook** you want to attach to the **Class**. * Click the Plus icon () to add the **Gradebook** You can remove the Gradebook from the Class by clicking on the Trash Can icon next to the Gradebook attached to the Class. -***Note: Once users in a Class as been added to the Gradebook, and they have Scores in the Gradebook, you are not able to remove the Gradebook from the Class.*** +***Note: Once users in a Class as been added to the Gradebook, and they have Scores in the Gradebook, you are not able to remove the Gradebook from the Class.*** diff --git a/topics/events/schedule-new-class/class-information.md b/topics/events/schedule-new-class/class-information.md index 6e0b03d..d68ccb1 100644 --- a/topics/events/schedule-new-class/class-information.md +++ b/topics/events/schedule-new-class/class-information.md @@ -1,3 +1,7 @@ +--- +description: Under the Registration tab, Administrators are able to manually Add Registrations to a class and download different class Reports. +--- + # Add and Edit Class Information ## Registrations Tab @@ -20,14 +24,14 @@ Under the **Registration** tab, Administrators are able to manually **Add Regist * Billing Customer * Employer * Click **Save** after changes were made to the users registration.
-* **Download Reports** +* **Download Reports** - * Reports available for Classes: - * Registration Report (\*.pdf / \*.xlsx) - * Detailed Registration Report (\*.pdf / \*.xlsx) - * Attendee List (\*.pdf / \*.xlsx) - * Scores Report (\*.pdf / \*.xlsx) - * Most Improved Report (\*.xlsx)
+ * Reports available for Classes: + * Registration Report (\*.pdf / \*.xlsx) + * Detailed Registration Report (\*.pdf / \*.xlsx) + * Attendee List (\*.pdf / \*.xlsx) + * Scores Report (\*.pdf / \*.xlsx) + * Most Improved Report (\*.xlsx)
### Gradebooks Tab @@ -35,7 +39,7 @@ Under the **Registration** tab, Administrators are able to manually **Add Regist * Create **New Gradebook** * Click on the **New Gradebook** button. * Create a **Title** for the new Gradebook, select **Period** (optional) and select the **Achievement**. - * Choose if you want to include only Scores in the Gradebook or Standards (Compentencies) as well. If Standards is included, select the Competency Framework you want to attached to the Gradebook. + * Choose if you want to include only Scores in the Gradebook or Standards (Competencies) as well. If Standards is included, select the Competency Framework you want to attached to the Gradebook. * Select **Save**
* Add **Existing Gradebook** * Click on the **Find Gradebook** button. diff --git a/topics/events/schedule-new-class/class-privacy.md b/topics/events/schedule-new-class/class-privacy.md index 5472e17..a51dce2 100644 --- a/topics/events/schedule-new-class/class-privacy.md +++ b/topics/events/schedule-new-class/class-privacy.md @@ -1,6 +1,10 @@ -# Class Privacy - -**Groups** in the Contacts toolkit can be used to set access permissions for the **Classes** published on the **Portal**. If no Groups have been created or new groups are required, it can be added in the Contacts toolkit, using Groups (See **Create a New Group**). +--- +description: Groups in the Contacts toolkit can be used to set access permissions for the Classes published on the Portal. +--- + +# Class Privacy + +**Groups** in the Contacts toolkit can be used to set access permissions for the **Classes** published on the **Portal**. If no Groups have been created or new groups are required, it can be added in the Contacts toolkit, using Groups (See **Create a New Group**). Under the Privacy tab click on the Pencil Icon () next to the Groups field. @@ -9,4 +13,4 @@ In the **Filter** card, select the **Group Type** (**Department**, **District**, Click the **Save** button to save your changes. *Note: You are able to give permissions to different Group Types for the same Folder/Page. -e.g. A combination of Groups withing a Role and within a List can be added to the permission list of a Foler/Page.* +e.g. A combination of Groups withing a Role and within a List can be added to the permission list of a Folder/Page.* diff --git a/topics/events/schedule-new-class/class-settings.md b/topics/events/schedule-new-class/class-settings.md index 37080de..f04134e 100644 --- a/topics/events/schedule-new-class/class-settings.md +++ b/topics/events/schedule-new-class/class-settings.md @@ -1,3 +1,7 @@ +--- +description: "After a Class is created, the following information can be added or edited under the Class Setup tab:" +--- + # Class Settings After a **Class** is created, the following information can be added or edited under the **Class Setup** tab: diff --git a/topics/events/schedule-new-class/class-statuses.md b/topics/events/schedule-new-class/class-statuses.md index a84d613..2f8b8b2 100644 --- a/topics/events/schedule-new-class/class-statuses.md +++ b/topics/events/schedule-new-class/class-statuses.md @@ -1,5 +1,9 @@ +--- +description: After a class is created, an administrator will see various statuses appear next to the class. +--- + # Class Statuses After a class is created, an administrator will see various statuses appear next to the class. The flowchart below shows when statuses are updated and what they are updated to: -
+
Class Statuses (1)
diff --git a/topics/events/schedule-new-class/create-class.md b/topics/events/schedule-new-class/create-class.md index de3100b..3ada384 100644 --- a/topics/events/schedule-new-class/create-class.md +++ b/topics/events/schedule-new-class/create-class.md @@ -1,9 +1,13 @@ +--- +description: From the Admin Home Screen select the Event Toolkit +--- + # How to Create a New Class ## Create a New Class * From the **Admin Home Screen** select the **Event** Toolkit -* Under the **Classes** heading, select the **Clases** counter. +* Under the **Classes** heading, select the **Classes** counter. * At the top of the page, click on **Add New Class** On the **Schedule a New Class** page: diff --git a/topics/events/schedule-new-class/publish-class-registration.md b/topics/events/schedule-new-class/publish-class-registration.md index 9e2df97..c1ffb7e 100644 --- a/topics/events/schedule-new-class/publish-class-registration.md +++ b/topics/events/schedule-new-class/publish-class-registration.md @@ -1,11 +1,15 @@ -# Publish Class Registration - +--- +description: When you are ready to Publish your Class to the user Portal, search for the Class you created and under the Class Setup tab, click on the Publish button. +--- + +# Publish Class Registration + When you are ready to **Publish** your **Class** to the user Portal, search for the **Class** you created and under the **Class Setup** tab, click on the **Publish** button. Select the **Registration Start** date (The date and time when registration for this event is open, after which new registrations are permitted) and **Registration Deadline** date (The date and time when registration for this event is closed, after which no new registrations are permitted.). -*Note: The **Registration Start** and **Registration Deadline** dates controls when the Self-Register and Register Employees buttons appear on the Class Outline page.* +*Note: The **Registration Start** and **Registration Deadline** dates controls when the Self-Register and Register Employees buttons appear on the Class Outline page.* The **Register Employees** button can be added/removed by Organization specific settings. Please ask your Shift iQ Account Representative if you need to add/remove this button. -Click the **Publish** button. +Click the **Publish** button. diff --git a/topics/messages/authoring-messages/README.md b/topics/messages/authoring-messages/README.md index 3913629..9fef47e 100644 --- a/topics/messages/authoring-messages/README.md +++ b/topics/messages/authoring-messages/README.md @@ -1,3 +1,16 @@ -# Authoring messages - -(The content is under revision. Check back soon.) +--- +description: >- + Create new messages, format their contents, and use placeholders to + personalize them +--- + +# Authoring messages + +Authoring covers the work of writing the message itself: composing the contents, formatting them, and inserting placeholders that get replaced per recipient at send time. + +## In this section + +* [Create New Message](create-new-message.md) +* [Markdown Reference](markdown-reference.md) +* [Message Placeholders](message-placeholders.md) +* [Editing and Formatting Message Contents](edit-contents.md) diff --git a/topics/messages/authoring-messages/create-new-message.md b/topics/messages/authoring-messages/create-new-message.md index f7a6f84..9255d25 100644 --- a/topics/messages/authoring-messages/create-new-message.md +++ b/topics/messages/authoring-messages/create-new-message.md @@ -1,16 +1,20 @@ -# Create New Message - +--- +description: From the Admin Home Page, select Messages toolkit. +--- + +# Create New Message + From the Admin Home Page, select **Messages** toolkit. Select your **Message Type**: * **Invitation:** Tenants can send an **Invitation** to users to complete a **Survey**. The system tracks who has answered the original survey invitation. If you re-send an invitation, the system will omit the people who have already answered the survey. * **Newsletter:** This can be used to send News, Updates or Reminders to users -* **Notification:** Notifications can be sent to users for different reasons (Do NOT use for general communication). +* **Notification:** Notifications can be sent to users for different reasons (Do NOT use for general communication). **Example:** - - Reminder to complete a survey - - Confirmation of exam registration - - Failed Login Attempts + * Reminder to complete a survey + * Confirmation of exam registration + * Failed Login Attempts Click the **Add New Invitation**, **Add New Newsletter** or **Add New Notification** link at the top of the **Search** page. @@ -20,4 +24,4 @@ Choose an **Subject** for your Invitation, Newsletter or Notification. The **Sub Select the **Sender** for your Invitation, Newsletter or Notification. Contact [**support@shiftiq.com**](mailto:support@shiftiq.com) to configure the list of Senders available in your account. -Select **Save** +Select **Save** diff --git a/topics/messages/authoring-messages/edit-contents.md b/topics/messages/authoring-messages/edit-contents.md index da6c088..143d150 100644 --- a/topics/messages/authoring-messages/edit-contents.md +++ b/topics/messages/authoring-messages/edit-contents.md @@ -1,9 +1,14 @@ -# Editing and Formatting Message Contents - +--- +description: Add your message content here using the Shift iQ markdown Content Authoring tool, designed to be fast, light, and easy to use. +--- + +# Editing and Formatting Message Contents + Add your message content here using the Shift iQ markdown Content Authoring tool, designed to be fast, light, and easy to use. This tool helps create content that’s less likely to be marked as spam, making it more likely that your messages will reach your email subscribers. The Markdown toolbar buttons can be used to quickly format text, or you can simply add the correct markdown language manually. Here is what the buttons do: -* **B** bolds or *I* italisizes the selected text + +* **B** bolds or *I* italicizes the selected text * **H** makes a line of text into a heading with larger, bolded, font, and space before and after that line; each click of **H** button changes the Heading level, from level 1 (largest font) to level 6 (smallest font) * **"** makes a line of text into a quote * the bullet and numbered list buttons can be used to make a generic or numbered lists @@ -14,4 +19,4 @@ The Markdown toolbar buttons can be used to quickly format text, or you can simp * the **Full Screen** button (arrow box) opens the markdown editor in full screen mode, or returns it to the normal view * the **Markdown Guide** button (question mark) opens a simple markdown guide with additional options -We also recommend [www.markdownguide.org](https://www.markdownguide.org/) for more details, if needed. +We also recommend [www.markdownguide.org](https://www.markdownguide.org/) for more details, if needed. diff --git a/topics/messages/authoring-messages/markdown-reference.md b/topics/messages/authoring-messages/markdown-reference.md index 4f44b34..ece5528 100644 --- a/topics/messages/authoring-messages/markdown-reference.md +++ b/topics/messages/authoring-messages/markdown-reference.md @@ -1,5 +1,9 @@ -# Markdown Reference - +--- +description: "Thanks to The Markdown Guide for providing this list! This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements." +--- + +# Markdown Reference + Thanks to [The Markdown Guide](https://www.markdownguide.org) for providing this list! This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every case, so if you need more information about any of these elements, refer to the reference guides for [basic syntax](https://www.markdownguide.org/basic-syntax/) and [extended syntax](https://www.markdownguide.org/extended-syntax/). ## Basic Syntax @@ -9,7 +13,9 @@ These are the elements outlined in John Gruber’s original design document. All ### Heading # H1 + ## H2 + ### H3 ### Bold @@ -32,9 +38,9 @@ These are the elements outlined in John Gruber’s original design document. All ### Unordered List -- First item -- Second item -- Third item +* First item +* Second item +* Third item ### Code @@ -65,7 +71,7 @@ These elements extend the basic syntax by adding additional features. Not all Ma ### Fenced Code Block -``` +```text { "firstName": "John", "lastName": "Smith", @@ -94,9 +100,9 @@ term ### Task List -- [x] Write the press release -- [ ] Update the website -- [ ] Contact the media +* [x] Write the press release +* [ ] Update the website +* [ ] Contact the media ### Emoji @@ -114,4 +120,4 @@ H~2~O ### Superscript -X^2^ +X^2^ diff --git a/topics/messages/authoring-messages/message-placeholders.md b/topics/messages/authoring-messages/message-placeholders.md index 0ba977e..ae51d78 100644 --- a/topics/messages/authoring-messages/message-placeholders.md +++ b/topics/messages/authoring-messages/message-placeholders.md @@ -1,10 +1,14 @@ +--- +description: When creating the content for an Notification, Newsletter or Invitation, there are Placeholders that can be added in the content. +--- + # Message Placeholders When creating the content for an Notification, Newsletter or Invitation, there are Placeholders that can be added in the content. Please see below a list of the Placeholders available and what information each Placeholder provides: Please note Placeholders should not be used in **Alerts**, please [**contact**](mailto:support@shiftiq.com) your Shift iQ representative to assist with the initial setup. -### NOTIFICATION Placeholders: +### NOTIFICATION Placeholders * $RecipientFirstName - First Name of person receiving Newsletter * $RecipientLastName - Last Name of person receiving Newsletter @@ -24,7 +28,7 @@ Please note Placeholders should not be used in **Alerts**, please [**contact**]( * $UserEmail - Email of person who triggered the Notification * $SurveyFormName - Survey that triggered the Notification -**Message Variables (For Gradebook Worklfow Notifications ONLY):** +**Message Variables (For Gradebook Workflow Notifications ONLY):** * $CourseName * $CourseStarted @@ -36,7 +40,7 @@ Please note Placeholders should not be used in **Alerts**, please [**contact**]( * $AppUrl * $CourseName * $CourseStarted -* $LearnerIdentifie +* $LearnerIdentifier * $LearnerFirstName * $LearnerLastName @@ -45,7 +49,7 @@ Please note Placeholders should not be used in **Alerts**, please [**contact**]( * $AppUrl * $CourseName * $CourseStarted -* $LearnerIdentifie +* $LearnerIdentifier * $LearnerFirstName * $LearnerLastName @@ -62,7 +66,7 @@ Please note Placeholders should not be used in **Alerts**, please [**contact**]( {Sender-Logo} and {Social-Media-Links} - These Placeholders do not work in Survey Workflow Notifications if attached to **Response Started (Administrator)**.
-### NEWSLETTER Placeholders: +### NEWSLETTER Placeholders * $RecipientFirstName - First Name of person receiving Newsletter * $RecipientLastName - Last Name of person receiving Newsletter @@ -71,9 +75,7 @@ Please note Placeholders should not be used in **Alerts**, please [**contact**]( * $Social-Media-Links - Display Organization's social media links (Please [**contact**](mailto:support@shiftiq.com) your Shift iQ representative to assist with the initial setup) ![placeholders.png](https://e02.insite.com/files/sites/global/message-placeholders/placeholders.png) * $Unsubscribe-Link - - -### INVITATION Placeholders: +### INVITATION Placeholders * $RecipientFirstName - First Name of person receiving Newsletter * $RecipientLastName - Last Name of person receiving Newsletter diff --git a/topics/messages/managing-recipients/README.md b/topics/messages/managing-recipients/README.md index c1925a4..09d382e 100644 --- a/topics/messages/managing-recipients/README.md +++ b/topics/messages/managing-recipients/README.md @@ -1,3 +1,14 @@ -# Managing recipients - -(The content is under revision. Check back soon.) +--- +description: >- + Add subscribers, build mailing lists, and handle unsubscribe requests +--- + +# Managing recipients + +Recipients are the people who receive a mailout. This section covers adding subscribers, creating mailing lists, and handling unsubscribe requests. + +## In this section + +* [Add Subscribers/Recipients](add-recipients.md) +* [Create new Mailing List](new-mailing-list.md) +* [Unsubscribe from Messages](unsubscribe.md) diff --git a/topics/messages/managing-recipients/add-recipients.md b/topics/messages/managing-recipients/add-recipients.md index ac10589..fc698a6 100644 --- a/topics/messages/managing-recipients/add-recipients.md +++ b/topics/messages/managing-recipients/add-recipients.md @@ -1,15 +1,19 @@ -# Add Subscribers/Recipients - +--- +description: You can attach multiple mailing lists to one message. +--- + +# Add Subscribers/Recipients + You can attach multiple mailing lists to one message. The group members are copied into the recipient list of the message; If you add/remove individuals from a mailing list they will NOT be added/removed from the message. Click on the **Subscribers/Recipients** tab to add **Subscribers/Recipients** to your message Then click on the **Add Subscriber** button. -You can add **Subscribers** one at a time, or you can add a whole Group. Groups do not have to be a -Mailing List to be added to a Message; Groups of any Type can be added. For example, if you have a pre-defined -list of Companies that you want to send it to, just add it to the message. All contacts on that list will be -included. +You can add **Subscribers** one at a time, or you can add a whole Group. Groups do not have to be a +Mailing List to be added to a Message; Groups of any Type can be added. For example, if you have a pre-defined +list of Companies that you want to send it to, just add it to the message. All contacts on that list will be +included. **Adding a Group:** @@ -21,9 +25,9 @@ included. **Adding Individuals:** * In the **Search** card select **Person** in the **Contact Type** field. -* Search for the individuals you want to add using the **Name** and **Email** fields. -* In the **Code(s)** field, you can search for users using their Person Code. +* Search for the individuals you want to add using the **Name** and **Email** fields. +* In the **Code(s)** field, you can search for users using their Person Code. * After adding the details, click the **Search** button * Select the **People** card, select the individuals you want to add as the **Subscribers/Recipients** and click the **Add** button. -You can re-use newsletters (Messages) over and over by removing the last batch of recipients and adding new ones. +You can re-use newsletters (Messages) over and over by removing the last batch of recipients and adding new ones. diff --git a/topics/messages/managing-recipients/new-mailing-list.md b/topics/messages/managing-recipients/new-mailing-list.md index 5c36ba2..7dcf756 100644 --- a/topics/messages/managing-recipients/new-mailing-list.md +++ b/topics/messages/managing-recipients/new-mailing-list.md @@ -1,20 +1,26 @@ -# Create new Mailing List - +--- +description: "Creating the Mailing List Group:" +--- + +# Create new Mailing List + **Creating the Mailing List Group:** -* From the Admin Home Page select the **Contacts** Toolkit, + +* From the Admin Home Page select the **Contacts** Toolkit, * Select the **Groups** counter in the **Counters** panel * Create a new group by selecting the **Add New Group** link at the top of the Groups page (also see Adding New Groups). * Add your **Group Name** * Select **List** from the **Group Type** drop down. -* Click on the **Save** button +* Click on the **Save** button * Once the group has been created you are able to add people to this group. Under the **People** panel select **Add People** * People can be added one at a time by searching for the people you would like to be included in the mailing list. Alternatively you are able to add conacts in bulk by adding the email addresses of the people who you want to be part of the mailing list. * Confirm all users were added **Adding Mailing List Group as Subscriber:** + * Once the Mailing List has been created, return to the Admin Home Page and select the **Messages** Toolkit. * Select the Newsletter, Invitation or Notification you’d like to edit. * In the **Search** card select **Group** in the **Contact Type** field. * In the **Group Type** field select the type of group being added as the **Subscribers/Recipients** (Department, District, Employer, List, Role, Team, Venue) * Click the **Search** button -* In the **Groups** card, select the groups you want to add as the **Subscribers/Recipients** and click the **Add** button. +* In the **Groups** card, select the groups you want to add as the **Subscribers/Recipients** and click the **Add** button. diff --git a/topics/messages/managing-recipients/unsubscribe.md b/topics/messages/managing-recipients/unsubscribe.md index 922de62..04a1a26 100644 --- a/topics/messages/managing-recipients/unsubscribe.md +++ b/topics/messages/managing-recipients/unsubscribe.md @@ -1,3 +1,15 @@ -# Unsubscribe from Messages - -(The content is under revision. Check back soon.) +--- +description: How recipients unsubscribe and how administrators manage opt-outs +--- + +# Unsubscribe from Messages + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* The unsubscribe link included in outgoing mailouts. +* The recipient-facing unsubscribe flow. +* How administrators review unsubscribed recipients and re-subscribe them when appropriate. + + diff --git a/topics/messages/organizing-messages/README.md b/topics/messages/organizing-messages/README.md index f04ce44..c9d54a0 100644 --- a/topics/messages/organizing-messages/README.md +++ b/topics/messages/organizing-messages/README.md @@ -1,3 +1,11 @@ -# Organizing messages - -(The content is under revision. Check back soon.) +--- +description: Search for and organize existing messages +--- + +# Organizing messages + +As the message library grows, organizing existing messages becomes a routine task. This section covers searching for an existing message. + +## In this section + +* [Search for existing Message](search.md) diff --git a/topics/messages/organizing-messages/search.md b/topics/messages/organizing-messages/search.md index 4b7e2b7..bdad081 100644 --- a/topics/messages/organizing-messages/search.md +++ b/topics/messages/organizing-messages/search.md @@ -1,13 +1,18 @@ -# Search for existing Message - +--- +description: On the Admin Home Page, select the Messages Toolkit. +--- + +# Search for existing Message + On the **Admin Home** Page, select the **Messages** Toolkit. Under the **Messages** heading, select the **Message Type** (**Alert**, **Invitation**, **Newsletter** or **Notification**) you want to search for. You can narrow down your search results by entering as much search criteria you know. Under the **Criteria** tab, you can search for the following fields: + * Message Type (**Alert**, **Invitation**, **Newsletter** or **Notification**) * External Subject -* Interal Name +* Internal Name * Last Modified Date **≥** * Last Modified Date **≤** * Sender Nickname @@ -15,4 +20,4 @@ You can narrow down your search results by entering as much search criteria you * Sender Email * System Mailbox -Click the **Search** button after entering your criteria. Your results will appear in the **Results** tab on the **Search** page. +Click the **Search** button after entering your criteria. Your results will appear in the **Results** tab on the **Search** page. diff --git a/topics/messages/overview.md b/topics/messages/overview.md index 17f6be8..d320186 100644 --- a/topics/messages/overview.md +++ b/topics/messages/overview.md @@ -1,3 +1,9 @@ -# Overview - -Messages is your communications hub; here you can create and edit new messages and see mailout records for items that were already sent. Newsletters are for any correspondence you'd like to schedule and send to any Contacts or Groups in the system. Notifications & Alerts are sent automatically by the system based on some defined event. Invitations are used to invite users to complete a specific survey. +--- +description: >- + Author and schedule newsletters, automated notifications, and survey + invitations from a single communications hub +--- + +# Overview + +Messages is your communications hub; here you can create and edit new messages and see mailout records for items that were already sent. Newsletters are for any correspondence you'd like to schedule and send to any Contacts or Groups in the system. Notifications & Alerts are sent automatically by the system based on some defined event. Invitations are used to invite users to complete a specific survey. diff --git a/topics/messages/sending-mailouts/README.md b/topics/messages/sending-mailouts/README.md index 953ca04..72a0b1c 100644 --- a/topics/messages/sending-mailouts/README.md +++ b/topics/messages/sending-mailouts/README.md @@ -1,3 +1,12 @@ -# Sending mailouts - -(The content is under revision. Check back soon.) +--- +description: Schedule message delivery and review delivery reports +--- + +# Sending mailouts + +A mailout is a scheduled delivery of a message to a list of recipients. This section covers scheduling the delivery and reviewing the report that records what was sent and to whom. + +## In this section + +* [Schedule Delivery](schedule-delivery.md) +* [Delivery Report](delivery-report.md) diff --git a/topics/messages/sending-mailouts/delivery-report.md b/topics/messages/sending-mailouts/delivery-report.md index 2e38007..fadc5ff 100644 --- a/topics/messages/sending-mailouts/delivery-report.md +++ b/topics/messages/sending-mailouts/delivery-report.md @@ -1,24 +1,29 @@ -# Delivery Report - +--- +description: Open the Message Toolkit and select Mailout Counter. +--- + +# Delivery Report + Open the **Message** Toolkit and select **Mailout** Counter. -Search for the **Alert, Invitation or Newsletter** you would like to check delivery status for by setting your search critiera under the **Criteria** tab. +Search for the **Alert, Invitation or Newsletter** you would like to check delivery status for by setting your search criteria under the **Criteria** tab. Under the **Criteria** tab you can specify your search criteria + * Sender * Recipient * Subject * Status (Scheduled, Started, Completed, Cancelled) * Scheduled before/after date and time * Completed before/after date and time -* Message type (Invitation, Newlsetter, Notification) +* Message type (Invitation, Newsletter, Notification) * Devliveries before/after date and time Click the **Search** button. -Under the Results tab you will see the results based on your search critieria. +Under the Results tab you will see the results based on your search criteria. Click on the **Document Icon** (), next to the **Subject**, to open the Delivery Report for that **Mailout**. -Scroll down to the bottom of the page and under the **Successful Deliveries** heading, you will find a list of all the deliveries and status of delivery for each mailout. -If a detailed delivery report for a specific recipeint is required, click on the **Magnifying Icon** () next to the Recipeint's mailout to view the detailed report. +Scroll down to the bottom of the page and under the **Successful Deliveries** heading, you will find a list of all the deliveries and status of delivery for each mailout. +If a detailed delivery report for a specific recipeint is required, click on the **Magnifying Icon** () next to the Recipeint's mailout to view the detailed report. diff --git a/topics/messages/sending-mailouts/schedule-delivery.md b/topics/messages/sending-mailouts/schedule-delivery.md index d36fd17..026e984 100644 --- a/topics/messages/sending-mailouts/schedule-delivery.md +++ b/topics/messages/sending-mailouts/schedule-delivery.md @@ -1,11 +1,15 @@ -# Schedule Delivery - -In the Notification, Newsleter or Invitation, click on the **Message Setup** tabl and click the **Schedule Mailout** to schedule the mailout. +--- +description: In the Notification, Newsletter or Invitation, click on the Message Setup tab and click the Schedule Mailout to schedule the mailout. +--- + +# Schedule Delivery + +In the Notification, Newsletter or Invitation, click on the **Message Setup** tab and click the **Schedule Mailout** to schedule the mailout. Select the **Date and Time** you want your **Invitation/Newsletter/Notification** to be sent out. Click the **Add to Schedule** button. -Pending messages are sent every fifteen minutes, so if you schedule this mailout now then you might still need to wait several minutes before delivery is complete. +Pending messages are sent every fifteen minutes, so if you schedule this mailout now then you might still need to wait several minutes before delivery is complete. -Limit the number of recipients to 10,000. Mailouts larger than this tend to trigger spam filters. To help prevent this, Messages are released from the system in batches to lower the chance of being flagged by a spam filter. Large mailouts may be released over several hours. If you need to send to more than 10,000 recipients, consider sending in multiple batches. +Limit the number of recipients to 10,000. Mailouts larger than this tend to trigger spam filters. To help prevent this, Messages are released from the system in batches to lower the chance of being flagged by a spam filter. Large mailouts may be released over several hours. If you need to send to more than 10,000 recipients, consider sending in multiple batches. diff --git a/topics/records/achievements/README.md b/topics/records/achievements/README.md index 689ebd2..a84f795 100644 --- a/topics/records/achievements/README.md +++ b/topics/records/achievements/README.md @@ -1,3 +1,17 @@ -# Creating and Granting Achievements - -(The content is under revision. Check back soon.) +--- +description: >- + Define achievement templates, grant achievements, and lay out printed + certificates +--- + +# Creating and Granting Achievements + +An achievement records that a learner has met a defined outcome — completion, certification, badge, license, and similar. This section covers defining the template, editing it, granting achievements manually, designing the printed certificate layout, and searching or editing achievements after the fact. + +## In this section + +* [Create New Achievement Template](define-achievement.md) +* [Editing Achievement Templates](edit-achievement-template.md) +* [Manually Granting Achievements](manually-grant-achievement.md) +* [Printed Certificate Layout for Achievements](achievement-layouts.md) +* [Searching and Editing Achievements](search-edit-achievements.md) diff --git a/topics/records/achievements/achievement-layouts.md b/topics/records/achievements/achievement-layouts.md index 45f2b48..b8a40ce 100644 --- a/topics/records/achievements/achievement-layouts.md +++ b/topics/records/achievements/achievement-layouts.md @@ -1,3 +1,7 @@ +--- +description: Printable certificates can be attached to an achievement. +--- + # Achievement Layouts for Printed Certificates Printable certificates can be attached to an achievement. To create a certificate, please contact your account representative or submit a request to support@shiftiq.com. diff --git a/topics/records/achievements/define-achievement.md b/topics/records/achievements/define-achievement.md index 29b0114..9f85f9e 100644 --- a/topics/records/achievements/define-achievement.md +++ b/topics/records/achievements/define-achievement.md @@ -1,8 +1,12 @@ +--- +description: On the Admin Home Page, select Records Toolkit +--- + # Create New Achievement Template -#### There are 2 ways of creating a New Achievement: +#### There are 2 ways of creating a New Achievement -#### Option 1: +#### Option 1 On the **Admin Home Page**, select **Records** Toolkit @@ -16,11 +20,11 @@ Click the **Add New Achievement** link at the top of the page. * Select the **Achievement Expiry** (If achievement expires, select whether this is a fixed date or relative to when issued) * No Expiry * Fixed Date: Add the date the Achievement expires - * Relative Date: Set the duration the Achievment is valid for + * Relative Date: Set the duration the Achievement is valid for * Months * Years
-#### Option 2: +#### Option 2 On the **Admin Home Page**, select **Records** Toolkit diff --git a/topics/records/achievements/edit-achievement-template.md b/topics/records/achievements/edit-achievement-template.md index 7db13ae..3917bd7 100644 --- a/topics/records/achievements/edit-achievement-template.md +++ b/topics/records/achievements/edit-achievement-template.md @@ -1,5 +1,9 @@ -# Editing Achievement Templates - +--- +description: On the Admin Home Page, select Records Toolkit +--- + +# Editing Achievement Templates + On the **Admin Home Page**, select **Records** Toolkit Under the **Achievements** heading, click on the **Achievement Template** counter. @@ -8,17 +12,19 @@ Search for the **Achievement** you need to edit, and click on the edit pencil or Scroll down past any learners who have been granted the achievement to the **Achievement Setup** card; here you can edit the following fields: -**Achievement Expiration** - set or remove a fixed or relative Expirey date, and bulk update any existing learner achievements if required +**Achievement Expiration** - set or remove a fixed or relative Expiry date, and bulk update any existing learner achievements if required **Achievement Description** + * Title (**Note** this will change the title for any learners who have already achieved it; create a new achievement if this isn't desired) * Tag * Certificate Layout (select a Credential Layout if you want the learner to have a downloadable certificate for this Achievement) * Description * Webhook * Reporting Status - should this Achievement appear on a learner's Training Records -* Achievement Type - can be configured to allow groupings on a learner's Training Records* +* Achievement Type - can be configured to allow groupings on a learner's Training Records* **Registration Settings** - used if this Achievement is connected to classes + * Tradeworker Number Required - is the Person/Learner Code optional or required, when completing a registration -* Are Multiple Registration Allowed - can an Employer or Referrer register multiple learners in a class at once +* Are Multiple Registration Allowed - can an Employer or Referrer register multiple learners in a class at once diff --git a/topics/records/achievements/manually-grant-achievement.md b/topics/records/achievements/manually-grant-achievement.md index d0148b8..1058c5b 100644 --- a/topics/records/achievements/manually-grant-achievement.md +++ b/topics/records/achievements/manually-grant-achievement.md @@ -1,10 +1,14 @@ -# Manually Granting Achievements - +--- +description: In most cases, Achievements will be automatically granted to a learner based on a Course or Gradebook result. +--- + +# Manually Granting Achievements + In most cases, Achievements will be automatically granted to a learner based on a Course or Gradebook result. However, there may be times when it is necessary to manually grant an Achievement to an individual learner. Here is how you do so: -1. Select **Records** Toolkit, **Achievement Template** counter. -1. Search for and open the **Achievement** you want to grant to a learner by clicking on the Title or edit pencil on the **Achievement Search** page. +1. Select **Records** Toolkit, **Achievement Template** counter. +1. Search for and open the **Achievement** you want to grant to a learner by clicking on the Title or edit pencil on the **Achievement Search** page. 1. On the **Achievements** tab, click the **Grant Certificate** button. 1. Search for the learner by **Name** or **Email**, and click **Search**. 1. Select the checkbox next to the learner's name and click the **Next** button. -1. Select the Assigned date for the Achievement and under the Status heading select **Assigned and Granted**. Select the **date and time** the Achievement was granted and click **Save**. +1. Select the Assigned date for the Achievement and under the Status heading select **Assigned and Granted**. Select the **date and time** the Achievement was granted and click **Save**. diff --git a/topics/records/achievements/search-edit-achievements.md b/topics/records/achievements/search-edit-achievements.md index b1993fb..356e656 100644 --- a/topics/records/achievements/search-edit-achievements.md +++ b/topics/records/achievements/search-edit-achievements.md @@ -1,17 +1,24 @@ -# Searching and Editing Achievements - +--- +description: search options, including criteria and download +--- + +# Searching and Editing Achievements + search options, including criteria and download -* by achievement title, status and/or tag, learner name, learner employer (and employer group status and region) and dates acheivement was granted, revoked or expired + +* by achievement title, status and/or tag, learner name, learner employer (and employer group status and region) and dates achievement was granted, revoked or expired * credentials.xls report - maybe need to get query language for this from Aleksey and move this to RCABC's queries, not sure it makes sense for other customers not using trades and employers outline: -* shows information about the achievement template configuration, and about the user who was granted the acheivmement [should we get rid of the CMDS refs outside of partition 3?] + +* shows information about the achievement template configuration, and about the user who was granted the achievement [should we get rid of the CMDS refs outside of partition 3?] * authority [what is this, or what is the plan for this, is it to do with blockchain maybe?] * shows information about the credential, when it was granted, expired, etc. edit options: + * configure - set or edit a fixed or relative expiry date, add a necessity and a priority (contact support to configure a collection to use either of these fields) [who uses these and what for?] * grant - change the granted date * revoke - revoke the credential and give a reason for the revocation [who uses this and what for?] -delete the achievement - if it was granted in error +delete the achievement - if it was granted in error diff --git a/topics/records/blockchain/README.md b/topics/records/blockchain/README.md index 56bcb04..f47c300 100644 --- a/topics/records/blockchain/README.md +++ b/topics/records/blockchain/README.md @@ -1,3 +1,7 @@ +--- +description: Blockchain is a system of recording information in a way that makes it difficult or impossible to change, hack, or cheat the system. +--- + # Blockchain Certificate Management Blockchain is a system of recording information in a way that makes it difficult or impossible to change, hack, or cheat the system. A blockchain is essentially a digital ledger of transactions that is duplicated and distributed across the entire network of computer systems on the blockchain. All of these qualities make blockchain the best candidate for safe and permanent record keeping. Additionally, cryptographic concepts that form the underlying structure of Blockchain, such as digital signatures, can be utilized for other means as well. diff --git a/topics/records/blockchain/blockchain-wallet.md b/topics/records/blockchain/blockchain-wallet.md index 286fd1c..d5b1f84 100644 --- a/topics/records/blockchain/blockchain-wallet.md +++ b/topics/records/blockchain/blockchain-wallet.md @@ -1,24 +1,30 @@ -# Creating and Connecting a Blockchain Wallet to Shift iQ - -In order to jump in with Blockchain technology, learners need to have a wallet. A wallet is normally used to keep and manage digital assets such as cryptocurrencies. Wallets can also be used to communicate with blockchain and smart contracts. +--- +description: In order to jump in with Blockchain technology, learners need to have a wallet. +--- + +# Creating and Connecting a Blockchain Wallet to Shift iQ + +In order to jump in with Blockchain technology, learners need to have a wallet. A wallet is normally used to keep and manage digital assets such as cryptocurrencies. Wallets can also be used to communicate with blockchain and smart contracts. Shift iQ's certificate manager has been built on top of the Ethereum network, so learners need an Ethereum wallet. One such wallet is MetaMask, the rest of this help topic is based on this wallet. However, you can choose any wallet of your choosing as long as it has web3 capabilities. ## Creating a MetaMask Wallet + MetaMask wallet is a browser extension that can be downloaded from web stores such as chrome web store based on your browser. Below you can find steps for installing this extension on Chrome. -1. Install the extension from chrome web store. +1. Install the extension from chrome web store. ![Install Chrome Extension](https://e02.insite.com/files/web/da564272-ddb7-4637-a45a-afbd010b1f95/blockchain.png) -2. Once installed press Getd button in MetaMask window, then hit I Agree, and then Create Wallet and buttons and finally set a password for your wallet. +2. Once installed press Get button in MetaMask window, then hit I Agree, and then Create Wallet and buttons and finally set a password for your wallet. ![Create Wallet](https://e02.insite.com/files/web/da564272-ddb7-4637-a45a-afbd010b1f95/blockchain-1.png) -3. After the installation phase you will be presented with 12 words that are used for driving your private key, make sure to write them on a secure piece of paper, as these words are the key to your funds on blockchain. +3. After the installation phase you will be presented with 12 words that are used for driving your private key, make sure to write them on a secure piece of paper, as these words are the key to your funds on blockchain. ![Key Words](https://e02.insite.com/files/web/da564272-ddb7-4637-a45a-afbd010b1f95/blockchain-2.png) -4. Click next and then in the next window use your physical backup to re enter the same words in the same order for the final step. +4. Click next and then in the next window use your physical backup to re enter the same words in the same order for the final step. 5. After this step, you can see your balance, and connect to your Meta mask wallet by hitting MetaMask icon on the top right corner of your browser, right across the search bar in the extensions section. ![Connect](https://e02.insite.com/files/web/da564272-ddb7-4637-a45a-afbd010b1f95/blockchain-3.png) ## Connecting your wallet to Shift iQ -Once you have MetaMask up and running you can redirect to your profile page at ShiftIQ to connect it to your wallet. In order to do this, just hit Connect your wallet on the first column of the profile page. You will then need to log in to your MetaMask wallet and connect it to Shift iQ. + +Once you have MetaMask up and running you can redirect to your profile page at ShiftIQ to connect it to your wallet. In order to do this, just hit Connect your wallet on the first column of the profile page. You will then need to log in to your MetaMask wallet and connect it to Shift iQ. ![Log In](https://e02.insite.com/files/web/56ef106d-298a-4625-8d9a-afbd010c5e59/blockchain-4.png) Once connected you will be presented with a one-time nonce to sign, and by signing this nonce using your wallet's private key you can prove your identity to Shift iQ. After this process, your signature alongside your public key will be stored in the Shift iQ database and can be used to establish your identity for future use. @@ -28,4 +34,4 @@ When a learner is viewing their Achievement, if they have a wallet connected to Administrators of an organization are provided with batch publish functionalities that can be accessed from their administrative panel. This functionality can be found under records > Learner Achievements page and in the last column of the results table. -Published certificates can be verified from Shift iQ certificate verification page, you only need to enter your certificate identifier and hit verify to receive the verification message. Using this page, anyone can verify any Shift iQ certificate and observe some complementary data regarding the certificate. You can also access this menu by hitting verify button in the My Achievements of your dashboard. +Published certificates can be verified from Shift iQ certificate verification page, you only need to enter your certificate identifier and hit verify to receive the verification message. Using this page, anyone can verify any Shift iQ certificate and observe some complementary data regarding the certificate. You can also access this menu by hitting verify button in the My Achievements of your dashboard. diff --git a/topics/records/blockchain/certificate-manager.md b/topics/records/blockchain/certificate-manager.md index 54f1e22..d9d2f16 100644 --- a/topics/records/blockchain/certificate-manager.md +++ b/topics/records/blockchain/certificate-manager.md @@ -1,3 +1,7 @@ +--- +description: Certificate data is of high importance and is intended to be long-lived. +--- + # Overview of Shift iQ's Blockchain Based Certificate Manager Certificate data is of high importance and is intended to be long-lived. By using blockchain, the security of the produced certificates is guaranteed and certificates will live on the blockchain as long as blockchain exists. What's more, the process of certificate management becomes decentralized, trustless, secure, and immutable. diff --git a/topics/records/blockchain/login-with-blockchain.md b/topics/records/blockchain/login-with-blockchain.md index 08cbfdc..fac6e08 100644 --- a/topics/records/blockchain/login-with-blockchain.md +++ b/topics/records/blockchain/login-with-blockchain.md @@ -1,3 +1,7 @@ +--- +description: Another interesting integration of Shift iQ with Blockchain technology can be found on the login page, this functionality provides our users with +--- + # Login With Blockchain Another interesting integration of Shift iQ with Blockchain technology can be found on the login page, this functionality provides our users with the benefit of logging in to their accounts using a digital signature associated with their Ethereum wallet. In order to use this functionality, users need to connect their Ethereum wallet with Shift iQ through the [steps mentioned](https://e02.insite.com/portals/portal/records/blockchain/blockchain-wallet). Users can then use the **Login with MetaMask** button on the login page when logging in to Shift iQ; they just need to sign a nonce every time to prove their identity. No password or username is required. diff --git a/topics/records/gradebooks/README.md b/topics/records/gradebooks/README.md index c1da74c..cd89dcd 100644 --- a/topics/records/gradebooks/README.md +++ b/topics/records/gradebooks/README.md @@ -1,3 +1,20 @@ -# Creating and Configuring Gradebooks - -(The content is under revision. Check back soon.) +--- +description: >- + Create gradebooks, add grade items, manage learners, and view learner + progress +--- + +# Creating and Configuring Gradebooks + +A gradebook records grade items for a class or program and tracks each learner's progress against them. This section covers creating a gradebook, editing its settings, adding grade items, managing learners, recording scores and achievements, and the instructor's view of all of it. + +## In this section + +* [Creating a New Gradebook](new-gradebook.md) +* [Editing Gradebook Settings](gradebook-settings.md) +* [Adding and Configuring Grade Items](grade-items.md) +* [Managing Learners in a Gradebook](learners-gradebook.md) +* [Learner Progress and Scores](gradebook-scores.md) +* [Gradebook Achievements](gradebook-achievements.md) +* [Gradebook Comments and Periods](gradebook-comments-periods.md) +* [Instructor Gradebook Views](instructor-gradebook.md) diff --git a/topics/records/gradebooks/grade-items.md b/topics/records/gradebooks/grade-items.md index b7c7f99..97979f4 100644 --- a/topics/records/gradebooks/grade-items.md +++ b/topics/records/gradebooks/grade-items.md @@ -1,3 +1,7 @@ +--- +description: split into separate pages if gets too bulky, i.e., Category Grade Items, Score Grade Items, Calculation Grade Items, or split out adding and editing +--- + # Adding and Configuring Grade Items split into separate pages if gets too bulky, i.e., Category Grade Items, Score Grade Items, Calculation Grade Items, or split out adding and editing and grade items with achievements. diff --git a/topics/records/gradebooks/gradebook-achievements.md b/topics/records/gradebooks/gradebook-achievements.md index d12681e..d328e82 100644 --- a/topics/records/gradebooks/gradebook-achievements.md +++ b/topics/records/gradebooks/gradebook-achievements.md @@ -1,3 +1,7 @@ +--- +description: Achievement Tab navigation (gradebook only vs all learner achievements) +--- + # Gradebook Achievements Achievement Tab navigation (gradebook only vs all learner achievements) diff --git a/topics/records/gradebooks/gradebook-comments-periods.md b/topics/records/gradebooks/gradebook-comments-periods.md index baf4f56..dc8099b 100644 --- a/topics/records/gradebooks/gradebook-comments-periods.md +++ b/topics/records/gradebooks/gradebook-comments-periods.md @@ -1,3 +1,7 @@ +--- +description: Hide/Unhide Comments and Periods +--- + # Gradebook Comments and Periods Hide/Unhide Comments and Periods diff --git a/topics/records/gradebooks/gradebook-scores.md b/topics/records/gradebooks/gradebook-scores.md index 785f0ce..6bad794 100644 --- a/topics/records/gradebooks/gradebook-scores.md +++ b/topics/records/gradebooks/gradebook-scores.md @@ -1,3 +1,7 @@ +--- +description: Navigating the Grade Item Hierarchy +--- + # Learner Progress and Scores Navigating the Grade Item Hierarchy diff --git a/topics/records/gradebooks/gradebook-settings.md b/topics/records/gradebooks/gradebook-settings.md index ae2af0d..89cd9b8 100644 --- a/topics/records/gradebooks/gradebook-settings.md +++ b/topics/records/gradebooks/gradebook-settings.md @@ -1,3 +1,15 @@ -# Editing Gradebook Settings - -(The content is under revision. Check back soon.) +--- +description: Edit the settings that control how a gradebook behaves +--- + +# Editing Gradebook Settings + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* Where to open the gradebook settings. +* Each setting on the tab and its effect. +* When to use periods, weighted grade items, and pass marks. + + diff --git a/topics/records/gradebooks/instructor-gradebook.md b/topics/records/gradebooks/instructor-gradebook.md index ce302f2..22edb11 100644 --- a/topics/records/gradebooks/instructor-gradebook.md +++ b/topics/records/gradebooks/instructor-gradebook.md @@ -1,3 +1,7 @@ +--- +description: configuration requirements (create a role for Instructors and ask Support to add the appropriate permissions) +--- + # Instructor Gradebook Views configuration requirements (create a role for Instructors and ask Support to add the appropriate permissions) diff --git a/topics/records/gradebooks/learners-gradebook.md b/topics/records/gradebooks/learners-gradebook.md index 4b22db5..e049369 100644 --- a/topics/records/gradebooks/learners-gradebook.md +++ b/topics/records/gradebooks/learners-gradebook.md @@ -1,3 +1,7 @@ +--- +description: how learners are added automatically +--- + # Managing Learners in a Gradebook how learners are added automatically diff --git a/topics/records/gradebooks/new-gradebook.md b/topics/records/gradebooks/new-gradebook.md index f6959a3..b0ff068 100644 --- a/topics/records/gradebooks/new-gradebook.md +++ b/topics/records/gradebooks/new-gradebook.md @@ -1,3 +1,7 @@ +--- +description: "How to create a Gradebook:" +--- + # Creating a New Gradebook **How to create a Gradebook:** @@ -7,8 +11,6 @@ 3. Enter the **Gradebook Title** and select the associated **Achievement**. 4. Select the **Grade Items** tab and add the Grade Items required for the Gradebook. - - **How to create a Gradebook from an Assessment Form:** 1. On the **Admin Home** page, click **Assessments Toolkit**, then select the **Banks** tile @@ -21,8 +23,6 @@ 6. Select **Create Gradebook**, then click **Save**. 7. The system automatically creates the Gradebook and corresponding Grade Items. Each question in the Form becomes a Grade Item, allowing you to view a learner’s score for each question directly in the Gradebook. - - **How to create a Gradebook from a Course:** 1. On the **Admin Home** page, select the **Course Toolkit**, then click the **Course** tile. @@ -42,8 +42,6 @@ 4. Points 5. Score % - - **How to create a Gradebook from a Class:** 1. On the **Admin Home** page, select the **Events Toolkit**, then click the **Classes** tile. @@ -54,12 +52,3 @@ 6. Click **Save**. 7. Under the **Gradebooks** tab, click the **Gradebook Title** to open it. 8. Select the **Grade Items** tab and add the Grade Items required for the Class. - - - - - - - - - diff --git a/topics/records/logbooks/README.md b/topics/records/logbooks/README.md index df3d054..d314492 100644 --- a/topics/records/logbooks/README.md +++ b/topics/records/logbooks/README.md @@ -1,3 +1,16 @@ -# Working with Logbooks - -(The content is under revision. Check back soon.) +--- +description: >- + Create logbooks, manage their settings and content, and validate learner + entries +--- + +# Working with Logbooks + +A logbook is a structured record where learners capture entries against a defined set of activities or competencies. This section covers creating new logbooks, managing their settings and content, how learners enter and edit entries, and how validators review them. + +## In this section + +* [Creating New Logbooks](create-logbooks.md) +* [Managing Logbook Settings and Content](edit-logbooks.md) +* [How Learners Create and Edit Logbook Entries](logbook-entry.md) +* [Validating Logbook Entries](logbook-validation.md) diff --git a/topics/records/logbooks/create-logbooks.md b/topics/records/logbooks/create-logbooks.md index e90a72b..c2dcf8b 100644 --- a/topics/records/logbooks/create-logbooks.md +++ b/topics/records/logbooks/create-logbooks.md @@ -1,3 +1,16 @@ -# Creating New Logbooks - -(The content is under revision. Check back soon.) +--- +description: Create a new logbook and configure its activities or competencies +--- + +# Creating New Logbooks + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* Where to start a new logbook. +* Required fields and their meanings. +* Connecting the logbook to a standards framework or activity list. +* Publishing the logbook so learners can begin recording entries. + + diff --git a/topics/records/logbooks/logbook-entry.md b/topics/records/logbooks/logbook-entry.md index 186043d..23a66e6 100644 --- a/topics/records/logbooks/logbook-entry.md +++ b/topics/records/logbooks/logbook-entry.md @@ -1,3 +1,7 @@ +--- +description: adding portal tile and/or dashboard and/or program so learner can find their logbooks +--- + # How Learners Create and Edit Logbook Entries adding portal tile and/or dashboard and/or program so learner can find their logbooks diff --git a/topics/records/logbooks/logbook-validation.md b/topics/records/logbooks/logbook-validation.md index 52066df..3907394 100644 --- a/topics/records/logbooks/logbook-validation.md +++ b/topics/records/logbooks/logbook-validation.md @@ -1,3 +1,7 @@ +--- +description: assigning validators +--- + # Validating Logbook Entries assigning validators diff --git a/topics/records/overview.md b/topics/records/overview.md index 168a93d..71d00d1 100644 --- a/topics/records/overview.md +++ b/topics/records/overview.md @@ -1,3 +1,9 @@ -# Overview - -Use records to log and track learner scores, outcomes, & achievements. Gradebooks can be hooked to a registered event like a class or exam, as well as to any number of course lessons, assessments or surveys. Achievements can be granted manually or automatically upon completion of specific prerequisites. Logbooks allow learners and their instructors to record and validate practical learning such as on-site experience. +--- +description: >- + Track learner scores, outcomes, and achievements through gradebooks, + achievement templates, programs, and logbooks +--- + +# Overview + +Use records to log and track learner scores, outcomes, & achievements. Gradebooks can be hooked to a registered event like a class or exam, as well as to any number of course lessons, assessments or surveys. Achievements can be granted manually or automatically upon completion of specific prerequisites. Logbooks allow learners and their instructors to record and validate practical learning such as on-site experience. diff --git a/topics/records/programs-and-periods/README.md b/topics/records/programs-and-periods/README.md index 9004e6f..35c29b3 100644 --- a/topics/records/programs-and-periods/README.md +++ b/topics/records/programs-and-periods/README.md @@ -114,7 +114,7 @@ After the Program is created, you need to **Publish** the Program to the **Porta * Click on the **magnifying glass (🔍) icon** next to the Upload New Program Image field * Select the image you want to use for the portal tile -
+
{34096A6A CC7C 497D B3A8 2974D27D600D}
### Publishing the program to the learning portal diff --git a/topics/records/programs-and-periods/create-program.md b/topics/records/programs-and-periods/create-program.md index 653af94..c04e5cc 100644 --- a/topics/records/programs-and-periods/create-program.md +++ b/topics/records/programs-and-periods/create-program.md @@ -1,3 +1,7 @@ +--- +description: Open the Records toolkit and then click on the Programs tile under the Programs and Periods heading. +--- + # Purpose of Programs and How to Create Them ### Creating a New Program @@ -22,13 +26,13 @@ On the **Program Outline** page, add the **Achievement** for the program by sele ### Add Tasks to the Progam -On the **Program Outline** page, in the **Tasks** card, administrators can add the different tasks that will form part of the Program by clicking on the **Edit Tasks** button. The administrator can add each task by selecting the chechbox next to the task. +On the **Program Outline** page, in the **Tasks** card, administrators can add the different tasks that will form part of the Program by clicking on the **Edit Tasks** button. The administrator can add each task by selecting the checkbox next to the task. Tasks that can be added to a Program: * **Assessments** * Only **Published Assessment Forms** in **Assessment Banks** can be selected. - * When selecting the checkbox next to the **Assessment Bank**, a list of all the **Published Assessment Forms** in that bank will be availble for selection by an administrator. Select the checkbox next to each **Assessment Form** that needs to be included in the Program. + * When selecting the checkbox next to the **Assessment Bank**, a list of all the **Published Assessment Forms** in that bank will be available for selection by an administrator. Select the checkbox next to each **Assessment Form** that needs to be included in the Program. * Multiple Assessment Forms can be added to one Program. * **Standalone Achievements** - _Please Note: Adding a Standalone Achievement will not include its related activity._ * If the Achievement you want to add to the Program is not listed, the achievement still need to be created. (See [**Create new Achievement**](../../../ui/help/portal/records/achievements/define-achievement/)) @@ -51,7 +55,7 @@ Learners need to be enrolled in a Program before they will be able to see any of * Search for the **Learner** or **Group** that you want to enroll in the Program. * Once selected, click on the **Add** button. -The **Learner** or **Group** that was seleced will be enrolled into the Program and can access the Program on the Portal.
+The **Learner** or **Group** that was selected will be enrolled into the Program and can access the Program on the Portal.
### Program Achievement @@ -76,7 +80,7 @@ Under the **Achievements** tab, administrators will be able to see all learners Administrators can setup **Progress Stalled** and **Progress Completed** notifications. -* **Progress Stalled** Stalled notifications can be setup to send reminders to a **Learners** and **Administrators** to compelete the Program they started. The following notifications can be created: +* **Progress Stalled** Stalled notifications can be setup to send reminders to a **Learners** and **Administrators** to complete the Program they started. The following notifications can be created: * **Send to Learner:** The stalled notification is sent to the **Learner** once they started the Program, but no progress has been made after a set amount of days. * **Send to Administrator:** The stalled notification is sent to an **Administrator** to advise that a learner started the Program, but no progress has been recorded after a set amount of days. * **Days Without Task Completion:** This is the number of days a learner can go without completing a task before the program is considered stalled. @@ -84,6 +88,6 @@ Administrators can setup **Progress Stalled** and **Progress Completed** notific * **Progress Completed** Once a learner has completed a Program, notifications can be sent to the **Learner** and **Administrator** to advise that they have completed the Program. The following notifications can be created: * **Send to Learner:** Add the notification you want to send to the **Learner** once they have completed the Program. * **Send to Administrator:** Add a notification if you want to let an **Administrator** know when a **Learner** has completed the Program. - * **Send On Completion of this Task:** An administrator can select the task in the Progam that is considered the last task that needs to be complted to consider the Program as Done. + * **Send On Completion of this Task:** An administrator can select the task in the Progam that is considered the last task that needs to be completed to consider the Program as Done. Once the notifications has been added, click the **Save** button. diff --git a/topics/records/programs-and-periods/edit-program.md b/topics/records/programs-and-periods/edit-program.md index f927a03..34ee16b 100644 --- a/topics/records/programs-and-periods/edit-program.md +++ b/topics/records/programs-and-periods/edit-program.md @@ -1,3 +1,17 @@ -# Editing and Managing Programs - -split into additional pages if gets too bulky +--- +description: Edit an existing program and manage learners enrolled in it +--- + +# Editing and Managing Programs + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* Where to open an existing program. +* Changes that are safe to make after learners are enrolled. +* Managing the roster of enrolled learners. + +> Note for the author: split into additional pages if this page grows too large. + + diff --git a/topics/records/programs-and-periods/gradebook-periods.md b/topics/records/programs-and-periods/gradebook-periods.md index ec6066e..dca7e9a 100644 --- a/topics/records/programs-and-periods/gradebook-periods.md +++ b/topics/records/programs-and-periods/gradebook-periods.md @@ -1,3 +1,15 @@ -# Creating and Managing Gradebook Periods - -(The content is under revision. Check back soon.) +--- +description: Create and manage gradebook periods within a program +--- + +# Creating and Managing Gradebook Periods + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* What a gradebook period is and when to use one. +* Creating a new period on a gradebook. +* Editing and closing existing periods. + + diff --git a/topics/sales.md b/topics/sales.md index 359cec2..e4d6595 100644 --- a/topics/sales.md +++ b/topics/sales.md @@ -1,3 +1,11 @@ -# Sales - -Generate invoices from class or event registrations, product sales or application fees. Collect online payments via a link to a payment processing service such as Bambora. +--- +description: >- + Generate invoices from class or event registrations, product sales, or + application fees and collect online payments +--- + +# Sales + +The Billing toolkit (customer-facing name: **Sales**) generates invoices and collects online payments. Use it to invoice for class or event registrations, product sales, and application fees, and to take payment through a processing service such as Bambora. + +> More Billing pages are coming. For now, this overview is the only customer-facing page in the section. diff --git a/topics/sandbox.md b/topics/sandbox.md index 98a1a28..c817164 100644 --- a/topics/sandbox.md +++ b/topics/sandbox.md @@ -19,4 +19,4 @@ To access your sandbox environment, follow these steps: For example: -
+
Signin environments
diff --git a/topics/sites/edit-site-contents/README.md b/topics/sites/edit-site-contents/README.md index 2510fee..48a0512 100644 --- a/topics/sites/edit-site-contents/README.md +++ b/topics/sites/edit-site-contents/README.md @@ -1,3 +1,22 @@ -# Managing Website and Portal Contents - -(The content is under revision. Check back soon.) +--- +description: >- + Add and edit content blocks, images, links, videos, and documents on website + and portal pages +--- + +# Managing Website and Portal Contents + +Once a site or portal exists, its pages need ongoing content updates: text, images, links, videos, documents, and URL changes. This section covers each of those edits and the previews you can use to check them before publishing. + +## In this section + +* [Adding and Editing Site and Block Content](content-editing.md) +* [Adding Images](adding-images.md) +* [Adding a Hyperlink to Images](adding-url-to-images.md) +* [Adding Links](adding-links.md) +* [Upload Document](upload-document.md) +* [Delete Site Page](delete-site-page.md) +* [Preview Contents](preview-contents.md) +* [Adding an Embedded Video](adding-video.md) +* [Customized Help Requests](portal-support-customize.md) +* [Changing URLs and Page Slugs](change-url.md) diff --git a/topics/sites/edit-site-contents/adding-images.md b/topics/sites/edit-site-contents/adding-images.md index 36ac81f..bbc09d2 100644 --- a/topics/sites/edit-site-contents/adding-images.md +++ b/topics/sites/edit-site-contents/adding-images.md @@ -1,3 +1,7 @@ +--- +description: You are able to drag and drop a picture from file into the body of the content.\ +--- + # Adding Images You are able to drag and drop a picture from file into the body of the content.\ @@ -11,7 +15,7 @@ e.g. !\[agriculture-1.jpg]\(https://organization.insite.com/files/sites/global/a On your portal or web site you will be able to see the picture you uploaded. -![](https://e02.insite.com/files/sites/global/adding-images-or-videos/agriculture-1.jpg)
+![Agriculture 1](https://e02.insite.com/files/sites/global/adding-images-or-videos/agriculture-1.jpg)

diff --git a/topics/sites/edit-site-contents/adding-links.md b/topics/sites/edit-site-contents/adding-links.md index 2b1ed35..8ec4076 100644 --- a/topics/sites/edit-site-contents/adding-links.md +++ b/topics/sites/edit-site-contents/adding-links.md @@ -1,3 +1,7 @@ +--- +description: You are able to add web links or email addresses in the text of your content. +--- + # Adding Links You are able to add web links or email addresses in the text of your content. @@ -6,7 +10,7 @@ When you click the **Create Link** button, the system will insert the outline ne You are able to configure the link with an email address instead. You can either add a email address between the square brackets or text. Instead of adding a website, you remove the http:// and add [mailto:add email address.](mailto:support@shiftiq.com.) The full link will be [Click Here to Email](mailto:support@shiftiq.com) or [support@shiftiq.com](mailto:support@shiftiq.com). The text will display as [Click Here to Email](mailto:support@shiftiq.com) or [support@shiftiq.com](mailto:support@shiftiq.com) -#### Open Link in New Browser Window: +#### Open Link in New Browser Window If you require the link you are inserting to open on in a new browser window, you can us the following link:\ \text to display\ diff --git a/topics/sites/edit-site-contents/adding-url-to-images.md b/topics/sites/edit-site-contents/adding-url-to-images.md index fab8ad8..8144b84 100644 --- a/topics/sites/edit-site-contents/adding-url-to-images.md +++ b/topics/sites/edit-site-contents/adding-url-to-images.md @@ -1,3 +1,7 @@ +--- +description: In Markdown hyperlinks can be added to an image you added to the page content. . +--- + # Adding a Hyperlink to Images In Markdown hyperlinks can be added to an image you added to the page content. . diff --git a/topics/sites/edit-site-contents/adding-video.md b/topics/sites/edit-site-contents/adding-video.md index 0eb969f..1dd6de5 100644 --- a/topics/sites/edit-site-contents/adding-video.md +++ b/topics/sites/edit-site-contents/adding-video.md @@ -1,3 +1,7 @@ +--- +description: To embed a video on the portal, you will need to upload the video to either Vimeo or You Tube. +--- + # Adding an Embedded Video To embed a video on the portal, you will need to upload the video to either **Vimeo** or **You Tube**. diff --git a/topics/sites/edit-site-contents/change-url.md b/topics/sites/edit-site-contents/change-url.md index 5b23f5b..80ccd70 100644 --- a/topics/sites/edit-site-contents/change-url.md +++ b/topics/sites/edit-site-contents/change-url.md @@ -1,14 +1,18 @@ -# Changing URLs and Page Slugs - +--- +description: If you’d like to adjust a URL Segment, you can do so under the Page Setup tab. +--- + +# Changing URLs and Page Slugs + **Be careful when editing existing URLs: if you have linked or referenced the URL somewhere else and edit it, the link will no longer work.** However, sometimes the automatically generated segment when creating content is longer than it needs to be as it is built from the Title you give the page. -If you’d like to adjust a **URL Segment**, you can do so under the **Page Setup** tab. Under the **Details** tab within the **Page Setup** tab, click on the Pencil Icon next to the **Page Slug (URL Segment)** field, under the **Navigation** heading. +If you’d like to adjust a **URL Segment**, you can do so under the **Page Setup** tab. Under the **Details** tab within the **Page Setup** tab, click on the Pencil Icon next to the **Page Slug (URL Segment)** field, under the **Navigation** heading. -On the Update **Navigation** card, in the **Page Slug (URL Segment**) field update/change the URL. +On the Update **Navigation** card, in the **Page Slug (URL Segment**) field update/change the URL. Click the **Save** button to save your changes. -*Please note that when you update a Folder/Page **URL Segment**, each Folder/Page needs to have its own unique **URL Segement**. Folders/Pages **cannot** share the same **URL Segement**.* +*Please note that when you update a Folder/Page **URL Segment**, each Folder/Page needs to have its own unique **URL Segment**. Folders/Pages **cannot** share the same **URL Segment**.* **Example:** Changing URL Segment from **changing-webpage-url-segment** to **change-url** -This will change the webpage URL from **www.example.ca/changing-webpage-url-segment** to **www.example.ca/change-url** +This will change the webpage URL from **www.example.ca/changing-webpage-url-segment** to **www.example.ca/change-url** diff --git a/topics/sites/edit-site-contents/content-editing.md b/topics/sites/edit-site-contents/content-editing.md index 61a00f4..e2682bb 100644 --- a/topics/sites/edit-site-contents/content-editing.md +++ b/topics/sites/edit-site-contents/content-editing.md @@ -1,3 +1,7 @@ +--- +description: Add your site page or block content here using the Markdown or HTML editors. Markdown is a simple way to format text that looks great on any device. +--- + # Adding and Editing Site and Block Content Add your site page or block content here using the Markdown or HTML editors. Markdown is a simple way to format text that looks great on any device. We recommend caution when using HTML, as there can be hidden formatting code that may not translate as expected on different computer platforms, screen sizes, or software versions. @@ -12,7 +16,7 @@ When you select Create Link, the system will create the outline needed for the l You are able to configure the link with an email address instead. You can either add a email address between the square brackets or text. Instead of adding a website, you remove the http:// and add [mailto:add email address.](mailto:support@shiftiq.com.) The full link will be \[Click Here to Email]\(mailto:support@shiftiq.com) or \[support@shiftiq.com]\(mailto:support@shiftiq.com). The text will display as [Click Here to Email](mailto:support@shiftiq.com) or [support@shiftiq.com](mailto:support@shiftiq.com) -#### Open Link in New Browser Window: +#### Open Link in New Browser Window If you require the link you are inserting to open on in a new browser window, you can us the following link:\ \text to display\ diff --git a/topics/sites/edit-site-contents/delete-site-page.md b/topics/sites/edit-site-contents/delete-site-page.md index b2e2e18..7f8afc1 100644 --- a/topics/sites/edit-site-contents/delete-site-page.md +++ b/topics/sites/edit-site-contents/delete-site-page.md @@ -1,6 +1,10 @@ +--- +description: Select the Page or Folder you want to Delete. +--- + # Delete Site Page -### Please note: Deleting a Folder, Page or Block is a permanent change that cannot be undone. The web page and any Contained Pages will be deleted from all forms, queries, and reports. +### Please note: Deleting a Folder, Page or Block is a permanent change that cannot be undone. The web page and any Contained Pages will be deleted from all forms, queries, and reports
@@ -10,7 +14,7 @@ Select the **Page** or **Folder** you want to **Delete**. On the **Page Setup** tab, click the **Delete** button. You will be redirected the the **Delete** confirmation page. You need to confirm that you want to delete the **Page** or **Folder** selected. The delete screen will show the impact deleting the **Page** or **Folder** you selected will have. How many Web Pages and Contained Pages (if deleting a folder) you will be deleting. -Select the "**Delete this page and all its contents and contained pages**" checkbox and click the **Delete** button to completly delete the Folder/Page. +Select the "**Delete this page and all its contents and contained pages**" checkbox and click the **Delete** button to completely delete the Folder/Page.
@@ -20,4 +24,4 @@ Under the **Page Content** tab, click on the **Blocks** tab and then the **Edit* Click on the Trash Can icon :trash-alt:next to the **Block Title** field. You will be redirected the the **Delete** confirmation page. You need to confirm that you want to delete the **Page** or **Folder** selected. The delete screen will show the impact deleting the **Page** or **Folder** you selected will have. How many Web Pages and Contained Pages (if deleting a folder) you will be deleting. -Select the "**Delete this page and all its contents and contained pages**" checkbox and click the **Delete** button to completly delete the Folder/Page. +Select the "**Delete this page and all its contents and contained pages**" checkbox and click the **Delete** button to completely delete the Folder/Page. diff --git a/topics/sites/edit-site-contents/portal-support-customize.md b/topics/sites/edit-site-contents/portal-support-customize.md index ff70225..9d96b9b 100644 --- a/topics/sites/edit-site-contents/portal-support-customize.md +++ b/topics/sites/edit-site-contents/portal-support-customize.md @@ -1,25 +1,29 @@ -# Customized Help Requests - -If desired, site pages can be configured to have a **Submit a Request** button below the other content. Admins can also customize who recieves the help request that is triggered with this button, if desired. +--- +description: If desired, site pages can be configured to have a Submit a Request button below the other content. +--- + +# Customized Help Requests + +If desired, site pages can be configured to have a **Submit a Request** button below the other content. Admins can also customize who receives the help request that is triggered with this button, if desired. Select the **Sites** Toolkit on the **Admin Home Page**. Select the **Site** counter and then in the **Results** panel select the **Portal** you want to edit. -Open the **Sitemap** panel and navigate to the **Page** for where you want to add the help ** Email**. Click on the Magnifying icon next to the **Page** you would like to edit. +Open the **Sitemap** panel and navigate to the **Page** for where you want to add the help **Email**. Click on the Magnifying icon next to the **Page** you would like to edit. -Under the **Page Setup** tab, click on the **Settings** tab and click on the Pencil icon next to the **Content Tags** field under the **Content** heading. +Under the **Page Setup** tab, click on the **Settings** tab and click on the Pencil icon next to the **Content Tags** field under the **Content** heading. In the **Update Content** card, add **Support URL** to the list of content labels in the **Content Tags** field. ![content-tags.png](https://e02.insite.com/files/sites/global/customizing-contact-email-for-each-page/content-tags.png) -Click the **Save** button to save your changes. +Click the **Save** button to save your changes. -Under the **Page Content** tab, click on the **Support URL** tab and click the **Edit** button. +Under the **Page Content** tab, click on the **Support URL** tab and click the **Edit** button. -In the **Content** field add the desired email address starting with **mailto:** +In the **Content** field add the desired email address starting with **mailto:** ![support-url1.png](https://e02.insite.com/files/sites/global/customizing-contact-email-for-each-page/support-url1.png) -At the bottom of the **Page**, where you added the **Support URL**, will display a **Submit a Request** button. When a user clicks on the button it will open your default email application and automatically open a **New Message** email. +At the bottom of the **Page**, where you added the **Support URL**, will display a **Submit a Request** button. When a user clicks on the button it will open your default email application and automatically open a **New Message** email. -![support-url-3.png](https://e02.insite.com/files/sites/global/customizing-contact-email-for-each-page/support-url-3.png) +![support-url-3.png](https://e02.insite.com/files/sites/global/customizing-contact-email-for-each-page/support-url-3.png) diff --git a/topics/sites/edit-site-contents/preview-contents.md b/topics/sites/edit-site-contents/preview-contents.md index a0e277b..2dccf12 100644 --- a/topics/sites/edit-site-contents/preview-contents.md +++ b/topics/sites/edit-site-contents/preview-contents.md @@ -1,9 +1,13 @@ +--- +description: You are able to preview the content you are creating at any time. There are 3 ways of previewing contents. +--- + # Preview Contents You are able to preview the content you are creating at any time. There are 3 ways of previewing contents. 1. Select **Preview** Button (** Preview**) at the top right of the content panel. When you select **Preview** it will open the page you are currently working on in a new tab with a view of what it will look like on the Portal or Web Site. -2. Select the **Toggle View** icon () on the menu bar. This will toggle the conent view so you are able to preview what the contents will look like on Portal or Web Site. +2. Select the **Toggle View** icon () on the menu bar. This will toggle the content view so you are able to preview what the contents will look like on Portal or Web Site. 3. Select **Toggle Side by Side** icon () on the menu bar. You will have a Side by Side view of the content you are adding to your Portal or Web Site. To exit the Side by Side view, click on the Toggle Full Screen icon diff --git a/topics/sites/edit-site-contents/upload-document.md b/topics/sites/edit-site-contents/upload-document.md index 2f5fa49..bb3e40a 100644 --- a/topics/sites/edit-site-contents/upload-document.md +++ b/topics/sites/edit-site-contents/upload-document.md @@ -1,3 +1,7 @@ +--- +description: To upload a document you are able to drag and drop the document from file into the body of the content.\ +--- + # Upload Document To upload a document you are able to drag and drop the document from file into the body of the content.\ diff --git a/topics/sites/new-portal/README.md b/topics/sites/new-portal/README.md index 739f629..a8f6688 100644 --- a/topics/sites/new-portal/README.md +++ b/topics/sites/new-portal/README.md @@ -1,3 +1,18 @@ -# Creating Beautiful Web Sites and Learner Portals - -(The content is under revision. Check back soon.) +--- +description: >- + Build websites and learner portals: pages, tiles, hosts, and the sitemap + view +--- + +# Creating Beautiful Web Sites and Learner Portals + +The Sites toolkit hosts both your public website and the learner portals your customers see. This section covers building new sites and portals, adding content, and using the sitemap and tile features that make administration easier. + +## In this section + +* [Host and Edit a Public Website using Shift iQ](create-website.md) +* [Have One or More Portals for Your Customers](create-portal.md) +* [Creating Contents for Your Sites](create-site-contents.md) +* [Using the Sitemap tab to Navigate Site Administration](sitemap.md) +* [Add Portal Tile Pictures or Icons](tile-pics.md) +* [List of Portal Tile URLs Customers will Love](portal-tile-urls.md) diff --git a/topics/sites/new-portal/create-portal.md b/topics/sites/new-portal/create-portal.md index 3b6ce3f..04119a5 100644 --- a/topics/sites/new-portal/create-portal.md +++ b/topics/sites/new-portal/create-portal.md @@ -1,3 +1,15 @@ -# Have One or More Portals for Your Customers - -(The content is under revision. Check back soon.) +--- +description: Create one or more learner portals for your customers +--- + +# Have One or More Portals for Your Customers + +> **Draft** — this page is a stub. Detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* The difference between a public site and a learner portal. +* When to create more than one portal. +* The steps to add a new portal and connect it to a customer group. + + diff --git a/topics/sites/new-portal/create-site-contents.md b/topics/sites/new-portal/create-site-contents.md index 6621f4f..756d886 100644 --- a/topics/sites/new-portal/create-site-contents.md +++ b/topics/sites/new-portal/create-site-contents.md @@ -1,3 +1,7 @@ +--- +description: From the Admin Home Page, select Sites toolkit. Under the Web Sites heading, click on the Site counter. +--- + # Creating Contents for Your Sites ## Creating New Folders and Pages on your Site diff --git a/topics/sites/new-portal/create-website.md b/topics/sites/new-portal/create-website.md index ba341aa..4c8662a 100644 --- a/topics/sites/new-portal/create-website.md +++ b/topics/sites/new-portal/create-website.md @@ -1,3 +1,7 @@ +--- +description: To create and setup a new Website, please contact your Shift iQ Account Manager to assist with the initial setup. +--- + # Host and Edit a Public Website using Shift iQ To create and setup a new Website, please contact your **Shift iQ Account Manager** to assist with the initial setup. diff --git a/topics/sites/new-portal/portal-tile-urls.md b/topics/sites/new-portal/portal-tile-urls.md index 1a91ef1..4dce0c4 100644 --- a/topics/sites/new-portal/portal-tile-urls.md +++ b/topics/sites/new-portal/portal-tile-urls.md @@ -1,72 +1,76 @@ -# List of Portal Tile URLs Customers will Love - -### Portal Tile URLs: +--- +description: /ui/portal/events/classes/search +--- - **Classes:** -/ui/portal/events/classes/search +# List of Portal Tile URLs Customers will Love + +### Portal Tile URLs + + **Classes:** +/ui/portal/events/classes/search **Registrations:** /ui/portal/events/classes/registrations/search - **Calendar:** + **Calendar:** /ui/portal/events/calendar /ui/portal/events/appointments/search - **Invoices:** + **Invoices:** /ui/portal/billing/invoices - **Credentials:** + **Credentials:** /ui/portal/record/credentials/learners/search - **Instructor Credentials Search:** + **Instructor Credentials Search:** /ui/portal/records/credentials/instructors/search - **Standards Outline:** + **Standards Outline:** /ui/portal/standards/outline?standard=***Standard Unique Identifier*** - **Assessment Summary:** -/ui/portal/learning/progress?course=***Course Unique Identifier*** + **Assessment Summary:** +/ui/portal/learning/progress?course=***Course Unique Identifier*** **Assessment Attempts:** /ui/portal/assessments/attempts/search - **Survey Responses:** + **Survey Responses:** /ui/portal/surveys/responses/search - **Logbooks:** + **Logbooks:** /ui/portal/records/logbooks/search **Validators Logbook View** /ui/admin/records/logbooks/validators/search - **My Profile:** -/ui/portal/identity/profile + **My Profile:** +/ui/portal/identity/profile - **Creating New People:** + **Creating New People:** /ui/portal/contacts/people/search - **Issues:** + **Issues:** /ui/portal/workflow/cases/search **Instructors Gradebook View** /ui/admin/records/gradebooks/instructors/search -### Competancy Tile URLs: +### Competancy Tile URLs - **Standards (Documents):** + **Standards (Documents):** /ui/portal/standards/documents/search - **Competency Based Job Descriptions:** + **Competency Based Job Descriptions:** /ui/portal/standards/documents/search?type=Job+Description **Occupational Profiles:** /ui/portal/standards/documents/search?type=Occupation+Profile - **Competancy Mapping:** + **Competancy Mapping:** /ui/portal/standards/documents/analysis?type=careermap - **Ocupation Standards:** + **Occupation Standards:** /ui/portal/standards/documents/search?type=National+Occupation+Standard - **Competency Clustering:** -/ui/portal/standards/documents/search?type=Competency+Clustering + **Competency Clustering:** +/ui/portal/standards/documents/search?type=Competency+Clustering diff --git a/topics/sites/new-portal/sitemap.md b/topics/sites/new-portal/sitemap.md index 35952ac..4368323 100644 --- a/topics/sites/new-portal/sitemap.md +++ b/topics/sites/new-portal/sitemap.md @@ -1,9 +1,13 @@ -# Using the Sitemap tab to Navigate Site Administration - +--- +description: To Navigate the different folders/pages in the Web Sites toolkit, select the Sitemap panel +--- + +# Using the Sitemap tab to Navigate Site Administration + To Navigate the different folders/pages in the Web Sites toolkit, select the Sitemap panel -You will see all the folders/pages on your portal/site. +You will see all the folders/pages on your portal/site. You can click on the edit button (pencil) next to the title of the folder/page to view and edit the content. -![sitemap-1.png](https://e02.insite.com/files/sites/global/navigating-sites-sitemap/sitemap-1.png) +![sitemap-1.png](https://e02.insite.com/files/sites/global/navigating-sites-sitemap/sitemap-1.png) diff --git a/topics/sites/new-portal/tile-pics.md b/topics/sites/new-portal/tile-pics.md index 92a4045..2dc91a9 100644 --- a/topics/sites/new-portal/tile-pics.md +++ b/topics/sites/new-portal/tile-pics.md @@ -1,3 +1,7 @@ +--- +description: Under the Page Content tab of the Site folder you want to add a picture to, select the ImageURL tab (if there is no ImageURL tab, please +--- + # Add Portal Tile Pictures or Icons ## Adding Portal Tile Pictures @@ -11,7 +15,7 @@ The image will display as a URL link, for example:\ Edit the URL link to only show /files/sites/insite/example/insite.jpg and select Save. -![](https://e02.insite.com/files/sites/global/tile-pics/portal-tile.png) +![Portal tile](https://e02.insite.com/files/sites/global/tile-pics/portal-tile.png) ## Adding Portal Tile Icons @@ -19,7 +23,7 @@ If you'd prefer to use fa-fa icons, rather than pictures, you can do so on the P On the Update Content card, add the icon code in the Icon field. Icon codes can be found on websites like [_Font Awesome_](https://fontawesome.com/v5/search)_._ -![](https://e02.insite.com/files/web/bc03a342-fc83-4fe9-946c-af900134fadd/icon-1.png) +![Icon 1](https://e02.insite.com/files/web/bc03a342-fc83-4fe9-946c-af900134fadd/icon-1.png) Click the Save button to save your changes. @@ -27,6 +31,6 @@ When going back to the portal, you will see the Icon you added on the tile.
-![](https://e02.insite.com/files/web/bc03a342-fc83-4fe9-946c-af900134fadd/icon-2.png)
+![Icon 2](https://e02.insite.com/files/web/bc03a342-fc83-4fe9-946c-af900134fadd/icon-2.png)

diff --git a/topics/sites/overview.md b/topics/sites/overview.md index 39b23f4..9ee970b 100644 --- a/topics/sites/overview.md +++ b/topics/sites/overview.md @@ -1,3 +1,9 @@ -# Overview - -Easily create, edit, and expand portal content for your users with our Web Sites toolkit. Add custom or stock images to portal tiles for a visually appealing experience. Set privacy at any level to ensure only specific users or groups can access the content. External public-facing web sites can also be created and hosted here, simplifying the administration of your various sites (see www.insite.com for an example). +--- +description: >- + Build and host learner portals and external public-facing websites with + privacy controls, portal tiles, and shared content management +--- + +# Overview + +Easily create, edit, and expand portal content for your users with our Web Sites toolkit. Add custom or stock images to portal tiles for a visually appealing experience. Set privacy at any level to ensure only specific users or groups can access the content. External public-facing web sites can also be created and hosted here, simplifying the administration of your various sites (see www.insite.com for an example). diff --git a/topics/sites/publish-privacy/README.md b/topics/sites/publish-privacy/README.md index d5a5e0b..0254a34 100644 --- a/topics/sites/publish-privacy/README.md +++ b/topics/sites/publish-privacy/README.md @@ -1,3 +1,13 @@ -# Publishing and Privacy Settings - -(The content is under revision. Check back soon.) +--- +description: >- + Control portal permissions and publish individual site pages +--- + +# Publishing and Privacy Settings + +Before a site page becomes visible, it has to be published and its privacy controlled. This section covers portal permissions and the publishing step itself. + +## In this section + +* [Portal Permissions](portal-permissions.md) +* [Publishing Site Pages](publish-site-page.md) diff --git a/topics/sites/publish-privacy/portal-permissions.md b/topics/sites/publish-privacy/portal-permissions.md index d976fda..474014c 100644 --- a/topics/sites/publish-privacy/portal-permissions.md +++ b/topics/sites/publish-privacy/portal-permissions.md @@ -1,3 +1,7 @@ +--- +description: Groups in the Contacts toolkit can be used to set the access permissions on the Organization Portal. +--- + # Portal Permissions **Groups** in the **Contacts** toolkit can be used to set the access permissions on the Organization **Portal**. If no **Groups** has been created or new groups are required, it can be added in the **Contacts** toolkit, using **Groups** (See **Create a New Group**). Once a **Group** has been created, and users were added to the group, go to the **Site** Toolkit and navigate to your portal Folder/Page where the permissions need to be added. @@ -9,4 +13,4 @@ In the **Filter** card, select the **Group Type** (Department, District, Employe Click the Save button to save your changes. *Note: You are able to give permissions to different **Group Types** for the same **Folder/Page**. -e.g. A combination of **Groups** withing a **Role** and within a **List** can be added to the permission list of a **Foler/Page**.* +e.g. A combination of **Groups** withing a **Role** and within a **List** can be added to the permission list of a **Folder/Page**.* diff --git a/topics/sites/publish-privacy/publish-site-page.md b/topics/sites/publish-privacy/publish-site-page.md index 08a421d..bbcf1f5 100644 --- a/topics/sites/publish-privacy/publish-site-page.md +++ b/topics/sites/publish-privacy/publish-site-page.md @@ -1,10 +1,14 @@ -# Publishing Site Pages - +--- +description: "Steps to Publish or Unpublish tile from Portal page:" +--- + +# Publishing Site Pages + Steps to ** Publish** or ** Unpublish** tile from Portal page: * Select the **Sites** toolkit on the **Admin Home** page and then select the **Sites** counter. * Select **Portal Title** on the **Sites Search** page. -* Navigate to the **Folder/Page** you want to ** Publish** or ** Unpublish** by clicking on the Folder/Page name. -* Click on the **Magnifying Glass** icon () next to the Folder/Page to open the page you want to ** Publish** or ** Unpublish**. -* Click on the **Page Setup** tab and then click the ** Publish** button so the Folder/Page will become visible on the portal; -* Or click on the ** Unpublish** button so the Folder/page will not longer be visible on the portal. +* Navigate to the **Folder/Page** you want to ** Publish** or ** Unpublish** by clicking on the Folder/Page name. +* Click on the **Magnifying Glass** icon () next to the Folder/Page to open the page you want to ** Publish** or ** Unpublish**. +* Click on the **Page Setup** tab and then click the ** Publish** button so the Folder/Page will become visible on the portal; +* Or click on the ** Unpublish** button so the Folder/page will not longer be visible on the portal. diff --git a/topics/standards/create-standards/README.md b/topics/standards/create-standards/README.md index 466b356..94a4d35 100644 --- a/topics/standards/create-standards/README.md +++ b/topics/standards/create-standards/README.md @@ -1,13 +1,19 @@ -# Creating Standards - +--- +description: "A good process (or best practice) for building a complex, hierarchical framework in Shift iQ with the Framework Builder tool is to:" +--- + +# Creating Standards + A good process (or best practice) for building a complex, hierarchical framework in Shift iQ with the Framework Builder tool is to: + 1. Create the framework and its properties 2. Create the Level 1 competencies and organizers -3. Create the Level 2 competencies and organizers +3. Create the Level 2 competencies and organizers 4. Create further levels for each of the Level 1 competencies Note that if the Framework asset you’re creating is to be evaluated by assessments (i.e, an exam form, exam specification), it is typically best to follow the tiers of: - - Framework - - General Area of Competence (GAC) - - Competency - - Task + +* Framework + * General Area of Competence (GAC) + * Competency + * Task diff --git a/topics/standards/create-standards/add-standard.md b/topics/standards/create-standards/add-standard.md index d84e114..5d1f18c 100644 --- a/topics/standards/create-standards/add-standard.md +++ b/topics/standards/create-standards/add-standard.md @@ -1,5 +1,9 @@ -# Options for Adding Standards - +--- +description: 1. Click on Add New Standard at the top of any Standards search screen. Leave the first dropdown box as One New Standard. +--- + +# Options for Adding Standards + ## Add New Standard 1. Click on **Add New Standard** at the top of any Standards search screen. Leave the first dropdown box as **One New Standard**. @@ -15,28 +19,36 @@ Add a new Standard directly into the outline when working in Outline mode 1. Switch to Edit mode 2. On the left side of the screen, select the Standard that you want to be the parent of the new Standard(s) by clicking the circle inside the cell. 3. Scroll down to the **Create New Standard** card on the right -3. Choose the Standard type from the radio list options -4. Click in the text box and type a name for the new Standard (or multiple new standards of the same type under the same parent, separted by pressing the Enter key so each one is on it's own line. -5. Click the **Create** button. The new standard(s) can now be edited in outline mode. +4. Choose the Standard type from the radio list options +5. Click in the text box and type a name for the new Standard (or multiple new standards of the same type under the same parent, separated by pressing the Enter key so each one is on it's own line. +6. Click the **Create** button. The new standard(s) can now be edited in outline mode. ## Add Multiple New Standards from an Outline + Use an outline to quickly build a framework with multiple nested standards. + 1. Click on **Add New Standard** at the top of any Standards search screen. Change the first dropdown box to **Multiple new standards from an outline** 2. Optional, select a parent if you want the new standards nested under an existing standard -3. In the Tiers field, edit the default list of “Framework, Area, Competency” to indicate which asset types you are uploading in the Hierarchy. -4. In the Outline box, edit the existing sample content as desired. The ouline can include hierarchy, titles, summary content and codes. Example structure: - Framework, Area, Competency - # A. Framework name - ## 1. Area name - ### 1.1. Competency name - Summary: - Summary content +3. In the Tiers field, edit the default list of “Framework, Area, Competency” to indicate which asset types you are uploading in the Hierarchy. +4. In the Outline box, edit the existing sample content as desired. The outline can include hierarchy, titles, summary content and codes. Example structure: + Framework, Area, Competency + + # A. Framework name + + ## 1. Area name + + ### 1.1. Competency name + + Summary: + Summary content ## Upload a New Framework from a File + Quickly create an entire framework using the Upload options + 1. Click on **Add New Standard** at the top of any Standards search screen. Change the first dropdown box to **Upload one new standard from a file**. 2. Choose the File Type (Markdown or JSON) of the file you are uploading 3. Select the file you want to upload using the Open File button -4. Upload the file using the File Upload button, note the Uploaded File Content on the right to confirm you selected the correct file. +4. Upload the file using the File Upload button, note the Uploaded File Content on the right to confirm you selected the correct file. 5. Click the **Next** button to get to the Review tab; you can make changes to the Names and Standard Types on this screen if desired. -6. Scroll to the bottom and click **Save** to create the Framework +6. Scroll to the bottom and click **Save** to create the Framework diff --git a/topics/standards/create-standards/framework-settings.md b/topics/standards/create-standards/framework-settings.md index 4147f8d..7dbe4ab 100644 --- a/topics/standards/create-standards/framework-settings.md +++ b/topics/standards/create-standards/framework-settings.md @@ -1,25 +1,31 @@ -# Framework settings and details - +--- +description: To a framework asset’s functional relationships, and/or specific settings and properties for the asset not displayed in Edit Mode, switch to View Mode +--- + +# Framework settings and details + To a framework asset’s functional relationships, and/or specific settings and properties for the asset not displayed in Edit Mode, switch to View Mode and select the asset to be edited. - - Details – Most details will already be completed; some additional ones you may want to use: - - Code – enter a numbering or alphanumeric coding convention for your framework if it wasn’t entered at creation. Note that you need only define the asset at each tier of the framework and the coding convention will be propogated by the framework asset. - - Configuration Properties – These will also likely already be defined from your initial asset creation, but can be added to as appropriate - - Settings – there are several Settings that can be specified for each Standard asset sub-type that won’t have been done in the hierarchical build of the framework. These include: - - Complexity/Taxonomy - - Criticality - - Frequency - - Difficulty Level - - Etc. - - Categories – allows you to set and assign Categories to assets in order to better organize, search and report on them - - Privacy – allows you to specify what roles or contacts have access to the standard framework. +* Details – Most details will already be completed; some additional ones you may want to use: + * Code – enter a numbering or alphanumeric coding convention for your framework if it wasn’t entered at creation. Note that you need only define the asset at each tier of the framework and the coding convention will be propagated by the framework asset. + * Configuration Properties – These will also likely already be defined from your initial asset creation, but can be added to as appropriate +* Settings – there are several Settings that can be specified for each Standard asset sub-type that won’t have been done in the hierarchical build of the framework. These include: + * Complexity/Taxonomy + * Criticality + * Frequency + * Difficulty Level + * Etc. + +* Categories – allows you to set and assign Categories to assets in order to better organize, search and report on them +* Privacy – allows you to specify what roles or contacts have access to the standard framework. Notes: - - Functional relationships typically relate from Plan or Exam assets to frameworks; these will be considered in the following workshops. - - Some of the Builder tools are not needed when working with Framework assets; e.g., the Pin tool is used primarily with Exam Builder. - - As you are building the framework, refer to the two-pane work panel frequently. The left pane or View Mode will now be displaying the competency framework and its elements hierarchically. - - This should now mimic your reference competency framework document, but will have asset numbers and properties assigned to each of the elements within the framework. The right frame or *Asset Creation* pane allows you to refer to the properties of the individual asset within the framework you are creating. - - After completing the framework, check it against your original reference document to be sure it has been captured correctly. - - Publish the competency framework by saving it in the Shift iQ environment so that you can display and use it. It will now be listed as a published asset in the Frameworks app. - - Note that if you create the skills development plan related to this framework that you will be referencing it frequently. +* Functional relationships typically relate from Plan or Exam assets to frameworks; these will be considered in the following workshops. +* Some of the Builder tools are not needed when working with Framework assets; e.g., the Pin tool is used primarily with Exam Builder. +* As you are building the framework, refer to the two-pane work panel frequently. The left pane or View Mode will now be displaying the competency framework and its elements hierarchically. + +* This should now mimic your reference competency framework document, but will have asset numbers and properties assigned to each of the elements within the framework. The right frame or *Asset Creation* pane allows you to refer to the properties of the individual asset within the framework you are creating. +* After completing the framework, check it against your original reference document to be sure it has been captured correctly. +* Publish the competency framework by saving it in the Shift iQ environment so that you can display and use it. It will now be listed as a published asset in the Frameworks app. +* Note that if you create the skills development plan related to this framework that you will be referencing it frequently. diff --git a/topics/standards/create-standards/manage-standards-outline.md b/topics/standards/create-standards/manage-standards-outline.md index 5995013..a1e95c7 100644 --- a/topics/standards/create-standards/manage-standards-outline.md +++ b/topics/standards/create-standards/manage-standards-outline.md @@ -1,43 +1,50 @@ -# Manage Frameworks using the Outline View - +--- +description: You can also add and manage frameworks using the Outline view. +--- + +# Manage Frameworks using the Outline View + You can also add and manage frameworks using the Outline view. ## Opening Framework Outline View + How to access it from search screen and from edit screen of any of it's children ## Managing Outline in View Mode - - Click on the ![picture2.png](https://e02.insite.com/files/sites/global/9890/picture2.png) Asset Construction and Outlining Tool and select the asset. The framework asset now appears. - - The framework will be displayed in View Mode. Note that in general, to define a framework hierarchy and hierarchical relationships, you will be working in Edit mode. - - Typically, you will be working in View mode to define: - - a framework asset’s functional relationships, - - specific settings and properties for the asset not displayed in Edit Mode - - Should you want to edit this asset in the administrative interface, or view the entire set of properties for it, simply click on the Edit icon on the far right side in View Mode. +* Click on the ![picture2.png](https://e02.insite.com/files/sites/global/9890/picture2.png) Asset Construction and Outlining Tool and select the asset. The framework asset now appears. +* The framework will be displayed in View Mode. Note that in general, to define a framework hierarchy and hierarchical relationships, you will be working in Edit mode. +* Typically, you will be working in View mode to define: + * a framework asset’s functional relationships, + * specific settings and properties for the asset not displayed in Edit Mode -## Managing Outline in Edit Mode -- Click on Edit to edit the framework or create new assets within it -- A two-pane work panel will appear; the left pane is approximately 1/2 of the display and is the View or outline mode of the framework. The right frame is approximately the *Asset Edit and Creation* pane. -- The properties of the asset, asset number, and other assets and their properties contained by the same parent asset will be displayed in the asset creation pane, along with the edit icon which will launch a modal bar to set properties for each of the competency assets. +* Should you want to edit this asset in the administrative interface, or view the entire set of properties for it, simply click on the Edit icon on the far right side in View Mode. -![picture1.jpg](https://e02.insite.com/files/sites/global/9890/picture1.jpg) +## Managing Outline in Edit Mode +* Click on Edit to edit the framework or create new assets within it +* A two-pane work panel will appear; the left pane is approximately 1/2 of the display and is the View or outline mode of the framework. The right frame is approximately the *Asset Edit and Creation* pane. +* The properties of the asset, asset number, and other assets and their properties contained by the same parent asset will be displayed in the asset creation pane, along with the edit icon which will launch a modal bar to set properties for each of the competency assets. -- Indent – contain this new asset in the parent above and expand framework one level - - Enter the title of this asset. - - You’ll want to specify if competencies assessed in the framework are Theory, and/or Practical, using the asset creation tools when they are created. - - Competency Assessment Environment - - Theory - - Practical - - An asset number has been assigned to this and it has been created in the administrative back end of Shift iQ with the following default properties: +![picture1.jpg](https://e02.insite.com/files/sites/global/9890/picture1.jpg) - - Asset sub-type: Competency - - Asset properties: - - Collapsible - - Theory and/or Practical - - You’ll notice that the Outline Mode pane now displays the hierarchical framework of assets and their properties you are creating so that you can reference it. - - Next create the next and remaining Level 1 competencies in the framework using the same process. - - You’ll now see in the Outline Mode pane your framework and the two to four Level 1 competencies, modules or folders. +* Indent – contain this new asset in the parent above and expand framework one level + * Enter the title of this asset. + * You’ll want to specify if competencies assessed in the framework are Theory, and/or Practical, using the asset creation tools when they are created. + * Competency Assessment Environment + * Theory + * Practical + * An asset number has been assigned to this and it has been created in the administrative back end of Shift iQ with the following default properties: + + * Asset sub-type: Competency + * Asset properties: + * Collapsible + * Theory and/or Practical + * You’ll notice that the Outline Mode pane now displays the hierarchical framework of assets and their properties you are creating so that you can reference it. + * Next create the next and remaining Level 1 competencies in the framework using the same process. + * You’ll now see in the Outline Mode pane your framework and the two to four Level 1 competencies, modules or folders. Code your assets as you create them in the hierarchy to match your standards framework. - - Note that you need only define the asset at each tier of the framework and the coding convention will be propagated by the framework asset. - - The system references assets by asset number so you can also use this to specify an asset within a framework. + +* Note that you need only define the asset at each tier of the framework and the coding convention will be propagated by the framework asset. +* The system references assets by asset number so you can also use this to specify an asset within a framework. diff --git a/topics/standards/create-standards/upload-standards-using-markdown.md b/topics/standards/create-standards/upload-standards-using-markdown.md index 3772177..25dfe45 100644 --- a/topics/standards/create-standards/upload-standards-using-markdown.md +++ b/topics/standards/create-standards/upload-standards-using-markdown.md @@ -1,3 +1,7 @@ +--- +description: When uploading your Competency Framework using Markdown, the structure of the file must follow a specific heading hierarchy, depending on the number +--- + # Upload Standards using Markdown When uploading your Competency Framework using Markdown, the structure of the file must follow a specific heading hierarchy, depending on the number of tiers in your framework. @@ -14,4 +18,4 @@ Example of Markdown Upload 4 Tiers:\ (_The heading specifying the tiers must be included at the top of your file you are uploading._) Example of Competency Framework after upload:\ -![](<../../.gitbook/assets/Framework Example.png>) +![Framework Example](<../../.gitbook/assets/Framework Example.png>) diff --git a/topics/standards/documents/README.md b/topics/standards/documents/README.md index 84bcf62..14d3cee 100644 --- a/topics/standards/documents/README.md +++ b/topics/standards/documents/README.md @@ -1,3 +1,15 @@ -# Creating and Editing Documents - -(The content is under revision. Check back soon.) +--- +description: Publish, translate, print, and analyze standards documents +--- + +# Creating and Editing Documents + +Documents are the published output of a standards framework. This section covers the steps to publish a document on the portal, translate it, print or download it, work with the administrator view, and publish analysis tools alongside it. + +## In this section + +* [Publishing Documents on the Portal](publish-document.md) +* [Translation Tips](translation-tips.md) +* [Printing and Downloading](printing-and-downloading.md) +* [Working in the Administrator View](administrator-view.md) +* [Publishing Document Analysis Tools on the Portal](document-analysis.md) diff --git a/topics/standards/documents/administrator-view.md b/topics/standards/documents/administrator-view.md index 1b3bd9f..55e5430 100644 --- a/topics/standards/documents/administrator-view.md +++ b/topics/standards/documents/administrator-view.md @@ -1,5 +1,9 @@ -# Working in the Administrator View - +--- +description: Documents are created to group and print Standards into various useful outputs +--- + +# Working in the Administrator View + Documents are created to group and print Standards into various useful outputs Create a new Document using the Administration Tools panel in the Standards Module. All Documents consist of four parts. @@ -10,7 +14,7 @@ Title and additional information you would like to include with your document. T Use your document as a Template by checking the Template checkbox under the Settings tab. Template documents are locked on the portal. They may be duplicated, but not modified. **Attach Competencies** -Attach Competencies to your document on the Competencies panel. You may include some or all competencies in a particulare area. If you choose to attach only some, the parent area for those competencies will still print on the Document as a header. In order for competencies to show on the outline screen, you must follow the convention: FRAMEWORK, then Area Asset, then Competency. +Attach Competencies to your document on the Competencies panel. You may include some or all competencies in a particular area. If you choose to attach only some, the parent area for those competencies will still print on the Document as a header. In order for competencies to show on the outline screen, you must follow the convention: FRAMEWORK, then Area Asset, then Competency. **Relate other Documents** Attach a pre-selected group of competencies by relating an existing Document. All the competencies from the related document will now be attached to the current document. @@ -22,5 +26,6 @@ Output and print a copy of your document using hte Download button in the Setup **Why can't I relate a NOS or Job Description to one I'm creating?** In order to relate a document 2 conditions must be met: + * The Document you are editing must not be a template (Settings tab) -* You must have been assigned permission to the Standards/Documents module. If you do not have this permission, please contact your administrator. +* You must have been assigned permission to the Standards/Documents module. If you do not have this permission, please contact your administrator. diff --git a/topics/standards/documents/document-analysis.md b/topics/standards/documents/document-analysis.md index 81af6c8..812f0b6 100644 --- a/topics/standards/documents/document-analysis.md +++ b/topics/standards/documents/document-analysis.md @@ -1,6 +1,10 @@ -# Publishing Document Analysis Tools on the Portal - -Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. +--- +description: Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. +--- + +# Publishing Document Analysis Tools on the Portal + +Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. Create a link to a page where you can select any document analysis tool using the following syntax: @@ -13,4 +17,4 @@ Create one Page inside your Folder for each Document or Analysis tool you want t /ui/portal/standards/documents/analysis?type=jobfitanalysis2 /ui/portal/standards/documents/analysis?type=standardsanalysis* -Also see [Publishing Documents on the Portal](/ui/help/portal/standards/documents/publish-document) +Also see [Publishing Documents on the Portal](/ui/help/portal/standards/documents/publish-document) diff --git a/topics/standards/documents/printing-and-downloading.md b/topics/standards/documents/printing-and-downloading.md index 2585ab5..dffb5e6 100644 --- a/topics/standards/documents/printing-and-downloading.md +++ b/topics/standards/documents/printing-and-downloading.md @@ -1,7 +1,11 @@ -# Printing and Downloading - -Download your document to Microsoft Word. +--- +description: Download your document to Microsoft Word. +--- -Heading styles can be edited in word to correspond with your organization's standards. You can also choose to configure a full table of contents in the downloaded document. +# Printing and Downloading -Save preferred settings for faster access the next time you download a document. +Download your document to Microsoft Word. + +Heading styles can be edited in word to correspond with your organization's standards. You can also choose to configure a full table of contents in the downloaded document. + +Save preferred settings for faster access the next time you download a document. diff --git a/topics/standards/documents/publish-document.md b/topics/standards/documents/publish-document.md index 5194ddd..2a26b28 100644 --- a/topics/standards/documents/publish-document.md +++ b/topics/standards/documents/publish-document.md @@ -1,6 +1,10 @@ -# Publishing Documents on the Portal - -Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. +--- +description: Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. +--- + +# Publishing Documents on the Portal + +Publish Documents to the Portal through the Web Sites module. We recommend you make a Folder to group your Documents on the portal. Note that you must have the admin/standards/documents permission in order to modify relationships for documents in the portal. If you are unable to modify relationships, please contact your administrator to have this permission added to your account. @@ -15,4 +19,4 @@ Control access to Documents on the portal using the Privacy settings on the Web Note that you must have the admin/standards/documents permission in order to modify relationships for documents in the portal. If you are unable to modify relationships, please contact your administrator to have this permission added to your account. -Also see [Publishing Document Analysis Tools on the Portal](/ui/help/portal/standards/documents/document-analysis) +Also see [Publishing Document Analysis Tools on the Portal](/ui/help/portal/standards/documents/document-analysis) diff --git a/topics/standards/documents/translation-tips.md b/topics/standards/documents/translation-tips.md index 616a875..efd8d18 100644 --- a/topics/standards/documents/translation-tips.md +++ b/topics/standards/documents/translation-tips.md @@ -1,3 +1,7 @@ +--- +description: Translate the content of each element in the document using the translation feature in the Content panel. +--- + # Translation Tips **Translate** the content of each element in the document using the translation feature in the Content panel. diff --git a/topics/standards/edit-standards/README.md b/topics/standards/edit-standards/README.md index 987d0df..906bfb5 100644 --- a/topics/standards/edit-standards/README.md +++ b/topics/standards/edit-standards/README.md @@ -1,3 +1,23 @@ -# Managing and Editing Standards - -(The content is under revision. Check back soon.) +--- +description: >- + Manage existing standards: numbering, ordering, translations, occupations, and + type changes +--- + +# Managing and Editing Standards + +Once a standards framework exists, this section covers the day-to-day editing tasks: numbering, re-ordering, searching, bulk updates, translations, occupations, and changing standard types. + +## In this section + +* [Manually enter alternate language text](alternate-language.md) +* [Numbering a Single Standard](number-single-standard.md) +* [Re-order in the Outline view](re-order-in-outline-view.md) +* [Searching Standards](searching-standards.md) +* [Bulk update numbering](bulk-update-numbering.md) +* [Delete in Outline view](delete-in-outline-view.md) +* [Reorder within a Standard](reorder-within-standard.md) +* [Use Google Translate to enter alternate language text](use-google-translate.md) +* [Change Standard Type](change-standard-type.md) +* [Occupations](occupations.md) +* [Competencies in a document print in an illogical structure](competencies-print.md) diff --git a/topics/standards/edit-standards/alternate-language.md b/topics/standards/edit-standards/alternate-language.md index 857252c..8a0a442 100644 --- a/topics/standards/edit-standards/alternate-language.md +++ b/topics/standards/edit-standards/alternate-language.md @@ -1,11 +1,15 @@ -# Manually enter alternate language text - +--- +description: Contact your system administrator to set the secondary languages available for translation. +--- + +# Manually enter alternate language text + Contact your system administrator to set the secondary languages available for translation. Available options are: *French, German, Italian, Japanese, Portuguese, Russian, Spanish, Ukrainian* -Currently, translated content may only be entered for fields shown in the Content ribbon when editing a Standard. +Currently, translated content may only be entered for fields shown in the Content ribbon when editing a Standard. These fields are: *Title, Summary, Description, Feature, Body, Statements* @@ -20,5 +24,4 @@ These fields are: **Step 5** Save - -*Helpful tip: You can edit multiple fields within the Content ribbon without losing your data, but you must save before you navigate away from the Content ribbon.* +*Helpful tip: You can edit multiple fields within the Content ribbon without losing your data, but you must save before you navigate away from the Content ribbon.* diff --git a/topics/standards/edit-standards/bulk-update-numbering.md b/topics/standards/edit-standards/bulk-update-numbering.md index 599ed15..cdf015f 100644 --- a/topics/standards/edit-standards/bulk-update-numbering.md +++ b/topics/standards/edit-standards/bulk-update-numbering.md @@ -1,11 +1,13 @@ -# Bulk update numbering - -You can update multiple codes quickly and easily by using the **Classify** function. Edit the Framework you will be working with and select the **Options menu** and then the **Classify** option. +--- +description: You can update multiple codes quickly and easily by using the Classify function. +--- + +# Bulk update numbering +You can update multiple codes quickly and easily by using the **Classify** function. Edit the Framework you will be working with and select the **Options menu** and then the **Classify** option. ![picture9.jpg](https://e02.insite.com/files/sites/global/9932/picture9.jpg) From here you can update all the Codes for the Framework you have selected. - -*Important: Click the green **Save Changes** button at the bottom of the page, not the **Recode** button at the top of the page. The **Recode** button will re-number all standards in the framework. The **Save Change**s button will save your custom changes.* +*Important: Click the green **Save Changes** button at the bottom of the page, not the **Recode** button at the top of the page. The **Recode** button will re-number all standards in the framework. The **Save Change**s button will save your custom changes.* diff --git a/topics/standards/edit-standards/change-standard-type.md b/topics/standards/edit-standards/change-standard-type.md index 5592833..f485290 100644 --- a/topics/standards/edit-standards/change-standard-type.md +++ b/topics/standards/edit-standards/change-standard-type.md @@ -1,3 +1,7 @@ +--- +description: You can update multiple Standard Types by using the Classify function. From here you can update all the Standard Types for the Framework you have selected. +--- + # Change Standard Type You can update multiple Standard Types by using the **Classify** function. From here you can update all the Standard Types for the Framework you have selected. diff --git a/topics/standards/edit-standards/competencies-print.md b/topics/standards/edit-standards/competencies-print.md index ff0c375..3772427 100644 --- a/topics/standards/edit-standards/competencies-print.md +++ b/topics/standards/edit-standards/competencies-print.md @@ -1,3 +1,7 @@ +--- +description: The user expects competencies printing in a document to follow the logical structure of the framework, see below. +--- + # Competencies in a document print in an illogical structure The user expects competencies printing in a document to follow the logical structure of the framework, see below. diff --git a/topics/standards/edit-standards/delete-in-outline-view.md b/topics/standards/edit-standards/delete-in-outline-view.md index dfef111..91ed541 100644 --- a/topics/standards/edit-standards/delete-in-outline-view.md +++ b/topics/standards/edit-standards/delete-in-outline-view.md @@ -1,3 +1,17 @@ -# Delete in Outline view - -Delete a Standard using the Edit mode of the Outline view. +--- +description: Delete a standard from the Outline view in Edit mode +--- + +# Delete in Outline view + +Delete a standard using the Edit mode of the Outline view. + +> **Draft** — detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* Switching the Outline view into Edit mode. +* Selecting the standard to delete. +* The implications of deletion when the standard has downstream relationships. + + diff --git a/topics/standards/edit-standards/number-single-standard.md b/topics/standards/edit-standards/number-single-standard.md index f99052b..3a28fd8 100644 --- a/topics/standards/edit-standards/number-single-standard.md +++ b/topics/standards/edit-standards/number-single-standard.md @@ -1,9 +1,13 @@ +--- +description: Add a numbering system to your Standards for easy reference. The numbers you see in the Standard Outline view are Codes. +--- + # Numbering a Single Standard Add a numbering system to your Standards for easy reference. The numbers you see in the Standard Outline view are **Codes**. Example: -In the example below, the Framework **DESIGN** has a code **A**. the GAC asset **Conduct pre-Design Consultations** has a code **1**, and the Competency Asset **Consult with external/internal clien**t has a code **1**. The codes nest automatically so there is no need to enter A.1.1. +In the example below, the Framework **DESIGN** has a code **A**. the GAC asset **Conduct pre-Design Consultations** has a code **1**, and the Competency Asset **Consult with external/internal client**t has a code **1**. The codes nest automatically so there is no need to enter A.1.1. To enter a code for a single Standard, edit the standard and enter the code into the Standard/Details/Code box. diff --git a/topics/standards/edit-standards/occupations.md b/topics/standards/edit-standards/occupations.md index 9946de4..72aeae8 100644 --- a/topics/standards/edit-standards/occupations.md +++ b/topics/standards/edit-standards/occupations.md @@ -1,3 +1,7 @@ +--- +description: Occupations are just a type of Framework Standard. +--- + # Occupations Occupations are just a type of Framework Standard. diff --git a/topics/standards/edit-standards/re-order-in-outline-view.md b/topics/standards/edit-standards/re-order-in-outline-view.md index 9945450..0c38225 100644 --- a/topics/standards/edit-standards/re-order-in-outline-view.md +++ b/topics/standards/edit-standards/re-order-in-outline-view.md @@ -1,3 +1,7 @@ +--- +description: Open the Framework you wish to work with in Outline view. Choose the Edit tab and select the Standard for which you wish to re-order the child Standards +--- + # Re-order in the Outline view Open the Framework you wish to work with in Outline view. Choose the Edit tab and select the Standard for which you wish to re-order the child Standards diff --git a/topics/standards/edit-standards/reorder-within-standard.md b/topics/standards/edit-standards/reorder-within-standard.md index ab3f473..03ecffb 100644 --- a/topics/standards/edit-standards/reorder-within-standard.md +++ b/topics/standards/edit-standards/reorder-within-standard.md @@ -1,3 +1,7 @@ +--- +description: Edit the Standard for which you wish to re-order the child Standards. +--- + # Reorder within a Standard Edit the Standard for which you wish to re-order the child Standards. diff --git a/topics/standards/edit-standards/searching-standards.md b/topics/standards/edit-standards/searching-standards.md index 70c2237..13833a0 100644 --- a/topics/standards/edit-standards/searching-standards.md +++ b/topics/standards/edit-standards/searching-standards.md @@ -1,3 +1,7 @@ +--- +description: From the Admin Home page select the Standards Toolkit +--- + # Searching Standards From the Admin Home page select the **Standards** Toolkit diff --git a/topics/standards/edit-standards/use-google-translate.md b/topics/standards/edit-standards/use-google-translate.md index a5e32ab..647eb15 100644 --- a/topics/standards/edit-standards/use-google-translate.md +++ b/topics/standards/edit-standards/use-google-translate.md @@ -1,3 +1,7 @@ +--- +description: Step 1 Click the globe icon in the top right corner to have Google translate the text for you. +--- + # Use Google Translate to enter alternate language text **Step 1** Click the globe icon in the top right corner to have Google translate the text for you. diff --git a/topics/standards/overview.md b/topics/standards/overview.md index e9c5989..69f03dd 100644 --- a/topics/standards/overview.md +++ b/topics/standards/overview.md @@ -1,3 +1,9 @@ -# Overview - -Use standards to build detailed competency frameworks that can be tied to courses and assessments to drive adaptive competency-based training. +--- +description: >- + Build competency frameworks, tie them to courses and assessments, and drive + adaptive competency-based training +--- + +# Overview + +Use standards to build detailed competency frameworks that can be tied to courses and assessments to drive adaptive competency-based training. diff --git a/topics/standards/relationships/README.md b/topics/standards/relationships/README.md index 30dfa08..1dcdbf2 100644 --- a/topics/standards/relationships/README.md +++ b/topics/standards/relationships/README.md @@ -1,3 +1,15 @@ -# Relationships - -(The content is under revision. Check back soon.) +--- +description: >- + Connect standards to each other through upstream and downstream relationships +--- + +# Relationships + +Relationships connect one standard to another so a single change can flow through a framework. This section covers the types of relationships available and how to add or remove them. + +## In this section + +* [Types of relationships](types-of-relationships.md) +* [Add a relationship](add-a-relationship.md) +* [Remove downstream relationships](remove-downstream.md) +* [Remove upstream relationships](remove-upstream.md) diff --git a/topics/standards/relationships/add-a-relationship.md b/topics/standards/relationships/add-a-relationship.md index 491d592..c578649 100644 --- a/topics/standards/relationships/add-a-relationship.md +++ b/topics/standards/relationships/add-a-relationship.md @@ -1,11 +1,15 @@ -# Add a relationship - +--- +description: Step 1 Edit the Standard that you want to hold the upstream relationship +--- + +# Add a relationship + **Step 1** Edit the Standard that you want to hold the upstream relationship **Step 2** Click the Add icon in the Relationships ribbon **Step 3** Search for the Standard(s) you want to create downstream relationships with. - - Easily add multiple relationships by searching for a Parent Standard. The search results returned here will show all Standards under the Parent you searched for. You can select all and create all the relationships at once. - - Narrow your search by entering criteria in the Standard Type box - - Search for a single Standard by name or number using the Standard Number or Keyword box +* Easily add multiple relationships by searching for a Parent Standard. The search results returned here will show all Standards under the Parent you searched for. You can select all and create all the relationships at once. +* Narrow your search by entering criteria in the Standard Type box +* Search for a single Standard by name or number using the Standard Number or Keyword box diff --git a/topics/standards/relationships/remove-downstream.md b/topics/standards/relationships/remove-downstream.md index 512d8f8..bce75e7 100644 --- a/topics/standards/relationships/remove-downstream.md +++ b/topics/standards/relationships/remove-downstream.md @@ -1,3 +1,7 @@ +--- +description: In the Downstream tab of the Relationships ribbon, select the relationships you want to remove and click the Delete icon. +--- + # Remove downstream relationships In the Downstream tab of the Relationships ribbon, select the relationships you want to remove and click the Delete icon. **This will not delete the downstream Competency or Standard, ONLY the relationship between them.** You can remove downstream relationships one at a time or select multiple relationships to delete. diff --git a/topics/standards/relationships/remove-upstream.md b/topics/standards/relationships/remove-upstream.md index cebec30..77c1d86 100644 --- a/topics/standards/relationships/remove-upstream.md +++ b/topics/standards/relationships/remove-upstream.md @@ -1,3 +1,7 @@ +--- +description: Step 1 Edit the downstream Standard you want to remove from it’s parent +--- + # Remove upstream relationships **Step 1** Edit the downstream Standard you want to remove from it’s parent diff --git a/topics/standards/relationships/types-of-relationships.md b/topics/standards/relationships/types-of-relationships.md index 6582f38..4cd34e8 100644 --- a/topics/standards/relationships/types-of-relationships.md +++ b/topics/standards/relationships/types-of-relationships.md @@ -1,3 +1,7 @@ +--- +description: Currently there are five types of relationships between Standards +--- + # Types of relationships Currently there are five types of relationships between Standards diff --git a/topics/surveys/configure-survey-details/README.md b/topics/surveys/configure-survey-details/README.md index 4dfe007..de3cf17 100644 --- a/topics/surveys/configure-survey-details/README.md +++ b/topics/surveys/configure-survey-details/README.md @@ -1,2 +1,19 @@ +--- +description: >- + Configure a survey form: details, outline, translations, conditions, + branches, and summaries +--- + # Configuring a survey form +Each survey form has a set of tabs that control how it behaves: basic details, outline, translations, conditional logic, branching, and summary rules. This section covers each tab and how to search for a survey. + +## In this section + +* [Details Tab](details-tab.md) +* [Searching for a survey](searching-surveys.md) +* [Survey Outline](survey-outline.md) +* [Translations Tab](translations-tab.md) +* [Conditions Tab](conditions-tab.md) +* [Branches Tab](branches-tab.md) +* [Summaries Tab](summaries-tab.md) diff --git a/topics/surveys/configure-survey-details/branches-tab.md b/topics/surveys/configure-survey-details/branches-tab.md index 4cff7c8..79ec800 100644 --- a/topics/surveys/configure-survey-details/branches-tab.md +++ b/topics/surveys/configure-survey-details/branches-tab.md @@ -1,3 +1,7 @@ +--- +description: The Branches tab shows a summary of the skip patterns contained in the survey. +--- + # Branches Tab The Branches tab shows a summary of the skip patterns contained in the survey. diff --git a/topics/surveys/configure-survey-details/conditions-tab.md b/topics/surveys/configure-survey-details/conditions-tab.md index c160038..80b57dc 100644 --- a/topics/surveys/configure-survey-details/conditions-tab.md +++ b/topics/surveys/configure-survey-details/conditions-tab.md @@ -1,14 +1,19 @@ -# Conditions Tab - +--- +description: Add conditional logic to your survey. +--- + +# Conditions Tab + Add conditional logic to your survey. This function hides a question on a subsequent page based on the answers of an earlier page (in case the condition is met or not met). -If Conditions have been enabled, you will see this icon beside the survey questions. +If Conditions have been enabled, you will see this icon beside the survey questions. + +How to add an condition: -How to add an condidtion: * Under the **Conditions tab**, click on the **Add Conditions** button. * Select the question for which you want to define conditional logic so that another question on the survey is suppressed, depending upon the respondent's answer to it. -* Select the answer field value that will cause one or more subsequent questions to be supressed. You can suppress only questions that appear on subsequent pages. You cannot supress questions on the same page. +* Select the answer field value that will cause one or more subsequent questions to be suppressed. You can suppress only questions that appear on subsequent pages. You cannot suppress questions on the same page. * Select the question that should be suppressed when a respondent selects the above answer field value. -* Click **Add Condidtion** button. +* Click **Add Condition** button. -You must remove all responses before you can edit skip patterns, conditions, or branches. Remove responses under the Edit Survey/Details tab. +You must remove all responses before you can edit skip patterns, conditions, or branches. Remove responses under the Edit Survey/Details tab. diff --git a/topics/surveys/configure-survey-details/details-tab.md b/topics/surveys/configure-survey-details/details-tab.md index 888923d..9e086a4 100644 --- a/topics/surveys/configure-survey-details/details-tab.md +++ b/topics/surveys/configure-survey-details/details-tab.md @@ -1,5 +1,9 @@ -# Details Tab - +--- +description: Internal Name (Required) +--- + +# Details Tab + #### IDENTIFICATION **Internal Name (Required)** @@ -15,7 +19,7 @@ Link for testing and viewing the survey. This URL is intended for use by Adminis Lock your survey if you want to prevent changes to the survey settings or questions. **Hook/Integration Code** -Unique code for integration with internal toolkits and external systems. The survey Hook is for integrating the survey with the Gradebook module. If used, the identifier here must match the hook in the corresponding Gradebook. +Unique code for integration with internal toolkits and external systems. The survey Hook is for integrating the survey with the Gradebook module. If used, the identifier here must match the hook in the corresponding Gradebook. **Department** The departments to which this survey is assigned. @@ -23,9 +27,10 @@ The departments to which this survey is assigned. #### CONFIGURATION **Publication Status** -* **Draft:** A Drafted survey is open to responses from administrators only. + +* **Draft:** A Drafted survey is open to responses from administrators only. * **Open (Published):** An Opened survey is open to all respondents. -* **Closed:** Responses are not accepted for a closed survey +* **Closed:** Responses are not accepted for a closed survey * **Archived:** Archived surveys no longer show up in the default search results. View archived surveys by explicitly searching for them using the Closed (Archived) search criteria. **Opened Date** @@ -35,20 +40,22 @@ The date and time when responses to the survey are opened to all respondents. New responses are not permitted after the survey is closed. **Expected Duration (in Minutes)** -The number of minutes that a user is expected to need to complete this survey. If your survey is published to the Portal, the expected duration will show up on the survey card in portal. +The number of minutes that a user is expected to need to complete this survey. If your survey is published to the Portal, the expected duration will show up on the survey card in portal. **Feedback for Respondents** Allow respondents to review feedback from the survey administrator about answers they submitted to questions on the form. This is available for Radio Button style questions and is configured in the Question Options panel. + * **Summary Feedback:** Summary Feedback will display all the question in the Survey a user answered, that has feedback enabled in the question itself. If questions were answered, but there is no feedback in that question, it will not show when Summary Feedback is selected. It will also display likert type questions, if likert style question were setup in your survey questions. -* **Detailed Feedback:** Detailed Feedback will show the user all the question question in the survey, including the questions the user did not answer (or were not required to answer). +* **Detailed Feedback:** Detailed Feedback will show the user all the question question in the survey, including the questions the user did not answer (or were not required to answer). * **Feedback Disabled:** No feedback will be given to the user once the survey is completed. **Limit Responses per Respondent** -Select Limited to ensure each respondent answers the survey only once (preferred). If you need to be able to download the name of responses, you must limit responses to one per person. +Select Limited to ensure each respondent answers the survey only once (preferred). If you need to be able to download the name of responses, you must limit responses to one per person. + * **Limited:** Allows respondents to answer the survey only once, but also allows identification of respondent. The Start Survey button goes away once a respondent has taken the survey once. To allow them to take it again, you must either - * Turn off the Limit response option - * Delete the respondent’s answers + * Turn off the Limit response option + * Delete the respondent’s answers * **Unlimited:** Allows respondents to answer the survey an unlimited amount of times, and also allow anonymous responses. **Allow Anonymous Responses** -Allow users to answer the survey without identifying themselves and without signing in. +Allow users to answer the survey without identifying themselves and without signing in. diff --git a/topics/surveys/configure-survey-details/searching-surveys.md b/topics/surveys/configure-survey-details/searching-surveys.md index 02e0025..d8132a8 100644 --- a/topics/surveys/configure-survey-details/searching-surveys.md +++ b/topics/surveys/configure-survey-details/searching-surveys.md @@ -1,7 +1,11 @@ +--- +description: To search for existing Surveys, go to the Survey Toolkit. Below the Surveys heading, select the Surveys Counter. +--- + # Searching for a survey -To search for existing Surveys, go to the **Survey** Toolkit. Below the Surveys heading, selec the **Surveys** Counter. +To search for existing Surveys, go to the **Survey** Toolkit. Below the Surveys heading, select the **Surveys** Counter. -Select the **Criteria** tab and click on the **Clear** button to remove any previous search citeria you have used. Fill in the search criterias you would like to use to search for the existing Survey and click on **Filter**. +Select the **Criteria** tab and click on the **Clear** button to remove any previous search citeria you have used. Fill in the search criteria you would like to use to search for the existing Survey and click on **Filter**. Your search results will be displayed under the **Results** tab. diff --git a/topics/surveys/configure-survey-details/summaries-tab.md b/topics/surveys/configure-survey-details/summaries-tab.md index cc028d0..67b0165 100644 --- a/topics/surveys/configure-survey-details/summaries-tab.md +++ b/topics/surveys/configure-survey-details/summaries-tab.md @@ -1,3 +1,17 @@ -# Summaries Tab - -This tab shows a list of likert summary questions in a survey. +--- +description: Manage the list of Likert summary questions on a survey +--- + +# Summaries Tab + +This tab shows a list of Likert summary questions in a survey. + +> **Draft** — detailed steps to be authored by a subject-matter expert. + +This page will cover: + +* What a Likert summary question is. +* Adding, editing, and removing summary entries on the tab. +* How summaries surface in survey reporting. + + diff --git a/topics/surveys/configure-survey-details/survey-outline.md b/topics/surveys/configure-survey-details/survey-outline.md index e015fc0..e23d9bb 100644 --- a/topics/surveys/configure-survey-details/survey-outline.md +++ b/topics/surveys/configure-survey-details/survey-outline.md @@ -1,5 +1,5 @@ -# Survey Outline - +# Survey Outline + **New** Create a New Survey **Duplicate** @@ -9,8 +9,8 @@ Using this button will translate the entire Survey, depending on the language co **History** History shows a detailed log of who has made changes to the survey. **Download** -Download .JSON file of Survey - **Reports** +Download .JSON file of Survey + **Reports** Survey Report give statistics for each question in the survey. **Responses** Shortcut all started and completed responses for this survey. @@ -19,7 +19,7 @@ This is often used after testing when you are preparing to launch your survey li ### Translations -The **Translations** tab enables you to set the language and translation features of the survey (if necessary). Surveys must be authored in English. Once the English version is complete, you can translate it into another language. +The **Translations** tab enables you to set the language and translation features of the survey (if necessary). Surveys must be authored in English. Once the English version is complete, you can translate it into another language. Select **Translate** in the **Survey** Panel and then select the language you would like to translate your survey into. @@ -29,16 +29,16 @@ Please contact [support@shiftiq.com](mailto:support@shiftiq.com) if you are unsu ### Conditions -Add conditional logic to your survey. This function hides a question on a subsequent page based on the answers of an earlier page (in case the condition is met or not met). +Add conditional logic to your survey. This function hides a question on a subsequent page based on the answers of an earlier page (in case the condition is met or not met). -If Conditions have been enabled, you will see this icon beside the survey questions. +If Conditions have been enabled, you will see this icon beside the survey questions. ### Branches -The Branches tab shows a summary of the skip patterns contained in the survey. +The Branches tab shows a summary of the skip patterns contained in the survey. Set up skip patterns by editing the answer options for the question you want to branch off. Skip patterns will be displayed on the Branches tab but cannot be edited on the Branches tab. When actively editing a survey, you should check here periodically for errors or warnings. -**Warning:** Be aware when editing skip patterns, conditions, or branches, that if there is a user currently in the process of responding to the survey, they may get stuck. You will likely need to delete their response and have them start again. +**Warning:** Be aware when editing skip patterns, conditions, or branches, that if there is a user currently in the process of responding to the survey, they may get stuck. You will likely need to delete their response and have them start again. diff --git a/topics/surveys/configure-survey-details/translations-tab.md b/topics/surveys/configure-survey-details/translations-tab.md index 89a4cc9..fb30661 100644 --- a/topics/surveys/configure-survey-details/translations-tab.md +++ b/topics/surveys/configure-survey-details/translations-tab.md @@ -1,11 +1,15 @@ -# Translations Tab - +--- +description: Under the Translations tab, you will be able to see the the language your Survey was translated to. +--- + +# Translations Tab + Under the **Translations** tab, you will be able to see the the language your Survey was translated to. If there is not translation, it will show None under **Translate To**. -The **Translate** button at the top of the page enables you to set the language and translation features of the survey (if necessary). Surveys must be authored in English. Once the English version is complete, you can translate it into another language. +The **Translate** button at the top of the page enables you to set the language and translation features of the survey (if necessary). Surveys must be authored in English. Once the English version is complete, you can translate it into another language. Select the **Translate** button in the **Survey** and then select the language you would like to translate your survey into. The translations are generated by Google Translate and automatically populated into the fields. Edit and replace as necessary. -Please contact [**Shift iQ Support**](mailto:support@insite.com) if you are unsure whether your account has been set up for multi-language surveys. +Please contact [**Shift iQ Support**](mailto:support@insite.com) if you are unsure whether your account has been set up for multi-language surveys. diff --git a/topics/surveys/create-survey/README.md b/topics/surveys/create-survey/README.md index 3a2dee2..949178b 100644 --- a/topics/surveys/create-survey/README.md +++ b/topics/surveys/create-survey/README.md @@ -1,6 +1,10 @@ +--- +description: To create a new survey form, click on the Surveys toolkit on the Admin Home Screen, then select the Survey counter. +--- + # Creating survey forms -To create a new survey form, click on the **Surveys** toollkit on the Admin Home Screen, then select the **Survey** counter. +To create a new survey form, click on the **Surveys** toolkit on the Admin Home Screen, then select the **Survey** counter. Click on **Add New Survey** at the top of the Survey search page. @@ -13,7 +17,7 @@ Select **Limit Responses per Respondent**, **Allow Anonymous Responses** and **C * Turn off the Limit response option * Delete the respondent’s answers * Not Limited - Allows respondents to answer the survey an unlimited amount of times, and also allow anonymous responses.
-* **Allow Anonymous Responses** Allow users to answer the survey without identifying themselves and without signing in. Please Note: Allow Anonymous Responses is only availble if **Not Limited** is selected under **Limit Responses per Respondent** settings
+* **Allow Anonymous Responses** Allow users to answer the survey without identifying themselves and without signing in. Please Note: Allow Anonymous Responses is only available if **Not Limited** is selected under **Limit Responses per Respondent** settings
* **Confidentiality for Respondents** Enable this setting if you do not want to disclose confidential/personal information about survey respondents to survey administrators.
Click the **Save** button. diff --git a/topics/surveys/create-survey/download-surveys.md b/topics/surveys/create-survey/download-surveys.md index 103efcd..e6b1123 100644 --- a/topics/surveys/create-survey/download-surveys.md +++ b/topics/surveys/create-survey/download-surveys.md @@ -1,3 +1,7 @@ +--- +description: "Open the survey that you want to download the JSON (*.json) file for." +--- + # Download Survey in JSON (*.json) format Open the survey that you want to download the **JSON (*.json)** file for. diff --git a/topics/surveys/instructions-respondents/README.md b/topics/surveys/instructions-respondents/README.md index 1fb7315..4d10a09 100644 --- a/topics/surveys/instructions-respondents/README.md +++ b/topics/surveys/instructions-respondents/README.md @@ -1,3 +1,7 @@ +--- +description: "In the Contact panel, add survey instructions for respendents:" +--- + # Providing instructions to respondents In the **Contact** panel, add survey instructions for respendents: diff --git a/topics/surveys/instructions-respondents/adding-buttons.md b/topics/surveys/instructions-respondents/adding-buttons.md index 159d9f6..0c605a8 100644 --- a/topics/surveys/instructions-respondents/adding-buttons.md +++ b/topics/surveys/instructions-respondents/adding-buttons.md @@ -1,3 +1,7 @@ +--- +description: When user completes a survey, there is no Home or Return to Course buttons available to click on to take a user out of the survey.\ +--- + # Adding Home/Return to Course buttons at end of Survey When user completes a survey, there is no Home or Return to Course buttons available to click on to take a user out of the survey.\ @@ -6,4 +10,4 @@ E.g.\ Thank you for completing the Carpenter Self-Assessment! \ &#xNAN;_\ADD TEXT FOR BUTTON HERE\_\ Click the Continue button to review your completed application. To return to your Home Page, click on the NBCC logo at the top left.\ -![](https://e02.insite.com/files/sites/global/adding-home-return-to-course-buttons-at-end-of-survey/survey.png)
+![Survey](https://e02.insite.com/files/sites/global/adding-home-return-to-course-buttons-at-end-of-survey/survey.png)
diff --git a/topics/surveys/overview.md b/topics/surveys/overview.md index c10f654..7fb9df0 100644 --- a/topics/surveys/overview.md +++ b/topics/surveys/overview.md @@ -1,3 +1,9 @@ -# Overview - -Surveys enable you to collect information from *your* Users. Surveys can be used to gather opinions or experience (for example, a course evaluation or customer feedback). They can also be used as application forms, and data gathered in the application can update fields in the contact record. Survey responses can be anonymous, or connected to a contact. +--- +description: >- + Collect feedback, run evaluations, and capture application data through + surveys, with responses that can be anonymous or attached to a contact +--- + +# Overview + +Surveys enable you to collect information from *your* Users. Surveys can be used to gather opinions or experience (for example, a course evaluation or customer feedback). They can also be used as application forms, and data gathered in the application can update fields in the contact record. Survey responses can be anonymous, or connected to a contact. diff --git a/topics/surveys/question-configuration/README.md b/topics/surveys/question-configuration/README.md index b7370a0..502aa0b 100644 --- a/topics/surveys/question-configuration/README.md +++ b/topics/surveys/question-configuration/README.md @@ -1,2 +1,22 @@ +--- +description: >- + Configure survey questions: types, Likert, options, breaks, termination, and + formatting +--- + # Configuring survey questions +A survey is built from questions. This section covers picking a question type, configuring options, inserting breaks, terminating early, embedding videos and hyperlinks, and adjusting fonts and colours. + +## In this section + +* [Question Types](question-types.md) +* [Likert Questions](likert-questions.md) +* [Configure Radio Button, Dropdown, or Check Box Questions](configure-option-questions.md) +* [Edit, Copy or Delete a Question](edit-question.md) +* [Adding a Break Question](adding-a-break-question.md) +* [Adding a Break Page](adding-a-break-page.md) +* [Terminating a Survey](terminating-a-survey.md) +* [Adding Videos and Hyperlinks](add-videos-hyperlinks.md) +* [Replacing a Survey Question in an existing Survey](replace-question.md) +* [Changing Fonts and Colors](changing-fonts-and-colors.md) diff --git a/topics/surveys/question-configuration/add-videos-hyperlinks.md b/topics/surveys/question-configuration/add-videos-hyperlinks.md index b97fdf6..716b64c 100644 --- a/topics/surveys/question-configuration/add-videos-hyperlinks.md +++ b/topics/surveys/question-configuration/add-videos-hyperlinks.md @@ -23,7 +23,7 @@ When you select Create Link, the system will create the outline needed for the l You are able to configure the link with an email address instead. You can either add a email address between the square brackets or text. Instead of adding a website, you remove the http:// and add [mailto:add email address.](mailto:support@insite.com.) The full link will be \[Click Here to Email]\(mailto:support@insite.com) or \[support@insite.com]\(mailto:support@insite.com). The text will display as [Click Here to Email](mailto:support@insite.com) or [support@insite.com](mailto:support@insite.com) -#### Open Link in New Browser Window: +#### Open Link in New Browser Window If you require the link you are inserting to open on in a new browser window, you can us the following link:\ \text to display\ diff --git a/topics/surveys/question-configuration/adding-a-break-page.md b/topics/surveys/question-configuration/adding-a-break-page.md index 97b090b..f51e9c8 100644 --- a/topics/surveys/question-configuration/adding-a-break-page.md +++ b/topics/surveys/question-configuration/adding-a-break-page.md @@ -1,3 +1,7 @@ +--- +description: "To add or remove page breaks in your survey. In the Details panel, choose Page # from the drop Down and Page Break as Question Type. Click Save" +--- + # Adding a Break Page To add or remove page breaks in your survey. In the Details panel, choose **Page #** from the drop Down and **Page Break** as Question Type. Click **Save** diff --git a/topics/surveys/question-configuration/adding-a-break-question.md b/topics/surveys/question-configuration/adding-a-break-question.md index 4ea8ea2..93da9ee 100644 --- a/topics/surveys/question-configuration/adding-a-break-question.md +++ b/topics/surveys/question-configuration/adding-a-break-question.md @@ -1,3 +1,7 @@ +--- +description: "Break Question is used to branch the survey due to a certain response. For eg: If a respondent clicks No to a certain question." +--- + # Adding a Break Question Break Question is used to branch the survey due to a certain response. For eg: If a respondent clicks No to a certain question. It might either redirect to a new question or share some text as feedback such as Unfortunately this survey is not for you. diff --git a/topics/surveys/question-configuration/changing-fonts-and-colors.md b/topics/surveys/question-configuration/changing-fonts-and-colors.md index c9fedfb..86516bc 100644 --- a/topics/surveys/question-configuration/changing-fonts-and-colors.md +++ b/topics/surveys/question-configuration/changing-fonts-and-colors.md @@ -1,90 +1,101 @@ +--- +description: Change the font, color, weight, italics, underline, and line breaks of survey question text and answer options using inline HTML +--- + # Changing Fonts and Colors -Changing Survey Question Text and Response Options Font and Color
---------------------------------------------------------------------- +## Changing Survey Question Text and Response Options Font and Color + +The font and color in survey question text and response option text can be changed. + +The HTML code needs to be added around the text as follows: + +```html +insert text +``` + +Instead of adding the Name of the Font (e.g. Green, Yellow, Blue, etc.) you are able to add the [HTML Color Code](https://html-color.codes/) (e.g. `#24ffff`, `#ff2424`, `#ffff24`, etc.). + +![Inline HTML font-size and color tags around a survey response option](../../.gitbook/assets/font-color-html-tag-example-1.png) + +![Inline HTML font-size and color tags around a longer survey response option](../../.gitbook/assets/font-color-html-tag-example-2.png) + +The above will display as follows: + +![Survey response options rendered with custom font sizes and colors](../../.gitbook/assets/font-color-html-tag-rendered.png) + +## Bold, Italic and Underline and Line Breaks for Survey Questions + +You are able to add Line Breaks, Bold, Underline, and _Italicize_ sentences or words when adding answer options to a survey. + +HTML code to **bold** a sentence or word — wrap with `` and ``: + +```html +This text is bold. +``` -The font and color in survey question text and response option text can be changed. +HTML code to **underline** a sentence or word — wrap with `` and ``: -The HTML code needs to be added around the text as follows: \ -\insert text\ +```html +The text is underlined. +``` -Instead of adding the Name of the Font (e.g. Green, Yellow, Blue, etc.) you are able to add the \ -[HTML Color Code ](https://html-color.codes/)(e.g. #24ffff , #ff2424 , #ffff24 , ect.)\ -\ - ![](../../../files/sites/global/changing-font-and-color/color-change-1.png) +HTML code to **italicize** a sentence or word — wrap with `` and ``: -
+```html +The text was Italicized. +``` -![](../../../files/sites/global/changing-font-and-color/color-change-2.png)
+HTML code to add a **line break** — insert `
` at the position where the break should appear: -So, the above will display as follows:
+```html +Adding a line break at the end of the question options.
The next sentence will display in a new line. +``` -![](../../../files/sites/global/changing-font-and-color/color-change.png)
+The text will display as: -
+> Adding a line break at the end of the question options. +> The next sentence will display in a new line. -Bold, Italic and Underline and Line Breaks for Survey Questions
-------------------------------------------------------------------- +![Inline HTML bold and italic tags around survey answer options in the editor](../../.gitbook/assets/survey-bold-italic-source.png) -You are able to add Line Breaks, Bold, Underline, _Italicize_ sentences/words when adding answer options to an survey.\ -HTML Code to Bold a sentence/word:Add \ in the beginning of the sentence/word and \ at the end.Example: "\This text is bold.\" will display as "This text is bold."\ -HTML Code for Underlining a sentence/word:\ -Add \ in the beginning of the sentence/word and \ at the end.Example: "The text is \underlined\." will display as "The text is underlined."\ -HTML Code for _Italicizing_ a sentence/word:\ -Add \ in the beginning of the sentence/word and \ at the end.\ -Example: "The text was \Italicized\." will display as "The text was _Italicized_."\ -HTML code for adding a Line Break:Add \
at the end of your question option.Example: "Adding a line break at the end of the question options.\
The next sentence will display in a new line." The text will display as:\ -"Adding a line break at the end of the question options\ -The next sentence will display in a new line."\ -![](../../../files/sites/global/survey-questions-edit/bold-italic.png)\ -\ -![](../../../files/sites/global/survey-questions-edit/bold-italic-1.png)\ -\ -
+![Survey answer options rendered with bold and italic formatting](../../.gitbook/assets/survey-bold-italic-rendered.png) ## Change font color of Question Text and Answer Options -
+### How to change the font color of the answer options in a survey -##
+1. Open the Survey and click on the **Content** tab. +2. Under the **Page Header** tab, click the **Edit** button. +3. Add the following code: -1\. How to change the font color of the Answer Options in an Survey: + ```html + + ``` -* Open the Survey and click on the Content tab. -* Under the Page Header tab, click the Edit button. -* Add the following code:\ - \ - \\ -
-* You can change the color by typing the color name (e.g. black, red, blue) or adding the HTML color code (e.g. #060606, #F90F0F, #0F0FF9) behind color:\ - Example: color: blue / color: #060606 -* Click Save. +4. You can change the color by typing the color name (e.g. `black`, `red`, `blue`) or adding the HTML color code (e.g. `#060606`, `#F90F0F`, `#0F0FF9`) after `color:` — for example, `color: blue` or `color: #060606`. +5. Click **Save**. -![](../../../files/sites/global/change-font-color/surveyfontcolor2.png)\ -\ -Please note: Adding this code to the survey will change the color for all answer options in the survey.\ -
+![Survey content editor showing the form-check-label style being saved](../../.gitbook/assets/survey-answer-options-color-rendered.png) -2\. How to change the font color of the survey Question Text: +> Note: Adding this code to the survey will change the color for all answer options in the survey. -* Open the Survey and under the Questions tab, click the Pencil icon next to the question you want to change the font color for. -* Add the code \add text here\ in the Question Text field. -* Add your question text between "color:black"> and \ -* Click Save. +### How to change the font color of the survey question text -\ -![](../../../files/sites/global/change-font-color/surveyfontcolor.png)\ -\ -![](../../../files/sites/global/change-font-color/surveyfontcolor1.png)\ -
+1. Open the Survey and under the **Questions** tab, click the **Pencil** icon next to the question whose font color you want to change. +2. Add the code `add text here` in the **Question Text** field. +3. Add your question text between `"color:black">` and ``. +4. You can change the color by typing the color name (e.g. `black`, `red`, `blue`) or adding the HTML color code (e.g. `#060606`, `#F90F0F`, `#0F0FF9`) after `color:` — for example, `color: blue` or `color: #060606`. +5. Click **Save**. -
+![Survey question editor showing inline color span being applied to question text](../../.gitbook/assets/survey-question-text-color-edit.png) -Note: When you are adding the color coding, you need to make sure that there are no spaces in the code where there isn't supposed to be. +![Survey question rendered in a custom color](../../.gitbook/assets/survey-question-text-color-rendered.png) -The code should look like this: \Add Content Here\\ -If spaces are in included in the code, where there shouldn't be spaces (e.g. < span style="color:#4f81bd">Add Content Here< /span> There is a space between the < and span in the beginning of the code and also between < and / at the end of the code), the code is not going to work correctly. +> Note: When you are adding the color coding, make sure there are no spaces in the code where there are not supposed to be. +> +> The code should look like this: `Add Content Here`. +> +> If spaces are included where they should not be (for example, `< span style="color:#4f81bd">Add Content Here< /span>` — a space between `<` and `span` at the beginning, and a space between `<` and `/` at the end), the code will not work correctly. -If you are copy and pasting this code, please make sure that the code copied correctly after pasting it, and fix it if it did not. +If you are copy-pasting this code, please make sure the code copied correctly after pasting it, and fix it if it did not. diff --git a/topics/surveys/question-configuration/configure-option-questions.md b/topics/surveys/question-configuration/configure-option-questions.md index 8590d7f..a6cb30e 100644 --- a/topics/surveys/question-configuration/configure-option-questions.md +++ b/topics/surveys/question-configuration/configure-option-questions.md @@ -1,5 +1,9 @@ -# Configure Radio Button, Dropdown, or Check Box Questions - +--- +description: Insert a new question with desired type. +--- + +# Configure Radio Button, Dropdown, or Check Box Questions + Insert a new question with desired type. **Radio Button List** questions restrict respondents to a single answer. @@ -9,9 +13,10 @@ Insert a new question with desired type. **Check Box List** questions allow respondents to select multiple answers. Under the Question panel, insert question text and decide on options. -- The questions number by default, but you can override that by using the Question Code box. -- The colour picker allows you to specify the colour you want the question numbers appear on the survey. + +* The questions number by default, but you can override that by using the Question Code box. +* The colour picker allows you to specify the colour you want the question numbers appear on the survey. Under Options panel, define your answer fields. -Set up more complex surveys by enabling Branches. Once Branches are enabled, configure the skip pattern by clicking the double arrow icon on the main question page. +Set up more complex surveys by enabling Branches. Once Branches are enabled, configure the skip pattern by clicking the double arrow icon on the main question page. diff --git a/topics/surveys/question-configuration/edit-question.md b/topics/surveys/question-configuration/edit-question.md index 09d0be3..4f45a56 100644 --- a/topics/surveys/question-configuration/edit-question.md +++ b/topics/surveys/question-configuration/edit-question.md @@ -1,11 +1,15 @@ -# Edit, Copy or Delete a Question - -You can **Edit/Copy/Delete** the question using **icons** on the left side of the questions. The questions in your survey are displayed in the order they were entered. +--- +description: You can Edit/Copy/Delete the question using icons on the left side of the questions. +--- + +# Edit, Copy or Delete a Question + +You can **Edit/Copy/Delete** the question using **icons** on the left side of the questions. The questions in your survey are displayed in the order they were entered. Click on **Reorder** button to shuffle your questions, using the function at the top right side of the Edit Questions panel. ![edit-copy-delete-the-question.png](https://e02.insite.com/files/sites/global/9779/edit-copy-delete-the-question.png) -**Note:** When inserting a question, it is placed at the end of the survey by default. You then must scroll to the bottom and drag it to where it is supposed to be. +**Note:** When inserting a question, it is placed at the end of the survey by default. You then must scroll to the bottom and drag it to where it is supposed to be. -**Tip:** Try to Insert before question X, or after question Y. +**Tip:** Try to Insert before question X, or after question Y. diff --git a/topics/surveys/question-configuration/likert-questions.md b/topics/surveys/question-configuration/likert-questions.md index 96aa7d4..124fd9b 100644 --- a/topics/surveys/question-configuration/likert-questions.md +++ b/topics/surveys/question-configuration/likert-questions.md @@ -1,66 +1,75 @@ -# Likert Questions - +--- +description: "Likert question: column Category" +--- + +# Likert Questions + **Likert question: column Category** -Click the Columns tab and enter values, text and scores for your answer fields. +Click the Columns tab and enter values, text and scores for your answer fields. -- Name column headers -- Define associated scores: By entering scores, the system will automatically calculate Mean and Standard Deviation on these answer fields. +* Name column headers +* Define associated scores: By entering scores, the system will automatically calculate Mean and Standard Deviation on these answer fields. The Disable Column Heading Wrap option will force your column header to print in one horizontal row. **Likert question: row Category** -Use Categories on likert rows to group scores for meaningful output. +Use Categories on likert rows to group scores for meaningful output. Decide if your likert analysis applies to the current question only, or multiple previous questions -- Current Question Only: Allows user to define likert feedback for the current question. -- Preceding Question(s) - - All Scales: Allows user to define likert feedback for the preceding questions. This will make the current question hidden; it will only show up for the purpose of feedback on the Survey Review report. Feedback will display for every category defined. - - Preceding Questions, Highest-Point Scale Only: Allows user to define likert feedback for the preceding questions. This will make the current question hidden; it will only show up for the purpose of feedback on the Survey Review report. Feedback will only display for the category that had the highest score. + +* Current Question Only: Allows user to define likert feedback for the current question. +* Preceding Question(s) + * All Scales: Allows user to define likert feedback for the preceding questions. This will make the current question hidden; it will only show up for the purpose of feedback on the Survey Review report. Feedback will display for every category defined. + * Preceding Questions, Highest-Point Scale Only: Allows user to define likert feedback for the preceding questions. This will make the current question hidden; it will only show up for the purpose of feedback on the Survey Review report. Feedback will only display for the category that had the highest score. For example, suppose you have a likert question with 4 rows: What career is good for you? + 1. I enjoy working alone at my own pace [category=Housekeeping] 2. I have experience cleaning outside my own home [category=Housekeeping] 3. I love interacting with people [category=Front Desk] 4. I like telling people about local attractions [category=Front Desk] -Scores for answers on the above questions will be grouped into 2 categories. The system will structure your likert feedback to allow you to enter scores and feedback for both Front Desk and Housekeeping. +Scores for answers on the above questions will be grouped into 2 categories. The system will structure your likert feedback to allow you to enter scores and feedback for both Front Desk and Housekeeping. You can set this up on a single likert question or use the same categories over multiple questions to group data over multiple questions. If you do this option, you will need to insert a likert summary question to configure the feedback. Example 1 Question 1 text - Answer option 1 [Category A] - Answer option 2 [Category A] - Answer option 3 [Category A] + Answer option 1 [Category A] + Answer option 2 [Category A] + Answer option 3 [Category A] Question 2 text - Answer option 1 [Category B] - Answer option 2 [Category B] - Answer option 3 [Category B] + Answer option 1 [Category B] + Answer option 2 [Category B] + Answer option 3 [Category B] Question 3 (select Preceding Questions, All scales) -- Define feedback for Category A and Category B -- This will be hidden to the user, and display it’s feedback on the Survey Review report + +* Define feedback for Category A and Category B +* This will be hidden to the user, and display it’s feedback on the Survey Review report Example 2 Question 1 text - Answer option 1 [Category A] - Answer option 2 [Category A] - Answer option 3 [Category B] - Answer option 4 [Category B] - Answer option 5 [Category C] - Answer option 6 [Category C] -- Define feedback for Categories A, B, & C. -- Feedback on the Survey Review report will summarize A, B, & C right on the current question. + Answer option 1 [Category A] + Answer option 2 [Category A] + Answer option 3 [Category B] + Answer option 4 [Category B] + Answer option 5 [Category C] + Answer option 6 [Category C] + +* Define feedback for Categories A, B, & C. +* Feedback on the Survey Review report will summarize A, B, & C right on the current question. **Enable Branches:** Check the Enable Branches box to set up skip patterns. When skip patterns are in play, the respondents answer to a question will skip them forward to a predetermined place in the survey. Note that branches will not work from inside a nested question, or to a nested question. **Example: Skip to termination** If you want to skip to a terminate survey scenario you have to have: + 1. Question with branches enabled (Edit question, Options panel) -2. Add Page break +2. Add Page break 3. Add Break question with termination text (This is important. Text on a Termination Question will not display) -4. Add termination question +4. Add termination question 5. Add page break -**Please note: Once a Likert Table is created, it is advised not to change the order of the questions or categories within that Likert Table. You would have to delete that Likert Table and recreate the Likert Table with the questions or categories in the order you would like it to be displayed.** +**Please note: Once a Likert Table is created, it is advised not to change the order of the questions or categories within that Likert Table. You would have to delete that Likert Table and recreate the Likert Table with the questions or categories in the order you would like it to be displayed.** diff --git a/topics/surveys/question-configuration/question-types.md b/topics/surveys/question-configuration/question-types.md index 5b9442b..2e04741 100644 --- a/topics/surveys/question-configuration/question-types.md +++ b/topics/surveys/question-configuration/question-types.md @@ -1,27 +1,34 @@ -# Question Types - -Click on the **Questions** tab and then the **Add question** button to start adding questions to the survey. +--- +description: Click on the Questions tab and then the Add question button to start adding questions to the survey. +--- + +# Question Types + +Click on the **Questions** tab and then the **Add question** button to start adding questions to the survey. There are different question types that can be added to a survey: **Quantitative question types** -- **Radio Button List** (single select): questions restrict respondents to a single answer -- **Dropdown Lis**t (single select): questions restrict respondents to a single answer, but use less physical space on the page -- **Check Box List** (multi-select): You cannot use the Answer Required checkbox (currently the Answer Required feature requires (or does not require) answers to all the answer fields in the question. With a multi-select question type, a user can answer some, but not all, which makes this invalid.) You cannot calculate statistics on a check box question type + +* **Radio Button List** (single select): questions restrict respondents to a single answer +* **Dropdown Lis**t (single select): questions restrict respondents to a single answer, but use less physical space on the page +* **Check Box List** (multi-select): You cannot use the Answer Required checkbox (currently the Answer Required feature requires (or does not require) answers to all the answer fields in the question. With a multi-select question type, a user can answer some, but not all, which makes this invalid.) You cannot calculate statistics on a check box question type **Qualitative question types** -- **Comment Box** -- **Date Selector** -- **Number Box** -- **File Upload** + +* **Comment Box** +* **Date Selector** +* **Number Box** +* **File Upload** **Special input controls** -- **Break Question:** insert a question on the survey with no answer options. This is often used to create section headings or provide the respondent with necessary information inline. -- **Break Page:** Inserts a page break into the list of questions -- **Terminate Survey**: triggers the end of the survey. Surveys do not display text written in a terminate survey question box. To enter text to terminate a survey, the user must first put a break question with desired text then an empty Terminate Survey question. + +* **Break Question:** insert a question on the survey with no answer options. This is often used to create section headings or provide the respondent with necessary information inline. +* **Break Page:** Inserts a page break into the list of questions +* **Terminate Survey**: triggers the end of the survey. Surveys do not display text written in a terminate survey question box. To enter text to terminate a survey, the user must first put a break question with desired text then an empty Terminate Survey question. **Points** For quantitative question types, points are usually assigned as 0 for incorrect responses, and 1 for correct responses. Likert question types are more likely to use a scale for rating the answers. **Category** -Categories are used for the purpose of summarizing or grouping output for reports. +Categories are used for the purpose of summarizing or grouping output for reports. diff --git a/topics/surveys/question-configuration/replace-question.md b/topics/surveys/question-configuration/replace-question.md index c347c7c..80b82f1 100644 --- a/topics/surveys/question-configuration/replace-question.md +++ b/topics/surveys/question-configuration/replace-question.md @@ -1,14 +1,18 @@ -# Replacing a Survey Question in an existing Survey - -After a question has been created, you are not able to change the **Question Type**. This is to prevent data loss in case someone has answered the survey already. -If you want to change the **Question Type** of an existing question, you need to delete the original question and then create a new question with the new **Question Type** in its place. +--- +description: After a question has been created, you are not able to change the Question Type. +--- + +# Replacing a Survey Question in an existing Survey + +After a question has been created, you are not able to change the **Question Type**. This is to prevent data loss in case someone has answered the survey already. +If you want to change the **Question Type** of an existing question, you need to delete the original question and then create a new question with the new **Question Type** in its place. ***Note:** Before deleting the existing question, note any attributes it has that you might need to carry forward to your new question (e.g. Settings, Respondent Attribute, Answer Options and Settings). The most important field to take note of is the **Question #**. You need the **Question #** of the **existing** survey question to enter in the **Question #** field of the new replacement question you are creating.* * Identify the Question you want to replace and click on the Edit pencil icon (); * Make note of the Question # (and any other attributes you want to reuse in the new question); -* Create your new question, by clicking on the Add Question button at the top of the page, and add the existing Question # in the new questions Question # field; +* Create your new question, by clicking on the Add Question button at the top of the page, and add the existing Question # in the new questions Question # field; * Add the content for your new Survey Question and click the Save button. * Delete the existing Survey Question you wanted to replace. -**Important Note: Deleting an existing question (or survey answer option) in a Survey will delete any responses associated with that question. Once a survey is active, and a question or answer option needs to be updated/replaced/removed, it is better to create a new Survey.** +**Important Note: Deleting an existing question (or survey answer option) in a Survey will delete any responses associated with that question. Once a survey is active, and a question or answer option needs to be updated/replaced/removed, it is better to create a new Survey.** diff --git a/topics/surveys/question-configuration/terminating-a-survey.md b/topics/surveys/question-configuration/terminating-a-survey.md index fb8d715..c44c8a5 100644 --- a/topics/surveys/question-configuration/terminating-a-survey.md +++ b/topics/surveys/question-configuration/terminating-a-survey.md @@ -1,3 +1,7 @@ +--- +description: Navigate to the Survey Termination options by clicking in the Details panel, choose Terminate Survey as Question Type. Click Save +--- + # Terminating a Survey Navigate to the Survey Termination options by clicking in the Details panel, choose **Terminate Survey** as Question Type. Click **Save** diff --git a/topics/surveys/survey-messages/README.md b/topics/surveys/survey-messages/README.md index 6571fbe..9f4d523 100644 --- a/topics/surveys/survey-messages/README.md +++ b/topics/surveys/survey-messages/README.md @@ -1,2 +1,12 @@ +--- +description: Configure invitations and workflow notifications for survey responses +--- + # Managing survey invitations +Surveys are usually delivered through an invitation message and may also drive workflow notifications as respondents move through them. This section covers both. + +## In this section + +* [Survey Invitation](survey-invitation.md) +* [Workflow Notifications](workflow-notifications.md) diff --git a/topics/surveys/survey-messages/survey-invitation.md b/topics/surveys/survey-messages/survey-invitation.md index 0bc3891..9d7d8c8 100644 --- a/topics/surveys/survey-messages/survey-invitation.md +++ b/topics/surveys/survey-messages/survey-invitation.md @@ -1,3 +1,7 @@ +--- +description: Open the Survey that you want to send the invitation for. +--- + # Survey Invitation ### Create an Invitation from a Survey @@ -7,7 +11,7 @@ * Click on the **Add Invitation** button. * Add the **Internal Name** and **Subject**. * Then select the **Save** button. -* After saving you will be redirected to the **Message Outline** page where you can modify the invitaion's content, under the **Content** tab. **Please note:** Do not remove the {Survey-Link} placeholder that is in the content message content. +* After saving you will be redirected to the **Message Outline** page where you can modify the invitation's content, under the **Content** tab. **Please note:** Do not remove the {Survey-Link} placeholder that is in the content message content. * Under the **Subcribers** tab, add the user you want to send the **Survey Invitation** to. * Add existing contacts to a message individually * Add existing contacts to a message as a group @@ -22,7 +26,7 @@ * Add information into the following fields: * **Survey Form** - A link to this survey must be included in the body of the invitation email. * Add the **Internal Name** and **Subject**. -* Under the **Content** tab, add the\*\* Content\*\* you want included in your **Invitiation**. This will be the body of the message the respondent receives via email. +* Under the **Content** tab, add the\*\* Content\*\* you want included in your **Invitation**. This will be the body of the message the respondent receives via email. * Add Subscribers/Recipients * Add existing contacts to a message individually * Add existing contacts to a message as a group diff --git a/topics/surveys/survey-messages/workflow-notifications.md b/topics/surveys/survey-messages/workflow-notifications.md index 57dae46..fad75b6 100644 --- a/topics/surveys/survey-messages/workflow-notifications.md +++ b/topics/surveys/survey-messages/workflow-notifications.md @@ -1,6 +1,10 @@ -# Workflow Notifications - -In the **Survey**, click on the **Messages** tab, then on the tab you wish to configure a workflow for: +--- +description: "In the Survey, click on the Messages tab, then on the tab you wish to configure a workflow for:" +--- + +# Workflow Notifications + +In the **Survey**, click on the **Messages** tab, then on the tab you wish to configure a workflow for: * **Response Started (Administrator):** A notification is sent to an **Administrator** as soon as a user starts a Survey response. * **Response Completed (Administrator):** A notification is sent to an **Administrator** once a user submits their Survey response. @@ -9,17 +13,20 @@ In the **Survey**, click on the **Messages** tab, then on the tab you wish to co Click on the **Assign Messages** button to assign an **existing** notification or **Add Notification** to create a **new** notification. **Assign Messages** button: -* Under the **Email Notifications** heading, select an existing notification for each of the above workflows. + +* Under the **Email Notifications** heading, select an existing notification for each of the above workflows. **Add Notification** button: + * Click on the **Add Notification** button. * Add the **Internal Name** and **Subject**. * Then select the **Save** button. * After saving you will be redirected to the **Message Outline** page where you can modify the notification's content, under the **Content** tab. **Placeholders** that work with **Survey Workflow Notifications**: + * **$UserFullName** - Full Name of person who starts/completes a response * **$UserEmail** - Email of person who starts/completes a response * **$SurveyFormName** - Internal name of the Survey that was started/completed * [**$UserFullName**](https://**Your Org**.insite.com/ui/admin/contacts/people/edit?contact=$UserIdentifier) - use to create a hyperlink to the respondent's contact record (use on Administrator workflows only) -* [**Review Your Response**](https://**Your Org**.insite.com/ui/survey/respond/search) - use to create a hyperlink for the respondent to log in to their portal and see/review/resume all of their survey responses (use on Response Completed (Respondent) only) +* [**Review Your Response**](https://**Your Org**.insite.com/ui/survey/respond/search) - use to create a hyperlink for the respondent to log in to their portal and see/review/resume all of their survey responses (use on Response Completed (Respondent) only) diff --git a/topics/surveys/survey-responses/README.md b/topics/surveys/survey-responses/README.md index 0adf89c..62a602e 100644 --- a/topics/surveys/survey-responses/README.md +++ b/topics/surveys/survey-responses/README.md @@ -1,2 +1,15 @@ +--- +description: >- + Search, view, download, and report on responses submitted to survey forms +--- + # Managing survey responses +Once respondents submit a survey, this section covers searching, viewing, downloading, and reporting on the responses. + +## In this section + +* [Search Responses](search-responses.md) +* [View Responses](view-responses.md) +* [Download Responses](download-responses.md) +* [Survey Reporting](survey-reporting.md) diff --git a/topics/surveys/survey-responses/download-responses.md b/topics/surveys/survey-responses/download-responses.md index ebc8502..ae1afd6 100644 --- a/topics/surveys/survey-responses/download-responses.md +++ b/topics/surveys/survey-responses/download-responses.md @@ -1,5 +1,9 @@ -# Download Responses - +--- +description: Download an individual survey response as a PDF from the response review page +--- + +# Download Responses + When reviewing a users survey response, you are able to download a *.pdf copy of the users response by clicking on the **Download** button under the **Respondent Answers** heading. -If you want to download an aggregate of all survey responses, please see [**Survey Reporting**](/ui/help/portal/surveys/survey-reporting) +If you want to download an aggregate of all survey responses, please see [**Survey Reporting**](/ui/help/portal/surveys/survey-reporting) diff --git a/topics/surveys/survey-responses/search-responses.md b/topics/surveys/survey-responses/search-responses.md index ee9f4f5..ebb7d3b 100644 --- a/topics/surveys/survey-responses/search-responses.md +++ b/topics/surveys/survey-responses/search-responses.md @@ -1,9 +1,13 @@ +--- +description: To search for existing Survey Responses, select the Surveys Toolkit and then click on the Responses counter. +--- + # Search Responses To search for existing **Survey Responses**, select the **Surveys** Toolkit and then click on the **Responses** counter. -Under the **Criteria** tab, click on the **Clear** button to remove any previous search citeria you have used. Fill in the search criterias you would like to use to search for the existing Survey and click on **Filter**. +Under the **Criteria** tab, click on the **Clear** button to remove any previous search citeria you have used. Fill in the search criteria you would like to use to search for the existing Survey and click on **Filter**. The results for your search will be available to view under the **Results** tab. -Use the Downloads tab to download a csv or xlxs spreadsheet of your results. +Use the Downloads tab to download a csv or xlsx spreadsheet of your results. diff --git a/topics/surveys/survey-responses/survey-reporting.md b/topics/surveys/survey-responses/survey-reporting.md index bc3179e..98f205e 100644 --- a/topics/surveys/survey-responses/survey-reporting.md +++ b/topics/surveys/survey-responses/survey-reporting.md @@ -1,21 +1,29 @@ -# Survey Reporting - -Once your survey has responses, you can review the aggregate results in Survey Reports. Access the Survey **Report** on the **Survey Results** search screen (graph icon at the end of each line in the results) or when looking at the survey itself by clicking on the **Reports** button. +--- +description: Once your survey has responses, you can review the aggregate results in Survey Reports. +--- + +# Survey Reporting + +Once your survey has responses, you can review the aggregate results in Survey Reports. Access the Survey **Report** on the **Survey Results** search screen (graph icon at the end of each line in the results) or when looking at the survey itself by clicking on the **Reports** button. ### Analyzing Responses (Frequency Distribution Analysis panel) + When you open the report, it first diplays the **Frequency Distribution Analysis** panel, which contains a visual representation for the distribution of all completed answers within the survey, even if a respondent didn't finish and submit their response. Click on the **Print** button here if you want to print the distribution analysis of the answers. This will open the visual representation in a new tab (you may need to **allow** popups and redirects for our site on your browser for this new tab to open). To get a print out or print to pdf of this distribution analysis, right click anywhere on the page and follow your browser's options. Note that Mean and Standard Deviation will only show for questions that have been configured with a scoring scale. Likert Questions are a good example of this. You can also filter your respones in a variety of ways using options in the **Reports** panel, above the **Frequency Distribution Analysis** panel. Options include: -- Filtering by quantitative (aggregated responses, relative % of total, histogram) or qualitative (text answers, comments) response types. -- Filtering by individual survey questions. Stack filters for more targeted reporting. -- Filtering by submission date range. -- Filtering by a specific group of respondants. + +* Filtering by quantitative (aggregated responses, relative % of total, histogram) or qualitative (text answers, comments) response types. +* Filtering by individual survey questions. Stack filters for more targeted reporting. +* Filtering by submission date range. +* Filtering by a specific group of respondants. ### Report Panel + In addition to filtering criteria for the **Frequency Distribution Analysis** results, the following options are available in the Report panel: **Correlation Analysis** Shift iQ allows you to manipulate your data to identify the strength of a relationship between two variables. Set data across the x and y axis to view correlations between answer fields. + 1. Open up the **Correlation Analysis** tab of the **Report** panel to configure the report you'd like to view 1. Choose a question to represent the X-axis. The title field will appear as your X-axis label. Click the **Add Variable** button. 1. Choose a question to represent the X-axis. The title field will appear as your X-axis label. Click the **Add Variable** button. @@ -24,12 +32,14 @@ Shift iQ allows you to manipulate your data to identify the strength of a relati **Download Results** On the **Download Report** tab, you can download a zip file containing .csv spreadsheet files for the entire survey; including Answers, Choices, Questions, Respondents and the Survey Data Set, (if you opt for the additional Meta Data files). The Default settings (recommended) on this panel are best if you just need to analyze your data in a spreadsheet. If you need to do analysis or comparison on survey results (pivot tables, for example) you may want to encode answer options as numbers. UTF-8 text encoding is generally suitable for most surveys; Unicode is recommended if your survey has other languages with Cyrillic characters, for example. - ### Time Series Analysis Panel + Time Series Analysis enables an admin to view survey response activity over time. ### Survey Invitation Analytics Panel -This panel shows the response rate of survey invitations that have been sent out via the **Messages** toolkit to unique users. It doesn't show results if a survey is shared via a generic link rather than an invitation. Clicking on any of the hyperlinked numbers on this panel will download a report of the respondents or deliveries in question. + +This panel shows the response rate of survey invitations that have been sent out via the **Messages** toolkit to unique users. It doesn't show results if a survey is shared via a generic link rather than an invitation. Clicking on any of the hyperlinked numbers on this panel will download a report of the respondents or deliveries in question. ### Submitted Responses Panel -View individual survey responses on the Submitted Responses panel, using the magnifying glass at the end of each line. Note the lock icon; when a response has been completed (submitted or confirmed) they will show as locked, and partially completed responses will show as unlocked. Admins can unlock a locked response and vise versa by clicking this icon; respondents can edit/continue an unlocked response but can only review their submission to locked respones. When a survey is unlocked, the survey respondent will be able to resume the survey and re-submit it later. + +View individual survey responses on the Submitted Responses panel, using the magnifying glass at the end of each line. Note the lock icon; when a response has been completed (submitted or confirmed) they will show as locked, and partially completed responses will show as unlocked. Admins can unlock a locked response and vise versa by clicking this icon; respondents can edit/continue an unlocked response but can only review their submission to locked respones. When a survey is unlocked, the survey respondent will be able to resume the survey and re-submit it later. diff --git a/topics/surveys/survey-responses/view-responses.md b/topics/surveys/survey-responses/view-responses.md index 57283a9..f53c95f 100644 --- a/topics/surveys/survey-responses/view-responses.md +++ b/topics/surveys/survey-responses/view-responses.md @@ -1,3 +1,7 @@ +--- +description: "On the Results tab, click on the Magnifying Glass () at the front of any row to view that survey response." +--- + # View Responses On the Results tab, click on the Magnifying Glass () at the front of any row to view that survey response. (The magnifying glass will not be available for any responses to surveys where confidentiality has been enabled.)