White Paper

White Paper

Automatic review of requirements

Motivation

Requirement validation is one of the four main activities of requirements engineering. The aim of this review is to ensure at an early stage that the (document) requirements on the one hand meet the actual wishes and needs of the stakeholders and on the other hand have the necessary quality to enable further development activities such as design, implementation and testing to be carried out successfully.

According to the International Requirements Engineering Board (IREB), the content, documentation and consistency of requirements are to be ensured during the audit. For this purpose, different quality criteria are used for the inspection, which either refer to individual requirements or to the total quantity of requirements. The main criteria include the following

  • Content correctness and necessity of every requirement
  • Consistency, i. e. consistency and uniformity of requirements
  • Completeness of the total required quantity
  • Completeness of the description of each individual requirement
  • Traceability and traceability of requirements
  • Clarity in the formulation of requirements
  • Testability of each requirement
  • General comprehensibility of the requirements

Although specific notations, description templates and best practices for writing good requirements have existed for many years, many companies still find it difficult to adequately capture, document and manage their requirements with regard to these quality criteria. According to the RE-Compass 2014/2015, even among RE-affine companies, more than 50% of the respondents complain about the unambiguousness and completeness of their requirements.

In particular, but not exclusively in client-contractor-relationships, the examination of requirements plays a central role because subsequent corrections – even in the case of agile development – are often associated with considerable costs.

However, however important and purposeful the systematic examination of requirements may be, it is rarely possible to establish them in practice in many companies for organisational or temporal reasons. Requirements are therefore only reviewed on an ad hoc basis, if at all, or only clarified if there is uncertainty among the developers or other project participants. Even if this – fortunately – can often prevent a completely erroneous development at an early stage, in this case unnecessary coordination and correction loops arise which often confuse the budget and time schedules of projects.

Due to the increasing digitization, especially of software development activities themselves, the question arises for a reliable automation of quality assurance. Therefore, this article describes the current possibilities and limitations of the ReqSuite® Quality Checker for this purpose.

ReqSuite® Quality Checker

Sample messages of the Quality Checker

ReqSuite® is a modern requirements management software that aims to make the inherent complexity of procurement and development projects manageable for all project participants in order to reduce risks and significantly increase the efficiency of projects. In contrast to other requirements and project management tools, ReqSuite® offers sophisticated assistance functions to support users in the capture of requirements, also with regard to content and language.

The Quality Checker is one of these assistance functions within ReqSuite® and is used to

  • incompleteness or over-specification in the total set of requirements
  • imprecise and incompletely specified requirements
  • as well as contradictions and duplicates

at the push of a button. For customers who already use another requirements management tool and do not want to switch to ReqSuite® completely, the latter part of the ReqSuite® Quality Checker – the ReqSuite® “Language Checker” – can also be used and connected via a Web API. Currently German and English are supported.

The individual test options of the ReqSuite® Quality Checker are presented below using examples.

Detection of incompleteness and over-specification

Conceptional incompleteness and overs-pecification

Incompleteness in the total set of requirements occurs when important requirements are completely forgotten by the stakeholders and therefore not included (incompleteness of content) or when requirements imply further requirements and these are missing (conceptual incompleteness).

This conceptual incompleteness, on which ReqSuite® is currently focussed, can only be recognized in a context-specific way. For example, if application cases are specified, but the resulting detail requirements are still missing, this can only be recognized if you are aware of the context-specific dependency on application cases and functional details.

Especially since requirements of different types are usually contributed by different people, manual recognition of conceptual incompleteness is often challenging. Without an automatic check, it is therefore difficult to adequately control the requirements analysis, which often leads to late requirement extensions with corresponding effects on the overall project. The ReqSuite® Quality Checker was therefore developed with this in mind and can interpret contextual knowledge at runtime and apply it to specified requirements.

In addition to conceptual incompleteness, however, over-specifications often lead to documents that unnecessarily endanger the cost and time frame of projects. For example, if a departmental component was included in the requirement set by a special function, but if the function was discarded in the meantime, it makes no sense to take this departmental component even further into account. Accordingly, over-specifications must be eliminated at an early stage in order to avoid unnecessary or even counter-productive project work.

The ReqSuite® Quality Checker can therefore detect such over-specifications and suggest corrections at the touch of a button.

