User guide

This guide describes what you can do in Heimdall UI and how to do it. It follows the UI’s own Use Case Specification Document: each task is one use case, named UI-01 to UI-30, with the steps of its main flow and the notable things that can go differently. Every use case appears once, on the page for its group.

You need a running Heimdall API and UI first. The Installation page covers both. The terms used here (scope, role, person, application, permission) are explained in the Overview.

The pages of this guide

Who can reach what

What the UI shows follows the role in your session. There are three roles, and a fourth case, a restricted session, that is described on its own page. The Architecture page has a diagram of the same rules.

“Not offered” means the screen or control is hidden, or a screen says it is not available for your role. “Owned scopes only” means the screen works for the scopes you own; asking for another scope shows a “Not available for your role” panel.

Screens outside the use cases

Three screens belong to no numbered use case but are part of what you see.

• Home is the first screen after you sign in. Everyone sees their own account there: the address and whether it is verified, whether two-factor authentication is on, and the role. A System Admin or Scope Admin also sees an overview of the scopes they administer, such as how many there are and how many Users, applications, permissions and Google users they hold, summed over the first ten scopes.
• Privacy notice at /privacy shows the Heimdall API’s own Privacy Notice. Anyone can open it, signed in or not, and a restricted session may open it too.
• Health shows whether the API is reachable. A System Admin gets the full report, a Scope Admin gets a read-only view, and a User does not see it.

Things that work the same everywhere

• Errors come from the API. When a request is refused, the UI shows the messages the API returned, next to the field they name or in a banner when no field is named. The API is the only authority; the UI hides what your role cannot use, but it never grants anything.
• Records are read-only until you press Edit. On the profile and on the scope, person, application and permission detail screens, the fields open for editing only after Edit. Editing offers Cancel, which puts back what the API holds, and Save changes, which stays disabled until something differs. If you may not change a record, Edit is not offered.
• Deleting asks first. Every deletion opens a confirmation that names the record. A permanent deletion also asks you to type the record’s name before the confirm button works; for a person or a Google user you type the email address.
• Listings show cards on a narrow window and a table on a wide one. They have a search field, an Include deleted switch and paging. Changing the search or the switch returns to the first page. An empty listing tells “nothing yet” apart from “nothing matches your search”.
• Leaving unsaved work asks first. A form you have changed asks before you discard it.

What the UI does not cover

The UI covers the use cases listed above. A few API capabilities have no UI and are done through the API. The first three rows below are missing from the copy of the API specification the UI is built from (API 1.4.0 has 61 operations, the copy has 58). For the other rows the UI has no screen that calls them.

Use the API’s API reference for who may call each one and what it expects, or the API Explorer to read their request and response shapes (it does not send requests). Note that the restricted-session screen can lift a restriction (UC-45), download your data (UC-41) and request erasure (UC-42), but cannot impose a restriction in the first place; that is UC-44, above.

The source of this guide is the UI’s Use Case Specification Document and its System Requirements Document. Where the screens differ from the specification, this guide describes the screens.