Introductory example: BPMN validation

Overview

The aim of this example is two-fold:

  • to demonstrate how well-formedness (validation) rules can be easily specified using EMF-IncQuery;
  • to demonstrate the generic integration capabilities of the IncQuery framework; that is, the ability to work with almost any EMF-based tool out-of-the-box, without having to touch the source code of the original tool.

It is a good idea to check the School example walkthrough before reading this page.

Prerequisites

A working configuration may look like this (note that there are other features installed here which are not strictly necessary for this example):

Getting the example

Download the IncQuery project and some sample instance models from github:

Make sure to build the bpmn.incquery project to ensure that the bpmn.incquery.validation auxiliary project is generated and compile error free.

Trying the example

  1. Run the bpmn.incquery and bpmn.incquery.validation projects in a runtime Eclipse Application.
  2. Open the bpmn.instancemodel/default.bpmn_diagram in the newly launched Eclipse.
  3. Activate the context menu inside the diagram editor, select Initialize EMF-IncQuery Validators.
  4. Make sure the Problems view is open. It should look as follows:

If you now insert a new Flow connector edge between "Lonely" and "SomeTask", the warning markers will be automatically removed on-the-fly by the IncQuery Validation Engine. Similarly, if you rename the "Simple" looping activity to "Looping activity", the "bad looping activity" marker will disappear.

  • You can try editing the model and observing how the validation status will change (hint: take a look at the sample code below, and check the two well-formedness rules badLoopingActivity and lonelyActvity).
  • You can also try clicking on the warning markers to reveal the offending instance model elements in the abstract syntax editor.
  • Finally, you can try how IncQuery validation performs on a larger, real-life BPMN model with some examples found in the bpmn.instancemodel/reallife folder.

Developing validation rules

In order to turn an IncQuery pattern definition into a well-formedness rule, you simply need to add the @Constraint annotation, which takes three parameters:

  • location identifies the pattern parameter which should represent a model element that will be the "location" of the violation of the rule. By design of the EMF Validation Marker API, only a single element is allowed to be designated as the location.
  • message defines the validation error/warning message that will be shown to the user.
  • severity can take either "error" or "warning", giving the developer the possibility to distinguish between these two frequent cases.

The @Constraint annotation will trigger the generation of an auxiliary .validation project which contains some glue code that registers your rule with the IncQuery Validation Engine. The Validation Engine is a generic component that works with the Reflective Ecore model editor, generated EMF tree editors and also GMF-based graphical editors such as the STP BPMN modeler. Additionally, the Query Explorer view is also generic in the sense that it supports the "Show location" feature (by right clicking on matches inside the tree, or double clicking on them) to reveal the instance model elements inside your GMF diagrams automatically.

As the general rule-of-thumb, a meaningful validation pattern should define the "bad case", i.e. match for those cases that represent a violation of the well-formedness constraint. A common technique to specify such patterns is to create a pattern for the "good case", and then use the neg keyword for negation (see lonelyActivity below for an example).