Detection of imprecise and incompletely specified requirements

Imprecise requirements

The best known and most problematic category of problematic requirements are undesirable or incompletely specified requirements. The difficulty here is that you get the impression, both in writing and in simple reading, that you know exactly what is meant and only become aware of existing inaccuracies when dealing with the requirements in detail.

The inaccuracy of a requirement is usually due to the use of generally vague terms and words that cannot be interpreted unambiguously without quantification or detailing. Some examples are given below.

  • “Excel Export: The system should be able to export data to Excel if possible.” –> Is this mandatory or is this an optional requirement?
  • “Travel process: The supplier must map the travel process in the same way as the publication approval process.” –> the same process again or how?
  • “Performance: The system should be faster than the old one.” –> how fast is this?
  • “Reliability: The system must have better availability than before.” –> and how high should this availability be?
  • “Response time: The system should respond to each user input in a few seconds.” –> and how much are a few? 2,3,5,10?

Recognizing that a requirement is not precise is not always easy, because even small changes to a sentence already make the requirement precise. It is therefore very important for an automatic check to understand these nuances in texts and to be able to recognize differences between good and bad requirements. During the development of the language checker, rules for good requirements (e. g. on the basis of sentence templates) were not implemented, but rather experiences with bad requirements from more than 50 industrial requirement specifications of different industries were consolidated.

Incompletly specified requirements

In addition, an incomplete specification of individual requirements usually results from the lack of an actor (subject) and the lack of necessary information when using certain verbs. Here are a few examples:

  • “Result display: If the search was successful, the system should display the results to the user.” –> in which window and in which form?
  • “Data plausibility check: The system must validate the entered customer data.” –> by what rules and with regard to what?
  • “Data export: When the process is complete, the customer data must be exported.” –> automatic or at the push of a button? from where? to where? in which format?

A review of requirements for incomplete specification therefore requires an intensive analysis of sentence contents. The more contextual knowledge a reader has, the less noticeable are the corresponding phrases, since the gaps in content are filled by their own knowledge (or implicit assumptions). Therefore, automatic test methods that implement a thorough knowledge of a complete sentence structure can help here. The ReqSuite® Quality Checker is trained exactly for this purpose.

Requirements that are not recognizable as such

Another problematic case – which unfortunately can be found in a large number of requirement documents across all industries – is not the description of requirements as a clear requirement. Instead, factual statements are made in the presence of the reader, where it remains unclear whether the status quo or a desired target state (and thus a requirement) is described here. Particularly when heterogeneous forms of description are used in the total set of requirements and a clear requirement can be identified in the next sentence, the question arises as to whether other formulations are also a requirement. Here are some examples:

    • “Notification: After the reservation, the system sends a message to the user.” –> is that already or is it still to be implemented?
    • “Response time: The system responds to 98% of all requests in less than 1 second.” –> is this the case today or is it a requirement?
    • “One-off payment: A contract can also be concluded against a one-off payment.” –> is that already the case today? is this a new regulation? and if so, has it to be implemented in software?

The ReqSuite® Quality Checker also supports the recognition of such formulations.

Recognition of contradictions and duplicates

Contradictions between requirements inevitably lead to misunderstandings, clarification rounds or even late surprises, as long as the developers do not notice the contradiction at an early stage and only one variant of the requirements is seen and implemented. Example:

  • “The system must allow all users to maintain customer data.” vs.“The system may only allow the administrator to maintain customer data.” –> which of these is to be implemented?

Duplicates also pose a risk for the formation of such contradictions (e. g., if only one part of the text is changed and its duplicates remain unchanged); on the other hand, repetitions make it more difficult to read the entire requirement document, but they only inflate it unnecessarily.

In the ReqSuite® Quality Checker, therefore, contradictions and duplicates can also be detected. ReqSuite® currently uses text similarity analysis algorithms. In the long term, however, contradictions should also be detected on a semantic basis, so that even inconsistencies in the use of different terms can be reliably detected.

Conclusion

