ICBN_Requirements_Specification

TypeT-76.115 Software Project
Project TopicE-business enabled legacy system
GroupIC Broker
Project PhaseProject Planning
Document nameRequirements Specification
Approved by Alex Alonso28.10.2002
Version historyDante Dionne II05.09.2002

Requirements Specification

Contents

  1. Introduction
  2. System overview
  3. Business goals
  4. User Groups
  5. Functional requirements
  6. Non-functional requirements
  7. Main domain concepts

1. Introduction

1.1. Purpose of the document

The purpose of this document is to define what the system is to do from the user’s point of view. User requirements define system functions that the users can see and system properties that customers are ready to pay for. Although it may sound harsh, requirements are defined mainly to determine what the user needs, rather than what the user wants.

Table 1. Possible readers of this document

Group of the readersReasons for reading
Users and customersTo give feedback about the user requirements
System developersTo understand what functions and properties the system must contain
TestersTo test the system against the requirements
Writers of user manualsTo get material for user manuals
Project teamTo follow-up the status of the project against the requirements

1.2. References

These documents have been used as an information source and are necessary for understanding this document.

Table 2. A list of all other relevant documents

Name of the documentShort description of the document contents
Engineering Document Management ResearchAn overview of the document management system used in this project. ICBN must be integrated into this system. http://projects.icbroker.com/edmr/docs/
BizTalkBizTalk is an EAI messaging server which can handle document exchange between two parties using RosettaNet PIP standards. It offers standard transparent services such as compression, encryption, authentication etc. http://www.microsoft.com/biztalk/
ICBN research projectThe customer’s project at IC Broker IT. ICBN tries to improve the predictability of lead-time or resources in networked product development projects by better engineering change management and integration of product data management systems. http://projects.icbroker.com/icbn/docs/
PINJA APICode and description of the Java API used to interact with the EDMS http://edmspc.soberit.hut.fi/pinja/
PIPRosettaNet Partner Interface Process. A description of a process which is related to document exchange between two parties. PIP envelopes are described using XML. http://www.rosettanet.org
RosettaNetA self-funded, non-profit organization, RosettaNet is a consortium of major Information Technology, Electronic Components and Semiconductor Manufacturing companies working to create and implement industry-wide, open e-business process standards. These standards form a common e-business language, aligning processes between supply chain partners on a global basis. http://www.rosettanet.org/
SOAPCode Library: SOAP Librarysimplifies processing and creation of SOAP messages.
http://xml.apache.org/soap/
VelocityCode Library: Velocity – Template EngineVelocity can be used to build a web-application based on MVC-model
http://jakarta.apache.org/velocity
XMLCode Library: XML & XSL(T) Engine,Apache Xalan (XSL(T)) and Xerces (XML)
http://xml.apache.org
ICReq Research ProjectQure project lists good requirements engineering methods and possible problems related to gathering and management process regarding user requirements.
DroolsDrools is a Java-based Rule Engine implementation which uses Rete-OO-algorithm for resolving rule matches. Drools is the most important module in ICBN. http://drools.org/
Functional SpecificationFunctional Specification includes use case descriptions.

1.3. Requirements sources

A list of people who have defined requirements.

IDPerson nameEmailPhoneOrganizationTitle
DTDante Dionne Project Lead
JKJasonSystem Architect
AAAlexander Sponsor

1.4. Definitions

1.4.1. Degree of necessity

ESSENTIALImplies that the software will not be acceptable unless these requirements are provided in an agreed manner.
CONDITIONALImplies that these are requirements that would enhance the software product, but would not make it unacceptable if they are absent.
OPTIONALImplies a class of functions that may or may not be worthwhile. This gives the supplier the opportunity to propose something that exceeds the scope of requirements specification.

1.4.2. Implementation schedule codes

I1Requirement implemented at the 1st implementation phase
I2Requirement implemented at the 2nd implementation phase
I3Requirement implemented at the 3rd implementation phase

1.5. Glossary

The special terms, acronyms and abbreviations used in this document.

