Where is Model-Driven Used?

German e-Government (some information on the XML standards inGerman,  an english description of the XGenerator tool used)

Telecommunications management interfaces (TMForum TIP interfaces)

US government information exchange (NIEM-UML)

And of course banking (ISO20022)

What gets Generated from the Models?

XSD, and sometimes WSDL.

Why is it used?

To ensure consistency in the messages and interfaces used in the domain.

What does consistency mean?

In banking, this means the message for making payments is similar to the message for sending out bank statements.

In telecommunications, this means the interface used to send an alarm about faulty equipment to a management system is similar to the interface used to activate a service on a piece of equipment.

In e-Government, this means that a message notifying others that a search warrant has been issued will be similar to a message notifying others that there has been an emergency call out.

When I say similar, I mean two things.

• First, it will be similar in technical structure.
• Second, if the message or interface includes similar sorts of information, the information will be represented in similar ways. For example, phone numbers will be represented in one uniform way.

What’s the benefit?

Using consistent technical structures means a programmer does not have to learn about new technical structures every time they have to deal with a new message or interface. This saves time.

Using consistent representations of the information saves time too. And reduces the chance of misinterpretations.

Another way of saying the same thing: it is easier for practitioners to work with a range of XML schemas and WSDLs that follow the same design patterns, and represent the same information in the same way, rather than with schemas that are individually handcrafted and inconsistent.

Making things easier reduces the so-called ‘integration tax’ in getting IT systems to work together.

How does model-driven ensure consistency?

This is for another day, but you use OCL constraints on the model, and force consistency through the generation process.

Do you know of other examples of model-driven?

If you do, leave a note.

Our suggestion

Get the team of people responsible for writing the business rule requirements to author and test the rules – for real.

You may well ask…

How can you do this if the team doesn’t know how to write code, and doesn’t work in a development environment?

Solution

Get the team to work with one of the standard modelling environments like MagicDraw. Give them a model of the business data, give them some very good examples of working rules, and then get them to write and test the rules – much better than excel.

What does this give you?

Take a look at our webinar

Take a look at our webinar.  We show how you can capture, execute and test rules using MagicDraw and the Cameo OCL Transformer, and generate rulesets that can be deployed to test and production systems.

Organise an online meeting

And we can help you get started.

But it’s hard to remember how to create them. A helpful hint: they are called generic tables in MagicDraw and are a type of diagram!

Here are some step by step instructions on how to create one.

You will need:

MagicDraw version 17.0 or later (though they may be available in a slightly earlier version of Magicdraw).

The Steps:

Select Diagrams->Diagram Wizards->Generic Table Wizard…

Enter a table name e.g. “OCL Rules”, and select a location for the table in your project. Spend a bit of time thinking about where it should go, but you can always move it afterwards.

Select the type of thing (element) you want to list in the table. For example, you could select a constraint element or a class element. In our case, we select an OCLTransfomerValidationRule Stereotype (stereotypes are listed after elements in the dialog).

Select the elements to be displayed in the table. We select the package Payments, and click ‘Add Recursively’. All OCLTransformerValidationRules under this package will be displayed in the table.

Select the columns to be added. We choose Name (the name of the rule), Owner (the context of the rule), specification (the OCL), and Error message (the description).

Click finish and the table is created.

Here’s what our table of OCL looks like.

 In Summary

It’s easy to create generic tables. They are very useful. And you can also customise them once they are created. It’s worth putting in a little effort to configure them in your project.

It is nearly 20 years since, in 1994, OCL evolved at IBM from Syntropy as a ‘business engineering language’. It is nearly 10 years since, in 2003, OCL 2.0 was split off from UML 2.0.

To understand the history of OCL, it is necessary to understand the history of UML, which arose in the 1990s as a compromise between competing modeling notations. This compromise is easy to criticize but to do so can ignore UML’s many successes, not least of which is that we no longer argue about the shape of a class; the Booch clouds have been consigned to history. UML and its SysML extension provide the standard graphical notations that can be used for a very wide range of modeling activities. Of course the real problem with UML is that it is too big and it lacks precision and so this is where progress is being made. Executable UML defines a subset with much more rigorous semantics. OCL provides the technology to express semantics rigorously.