The examination of requirements is essential in order to ensure that costly rework can be prevented in the further course of the project. A clean requirement analysis without final validation of the results is therefore a “wasted love effort” and mostly torpedoes the goals that one wanted to set oneself through systematic requirements engineering. While the substantive examination of requirements can still only be carried out by stakeholders (“is this what I really want?”), all quality aspects of the documentation can be checked automatically and thus secured at an early stage. This significantly reduces the time and effort required for subsequent enquiries and, in particular, reworking.

With the ReqSuite® Quality Checker, such automation is available for the first time in a commercial requirements management tool. As a result, users using ReqSuite® as a tool for their requirements management can immediately benefit from a variety of helpful checks. Other interested parties can at least check the requirements for linguistic quality using the ReqSuite® Language Checker via a web API, so that these tests can also be integrated into other tools.

White Paper

A method for flexible, tailor-made requirements processes

Abstract

Recent studies show that many companies are still struggling to carry out efficient and effective activities in the field of requirements engineering. Company-specific, tailor-made requirements processes have great potential to meet this challenge. This paper describes a novel approach that enables the semiautomatic definition of company-specific requirements processes and the use of tools to achieve a more sustainable and, above all, more valuable implementation of this discipline.

Introduction

The RE Compass 2014 / 2015 [1] has shown that a large number of companies are still confronted with fundamental questions in the field of requirements engineering, such as:

  • What level of detail of requirements is appropriate/necessary? (69% of the companies surveyed)
  • What types of requirements must be collected? (37% of the companies surveyed)
  • How can the requirements be collected and documented in a meaningful way? (35% of the companies surveyed)

These ambiguities lead to ambiguous and incomplete specifications in almost half of the companies, with correspondingly negative consequences within the projects[1].

Although existing literature and training [2][3][4][4] offers good best practices for the collection and documentation of requirements, the above-mentioned questions can often only be answered in a context- or company-specific manner. This results in a high potential for tailor-made requirements processes to ensure an effective and efficient mode of operation during the requirements assessment and documentation in the respective company environment.

However, companies face numerous other challenges in implementing and successfully implementing such individual processes, such as the

  • Defining a meaningful elicitation order for requirements,
  • Easy feasibility of the elicitation and documentation tasks by the project participants (particularly for those involved without in-depth expertise and experience in requirements engineering)
  • Relief of purely administrative, non-value-adding activities in requirements engineering, such as linking requirements,
  • Mapping of defined procedures into tools for requirements engineering without sacrificing flexibility.

Especially with regard to the last point, it is worth mentioning that standard office applications such as MS Office® are still used for requirements documentation in around 80% of all companies[1]. On the one hand, these products are popular because they are well known and widespread and offer a simple, familiar use. On the other hand, the use of such standard software often pushes you to the limits when it comes to making work steps during requirements assessment and documentation more efficient. If these products are not to be completely replaced, this must also be taken into account when tailoring requirement processes.

This article introduces a tool-based approach that optimizes the introduction and execution of bespoke requirements processes in companies. The aim of this approach is to be able to carry out company-specific requirements processes effectively and efficiently, but also to address the special challenges arising from this during the introduction in a targeted manner. The innovative tool “ReqSuite®” is used for this purpose, with the help of which individual requirement processes can be mapped conceptually and processed with the help of common office software.

A tool-supported methodology for the introduction and implementation of flexible, tailor-made requirements processes

The method for the tool-supported introduction of customized requirements processes consists of a total of four steps (see Figure 1), which are explained in more detail below. It should be noted that the first three steps are one-time steps for setting up a requirements process and therefore usually only have to be run through once. Step 4, on the other hand, is carried out several times, i. e. once per project.

Abbildung 1. Schritte der Methode zur werkzeuggestützten Einführung maßgeschneiderter Anforderungsprozesse
Figure 1. Steps of the Method

Step 1 – Determine information and documentation requirements: In a workshop, the individual information requirements in typical RE projects are first determined together with the RE participants of the company. These could be, for example, specific requirements types, domain-specific requirements structures, and other information that should be contained in the requirements documents. To do this, the current RE process is first analyzed. This can be realized in the workshop, for example, by means of map queries in which all participants present their activities as well as the required and delivered information during the creation of the requirement specification. Interfaces to downstream processes such as change and test management can also be identified and analyzed. In addition, existing requirements documents are considered in order to identify further information requirements. In addition to content, the study also looks at description templates and notations that have become established in corporate practice or which could be usefully used in the company in the future. In order to optimize the entire requirements process, expert knowledge and established best practices from the literature are included in addition to any suggestions for improvement made by the company’s stakeholders.

