Skip to content

Screenplay extensions: systems, abilities and extension packages

A model often has to reach something it does not own: a carrier that books a pickup, a payment provider, a chat tool where someone approves a request. Screenplay keeps that reach declarative. The model says what the business can ask and what can come back. An extension is the code that does it, and it is chosen outside the model.

This page explains how the pieces fit and points to the page that owns each one. Start here when you think “I need Screenplay to talk to X” and follow the links.

Term Meaning
System A named external system the business can ask for something. See Systems and abilities.
Ability One typed thing a system can be asked to do: inputs, optional returned values, named outcomes and an effect class.
Outcome A named business result other than success, such as a refusal the external system gives.
Effect class safe, idempotent or once: what a retry may do when an attempt’s result is unknown.
Extension The realization of a system: the code and assets that carry its abilities out.
Extension package The distributable unit of an extension. Its contract.play declares what it contributes. See Extension contracts.
Invocation One durable request to perform an ability, with an identity of its own.
Activation When an extension’s backend starts and stops.
Placeholder The static HTML that design tools draw in place of an extension’s component.
Lock screenplay.lock, which pins every extension reference to an exact release.

The glossary holds one line for each.

A reaction, a workflow action and a state’s entering line all ask a system for an ability with invokes <System>.<Ability>. The dotted name tells an ability from a command. Each input is mapped once, and the answer is handled where the call is made, with on returned, one branch per declared outcome and on failed. See Invoke an ability, and reactions, workflows and state machines for the places it appears.

invokes replaced the older sends in workflows, state machines and specifications. Operation phases that invoke an ability are covered in Operations and external systems. A command written in C# invokes abilities through Arc’s operations.

An invocation’s result is never turned into an event implicitly. The branch says which event records which outcome.

Inline code that only computes may run anywhere and any number of times. Anything with an external effect goes through an ability, so it gets an identity, an idempotency key, retries, a recorded outcome and a place in specifications. This is the reason the effect class is part of the declaration, and once is the default: it is the only class that is never wrong. See Choose the effect class.

Stage runs every ability invocation as a persisted message through Choreography, on the Orleans silo it already hosts. In short:

  1. The invocation is recorded with its cause before any work starts, so it is never held only in memory.
  2. One run handles the invocation, keyed by its identity, so asking twice does not call the system twice. The run pins the locked package digest, so upgrading an extension never changes an invocation in flight.
  3. Deployment limits on concurrent calls apply, then the extension is called.
  4. The outcome is recorded and handed back to the behavior that asked.

once abilities are never retried after an attempt that may have reached the system. They stop for reconciliation. An ability that answers later suspends its run until the answer arrives. The owning pages are Stage’s Durable ability invocations and Choreography’s answers that arrive later, capability gates and reconciliation.

Specifications script an ability’s answer without running anything. See Ability answers.

Packages, references, the lock and activation

Section titled “Packages, references, the lock and activation”

A system that names a package declares no abilities of its own. The package’s contract.play provides them, so the contract and the model cannot drift.

system Payments
extension "cratis/stripe" version 2
setting secretKey from secret StripeSecretKey
activation on demand idle after 10 minutes
  • References. A reference is a catalog short name, a full OCI reference or an npm: package for a frontend-only package. Without a version it means the latest release. See Referencing a package.
  • The lock. screenplay.lock pins each reference to a version, a package digest, a contract hash and a publisher. Commit it. The compiler never resolves a range: it reads the contract by the locked digest from the vendored extensions folder or the user cache. See The lock and the cache, vendoring and restore.
  • Naming is not trusting. Whether a package may run is decided by an allow-list of publishers in .cratis/extensions.json and, for a deployment, by Stage. See the CLI’s trust rules and Stage’s Extension packages.
  • Settings and secrets. A system maps each setting its contract declares to a literal or a named secret, never a secret’s value. See System settings and named secrets.
  • Activation and tiers. A backend runs in an execution tier and starts lazily. Reaching a screen that places the system’s components starts the backend. Mounting a component does not. See Stage’s Execution tiers and activation.

The extension, setting and activation lines are realization metadata. They change no bytes of the executable semantic model, so swapping one provider for another does not change what an invocation means.

A contract can declare abilities, inbound triggers, settings, a backend and frontend components. A screen places a component with component <System>.<Component> <name>, names the system and never the package, and handles the signals the component raises. See Extension components and Interaction triggers. Inbound traffic such as a webhook is stored and acknowledged by Stage and delivered to the extension, which raises the contract’s triggers; see Stage’s inbound traffic and triggers.

An ability can also be realized without writing a backend, by the built-in http extension, which maps an ability to a REST call from a declarative block.

You want to Read
Declare a system and its abilities Systems and abilities
Invoke an ability from a behavior Invoke an ability
Write a specification for an invocation Ability answers
Understand the contract file, the manifest and the lock Extension contracts
Configure settings, secrets and activation Environments
Place an extension component on a screen Extension components
Restore, update and vendor packages cratis extension and Restore extensions
Run a model that uses extensions cratis run
Create and verify a package cratis extension new, cratis extension verify and the extension templates
Write a backend Stage’s extension backends: protocol, host services and SDKs for C#, Kotlin, Go and TypeScript
Write a frontend component Scene’s extension component contract and Build an extension component
Invoke abilities from a C# command Arc operations that invoke abilities
Understand why it is designed this way Decision 0159 and decision 0160