OCL is a natural evolution from the original formula translation in Fortran. Data and objects are accommodated by ‘dot’ operators as in Pascal or C or Java, so OCL is object-oriented. UML models are used as the type system for these objects so that OCL is model-oriented. Concepts from functional languages and lambda calculus are adopted so that OCL is collection-oriented, with the ‘arrow’ operator providing operations and iterations on collections of objects. The ideas for OCL originated within IBM and with the benefit of hindsight may seem rather obvious; they represent a very pragmatic compromise between the lack of precision of informal language and formal languages such as Z that are perceived to be too complex and consequently unapproachable to many programmers.

The problems of ‘business engineering’ are still very much with us 20 years on. In modern parlance, how do we ensure more effective communication between business and IT? How do we capture business logic as an architecturally distinct component of a software system? OCL and models still have a role to play.

From our work with many real world XML Schemas at Nomos Software, we see evidence that model-driven can deliver.

Here’s an example from the domain of financial messaging standards. FpML (handcrafted XML schema for an admittedly complex domain, derivatives trading) is much more complex than ISO20022 (a set of XML schemas for a variety of financial transactions, created using a model-driven approach).

Defining standards is notoriously difficult: creating something simple that caters for all scenarios.

Everything should be made as simple as possible, but no simpler – Albert Einstein

Let’s explore a bit more.

FpML

FpML is a financial messaging standard for derivatives trading. It is a set of many inter-related XML Schemas. The message schemas are large and complex. FpML is complex in part because derivatives trading is itself complex. But the schemas are also complex because they were defined when XML Schema itself was quite a new standard, they are handcrafted, and they are designed to be used in a large number of different scenarios.

IT teams working with FpML have to work with this complex set of schemas.

ISO20022

Now consider ISO20022. ISO20022 is a set of financial messaging standards covering securities, payments, and corporate actions among others. ISO20022 messaging is defined using a model-driven approach. One large model is created (in UML, and more recently in Eclipse EMF), and individual message schemas are generated from this single large model. Each XML Schema that is generated has a specific purpose. So for example, there is an XML Schema for initiating payments, and there is another XML Schema for bank account statements

ISO20022 is dramatically simpler

What is clear when you look at the ISO20022 messaging is that the XML Schemas are dramatically simpler than the FpML Schemas.

For a bird’s eye view of the difference, take a look at FpML schemas on the file system:

You can download the FpML schemas from here.

Compare this to an ISO20022 schema:

You can download the ISO20022 schemas from here.

Simpler in what ways?

ISO20022 is made up of many different individual messages.

Each message is used for a single purpose.

Each message is a single schema with no imports.

Complex constructs like substitution groups are not used.

This all means it is easier for IT teams to use ISO20022 messaging.

How has model-driven helped?

It ensures simplicity combined with consistency.

For simplicity, you need a single message for a single purpose. But the messages also need to be consistent with each other. Maintaining consistency across many messages is very difficult if each message is handcrafted independently. With model-driven, consistency is managed in the main model, and simple messages for a single purpose are generated from there.

For simplicity, the XML schemas need to be ‘technically’ straightforward (e.g. no imports and no substitution groups) and ‘technically’ consistent (if an IT team learns how to use an ISO20022 message for one purpose, there should be no technical barrier to using a second ISO20022 message for another purpose). Simple XML schemas can be handcrafted, but once again, ensuring that a large number of handcrafted schemas are consistently simple is difficult. With model-driven, the generation step can be used to programmatically ensure ‘technical’ simplicity.

A sidebar: some of the people involved in ISO20022 had previously been involved in FpML.

Consistency of Design in ISO20022