Step 2 – Derive Requirement Structure: In the next step, the analysis results are documented using a domain-specific language. In the first step, the structure of the requirements types and accompanying information is mapped. For example, you can define that system functions are always used in application cases that support business process activities in business processes (see figure 2).

Abbildung 2. Beispielhafte Abbildung einer einfachen Anforderungsstruktur
Figure 2. Example of a Requirements Structure

The mapping of this structure is not only important and useful for ensuring the traceability of the requirements, but also provides a decisive basis for subsequent process support (see step 4). This model thus forms the logical “thinking model”, which stands behind the requirements process and which has to be filled with content within the framework of a concrete project.

Based on the results from step 1, you then define for each requirements type or information module how the documentation of the corresponding requirements or information is to be carried out within the framework of a project. Among other things, it is determined whether the description is to be textual (e. g. by means of certain natural language typesetting templates) or graphical (e. g. by means of UML models) and which attributes (e. g. priority) are to be maintained for the different requirement or other content types. In the example in Figure 2, for the requirements type “business process”, for example, it could be defined that each process to be described in the requirement specification can be described using a graphical process description, such as BPMN, and is also to be specified by means of a short tabular description using various attributes.

The formalized description is imported into the ReqSuite® tool and automatically transformed into an adaptive requirements workflow. In addition, a company-specific template of the requirement document is stored in the tool, into which the actual requirements and contents can be exported later at the push of a button. The user can specify, for example, which content from the database should appear in the document in which form. Due to this strict separation of content and representation, requirements can be recorded and documented differently than they are ultimately represented in the requirements document. Accordingly, several templates can be stored if, for example, different documents are to be created from the data at a later date (e. g. a requirement specification and a test specification).

Step 3 – Importing existing requirements: In many companies, systems are not developed from scratch, but are continuously being expanded and enhanced with new functions. This is also reflected in the corresponding requirement process, as requirements from old projects can or even have to be reused. This pool of existing requirements should be used to create an explicit reuse basis for future projects in order to increase efficiency, in order to avoid the risks of a clone-&-down approach. Relevant requirements from old projects are identified by examining old requirement documents, for example. The requirements should be checked for up-to-dateness so that no obsolete requirements are adopted. Because building a reusable base is very time-consuming, ReqSuite® can be used in this step to automatically import requirements from Word or Excel documents into a central reusable library in an appropriate form.

Step 4 – Execute Requirements Engineering Process: The actual execution of the requirements process is based on work steps that are dynamically defined at runtime and provided to users by the ReqSuite® tool. Unlike conventional requirements management tools [5], ReqSuite®, which is integrated into Microsoft Office® products on the client side (see Figure 3), supports not only the specification and management of requirements, but also the entire process of elaborating requirements in terms of content.

Abbildung 3. ReqSuite® Client in Microsoft Word
Figure 3. ReqSuite® Client in Microsoft Word

The algorithms of ReqSuite® are based on expert knowledge and are able to propose a sensible sequence for the elaboration of the relevant requirements. At runtime, the tool generates a set of precise work instructions for each process step in the so-called Process Guide (see lower part of Figure 3) in order to guide the project participants step-by-step through the individual elicitation and documentation tasks. Comparable to programs for preparing tax returns, the tool ensures that the resulting requirements contain complete content in the desired form by continuously querying and quality checking the desired information.

The process is not static, but the tool always acts adaptively throughout the entire application, which means that a sequence of work steps does not have to be defined in advance or followed exactly. Instead, the work steps are adapted at runtime on the basis of the requirements already established. This takes into account the fact that, due to the fast-moving nature of projects, processes of requirements cannot be formalized in the form of rigid processes anyway, but seldom correspond to the desired procedure of the project participants in the requirements analysis.

The agents can therefore ignore the recommended steps at any time and carry out other processing operations independently. For this purpose, ReqSuite® provides the so-called Content Manager (see right-hand part of Figure 3), in which the requirements, as well as other information content and its relationships can be created and maintained. However, the tool always suggests the most sensible next step – based on the known options for further procedure and taking into account any limitations.

