Documenting Requirements

Perhaps the biggest challenge you are faced with is to come up with requirements that are both complete and unambiguous.You will need to become involved with the stakeholders to get their views on the application-to-be. Stakeholders are those who are going to use the system, or have some interest in the application. In UML terminology, the users of an application are called actors, and can be users or other systems that interact with the system. Other significant terms in ICONIX are Problem domain, which is the part of the dynamic situation that you are trying to capture in a static application. The latter is related to the Solution domain. Remember that a BizTalk application is in essence an object-oriented application. Modeling within the premises of the domain should lead to a solution that meets all the demands. So, always keep your goal in sight, and do not be distracted by anything that can keep you from realizing that goal. This is one of the strong points of ICONIX, as it does not carry all of the "fat" that other methods tend to carry in a rigid process with a high level of detail. Every stage in a development process is organic. Never expect that every step along the way will be complete and detailed. Never think that you can only take a next step if the current one is perfect. It is better to revisit previous steps and refine them based on the knowledge you gather along the way. Draw on your experiences with previous projects, but do not let them lead you into making assumptions or premature conclusions.

The first step is to establish the set of requirements that will impact all future actions in the process. Draw from as many sources as possible. Remember that the users are possibly the most valuable, and at the same time, the most uncontrollable source available to you (see the sidebar "Users Hold the Key to the Requirements"). Once you have gathered all this information, you should start unifying it. Capture each requirement in a single sentence that explicitly phrases it. For example:

■ The application must connect with the Database General Ledger.

■ The application must provide user authentication.

■ The application must print weekly statements.

■ The application must log every transaction.

■ The application will only accept money transfers over $5,000 if the user has at least an authentication level of "Department Manager."

Sort this list so that strongly coupled requirements are grouped together. Again, the list does not need to be perfect, but be sure that what is on the list is correct.

Developing & Deploying...

Users Hold the Key to the Requirements

You often come across developers who do not speak fondly of the users who are involved in the requirement phase—"They don't know what they want!" or "They always come up with new requirements!" or "Users just keep you from getting on with the development!" Although sometimes expressed in more subtle ways, there is a certain ring of truth to these statements. However, most developers are in the business for the technology, and forget that they develop for users, meaning that they are also in the "people business." Users often do not know exactly what they want, since they are not developers—this does not mean that they do not know what they need. They are perfectly capable of telling you what they expect from the application. It is the role of the developers, or business analysts for that matter, to coach them in formulating these expectations, which will then form the foundations of the requirements you are looking for. You can do this using a number of interview techniques, the number-one skill for a developer involved in establishing requirements.

A very productive way is the group session that is led by a moderator whose only task is to lead the group in getting the requirements on the whiteboard. The group must have a balanced composition to prevent

Continued certain users from dominating. Begin with the question "what do you want the application to be able to do?" Give all the participants a number of cue cards—let's say five—and ask them to put down the five most important requirements for the new application, one on each card. After they are finished, the moderator collects all the cards and puts them on a board for everyone to see.

The next step is to let the group cluster these requirements, based on their relation to one another. It is very likely that most of these clusters will be too general, so ask the same sort of question focused on one cluster. Never go more than three levels deep per cluster, since you might exhaust the participants and lose their attention. The moderator should take time to discuss the results and make some objective conclusions, based on the information on the board. You may have to or want to do more than one group session, so there is no need to get a highly refined requirement package from the first session. Keep the participants motivated by keeping them involved!

A second interview technique that works for both a group and a one-on-one interview is, "Listen-Summarize-Continue asking" (LSC). This is an effective way of requirement finding, because you let the interviewee tell his story, you listen, make notes, and ask questions that make the interviewee refine his answer. You should have a list of questions— somewhere between five and ten—that need to be answered to your satisfaction. Even for the one-on-one interviews, multiple sessions might be needed.

Between group and individual interviews, it is up to you to analyze the results and start with the documentation of the requirements. This will bring new questions to the surface, or show areas for which you have insufficient information. Do not refrain from prototyping the user interface (UI), since visualization is a strong tool. Always start a new session/interview with the information from the previous one, and see if there is still a consensus on the conclusions. This interaction with the stakeholders/users is important; if you keep them involved and get their approval on the requirements, it is highly unlikely that they will complain about, or try to shoot down, the application you are building. You document the requirements both for you and the users. Requirements subsequently lead to Use Cases. Both are also used during the (functional) testing phase, since the test cases will (should!) be based on requirements and Use Cases. If both are not accessible to the people who make the test cases, you might end up with test cases that do not reflect the requirements—a major problem!

The next step might surprise you, but it makes a lot of sense if you take some time to think about it: "Start Building the Domain Model"(also known as Domain modeling), using a minimal set of the UML diagramming methods for Domain models.You are building an (object-oriented) application, meaning that you better start defining the boundaries of that application.The Domain model is part of the (static) Solution domain.