ISO20022 creates many disparate XML Schemas for different purposes. Consistency across this set of messages needs to be maintained. ISO20022 replaces previous messaging standards e.g. ISO15022. Because a model-driven approach was used for ISO20022 and not for previous standards, there is much more consistency across the different ISO20022 messages.

In Summary

Consistency combined with simplicity would not be possible without a model-driven approach. ISO20022 may not be perfect, but it is a success story for model-driven. ISO20022 impacts hundreds of thousands of IT teams: it is being used by all European banks and corporates for payments, and adoption is only set to grow  ISO20022 messages must be simple. The modelling step has shown a high return on investment for the whole the finance industry and those who depend on it.

Any Comments?

What are your experiences with ISO20022 and FpML? What other approaches work to create simple XML schemas for broad and complex domains? Contact us if you would like to discuss more.

You will need…

To have followed the steps in the first post!

Create a code engineering set

You may or may not see a ‘Code engineering sets’ node in the MagicDraw containment tree. If you don’t, click on the ‘Show Code Engineering Sets’ icon at the top of the tree to make the node visible.

To create a code engineering set, select the ‘Code engineering sets’ node in the tree, right click and select New->XML Schema from the popup menu.

You will be prompted to give the set a name. In our example, we use PaymentsSchema.

A new node then appears in the tree.

Configure (edit) the code engineering set

You will need to identify the model that is the basis for the schema generation (the transformed model). Click on the new node, and select ‘Edit…’ from the popup menu.

In the code engineering set dialog, select the tab ‘Add Data from Model’. Select the package containing your transformed model (‘Payments Schema’ in our example), and click ‘Add Recursively’. An entry ‘schema.xsd’ will appear in the right hand column.

Close the dialog.

Rename the ‘schema.xsd’

By default, the name of the generated schema is ‘schema.xsd’. But it is useful to give your XML schema file a meaningful name. The name of the .xsd node under code engineering sets in the tree is what determines the name of the XML schema file. We recommend you rename it.  Select schema.xsd and from the popup menu, select Rename. In our case, we rename to paymentsSchema.xsd.

You will notice that a File View package has appeared in the tree. This contains a component element representing the schema file.  You don’t need to do anything with this!

Generate the XML schema

You are now ready to generate the schema. Select the .xsd node, right click and select ‘Generate’ from the popup.

You will need to select the output directory. We use the default in our example – the install location for MagicDraw.

Your schema should now be generated.

Locate the .xsd file in the output directory and open in an XML editor. Check what it looks like and make sure it is a valid schema – most XML editors will provide an option to check the schema is valid. Here’s a visual representation of what the schema looks like for our payments example:

And try generating an XML file from it  – again, most XML editors will give you this option.  Here’s what an XML file based on our example schema.

Now you can add OCL rules…

Once the schema generation is working, you can start adding OCL business rules to the MagicDraw model, and generate executable rulesets from the OCL. Use the XML schema to validate that your XML files are syntactically correct, and use the executable rulesets to validate that the content of the XML files meets your business rules. Take a look at the Cameo OCL Transfomer product for details.

And don’t forget the tip about rerunning transformations

When you make changes to the classes in the source package, you will need to run a transformation again – and regenerate the schema. If you run the transformation from scratch, the changes you made to add a global element to the .xsd class in the transformed model will be lost. Instead, you can update the transformed model. Use the ‘update transformed model’ option. Select the target model in the tree (Payments Schema package in our example). Right click and select Tools>Update Transformed Model’ from the popup menu.  Select the option to Change destination properties according to source, and ‘refresh’ the model.

To regenerate the XML schema, just select .xsd node under Code engineering sets again, and select the ‘Generate’ option from the popup menu. The XML schema file is regenerated and will reflect the changes made to your source model (new classes, changed properties etc).

What we are using

• MagicDraw 17.0.1 Enterprise Edition
• The Cameo Data Modeler

If you are using an earlier version of MagicDraw, you won’t need the Cameo Data Modeler.

You will need…

A class model in MagicDraw, your ‘source model’, ideally with a class diagram. For example, something like the following. The Payments package on the left contains classes and a diagram.