This process support helps in particular also project participants without relevant expertise in requirements engineering to contribute to the creation of requirement documents in a purposeful way. A project progress display always shows the current status of the requirements elaboration.

The details for requirements are entered directly in Microsoft Office® or via pop-ups provided by ReqSuite®, which are based on the previously stored configuration for the respective requirement type. In each step, the individual requirements and entire requirement structures can also be imported from other projects or from the reuse base in order to considerably speed up the use of existing documentation.

Practical Experience

Especially for companies that often deal with special topics or outside RE standards in their project business, a high degree of individuality in their requirements processes is crucial for achieving acceptance of requirements engineering by both their own employees and the customer.

The high adaptability of the approach described here, coupled with its systematic guidance for pilot customers from various industries, has already enabled more efficient project work.

This was due in particular to the fact that the individually configured tool enabled requirements to be collected and documented in a more complete and consistent manner, which meant that fewer queries were necessary due to incomplete or unclear requirements. In particular, employees who had little practical experience in requirements engineering to date could benefit from the approach to improve their own tasks by focusing on essential aspects of content. This is a significant support for companies, as requirements are often collected and documented using very different approaches in practice – depending on the framework conditions and the availability of stakeholders.

At HK Business Solutions, for example, it was shown that even inexperienced employees can be systematically supported in a structured procedure with a top-down approach by means of adaptive process instructions. This begins with activities that have to be settled very early in the development process, e. g. the creation of product visions and the definition of system context and scope, and ends with the consistency and completeness check of all created requirement artifacts. Many errors that typically arise due to incomplete, misleading or incorrect requirements can be avoided by this support and the systematic re-use of requirements that have already been recorded and quality-assured.

Measurable value of the approach is therefore a higher completeness, quality and uniformity of requirement documents and a consequent saving of effort in the overall project or in maintenance and support costs. This is a significant added value in that, according to RE-Kompass [1] incompleteness and inconsistent level of detail in 48% and 69% of all companies, respectively, represent the greatest shortcomings of requirements documents at present.

Even though the effort for the requirements process can hardly be reduced due to the structured approach, all users confirm that their tasks in the requirements analysis could be simplified and accelerated considerably. The introduction of the new RE approach is facilitated by the fact that the approach is based on familiar standard office software, which made it easy to roll out and allowed users to quickly find their way around. Successive management through various steps of the process also helps to better internalize the individual corporate approach in requirements engineering.

Conclusion

Tailor-made requirements processes are indispensable for successfully embedding the topic of requirements engineering in companies. However, defining and implementing such business processes is an additional challenge for many companies. This article therefore proposes a novel, tool-supported approach to support bespoke tailoring and subsequent application of individual requirements processes.

References

  • Adam, S., Wünch, C., Seyff, N.: RE-Kompass 2014/2015 – Ergebnisbericht, http://www.re-kompass.de
  • Pohl, K., Rupp, C.: Basiswissen Requirements Engineering, dpunkt (2011)
  • Rupp, C.: Requirements-Engineering und -Management: Aus der Praxis von klassisch bis agil, Carl Hanser (2014)
  • Wiegers, K., Beatty, J.: Software Requirements, Pearson Education (2013)
  • Birk, A., Heller, G.: List of Requirements Management Tools, http://makingofsoftware.com/ re-sources/list-of-rm-tools

Authors

Dr. Norman Riegel is Managing Director of OSSENO Software GmbH and is primarily responsible for consulting, quality assurance and administration. He is an IREB-certified Requirements Engineer and works as a trainer for CPRE. Prior to founding OSSENO Software GmbH, he worked as a consultant, trainer and scientist for requirements engineering at Fraunhofer IESE. Parallel to his work, he also earned his doctorate at the Technical University of Kaiserslautern on the subject of “Efficient requirements assessment based on business processes”.

Dr. Sebastian Adam is Managing Director of OSSENO Software GmbH and is responsible for product innovation, marketing and sales. He is an IREB-certified Requirements Engineer and works as a trainer for CPRE. After his studies in Applied Computer Science, he worked for ten years as a consultant, scientist and team leader for Requirements Engineering at Fraunhofer IESE and at the same time did his doctorate at the University of Kaiserslautern on the topic of “Reusable Requirements Survey”.

