how to deploy processes in jBPM 6?

After release of 6.0 of jBPM, there were number of questions coming from community about how processes can be deployed into the new and shiny jbpm console?

So let's start with short recap on how the deployment model look like in jBPM 6. In version 5.x processes were stored in so called packages produced by Guvnor and next downloaded by jbpm console for execution using KnowledgeAgent. Alternatively one could drop their process files (bpmn2 files) into a predefined directory that was scanned on the jbpm console start. That was it.

That enforces users to always use Guvnor when dynamic deployment was needed. Although there is nothing wrong with it, actually that was recommended approach but not everyone was happy with that setup.

Version 6, on the other hand moves away from proprietary packages in favor of, well known and mature, Apache Maven based packaging - known as knowledge archives - kjar. What does that mean? First of all, processes, rules etc (aka business assets) are now part of a simple jar file built and managed by Maven. Along the business assets, java classes and other file types are stored in the jar file too. Moreover, as any other maven artifact, kjar can have defined dependencies on other artifacts including other kjars.
What makes the kjar special when compared with regular jars? It is a single descriptor file kept inside META-INF directory of the kjar - kmodule.xml. That descriptor allows to define:

  • knowledge bases and their properties
  • knowledge sessions and their properties
  • work item handlers
  • event listeners
By default, this descriptor is empty (just kmodule root element) and is considered as marker file. Whenever a runtime component (such as jbpm console) is about to process kjar it looks up kmodule.xml to build its runtime representation. See documentation for more details about kmodule.xml and kjars.

Alright, now we know bit more about what is actually placed on runtime environment - kjar. So how we can deploy kjar into running jbpm console? There are several ways:

Design and build your kjar inside jbpm console

The easiest way is to actually use jbpm console to completely build the kjar. For that purpose there is entire perspective available - Authoring perspective - that consist of quite big set of editors tailored for various asset types.

First, you have to have repository created where your projects (after they are built they become kjars) will be stored. When running the demo setup of jbpm console (installed by jbpm installer), you will have two repositories already available - jbpm-playground and uf-playground. You can use any of these or create new repository.
Once you have repository available, create new item - a project - you need to specify GAV (GroupId, ArtifactId, Version) to name your project.
Next you create business assets in it, like business processes, rules, data model, forms, etc. And now we are at the stage where we should build and deploy our project into runtime. Nothing simpler than that - just press "Build & Deploy" button and you're ready to rock!

Is that really that simple?! In most of the cases, yes, it is really that simple. But you need to be aware of several rules (convention over configuration) that drive the build and deploy. First rule is that everything needs to be properly designed - processes, rules, etc - that is the build phase that catches any compilation or validation errors and provides feedback to the user via Problems Panel.
Assuming, all assets are built successfully, the deploy phase comes into the picture. Deploy phase is actually a two step process:
  • Maven phase - 
    • it installs build project (now it's kjar already) into Maven local repository (usually ~/.m2/repository but it can be configured with standard maven way - settings.xml)
    • deploys built project into jbpm console embedded Maven repository - it's a remote repository accessible over http and can be declared in pom.xml, settings.xml as any other maven repository
  • Runtime phase
    • once Maven phase is completed successfully, jbpm console will attempt to deploy the kjar into runtime environment for execution. Here are few requirements to make this happen:
      • kmodule.xml needs to be empty - which it is by default unless you edited it via Project Editor
      • kmodule.xml must have at least one knowledge base and stateful knowledge session defined and marked as default
When both phases are successfully completed, your kjar is deployed to runtime environment and ready for execution. Simply go to Process Management --> Process Definitions to examine what's there and start executing your just deployed processes.

So that's first and the easiest way to get started with deployments in jBPM 6.

Build project in IDE and push to console for build and deploy

Another approach would be when you prefer to do the heavy work in your IDE like Eclipse (since the modeling capabilities - bpmn2 modeler - is only available in Eclipse).  So you do pretty much similar steps, although no need to create repository here but clone an existing one from jbpm console instead.  So you first start with cloning of an existing repository. 

git clone ssh://{jbpmconsole-host}:{port}/{repository-name}

Then create Maven project - you can actually do that with jBPM Project wizard in eclipse, that creates simple Maven project with sample business process and executable class in it to get you started much faster. 

Note: make sure you place the project in the cloned repository structure so it can be later on pushed back.

It declares dependencies to jbpm-test module to be able to execute the sample process.
Once you have a mavenized project, you're ready to start working on your business assets, data model and more. 
When done, you're ready to push your project into jbpm console so it can be built and deployed to runtime environment. To do so, you need to use any GIT tool that allows you to pull and push changes from your working copy into the master repository. To add all files in your working copy into commit index:

git add -A

then examine if you haven't added too much like the target folder, if so create or edit .gitignore file to exclude unneeded files. And commit:

git commit -m "my first jbpm project"

once committed, push it to origin

git push origin master

now go into jbpm console Authoring perspective, and you should see you project in the repository, it's ready to be build and deployed. Just follow same step from the first approach to build and deploy it. 
That was second approach to deploying business assets into jbpm console version 6. Somehow in between developers and business users. Might also be seen as collaboration way - where initially business users create high level processes, rules etc and then developers step in and add implementation details and some "glue code" to make it fully executable.

Build and deploy to Maven from IDE

This one focuses completely on developers and allows to actually do the work without being too much aware of jbpm console. So here developers build regular maven projects that include business assets, java classes, forms and then add the kmodule.xml to make the jar become kjar. Everything is done in IDE of developer choice. Same goes for version control system, it does not have to be git any more, in this case. That is because, jbpm console won't be used as source management tool for these projects but it will be used only for pure execution capabilities.

Once you're done with development, you simply build the project with maven (mvm clean install). That makes it directly available for any other components that would like to use it on your local machine. So if you're running jbpm console on your machine you can directly skip to section deployment (three paragraphs below ;))