The main steps

Starting with the UML class model:

1. Use ‘Model Transformations’ to transform the class model to a UML model of an XML Schema
2. Make some small updates to the transformed model
3. Use a ‘Code Engineering Set’ to generate an XML Schema (a .xsd file) from the transformed UML model

We will cover the first two steps in this post. Check out ‘How to Generate an XML Schema from MagicDraw – II‘ for details on the third step.

What the transformation step does

In step 1, elements from the ‘source’ model are created in a ‘target’ model and  ‘stereotyped’ to identify how the elements in the class model are to be represented in XML schema. For example, the Payment class in the source model gets transformed into a Payment class stereotyped as <XSDcomplexType>, with properties stereotyped as <XSDelement>s, etc…

Doing a transformation

To transform the class model to an ‘XML Schema’ model, select the Menu ‘Tools->Model Transformations’.

This opens the Model Transformation Wizard. Select the UML to XML Schema transformation type. If you have not already included the modules needed for schema transformations, these will be automatically included by MagicDraw at this point.

Click Next, and select the ‘source’ for the transformation, that is, select the package containing the class model. In our example, we select the Payments package.

Select the destination for the transformation, the ‘target model’. We choose to place the transformation in a package called Payments Schema, and create a new package for this purpose.

At this point, click Finish, skipping steps 3, and 4 (accepting the defaults that MagicDraw uses), and the source model gets transformed.

The new Payments Schema package is populated with the transformation. Take a look at the tree below. You will see that the new Payments Schema package now contains a Payments package almost identical to the source package Payments. It contains classes of the same name as the classes in the source package, and a diagram of the same name as the original diagram.

Note that  there is one addition – a Payments.xsd class. You will need to make some updates to this.

But first take a look at the diagram that was generated. You will see that the classes in the target model are stereotyped as XSD constructs.

You will also notice that the diagram is a bit of a mess. This is easy to correct. Select one of the options from the Layout menu, and you should get a diagram looking something like this:

Making updates to .xsd element in the transformed model

Look again at the newly created class, Payments.xsd in our example. This represents the XML schema itself. The name comes from the package name in the source model. Drag this class onto your class diagram.

You will see that it is stereotyped as an ‘XSDSchema’.

If this is to be a top level schema, you will need to add at least one ‘global element’ to the .xsd class (Payments.xsd in our example). We will create a global element of type ‘BulkPayments’, so that any XML file based on this XML schema will need to contain a global ‘BulkPayments’ element.

Create a property element on the class (right click New element->Property). Double click on the property to open the Specification dialog, type in a name (bulkPayment in our example), and choose the type. We  set it to the BulkPayments class in the target package (from PaymentsSchema).   Tip: If you start typing the name of the class in the entry field e.g. Bul, the list of classes starting with B will be displayed.

The property needs to be stereotyped as an ‘XSDElement’. Update the ‘Applied Stereotype’ field in the Specification dialog.

Your XSDschema class should now look something like this:

In case you want to set your own URL…

One of the tags on the class defines the namespace for the schema. The namespace is defaulted to the name of the package in the source – Payments in this case. If you want to change this to a URL, double click on the Payments.xsd class to open the Specification dialog, select tags and change the value of the Namespace tag e.g. to something of the form http ://my.namespace/ package. But this step isn’t essential.

You are now ready….

You are now ready to create an XML schema (.xsd file) using a code engineering set. Check out the blog post ‘How to Generate an XML Schema from MagicDraw – II’ for details.

One final important tip on rerunning transformations

If you make a change to classes in the source package, and transform again, the .xsd class will be created and the ‘global element’ property that you added manually will be removed. To avoid this, use the ‘update transformed model’ option. Select the target model in the tree (Payments Schema package in our example). Right click and select Tools>Update Transformed Model’ from the popup menu.  Select the option to Change destination properties according to source, and ‘refresh’ the model.

