Pragmatic model driven development. Part III. Creating the domain model

Note. This series of posts is also published as a Capgemini group white paper and published in Software Release Magazine (in Dutch, in two parts).

The next step towards generated code, and other deliverables, is to create the domain model for the project. Next to the smart use cases, that capture the desired behavior, the domain model provides a structural view of the system.

Roughly said, the domain model captures the key concepts, types, rules, validations, and services of the business domain, expressed in customer terminology. Furthermore,  the model identifies the relationships between all major types.

In this pragmatic approach we follow and extend on the principles stated by Eric Evans in his domain driven design paradigm. As your might expect, the domain model is expressed in UML class diagrams. Primarily, the domain model models domain objects (or entities) such as Customer, Order, Subscription or Course and their relationships, expressed as associations. Next, the properties and their types are modeled.


We consider five different categories of property types, that are all applicable in different situations:

  • Basic types. In general, people tend to model property types in basic types, such as string, integer, boolean or date. However, we have more knowledge on most property types than that it’s just a string or integer. In this case it’s better to use value objects.
  • Value objects. A value object holds no identity, but reflects a value. In short, value objects are good for modeling property types that can be validated, such as Bsn, Isbn or Email.
  • Enumerations. We model property types as an enumeration, if the property can only have a limited, fixed number of different values. Think of ContractType, Gender or Level.
  • Smart references. Another pattern we apply to modeling property types, is the smart reference. We have agreed to model a property as smart reference if the property can only have a limited, but possibly changing number of different values. Here you could consider properties such as Department, Prefix or Country (if no other information on countries is required).
  • Associations. If a property has a type that itself is a domain object, we model an association. Note that in UML an association is actually defined as properties on both ends of the association.

Each of these categories of property types can be used nicely in code generation. For instance, enumerations and smart references can be used to fill drop down lists, and associations of course can be used to generate master-detail behavior or object-relationship mapping configuration files. Moreover, the multiplicity, role names and composite parts of associations can all be used in code generation.

September 30 & October 1, 2009. Workshop. “Pragmatic modelling with UML”

Array Seminars, Amrâth Hotel Lapershoek, Hilversum

I will present an intense two day workshop in Hilversum that follows the pragmatic modeling approach presented in my book with the same title. During this highly interactive workshop participants will learn how the various modeling techniques from UML and beyond connect.


Learn everything about (smart) use cases and start working directly with UML in many exercises a pragmatic case – Dare2Date, an online dating site.

Topics include: UML overview, an agile approach to requirements, modeling smart use cases, testing use cases (with activity diagrams), user interface modeling, domain modeling (using class diagrams), modeling services, modeling in agile software development projects, and model driven development using UML.

Participants will receive a copy of the book Pragmatic Modelling with UML 2.0. This workshop always gets rave reviews.



Delivering products in agile (Smart) projects

In most cases where a form of agile software development is applied, projects are challenged with difficult issues, such as a swaggering scope, unclear and incomplete requirements, unstable software architecture, are quickly approaching dead lines. Within these strict boundaries projects try to deliver high quality software at high productivity – or velocity. This is not an easy challenge.

Delivering just what is needed

Therefore, during agile projects there is high pressure on delivering just that what is needed. The emphasis of an agile project team is on creating just the right (amount of) software, and minimizing the amount of work spent on other products, such as documentation and work in the peripherals of the project. Although many project teams seem to call on this principle to actually not deliver any documentation, the fine art of being agile is delivering just-enough, just-right documentation.

In our experience, a lot of time is spent in agile projects on deciding what’s enough, and moreover, what’s right. Especially when projects are executed in complex organizations, and applying complex (service or cloud oriented) technology, finding the right level of documentation is actually a quite intriguing task, and goes beyond writing (structured or not) user stories.

Delivering products

In the vision of the agile process Smart (and other agile processes, including Scrum and feature driven development) projects should focus on delivering products, not just on performing activities. Please note that working software is not the only product a project delivers.

The agile process Smart suggests to deliver a number of products that will guide projects through these just-enough, just-right in a more standardized fashion. In essence, Smart projects are product driven, as are other agile processes such as Scrum, FDD and OpenUP. During each of the iterations in a Smart project, the team delivers a number of working products. These products fall into a few categories:

  • Project deliverables. In each of the different types of iterations Smart suggests to deliver additional products that will help drive your project to success. These products might include well know deliverables such as a project proposal and non-functional requirements.
    Although none of these product are actually mandatory in a Smart project, they are considered good practice, and over the years have been produced in numerous Smart projects. Using these standard suggested products, organizations get an even better grip on the projects at hand. Note that emphasizing the existence of other project deliverables besides working software (in smart use cases) does not mean projects become less agile.
  • Smart use cases. The body of products delivered in a project is formed by smart use cases, small discrete pieces of functionality that drive development. Smart use cases is a technique to rapidly model your functional requirements at a equal-granular level. Smart use case supply a small and very useful unit of work, and furthermore serve as the main unit of estimation, planning, but also drive realization, testing and even delivery.

