Skip to content

Screenplay files

An event model on a Studio board is a Screenplay model: modules, features, slices, commands, events, read models, screens and specifications, written in .play files. Studio is one place to edit that model. The .play files are another, and they can be the source of truth that lives next to your code.

This page covers the developer’s side: getting the files out, getting them back in, and keeping them in Git. The language itself is described at cratis.io.

export import commits when the board is quiet changes in the repository, offered for import STUDIO Event model board SCREENPLAY .play files GIT Your repository
Two ways to move a model: by hand, as an export and an import, or automatically, by keeping the board in sync with a repository.

Open Project options > Export to download the open event model. You can choose:

Export What you get
Screenplay file One .play file holding the whole event model
Screenplay folder A ZIP of .play files, one per module, feature and slice, laid out as folders
Mermaid A Mermaid eventmodeling diagram. There is also Export feature to Mermaid for a single feature
Event Modeling JSON A document in the official Event Modeling Specification format

Use the Screenplay folder when you want the model in a repository, because small files give small diffs and sensible merges. Use the single file when you want to hand the model to a person or a tool in one piece.

The folder export mirrors the board. Module folders hold feature folders, and feature folders hold slice folders. The names below are only an illustration:

model/
Catalog/ module
Products/ feature
AddProduct/ slice
...
Sales/
Orders/
...

Beside the .play documents, the folder carries everything the model names that a .play file cannot hold:

  • the sketches, mockups and images of your screens, saved byte for byte,
  • .screenplay/notes.json, which holds the issue links of your slices.

The export reports what the board holds that the files could not carry. Read those diagnostics before you decide the files are a complete copy.

Project options > Import reads a model into a board:

Import Use it for
Screenplay file A single .play file
Screenplay ZIP A ZIP of .play files imported as one application. The ZIP can be up to 8 MiB
Screenplay folder A folder of .play files you pick from disk
Event Modeling JSON An official Event Modeling Specification document

Studio compiles what you pick before it changes anything, and shows the result as Preview import. Compile errors are listed with their line and column. Anything the import cannot carry shows under Some of the document will not be added. Select Accept & Import to import, or Cancel to leave the board as it is.

An import brings the screens’ sketches, mockups, images and issue links along with the model.

A model can go out and come back. These are the limits worth knowing:

  • Concepts that already exist on the board are left unchanged by an import, so their generation strategy and rules do not change. Studio warns when this happens.
  • Generation strategies that Screenplay cannot express (pattern, random and rule) are dropped with a warning on import.
  • A concept that is marked as personal data and also generated keeps its personal-data classification and loses generation, with a warning.
  • Rules on a generated concept are checked against the strategy on export. A rule that can never hold is refused on export and its concept is left out, while the rest of the model still exports.

Read the import preview’s warnings every time. They name what an import will not carry.

Instead of exporting by hand, connect a board to a repository. Studio then commits the model there as you work.

You need a project with a repository connected. See Build and deliver for connecting one.

  1. Open Project options > Keep in sync with Git.
  2. Choose the Branch and the Folder inside the repository, for example model. The folder’s contents are replaced by the board’s files.
  3. Optionally turn on Offer changes pushed to these files for import into the board.
  4. Select Keep in sync.

What Studio commits is exactly what the Screenplay folder export holds. Each commit message names the board and lists the files added, changed and removed. Studio waits until the board has been quiet for a while, so a modeling session becomes a few commits, not one per keystroke. A board that keeps changing is still committed after a longer delay.

Studio reaches the repository through the application’s GitHub App installation. No Git credentials are stored for the sync.

Studio never overwrites a change it has not seen. When someone changes the board’s files in the repository, the status says Someone changed the board’s files in the repository and Studio stops committing. The dialog lists the files that differ, and you choose:

  • Import the repository’s version, which goes through the usual import preview and brings the sketches, mockups, images and issue links in the folder back with it.
  • Commit Studio’s version on top, which keeps the repository’s change in history and then replaces the folder’s files with the board’s.

With Offer changes pushed to these files for import into the board on, a change in the repository with no change on the board is offered for import. When both sides changed, Studio reports the conflict and overwrites neither.

A sync that fails shows why. Select Stop syncing to end it. Nothing already committed is removed.

Because the files are plain text, an editor, a pull request review or a script can work on them. The safest flow:

  1. Let Studio commit the board to the branch.
  2. Change the .play files on that branch, or on a branch of your own.
  3. Merge into the synced branch, and use Import the repository’s version in Studio to bring the change onto the board.

Edit the model in one place at a time. If the board and the files both change between two syncs, you will be asked to choose.

The viewer at https://view.cratis.studio/?url=<URL-encoded address> fetches a public .play document, compiles it, and draws it on the same board Studio uses, read-only, with pan and zoom. It needs no sign-in. It is a convenient way to put a model in a README or a blog post.