Skip to content

Model your first behavior

In this tutorial you model one small behavior from scratch: a shopper adds an item to a basket, and the basket keeps count. It is the same shape as the Basket feature in the Acme Commerce sample, built from an empty project. It takes about fifteen minutes, and every step ends with something you can see.

  • You need to be signed in with a seat in your organization. If you are not, start with Sign up and start your trial.
  • You do not need AI. Everything here is done by hand.
  • The screenshots in this tutorial come from the Storefront board of the Acme Commerce sample, which has the same controls as the board you will build. Your own board will look emptier, because it starts empty.
  • Names must be unique in your organization, for a project and for an application. If Studio refuses a name, add your initials to it.
  1. Select Projects in the top bar to open the project drawer, and then select Add Project (the + at the top of the drawer).

  2. Enter Corner Shop as the Name. You can leave Domain Description empty. It is only used by AI assistance. Select Add Project.

    Studio opens the project. Its overview says No applications yet and Add the first application to start modeling this project.

  3. Select Add Application. Enter Corner Shop Online as the Name, and describe it in a few words if you like. Select Add Application.

    The application appears under your project in the drawer.

  4. In the drawer, expand your application, hover over Domains and select the + that appears. Its tooltip reads Add Domain. Enter Storefront as the Name and select Add.

  5. Under your new domain, hover over Event Models and select the +, whose tooltip reads Add Event Model. Enter Storefront as the Name and select Add.

    Studio opens the new, empty board.

The overview of the Acme Commerce project, listing its applications and Add Application
A project's overview lists its applications. Yours lists none until you add one. Here is the sample's, with five.

You now have the whole structure: a project, an application, a domain and an event model. The board is empty and hints that you add a module with the sitemap icon. If you want to know why the work is organized this way, see Find your way around.

Part 2: Add a module and a feature (2 minutes)

Section titled “Part 2: Add a module and a feature (2 minutes)”

A module is one area of the business. A feature groups related behavior inside it.

  1. In the toolbar on the left edge of the board, select Add module. It is the first button, the one with the sitemap icon.

  2. Studio puts a module near the middle of your view. Double-click its name and rename it to Shop.

  3. In the header of the module, open the Add menu and choose Add Feature. Double-click the feature’s name and rename it to Basket.

You should see a module called Shop with a feature called Basket inside it. The feature is empty, and says so. More about both in Add modules and features.

Part 3: Add a behavior that changes something (4 minutes)

Section titled “Part 3: Add a behavior that changes something (4 minutes)”

Now the heart of it. A state change slice is one behavior where a person asks for something and the system records it. Slices come in four types; this is the one you will use most.

  1. In the header of the Basket feature, select Add (the + button), choose Add Slice, and then choose State Change. Studio describes it as UI drives a command that produces events.

  2. A new column appears. Double-click its name and rename it to AddToBasket.

    The column holds a command called Command and an event called Event, and a row that says who does it. Studio adds a row named UI for the person using the screen.

  3. Double-click the blue command card and rename it to AddToBasket. Commands are named like instructions.

  4. Double-click the orange event card and rename it to BasketLineAdded. Events are named in the past tense, because they are facts that already happened.

The Add Slice chooser open in a feature, listing State Change, State View, Automation and Translator with a description of each
The chooser asks which kind of behavior the slice is. You pick State Change.

You should see a column with a blue AddToBasket card above an orange BasketLineAdded card, the same shape as the first columns of the sample’s Basket feature:

The first three slices of the Basket feature: AddToBasket, ChangeBasketQuantity and RemoveFromBasket, each with a screen on top, a blue command and an orange event
In the sample's Basket feature, each column is one change: the screen, the command, the event.

Select the AddToBasket command card to open the command editor.

  1. Select + Add property, double-click the new property’s name, and rename it to basketId. In the panel on the right, tick Identifier - names what changes. This says which basket the command is about.

  2. Add a second property, sku, with the type Text.

  3. Add a third property, quantity, and change its type to Number. Use the type menu in the panel on the right, or the type field on the property.

  4. Make sure all three are Required - the sender must give it.

  5. Close the command editor.

The command editor open on AddToBasket, with the properties basketId, sku and quantity, each with a type and a Required box, and the panel for the selected property on the right
The command editor of the sample's AddToBasket, with the same kind of properties. Each property has a type, and can be required or the identifier.