Hartmut Schmitt is coordinator of research projects at HK Business Solutions GmbH. Since 2006 he has been working in collaborative projects in the fields of human-computer interaction, usability, user experience and requirements engineering.

White Paper

Requirements Management with JIRA and ReqSuite®

Introduction

Requirements management with JIRA

Atlassian’s JIRA has made a remarkable entry into a variety of companies over the past few years and it is more than a feeling that almost every company in which software development plays a role now uses JIRA (or similar products like Microsoft’s Team Foundation Server). Originally used as an application for error management, problem solving and operative project management, more and more companies use JIRA for task and requirement management within the (agile) software development. Meanwhile, meanwhile, evil tongues are not wrong to claim that JIRA is the new Excel, i. e. a tool with the company trying to kill as much as possible.

With regard to requirements management and other requirements engineering tasks, the question arises justifiably as to what benefits JIRA can provide in this environment. JIRA offers basic features for requirements management and can therefore keep up with explicit requirements management tools (RM tools) in many aspects. However, more and more companies are discovering that the use of JIRA (or similar tools) does not automatically lead to project success or that communication between the department and IT can only be improved to a limited extent. If there is no sufficient methodological basis for the project participants, the old saying “A fool with a tool is still a fool” or the even more drastic insight “Shit in, shit out”is also used in this context.

Without a doubt, JIRA offers excellent opportunities for task management and status control before, during and after development. But to know which tasks have to be done (that is, which requirements require implementation in a certain sprint or release) takes more than that. Good requirements engineering still includes core issues such as

  • Who are my stakeholders?
  • What are their needs?
  • Which system properties and capabilities (requirements) result from this?
  • How important are these requirements in each case?
  • What is the relationship between the requirements and what kind of refinement is there between them?
  • Have we forgotten important requirements or have we not specified them sufficiently?
  • etc.

Established tools on the market can hardly, if at all, answer this question. The benefit of JIRA, but also other well-known RM tools in terms of the quality of the requirements, therefore still depends solely on the individual expertise of individual project participants.

The Requirements Management Tool “ReqSuite®”

With OSSENO’s ReqSuite® (see Fig. 1) a tool for requirements management has been presented in the past few years, which also supports content-related and methodological questions and can ensure the quality and completeness of requirements from the outset by means of intelligent assistance functions. Similar to a program for the preparation of income tax returns that helps inexperienced individuals to create accurate and complete standardized tax returns, ReqSuite® offers concepts to develop (sufficiently) good requirements documents in a standardized manner, regardless of personal expertise in the field of requirements engineering. The ReqSuite® Assistant also offers assistance in answering the above-mentioned core questions and points out incompleteness or inconsistencies directly during the documentation of requirements. The phrase “A fool with a tool is still a fool” therefore has only limited effect in this context.

Fig. 1: Screenshot of ReqSuite®

The advantages are obvious and have already been confirmed by a large number of customers: ambiguities and incompleteness leading to costly rework before, during or even after development are proactively reduced. At the same time, there is always an overview of aspects that are not yet sufficiently clarified, which is crucial for success (unless they are developed in a waterfall-like way), especially when determining parallel to the analysis of running sprints. Finally, ReqSuite® automates formulations and formatting so that users can focus on the content of requirements rather than their syntax. This not only creates more freedom for thematic work, but also increases the acceptance of requirements engineering as a whole, which is often perceived as heavy and antiquated.

But should you now switch off your established JIRA and only work with ReqSuite®? Clearly no! Even if the correct answer always has to be answered in individual cases, it can be said that JIRA offers a large number of valuable features for many steps in software development that ReqSuite® has not yet been able to adequately replace. Nevertheless, ReqSuite® offers enormous added value for requirements engineering and similar disciplines, which JIRA and its extensions and accompanying tools such as Confluence cannot sufficiently achieve.

Accordingly, it is promising to highlight the joint and integrated use of JIRA and ReqSuite® in the following.

Methodical Integration

The methodical integration of JIRA with ReqSuite® is highly dependent on the business and development context. This concerns on the one hand the subject of development (e. g. the further development of an existing system in an insurance company vs. the development of a tax module in mechanical engineering) and on the other hand the scope of development activities (e. g. project vs. portfolio).

