Category Archives: Architecture

Architecture Development

How to use Environment Variables in WildFly Docker Containers

When setting up a Wildfly server, it is possible to use environment variables in the standalone.xml file by using the Bean Shell expression.

See the following example which sets up the database, user and password in a database configuration in the standalone.xml file by accessing environment variables:

<datasource jta="true" jndi-name="java:/jdbc/my_datasource" pool-name="my_pool" enabled="true" use-ccm="true">
    <connection-url>${env.POSTGRES_CONNECTION}</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <driver>postgresql</driver>
    <security>
      <user-name>${env.POSTGRES_USER}</user-name>
      <password>${env.POSTGRES_PASSWORD}</password>
    </security>
</datasource>

With the Bean Shell expression it is not necessary to turning parameters into System Properties: just use the expression:

${env.SYSTEM_ENVIRONMENT_VAR}

Especially when running wildfly in a docker container, this can be very helpful, because you can pass through environment variables to the container:

docker run --name="wildfly" -d -p 8080:8080 -p 9990:9990 \
    -e WILDFLY_PASS="admin_password" \
    -e POSTGRES_USER="my-postgres-user" \
    -e POSTGRES_PASSWORD="mypassword" \
    -e POSTGRES_CONNECTION="jdbc:postgresql://postgres/mydb" \
    imixs/wildfly

Also in combination with docker-compose environment variables can be set in the docker-compose.yml file. See the next example of a docker-compose.yml file, which sets up a postgres service and a wildfly service with a connection pool configuration as defined before in the standalone.xml:

postgres:
 image: postgres:9.6.1
 environment:
 POSTGRES_PASSWORD: mypassword
 POSTGRES_DB: mydb

mywildflyservice:
 image: imixs/mywildfly
 environment:
 POSTGRES_USER: "my-postgres-user"
 POSTGRES_PASSWORD: "mypassword"
 POSTGRES_CONNECTION: "jdbc:postgresql://postgres/mydb"
 ports:
 - "8080:8080"
 - "9990:9990"
 - "8787:8787"
 links: 
 - postgres:postgres

This is an example, which we use in combination with the wildfly docker container provided by the Imixs-Workflow project.

Architecture Development

Don’t model Business Behavior in Objects!

During the past years I saw many projects where nearly any kind of business requirements was modeled into the technical object model, independent of the reason of the requirement. In many cases, modelling business requirements into a technical object model is quite ok and I agree with it in general. But also modelling business requirements into the affected business objects can lead into a ugly and complicated data structure. Let’s look into a short example to illustrate my thoughts: read more »

Architecture

How to Integrate Imixs-Workflow with Single Sign On

Imixs-Workflow can now be easily combined with the Open Source Identity and Access Management solution Keycloak. Keycloak is an Open Source Identity and Access Management Server which can be used together with Wildfly to authenticate users with a modern authentication mechanism based on OpenID Connect SAML and OAuth. This is a short tutorial how to setup the Single Sign On Server Keycloak and configure the Imixs-Workflow to authenticate users. read more »

Architecture Development

How to secure Business Objects

This post explains how you can secure your business objects in a model driven way, using the Imixs-Workflow engine.

Most applications deal with security in a functional way. This means that a business application typically defines different functional roles which are mapped to different users. For example let’s look on a simple Ordering System. In an Ordering System, we will have roles like

  • Order-Creator‘ – creating the order
  • Order-Approver‘ – validating and approving
  • Order-Executor‘ – execution

These roles are typical for such an business application and mostly tightly coupled to the corresponding business methods – e.g. createOrder(), approveOrder() and executeOrder(). This works well in a monolithic business application where you can control the security layers as also the business logic. But as more complex the business application becomes, also the enclosed security becomes more complicated. For modern application design, in addition, you often have to deal with external web services and business logic which need to be adapted easily to changing requirements. So this static security model leads into a hell of hard coded business rules or, what is worse, can no longer guarantee the security. read more »

Architecture Development

How to Run a Custom Build of Imixs-Office-Workflow Using Docker

