How can logical domain modeling be made simple and collaborative?

Many non-technical end-users, managers and business domain experts find it difficult to understand the visual models offered by many UML tools. This creates trouble in capturing and verifying the information that goes into a logical domain model. The tools are also too advanced and complex for a non-technical user to learn and use.

We have therefore, in our current project, ended up with using Confluence as tool for designing the logical domain model with the help of a few very useful plugins. Big thanks to Ole Nymoen and Per Spilling for their expertise in this field that made this posting possible.

Confluence Plugins

Here is a list of Confluence plugins used in this solution. Install these before trying out the macros used below.

Plugin	Description
Copy Space	Allows a space administrator to copy a space, including the pages within the space
Metadata	Supports adding metadata to Wiki pages
Label	Manages labeling of pages
Linking	Contains macros for linking to templates, the dashboard and other
Table	Enhances the table capability in Confluence

Creating a Confluence Space

First we need to create a new confluence space for the domain model. Click the link Create a Space located below the list of spaces on the Dashboard. Please contact your Confluence administrator is you do not have permissions to do this.

 

For illustrative purpose all attributes and entities in this posting are based on my imaginary project manager domain model.

When a logical domain model is good enough for being implemented, do a copy of the Confluence Space (see Copy Space plugin). In this way you create a stable version of the logical domain model while further design can continue with the new copied space. Typical will the implementation phase result in a database design and/or a XSD schema design.

Add Space Templates

Go to the Home page of your Confluence Space. Navigate to the Browse drop-down menu and click on Advanced. Then click the Templates option in the left navigation panel.

Click Add New Space Template to add the following three templates.

Name: attribute

{metadata-list} || Name | | || Type | | || Format | | || Description | | {metadata-list} {add-label:attribute}

Name: primary-type

{metadata-list} || Name | || || Type | || || Format | || || Description | || {metadata-list} {add-label:primary-type}

Name: complex-type

{metadata-list} || Name | || || Description |  || {metadata-list} h3. Attributes || Name || Type || Format || Description || | [name] | {metadata-from:name|Type} | {metadata-from:name|Format} | {metadata-from:name|Description} | {add-label:complex-type,entity}

The metadata-list macro (see Metadata plugin) will save a list of metadata values to the page.

The add-label macro (see Label plugin) will automatically label the page.

Primary Types Page

Our first page to add will act as container for our primary types. Switch to Wiki markup when adding the following content to the page.

| (+) {add-page:template=primary-type|parent=@self}Add new primary type{add-page} | {metadata-report:Name,Type,Format,Description|sort=Name|root=@self|pages=@descendents}

Once the page is created, click the Add new primary type (create-page macro) to start creating a new pages.

Here is an example of input to the LocalDate page. Embrace the LocalDate with square brackets [] to make the page linkable. Again switch to Wiki markup before editing.

{metadata-list} || Name | [LocalDate] || || Type | Date || || Format | YYYY-MM-DD || || Description | Date in local time zone. YYYY = year, MM = month and DD = day || {metadata-list} {add-label:primary-type}

The metadata-report macro will show a tabular report of all child pages.

 

Attributes Page

The next page will act as container for all of our attributes.

| (+) {add-page:template=attribute|parent=@self|title=attribute}Add new attribute{add-page} | {metadata-report:Name,Type,Format,Description|sort=Name|pages=@descendants}

Here is an example of input to the startDate page.

{metadata-list} || Name | [startDate] || || Type | [LocalDate] || || Format | {metadata-from:LocalDate|Format} || || Description | The projects start date || {metadata-list} {add-label:attribute}

Using the metadata-from macro we fetch the text from the previously created LocalDate page.

Complex Types Page

The last page in this example shows how attributes can be combined together to form more complex types.  

h3. Intro Overview of complex types in the domain model. | (+) {add-page:template=complex-type|parent=@self}Add a new complex type{add-page}\\ | {metadata-report:Name,Description|sort=Name|root=@self|pages=@descendents}

Here is an example of input to the ProjectType page.

{metadata-list} || Name | [ProjectType] || || Description | Represents a project || {metadata-list} h3. Attributes || Name || Type || Format || Description || | [projectId] | {metadata-from:projectId|Type} | {metadata-from:projectId|Format} | {metadata-from:projectId|Description} | | [name] | {metadata-from:name|Type} | {metadata-from:name|Format} | {metadata-from:name|Description} | | [description] | {metadata-from:description|Type} | {metadata-from:description|Format} | {metadata-from:description|Description} | | [startDate] | {metadata-from:startDate|Type} | {metadata-from:startDate|Format} | {metadata-from:startDate|Description} | {add-label:complex-type,entity}

Gives us this

Conclusion

Using a web-based corporate Wiki like Confluence to create a logical domain model increases the collaboration between people with different roles in the enterprise. It’s my believe that this helps the domain model to be more accurate, and better documented.

In our real project we have more pages than illustrated here to complete the documentation. We do also still use UML tools to create different types of diagrams that Confluence do not support. As a last tip, an ImageMap plugin can make those diagrams clickable when used in pages.

Enjoy!