Run skills in your house

Available now A skill is a specification; an

executor, a vendor's app, runs it. Your house decides which skills run, with your values, and on which vendor's executor. Everything here happens on the portal's Your house: skills page, in your publisher workspace.

How it works

1. A vendor connects its executor into your house as a skill app, and you grant it the message types it needs, as for any vendor connection. The vendor declares which library skills its app implements. A skill app's connection only receives: it should receive at least story.context. To publish its warnings, the same vendor connects a producer app too, and you grant that connection skill.warning.raised.
2. You register a configured instance: a skill from the SOM skill library (0.2.2), an instance label and the skill's values. For a skill that compares authorities, you also give your house's authority scale.
3. You bind it to the executor, one whose app declares the skill at that version. The executor reads its registrations from the bus with its own credential, and runs them. It sees only the configured instances bound to its connection, never another vendor's.
4. You see the chain: which executor runs each skill, which of the skill's trigger message types it's subscribed to, who in your house publishes them, and which of the vendor's connections may publish its warnings.

Owners and admins of your workspace register, bind, change, pause, restore and remove. Developers and viewers see the page, and each configured instance's history.

To see skill warnings on a story before you register anything, play the demo newsroom: its raise-flag-on-match instances are evaluated live by HyperContent's reference executor, and its other skills are scripted and labelled so.

Register a configured instance

Field	What it is
Skill	One of the library's eleven skills, at the library's current version (0.2.2, the only version on the bus today). See the skill library catalogue and Library versions and upgrades
Instance label	Your name for this configured instance, unique in your house: lowercase letters, digits, dots, hyphens or underscores. It becomes the rule_id on every warning it raises
Values	The fields of the skill's configuration, as its skill file describes them. The page lists them, with which are required
Authority scale	Your house's authority levels, most senior first, for example editor-in-chief, duty-editor, producer. A clearance counts when it comes from the declaring level or above; a level not on your list ranks below it, so a declaration stands. Required for skills that compare authorities, and every authority you name in the values must be on it
Executor	Optional: bind it now, or later. Only executors whose app declares the skill at this version are offered

The bus checks the values when you register: a field the skill doesn't have is refused, so a typo can't fall back to a default silently, and every field that names a place in the story (such as match_field or watched_field) must be a field of SOM 1.0's story.context, for example lifecycle.phase or tags[].value.

A house has at most 50 configured instances.

Which configured instances run on a story

Values always come from your registration: a story can't carry them. A story can still say which skills are active on it, in its skills_config.active_skills:

• A story without skills_config gets every configured instance you registered.
• A story with skills_config gets only those whose skill is listed in its active_skills. An empty list means none.
• If the story lists a skill at another version than the one you registered, that configured instance doesn't run on that story.

This is HyperContent position P-04. Keep it in mind for hold skills: a story that leaves a hold skill out of its list switches that hold off for itself.

Change, rebind or remove

• Edit values changes the values or the authority scale. The configured instance's revision goes up, and the executor picks up the new values at its next read.
• Bind moves it to another executor, or Unbind stops it running anywhere without losing its values. The bus binds a configured instance only to an executor whose app declares its skill at its version; any other is refused with house.skill_not_implemented. If none of your executors declares it, ask the vendor to declare it on its app.
• Remove stops it for good: the executor stops running it at its next read, and it raises no more warnings. Warnings it already raised stay in your story timeline. Its instance label is free again.

If you disconnect a vendor's executor, the configured instances bound to it show Executor disconnected until you bind them to another.

Configured instances bound before vendors declared their apps' skills stay bound and keep running. The chain shows Not declared beside them until the vendor declares the skill, and Not declared for this skill if the vendor's app declares others.

To change many at once, or copy your skills to another house, use Export as file and Import from file: you see the plan before anything changes. See Skills as a file.

Pause and resume

Pause stops a configured instance without losing anything: it keeps its values and its executor, and shows Paused. From its next read, the executor no longer gets it, so it raises no more warnings, and it runs on no story whatever the story's skills_config says. Resume brings it back as it was: the same values, bound to the same executor, which picks it up at its next read.

Use it for a skill that's raising warnings you don't want for now, during an incident or while you rethink its values. Unbinding stops it too, but then you have to choose its executor again.

You can still change the values of a paused configured instance, or bind it elsewhere: it stays paused until you resume it. Pausing and resuming each count as a change, so the revision goes up. When your house is exported, a paused configured instance goes with paused: true.

History and restore

Every change to a configured instance is a new revision: registering it, changing its values or authority scale, binding or unbinding it, pausing or resuming it, restoring an earlier revision, and upgrading it to a new library version. History on each configured instance lists its revisions, newest first, with:

• What changed: each field that differs from the revision before, such as values.match_value, authority_scale, connection_id (the executor) or paused, with its value before and after.
• Who and when: the member who made the change, while they are still a member of your workspace, and the time.

The last 50 revisions of each configured instance are kept, the current one included. Revisions made before history was kept aren't in it: it starts at the first change after that.

