- 10.1. Installation
- 10.2. Source code
- 10.3. Designer UI Explained
- 10.4. Support for Domain-specific service nodes
- 10.5. Configuring Designer
- 10.6. Generation of process and task forms
- 10.7. View processes as PDF and PNG
- 10.8. Viewing process BPMN2 source
- 10.9. Embedding designer in your own application
- 10.10. Migrating existing jBPM 3.2 based processes to BPMN2
- 10.11. Visual Process Validation
- 10.12. Integration with the jBPM Service Repository
- 10.13. Generating code to share the process image, PDF, and embedded process editor
- 10.14. Importing existing BPMN2 processes
- 10.15. Viewing Process Information
- 10.16. Requirements
Web-based process editing is possible using the jBPM Designer. The designer is fully integrated into Drools Guvnor, the knowledge repository where you can store all your BPM assets such as of course your BPMN2 processes as well as rules, process images, workitem configurations, and process forms. The Designer can be used to create, view or update BPMN2 based processes which are executable in the jBPM runtime environment.
Designer targets the following scenarios:
- View and/or edit existing BPMN2 processes: The designer allows you to open existing BPMN2 processes (for example created using the BPMN2 Eclipse editor or any other tooling that exports BPMN2 XML) in a web context.
- Create fully executable BPMN2 processes: A user can create a new BPMN2 process in the Designer and use the editing capabilities (drag and drop and filling in properties in the properties panel) to fill in the details. This for example allows business users to create complete business processes all inside a a browser. The integration with Drools Guvnor allows for your business processes as wells as other business assets such as business rules, process forms/images, etc. to be stored and versioned inside a content repository.
Designer supports all BPMN2 elements that are also supported by jBPM as well as all jBPM-specific BPMN2 extension elements and attributes.
If you are using the jBPM installer, this should automatically download and install the latest version of the designer for you. To manually install the designer, simply drop the designer war into your application server deploy folder. Currently out-of-the-box designer deployments exist for JBoss 5.1.0 and JBoss AS7. Note: If you want to deploy on other (versions of an) application server, you might have to adjust the dependencies inside the war based on the default libraries provided by your application server. The latest version of the designer can be found here.
To start working with the designer, open Guvnor (e.g. http://localhost:8080/drools-guvnor) and either open an existing BPMN2 process or create a new one (under the "Knowledge Bases category on the left, select create new BPMN2 process"). This will open up the designer for the selected process in the center panel. You can use the palette on the left to drag and drop node types and the properties tab on the right to fill in the details (if either of these panels is not visible, click the arrow on the side of the editor to make them move forward).
The designer may also be opened stand-alone by using the following link: http://localhost:8080/designer/editor?profile=jbpm&uuid=123456 (where 123456 should be replaced by the uuid of a process stored in Guvnor). Note that running designer in this way allows you to only view existing processes, and not save any edits nor create new ones. Information on how to integrate designer into your own applications can be found here.
The designer source code is available for each release. You can find it here.
You can also browse and clone the project on github.
The Designer UI is composed of a number of sections as shown in the screenshot below:
- (1) Shape Repository Panel - the expandable section on the left shows the jBPM BPMN2 (default) shape repository. It includes all shapes of the jBPM BPMN2 stencil set which can be used to assemble your processes. If you expand each section sub-group you can see the BPMN2 elements that can be placed onto the Designer Canvas (2) by dragging and dropping the shape onto it.
- (2) Canvas - this is your process drawing board. After dropping different shapes onto the canvas, you can move them around, connect them, etc. Clicking on a shape on the canvas allows you to set its properties in the expandable Properties Window (3)
- (3) Properties Panel - this expandable section on the right allows you to set both process and shape properties. It is divided in two sections, namely "Often used", and "More Properties" section which is expandable. When clicking on a shape in the Canvas, this panel is reloaded to show properties specific to the shape type. If you click on the canvas itself (not on a shape) the section shows your general process properties.
- (4) Toolbar - the toolbar contains operations which can be performed on shapes present on the Canvas. Individual operations are disabled or enabled depending on what is selected. For example, if no shapes are selected, the Cut/Paste/Delete operations are disabled, and become enabled once you select a shape. Hovering over the icons in the Toolbar displays the description text of the operation.
- (5) Footer - the footer contains operations that allow users to view the source of the process being editor in the Canvas section in various formats such as BPMN2, PNG, JSON, etc.
- (6) Process Information - this section contains information about your process, such as its name, creation date, version, etc
Connecting shapes together in the canvas is realized with the Shape-Menu. The Shape-Menu is displayed by clicking on a shape:
The Shape-Menu is composed of two sections:
- (1) Connection section: allows you to easily connect your shape with a new one. The shapes displayed in this section are based on connection rules of the BPMN2 specification.
- (2) Morphing section: allows you to easily morphe a base shape into any other that extend this base shape.
Following sequence of picture shows how easy it is to quickly create and connect multiple shapes in the canvas:
You can also name your shapes by double-clicking on the shape in the canvas. This sets the name attribute of the particular shape:
Designer has full support for jBPM domain-specific service nodes. To include your service nodes in the Designer jBPM BPMN2 stencil set, you can either upload your existing service node definitions into Guvnor, or use the the new service node configuration editor which we added to Guvnor to create new configurations.
Once you have some service node configurations present, you can see them being included in Designer stencil set by re-opening an existing or creating a new process. Your service nodes will be now available under the "Service Task" section of the jBPM BPMN2 stencil set.
Service nodes are fully usable within your processes. Please note that the service node configurations are package-specific in Guvnor. If you want to re-use your service nodes across multiple Guvnor packages, you have to copy their configurations to each indidual package you would like to use them in.
For more information on this feature please view this, and this video.
Designer is tightly integrated with Guvnor. By default Designer expects to find a Guvnor instance on http://localhost:8080/drools-guvnor/. Guvnor, by default, expects to find the Designer on http://localhost:8080/designer. Here we show how to configure both Designer and Guvnor to be able to change these default settings when needed.
In cases where Guvnor is configured to use https, or is running on a different host/port/domain/subdomain you have to configure Designer to reflect these settings. in order to change Designer configurations you have to deploy it as an exploded war. In $designer.war/profiles/jbpm.xml notice the section on the bottom:
<externalloadurl protocol="http" host="localhost:8080" subdomain="drools-guvnor/org.drools.guvnor.Guvnor/oryxeditor" usr="admin" pwd="admin"/>
The configuration attributes include:
- protocol: the protocol to use (http/https)
- host: includes both the host and the port that Guvnor is running on
- subdomain: in some situations Guvnor subdomain is not drools-guvnor. You should leave the path to the servlet as-is.
- usr: if you have set up JAAS authentication in Guvnor, provide a Guvnor user name here. Note that this user should have admin privileges in Guvnor
- pwd: password for the Guvnor user
Alernative you can specify these configrations via system properties:
- oryx.external.protocol
- oryx.external.host
- oryx.external.usr
- oryx.external.pwd
If you choose to use system properties you do not have to deploy the designer war as exploded.
To configure Guvnor to reflect the host/port/domain/subdomain and the default profile settings of the Designer, we need to edit $drools-guvnor.war/WEB-INF/preferences.properties:
#Designer configuration designer.url=http://localhost:8080 #Do not change this unless you know what are you doing designer.context=designer designer.profile=jbpm
The configuration attributes include:
- designer.url: set the protocol, host, and port where Designer is located at
- designer.context: this sets the configured subdomain of Designer. Should not change unless you deploy it under some other subdomain
- designer.profile: Designer can have multiple profiles defined. Profiles determine the used stencil set, the saving/loading strategy of processes, etc. The default profile name used is "jbpm" and this should not be changes unless you create a custom profile to be used
Note that in order to be able to edit $drools-guvnor.war/WEB-INF/preferences.properties, you have to deploy Guvnor as an exploded archive.
Designer allows users to generate process and task ftl forms. These forms are fully usable in the jBPM console. To start using this feature, locate the "Generate Task Form Templates" button in the designer toolbar:
Designer will iterate through your process BPMN2 and create forms for your process, and each of the human tasks in your process. It uses the defined process variables and human task data input/output parameters and associations to create form fields. The generated forms are stored in Guvnor, and user is presented with a page which shows each of the forms created as well as a link to their sources in Guvnor:
As mentioned, all forms are fully usable inside jBPM console. In addition each form includes basic JavaScript form validation which is determined based on the type of the process variables, and/or human task data input/output association definitions. Here is an example generated human task form.
In order for process and task forms to be generated you have to make sure that your process has it's id parameter set, as well that each of your human tasks have the TaskName parameter set. Task forms contain pure HTML, CSS, and JavaScript, so they are easily editable in any HTML editor. Please note that there is no edit feature available currently in Designer, so each time you generate forms, existing ones will be overwritten.
For more information on this feature please view this video.
Any process created in Designer can be easily viewed in PDF and PNG formats. In the Designer footer section locate the "Convert to PDF" and "Convert to PNG" buttons. Both PDF and PNG formats are also stored in Guvnor, making it easily accessible.
The footer section also includes buttons to view the process sources in ERDF, JSON, SVG, and BPMN2 formats.
At any time you can view your process's BPMN2 source by selecting the Source->View Source link in the Guvnor toolbar above the designer frame. The soure generated by designer is fully BPMN2 compliant and can be used in any BPMN2 compliant editor.
Same can be done by clicking on the BPMN2 button in the footer section of the designer:
It is possible to embed the designer in your own application and still be able to utilize Guvnor as the asset repository for all of your process assets. For more information on this feature please view this video.
To migrate your existing jBPM 3.2 based processes to BPMN2 locate the migration button in the toolbar section of the designer:
The feature allows users to select the location of their processdefinition file, and the location of it's gpd.xml file. Designer then uses the jbpmmigration tool to convert the jBPM 3.2 based processes to BPMN2 and displays it onto the designer canvas:
For more information on this feature please view this video.
To run process validation against the process you are developing in the designer, locate the validation button in the designer toolbar section:
In case of validation errors, designer presents a red "X" mark next to process nodes that contain them. Mouse-over this red "X" presents a tooltip with the descriptions of validation errors. Note that since the process node is not visually displayed, designer will merge all process-node-specific validation errors with those of the very first node of the BPMN2 process. Following is a screenshot of the visual process validation feature in use:
For more information on this feature please view this video.
Designer integrates with the jBPM Service Repository and allows users to install and use assets from the repository.. To connect to the Service Repository from designer, click on the service repository button in the designer toolbar:
Designer will present you with all assets located in the jBPM service repository in table format. Colums of this table show information about the specific asset in the repo. To install the item to your local Guvnor package, simply double-click on the item row. You will have to save and re-open your process in order to be able to start using the installed items.
For more information on this feature please view this video.
It is important to be able to share your process with users who do not have access to your running designer instance. For these cases designer allows code generation of "sharable" image, PDF and embedded editor code of your processes. To use this feature locate the following dropdown in the designer toolbar section:
You can easily import your existing BPMN2 processes into the designer by locating and clicking on the following dropdown selection list in the toolbar section:
You will be able to either select an existing file on your filesystem or paste existing BPMN2 XML. The designer canvas will automatically import and display your process without a page refresh.
The Process Information section displays important information about your process. These include the process:
- name
- format
- Guvnor package name the process belongs to
- creation date
- name of user that created the process
- last modification date
- last check-in comment
- version number