ICONIX Software Engineering, Inc.  

ICONIX Process for Service-Oriented Architecture

  ICONIX JumpStart Training
  UML JumpStart with EA
  SysML JumpStart Training
  Hands on ICONIX Process
(Onsite or Open Enrollment)
  Request Training Info
  EA for Power Users
  Mastering UML w/ICONIX Process
  EA TrainingPack
  Enterprise Architect
  MDG Integration for Eclipse
  MDG Integration for Visual Studio
  Design Driven Testing
  Use Case Driven Object Modeling - Theory and Practice
  Agile Dev. with ICONIX Process
  Extreme Programming Refactored
  eBook: 20 Terabytes a Night
  ICONIX Process for SOA
  ICONIX Process for Embedded Systems
  Tutorial: Design Driven Testing
  Case Study: Large Synoptic Survey Telescope
  Case Study: ESRI Professional Services
  Case Study: Virginia DMV
  Song of the Extremos (Humor)
  Alice in Use Case Land (Humor)



ICONIX Process for Service-Oriented Architecture

A roadmap for SOA development using web services


Doug Rosenberg, ICONIX


Figure 1 – A “Secret Decoder Ring” may be required for Service Oriented Acronyms

Trying to make sense out of the “acronym-scrabble” that engulfs Service Oriented Architectures (SOA) is a major challenge.  We’re going to take a shot at it in this article by defining a process roadmap and following a single example all the way from architecture to code. Along the way we’ll illustrate many of the key features of Enterprise Architect Business and Software Engineering Edition.

The example we’ll follow will be a Service-Oriented Architecture (SOA) car rental system model, developed by the team at Sparx Systems, that’s implemented with a combination of web-services and custom software.  Our SOA Process Roadmap will tie everything together in what we hope will be a clear and understandable manner.

Why a Service-Oriented Architecture Roadmap?

Web services and SOA have become increasingly important in today’s IT universe.  A recent article from IBM Global Technology Services[1] suggests that nearly half the companies in the world are either adopting, piloting, or considering SOA, and that investments in these projects may reach between $18 Billion and $160 Billion in the near future.  With those sorts of numbers, it stands to reason that many readers will be interested in a roadmap and a cohesive example that brings some clarity to the problem.  Hopefully this includes you.


A Quick Introduction to SOA


As it turns out, an SOA example also serves to illustrate many of the features of the Sparx Systems solution, which supports building “executable business processes” that use WSDL (Web Service Definition Language) to implement their solution.  And, since projects don’t live by web services alone, Enterprise Architect has numerous other useful features for handling those parts of the application that require custom (non-web service) development.  In particular we’ll be spending a significant amount of time exploring in this book include a new and unique capability for “behavioral code generation” for the enforcement of Business Rules, and tight integration with IDEs, including Eclipse and Visual Studio.  We’ve leveraged the power of these capabilities into our SOA Roadmap.

The SOA Roadmap (aka ICONIX Process for SOA Development)

As with all of our ICONIX Process Roadmaps[2], our SOA roadmap is defined as a set of activity diagrams.  In this case, the roadmap provides a “cookbook” set of steps that can be followed for building systems that are based around a Service-Oriented Architecture.

Figure 2 – ICONIX Process Roadmap for Service-Oriented Architecture Development

Figure 2 shows our top-level roadmap. Some of these top-level activities will expand out to a child diagram showing further detail.   As you can see, the top-level roadmap includes some “common stuff” like figuring out your requirements and modeling the problem domain, and then provides multiple paths for developing different flavors of business processes, all the way to code. 

Getting Ready for SOA

As shown in our top-level roadmap, there are a few “setup” activities that will are necessary at the beginning of our SOA project.  We’ll begin with a simple domain model (also called a fact model), that shows the main objects in the problem domain (Figure 3).

Figure 3 – Domain Model (also called Fact Model) for the Car Rental System

