Screenplay onboarding setup
Screenplay’s onboarding block declares how people join an application: through signup or invitations, with any required terms and email templates. Use it after declaring authentication and the personas named by invitations, so the model records who can invite people and which personas newcomers receive.
The application host carries out provisioning, term acceptance and email delivery. The block is authoring metadata, outside the executable semantic model; the reference evaluator does not run it. Supply sender and mail-server settings through environment bindings. Use policies to govern commands and queries separately: an onboarding declaration does not enforce their authorization.
Syntax
Section titled “Syntax”onboarding signup open creates tenant invite tenant as Owner invite member by Owner, Administrator grant Accountant, InvoiceManager legal terms file Legal/terms-of-service.md file Legal/privacy-policy.md offering Starter emails invitation file Emails/invitation.html welcome file Emails/welcome.html signupDeclined file Emails/signup-declined.html images Emails/Imagesonboarding— top level, alongsideauthentication. At most one block for the whole application; a second one is a compile error. Every line in the block is optional, and each may appear once.- It needs an
authenticationblock. Without one, there is nothing for a newcomer to sign in with, andonboardingis a compile error.
Self-signup
Section titled “Self-signup”signup open creates tenantsignup open joins tenantWith no signup line, the model offers no self-signup path; newcomers join by invitation. The host must implement that restriction.
signup open creates tenant— anyone may sign up, and signing up creates a new tenant (organization) for them.signup open joins tenant— anyone may sign up, and signing up asks to join a tenant that already exists.
Invitations
Section titled “Invitations”invite tenant as Ownerinvite member by Owner, Administrator grant Accountant, InvoiceManagerinvite tenant as <Persona>— an invitation sent by the application’s operator that creates a tenant for the invitee, who becomes the persona in it. One line, no body.invite member— an invitation into a tenant that exists.bylists the personas allowed to send it andgrantthe personas the invitee is given. Both are required.
At most one invitation of each kind. Every persona named by as, by or grant must be declared with persona: there are no free-text roles, so an unknown persona is a compile error (PLAY0831).
Legal terms
Section titled “Legal terms”legal terms file Legal/terms-of-service.md file Legal/privacy-policy.mdThis block declares the documents a newcomer must accept. The host must collect acceptance; the declaration does not record it or establish legal compliance. Each file is relative to the repository root, following the same convention as handlers and rules. A missing file produces an attachment warning when files are loaded.
Offering
Section titled “Offering”offering Starteroffering names the offering a new tenant starts on. Screenplay has no catalog to validate the name against; the provisioning host resolves it. Omitting the line leaves the offering unspecified in the model, without making a claim about the application’s licensing.
Emails
Section titled “Emails”emails invitation file Emails/invitation.html welcome file Emails/welcome.html signupDeclined file Emails/signup-declined.html images Emails/ImagesA template file for each email onboarding sends, and the folder the templates take their images from:
| Line | |
|---|---|
invitation file <path> |
The invitation a newcomer receives. |
welcome file <path> |
The welcome sent when someone has joined. |
signupDeclined file <path> |
Sent when a sign-up is declined. |
images <folder> |
The folder holding the images the templates use. |
The host is responsible for template rendering and language selection. An email that is not one of the three above is a compile error (PLAY0832). The sender and the mail server are environment values: see environments.
What the block deliberately does not carry
Section titled “What the block deliberately does not carry”Keep sender addresses, mail-server settings, credentials and prices outside this block. They can differ by environment or customer. Once the declarations are in place, use environment requirements to list the configuration keys and supply their values through the host.
Diagnostics
Section titled “Diagnostics”| Code | Meaning |
|---|---|
PLAY0826 |
The onboarding line carries anything beyond the keyword. |
PLAY0827 |
More than one onboarding block. |
PLAY0828 |
onboarding without authentication. |
PLAY0829 |
A line of the block is not one of its directives, or one is malformed or incomplete. |
PLAY0830 |
The same directive stated twice. |
PLAY0831 |
An invitation names a persona nothing declares. |
PLAY0832 |
The emails block names an email onboarding does not send. |
See diagnostics for the full catalog.