Restore on an earlier revision brings back that revision's values and authority scale, as a new revision. The executor picks them up at its next read. The binding and whether it's paused stay as they are now: bind, pause or resume for those. The bus checks the restored values again, as it does any change, and refuses a revision that no longer passes.

Owners and admins restore. If someone else changed the configured instance since you opened it, the change is refused: reload and try again.

When you remove a configured instance, its history goes with it.

Library versions and upgrades

The bus can carry more than one version of the SOM skill library side by side. Today it carries one, 0.2.2, so there is nothing to upgrade yet: this is how it works when a new library version is added.

Each library version the bus carries has a status:

Status	What it means
current	Exactly one version. New configured instances register at it
supported	An earlier version. Configured instances on it keep running, and you can change, bind, pause or restore them as usual
retired	An earlier version on its way out. Configured instances on it keep running as they are, and you can pause, resume, unbind, upgrade or remove them, but not change their values, restore a revision or bind them to an executor (refused with skill.version_retired)

A configured instance keeps the version it was registered at until you upgrade it. Its executor reads it at that version, and a story's skills_config.active_skills is compared with that version, so a new library version never changes a running configured instance by itself.

When a newer version is current, each configured instance on an older one shows Upgrade to that version. Owners and admins open it to see the plan first; nothing changes until they confirm:

• What differs: each config field of the skill that is new, removed, or changed (its kind, whether it's required, or its options).
• What carries over: each of your values whose field is still there and still passes the new version's checks. A value that doesn't carry over is listed with the reason.
• What it needs: each required field of the new version with no value yet. You give those values, and your authority scale if the new version compares authorities and the configured instance has none.

Upgrade writes a new revision at the new version. The configured instance keeps its id, its instance label (so its warnings keep the same rule_id), its executor and whether it's paused. Its history records the upgrade, with the version and each value that changed, and your audit log records it (house.skill_upgraded). A vendor's audit log records it too, as your organisation, without the values. A restore stays on the configured instance's current version: after an upgrade, revisions from before it can't be restored.

If the configured instance is bound and running, its executor's app must declare the skill at the new version, or the upgrade is refused with house.skill_not_implemented. Ask the vendor to declare it, bind an executor that does, or pause the configured instance first: an unbound or paused one upgrades whatever its executor declares; resuming it is refused (house.skill_not_implemented) until its executor's app declares the new version, or you bind it to one that does.

A skills file doesn't move a configured instance to another version: an entry with no skill_version keeps the one its configured instance has, a new entry registers at the current version, and an entry naming another version for a registered instance is a problem in the plan. Upgrade on the page instead.

The same through the API, as an owner or admin (both take the configured instance's current revision):

Method and path	What it does
POST /api/house/skills/{id}/upgrade/plan	The plan: fields, carried, dropped, needed, and the executor with whether its app declares the new version. Writes nothing
POST /api/house/skills/{id}/upgrade	The upgrade: { "values": { … }, "revision": 4 }, with the values the plan's needed asks for (and any others you change)

Is it running

A skill that runs quietly and a skill that doesn't run at all look the same: no warnings. So each configured instance on Your house: skills also shows:

Shown	What it tells you
Last read by its executor	When its executor last read its skills from the bus. An executor reads them at startup and at least every 5 minutes, so this is recent while it runs. The bus records it to within a few minutes
Warnings, last 7 days	How many skill.warning.raised messages your house accepted with this instance's label as rule_id in the last 7 days, and the latest one's time, severity and story, which links to the story timeline
State	Running: its executor read its skills lately. Waiting for its executor: bound, but its executor hasn't read its skills yet. Executor silent: its executor hasn't read its skills for your chosen hours. Executor disconnected: that connection is no longer in your house. Not bound: no executor runs it. Paused: you paused it; no email is sent about it while it's paused

Warnings a rehearsal, a stand-in or the demo newsroom raises never count here: only those from the connections in your house.

Few or no warnings from a running instance is normal: a skill only raises one when its condition holds. An instance whose executor is silent raises none at all, however often the condition holds.

Emails

Your house gets a House skills notification email when:

• an executor bound to your configured instances hasn't read its skills for 24 hours (you can choose 1 to 168 hours under Notifications). An executor that has never read them gets that long from when you bound it. One email per silence, listing the configured instances it runs; if it reads again and then stops again, you hear again;
• an executor running your configured instances is no longer connected;
• configured instances have been bound to no executor for those hours, in one email listing them.

The vendor whose executor went silent hears about it too, from its own vendor workspace, by its own chosen hours. It isn't told about your unbound instances or your other vendors.

Who sees what

Your registrations are your house's configuration: every member of your workspace sees them. A vendor's executor reads the configured instances bound to it, with their values, and nothing else. When you bind one to a vendor's executor, or unbind, pause, resume or remove it, the vendor's audit log records it, as your organisation, without the values. The vendor also sees, on its Where your skills run page, which of your configured instances are bound to its executors (label, skill, version, status, when bound), never their values or your authority scale. A configured instance's history stays with your house: a vendor never sees it. See Who sees what in a house.

When you export your house as a bus config, every active configured instance goes with it, values included.

For the executor's side, see Registrations in the executor contract.