You can derive the Domain model from the requirements, assuming you have had prior experience in building Domain models. Do not overwhelm yourself with details; in fact, the Domain model has a strong resemblance to a simplified entity relationship diagram (ERD). During the next steps, you will very likely revisit the Domain model to make modifications, so the more details you put in it now, the more difficult it will be to complete the Domain model later.The details are left for the "Class diagram," which is based on the Domain model, and will turn up in your BizTalk Orchestration diagram (XLANG schedule diagram). Even if you are already familiar with making UML diagrams, here are some things you should take into account:

■ Start identifying the core object, and from there, work to objects that are more specific and determine the relationship between these objects.This is also known as the "inside-out" approach.

■ Use only generalization and aggregation relationships in the Domain model; other relationships in the UML model are left for the Class diagram, since they imply implementation assumptions.

■ Focus on object reusability in your Domain model, since this is an important aspect of object modeling.

■ Establish a naming convention that is accessible to everyone. Do not use "cTransAccntLog" if you can write "Transaction Log."

■ Avoid data entities (attributes) and functions (operations) in the Domain model. Again, these obscure the Domain model and are left for the Class diagram.

■ Avoid design patterns in your Domain model, since this is also an implementation aspect.

■ Avoid n-to-m relationships (multiplicities) in your Domain model; again, this is an implementation aspect.

Figure 7.1 is a small example of what a Domain model in the ICONIX approach looks like.The Domain model is based on a person being able to make financial transactions on his bank account and create a new account.

Figure 7.1 A Bank Account Example for an ICONIX-Based Domain Model

Statement List


Statement Details

Logon Handler


Preliminary Customer


Transaction List

Transaction Details

User List

Customer List


Bank Account

Bank Account

Customer Bank Products

Statement List

Transaction List

Customer Bank Products




Transaction Details


The bank account example is meant for demonstration purposes. Although it is based on a real-life Problem domain, it is an excerpt edited for this chapter. Therefore, some details have been omitted to enhance the overview and thereby use it as an example. For example, we left out "Create User" and "Create Customer."

Once you have established this Domain model, review it with colleagues and employees from your client who are experienced in this business field. This way, you can establish that there are no misinterpretations in the Domain model. It needn't be complete; you can revisit and refine it as often as you like and make changes as the picture becomes more complete and transparent. As mentioned previously, you are in an organic improvement process where the results only get better by moving forward to gather more information.


As you build your Domain model, you will come across a lot of information that is very useful in the application development, but should not appear in the Domain model; for example, attributes, operations, and design pattern. Instead of ignoring them, make a type of "scrapbook" Domain model and add this information. You will need this information eventually, and this can help you to jumpstart that step in the process.

Once you are comfortable with the Domain model, it is time for the next step: "Start Building the Use Case Model" (Use Case modeling). A Use Case describes a single interaction between a user (actor) and the application. It shows the boundaries of the system. In fact, all the Use Cases put together would make the foundation of a complete User's Guide. The Use Case model will show all Use Cases you can identify from the requirements and the User Interface prototype, by identifying the verbs in the requirements that connect two nouns.You will notice that of the two nouns, one will be related to the application—identifiable as an object from the Domain model you created in the previous step—and one will be an actor.When doing so, try to be as complete as possible, by going through the requirements and checking if you can identify every requirement in a Use Case. When this is completed, you should group the Use Cases based on their (logical) coherence to make it easier to divide the work among you and your colleagues, and to help you later in identifying subsystems or application modules. Using the analogy of the Use Case model being the User's Guide, a group of Use Cases can be seen as a subdivision of this User's Guide; for example, a chapter in the User's Guide.You need a Domain model to be able to determine the relevance of a Use Case, since it has to be based on the application you are building.

We mentioned earlier that the ICONIX process is Use Case driven, and in that respect, the Use Case model defines the boundaries of the Problem domain and drives the identification of the application's behavior. This behavior in turn will influence the Solution domain.We now have linked the Problem domain and Solution domain.You may have noticed that the Use Case model has an out-side-in approach, going from the general requirements to specific application behavior—the opposite of the Domain model.

When you are satisfied with the Use Case model (Figure 7.2), it is time to describe the Use Cases that, according to the ICONIX process, should be kept simple without pre- and post-conditions, or goals. Again, pre- and post-conditions imply implementation aspects, and you are still some steps away from imple-menting.You can even argue that these extensive Use Case formats do not add significant value to the Use Case, but cost time to complete. Instead, the Use Case we promote consists of three parts: the "Use Case Name," the "Basic Course of Action," and the "Alternate Courses of Action."The Basic Course is what the Use Case is expected to do the majority of times that the Use Case is "exe-cuted."The Alternate Courses are all the other situations that can occur for the Use Case. A "Course" should be written from the actor's perspective, and from thereon follow the course of events that happen.The course should be written in the following structure: "The actor does this, then the application does that, followed by ... and then " Be explicit when naming the objects involved in the Use Case. Use the Domain model and identify the objects with which the actors interact, called Boundary objects; for example, "Login Page," "Bank Account Details Page," or "Error Page." Do not overwhelm the Use Case and yourself with details, since these are very likely implementation aspects and not relevant at this point.This does not mean that you should ignore them—remember your scrap-book! By the way, you can also make a copy of your Domain model and start adding attributes to the objects, instead of cluttering the Use Case with them. Since you identify the object involved, you ensure yourself that there is a reference to the attributes.