Nevertheless, the following best practice can be postulated for integration:

“ReqSuite® manages the content (including requirements) and JIRA manages the tasks within a portfolio or project.”

According to this best practice, it makes little sense to copy the contents of ReqSuite® from JIRA to JIRA one-to-one and create a redundancy in both tools. Rather, an abstraction level of content should be defined, which can be used as a suitable starting point for synchronization.

The main challenge in methodological integration (but also in general in defining a clean methodological approach) is therefore to define the refinement structure of content from requirements to the level of development activities. As a rule, there is no general model for this, since this structure depends to a large extent on the object of development. In the environment of an enterprise information system, this structure could, for example, contain requirements with regard to business processes, organizational units, use cases, system functions, business data and interfaces, which would have to be appropriately mapped to corresponding development activities (see also our WhitePaper on the definition of customized requirement processes).

Therefore, only an abstract refinement structure can be shown for the purpose of this article, which represents a possible division between ReqSuite® and JIRA (see Fig. 2).

Fig. 2: Concepts to be reflected in ReqSuite® and JIRA

In accordance with this model, ReqSuite® includes information about stakeholders, their context, their needs and the resulting topics, projects and requirements. In addition, JIRA maintains the development activities resulting from the requirements. Projects and project participants can be maintained redundantly in both tools.

If stakeholder requirements are now reported, they are specified in ReqSuite® in the form of topic descriptions within a corresponding portfolio. After appropriate examination and prioritisation of the topics, portfolio or programme managers can then map them to specific projects. Within projects, ReqSuite® then offers the abovementioned assistance functions to provide appropriate support to the project participants in gradually and quality-assured elaboration of the project requirements, taking into account the context.

At any time, but also at defined points in time, automated development activities (tickets) can be derived on the basis of requirements and exported to the associated JIRA project. If configured, an automatic assignment to the project participants responsible for the conversion can also be carried out. Once you have completed your tasks, you can then update the status of your activities, which is then automatically reflected back to ReqSuite during the next synchronization, thus documenting the fulfillment status of the requests.

An important question at this point, however, remains how individual (system) requirements can be mapped to development requirements for the respective development activities. This also depends on the development context. In the above example, it would be conceivable to gradually break down business requirements over different abstraction levels such as business processes and use cases to the level of fine-grained system functions, which also represent the content of individual development requirements. For example, the request “As a life insurance administrator, I would like to see the surrender value of a contract on the contract overview, so that I can inform the customer more quickly”. from ReqSuite® as a development requirement (ticket) in JIRA and the resulting development activities are implicitly visible to the developers. Alternatively, however, it would also be possible to further refine the requirement in actual activity descriptions such as “Extension of mask LV-1 by a read-only field surrender value”. The latter would have the disadvantage of increased specification efforts, but the advantage of a more precise task description and a finer granular tracking.

Technical Integration

One of the main arguments, which is sometimes used against the use of several tools, is integration and consistency problems. If data can only be exchanged manually or only partially automated between different tools, this is not only a hindrance to efficiency, but also an enormous source of error. In addition to methodical aspects of integration, the technical integration capability also plays a decisive role. The technical integration of JIRA and ReqSuite® has therefore been designed to be multi-stage, dynamic and bi-directional.

Multi-level integration

At the top level of integration, projects in ReqSuite® are linked to corresponding projects in JIRA in the form of a 0.0… 1 relationship. For each project in ReqSuite®, max. a project can be stored in JIRA. Conversely, several ReqSuite® projects can synchronize content with a JIRA project. The reason for this asymmetrical relationship is that ReqSuite® wants to define a clear “buyer” for the requirements. Conversely, however, a JIRA project can consolidate content from different ReqSuite® projects, as the customisation within the development process may be organized differently than at the technical project level within the topic portfolio. Fig. 3 shows, for example, that the “IT requirements” project from ReqSuite® is to be synchronized with the “ReConf2017” project.

Fig. 3: Mapping of a project and its corresponding requirements types