All products, both project deliverables and smart use cases run through (a subset of) the product life cycle.

Project deliverables

All products that need to be delivered to run your projects and do not deal with implementing functionality directly (which moreover is partitioned in smart use cases) are referred to as project deliverables. Most of these project deliverables are one-off, although they might be maintained and updated during the project, such as the project’s software architecture and the domain model. Any Smart project needs to decide which of the suggested project deliverables will be produced, and in which iterations.


An easy way to achieve the optimal set of project deliverables is to add the products suggested by Smart to the project’s backlog during the different iterations defined in the Smart process. Or alternatively, add them to the backlog at the start of the project. This allows project teams to add them to the list of products to deliver in any of the iterations.

For example, during the first Propose iteration the smart use case model, a project estimate and a project proposal can be added to the iteration backlog. At the start of the Scope iteration, the software architecture and reusable services might be added. At the start of each of the iterations, the customer and the project team decide which of these products will be picked up and produced.

Examples of project deliverables

Some examples of project deliverables are:

  • Project proposal. A first proposal covering the primary scope of the project and a first cut estimate is produced as a the final project deliverable for Propose iterations.
  • Project plan. The project plan describes the project approach, the stakeholders and goals, business case, risks, resources, timelines and project estimate. The project plan is mostly delivered at the end of Scope iterations.
  • Iteration plan. For each iteration a very brief iteration plan might be documented, sometimes not longer than a single page. This iteration plan describes the list of products (mostly smart use cases) to be implemented and resources needed. In most projects, iteration plans result from the planning session at the start of each iteration.
  • Software architecture. Document describing the architecture for the project. Ideally, your software architecture is an instance of a reusable reference architecture that might be in place at a organization. Having a reference architecture will allow a project team to focus only on deviations. This saves valuable time and effort.
  • Business process model. Most projects implement one or more business processes, and a number of additional functions that support these processes. Smart use cases can be derived from these business processes, independent of how these processes are modeled. The business process model is either obtained from the organization, or created during the project.
  • Smart use case model. The smart use case model is leading in Smart project. It delivers software estimates, and presents an overview of the scope of the project.
  • Domain model. Most custom software development projects will have a model describing the business domain and business services. Sometimes this model stems from previous version of the software, for instance modeled in a data model. In service oriented projects, the domain model in most cases overlays the services called in different back end systems, as forms the basis for a service consuming front end.

Again, in most cases these deliverables are one-off. They are created once during a project, but quite often maintained or updated later on, think of the domain model and a reusable services model.

Smart use cases

Most of the work in delivering working software in iterations that are of type Realize or ‘Finalize” relates to the realization of smart use cases. The smart use case has become our main unit of work. They are implemented following the product life cycle. The work on each individual smart use case includes analysis, design, test design, build, test and acceptance. This work is always visualized using an agile dashboard, either using post-its on a wall, or using an (online) automated dashboard.

Read more

You will find more information on these subjects at:

Slide deck on Pragmatic model driven development at J-Spring

Model driven development has a promise of high productivity. However, many approaches fail to deliver. Sander Hoogendoorn (Capgemini) and Rody Middelkoop (Avisi) will present a very pragmatic approach to model driven development, based on modeling smart use cases and domain models in UML. The speakers elaborate enthusiastically on this approach and the techniques used, and they will model and generate a fully deployable Java applications live on stage!

Rody Middelkoop and I will deliver the following talk on the J-Spring Conference, April 15, 2009 in ‘t Spant in Bussum.

More information:

Talk at J-Spring conference. Pragmatic model driven development using smart use cases and domain driven design

Today Rody Middelkoop, senior technology consultant at Avisi and lecturer at the HAN and I will do an amusing talk at the J-Spring Conference in Bussum on model driven development, using a highly pragmatic approach. Talk includes a live demo where we will build a Java web application on stage in a few minutes (the build process will likely take most of that time. A good moment to tell some jokes I suppose). In projects we execute using the Accelerated Delivery Platform, either with .Net or Java, we generate code from our standardized smart use cases and the domain model, using our Tobago MDA tool set. See for more details.

In our daily practice we generate for a variety of architectures in the .Net space. For instance, we apply our own frameworks, or combine these with open source frameworks such as nHibernate, and blocks from Microsoft.


Rody however used our created a set of templates to also facilitate that, resulting in the generation of large parts of Java applications. In short: model driven development has a promise of high productivity. However, many approaches fail to deliver. Rody and I will present a very pragmatic approach to model driven development, based on modeling smart use cases and domain models in UML. The speakers elaborate enthusiastically on this approach and the techniques used, and they will model and generate a fully deployable Java applications live on stage!