When jbpm console is running on remote host, you have two ways to make it aware of your artifacts built externally:
  • deploy (using maven) your projects into jbpm console Maven repository - as this is like any other repository you can use maven deploy goal after you have defined that repository either in your pom.xml or settings.xml
  • make jbpm console maven installation aware of any external maven repositories it should consider while deploying kjars
The first one, deploy to maven repository, does not have anything special, it's as simple as defining the repository in settings.xml so it can be successfully contacted and the artifact can be stored when running mvm clean install deploy.
Then the second approach is again standard maven way. On the machine (and user) that jbpm console is running, you need to add your main maven repository into settings.xml so whenever jbpm console will attempt to deploy the kjar it will look up for it in your maven repository.

With all these steps, jbpm console is now capable of finding the kjars that are outside of it's local maven repository so it can download them when needed. You can now go to jbpm console Deploy --> Deployments perspective where you can add new deployment units manually.
It's as simple as providing GAV of the project you want to deploy and optionally knowledge base and knowledge session names if you defined more than what is there by default.
In addition to that, you can select runtime strategy that fits your requirements for that given kjar - chose one from Singleton, Per Request or Per Process instance.

That concludes deployment options available in jBPM version 6. It promotes well known standards defined by maven and allow various ways of integrating with the jbpm console functionality. You, as a user, are in the control how you work with the tooling where you can leverage it's full power to do everything over the web, integrate with GIT server, to do everything externally and use it only for execution.