Select the BasketLineAdded event card to open the event editor. An event records what happened, so it carries what changed: not which basket (that is the identifier, and Studio keeps it with the event), but what was added.

  1. Add the property sku with the type Text, and the property quantity with the type Number. Use the same names as on the command: the event takes its values from the command property with the same name.

  2. Close the event editor.

Open the command editor once more and look at the bar at the bottom. It lists any problems with the model, and says how many warnings there are. It should say that everything is fine. If a warning names a property that no command property supplies, check that the names on the event match the names on the command exactly.

A screen shows what the person sees while the slice happens.

  1. In the UI row of the slice, select Add UI prototype (the small + in the corner), and choose From scratch.

  2. The screen editor opens over the board. Select Data, and then Generate the form. Studio makes a field for each property of the command. The drawer says Every property is on the form.

  3. Close the editor. It saves your screen.

You should see a small thumbnail of the screen on the slice, in the UI row, above the command.

The screen editor open on a screen of the Storefront board, with the parts of the screen on the left, the screen in the middle and the Inspector on the right
The screen editor, here on the sample's ProductBrowse screen. Yours holds the form you generated.

To go further with screens, see Add a screen to a slice and The screen editor.

Facts are hard to read on their own. A state view shows them as something a person can look at: here, how many lines the basket has.

  1. In the Basket feature, select Add again, choose Add Slice, and then choose State View. Rename the new column to BasketView. Studio places it to the right of the slice you already have, which matters: a view can only show events produced to its left.

  2. In the events row of the new slice, select Add existing event, search for BasketLineAdded, and pick it. The event card appears in the view. It points back at the slice where the event is produced.

  3. Double-click the green read model card (it is called Read Model) and rename it to BasketSize.

  4. Select the BasketSize card to open its editor. The read model starts with an id property, which is how one basket is found. In the card on the right, add a property, name it lineCount and give it the type Number.

  5. Drag the BasketLineAdded card, on the left, onto lineCount. A small menu asks what the event does: Each time BasketLineAdded happens, lineCount:. Choose Adds one. A line joins the two, and Studio now counts the events.

  6. Close the editor. The changes are saved when it closes.

The editor of the sample's BasketContents read model: events on the left, the read model's properties on the right, and lines between them
The read model editor, here on the sample's BasketContents. Events on the left, the read model on the right, and a line for each thing an event fills in. Yours has one line, from the event to the count.

You should see the BasketLineAdded card in the view, joined to the green BasketSize card. The read model is derived state: it can always be thrown away and rebuilt from the events, so it is never a second source of truth. For more on mapping events, see Read models, projections and queries.

An example says what should happen, in the form given these facts, when this happens, then this follows. It is how you prove the model does what you meant.

  1. Go back to the AddToBasket slice. Under it, select Add Specification. Double-click the name it gets, and rename it to Adding an item puts a line in the basket.

  2. In the When row, select the + and choose the command AddToBasket. Open the card and enter values: basket-1 for basketId, MUG-1 for sku, and 1 for quantity.

  3. In the Then row, select the + and choose the event BasketLineAdded. Open the card and enter MUG-1 for sku and 1 for quantity.

  4. Leave Given empty: nothing needs to have happened before you add the first item.

  5. Select Run specification.

Studio runs the example against your model and checks the result. When it passes, the specification shows a green mark, and its status reads Last run succeeded. If it shows a notice about missing required values, open the step it points to and fill in the property it names.

Two examples under a slice of the Sales board, each with the rows Caller, Given, When and Then, a green check mark and a run button in the header
Examples on the sample's Sales board. Each one has its own rows, a result mark, and a button to run it.

Examples check a step. Play runs the whole model as a small working application, so you can try it.

  1. In the top bar of the board, select Run Solution, the play button. Studio starts your model in a safe session of its own.

  2. When the application appears, run the AddToBasket command with basket-1, MUG-1 and 1.

  3. Select Read models in the Play toolbar and open BasketSize. You should see one entry for basket-1, with a lineCount of 1. Run the command again and the count goes up.

  4. Select Stop Solution to return to the board.

If Studio refuses to start the model, it tells you why. The usual reason is a warning on the command or event, such as a required value that nothing fills in. Fix what it names and try again. Play is a place to try things: its data lives only for the session, and it is not a deployment. See Check behavior for more.