As you can see, the domain model establishes the vocabulary we use to describe our system, and shows relationships between objects in the problem domain.  In most cases these relationships include UML generalization and aggregation relationships (not shown here).

Business Rules are represented in Enterprise Architect as stereotyped Requirements.  Figure 4  shows a Requirement Diagram for our Car Rental System that organizes these business rules according to different RuleTasks.  We’ll talk more about RuleTasks (actions that enforce Business Rules) shortly.

Figure 4 – Business Rules for the Car Rental System, organized by RuleTask

The top-level roadmap shown in Figure 2 reflects the philosophy that when you set out to implement a system using a service-oriented architecture, there will effectively be a mix of 3 different kinds of scenarios:

1)       Scenarios that use web services (for which we will develop web service interfaces using WSDL, and orchestrate the use of those web services using BPMN and BPEL.

2)       Scenarios that enforce business rules (for which we will use activity diagrams and the business rule composer)

3)       Regular old software use cases (which we won't discuss in this book because we’ve covered it quite thoroughly in my other books)

Most systems will contain a mix of these different types of scenarios. 

In many cases (but not all) the "web-service scenarios" will cross Business To Business (B2B) boundaries.  For example, a car rental reservation system talking to a credit card company to run a payment transaction is a B2B web-service scenario. Where a business process can be implemented via web services, we follow the branch on the left: web service interface definition using WSDL, and orchestration using BPMN and BPEL.

The "business rule scenarios" are more likely to be within the boundaries of one business, for example, the car rental system enforcing eligibility rules on driver age, credit score, etc.  There is little or no user interface in these business rule scenarios, so they can be completely code generated from an activity diagram using the business rule composer.
For processes that are primarily focused on enforcing business rules, we take the right branch: Behavioral Code Generation from Activity Diagrams using the Business Rule Composer.

Finally there is the user interface.  These would be the screens of the car rental system that the reservations agent accesses, and which would trigger the business rule checks and B2B transactions.  These parts of the system are best modeled using use cases,
following a “use case driven” approach that’s out of scope for this article, but well documented in my other books[3].   

With all of these branches, we can compile and build using either Eclipse or Visual Studio, and use the Sparx “MDG Integration” technology to keep models and code in-synch. 


A Short Intro to Web Services and WSDL


WSDL defines Services as collections of Network Endpoints, or Ports; a collection of Ports defines a Service. A Port associates a network address with a reusable binding, and a Message is an abstract description of the data that is being exchanged.  A WSDL file has an “abstract” section that describes Ports and Messages, and a “concrete” section that describes specific instances of their usage.  This file structure is shown in Figure 5.

Figure 5 - WSDL file structure showing Abstract and Concrete sections (from Wikipedia[4])

Developing Web Service Interfaces (WSDL) with Enterprise Architect

Before we can use BPMN and BPEL to orchestrate a collaborating group of web services, we first need to be able to define the web services themselves. 

WSDL Packages in Enterprise Architect are organized into Types, Messages, Ports, Bindings, and Services as shown in Figure 6.

Figure 6 – A look inside a WSDL Package for the CarRental web service

Generating WSDL

Once we’ve defined our Types, Bindings, Ports, Messages, and Services, it’s time to generate WSDL by right-clicking on our WSDL component and choosing Generate WSDL from the context menu.  Figure 7 shows the WSDL generation in progress.

Figure 7- Enterprise Architect generates WSDL automatically

The result of WSDL generation for our Car Rental component can be seen in Figure 8.

Figure 8 - We’ve successfully generated WSDL for the Car Rental component


Web Service Orchestration using BPEL

The term “orchestration” is often used to describe implementing a business process by using a number of web services in a collaborative way.  We’ll use BPEL to orchestrate web services, and BPMN to model BPEL.

Note that it’s possible to draw BPMN (Business Process Modeling Notation) diagrams to model business processes without generating BPEL (Business Process Execution Language).  And, you can model BPEL using other graphical notations besides BPMN.  But one of the more interesting strategies, which we’re following in this roadmap, involves using BPMN to model BPEL processes[5].

Figure 9 shows the roadmap basic steps for using BPMN to model BPEL.  

Figure 9 – Roadmap: We use BPMN to model BPEL, then generate BPEL code


A Quick Overview of BPEL

Modeling BPEL Processes with BPMN

Figure 10 – BPMN diagrams show activities, gateways, messages, pools, and events

Figure 10 shows a BPMN diagram for our BPEL Car Rental Process.  The process begins with a Start Event: a Request is received from the Customer.  If the customer is of legal age to rent the vehicle, a (B2B) web service is used to check the Customer’s credit card.  If the card is valid, another web service is used to rent the vehicle, and a “Success” message is sent. If either the age or credit card checks fail, a “No” message is sent back to the customer.


Mapping BPMN to BPEL

Once we’ve defined our activities, gateways, and events on our BPMN diagram, we can specify additional BPEL details as attributes on our BPMN elements.  In Figure 11, we’re defining that the CheckCreditCard activity will be implemented as a web service, and will take a “request” message and generate a “result” response.

Figure 11 – Mapping BPMN to BPEL for interfacing to the creditCardChecker web service

Generating BPEL Code

Finally, after we’ve specified our BPEL Process and validated the model, Enterprise Architect will generate the BPEL code to accomplish our business process.

Figure 12 – We’ve successfully orchestrated our web services using BPEL

Business Processes must satisfy Business Rules

Even in a service-oriented system, not all business processes can be implemented by orchestrating web services.  Some business processes will involve user interfaces, and some will be focused on enforcing business rules.  We won’t discuss GUI-based software use cases in this article, but we will spend a fair amount of time discussing some new ways to implement those processes that are focused on enforcing business rules.

In this section, we’ll introduce you to the unique capabilities of Enterprise Architect’s Business Rule Composer.  Starting from the domain model (fact model) and the requirements that we’ll presented earlier, we’ll take you through the process of creating Activity Diagrams for Business Processes, stereotyping Actions as RuleTasks, and finally, linking the business rules to the rule tasks in preparation for Behavioral Code Generation. 

Figure 13 shows our roadmap for business-rule-centric scenarios.

Figure 13 – Roadmap: Developing “business-rule-centric” scenarios using EA’s Business Rule Composer


Behavioral Code Generation – a quantum leap in tools capability

One of the common themes of all of our ICONIX Process Roadmaps is that they all get you to code.  We’ve always believed that processes that only get you halfway to code (or less) are much better in theory than they are in practice (because in practice, programmers tend to ignore them).  Enterprise Architect, since it’s early days, has excelled at “code engineering” (forward and reverse engineering for a wide range of languages,  powered by customizable code generation templates).  But those already strong capabilities have recently taken a quantum leap in power with the introduction of behavioral code generation from activity diagrams, state diagrams and sequence diagrams.  Behavioral code generation is a major advancement over generation of “class headers” (which has been the de-facto meaning of “code generation” for more than a decade).

Figure 14 – RuleFlow diagram for processing a car rental application

Let’s take a look at how we’re going to process an application for our Car Rental System.  The first thing we need to do is to create a RuleFlow diagram – in this case ProcessApplication (Figure 14).  We’ll create this diagram “inside” of a class in the Fact Model, just as if we were creating an Operation on that class, since that is, in effect, what we’re doing.  The RuleFlow diagram contains RuleTask actions.  Each RuleTask satisfies one or more business rules with some conditional logic.

Linking Business Rules to RuleTasks

What we’d now like to do, is to specify the conditional logic for each of these RuleTasks, while associating each piece of logic with the specific Business Rules that we’re enforcing.  As you might have guessed by now, that’s where the Business Rule Composer comes into play.  Once we’ve completely specified each RuleTask, we’d like Enterprise Architect to generate 100% complete code for the entire RuleFlow (Activity Diagram).  Using Behavioral Code Generation, that’s exactly what we’ll do. 

Figure 15 shows the Business Rule Composer for the “Eligibility” RuleTask.

Figure 15 – Specifying conditional logic for Eligibility using the Business Rule Composer

There are 2 sections on the Rule Composer screen.  The top panel shows the Business Rules that we’re satisfying within this Eligiblity RuleTask;  the lower section (in this case a Decision Table) has 3 parts: a Condition section to model condition variables, an Action section to model action variables, and a Rule Bind section to link the rule in the rule table.

Generate Behavioral Code from Activity Diagrams

Code generation turns out to be very simple (and yields astonishing results) once all the preliminary work has been done.  Simply right-click on the Fact Model Class in the Project Browser and select “Generate Code”…and…Voila!  No programming required!



Figure 16 – Enterprise Architect automatically generates complete behavioral logic for the entire rule flow


It’s worth examining the code shown in Figure 16 quite carefully.  Here are a few points worth noting:

  • The entire RuleFlow diagram is code generated as if it were a single class Operation on the FactModel Class
  • Each RuleTask is expanded in-turn
  • Within each RuleTask, the Business Rules are automatically propagated forward into the code as comments
  • Attribute and Operation names are taken directly from the Rule Composer
  • No manual programming intervention is required


It doesn’t take a whole lot of imagination to see that this capability can be a real “game-changer”.  Many organizations have thousands of business rules to implement, and “errors in translation” between Subject Matter Experts, Business Analysts, and Programmers are the norm, not the exception.  Many of those errors can be eliminated using Behavioral Code Generation and the Business Rule Composer.


Integration with IDEs – keeping model and code synchronized

Figure 17 – Roadmap:  Keeping models synchronized with code is accomplished with MDG Integration

Since well before UML even existed, one of the biggest issues with modeling software has been keeping the model and the source code synchronized.   The typical experience used to be that UML models were most useful in getting the first release of software completed, but after the initial release, the code would evolve independently in a development environment, and the UML model would rapidly grow obsolete. 

With the evolution of agile methodologies, this situation often led to projects abandoning UML modeling entirely, as agile methods specify many frequent releases of the software, and getting to the first release became a smaller and smaller percentage of solving the overall problem.

You can beat this problem entirely by using Sparx MDG Integration for Visual Studio and for Eclipse, both of which are included in the EA Business and Software Engineering Edition.


Most SOA systems will contain a mix of 3 different kinds of scenarios:

1)       Scenarios that use web services