The Imixs-Workflow project supports Docker and provides also a Docker image for the workflow management suite ‘Imixs-Office-Workflow‘. Imixs-Office-Workflow provides a full featured business process management suite and can also be used to be extended in various ways. With Docker it becomes easy to setup a custom build for development, test and productive environments.

Setup a New Custom Build

To setup a new custom build of Imixs-Office-Workflow you can use the Imixs-Office-Archetype maven project, which provides a simple starting point for custom development. To run you custom build using Docker you should add a docker folder into your project with the following structure:

-/.data
-/.deployments
-/configuration
 |-standalone.xml
-docker-compose.yml
-Dockerfile

Customize Wildfly standalone.xml

First you can use the standalone.xml file located in the /configuration folder to configure your wildfly server to your project needs. Typically this will be a data-pool configuration and a security realm. This is an example of a custom database pool configuration which can be run in a docker container to access a postgres database running in another Docker container:

...
  <datasource jta="true" jndi-name="java:/jdbc/office-test" pool-name="office-test" enabled="true" use-ccm="true">
 <connection-url>jdbc:postgresql://postgres/office-test</connection-url>
 <driver-class>org.postgresql.Driver</driver-class>
 <driver>postgresql-9.3-1102.jdbc41.jar</driver>
 <security>
 <user-name>postgres</user-name>
 <password>adminadmin</password>
 </security>
 <validation>
 <validate-on-match>false</validate-on-match>
 <background-validation>false</background-validation>
 </validation>
 <timeout>
 <set-tx-query-timeout>false</set-tx-query-timeout>
 <blocking-timeout-millis>0</blocking-timeout-millis>
 <idle-timeout-minutes>0</idle-timeout-minutes>
 <query-timeout>0</query-timeout>
 <use-try-lock>0</use-try-lock>
 <allocation-retry>0</allocation-retry>
 <allocation-retry-wait-millis>0</allocation-retry-wait-millis>
 </timeout>
 <statement>
 <share-prepared-statements>false</share-prepared-statements>
 </statement>
 </datasource>
 ...

Note that the connection-url points to the host ‘postgres’ which need to be linked later to this container.

The Dockerfile

Next you can create a custom Dockerfile to describe you Imixs-Office-Workflow container for your custom build:

FROM imixs/office-workflow:latest
# add custom standalone.xml file
ADD configuration/standalone.xml /opt/wildfly/standalone/configuration/

The Dockerfile is quite simple. It extends the office imixs/office-workflow container and adds the new custom configuration file standalone.xml into the container

Docker-Compose

We use now docker-compose to describe the environment where we run a PostgreSQL Server, a WildFly Application Server and our custom build of Imixs-Office-Workflow.

 postgresloml:
  image: postgres:9.4.6
  environment:
    POSTGRES_PASSWORD: adminadmin
    POSTGRES_DB: office-test
  volumes:
    - ./.data/db:/var/lib/postgresql/data

 officetest:
  build: .
  environment:
    WILDFLY_PASS: adminadmin
  ports:
    - "8080:8080"
    - "9990:9990"
  links: 
    - postgresloml:postgres
  volumes:
   - "./.deployments:/opt/wildfly/standalone/deployments"

The docker-compose.yml file describes the PostgreSQL container with a custom database named ‘office-test’ (see the standalone.xml file), and a new imixs/ofifce-workflow container running our custom build of Imixs-Office-Workflow. The volumes parameter binds the local ./deployments/ folder which is used for autodeployments our application artifacts and also to configure hot-deployment during the development phase.

To start the environment simply run:

docker-compose up

That’s it! Now you can deploy your application aretfact of Imixs-Office-Workflow together with ah postgresql-jdbc.jar file into the local ./deploymetns folder.