Do not try to convince yourself that you captured all possible Use Cases, but be sure you have identified the Use Cases based on the requirements that are known.You can do this by continuously cross-referencing the material you have and modifying it if needed.You will be surprised by the things you catch in this early stage. If you are convinced that you identified and described all the Use Cases, based on the information at hand, you can move to the next step. Do not lose time (and sleep) trying to be complete the first time around. If the different something does not match up, go back and fix it. Do not hesitate to call on a colleague or expert for a second opinion; peer review is a very useful instrument during the entire process. Remember that if you are able to explain your work to colleagues and the clients (users), without them staring glassy-eyed at you, it is more than likely that you did it correctly.Tables 7.1 and 7.2 show two of the Use Cases from Figure 7.2.

Figure 7.2 The Use Case Model for the Bank Account Example

View Transactions

General Ledger

Process Money Transfer

Clearing House

Table 7.1 The Make Money Transfer Use Case Basic Course

1 The Application shows the Money Transfer page.

2 The Application retrieves the Open Bank Accounts List associated with the Customer.


Table 7.1 Continued

Basic Course

3 The Customer selects one account in the Open Bank Accounts List from where the money must be transferred, fills out the recipient data with account number, recipient name, and address information, fills in the amount of money on the Money Transfer page, and then clicks OK.

4 The Application validates the recipient data from the Money Transfer page to ensure that all fields are correctly filled (e.g., correct bank account number and ZIP code).

5 The Application retrieves the Bank Account Details associated with the selected Bank Account, and validates the entered amount of money against the customer's Bank Account holds.

6 The Application creates a Preliminary Transaction and copies the customer's bank account, name, and address data to the Preliminary Transaction.

7 Then the Application retrieves the Customer Address associated with the Customer.

8 Then the Application copies the recipient data to the Preliminary Transaction.

9 The Application copies the amount of money to the Preliminary Transaction.

10 The Application displays the Preliminary Transaction on the Confirm Money Transfer page.

11 The Customer clicks OK on the Confirm Money Transfer page.

12 The Application calls the Process Debit Transaction Use Case.

13 The Application returns to the Customer's Home Page and returns control to the Use Case that called Make Money Transfer.

Alternate Courses

14 If the Open Bank Account List is empty, display a "No Account Available" message on the Error Page, and return control to the Use Case that called Make Money Transfer.

15 If the recipient data is incomplete or incorrect, display an "Incorrect Recipient Data" message on the Error Page, and the Application returns to the Make Money Transfer page.

16 If the amount of money in the Bank Account Details is not sufficient, display an "Insufficient Funds" message on the Error Page, and the Application returns to the Money Transfer page.


Table 7.1 Continued

Alternate Courses

17 If the Customer clicks Cancel on the Money Transfer page, the Application returns control to the Use Case that called Make Money Transfer.

18 If the Customer clicks Cancel on the Confirm Money Transfer Page, the Preliminary Transaction is removed and Application returns to the Money Transfer Page.

Table 7.2 The Process Debit Transaction Use Case

Basic Course

1 The Application retrieves Bank Account Details associated with the Transaction.

2 The Application validates the Recipient Bank Account Number associated with the Transaction against the bank's Bank Account List.

3 The Application validates the amount of money on the Preliminary Transaction.

4 The Application creates a Transaction and copies the data from the Preliminary Transaction.

5 The Application decreases the Bank Account balance associated with the Transaction with the amount of the Transaction.

6 If the recipient Bank Account Number is also of the same bank, the Application calls the Process Credit Transaction Use Case.

7 The Application sends the Transaction to the General Ledger.

8 The Application changes the status of the Transaction to "Completed."

9 The Application returns control to the Use Case that called Process Debit Transaction.

Alternate Courses

10 If the amount of money exceeds the thresholds, the Application changes the status of the Transaction to "To Be Authorized" and returns control to the Use Case that called Process Debit Transaction.

11 If the recipient Bank Account Number is not of the same bank, the Application sends the Transaction to the Clearinghouse and changes the status of the Transaction to "Pending."

Before you go to the next phase of the process ("Modeling the Interactions"), it is important that you consolidate your results so far: the Domain model and the Use Case model. Figure 7.3 shows what parts of the Problem domain and Solution domain we have already filled in, as well as the blank spots that we still need to cover.This consolidation, called the Requirements Review, is the first milestone of the project.You do this review with both your colleagues and the customers (stakeholders). Ask everyone involved:"Do we all agree that these are the requirements we have identified for the application?"You should only proceed if the response is a firm "Yes."

Figure 7.3 The Requirement Steps in the ICONIX Process


UI Prototype


Dynamic Domain



Static Domain

Was this article helpful?

0 0

Post a comment