2)       Scenarios that enforce business rules

3)       User interface scenarios

Our SOA roadmap takes all these different types of scenarios into account.  We use WSDL, BPMN, and BPEL for web-service-centric scenarios, we use the Sparx Behavioral Code Generation and Business Rule Composer capabilities for business-rule-centric scenarios, and we use normal use cases where there are users and systems interacting.

We hope you find the roadmap useful in your development efforts.  For more information visit ICONIX on the web at www.iconixsw.com, or contact us at SOAtraining@iconixsw.com .


[2] These now include roadmaps for Embedded Systems, Testing (aka Design-Driven Testing), Algorithm Intensive Development, and Business Modeling, in addition to ICONIX Process for Software (the original “Use Case Driven ICONIX Process”).  See www.iconixsw.com for more details.

[3] See “Use Case Driven Object Modeling with UML – Theory and Practice” by Doug Rosenberg and Matt Stephens

[4] Wikipedia:  Web_Services_Description_Language

[5] We found Using BPMN to model a BPEL Process by Stephen A. White, IBM Corporation, to be a very useful article.




ICONIX Software Engineering, Inc.
11301 W Olympic Blvd., Suite 559, Los Angeles, CA 90064
Tel (310) 474-8482 / Fax (310) 474-8609
email: UMLTraining@iconixsw.com