Acronym/ abbreviation/ special termDescription
APIApplication Interface – A language and message format used by an application program to communicate with the operating system or some other control program.
ICBNDocument Distribution Process – Actions that happen when a document is distributed.
EDMSEngineering Data Management System – System for managing engineering documents.
GUIGraphical User Interface – A graphics-based user interface that incorporates icons, pull-down menus and a mouse.
HTMLHypertext Markup Language – The document format used on the World Wide Web. Web pages are built with HTML tags (codes) embedded in the text.
HTTPHypertext Transport Protocol – The communications protocol used to connect to servers on the World Wide Web. Its primary function is to establish a connection with a Web server and transmit HTML pages to the client browser.
IC BrokerName of the project team
UMLUnified Modeling Language – An object-oriented analysis and design language from the Object Management Group (OMG).
PIP(RosettaNet) Partner Interface Processes – System-to-system XML-based dialogs which define business processes between trading partners.
SOAPSimple Object Access Protocol – A message-based protocol based on XML for accessing services on the Web.

1.6. Guideline for defining good requirements

Features of a good requirements specification document:

  • one requirement per sentence
  • clear structure
  • correctness (contributes to real user need)
  • understandability (use user’s language and terminology)
  • unambiguity (clarity, only one possible interpretation)
  • verifiable (requirement can be tested)
  • consistency (no subset of individual requirement conflict)
  • completeness (everything the system is supposed to do is included in the document)
  • traceability (every requirement has a unique identifier)
  • modifiability (document structure allows modifications easily)

2. System overview

ICBN is a software component which is able to store and manage object-related business rules. Objects can describe some real world elements such as documents, projects, users or some more abstract values or system services. The primary purpose of ICBN is to offer an easy way to define rules for document distribution processes between different companies. ICBN interacts with existing legacy system called Engineering Data Management System (EDMS) and Enterprise Application Integration (EAI) System called Biztalk. ICBN listens to events coming from the EDMS and initiates different document distribution processes if the corresponding business rules are matched. ICBN then calls BizTalk and instructs it to transfer the matching documents.The architecture of ICBN will be designed to be modular and independent of surrounding project related systems. Therefore it can be plugged into any document management system – not just EDMS. ICBN offers a simple HTML-based user interface for managing and visualizing rulesets for different projects.

2.1. System description

The purpose of the project is to develop a system that enables legacy document management systems to exchange documents according to definable rules. The core component that will enable this functionality will be called ICBN. ICBN system will provide a rule engine and a user interface through which user can define these rules The rule engine checks the rules to see which documents have to be sent and to which recipients. ICBN system is located between the document management system and the transport system with which it interacts.

2.2 System users and main functions

Figure 1. System users and main functions.

3. Business goals

3.1 Background

At the moment numerous product changes during product development cause extra delays or a need to use extra resources in product development projects. This is due to a lack of common iteration procedures between companies. Integration of document management systems is not possible because of a lack of common syntax and semantics. This kind of integration has been done earlier in order-to-delivery process, though, e.g. EDI (Electronic Data Interchange). In order to achieve the same kind of integration in product development messages (contents, syntax) must be formally described so that computers can process them.

3.3 Business Opportunities

The ICBN research project will analyse processes between partner companies. Based on this analysis a new framework for iteration is defined to enable better predictability of product development project schedule and resource usage. Inter-company messages are analyzed and common semantics is defined using appropriate schemas. Based on these the ICBN project will implement a software prototype where communication happens according to RosettaNet standards. ICBN will be a part of this prototype.

3.2 Business Objectives

The ICBN software will be part of a larger system. The main driver is to get some research data from using the system and to see if this kind of a system is feasible to implement. Customer will publish articles based on the research data obtained from the project. There are no economical interests and the system is to be used in business intelligence research. Result of this research can be used later in developing a better solution for the problem or as a model for a commercial system.

4. User groups

This section describes intended users of the system.

Table 3. Users of the system

