Integration Scenarios

A Requirement is a condition or capability that must be met by a system or component to satisfy a contract, standard, specification, or other form of request.

Integration Scenarios describe an end-to-end workflow across a Product or Product Family resulting in Business Value for a Product Customer in flexible format.
Integration scenarios are threads across a number of other requirements such as Features and User Stories that don’t deliver Business Value on their own. They are ideally suited to describing the scope of Releases and providing the input for integration testing, necessary to achieve higher levels of acceptance.
Integration Scenarios can also be used to manage cross-cutting Non-Functional Requirements and drive the discovery of Architectural Mechanisms.
Integration Scenarios provide the context for discussions around User Stories.

In a Delivery Team context, such as a Project, Integration Scenarios are useful to thread together numerous features and/or user stories into a scenario that delivers Business Value. When faced with hundreds of stories Release Planning can be very difficult without a high level requirement (many organizations dysfunctionally abuse “epics” for this purpose). Integration Scenarios, sometimes called “Integration Stories” in this context, provide the “story across stories”, helping teams to make sense of why the user stories exist.

In a team-of-teams context, delivering a Product Family (perhaps using a Programme) Integration Scenarios make sense on Programme Backlogs rather than Product Backlogs as they are threads across a number of features and/or user stories that are typically implemented by different Products/Systems in the context of a Solution Architecture.

As a result, Integration Scenarios are typically delivered by Releases, not iterations/sprints and are unlikely to be implemented and accepted as done until relatively late in the Product Families’ Release lifecycle (because once they’re complete you’re finished).

Integration Scenarios should not have story points associated with them, if you use them at all, as this can cause an inaccurate view of progress across teams, and means counting constituent stories twice in Release Burn Ups. . Integration Scenarios are built using Integration Streams.

Integration Streams combine the output of multiple developers, and/or from multiple contributing teams in a complicated or complex system. They also provide a staging mechanism for testing prior to promotion from “build” to “release” enabling progression through the levels of done. Integration Streams are typically implemented as “streams” or “branches” in version control tooling.

We recommend describing Integration Scenarios firmly grounded in technical delivery (not in an abstract way) so that it is possible to identify Stories that will be developed by the contributing development teams. The User Stories that result can be traced back to the Integration Scenario to provide effective lightweight traceability, giving insight into release progress based on completion of contributory stories. Of course, clearly communicated and understood requirements are far more important than maintaining traceability information.


Integration Scenarios can be described in a number of ways, ranging from textual to graphical depending on the nature of the system and the best way to achieve clarity. In all of these examples we recommend using a meaningful title, not “Integration Scenario”!

One of our favorite ways is to draw an activity diagram of user interactions using GUI mockups in the nodes with references to features/use cases/stories as appropriate. We do not recommend strictly following a diagram format but using the visual or textual elements that will communicate the scenario as effectively as possible. UX Storyboarding can also be an effective way of describing Integration Scenarios.

When using a graphical view we recommend including links to stories or systems that are covered by the scenario and adding rich graphics to standard modeling notation to increase communication.

Integration Scenarios using textual formats are best described as a narrative with links to contributing stories or systems.

They should ideally be no more than a couple of paragraphs that describe interactions between users and a Product or Product Famliy across a number of features and stories. Sometimes adding extra alternative or exceptional flows can be useful, in the style popularized by use cases, but if there’s a lot of “flow logic” involved then we recommend using a diagrammatic form (e.g. workflow) to avoid convoluted textual documents. Similarly adding a non-functional section indicating non-functional requirements or constraints that apply across the stories making up the scenario can be useful.

Importantly, Integration Scenarios must result in Business Value.

Integration Scenarios describe the dynamics between stories and how they collectively contribute to delivering business value. To that end we recommend highlighting and directly linking to the stories that make up the integration scenario. In this way Integration Scenarios add context to the mass of user stories and provide a sound basis for scoping a system, describing a release, describing functional architectural mechanisms, integration testing, and product acceptance.

Regardless of format we recommend that Integration Scenarios are described from the user perspective and focus on achieving business value. The choice of formats should be driven by the type of Product being developed (e.g. graphical/user facing vs. back end service) and further influenced by team experience and available tooling. We strongly advise not being concerned with the constraints imposed by formal modeling languages, the communication is important not the notation.

Sometimes we wish to use Integration Scenarios as part of diagrams, even workflow/activity diagrams (e.g. for Value Stream Analysis) in which case the full graphical or text version might be a bit big. In these situations, we recommend using a “zoomed out” view which just lists a title and the related stories. In fact, this “elided” form of an Integration Scenario is sometimes useful for simply gathering up a collection of stories into a larger chunk for planning purposes. Story lists in these diagrams don’t have to be exhaustive, just indicative.

The Flipside

The flipside of Integration Scenarios, as with Architectural Mechanisms, is a good place to keep acceptance criteria, or if using work item tracking tools another tab or field of information is useful. We recommend specifying acceptance criteria as tests where possible, and so often a list of acceptance criteria will link off to test information.


Textual Integration Scenarios can be crafted in any decent rich text editor that allows for hyperlinks. We recommend trying to keep them short since the detail of the requirements should be in lower level stories or UX designs/storyboards. Instead the Integration Scenario focuses on the dynamics between requirements. A good rule of thumb is that they should be only a couple of paragraphs, and at their biggest if alternates/exceptions and non-functionals are included they should only be 2 or 3 pages. Creating a large number of fully documented Integration Scenarios prior to any development effort is a very bad idea as it will introduce the problems inherent in waterfall development.

However, elaborating the Integration Scenarios for a Release prior to development iterations/sprints or continuous flow development (with customer representation and team representation) is an excellent way to align collective understanding of scope and requirements on a Release by Release basis.

Each Release should be scoped to no more than a one or two Integration Scenarios, if there’s more and they are not too interdependent then they can be delivered in separate Releases enabling earlier  feedback cycles, (even if they are internal Releases rather than operationally deployed customer releases).

A Release Plan is a medium term plan that defines a series of high level goals that delivery teams can “sprint” or “flow” towards.
Release plans join up the Portfolio/Programme views with Projects/Delivery Teams.

Links to other elements

Integration Scenarios provide a mid-level requirement type, higher level than User Stories but lower than Portfolio Requests. They are at a similar level to Feature, although they contain a lot more information than Features. As a result, Integration Scenarios provide a unit of incremental business value which can be used for Release Planning, tying in milestones for programme/portfolio tracking and governance.

Because Integration Scenarios are constructed in a narrative form that describes a scenario, tried and tested scenario based testing methods can be applied for Integration testing.

Integration Scenarios also provide a useful starting point for understanding Solution Architecture, in the case of Product Families or systems of systems,  and System Architecture in terms of indicating structure and identification of mechanisms. It is possible to resonate architectural structure with Integration Scenario structure although there is a risk of inappropriately introducing the incorrect structure to the Architecture.

By aligning Integration Scenarios with Integration Streams, delivering them in Releases tracked with simple Milestones we can focus the various views of Portfolio Management, Programme Management, Project Management, Architecture, Delivery, Quality, Deployment, Acceptance and Business Change onto Releases at the center of the H-Model. Using Integration Scenarios specifically, we can de-conflict business management and technical delivery. Integration Stories are a common currency for the entire IT organization providing a context for requirements, planning, delivery and acceptance.

Integration Modeling

Integration Scenarios can also be used as part of Integration Modeling (creating scope diagrams) to indicate which actors and  systems the various sets of requirements interact with, helping to clarify overall scope and identify potential gaps in scope.

A Scoping Diagram is used to draw a picture of the primary requirements and users/interacting systems.