Storylines
A user journey, such as “a customer returns an item”, usually crosses several modules, features and slices. A
storyline gives that path a name and keeps it with the model, so it can be reviewed, shown on a board and walked
step by step. Each step names one element by its kind and its name.
A storyline is authoring metadata. It never changes what the model executes: the executable model, the semantic revision and every generated artifact are the same with or without it.
Syntax
Section titled “Syntax”storyline <Name> ["<title>"] [description "<text>"] <kind> <reference> ["<note>"]*<Name>is unique among the application’s storylines. The optional title is what a board shows; the name stands in when there is none.- Each step is one line.
<kind>ismodule,feature,slice,command,event,readmodel,query,screenorreaction. The order of the lines is the order of the path. - A
screenstep names any screen: one declared in a slice or a free screen declared at the top level, in a module or in a feature, whether or not a slice has adopted it yet. <reference>is the element’s name. When the name alone matches several elements of that kind, qualify it with the module, feature or slice it sits in, such asRequests.RequestReturn.- The optional note says what happens at that step.
Storylines are declared at the top level of a document. In a folder model any file can declare one, and each storyline is declared in exactly one file.
Example
Section titled “Example”concept ItemId : Uuid
module Returns feature Requests slice StateChange RequestReturn command RequestReturn itemId ItemId produces ReturnRequested itemId = itemId
event ReturnRequested itemId ItemId
slice StateView PendingReturns readmodel PendingReturn itemId ItemId
projection PendingReturn from ReturnRequested key itemId
query AllPending => PendingReturn[]
storyline ReturnAnItem "A customer returns an item" description "From the request to the list the warehouse works from" feature Returns.Requests command RequestReturn "The customer asks to return the item" event ReturnRequested readmodel PendingReturn query AllPending "The warehouse sees the return"Renames, moves and missing elements
Section titled “Renames, moves and missing elements”A step is a reference like any other, so renaming or moving the element it names rewrites the step. Renaming
the command RequestReturn through propose-rename or screenplay rename rewrites command RequestReturn, and
moving the feature Requests to another module rewrites feature Returns.Requests to the new path.
A step that names nothing, for example after the element was deleted, is warning PLAY0942. It does not stop the
model from compiling: remove the step or point it at the element that replaced it. A step whose name matches
several elements of its kind is warning PLAY0198; qualify it. See diagnostics.
list-storylines(MCP) lists every storyline with its steps in order. Each step reports its kind, its reference, its note, and the element it resolves to: kind, address, location and semantic identity. A step that names nothing or is ambiguous reportsmissingorambiguousinstead.- Storylines are AST nodes (
StorylineSyntaxandStorylineStepSyntax), soread-astreads them andpropose-astcreates, reorders, edits or removes them.propose-sourceedits them as text. search-declarationsanddeclaration-detailsfind a storyline by name with kindStoryline.export-workspaceand every printed document keep storylines, so they survive export and import.