We will share our very pragmatic approach to delivering software using model driven development. First, I will elaborate on the modeling and code generation approach, that relies on smart use cases, smart use case stereotype, a solid software architecture and domain driven design. Next, Rody will take the stage and demonstrate how this approach effects in building Java web applications, generating a fully deployable Java EAR live on stage! Although other architectures and frameworks can be applied, Rody will use open source Java frameworks such as Ant, FreeMarker, Struts2, Spring and JPA/Hibernate3.

Cool isn’t it?

For more information:

Digg This

Client/service architecture. Domain driven development in the distributed era. Episode IV

Go to episode three.
Go to episode two.
Go to episode one.

In case you’re wondering why doesn’t this dude come to his point, you’ve probably missed it. I’ve made it already. The point is: you should always have a single point of truth, and at most have it reproduced on the server side. Which in most cases you don’t control anyway. Centralize your domain or business logic in the domain or business layer. Do not go directly from your front end to the server, but always use the domain layer as an intermediate. The longer I’m in this business, the more I am convinced of this simple, but golden rule.

Client / service architecture

Now you’re probably wondering why I am still blabbering on about this client / server technology. Client / server is dead and long gone isn’t it? Well, it should have been. But it isn’t. A lot of water went under the bridge since 1996, but this two-layered architecture is hard to wash out – in a sense it’s a bit like waterfall or Cobol. It’s still here in our everyday projects, on a day-to-day basis. Even though we are now building applications in service oriented architectures, and have build in a component based model before that, and perhaps in the near future are even building in a cloud model. Let’s call this client/service architecture.

Much to my liking, I get to do a lot of code audits, mostly on .NET applications. Code in these newer styled projects, such as web, service oriented, or even cloud is not that different from our old client/server code. Or if you just witness presentations at conferences on new technologies, or on emerging frameworks, such as ASP.NET MVC or ADO.NET Data Services. Or scroll around the average code example on web sites and blogs. Nothing changes. Developers are still binding their DataSet to their DataGrid. Please check out the following code.

private void ManageCustomer_Load(object sender, System.EventArgs e)
   string connString = "server=(local)\\SQLEXPRESS;database=MyDatabase;Integrated Security=SSPI";
   string sql = @"select * from customers";

   SqlConnection conn = new SqlConnection(connString);
   SqlDataAdapter da = new SqlDataAdapter(sql, conn);

   DataSet ds = new DataSet();

   da.Fill(ds, "customers");

   grdCustomers.SetDataBinding(ds, "customers");

The Hello World excuse

I just picked this code example from an arbitrary web site. It comes from an ASP.NET web page. There’s two options: either this is a Hello World style demo, or it represents the architectural style of the whole application. In the first option, the developer is forgiven. The developer in question will use Hello World as an excuse not to practice good architecture. There’s probably very little time during his demo to explain about good architecture – although I think you should always explain about good architecture, as many developers will just follow the code examples offered and build them into their real-life applications. “But hey, I only wanted to demonstrate this new piece of technology.” Sorry, that’s no excuse.

Hence, the second option: this code example could actually represent the architectural style for a real-life application. In which case you’re screwed. Having a connection string and a SQL statement set up – in strings – on every web page is probably not what you should do. Even though these mistakes will already kill you in maintenance mode, this is not what I wanted to express. Things get worse: this code does not have room for business logic. A DataSet with customers in it is retrieved from the database, and a grid view called grdCustomers is filled with this data. What if I want to run some business logic on my customers? Where do I put it?

The service oriented Hello World excuse

Let’s move on. You might consider that the previous code example is from the old world as it is still centered around the database. Even though it is quite recent code. Let’s consider a real new age code example.

private void GetAccountsData()
     CrmAuthenticationToken token = new CrmAuthenticationToken();
     token.OrganizationName = "MicrosoftCRM";
     token.AuthenticationType = 0;

     CrmService service = new CrmService();
     service.CrmAuthenticationTokenValue = token;
     service.Credentials = System.Net.CredentialCache.DefaultCredentials;
     string result;
     string fetchXml = @"<fetch mapping='logical'>
         <entity    name = 'account'>
         <attribute name = 'name'/>
         <attribute name = 'telephone1'/>
         <attribute name = 'address1_city'/>
         <attribute name = 'address1_country'/>
         <attribute name = 'websiteurl'/>
         <order attribute = 'name' descending='false' />

     result = service.Fetch(fetchXml);

     _crmData.ReadXml(new StringReader(result));

This particular code example comes from a SharePoint WebPart. This web part is used to represent a list of accounts and select an account from this list. These account are retrieved not from a database, but from a service in Microsoft CRM. The accounts retrieved are stored in an instance variable called _crmData. Unfortunately, this variable is not a collection of Account objects, but rather is defined as a DataSet.