IDUser groupDescriptionNumber of users
PMProject ManagersProject Managers define and manage controls for their projects.1-20
AdminAdministratorsAdministrators are able to create the most complex business rules and administer rule-sets for different projects. They can create new rule-templates, repositories and manage existing settings. Admins define what PIPs are used between different companies.1-5
PartnerPartner CompaniesPartners are other companies which do not directly interact with ICBN but their activity causes changes in the EDMS which indirectly instantiate events in ICBN. Basically partner is an instance which has right to receive certain documents or document types.1-2000
BizTalkEAI BizTalkEnterprise Application Integration messaging server can be seen as a user from ICBN point of view. BizTalk is responsible for sending the documents ICBN instructs it to send via SOAP calls.1
EDMSEDMSEDMS is the document management system which can also be regarded as a user. EDMS sends events to ICBN when documents change. ICBN should then evaluate the defined rules and in case of a match, initiate certain ICBNs.1

5. Functional requirements

This section defines all functions and services that the system will provide. See Functional Specification document for accurate descriptions.

ID: RQ-001Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to login into the system with a username and password
ID: RQ-002Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to define new ICBN rules
ID: RQ-003Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to create new rules using existing rules as templates
ID: RQ-004Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to modify existing rules
ID: RQ-005Source: AADate and phase: 22.10.2002, PP
Priority: LowClass: ESSENTIALRelease: I2
Requirement: user must be able to delete existing rules
ID: RQ-006Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to view all rules related to given project
ID: RQ-007Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to define a rule as a rule template
ID: RQ-008Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: ESSENTIALRelease: I1
Requirement: user must be able to view all rule templates
ID: RQ-009Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to list all documents belonging to a certain project
ID: RQ-010Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to list all projects
ID: RQ-011Source: AADate and phase: 22.10.2002, PP
Priority: LowClass: OPTIONALRelease: I3
Requirement: user must be able to list all users (other companies)
ID: RQ-012Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to list all companies belonging to a certain project
ID: RQ-013Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to view properties and values of given business object (document, project, user)
ID: RQ-014Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: ESSENTIALRelease: I1
Requirement: user must be able to send documents regardless of defined rulesets
ID: RQ-015Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to define what companies are allowed to receive a certain document
ID: RQ-016Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: user must be able to define what companies are allowed to receive a certain document type
ID: RQ-017Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: ESSENTIALRelease: I1
Requirement: user must be able to list what documents a certain company can receive
ID: RQ-018Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: ESSENTIALRelease: I1
Requirement: user must be able to list what document types a certain company can receive
ID: RQ-019Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: CONDITIONALRelease: I2
Requirement: user should be able to visualize which rules are bound to a specific document
ID: RQ-020Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: CONDITIONALRelease: I3
Requirement: user should be able to simulate what eventss take place when a certain EDMS event is fired
ID: RQ-021Source: AADate and phase: 22.10.2002, PP
Priority: MediumClass: CONDITIONALRelease: I2
Requirement: user should be able to view activity log for a certain project
ID: RQ-022Source: AADate and phase: 22.10.2002, PP
Priority: LowClass: CONDITIONALRelease: I3
Requirement: user should be able to view error log of the entire application
ID: RQ-023Source: JVDate and phase: 22.10.2002, PP
Priority: LowClass: OPTIONALRelease: I3
Requirement: user can retrieve a certain rule as XML via HTTP
ID: RQ-024Source: JVDate and phase: 22.10.2002, PP
Priority: LowClass: OPTIONALRelease: I3
Requirement: user can insert a new rule into the system as XML using the GUI
ID: RQ-025Source: AADate and phase: 22.10.2002, PP
Priority: LowClass: OPTIONALRelease: I3
Requirement: user can get email notification of a successful ICBN execution and a list of companies and documents which were sent to each company
ID: RQ-026Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: ICBN must be able to retrieve documents, projects and users from EDMS
ID: RQ-027Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: ICBN must be able to receive events regarding changes in documents, projects and users from the EDMS via HTTP
ID: RQ-028Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: ICBN must be able to send XML messages to BizTalk to define which document should be sent and which PIP should be used
ID: RQ-029Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: ICBN must be able to receive positive acknowledgement event from BizTalk of successful sending process
ID: RQ-030Source: AADate and phase: 22.10.2002, PP
Priority: HighClass: ESSENTIALRelease: I1
Requirement: ICBN must be able to receive negative acknowledgement event from BizTalk of failed sending process

