“The real story is that software developers are spending a relevant amount of their time learning, in order to do things they don’t have a clue about. Differently from other professions, we’re doing things for the first time, most of the time (even if it looks like the same old typing from the outside).”
This quote from Alberto Brandolini resonates with many teams that are faced with building software in less familiar domains. While some developers can stay in the same business vertical for most or all of their career, most do not have that luxury. Developers are required to understand a new domain quickly, translate it into software, and repeat throughout their career. They must quickly become familiar with a domain such that they are able to turn it into working software that includes user interfaces, APIs, and data models.
The ADDR Process helps to bridge this gap through a series of rapid design steps. Chapter 3 detailed the first step of the API design process through the understanding of desired outcomes. The next step is the gathering of details from stakeholders, development teams, and business domain experts to better understand the concepts, processes, and workflows of the domain.
This chapter addresses how to capture domain details and expected behavior using an activity-based structure (see Figure 4.1). It also introduces the EventStorming framework as a collaborative way to explore the domain. The result is a deeper understanding of the domain, alignment between all team members, and a foundation for defining and designing the APIs that will deliver the necessary digital capabilities.
Creating job stories helps identify the desired outcomes, along with the digital capabilities necessary to produce the outcomes. This was covered previously in Chapter 3. The next step is to detail the digital capabilities as the activities and activity steps required to achieve these outcomes.
An activity is work that helps to contribute toward a desired outcome. Activities may be performed by only one participant, or it may be a combination of multiple participants that collaborate together. A participant may be a person, an internal system, or a third-party system.
Activity steps decompose activities into individual tasks that need to be performed to complete the activity. Once all necessary activities are completed, the job story outcome will be met.
There are two quick steps to capture these details: identify the activities for each job story, then decompose each activity into individual steps. The results are then used to identify bounded contexts and APIs, which is detailed in the next chapter.
During this part of the process, all team members gain deeper understanding and alignment on the solution. If requirements are vague or uncertainty remains, the team may choose to proceed into a collaborative EventStorming session to explore the solution further. EventStorming is detailed later in this chapter.
Start by identifying any activities to be performed that produce the desired outcome for each job story. The goal is to find the bigger units of work that will contribute to the outcome.
Examples of activities for the JSON’s Bookstore “Place an Order” job story #4, identified in Table 3.1 of Chapter 3, are shown in Table 4.1.
Notice that the activities are high level and will often require one or more steps to accomplish the activity. If individual activity steps are identified during this step, go ahead and note it. Then seek to determine the activity that it belongs to and capture that as well.
Activities are composed of steps, with each step captured at a level of granularity that ensures it is executed by one participant at a time. If an activity step requires two or more people to execute it simultaneously, continue to decompose the activity step into smaller, independent steps for each participant.
Decomposing an activity into its individual steps requires a deeper understanding of how the API will solve real-world problems. This requires the insights of a domain or subject matter expert ("SME"). Include SMEs in the process of capturing activities and activity steps. If a SME is unavailable, spend some time interviewing SMEs and customers to better understand the needs. Be sure to allow sufficient time for this research to ensure all questions have been addressed, leaving no room for making assumptions about the problem space. When available, the product manager should be responsible for the interview process.
Table 4.2 decomposes the activities for JSON’s Bookstore into activity steps:
Notice that some activities may only have a single step while others may have multiple steps. This is common as some activities are more complex than others.
Repeat this process for each job story. Review the activities and steps with SMEs to gain feedback and to ensure proper alignment. Once completed, proceed to the Define phase detailed in Chapter 5. If requirements are not clear enough to produce activities and steps, more work will need to be done. The API workshop examples, available on GitHub, provides templates and examples for capturing job story activities.
The activities and activity steps examples detailed in Table 4.1 and Table 4.2 are easily understood as most people have experienced an online ecommerce website. For domains not familiar to the team, it may be necessary to explore the problem space further before the activities and activity steps are clear. EventStorming is the recommended technique to understand and align on requirements in a collaborative way.
EventStorming is a collaborative process to help surface the business processes, requirements, and domain events as a visual model. It is a tool designed by Alberto Brandolini that has been adapted in different ways to fit the needs of organizations around the world.
EventStorming is most effective when conducted as an in-person session. Remote sessions may be used, when necessary, though it will result in limited dynamic conversation. A facilitator helps the group navigate the process and helps to keep the session on-track. Everyone is expected to contribute throughout the entire session by offering insights, asking clarifying questions, and identifying missing facts that require follow-up research.
Unlike other techniques that focus on the software design of a solution, EventStorming seeks to create a shared understanding of all or a portion of a domain. Artifacts and learnings from EventStorming sessions are used as input to the software design process, including the API design process.
Case Study: EventStorming for International Wire Transfers
A recent EventStorming session was conducted for a group developing support for sending international wire transfers. The team was very familiar with the mechanics of performing the wire transfer but wished to explore the process leading up to the transfer. It was decided that EventStorming would be a useful tool for the exploration process.
In the weeks leading up to the EventStorming session, job stories were used to capture the requirements. A specific set of job stories were selected for the upcoming EventStorming session. The selected job stories expressed jobs to be done for the areas they wished to explore. The participant list was selected, and the team met for a remote session.
During the remote session, several insights were achieved:
1. Team alignment regarding the overall process to support international wire transfers
2. Open questions were identified regarding some fundamental business policies
3. Clear definitions of key terminology, referred to as ubiquitous language in domain-driven design, that included input from business
The most valuable insight, however, was the number of unknowns around the specifics of currency conversion. No one was familiar with the internal policies regarding when a currency conversion was conducted. There were several options, from performing the conversion at the time of wire initiation to waiting until the wire transfer process started. The gap in knowledge was identified within an hour of starting the session. It was decided that further investigation was necessary. Domain experts were brought into the session to clarify the matter.
With better knowledge at hand, some significant decisions needed to be made. The session was halted to gain further clarification on the scope of the release. The EventStorming was concluded at a future time when more information was known, ensuring that the initial release met all business and customer needs.
Had the EventStorming session not been conducted, developers would have assumed a specific set of business policies with regard to currency conversion. Subject matter experts would have required a different set of business policies, forcing developers to make last minute changes and incur significant technical debt to deliver on time.
EventStorming sessions are very interactive. They benefit from a dedicated facilitator to ensure the sessions make the most effective use of the attendees’ time. In-person sessions require a large wall space, called the EventStorming canvas, where sticky notes are placed and moved around to construct a narrative of how the solution will work. Remote sessions are also possible when teams are distributed or unable to locate a single room of sufficient size or duration.
The ADDR Process separates the EventStorming session into 5 distinct steps. Each step seeks to add more detail and understanding until a better understanding of the domain is gained. Along the way, assumptions will be clarified to ensure greater alignment between the team and the SMEs. The resulting output of an EventStorming session is used immediately to capture activities and steps. It is also used later in the process to help identify bounded contexts, as detailed in Chapter 5.
Scheduled Time: 30-60 minutes
The EventStorming process starts by identifying business domain events for a job story or group of job stories. Everyone captures these events on orange stickies and places them on the canvas.
Domain events are phrased in the past tense to indicate that something has already happened. Phrasing domain events in the past tense can be challenging for some attendees. Help them rephrase the domain events until the habit is built. Being consistent in this effort will pay off during subsequent steps. Table 4.3 demonstrates the preferred naming conventions for domain events and those to avoid.
This step should offer two passes of 15-30 minutes each. For a session with a larger scope, more passes may be required. The result is a large number of unordered orange sticky notes scattered all over the canvas.
As events are placed, attendees may start to slow down. This is common and easily remedied. Between each pass, review some areas of the canvas to identify missing domain events. Ask attendees to review all domain events and identify causation events that may come before a business domain event. If the causation event is missing, have them add it as a new orange sticky note.
Figure 4.2 demonstrates what this would look like when capturing the business domain events for JSON’s Bookstore job stories 1 and 4 captured in the previous chapter in Table 3.1.
Once the session is complete, take a brief break, then proceed to the next step.
Scheduled Time: 90-120 minutes
Next, the orange stickies are ordered into a narrative from beginning to end. Along the way, duplicate events are removed, and clarifications are made to ensure the events start to frame the narrative.
The facilitator is responsible for asking clarifying questions to the group to ensure the narrative is composed properly. Find the starting domain event for the narrative, then seek to find the next domain event and place it after the first. Leave plenty of space on the canvas to insert domain events as needed.
It is common for sessions to become stuck if there are branching or parallel narratives. To help expedite the session, select a single narrative and order the domain events accordingly. Branching or parallel narratives may be captured below the primary narrative, if desired.
Figure 4.3 demonstrates creating a narrative from the business domain events previously identified.
While this step may appear to require very little time, expect conversations to emerge as the narrative is established. Therefore, allocate between one and two hours minimum. If necessary, turn some of the domain events to a 45-degree angle to note that they need to be revisited and proceed with the remainder of the narrative. Once the overall narrative is established, revisit the domain events in question or mark them with a hotspot sticky (hot pink) for follow-up.
Scheduled Time: 60-90 minutes
Once all events have been cleaned up and grouped together in a general timeline, the group seeks to ensure that no events are missing. To do this, the group starts to walk from left-to-right to tell the full narrative. If events are missing or need clarification, they are changed immediately. It is at this step where a large surface area is beneficial to ensure sticky notes may be moved around and for filling in gaps in the narrative.
It is also at this step that all domain concepts need to be unified to establish a common vocabulary. This vocabulary will evolve into the ubiquitous language for each bounded context that will be identified in the next step of the ADDR Process. Figure 4.4 demonstrates cards that may be attached to the EventStorming canvas to unify common vocabulary. If necessary, rewrite existing domain events to use the new vocabulary. It won’t take long for the group to start adopting the new terminology.
Expect this step to take at least an hour as questions are raised and discussions emerge.
Scheduled Time: 30-60 minutes
After the events have been ordered, additional sticky note colors are used to expand domain understanding. Figure 4.5 illustrates a portion of the “Place Order” job story for JSON’s Bookstore using these additional types of sticky notes.
Below is a summary of the common sticky note types shown in Figure 4.4 and used throughout an EventStorming session:
■ Business event (orange) – the result of an action or policy that indicates forward progression through a workflow or process
■ Hotspot (bright pink) – unknown or missing data that will require research and follow-up after the session.
■ Command (dark blue) – an action taken by a user or system.
■ Aggregate (large, pale yellow) – represent behavior or logic that executes as a result of a command and behavior and often results in one or more events. In Domain-Driven Design (DDD), Aggregates are defined as units of transactional consistency. In EventStorming, this is a higher-level representation of workflows, state machines, and other behavior.
■ Policy (lilac) –the triggering event or motivation for why a new command is executed and is always required. It acts as the bridge or glue between an event and a command. They may start with the word “when” or “whenever”.
■ External system (pale pink) – represents systems outside of the solution. These may be external to the team but internal to the organization, or a third-party system. They are best thought of as aggregates outside of the group’s control.
■ User interface (white) – represents a user interface that will offer one or more roles the capability to execute a command against an aggregate.
■ User (yellow, small) – represents a specific role that is interacting with the system, typically via a UI, but also perhaps as a result of an automated call, email, or other mechanism.
Start by adding commands (blue stickies) to capture what actions are taken by a system or user that will result in one or more of the identified business domain events. Commands are sent to aggregates, so capture those as well. Business rules, often phrased as “when xyz happens...”, may be captured as policies (lilac). Hot pink stickies are used as hotspot indicators where more information is required.
Scheduled Time: 30 minutes
Finally, the narrative is reviewed from both directions, start-to-end and end-to-start, to ensure all elements have been captured. Important events and triggers are clearly marked to denote key transitions between steps. Figure 4.6 shows a fully explored “Place an Order” job story using the sticky notes necessary to express the understanding gained during the session.
This completes the EventStorming session. The canvas should be saved for future reference as it will be useful for informing future steps in the API design process. Consider taking photos of the canvas and sharing them with the team. Rolling the canvas up or relocating it to a shared space is helpful for team members co-located in the same office space. If the team used a digital tool, such as Miro, export the work as a PDF or image for sharing on a wiki or as part of other project assets.
Finally, write the activities and activity steps identified during the session using the format outlined previously.
Alignment between stakeholders and development teams is achieved through a shared understanding of terminology, processes, goals, and required integrations with other internal and external systems. Questions are surfaced for follow-up after the session to prevent assumptions or misunderstandings from being captured into the API design and code. An EventStorming session helps everyone to surface these insights and communicate effectively through a fun and effective exercise.
There are five additional benefits of conducting an EventStorming session:
1. Shared understanding of requirements and scope of the problem being modeled
2. Shared understanding of the workflow processes, business rules, and constraints
3. Establish a shared domain vocabulary, replacing multiple terms with a ubiquitous language
4. Identification of unknowns that require follow-up and clarification prior to software design and development
5. Identification of boundaries within the solution, useful for scoping team efforts and division of labor to minimize cross-team dependency coordination
There are circumstances when EventStorming is most effective. These include:
■ prior to API and microservice design and implementation to help establish outside-in design thinking
■ prior to software design and development to clarify assumptions and address open questions
■ after clearly documenting desired outcomes, typically through the use of job stories, discussed in Chapter 3
■ when all roles are represented in the session
■ when embarking on a significant scope of effort or one that spans multiple teams
There are also circumstances when the value of an EventStorming session may be reduced. To avoid spending unnecessary time in an EventStorming session, consider these factors that contribute to an ineffective session:
■ the business process is well-known and documented, as results will likely result in the same insights
■ the scope of the problem is small enough that the identified business requirements are sufficient and complete
■ the business requirements have not yet been identified. In this case, start with constructing job stories, covered in Chapter 3, to clearly define the desired outcomes and parties involved
■ business stakeholders cannot attend or do not see value in the exercise. While development teams may still conduct a session, doing so may lead to modeling a process based on too many technical assumptions that do not meet business needs
■ software delivery has begun, and delivery dates are fixed. If the teams are early enough in the delivery process, the output of the session may be used to make software architectural and design adjustments prior to a release. Otherwise, teams will be forced to proceed with existing decisions rather than the insights obtained through an EventStorming session
Including the right mix of attendees is critical for a successful EventStorming session. A session must involve a few representatives from various roles and responsibilities. It should be kept to no more than 12 people to ensure full participation by all attendees. Larger groups can prevent less assertive attendees from engaging in the session.
Optional participants that may raise the group size should be considered for inclusion on a case-by-case basis to avoid overloading the session with too many voices. Sessions with dozens of people often slow down or result in participants looking down at their phone or checking email. Smaller groups benefit from the need for smaller conference space when conducting an in-person session. Avoid observers whenever possible, as they don’t add value and may distract from the session. Rarely do observers strictly observe.
When selecting the participants for an EventStorming session, be sure to consider the following roles, in priority order:
1. Business owners, including those helping to define the requirements such as product managers and product owners
2. Subject matter experts with familiarity of the domain space
3. Technical leads, architects, and senior developers involved in leading the software delivery
4. Security experts, especially when the problem space requires the involvement of privacy or security concerns
5. Individual software developers and contributors not involved with decision-making (on a case-by-case basis only)
A facilitator familiar with EventStorming is important. They are responsible for moving the process forward and keeping everyone engaged throughout the process.
Emails and message notifications may lead to distractions, slowing down progress, causing clarifying questions to be missed, or preventing subject matter experts from answering clarifying questions. Remote sessions only add to the number of distractions possible as it is easy to task switch. Facilitators must work toward preventing these issues by controlling the pace of the session, the frequency of breaks, and providing clear transitions between each step in the process.
When in doubt, facilitators need to evaluate discussions to determine if they are clarifying intent or becoming a digression. If necessary, apply the hot spot sticky to capture an area of contention and revisit. Otherwise, the session will slowly become an forum for opinion by one or two people.
Since EventStorming is relatively new and experienced facilitators are in short supply, this section provides insights and tips from recently conducted sessions.
When conducting an in-person session, EventStorming requires some essential supplies. Be sure to have all the necessary supplies ordered and on hand several days prior to the session. Avoid gathering supplies the day prior or the morning of the session.
The session will require a large number of sticky notes that includes a variety of colors. Typically, orange stickies are used the most, so having more of that color is important. Most office supply stores offer boxes of colors that match the needs for EventStorming. However, feel free to adjust colors to team preferences or to what is available. Remember that most attendees will be attending their first EventStorming session, so they won’t know the “proper colors” anyway. If experienced participants complain about the wrong colors, request that they be in charge of the supplies for any future sessions.
A large wall is also required for hanging a large paper sheet as a modeling surface where sticky notes are applied and moved around as needed. Some organizations prefer to use paper sheets that are no more than 18-24 inches (45-60cm) to allow two or three lanes of sheets along the wall.
A legend should be visible to ensure that everyone is reminded of each color of sticky note used. Be sure to write out a legend that shows all sticky note colors, their type (e.g., “Business Domain Event” for orange stickies), and arrows that show how they are typically combined to produce a narrative. An example legend is shown in Figure 4.7.
Black markers should be used to write on the sticky notes, ensuring words are easy to read when stepping away from the modelling surface. Ensure there is at least one marker for each participant, with a few extra scattered around the room in case some are lost.
Remote sessions may choose to use a diagramming tool to simulate sticky notes. Another option is to use a shared document that is accessible by each attendee, applying similar color-coding to text as those used with sticky notes. Whatever is chosen, practice using the tool prior to the event to ensure an effective use of time during the session.
Achieving a successful EventStorming session requires preparation and effective communication before a session, at the start of a session, and after a session has been completed. The following are suggestions for facilitators to communicate effectively via email, video, and face-to-face before the session:
■ Product management attendance is essential. Insist on product owners and product managers to be present. A developer-heavy session will focus on how things work today, existing systems, and delivering the status quo. Additionally, misalignment will occur, rendering an incorrect understanding of the domain and desired outcomes.
■ Share the purpose and scope of the session. If the purpose and scope are not shared ahead of time, many will be confused or will fail to participate. This will also ensure the right people are in the room, which is key for EventStorming to be most effective. Establish expectations initially and reinforce at the start of the session.
■ Establish mutual expectations. Confusion or unmet expectations will lead to an ineffective session or a poor view of EventStorming. Establish expectations regarding the process, desired outcome, and the design assets to be produced. Reiterate these at the start of the session to reinforce the goals and establish a proper mindset.
■ Ensure that API design has not started yet. For teams that have already started API design, they will likely ignore the output of the session in favor of moving forward with the current design. The session should be used to guide future vision with immediate execution. Teams unwilling or unable to incorporate the output of the session will likely fail to obtain the highest possible value of an EventStorming session. Ensure team buy-in from everyone before proceeding.
■ Reinforce how EventStorming fits into the overall API design process. Share a progress indicator or revisit the overall process often to demonstrate where the session fits into the bigger picture. This includes the value this will provide to API modeling and design. Otherwise, the session may seem like busy work.
At session kickoff, review the items above once more. Reviewing everything the day of the session helps to bring everything top-of-mind and sets the expectations for the session.
At the start of a session, review the expectations, process, and scope of the session. Then start with the first step of the session. Most first-time attendees will be a bit uncertain how to get started. Be ready to help them along or allow those more familiar to start the process.
Show how the process works by first demonstrating it. Post the first business domain event by taking input from the group, phrase it into the past tense to demonstrate the expected format, then post it on the timeline at an approximate location. Then request that the group start to create their own independently. Use the same technique for each step in the session.
Establish clear reasons for each step of the process. Most first-time attendees won’t fully understand why each step in the process is necessary. Help them understand the value of the time spent. While the process may be obvious to the facilitator, most attendees will need time to adapt to the process of EventStorming.
Once the session is complete, take photos of canvas with the sticky notes for sharing. Before leaving the area, the photos should be checked to ensure that all handwriting is legible. If not, move closer to the board and take more photos.
To make the canvas available digitally, use a tool to produce a single panoramic photo or number the photos from left-to-right to ensure they can be reassembled as needed. If the team resides in a shared office space, the canvas may be carefully removed and placed in a new location for reference.
Digital tools, such as Miro, may be helpful for remote sessions and support PDF or image export of the final canvas. It is also possible to use a shared document, such as Google Docs or a Word documented hosted on SharePoint, if other tools are not readily available. Experience shows that color-coded text works just as well as virtual sticky notes and are easier to cut-and-paste as the canvas is manipulated.
Finally, use the canvas to identify and capture activities and activity steps, as described at the start of this chapter.
The facilitator should send a follow-up email two days after the session. The 2-day email should thank everyone for their participation and share the new location of the sticky notes and the digital folder where the photos reside. A survey link may also be provided to gather input for process improvement.
A second email from the facilitator should be sent two weeks after the session. This email should ask how the output of the session is being used by the team. Use this opportunity to find blocking issues that prevent the team from proceeding. Schedule a follow-up discussion to coach the team on next steps if they are blocked.
Finally, consider writing up a case study of the session and including quotes from attendees, if permission is provided. This will help teams uncertain about the EventStorming process understand the value that it provides and increase their willingness to invest the necessary time. It also helps to share team wins across the organizations.
Remember that EventStorming is a tool that offers discovery-based learning in a collaborative environment. Customizing the process helps organizations gain the most from sessions. The following additions or modifications have been explored beyond the original process suggested by Brandolini:
■ The three-lane approach. Rather than a single sheet of paper covering the wall, using narrow paper that allows for creating three separate lanes in parallel. All initial events are attached to the top lane during business event identification. When ordering them into a narrative, the events are moved to the middle lane. The top lane is then used to expand the available space when expanding the canvas with new sticky notes beyond the initial business events. The bottom lane is used as a “parking lot” for events considered out of scope or identified as duplicate. This approach was built out of necessity as the only available paper rolls from an organization’s supply closet were only 12 inches (30 cm) high.
■ 45-degree angle sticky notes. When a note isn’t clear, needs to be rewritten into the past tense, or revisited for another reason, anyone is empowered to tilt a sticky note at a 45-degree angle. This flags the note for follow-up before proceeding to the next step of the process.
■ Multi-part EventStorming sessions. With the introduction of remote sessions, fatigue often sets in more quickly than with high-energy in-person sessions. In this case, consider breaking an EventStorming session into multiple parts that take no more than two hours before a minimum of a one-hour break. If necessary, a session may be spread across two days as long as all attendees will be available to participate both days.
■ Shared facilitation. The facilitator is encouraged to ask different people to lead the narration/story telling effort. This provides co-ownership of the session, keeps team members engaged and away from email, and helps cross-train others in the EventStorming process. The facilitator demonstrates what is expected, facilitates for a time, then asks for a volunteer or selects someone to facilitate a portion of the process. This continues throughout the session until everyone has had a chance to facilitate some portion of the session. During the activity, the original facilitator remains available and coaches everyone as needed.
It is essential for teams to establish a detailed understanding of domain concepts, processes, and workflows. Capturing these details as activities and activity steps helps to align all team members and establish a foundation for future API design work. The EventStorming framework may be used as a collaborative method for exploring the domain concepts in detail alongside domain and subject-matter experts.
The next step in the API design process is to start defining the bounded contexts and APIs needed to realize the digital capabilities offered by an API product or API platform.