Hope that puts some light on the way you can use jBPM 6 out of the box and empowers your day to day work. As usual, ending with the same sentence: all comments and ideas are more than welcome.


  1. Hi Maciej,

    I have a concern.

    In the current deployment model if there is a instance of the particular process is already running I cant able to deploy my changes.

    It is complaing failed to undeploy since there are running instances. Is that by design?

  2. yes, that is by design, it will pretect from removing deployments if there are running instances. When you made a change make sure you increase version number of the project and as best practice change name/id of these processes so they can be seen nicely on UI. They will work properly as they belong to different deployments but to show them clearly on process definition list best is to have unique names

  3. Can you help me understand this?

    once Maven phase is completed successfully, jbpm console will attempt to deploy the kjar into runtime environment for execution. Here are few requirements to make this happen:
    kmodule.xml needs to be empty - which it is by default unless you edited it via Project Editor
    kmodule.xml must have at least one knowledge base and stateful knowledge session defined and marked as default

    How can the kmodule.xml be "empty" AND "have at least one knowledge base and stateful knowledge session" defined and marked default?

    Any chance you can clarify?

  4. Anonymous9/7/15 05:55

    Referring to "Build and deploy to Maven from IDE" section, I'd like to deploy my artifact into jBPM using pure Maven, something like:

    mvn deploy -DaltDeploymentRepository=releases::default::http://localhost:8082/nexus/content/repositories/releases/

    How do I know the address of the jBPM maven repository?
    Alternatively, how do I instruct jBPM to use my Nexus private repository?
    Thank you very much
    Best regards


  5. that's standard maven settings, you define repository/servers in settings.xml of your maven installation

  6. Anonymous9/7/15 07:18

    Hi Maciej, thank you for your answer, but you answered the wrong question :)
    I found this post that answer my question, I share it here hoping it can help: https://developer.jboss.org/message/926635#926635

    To recap:
    1) define a server in settings.xml with id=guvnor-m2-repo,username=krisv,password=krisv
    2) from Eclipse IDE, create a new jBPM Maven project and develop the process
    3) deploy to jBPM using:
    mvn clean install deploy -DaltDeploymentRepository=guvnor-m2-repo::default::http://localhost:8080/jbpm-console/maven2/
    4) go to KIE workbench, Deploy -> Process Deployments -> Deploy a new unit (the artifact just deployed)

    Unfortunately, when I try the last thing, I get
    WARN [org.jbpm.kie.services.impl.KModuleDeploymentService] (default task-62) Unexpected error while deploying unit it.visura:test-bpm:1.0.0: java.lang.IllegalStateException: Cannot find kbase, either it does not exist or there are multiple default kbases in kmodule.xml

    Do you know how to get rid of this error?

    1. I actually did answer it just with very few details, on that thread you got it better explain so thanks for linking it here!

      For the error change you lmodule.xml in kjar/META-INF as most likely has more kbases defined or none that is marked as default. If that's the case simply use kbase name and ksession name from the kmodule.xml when deploying using "Deploy new unit" there is additional fields where you can specify kbase and ksession names.

  7. Hi Maciej,

    Your articles are very very helpful. I have been following them for my first jbpm project. I am facing some difficulties in loading the kjar.

    Here is my setup. I have an enterprise application using Spring. I have loaded the jbpm-services (deploymentService, processDefService etc) as described in spring-jbpm-app. I can see the JPA logs loading using the name "org.jbpm.domain".

    I have another maven-based jbpm project in eclipse, where I have written processes and built the kjar out of it and copied the kjar into src/main/resources/kjar directory of my enterprise application.

    But during server (Tomcat 7) I am not able to see any process compilation log, which is why I am concerned. I even tried adding a Spring bean with @PostConstruct method, where I try to read the kjar from classpath using KieServices and KieContainer and trying to use ClassPath kie container. But that seems to be not working as well.

    I do not want to use Maven in the enterprise application and just want to use kjar.

    Is my approach correct? Do I need to do something additional to this?

    Please guide me on this.

    1. When using jbpm services you need to rely on Maven - one way or another. Note that you don't need any installation but just file system directory where you store your kjars in maven like structure. It does not have to load anything from the outside (like maven central or so). Then you configure application to use maven in offline mode that will disable all network interaction and rely only on local repo.

  8. Hi Maciej. I have the following issue. Now when I deploy something to BPM central, I go to Authoring > Artifact Repository > Upload and then to Deploy > Process Deployment > Deploy.

    I want to do all those tasks using rest calls. In this documentation https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_BPM_Suite/6.3/pdf/Development_Guide/Red_Hat_JBoss_BPM_Suite-6.3-Development_Guide-en-US.pdf on "3.7. Uploading Artifacts to Maven Repository" they say how to create the call.

    Should be something like this:

    curl -X POST -H "Authorization: Basic XXXXXXX" -H "Cache-Control: no-cache" -H "Postman-Token: XXXXX" "http://XXXX:XXXX/business-central/maven2/AppGroup/AppName/AppVersion/AppName-Version.jar".

    I have enabled the rest-all user in order to do REST calls. But I think somethig else is missing. How the jar file should be uploaded? I have tried by uploading it in body of rest call (nothig).

    Also I have tried to put it on server side in /tmp folders from different levels (application/tmp, jboss/tmp, Linux/tmp). The result is the same: negativ.

    The client have the following message: The Web Server may be down, too busy, or experiencing other problems preventing it from responding to requests. You may wish to try again at a later time.

    The server logs have following message: java.lang.RuntimeException: Cannot find KieModule...


    1. looks like you need to find a way to upload files with curl (http://stackoverflow.com/questions/12667797/using-curl-to-upload-post-data-with-files) or what I would recommend is to use maven to do that for you - define properly repository in your maven config (both pom and settings.xml) to point to workbench as maven repo and then use mvn clean install deploy goals to upload your project to workbench maven repo.

  9. Nice blog. It inspires me a lot. Thanks for publishing such useful information.
    Herbal Incense

  10. This blog post contains very useful information. I am very glad that I found this blog. Keep on sharing such useful information in future.
    Herbal Incense

  11. I honestly love your blog. It was very useful and it inspired me a whole lot. Thanks for sharing
    Herbal Incense

  12. That's a very good blog, I'm glad to see Polish people rocking it in foreign language!
    To the point, I had a similar isssue with my company's software, Dynamics, provided by one of dynamics ax partners and I don't really know how to fix it without calling an IT specialist.

  13. This is such a detailed and informative article you wrote my friend.. good stuff

  14. Hi, I need some recommendation. I have deployed 2 version business central, and I want to hide older version instead of undeploy, how can I achieve that