DataSet  _crmData       = new DataSet();

And to complete this service oriented example, the instance variable _crmData is then used to render the web part by binding the GridView to the first table in the DataSet.

protected override void OnPreRender(EventArgs e)
     grdCrmAccounts.DataSource = _crmData.Tables[1];

     lblHeader.Text = "Accounts from Microsoft CRM";
     lblHeader.ID = "header";

All in all, again this is a typical Hello World demo scenario that was presented to illustrate the combination of SharePoint and Microsoft CRM. But again, this kind of code will also appear in real-life applications without any doubt. It’s easy to see what’s missing here. There is no location to put our possible business logic.

In a service oriented scenario this means  we totally rely on the definition and signature of the objects from the server, in this particular example on the definition of the Account object in Microsoft CRM. Although relying on services sound reliable, it is in fact no more reliable then to trust on the definition of a table called Accounts in an underlying database. Hence the phrase client/service architecture.

The merits of two-tier architecture. Domain driven development in the distributed era. Episode II

Go to episode one.

So now you’re stuck with this two-tier architecture. Is this a problem. Well, not yet. However, it can become a huge problem, and it has become a huge problem in many, many client / server applications, in a vide variety of technologies, including several types of (legacy) web application technologies.

The truth is out there

The problem with this architecture again is fairly simple. There is no single point of truth. Business logic is scattered. Consider this simple piece of business logic below.

if (StartDate < EndDate)

This code is now in the database, to keep the database from getting harmed. But it is also copied into one of the forms in the application, preferably on an event that is fired when the user tabs out of the field StartDate from, let’s say a Contract.

Eventually, there will be someone on the team of developers who is going to build another form that involves manipulating a Contract. It could be yourself, or any of the other well-educated developers, but there’s always someone how will copy-and-paste the business logic from the other form to the new one. And from that time on the truth is out there. Somewhere. After a while, you will end up with an application that looks like this.


And you might not even see that, because it happens over time. For instance, much of this copy-and-paste activity will take place after the application is deployed and it enters maintenance mode. Especially when the boys and girls doing the maintenance were not on the team that built the software.

Customers changing their minds

Still, this doesn’t have to be bad. It will become bad when something peculiar happens: the customer changes his mind on the business rule. Now, I know, that never happens on your projects, but on mine it did and it does. On average, requirements will change about 20% to 25% during the project. And there you go. Let’s say the customer just thought of the fact that the previous rule must be altered. Just a very small change, isn’t

if (StartDate <= EndDate)

So the boys and girls in the development or maintenance team start looking for the locations this business rule applies to. Of course, there is hardly any documentation, so they start searching the code. And you know what, they will find occurrences of the business rule and fix them. But, that’s Murphy for you, they will likely not find all the occurrences. The applications will now look like this.


And that’s where client / server fails. Miserably.

Back in the days of client/server. Domain driven development in the distributed era. Episode I

At this point in time, where we slowly shift from service orientation to cloud computing, building business software is more complicated then it has ever been. There are many platform that your software needs to target, and there are even more ways of writing the software.

Beyond choosing technology

Choosing a technology goes way beyond stating that you are doing Java, .Net or Adobe, and can be quite complicated. A vast amount of architectures, patterns, frameworks – open source and vendor specific – is available to make life easier, but choosing more complex. With this paper – in episodes – I will try to make a point for building software around its domain, also in applications that consume services in a distributed environment. Especially in such a service oriented environment, since there is a wide variety of sources your domain can be fed from, including database, ERP, web services and the cloud – where ever that leads us to. In the sequential episodes of this paper, I aim at presenting a collection of patterns that will help you leverage your domain driven design independent of the back ends this domain needs to interact with.

Back in the good old days

But first things first. Back in the old days of client/server life was fairly simple. You could find the a way to get the data you needed from the database, usually using ODBC, and splash that data to a form, usually a Windows form. You could build applications in a jiffy. Didn’t we all love PowerBuilder, SQL:Windows and Visual Basic?

Then life got a little more complicated at the time the customer wanted some validation in the application. Let’s say hew wanted to make sure that the end date of a contract was either blank or later in time than the starting date. Here’s where the discussion started. The developers that previously worked with Clipper or DBase would insist to put this validation in the database. And they did. Nice and safe. The younger developers, including me, however would mention that if validation was delayed until the data reached the database, it was fairly late. Couldn’t we just build the validation into the form? Well, yes we could. And we did. So we ended up with a simple architecture, as shown below.

Client / server softwar architecture

The nasty thing about this architecture is that both arguments hold. Yes, validations in the database is fairly safe. And yes, validating until the data is in the database is fairly late. So now we keep two versions of our little validation rule. One in the database, and one in our form. It’s the same rule. For now.