At the second level of integration, the requirement types from ReqSuite® are linked to issue types in JIRA in the form of a 0.0… 1 relationship. In each project, you can define whether the requirements of a certain type of ReqSuite® should be exported to JIRA and, if so, which issue type. In the above example, you could specify that only requirements of type “Function” should be synchronized with JIRA (see Fig. 3) in the form of issue type “Task” (see Fig. 4).

On the third level of integration, a fine-grained attribute mapping between ReqSuite® and JIRA can be defined. In addition to a standard mapping (Name -> Summary and Description –> Description), you can also set very individually how individual fields from ReqSuite® are related to JIRA fields. The project participants can also be mapped automatically, so that the assignees responsible for implementation can be defined in JIRA in ReqSuite®.

Fig. 4: Mapping of requirements types to issues types (and corresponding attributes=

Dynamic Integration

When integrating ReqSuite® with JIRA, great importance was attached to flexibility and configurability. Consequently, the interface was developed in such a way that hardly any static mappings were predefined, but can be completely selected at runtime. The integrable projects, requirement types, issue types and attributes in both ReqSuite® and JIRA are determined dynamically at runtime and can then be related to each other. This means that it is also possible to include custom types and custom attributes, i. e. self-defined types and fields, in the mapping.

Bidirectional Integration

Bidirectional integration means the possibility of not only transferring content from ReqSuite® to JIRA, but also reflecting it back as required. When configuring the interface, you can therefore define whether a (bidirectional) synchronization or only a (unidirectional) export of ReqSuite® to JIRA is required. In the case of a real synchronization, the interface is able to merge changes on both sides or, in the case of a conflict, to resolve them automatically on the basis of stored rules. This virtually eliminates friction losses due to inconsistencies.

When does Integration make Sense?

The integration of JIRA and ReqSuite® can bring many advantages for requirements engineering and management. In concrete terms, the use of ReqSuite® in addition to JIRA makes sense, especially in the following cases.

If quality or completeness of requirements are inadequate

If the quality, completeness or standardization of requirements is not satisfactory, ReqSuite® offers excellent possibilities to remedy this. This is often (but not only) the case when technically less experienced colleagues from specialist areas are involved who have little experience with writing good requirements. Having them write their wishes and requirements directly in JIRA or upstream tools such as Confluence without assistance, usually brings with it a lot of advantages. and costly clarifications and adjustments are unavoidable.

If documents are needed in addition to tickets

In many organizations, various documents are needed for project work, even if the project is to be developed in an agile way. By separating content and representation more neatly in ReqSuite®, ReqSuite® can automatically generate all required documents and reports such as project applications, technical concepts, IT concepts, acceptance concepts, offers, etc. in the desired corporate design at the push of a button. JIRA is very limited in terms of the generation of such documents.

If a good cooperation between business and IT is desired

If a good cooperation between the department and IT is desired, a clear separation of content descriptions and development-relevant tasks makes sense. In particular, it is necessary to address the language of the departments appropriately (think, for example, of processes, tasks and documents) and to abstract from technical details or concepts. A further advantage of the separation of content and development task is that concrete development tasks, which are usually not only restricted to the development of the content, but also to the content and development task, can be carried out. only have to be carried out once in the context of a concrete project, can be clearly separated from the content implemented therein, which may be repeated across projects (e. g. data glossaries).

If project participants cannot or do not want to work with JIRA

Even though JIRA is quite easy to use, it is still a developer-to-developer tool for developers and not a tool where department staff feel at home. Especially when it is unclear what the requirements are and how they can be derived systematically, it is not enough to define simple templates for Epics and user stories, for example, to determine the needs of the departments appropriately. Here it makes sense to support the respective work by means of target-group-specific entry masks and assistance functions. While this is a time-consuming and costly process to implement in JIRA, ReqSuite® comes with simple yet powerful features.

Conclusion

The success and benefits of JIRA are undisputed and should not be diminished in any way in this article. Nevertheless, the use of additional tools is desirable, especially in the case of cross-departmental cooperation, especially on the part of the departments. Much sought-after products, which are often advertised in a bundle with JIRA, do not offer any real work assistance for project participants and often do not represent more than a web-based Word alternative; with all the advantages and disadvantages known from working with Office products up to now. To the extent that the above-mentioned aspects exist, additional use of ReqSuite® as a comprehensive and, above all, content-focused portfolio and requirement tool should therefore be considered.