Kestrel

Part 5. Administration

5.7 Connections

Version 1.0 ·Updated 2026-10-07

Next reviewed by 2027-04-07.

Written for a school's staff learning how Kestrel works, the trainers who teach them, and the families using the portal.

Message templates, the portal's policy, API tokens, roster feeds, the timetabling tool, webhooks, asking the record questions and the Microsoft 365 screen.

Written forITRegistrarBusiness managerPrincipal and executive

What this group is for

The group "Forms and connections" covers what Kestrel says to families and what it shares with other systems. The screens here are the wording of messages, the portal's policy, and the credentials other tools use to read from or write to Kestrel. Most of them show a secret once, when it is made, so take a copy at that moment.

Who uses it

The IT administrator owns the connection screens, which need the capability to read and manage plug-ins and connections. The registrar writes message templates. The principal decides the portal policy and whether staff may ask the record questions.

Key ideas

Message template
The wording of a message, with placeholders that fill from the record. Publishing makes the next version.
Scope
One thing a token may do. Each scope on the token screen comes with a sentence saying what it allows.
Shown once
A secret appears when it is made and is never shown again. If it is lost, revoke the credential and issue another.
Webhook
An address Kestrel posts to when a kind of change happens, signed so the receiver can check it came from Kestrel.

Screens

  • Message templates

    /app/settings/templates

    The wording of each message Kestrel sends.

  • Portal

    /app/settings/portal

    What families and students may see, the school's links and the acceptable use policy.

  • API tokens

    /app/settings/tokens

    Tokens for tools that read or write Kestrel.

  • Rostering

    /app/settings/rostering

    Systems that read Kestrel's class rosters, such as Wonde and School Data Sync.

  • LISS

    /app/settings/liss

    A credential for a timetabling tool such as Edval.

  • Webhooks

    /app/settings/webhooks

    Addresses Kestrel posts to when records change.

  • Ask the record

    /app/settings/questions

    Whether staff may ask questions of the record in plain words.

  • Microsoft 365

    /app/settings/microsoft-365

    Connect the school’s Microsoft 365 tenant, choose the staff group and check its Exchange scope.

Message templates and the portal

A message template has a Name, its Channels, a Tier ("The highest tier a message from this template may be sent at"), "Kept under" a retention class, a Subject line and a Body with placeholders. Tick "From the author's mailbox" to let a message from it go from the sender's own Microsoft 365 mailbox. Choose "Publish" to make the next version.

The Portal screen has a group for Families, with a section for each audience, and one for Students, where everything starts off. "School links" are the links shown in the portal. The "Acceptable use policy" has a Heading and "The policy", and "Publish" makes it current. A rewrite asks each student to agree again, and a corrected word does not.

API tokens

  1. Open "API tokens" and say "What it is for".
  2. Choose "How long it lasts" in days.
  3. Tick the scopes it needs. Read the sentence beside each that says what it lets the tool do.
  4. Create it, then choose "Copy the secret". It is shown once.
  5. To end it, choose "Revoke".

Rostering, LISS and webhooks

On "Rostering", register a source: Wonde, School Data Sync or another reader of the OneRoster standard. Give a System, a Name and a "Sign-in name". The credential is shown once and lasts a year. The screen also offers the roster files to save.

On "LISS", choose "Issue a credential" and name the tool, such as Edval. The password is shown once and expires in two years. If it is lost, revoke it and issue another.

On "Webhooks", give a Name, an Address that begins with https, the "Kinds of change" to send and the "API token" the receiver may use. Use "Send a test post" to try it. The Log shows each delivery. Kestrel signs each post with a Kestrel-Signature header, and the signing secret is shown once. A failed post is retried up to the thirteenth attempt. "Revoke" ends the webhook.

Ask the record

This screen switches on whether staff may ask questions of the record in plain words. It also sets the Provider and Region. Each person sees only the records they may already read, and an answer shows up to 500 rows.

Microsoft 365

An Entra administrator connects the school’s tenant from Settings → Microsoft 365 and grants directory reads only. Choose and save the staff group, then copy the Exchange setup script for an Exchange administrator to run. Run the check after Exchange has applied the scope; changes can take up to two hours. The staff list shows accounts linked through their staff identity and each person’s own sync switch.

The connection is unavailable until the deployment has a Microsoft application configured. Sync eligibility requires a passing scope check and each member of staff opting in from their account. A message a member of staff composes goes from their own mailbox once they have opted in, and is saved to their Sent Items. If Microsoft refuses it, it goes from the school’s address instead. Kestrel also writes the lessons, duties and meetings they see in their calendar for the next four weeks to Outlook. Disconnect removes Kestrel’s connection; the school’s administrators remove the grants in Entra and Exchange separately.

Once the tenant is connected, choose Download the manifest under Kestrel for Outlook. A Microsoft 365 administrator uploads that package in the Microsoft 365 admin centre under Settings → Integrated apps and chooses the staff who get it. Those staff then see File to Kestrel in Outlook on the web and supported versions of Windows when they read an email or open a meeting. It files the one item they have open, with the attachments they tick, to a student they choose, and Kestrel is given no mailbox permission for it. A school that requires a passkey cannot use the add-in, because Outlook’s sign-in cannot show one.

Tasks

Journeys that use this chapter

Settings

The choices here are the wording and tier of each message, the portal sections each audience sees, the policy students agree to, each credential's scopes and lifetime, and each webhook's address and kinds of change.

Training notes

  • Rehearse the shown-once rule with a test token before anyone makes a real one.
  • Give each token the fewest scopes it needs and a short life.
  • Explain that each member of staff controls their own Microsoft 365 switch, that it sends their messages to families from their own mailbox, and that calendar writes are not available yet.