To make things clear, we will follow the steps outlined in the OpenAPI UserGuide. We’ll show where we couldn’t follow the steps exactly, and what we had to do.

The post is based on MagicDraw Version 17.0.1 and Eclipse Indigo Service Release 2.

Here goes….

Step 1: Create Java Eclipse Project for MagicDraw Plug-in

We already had an existing project. We didn’t want to create a new one, so we had to skip this step. However, we did need to add all of the MagicDraw libraries to the project’s build path. Just like the guide recommends, we created a user library in Eclipse, which we called ‘MagicDraw’, and added it to the project’s build path.

We had previously developed some smaller plug-ins(that we didn’t debug in Eclipse), and had already added some libraries to the build path. These were MagicDraw specific jar files, such as md_api.jar, md.jar, md_common_api.jar, etc. If you have added any, it’s best to remove them before adding the user library you’ve created, because they may not be as up to date as the libraries your current MagicDraw version uses. We then added all of the libraries we need for our project, for example JAXB and Xbean libraries(it doesn’t matter if there are similar libraries in the user library you created). Some of the libraries may conflict with MagicDraw’s, but they are necessary, as you may have a different version than the one contained within the MagicDraw lib folder.

To ensure no conflict occurs, when you start, or debug MagicDraw in Eclipse – right click on your project → Build Path → Configure Build Path… then, click the ‘Order and Export’ tab. Once there, we made sure that the order was as follows: our source project was on top, followed by the JDK, then our ‘MagicDraw’ user library was located ABOVE any other jar, or library that we added to the project. After that, there was no particular precedence.

Step 2: Create Plug-in Main Class

Follow step 2 from the MagicDraw OpenAPI UserGuide, “Each MagicDraw plug-in main class must extend the com.nomagic.magicdraw.plugins.Plugin class and implement its methods ……… However, please remember that the Eclipse generated implementation for isSupported() and close() methods returns the false value which should be changed to true for enabling the plug-in initialization and disposing.”

Step 3: Prepare Plug-in Descriptor File

Step 3 from the MagicDraw OpenAPI UserGuide says “The plug-in descriptor XML file should be written as described in “Step 4: Start MagicDraw From Eclipse Environment” on page 23 and placed to the <MagicDraw installation directory>\plugins\my_plugin_name directory.

Please note, that even plug-in descriptor file contains information about runtime plug-in jar, it is not necessary to build and deploy this jar to plug-in directory while plug-in is developed under Eclipse IDE.”

So, just add a plugin.xml file to the <MagicDraw installation directory>\plugins\my_plugin_name directory. You won’t need anything else. (This step also mentions different properties that are needed in the plugin.xml file, but they are needed, only when the plug-in is actually deployed in MagicDraw. This is outside the scope of this post but, we will come back to this in a future one.)

Our plugin.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="nomos.plugin.five"
         name="Nomos Plugin Five"
         version="1.6"
         provider-name="nomos"
         internalVersion="15010"
         class="com.nomos.noMagic.NomosNoMagicPlugin5">
</plugin>

‘com.nomos.noMagic.Plugin5′ is the package in our Eclipse project, that contains our plug-in’s source code. NomosNoMagicPlugin5 is the plug-in main class in that package, mentioned in Step 2.

Step 4: Start MagicDraw From Eclipse Environment

Create a new debug, or run configuration, and add ‘com.nomagic.magicdraw.Main’ as the ‘Main class’. Make sure your source project is set as the ‘Project’.  MagicDraw output can be redirected to Console by specifying the -verbose key in ‘Program arguments’ under the ‘arguments’ tab. In the VM arguments add -Xmx800M -XX:PermSize=4M -XX:MaxPermSize=135m -Dinstall.root=”someDrive/someFolder/MagicDraw”. Then click debug, or run! You can also specify -Dmd.plugins.dir=”someDrive/CustomPluginFolderWithPlugInDotXml/” if MagicDraw needs to be loaded with custom plug-ins only.

Do you notice any of these problems?

In the Eclipse package folder there are .properties files

