# Part 1 · Settings

## 1.1 Changing a setting for the workspace

**Who** · `Admin` `Owner` · whoever holds "Change the workspace's settings" (`setting.manage`).

**Where** · **Settings** › the pen beside the setting.

**Before you start** · The value you want. The page says what the workspace may choose and what it would use instead.

**The steps**
1. Choose or type the value. A number carries its unit; a short choice is a row of answers.
2. Or tick **Use the platform's value from now on** to go back to following the platform.
3. Press **Save changes**. The setting's page opens, showing where the value now comes from.

**What the record shows** · The audit log keeps the setting, the value before and after, and who changed it
(`setting.changed`, `setting.followed`).

**Who is told** · Nobody. Everyone in the workspace who hasn't chosen their own uses the new value from their next page.

**What can go wrong**
- *"Choose one of the answers offered."* The Service narrowed what workspaces may choose (1.4).
- *"… can be 1 to 30 tries a minute."* A number outside the range; the message gives it.
- *The workspace's value is in force but shows "held".* The Service narrowed the range after you chose: your choice is
  kept and applies again if the range widens.

## 1.2 Seeing where a value comes from

**Who** · Anyone who can open a Settings page: `setting.view` for the workspace's, everyone for **Your settings**, the
Service for **Platform settings**.

**Where** · Any Settings page › the route icon beside a setting, or its name.

**Before you start** · Nothing.

**The steps**
1. Read the levels from the top: the shipped default, the platform, the workspace, each person, and an exception if
   there is one.
2. The one ticked is in force. One crossed out was overridden by a level below. "Not set: uses the level above" is a
   level that may set it and hasn't; a faded one doesn't set this setting at all.
3. Each set level says who set it and when. The Service is named as the product's support, never by name.

**What the record shows** · Nothing; reading changes nothing.

**Who is told** · Nobody.

**What can go wrong** · Nothing.

## 1.3 Choosing your own

**Who** · Everyone signed in.

**Where** · The menu under your name › **Your settings** › the pen.

**Before you start** · Only settings a person may set are here (today: rows per page).

**The steps**
1. Choose the value, or tick **Use your workspace's value from now on**.
2. Press **Save changes**.

**What the record shows** · The audit log keeps the change, with no workspace on it: your choice is yours in every
workspace you belong to.

**Who is told** · Nobody.

**What can go wrong**
- *Your value isn't what you chose.* It is held within the range the platform allows; the trace says "held".
- *The page refuses inside a lens.* The Service's own settings are closed while it looks into a workspace.

## 1.4 Changing the platform's value, and what workspaces may choose (Service)

**Who** · `Service` · the platform's owner, outside any lens.

**Where** · **Platform settings** › the pen beside the setting.

**Before you start** · Every setting is here, the platform-only ones too (security, the lens, exceptions).

**The steps**
1. Type or choose the value for everyone, and press **Save changes**. Saving the shipped default again keeps no value
   of the platform's own, so a later release's default applies.
2. For a setting a workspace or a person may set, **What the levels below may choose** gives the range (a number's
   lowest and highest) or the answers offered. Press **Save the range**.

**What the record shows** · The audit log keeps each change (`setting.changed`, `setting.range_changed`), with no
workspace on it.

**Who is told** · Nobody. Workspaces and people that chose a value outside the new range are held within it on their
next page; their choices are kept.

**What can go wrong**
- *"… can be 100 to 10,000 rows."* The hard bounds, which nobody passes, not even an exception.
- *The sign-in limiter counts a new figure at once.* The next tries count against the new value.

## 1.5 Giving a workspace an exception (Service)

**Who** · `Service`.

**Where** · **Platform settings** › the setting (only one marked as allowing exceptions: today, **Export at once**) ›
**Give an exception**. All of them are listed under **Platform settings** › **Exceptions**.

**Before you start** · The workspace, the value, the last day it applies (at most the **Longest exception** from
today, 90 days as shipped) and why.

**The steps**
1. Choose the workspace, the value and the day it ends; say why.
2. Press **Save changes**. The exception applies at once, above every other level.
3. To change it, press its pen in **Exceptions**; to end it now, its bin.

**What the record shows** · The audit log keeps each exception given, changed, ended or expired, with the workspace
and the reason. A setting no workspace sees is logged as the platform's alone, so the workspace's log never names it.

**Who is told** · Nobody yet: the notice before an exception ends comes with the mail engine (S7) and the bell (S14).

**What can go wrong**
- *"… already has an exception for this setting."* One at a time per workspace: change that one.
- *"The exception ends between today and …"* The day is past or beyond the longest allowed.
- *It ended by itself.* At its day the read stops using it; the daily `settings:exceptions` round removes it into the
  audit log (`setting.exception_expired`).

## 1.6 Why a setting isn't on your page

**Who** · Anyone.

**Where** · Any Settings page.

**Before you start** · Nothing.

**The steps**
1. A workspace's **Settings** lists only what a workspace may set. Security controls (sign-in attempts), the lens and
   exceptions are the platform's only, and never shown to a workspace.
2. **Your settings** lists only what a person may set.
3. A setting the app doesn't read yet isn't in the catalogue at all; each slice adds the settings its code reads.

**What the record shows** · Nothing.

**Who is told** · Nobody.

**What can go wrong**
- *A link to a platform-only setting from a workspace says "not found".* On purpose: a workspace never reaches one,
  whatever address is typed.

## 1.7 Your own web addresses

**Who** · `Owner`, `Admin` · anyone who may manage the organisation's addresses (`domain.manage`).

**Where** · **Settings** › **Web addresses**.

**Before you start** · A subdomain of a domain the organisation owns, such as `portal.yourschool.edu.gh`, and access to
where that domain's records are managed.

**The steps**
1. Type the address, choose the product it opens (if you run more than one), and press **Add an address**.
2. Add the one record the page shows where your domain is managed: a CNAME from your address to the product's own
   address for you, such as `portal → jis.tutecampus.app`.
3. Wait: it's looked up every few minutes. Or press **Check again**. Once found it says **Verified**, and the product
   opens there.
4. To stop, press the bin: the product stops opening there at once; its own addresses keep working.

**What the record shows** · The audit log: `domain.added`, each look-up, `domain.removed`.

**Who is told** · The product the address opens, by webhook (`domain.changed`), when it starts or stops opening there.
Your other products hear nothing of it.

**What can go wrong**
- *"Use a subdomain."* A bare domain such as `yourschool.edu.gh` can't be pointed at a product.
- *"… already opens TuteCampus."* One address opens one product: use another name, or stop using it there first.
- *"Another organisation already uses that address."* It's theirs on the platform.
- *It stays "Waiting for its record".* Check the record's name and target exactly; changes can take a while to spread.

## 1.8 Your products

**Who** · Anyone who may see Settings; `Owner`, `Admin` add one (`product.add`).

**Where** · **Products**, in the menu.

**Before you start** · Nothing.

**The steps**
1. Each product it runs shows its plan, its addresses and how many people signed in to it in the last 30 days; **Open**
   goes there.
2. Under **Fits with how … works**, press **Add to …** on a product made for organisations like yours.
3. Keep the short name offered (the one it uses on its other products, when free) or type another; add its own address now
   or leave it; press **Add …**. It starts on Free.

**What the record shows** · Its plan (`entitlement`) and address (`instance`).

**Who is told** · The product, by webhook (`entitlement.granted`), which sets the organisation up.

**What can go wrong**
- *"Another organisation has that short name on …"* Try another.
- *Its own address wasn't added.* The product is running; add the address again under Web addresses.