After you access Imixs-Office-Workflow from your web browser (http://localhost:8080/office-test) the default user account ‘admin’ with the default password ‘adminadmin’ will be created and can be changed from the Admin section

 

Architecture Development

Docker-Compose – How To Install

The Imixs-Workflow project supports Docker and provides several Docker containers to run business applications like Imixs-Office-Workflow on a Docker host. A business application like Imixs-Office-Workflow requires to start different containers to separate the database form the application/web server. With the help of the Docker Tool ‘Docker-Compose’ the  definition of multi-container Docker applications is quite simple. The Imixs project provides different Docker-Compose definitions stored in a docker-compose.yml file.

The Installation

The following installation guide is written for linux users. For other plattforms see the installation guide here.

Fist download docker-compose sources from GitHub and change mod with the following command:

curl -L https://github.com/docker/compose/releases/download/1.7.0/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
 chmod +x /usr/local/bin/docker-compose

After installation you should verify the installation with the following command::

docker-compose --version

this should result in something like:

docker-compose version 1.7.0, build 0d7bf73

How to downgrade the docker-compose

Depending on you docker installation it can be result in a version conflict between Docker and Docker-Compose after a manual installation. You will see an errer message when starting docker-compose like the following:

client and server don't have same version (client : 1.18, server: 1.17)

In this case you can easily install a lower version of docker-compose with the curl command as shown above.

Run Docker-Compose

After you have installed Docker-Compose successfully you can start a multi-container Docker application with the following command:

docker-compose up

You can run the containers in background:

docker-compose up -d

to stop all containers run:

docker-compose stop

 

 

Architecture Development

BPMN Versioning

Running BPMN models in a BPM system often requires to take care about the internal version of a BPMN model. This occurs, for example, in scenarios where you run multiple instances of an active process in a live system with different versions of the same BPMN model.

The Imixs-Workflow Engine provides a nice mechanism to manage different versions of a BPMN 2.0 model. This allows to setup complex production environments with different models and different model versions at the same time. A model version, which is placed as an extension element of a BPMN 2.0 model can be evaluated by the Imixs-Workflow engine:
imixs-bpmn-versioning
read more »

Architecture Development

Microservice Architecture for Workflow Applications

With our new project Imixs-Microservice we now provide a solution to build workflow management applications based on a modern microservice architecture.

Imixs-Microservice encapsulates the Imixs-Workflow Engine into a microservice architecture. The service can be bound to any business application, independent from the technology behind. This allows business applications to change the business logic without changing a single line of code. Thus the state of a business object can be controlled through the workflow model.

Based on the comprehensive functionality of the Imixs-Workflow Engine the Imixs-Microservice is empowered to control business data in various ways. Imixs-Microservice can send E-Mail notifications, log business transactions and secures any kind of business data.

The Imixs-Workflow Modeller can set an ACL for each single state in a business process model. This allows the definition of highly complex business applications and waves a security layer around each process instance.

 

The Rest Service API

Imixs-Microservice provides a flexible REST Service API which can be accessed from any platform and any kind of application. The Web Service is based on JSON and XML objects and allows an easy integration in existing projects (Java, .Net, PHP, …). Once deployed a new Workflow Model can be defined using the Eclipse based Imixs-Workflow Modeller. Any business object can be bound to a new business process by posting a JSON or XML based process instance. The state is then controlled by the Imixs-Workflow engine and can be requested and updated in various ways.

Runns with Docker

DockerImixs-Microservice provides a docker image. This makes is easy to run Imixs-Microservice in a Docker container and provides a powerful way to integrate a full featured workflow engine into a microservice architecture. The Docker image can be used as a template for custom projects and provides a scaffold to start with a microservice achitecture.

 

Imixs-Workflow and Imixs-Microservice are Open Source projects and can simplify the development of business applications in various ways. The Imixs Software Solutions provides professional services and support for building enterprise workflow management solutions.

 

Architecture Development

Building transaction save business logic

As I posted in my last blog about JSF and Transactioncontext, it is importend to keep the transaction context in mind when developing a business application within JSF. When you use the Imixs-Workflow Engine you normaly don’t need to think about transactions because Imixs-Workflow takes care about processing a workitem in a full controlled transaction context. But developing with JSF can lead into situations where the business logic is not allways encapsulated correctly in a single transaction. Look at the following example of an Imixs-Workflow web application based on JSF:

//jsf bean...
@EJB WorkflowService workflowService;
...
public String process(ItemCollection workitem) {
 workitem=workflowService.process(workitem);
 // evaluate result and trigger another process step...
 if (workitem.getItemValueString('department').equals('finance')) {
    workitem.replaceItemValue('$activity',APPROVE_BY_MANAGEMENT);
    workitem=workflowService.process(workitem);
 }
 ....
}

In this example, the process method of the front-end controller evaluates the result of a process step and calls a second process for the same business object. Now you have the problem that the workflowService will run in two separate transactions. As I mentioned in my blog this can result into unexpected database results.

When you are working with Imixs-Workflow, the solution is quite simple: Just put your business logic into Imixs-Workflow Plugi-In. Plug-Ins are always controlled by the WorkflowManager and called inside a single transaction. So there is no risk that your business process runs in an undefined context.

Architecture Development

Imixs BPMN

Imixs Workflow is an open source project providing a powerful workflow engine to manage any kind of business process. The main objective of such a Workflow Engine is to control the states defined in the business process. The transmission from one state into another is defined by Activities. The typcial way to describe such a process flow is a state diagram. As the common standard the Business Process Modelling Notation – BPMN has been established in the last years.

BPMN Modelling

BPMN provides an easy way to describe a business process from the perspective of an user or a software system. In case of a human based workflow BPMN can also be used to describe the view from one or may users participating in such a process. In the following section we will demonstrate how to use BPMN to create a model for the Imixs-Workflow.

First of all you need to remember that one of the most important tasks of a workflow engine is to control the state of a business process. This means that a process instance can always be defined by its state. So the first step using BPMN is to model the states of a business workflow.

In BPMN there are only two predefined states known. The Start Event and the End Event. They are describing the begin and the end of a business process:

bpmn-modelling-example1

Each state between the Start and the End event can be described with the BPMN Task element. A Task describes not only the state of the process but also the general task which need to be performed in a specific situation. So we can extend the model by defining additional BPMN tasks to describe our states the process can take:

bpmn-modelling-example2

This example describes the states of a simple Ticket Workflow. The different states a Ticket can have are

  • Open a new Ticket
  • Processing Ticket
  • Solving the Ticket

Defining Events and Transitions

What we have done so far is an important step in describing a workflow model with BPMN. We defined all the tasks a business process can take and which can be identified by the workflow system to control the status of the process. Now we extend this model by adding new elements.

A business process typically defines activities which can be performed on a specific process instance. Each task depends on a state and defines a transition from one state into another. This is the workflow logic we need to design a complex business process. Using BPMN we can model this by using Gateways and Event Elements. A Gateway is used to define on ore many transistions from one state into another. A Event Element is used to describe the activity which can be performed by an actor during the workflow.  Lets see the next example:

bpmn-modelling-example3

Here we extended our simple state diagram with Gateway and Event elements to describe the activities in our ticket workflow.

If new ticket was created we defined the State ‘Open Ticket’. From this state we defined the events ‘accept’ or ‘close’ which can be triggered by the actor creating the ticket. When the event ‘accept’ is performed the state of the Ticket changes in ‘Processing Ticket’. Again we define a Gateway with now two possible transitions. When the event ‘solve’ is triggered by the actor the business process ends in the state ‘Solved’. If the event ‘reopen’ is performed we go back to the first state ‘Open Ticket’ to repeat the Workflow.

What you have seen here is a simple business process. We use the BPMN to describe the different states a process instance can have and also the Events which can be performed by an actor to process a ticket. A workflow system like the Imixs Workflow Engine can control the status of a process instance in the business model. Also the events triggered in this model can now be controlled by the workflow engine to change the states.

The Imixs Workflow System

The Imixs Wokflow provides a rich set of functions to control a business process and define the state of a process instance. In each change of a state triggered by an activity (task) Imixs Workflow updates a lot of properties of each singe instance. For example:

  • Read- and write-access to a process instance
  • Process documentation and process history
  • Ownership of a process instance
  • E-Mail notification to the next participant
  • Business-Rules to perform complex business logic
  • Versions of a process instance
  • Scheduled Events triggered by a timer
  • Summary and detail description of an instance
  • Form elements for a user frontend

These technical descriptions can be added into a workflow model and also in a BPMN model using the BPMN Version 2.0.

Read more about the Imixs Workflow technology at: