As you probably remember, our boss told us about an upcoming meeting with the business folks.
During the meeting the business told us that the goal of the project was to create a prototype for a self-service banking application, which would feature web and mobile user interfaces and allow visitors to register and authenticate.
After successful registration/authentication the system shall provide users information about their accounts such as balances and statement transactions.
There are two systems of record (SOR's) - one for checking/savings accounts and the other for credit card accounts. The prototype shall demonstrate pulling data from the both systems. Initially the systems can be stubbed. As the prototype progresses the stubs shall be replaced with connectors to test instances of the SOR's.
We will keep the registration functionality out of scope for now and will add it later, once all other functionality is in place.
During the meeting several UI sketches were drawn on a whiteboard and we've been smart enough to take pictures of them with a mobile phone camera.
Account details page
Create a model file
The action of this chapter happens after the meeting. We will create a story model to capture the input from the meeting in a structured way and make it available in the documentation system.
To create a story model we click on File > New and select Nasdanika/Story model:
Click Next, select container and enter file name. We will keep our model in the application project and name the model file
Click Next again and select
Catalog as the story model root element:
Add the model file and sketches to the binary build
Once we have a model we shall copy sketches to the application project, say to the
sketches folder, and add the model file and the sketches folder to the binary build - plugin.xml, Build tab, Binary Build section:
Populate the model
Right-click on the root Catalog element, select New child > User:
Based on the information we gathered from the meeting with the business we are going to create two users - Guest and Customer. Each of them will have several stories with scenarios.
Detailed information about the story model can be found in the online documentation:
Below is a quick overview of several model classes.
Catalog is a generic container for story model elements. It is the root element of our story model.
User is a human actor.
User is a sub-type of Protagonist and as such can be linked to EClass representing this User/Protagonist in the domain model.
User can play zero or more Roles and contain zero or more states and stories.
As a sub-type of Actor it may reference super-actors and contain sub-actors.
Interaction state, e.g. a web page. Scenarios transition from their start state(s) (context, "given") to the end state (outcome, "then").
States can be useful when multiple scenarios share start/end states - it allows to clearly identify shared states.
Story represents an agile user story which has the following structure:
A story can
- Contain scenarios, states, parameters, and conditional protagonists.
- Depend on other stories.
- Reference protagonists. If a story is contained by a protagonist (e.g. in our case stories are defined under users), then the containing protagonist is implicitly added to the story's protagonist list.
- Reference zero or more themes.
- Reference start and end states.
- Realize zero or more Persona's goals.
Scenario has the following format:
Scenario may contain states and steps. It can also reference zero or more context (start) states and one outcome state.
A step in a scenario. For example, user registration or credit application may walk the user through several screens (states). It can be modeled as scenario-specific states contained in the scenario and a list of steps navigating between the states.
Steps can be conditional, e.g. an insurance application wizard may have special steps for different regions.
Register the model with the documentation system
Now we need to register the story model to make the documentation system aware of its existence.
To do so we should first open the application project's
plugin.xml and add
org.nasdanika.story bundle to the list of
org.nasdanika.bank.app bundle dependencies:
And then create an extension for the
org.nasdanika.story.model story element with
Browse story model documentation
Now we can start our application to browse the story model documentation and share it with others.
In the TOC there is a new
Stories node containing
Nasdanika Bank catalog node, which in turn contains nodes
representing story model elements.
The following sub-sections describe documentation content of different node types.
Catalog documentation may contain the following tabs:
- Description, if catalog description is not blank.
- Diagram - auto-generated diagrams visualizing catalog elements and their relationships.
Several types of diagrams are generated for all catalog elements:
- Activity diagram is generated only for scenarios which contain steps.
- Use-case diagram if the element is a protagonist or story or contains protagonists and/or stories.
- State hierarchy diagram if the element is a State or contains states.
- State transition diagram if the element is a State or Scenario or contains states and/or scenarios.
If an element supports more than one diagram type, then a drop-down box is shown in the diagram toolbar allowing to select a particular diagram (view).
The diagram toolbar contains the following additional controls:
- Direction - dependency direction to traverse during discovery of related elements.
- Depth - traversal depth.
- Left-to-right - allows to change diagram layout.
- Fit width - scales the diagram to fit the viewport.
When toolbar controls selections are modified the diagram is automatically regenerated and reloaded.
Direction, depth, and left-to-right are not applicable to activity diagrams and are disabled when "Activity" view is selected.
This diagram/view represents states as objects with scenarios which can be initiated from states are fields. Sub-states are connected to super-states with the generalization/inheritance connection:
This diagram depicts states as... states (what a surprise!) and scenarios as transitions between states. States contained in scenarios are considered "private" and are not displayed unless referenced by scenarios, which is allowed by the model but shall be avoided - private states shall be referenced by scenario steps, but not by scenarios.
State-transition diagrams may also show start and end pseudo-states. Scenarios with no context states are shown as originating from the start state, and scenarios with no outcome state transition to the end state. In the case of state-transition diagrams at the story level, scenarios having context states listed in the story start states are also shown as originating from the diagram start state, and scenarios with the end state listed in the story end states are shown as transitioning to the end state of the story.
As described above, this diagram contains protagonists and stories. It depicts protagonist-story relations as associations, actor and role inheritance as generalizations and actor-in-role as realizations.
Protagonist (Actor, User, System, Role) documentation contains description, diagram, states and stories tabs:
State documentation contains description, diagram, sub-states (if any) and super-states (if any) tabs:
In our model documentation we've used
image renderer to link screen sketches to the documentation.
This renderer generates a link with a picture icon as shown above. Click on the link opens an image dialog:
Story documentation contains overview, diagram, and scenarios tabs:
If a story defines start and end states, then the state transition diagram depicts start and end pseudo-states:
Scenario documentation contains overview, diagram, states (if any), and steps (if any) tabs:
If a scenario contains steps, then an activity diagram is generated:
In this chapter we've started with a little bit of requirements and a few sketches. We've put the requirements into a story model and linked the sketches to the model.
Then the documentation system generated several types of UML diagrams from the model we've created. These diagrams will be of great help in communicating the purpose of the prototype to the stakeholders.
nasdanika/bank image at Doker Hub corresponds to the state of our application at the end of this chapter.
In the next chapter we will create initial tests and link them to the story model. These tests will serve as executable specifications for our prototype.