Automatic Requirements Management for Continuous Delivery. Part 1

In a fabulous post our colleague Eamon McGaley described the Gherkin syntax as a normalized language to describe functionalities and features based on the description of a specific sequence of assumptions, pre-conditions and expected results to make automatic requirements management for Continuous Delivery possible. We have prepared a series of 3 posts regarding this topic:

• Part 1: BPMN 2 and how to design test scenarios based on features described as business processes
• Part 2: The applied automation for integration of BPMN 2 diagrams to synchronize them to an Agile server (JIRA)
• Part 3: Matching the results from automatic tests to the processed test scenarios and monitoring of status
  

BACKGROUND

We have worked a lot on Continuous Delivery pipelines and the requirements stuff and also the relationships with the customer have been always a stopper for automatic and continuous life cycles of software. Because of this we have retrieved from our toolbox the BPMN 2 specification. This is not the place to explain BPMN in detail although you can find a brief explanation here.  It will be enough to know that is a standard to describe business processes using different types of diagrams like the standard flow diagrams but with much more details and depth. BPMN is commonly used by BAs (Business Analysts) to reflect into dynamic flows the different working lines, communications and coordinated actions found in business processes.

There are three main types of diagrams and items. Activities, choreography, conversations, events, triggers, gateways, data, etc. It depends upon your specific needs and the analyzed business processes which parts of the BPMN specification you should use.

The BPMN 2 cheat sheet

We'll illustrate this series with a couple of basic examples for a better understanding of our approach.

DESCRIPTION

The Challenge

In our test case the business customer usually works with a BA to define functional and not functional requirements for software components. Besides, the business customer wants to define the user flows in the UI apps. The only tool the BA has to reflect all these requirements is by writing down a set of features each containing a list of scenarios that actually describe the functional/not functional requirements. And the only tool available to write them is JIRA. So, JIRA cards are created and the BA writes the requirements down there.

The main drawbacks of this simple, absolutely obsolete, naive methodology are:

• Changes in requirements are not tracked and correlated to subsequent and critically needed changes in tests.
  
• There is not communication to software components. They (JIRA and build pipelines and therefore the results fo tests) are isolated closed worlds.
• Therefore, any automation for continuous delivery is always blocked at this level as the results of functional/not functional tests can never be correlated to the Agile server scenarios.

We want to normalize the capture of requirements from the customer, handle the functional and not functional requirements  and matching them to the results of automatic tests. We need to build a way to integrate everything into our Delivery Platform to get metrics and the real status of the quality of the software components according to the most recent version of the requirements.

Our Goals in this Part

They are:

1-To provide a tool to business and BAs to design business processes as easy as possible.

2-The learning curve MUST be really low and the adoption period pretty short (never longer than a week).

3-Use basic diagrams to illustrate a real use case.

4-Include feature scenarios into the diagram in a normalized way and strictly following the Gherkin syntax and some simple rules to not be messy and keep things sorted out.

Use Case

Our approach to solve this situation is mainly based on BPMN diagrams as the very first step to put the work of the BA on the "paper". The BA will draw the BPMN diagrams from his/her analysis. The processes can be related to pure business logic in process as well as UI flows. In both cases we're handling business processes.

We've used Eclipse BPMN2 Modeler as our graphical tool to make the diagrams and work with them. There are other tools with more capabilities and integrations like Red Hat's JBPM but we want to keep things as simple as possible for now.

Why to use and IDE? It's easy in this stage. Besides, this approach solves several problems. On one side multiple departments can work on the same project, using different projects. The Diagrams history is preserved under Source Control Management (using Git). Every change releases a new version of the package with the diagrams to distribute in a common repository (Nexus).

We'll start with a two diagrams and a really common set of requirements: UI login and reset password.

The UI login flow

 

The UI reset password flow

In above diagrams we have used just a few BPMN components. The start and the end of the flow, some core activities (the blue rectangles), gateways as conditionals. The result is, a really intuitive and easy to understand flow of actions.

So, this is an extra advantage! Developer engineers and designers will understand sooner and better how a flow works.

And.. where are the features and scenarios?

That's a good question given our primary objective was to set a normalized way to write these features with their scenarios. The diagram items do not contain a specific box for such a thing as requirements. So, we made some decisions to keep us moving.

1. To set a match of 1 feature per each diagram. This constraint will help to keep diagrams tidier. So, we'll use the term Feature Diagram from now on.
   
2. To write the scenarios into each activity (the rectangles with logical steps in the diagrams).

The result is like this:

A list of scenarios into an activity in the feature diagram. The tags are marked with '@' as FR (Functional Tests).

The diagrams are stored as files with the BPMN extension although BPMN is based on proper XML.

The project is a Java/Maven regular one and of course is versioned in Git.

We'll use a folder structure related to JIRA items. "FUSION" will be the JIRA project name and "TELLER" the name of the JIRA component in that project. The features into each BPMN file have a name that will be the name of the JIRA issue grouped in that component.

The POM file is simple as we want only to package and deliver as an archive file to our artifact repositories.

https://gist.github.com/jesusjavierdediego/42beea197fa9cf81daa9c9b4c66bae4b

Why? Well, we said above that we wanted to track changes in the business diagrams. Additionally we want to apply a life cycle and distribute the diagram files using versions and packages as a regular artifact. That means we'll use our artifact repository to store the versions of the diagram files in archive files. The goal of this is to provide the diagram files packages as dependencies for the BPMN Automation component that will be explained in detail in the next post of this series.

So, we included the BPMN diagrams project into a build pipeline that is regularly executed to have the last changes made into the business processes design.

 

Recap

1. We highlighted the main drawbacks of a naive approach to capture of requirements and how are they provided to development engineers, blocking any attempt to implement Continuous Delivery,
2. We chose BPMN2 as a standard way to reflect business processes into a graphic diagram, helping BAs, designers and development engineers to better understand how business works.
3. We created some basic diagrams using Eclipse BPMN2.
4. We included some scenarios into the description of the activities in the diagrams, always under the strict principles of the Gherkin syntax.
5. We arranged the project as a conventional Java/Maven layout in order to be able to package, store and distribute the versions of the BPMN diagrams to reflect the changes into them made by business or the BAs. The distributed artifact will be used by the BPMN Automation component to read the diagrams.
   

What's Next?

In the next post we'll have a look on the BPMN Automation component that will handle the BPMN files to create, correlate and write to JIRA all the features enclosed into the diagrams. This component interacts with JIRA to keep the features and scenarios up to date as well as to tell the Delivery Platform  to run all the build pipelines regarding the involved software components to check the most recent compliance between requirements and implemented features.

We're a little bit  closer to automation now!