Open Requirements Management Framework
The Open Requirements Management Framework (ORMF) Project is a proposed open source project under the Eclipse Technology Project.
This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process document) and is written to declare its intent and scope. This proposal is written to solicit additional participation and input from the Eclipse community. You are invited to comment on and/or join the project. Please send all feedback to the http://www.eclipse.org/newsportal/thread.php?group=eclipse.technology.ormf newsgroup.
The goal of the Open Requirements Management Framework (ORMF) is to extend the Eclipse platform to create an open source framework for building Eclipse based tools which facilitate working with structured requirements. ORMF is focused on structured requirements, as opposed to free form ones. However, to avoid pedantic repetition, please read "structured requirements" for each occurrence of the term "requirements".
ORMF will be a solid multi-tier framework that will enable the Eclipse platform to support creation, development and management of disparate types of requirements by utilising a common set of services, patterns and mechanisms. Ultimately, it will enable analysts and requirements specifiers to collaboratively build valid, complete and resilient requirements models for their projects, while allowing the other team members or, more generally, all stakeholders in the projects to be active participants of both formation of the requirements and their subsequent maintenance imposed by evolution and change.
The framework will develop the infrastructure, components and services that will support the development of the specialised tools. It will be comprised both of a client component, which will be based on the Eclipse platform and will consist of Eclipse plug-ins, and of a server component. The server component, built on top of Java 5 Enterprise Edition (initially Glassfish), will contain all the necessary infrastructure as well as the modules that are required for the publication of the requirements documents in a variety of formats.
With Eclipse's role as a unifying platform for all development tools that tackle the entire life cycle of a software project, the need for a tool that guides practitioner in the capture and maintenance of requirements, as well as sophisticated reporting and multiple views into the requirements model, appears large and immediate to us. Our proposal for ORMF aims at fulfilling this need, as well as facing issues with the process of requirements gathering and management that we perceive in today's practices. These issues are covered in the Background section of this document.
Substantial portions of the framework have already been built by Etish Limited, along with an exemplary tool for ORMF, Useme, which allows analysts and requirements specifiers to define use case based requirements in a consistent and harmonious fashion. Etish Limited will offer the existing code for ORMF and Useme to this project, if accepted by the Foundation. Whilst our vision includes ORMF features that still require considerable thinking and exploration and will no doubt involve design and implementation challenges, the fundamental framework mechanisms and components are already in place and experience shows us that building tools such as Useme on top of ORMF is a straightforward and approachable endeavour.
During our consulting experience, we at Etish Limited have uncovered a set of needs that we have perceived time and time again whilst helping our clients organise (or, in many cases, reorganise) their requirements in a rational and usable fashion. In a nutshell, we could summarise these needs as the great difficulty of creating and maintaining robust, correct and consistent requirements without an excessive expenditure in time and commitment. We have observed this irrespective of the specific technology chosen by the clients for this purpose, whether one of the commonly available automated requirements management tools or manual capture and maintenance.
The main problems with requirements capture and management today, as we see them, are the ones outlined below.
- Free form documents
- Most organisations rely on requirements documents that are ultimately free form text documents. This often leads to document incorrectness and inconsistency.
- Gap between UML model and textual specification documents
- The model describes requirements as simple elements (for example use cases and actors) and the structural relationships between such elements (for example use case inclusion). The specification documents describe the details of each specific requirement but frequently loose the connectivity of the model due to the difficulty of capturing and subsequently maintaining structural relationship within a textual context. The two types of artefacts therefore tend towards being mismatched and inconsistent.
- Difficult document maintenance
- Even in cases where at least the most important of the relationships are captured in the textual documentation, the task of maintaining them by hand through requirements evolution and change is daunting for the amount of time and effort that is needed.
- Single user requirements capture
- Except for very expensive, high end requirements management tools, most other automated systems (or indeed manual capture!) are single user, making it difficult for all the project stakeholders in general to share the information expressed in these documents.
- Non integrated requirements management
- All requirements management tools available today are standalone applications, with their own user interfaces and their own utilisation rules and procedures, with the well known shortcomings of a non integrated development environment.
ORMF is aimed at resolving these issues.
Scope and Objectives
ORMF's objectives in a nutshell
To understand ORMF it is essential to recognise that its notion of requirements has two facets. There is the "artefact" view which is how most requirements practitioners perceive what is being created and managed; this is the document centric view. Then there is the "model" centric view which is structured, organised and precise. ORMF goes to great lengths to give the practitioners the impression they are working with documents while in fact the system is building highly structured models behind the scenes. This gives ORMF the ability to be quite robust in the way it handles, manipulates and utilises the model, while hiding most of the uncomfortable details from the user.
So in essence ORMF makes possible tools that build entire requirements documentation sets for any given software project. The documentation reflects the underlying requirements model, including the incorporation of all the necessary connectivity elements that are part of the model itself. All documentation is automatically kept up to date against the evolving and changing requirements model. One of the primary intentions of ORMF is to enable a working paradigm that makes it straightforward for tools to provide guidance and validation to the requirements specifiers throughout the requirements management life cycle.
The framework's aim is to foster collaboration among team members by providing the requisite mechanisms and controls that are necessary to a multi-user effort, including immediate exposure of the documentation to all the project's stakeholders through a completely transparent publication process.
A key goal of ORMF is to encourage the development of best of breed Eclipse based tools for the requirements management discipline, thereby expanding and enriching the Eclipse user community to embrace those involved in the requirements domain.
The detailed vision
The main components of our vision for ORMF are the ones outlined below.
Structured model based requirements
All requirements are represented as XML documents, the salient features of each being translated into an XML node. This representation drives the way in which requirements are captured (through specialised form editors) and subsequently presented to the user. The structured nature of the requirements enables any tool that is built on top of ORMF to apply strict validation rules when the requirement is being edited and to guide the user through the compilation of the requirement in order for it to be correct and consistent with the remainder of the model.
It is the goal of ORMF to support existing standards where they are relevant to the issues we are addressing and when it is practical, from a resource perspective, for the ORMF team to be taking on the effort. The OMG, IEEE and ISO all have relevant standards in the space ORMF is targeting; these will be explored and entertained for inclusion. Other standards will undoubtedly be suggested as the project matures.
The introduction of smart links
All requirements models are characterised to a significant extent by the relationships between the various elements composing the model. ORMF will provide an extensible mechanism for representing relationships which can be used, for example, to model such things as UML relationships based upon their stereotype. For any defined type of relationship, the framework will automatically support the creation of smart links, which are a representation of these relationships at the textual level. In this way ORMF will ensure that the connectivity of the model is preserved within the textual specifications, guaranteeing consistency between textual and model based descriptions. These links will be maintained by ORMF automatically throughout the life cycle of the project being developed, through changes to either side, i.e. producer and consumer, of the relationship. This is the reason why we refer to them as being "smart".
The general availability of common requirements related elements
ORMF will provide the ability to capture "cross cutting concerns" -- to steal an expression from Aspect Oriented Programming -- that are common to all types of requirements, such as Glossary, Notes, Risks and Issues. These will be provided for the usage of all requirements built on top of ORMF. In this way these elements can be defined by the user once and then utilised consistently and transparently. Any subsequent modification of one of these elements is automatically reflected in all consumers by ORMF.
The availability of complex views and reports
ORMF will enable specifiers to build and then manage a requirements model by utilising custom editors that are designed to support each specific requirement type. For example use cases and software requirement specifications have quite different shapes, so ease of use is enhanced by catering to each specific requirements type. The framework will also make available meaningful visualisations, including diagrammatic ones, non-trivial views and flexible search and reporting tools that will facilitate the extraction of required information from the model.
We will be exploring an extension of the BIRT framework to provide flexible reporting on requirement traceablity matrices, test matrices and high level project management reports, such as use case grouping by status, by priority, by degree of implementation. All these reports should be flexible in the sense that they should be customisable in their granularity to reflect the specialised needs of the stakeholders they are created for.
Another goal of ORMF is to explore how it can provide useful extensions to the Eclipse modelling projects in order to simplify and add consistency to diagrammatic representations of various requirements views, building on UML [or possibly other pertinent standards] wherever possible.
A rich infrastructure
ORMF will provide a useful infrastructure of common patterns, services and mechanisms. This refers to both an infrastructural layer of services that leverage the Eclipse platform in the client tier and a set of facilities that perform business logic and handle persistence in the server tier.
A collaborative environment
ORMF is geared towards collaborative work at both stages of requirements capture [production] and of artefact creation [consumption].
In the production stage, collaborative features, managed by the framework, will be inherited at no extra cost by all requirement type specific tools built on top of ORMF. These features include authentication and authorisation, automatic processes for synchronisation and conflict resolution of the client and server views of a project, automatic maintenance of the integrity of both the documents and the overall requirements model.
In the consumption stage, ORMF will provide a common engine for the publication of requirements documents in a variety of formats; the engine will be equipped with the possibility of customisation of the look and feel of the final published product.
ORMF will provide straightforward extension mechanisms, both via specialisation of base classes and via extension points, that permit the extension of the framework into requirement specific tools. See the diagram in section Functional architecture below for a schematic indication of the location within ORMF that will accept extensions.
Support for versioning and change control
As part of the development of ORMF, we will explore the issues of version control, baselining and snapshots creation, in order to identify what is needed and what can be done. This is especially relevant when considering the needs of change control in the development process.
Data export facilities
ORMF will provide support for data export into other standard tools, such as UML modellers, project management tools and testing frameworks.
ORMF will include a set of administrative plug-ins that will be utilised transparently by all ORMF based tools. These facilities will enable an Administrator to create and configure requirements projects, to define the participants and the roles of the requirements teams and, finally, to customise documentation artefacts for any given project.
The diagram that follows is a high level representation of our vision for the structure of ORMF, with some of the add-on plug-in tools that it will facilitate. As the diagram shows, we plan to architect ORMF in three tiers, namely the client tier, the server tier and the database tier. Each tier will provide APIs and extension mechanisms that will enable the creation of the add-on plug-ins. These are indicated in the diagram by the components that have a red border. The client tier rests on the Eclipse platform, whereas the server tier is based upon the Java 5 Enterprise platform.
ORFM High Level Architecture
(click image for high resolution PDF)
The client tier
This tier contains all components which deal with the direct production or with the consumption of the requirements.
The consumption portion of the client tier is of no great interest for this discussion as it will simply consist of a suitable program on the consumer's machine, e.g. web browser, Acrobat Reader, Microsoft Word etc.
The production portion of the client tier is a lot more interesting. It is a set of custom Eclipse plug-ins that will be based on a common extension of the Eclipse Platform that provides services of general applicability. Example of such services are:
- the translation of the XML based model elements into/from visual gadgets;
- a common wizard validation mechanism;
- a single pattern for handling views updates upon model changes based upon the well known observer/observable pattern
- common strategies for synchronisation of the contents of the visual components with changes occurring at the server level as a result of other users modifying the project.
The base plug-in is also responsible for acting as the communication mechanism between the client and the server tier.
The client tier will also offer a plug-in containing many common views, wizards and dialogs that will be used by any specialised tool that functions on top of ORMF.
Finally the client tier will also offer the Administration interface for direct usage by all ORMF based tools.
The server tier
The server tier will offer all the business logic and persistence mechanisms that are required to handle users requests coming from the client tier. These services will be mediated by agents located in a Web services layer, which will also be utilised by the publication and reporting engine. The latter will be responsible for the production of publishable documentation for consumption. Any tool that is built on top of ORMF will simply need to add its own document specific contributions to both the business logic components and to the publication and reporting engine, as indicated in the diagram above.
The persistence layer will finally be responsible for any communication with the database tier.
The database tier
Presently the framework is dependent on the Apache Derby database. It will be considered in the future if there is sufficient demand by the community for the database to be replaceable by any SQL compliant datastore.
The first demonstration of ORMF as an extensible framework will be provided by Useme, the set of Use Case based plug-ins that handle the details of use case requirements specifications. Useme already exists as an alpha grade product and has been used internally be Etish Limited on several projects, including Useme itself. In the architectural diagram above, the components that have been developed as part of Useme are the ones with a red border.
More information about Useme can be found in the following documentation:
- An overview of Useme
- An introduction to Useme
- A visual tour of Useme
- The rationale for Useme
- A spin around the block (Flash tutorial)
- A closer look at Useme (Flash tutorial)
Above and beyond the standard platform, ORMF does or soon will utilise the following Eclipse projects:
- Eclipse Modeling Project (EMF, GMF and UML2)
- Graphical Editor Framework
- Business Intelligence and Reporting Tools
To date we have identified collaborative possibilities with:
- Eclipse Process Framework Project
- Open System Engineering Environment
- Testing Tools (functional testing artefacts can be automatically generated from uses cases)
We propose this project should be undertaken as an incubator project with the Technology project.
- Gary Xue, Actuate
- Richard Gronback, Borland
- Harm Sluiman, IBM
The initial committers will focus on delivering the initial production ready release. The initial committers are:
To date the following organisations have expressed an interest in ORMF:
- Fijitsu (UK)
The ORMF newsgroup has been been gratifyingly active for a project still under proposal. The ORMF team wishes to thank all of the people who have taken time to comment on the proposal and share their ideas. It is premature to incorporate these ideas into proposal, but the ORMF team will be considering them all carefully as we scope the 1.0 release. In particular one comment which we have heard so frequently deserves special note in the proposal.
It has been consistently noted that requirements capture tools need to have a Web browser interface. The project leads have not disguised the fact that they consider Web interfaces semi-crippled for sophisticated tools and that they inevitably lead to difficult to use tools with compromised functionality. But alas the world, including a number of the ORMF team, does not share our [elitist?] views. Therefore it is clear that a web interface may well be in ORMF's future.
We are primarily considering several avenues towards growing the developer community.
- It is likely that many consulting service organisations can benefit substantially from both ORMF and Useme. We hope that some of them are interested in working with us towards extending the functionality for themselves and for the community.
- We believe that tools built on ORMF can save a significant portion of the effort it takes to gather and maintain requirements. By exposing Useme to organisations who expend considerable resources on internal development efforts, it should become evident to these entities that contributing to the functionality, richness and completeness of the framework (and of course contributing editor plug-ins) will have a positive influence on the success of their projects.
- We are hopeful that developers in the community will join us simply because what we are delivering is a great framework that helps make building software easier, faster and better.
We are in the very early stages of building a community, yet the limited exposure of our exemplary tool, Useme, to date has produced very positive results. The Useme website on Java.net has regular traffic, we receive information requests regularly and the Useme newsletter has over a hundred subscribers. We believe that once the initial beta version is released this community will grow rapidly.
Etish offers an initial contribution to this project which includes code corresponding to the described architecture. The contribution contains a portion of the features listed above and the first exemplary tool, Useme. We welcome all parties who are interested in contributing further to the project.
- Creation review - 25 June 2008
- Etish Limited donation of initial code base
- parallel IP process
- provisioning - project environment established.
- committers begin work
- Deliver alpha release to community of both ORMF and Useme - 6 September 2008
- gather feedback from community
- scope 1.0 release
- determine what architectural changes are necessary to achieve the 1.0 release
- Deliver project plan for the 1.0 release- 17 September 2008
Both the existing client and server code have been successfully tested on:
- Windows XP SP2
- Red Hat Enterprise Linux 5
- Mac OS X 10.5
- Eclipse Platform 3.3.1 or better
- A Java 5 Enterprise Edition compliant server
For development and testing Sun's Java EE 5 SDK (based on Glassfish) has been utilised. Standards have been observed, so any compliant server should suffice. In fact it is probable that some servers that are only partially compliant will also work, but these servers will have to be carefully tested individually.
High Level Use Cases
Please see the attached list of use cases for the portions of the framework and the exemplary tool that are already in existence.