Getting started with Ann

Summary

This topic explains core concepts behind how Ann works and describes an example process for creating stories in Ann.

Explore stories in Ann Studio

Ann studio lets you define processes and outcomes for your software. You can create stories that are very broad or very specific, from “Publish the new marketing site” to “Remove a user from this list.”

The studio helps you break down processes into discrete states: a starting state, called Given; a state that initiates a change, called When; and an outcome state called Then. If it helps you understand better, you can read these states as a sentence in English: Given that a thing has happened, when that state changes in a specific way, then an outcome occurs.

You define each of these states by specifying fields to identify and hold data. Each of these states exists independent of each other and can be understood by a human reader without needing context from the other steps. Each field has a Name and a Example. For example, you could create a field named “Email address” and specify “youremail@example.com” as the example. Fields can be unique or you can re-use the same fields between different states.

Are you ready for a more realistic example? Let’s get started.

Using Ann Studio

The studio lets you define ways of working using simple Given, When, and Then event steps. Each process supports multiple scenarios, which are discrete processes that relate to each other and change based on events and fields you specify.

You can access the studio at studio.tryitwithann.com.

Try an example

The first screen lets you start a story of your own or view an example story. Let’s go through the example first. This will help you understand some of Ann’s core features.

Click Try an Example. The studio window opens with an example story pre-populated.

The example story shows you how to use Ann to define a method of working for a rental car company. Click the down arrow next to Please reserve vehicle to expand the process.

Two different scenarios in the process appear:

Scenarios can get quite detailed. Scroll horizontally to read an entire scenario.

Scenario: Vehicle is available

In this scenario, a customer reserves a vehicle.

The “Vehicle entered” Given step specifies a vehicle field, a vehicle class, and the date and time when this vehicle was created in the system.

The When step defines the terms under which a state change to the vehicle specified in the Given step can occur. In this example, When the vehicle’s information is modified to add the “Reserved by” field, and that field is associated with a customer ID, the vehicle changes state.

This is when the Then events occur. The vehicle changes to include the “Reserved by” field and is associated with the ID of the customer who reserved it.

Scenario: Vehicle is reserved

In this scenario, a customer attempts to reserve a vehicle. They cannot complete this action because the vehicle is already reserved.

The first Given step specifies that the vehicle exists in the system by defining a vehicle field, a vehicle class, and the date and time when this vehicle was created in the system. There are two steps, one to create the vehicle in the system and a second to indicate that it is reserved (as indicated by the “Reserved by” field, which is associated with a customer ID).

The When step explains an error state for the system. In this example, When the vehicle’s information is modified to add the “Reserved by” field, and that field is associated with a customer ID, but a different customer ID is already associated with the vehicle, it will not let the vehicle be reserved by a new person.

This outcome is defined in the Then events step, where the customer ID in the “Reserved by” field in the Given steps does not match the ID of the customer attempting to reserve the vehicle.

Although its not defined in this example, as the final step of this scenario you could specify an output as well, such as displaying a user-facing message with suggested next steps, or returning the user to the vehicle reservation screen.

This example shows two common use cases for Ann: defining the ‘happy path’ where your software works as intended, and defining a common error state.

Create your first story

Are you ready to create your own? Return to studio.tryitwithann.com and click Explore a New Story. The studio opens.

Here’s how to create a scenario:

  1. Click in the text box to give your scenario a title.
  2. Click Explore scenario to specify the scenario’s steps. The Given, When, and Then state fields appear.
  3. Enter a Name in each of the relevant text areas for the three fields. Names should briefly summarize the data specified in each field.
  4. Now you can customize each of the three fields. All of the
  5. In the Given field, click the three-dot overflow menu and choose Add field. A new field appears.
  6. Click to replace the placeholder text and give the field a human-readable Name.
  7. Click to replace the placeholder text and specify a Example for the field.
  8. If necessary, click the three-dot overflow menu and choose Add field to specify an additional field.
  9. Repeat this process until you have specified all the fields you need in each of the three state fields.

That’s it!

This site uses Just the Docs, a documentation theme for Jekyll.