6. Non-functional Requirements

6.1 Quality Requirements

6.1.1. Usability Requirements

This category identifies the requirements for usage related areas such as look and feel of the product.

ID: USE-001Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I2
Requirement: the GUI should be understandable also to non-technical users
ID: USE-002Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I3
Requirement: the GUI should be able to visualize rules related to certain project and document
ID: USE-003Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I3
Requirement: the GUI should be able to visualize what rules are executed when a certain business object changes state, e.g. status of a document changes
ID: USE-004Source: HPDate and phase: 27.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I2
Requirement: the GUI should present the rules in a hierarchical way so the user can more easily understand the relationships between different parties.

6.1.2 Performance Requirements

ID: PERF-001Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I3
Requirement: Evaluation of rules should be done in less than a minute.

6.1.3 Reliability Requirements

ID: REL-001Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: MediumRelease: I3
Requirement: ICBN should be as stable as EDMS.

6.2 System Requirements

6.2.1 Interface Requirements

This category identifies the interface requirements for the product and includes external interfaces as they relate to hardware, protocols, external software packages, databases and any other external communication requirements. Third party software products which have interfaces internal to the product are also be specified here.

ID: IF-001Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: HighRelease: I1
Requirement: ICBN must be able to access EDMS using the PINJA Java API.
ID: IF-002Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: HighRelease: I1
Requirement: The product must be able to send document transfer commands to BizTalk using HTTP Protocol (SOAP is an option).
ID: IF-003Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: HighRelease: I1
Requirement: ICBN must be able to receive acknowledgement/negative acknowledgement messages from BizTalk related to certain ICBN.
ID: IF-004Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: HighRelease: I1
Requirement: ICBN must be able access rule repository via a generic interface which isn’t bound to any specific RDMBS or file system.

6.2.2 Compatibility Requirements

This category identifies the requirements for interoperability with existing products and third-party products, in addition to components of this product such as existing databases from prior releases.

ID: COMP-001Source: AADate and phase: 22.10.2002, PP
Class: ESSENTIALPriority: HighRelease: I3
Requirement: The graphical user interface must be usable with Internet Explorer 4.0 or later

6.3 Other Requirements

6.3.1 Documentation Requirements

ID: DOC-001Source: AADate and phase: 22.10.2002, PP
Requirement: JavaDocPriority: HighRelease: I1
Requirement: All source code must be commented using JavaDoc. JavaDocs must be generated to HTML files.
ID: DOC-002Source: AADate and phase: 22.10.2002, PP
Requirement: User ManualPriority: MediumRelease: I3
Requirement: Product should have simple user’s manual which explains all important operations and how to execute them. Either in HTML or PDF format.
ID: DOC-003Source: AADate and phase: 22.10.2002, PP
Requirement: UML ModelsPriority: MediumRelease: I3
Requirement: Product documentation should include UML class diagrams, UML Use case diagrams and Component architecture description.

7. Main domain concepts

This section contains

  • Textual definitions of the most important terms
  • A graph defining the relationship of the main concepts

Table 4. Main concepts of the users

ConceptDescription
Rule EngineSoftware Module which is able to efficiently evaluate a large set of business rules and a pool of business objects. Business objects are given as arguments to different rules to find rules that have matching conditions. When such a rule is found, action(s) of that rule are executed. Rule Engine used in this project is Drools which uses a well-known algorithm called Rete (Object Oriented version).
Rulea business rule consists of condition(s) and action(s). Conditions are defined by combining business object attribute comparisions (e.g. project.status == “finished” and document.type = “specification”). Action is usually a command to send the document to its recipient. Rules can have arbitrary level of complexity and they can address any attributes of any available business object.

 
Figure 2. Most important related systems.

 
Figure 3. Main modules of the system.