Well, they shouldn’t be there. Remove the files from the package and try again. The package should only contain the files that are vital for your plug-in.

There is more than one plug-in in the project

We work on a few things for MagicDraw, and test our plug-ins in MagicDraw on its own, so we have already imported some of them via the ‘Resource/Plugin Manager’.  Go to the package (in Eclipse) containing any plug-in that is installed in MagicDraw and  exclude them from your project’s build path. Rebuild your workspace and try again.

Still having an issue?

Leave a comment!

Learn More

Check out the rest of the MagicDraw OpenAPI UserGuide.

See Xavier Seignard’s posts on  how to develop MagicDraw plugins and debugging in Eclipse.

Read about our MagicDraw plugins.

But what are the mechanics of adding rules into a modelling environment. Here’s how it’s done in MagicDraw. You’ll find similar mechanisms in other modelling environments.

This example uses MagicDraw Enterprise edition 17.0.1.

Let’s assume you have created the very simple model shown in the OCL Examples post in MagicDraw.

Add a Constraint Rule

To add an OCL rule to the Payment class, select the class in Magicdraw (this is the ‘context’). Right click and select ‘New->Element->Constraint’.

A new constraint rule appears in the tree under the selected class.

Type in a Name

Type in a name for the rule on the tree e.g. FrenchCurrency.

Write the rule in Natural Language

Always write the rule in english (or another spoken language) first. We always define constraints as Validation Rules, and use the ‘error message’ field to add a natural language description. The error message field is only available if you stereotype the constraint as a validationRule. But you could create a Comment under the constraint and add the description there. In fact, sometimes we add both an error message and a higher level business description in a Comment.

To make the constraint a validation rule, select the new constraint in the tree, right click, select Stereotype, and tick ‘Validation Rule’. You can type the first letter of the stereotype, v, to quickly find the right stereotype – saves scrolling through a long list of stereotypes.

If you are using the Cameo OCL Transformer, stereotype the constraint as OCLTransformerValidationRule.

Now double click the constraint in the tree. The constraint dialog opens.

To add the description, click on the ‘Error Message’ field. Type directly into the entry box, or click on the ‘…’ button and type the message into a dialog.

If the country is France, the currency must be euro

If you are using the Cameo OCL Transformer, you will also need to provide a name in ‘ruleset’ field.

Add the OCL Expression

OCL gets added to the Specification field in the Constraint dialog.  When you click on the Specification entry field, a ‘…’ button appears. Click to open the Specification dialog.

For Language, select ‘OCL2.0’.

Now type the OCL into the dialog:

Country = ‘france’ implies Currency = ‘EUR’

That’s it. An OCL rule has been created.

To create a second rule

Creating a second rule is much easier. Just copy and paste the first rule. Then edit the rule name, the Error Message and the OCL. This saves on a few of the steps.

(Note: you can also manage your rules in a separate package in the model, rather than adding the rules to their ‘context’. Just add constraint rules to a package, and select the context in the Constraint dialog.)

Learn more

Watch out for our post on how to view OCL in the MagicDraw generic table. Makes it easy to view related rules together.

If you want to turn OCL rules captured in MagicDraw into executable rulesets and use the rulesets in development and test environments, contact us about our Cameo OCL Transformer product.

The data models are a mine of useful information. Everyone on the project team needs to know about them – from Information Modellers, to Business Analysts, to Testers to Project Managers. But what they need to know about is the business concepts captured in the model, not the XML Schema constructs. They need to be able to see the wood from the trees.

That’s why it’s a good idea to load the XML schemas into the UML modelling environment you use. Let your modelling team browse the models that the development team are actually using. Publish the models on your web portal so everyone on the project can browse a business-centric view of the models.

UML Model of XML Schema, in Web Browser

Nomos provides tools to load XML Schemas into modelling environments. The Cameo XSD Import product for MagicDraw creates a business-centric model with one click. Read about the product, buy from NoMagic, or contact us for information about integrations with other environments.