Wednesday, August 31, 2016

Using the Activiti 6 Angular app

The Activiti 6 Angular app has been updated with a number of new features in Beta3. This article shows a number of these new features and will guide you in creating an app definition that can be deployed on the Activiti Engine.

Start with downloading the Beta3 distribution from the Activiti download page. In the wars folder you can find the activiti-app.war that can be deployed on a Tomcat server or another servlet container of your choice. By default it will run with an in-memory H2 database. If you want to use a different database you can change the configuration in the WEB-INF/classes/META-INF/activiti-app/activiti-app.properties file, like the following example for MySQL:

datasource.driver=com.mysql.jdbc.Driver
datasource.url=jdbc:mysql://127.0.0.1:3306/activiti6ui?characterEncoding=UTF-8
datasource.username=mysql
datasource.password=test

hibernate.dialect=org.hibernate.dialect.MySQLDialect

Don't forget to change the Hibernate dialect as well and of course add the necessary database driver JAR to the WEB-INF/lib folder.

When the Activiti app has been booted you can see that the Activiti Engine is also included in the Activiti app and will create the Activiti database tables when not present. In addition, also the new Activiti DMN and Form Engine are booted and both engines will also create their database tables when needed (using Liquibase).

Now you can open your web browser and point it to http://localhost:8080/activiti-app and a login screen will be presented. The default user is admin with password test. The dashboard view is now presented:


The Kickstart App can be used to model processes, forms, decision tables and app definitions. The Task app is a general Activiti Engine app that shows all tasks and processes deployed on the Engine. The Identity management component allows you to edit your profile and if you have admin rights (like the default admin user), to create new users and groups.

Let's start with modeling a simple process in the BPMN editor by opening the Kickstart App and create a process in the process tab. In the popup a model name and key have to be filled-in. The model key will be used as the process identifier / logical key.


For this example process we will model a very simple order process, starting with a order start form. When you select the start event on the canvas there's a referenced form property you can click on. This will open a popup where all created forms are available. But you can also click on the new form button to create a new form. Again a form name and form key needs to be filled-in, and the form key will be used as the logical key to lookup the form in the form engine. The form key also has to be unique for every new form you create. When you would use the same form key twice the form engine will think it's the same form and will deploy it as a new version of the previous form with the same form key.


The form editor is opened and you can start dragging form fields on the canvas. Let's add a product name text field and an amount number field to the canvas. 


Click the save button and choose the save and close editor button to go back to the BPMN editor. The order start form is now connected to the start event of the order process. The next step in the process is to execute a decision table to decide on what needs to happen with the new order. In the activities palette group, a decision task can be dragged onto the canvas and connect it to the start event.


The decision task is a new type of service task in the Activiti Engine, which will invoke a decision table deployed on the DMN engine. Similar to attaching a form to the start event, you can select the decision table reference property after selecting the decision task on the canvas. The decision table key needs to be a unique logical key as it will be used as an unique identifier when deploying the decision table on the DMN engine.


Let's create a decision table that checks on a product name and an amount combination, and will return a reviewNeeded boolean variable. Select the first input header and fill-in productname for the variable field. Add another input, and fill-in amount for this variable field. For the output field you can fill-in the reviewNeeded variable name and select the boolean variable type. To fill-in an input or output value in the decision table, you have to double-click on the specific cell. The resulting decision table should look similar to the following screenshot:


We can now use the reviewNeeded variable in the next steps of the process. Let's save and close the decision table editor and add an exclusive gateway as the next step in the order process. Complete the order process like shown in this order process screenshot:


The sequence flow to the review task should have the following flow condition:

${reviewNeeded}

And the other sequence flow to the closing exclusive gateway can be the negative of this flow condition like:

${!reviewNeeded}

For the review task, let's add a very simple review form with an expression field. An expression field can be used to included process variables in a label text on a form. Let's fill it with the following expression:



Now the process design, together with forms and decision table is completed and we can use an app definition to deploy this as a bundle to the Activiti Engine. An app definition also needs a unique logical key and it will be persisted in the key property of the Activiti deployment. Let's create the following order app definition and included the order process model.


When clicking the save button, you can select the publish checkbox, which will deploy the process, forms and decision table to the Activiti Engine in a regular deployment. By default, the Activiti Engine will ignore the form (with extension .form) and decision table (with extension .dmn) files. But when the Activiti DMN and/or the Activiti Form Engine has been enabled for the Activiti Engine this changes. The DMN and Form engine can be enabled using a configurator, and can be configured in an activiti.cfg.xml file or in Java like this:

FormEngineConfiguration formEngineConfiguration = new FormEngineConfiguration();
formEngineConfiguration.setDataSource(dataSource);
    
FormEngineConfigurator formEngineConfigurator = new FormEngineConfigurator();
formEngineConfigurator.setFormEngineConfiguration(formEngineConfiguration);
processEngineConfiguration.addConfigurator(formEngineConfigurator);
    
DmnEngineConfiguration dmnEngineConfiguration = new DmnEngineConfiguration();
dmnEngineConfiguration.setDataSource(dataSource);
      
DmnEngineConfigurator dmnEngineConfigurator = new DmnEngineConfigurator();
dmnEngineConfigurator.setDmnEngineConfiguration(dmnEngineConfiguration);
processEngineConfiguration.addConfigurator(dmnEngineConfigurator);

The Form Engine configurator is included in the activiti-form-engine-configurator module and the DMN Engine configurator in activiti-dmn-engine-configurator. When the Form Engine configurator is added every .form file in a deployment will be processed on the Activiti Form Engine and deployed as a new form or a new form version. The same is true for the DMN Engine configurator with .dmn files.

In the Activiti app, the DMN and Form Engine are included by default, so the deployment with the .form and .dmn files will also be processed by the Form and DMN Engine and results in two deployed forms and one deployed decision table. 

These configurators also expose 2 new services each in the Activiti Engine. The Form Engine exposes the FormEngineRepositoryService and FormEngineFormService service interfaces and the DMN Engine exposes the DmnEngineRepositoryService and DmnEngineRuleService service interfaces. These services can be used to retrieve a form definition or submit a completed form to the Form Engine for example. Or execute a decision table in the DMN Engine.

By using the configurator approach we tried to decouple the DMN and Form Engine as much as possible from the Activiti Engine. If you don't want to use it then there are only two required dependencies with a few classes, activiti-form-api and activiti-dmn-api, to expose the service interfaces to the Activiti Engine. 

But coming back to the publish action when saving the app definition. This will deploy the BPMN process on the Activiti Engine, the forms on the Activiti Form Engine, and the DMN decision table on the Activiti DMN Engine. When we go back to the dashboard by clicking on the Activiti logo in the top left of the screen, we can see a new app has appeared.

In the app, you can create new standalone tasks and start new order process instances. Let's start a new process instance and fill-in the start form.


The start form is retrieved form the Form Engine using the logical key we've chosen. After clicking the start process button the decision task will be executed and with this example input we would expect the reviewNeeded variable to be set to true and a review task to be created. 

This concludes the introduction to the new Activiti 6 Angular app included in the Beta3 release. With the introduction of the Form Engine and the DMN Engine things have changed quite a bit since Beta2. But we need only a few additional tables now and the components are modularized and made optional. Let us know what you think about these changes, any feedback is valuable to get this app ready for the first Activiti 6 release.

25 comments:

  1. It won't let me log in. admin/test does not work as credentials.

    ReplyDelete
    Replies
    1. That are the correct credentials. Do you see an error message in the server log?

      Delete
  2. Thanks a lot for this new version and this simple process to go through new features. I have couple of questions:
    - Will it be possible to download form definition file directly from UI in final product (just like it is for dmn files today)?
    - Is it expected from decision table's designer to cover all combinations there or could decision table UI validate completeness, or easier probably ask for a row with rule for all other combinations not explicitly listed above. Currently you get an error if you try to input values that are not handled by decision table.
    - Is Drools used as DMN Engine?
    - Do you have plans of adding BPMN 2.0 validation in editor before releasing production ready version?

    ReplyDelete
    Replies
    1. - Yes it should be possible to download the form definition file directly from the UI in the final version.
      - There are definitely improvements possible to make the decision table designer more user friendly. This is something that needs to evolve and improve over time.
      - No the DMN Engine is part of the Activiti project https://github.com/Activiti/Activiti/tree/activiti6/modules/activiti-dmn-engine
      - Adding BPMN 2.0 validation is something we would definitely want, but it will probably be in one of the versions after 6.0

      Delete
    2. Thanks a lot for your answers. I have it now running locally and played a bit with new features. DMN engine and Decision Task extension seem very promising. I have raised a few bugs today for Decision Table editor as it turns quite tricky to play with bigger rule sets, starting with 10+ already. I wanted to run some performance tests with rule sets of 5000, 20000 rows. Have you maybe run such tests and could share how efficient your dmn engine is? Thanks

      Delete
    3. Thanks for the testing and the issues and JIRA, we'll look into it. We didn't do these kind of performance tests yet. If you see a possibility for improvement please let us know.

      Delete
  3. this looks a great step forward, Looking to see the final version 6 .

    Any possible release dates?

    ReplyDelete
    Replies
    1. Like mentioned in the blog post for the release, the Engine is now considered feature complete and only needs testing and bug fixing. For the Activiti Angular app some work is left and we are adding an admin application as well that's already in github but wasn't ready to be released yet. The plan is to release a RC1 and then do the final release shortly after if there are no huge issues.

      Delete
  4. Hey over there, its really nice the new app, im nervous for get the code of the final version.

    I was playing with the tool and I think I found a bug, when I define the decision table, I created the app, later when I was looking at the variable name of the decision tables I have typped productName, so the upper case make my variable name diferent. I have clicked over the name for change it and the app just do nothing, i couldt change the variable name, so i have to drop that input and create a newOne.


    Here is a question, when I open the app, im gettin a error message that just say "Sorry an error ocurred" how I can know in what step I do the things Wrong?

    ReplyDelete
    Replies
    1. Thanks, yes that's a bug, we'll fix it asap.
      Did you look in your browser debugger console if there's a javascript error or a failing network request?

      Delete
  5. An her is other question: After create a task in the app, can i delete it?

    Because I can delete the task I have created.

    Thanks, best regards from Mexico

    ReplyDelete
    Replies
    1. Right now you can only complete it. But would be good to add a delete button as well indeed.

      Delete
  6. Hello, could you tell me please wich is the main class for run the project activiti app?, because im triying to run the project and Im getting this error:

    ReferenceError: angular is not defined
    at Object. (C:\Users\asuarezr\Desktop\Activiti-activiti-6.0.0.Beta4\modules\activiti-ui\activiti-app\src\main\webapp\scripts\landing-app.js:15:19)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Function.Module.runMain (module.js:441:10)
    at startup (node.js:139:18)
    at node.js:974:3

    Thank you !!!

    ReplyDelete
    Replies
    1. I'm not sure what you mean with "Main class". With the beta4 release we provide an activiti-app.war file that should work fine. Can you provide a bit more details about what you are trying to do?

      Delete
    2. Yes of course, well first of all, thanks for your answer, Im triying to contruct all the project from the sources, I already made a maven install and comile the entire project without problems, but now I'm triying to run activiti app, and I can't i dont undertand how to create the war, to run angular app, any sugestiĆ³n?

      Delete
  7. I got an exception related to the decision table. Here's an excerpt:
    Caused by: [Error: illegal use of operator: <=]
    [Near : {... <= 1 ....}]
    ^
    In the second column of the table I had entered the text "<= 1", without the quotes. Removing the whole second column and simplifying the decision only using column 1 works. Any clues?

    ReplyDelete
    Replies
    1. Hi, could you sent the whole stack trace? Did you get the exception while running the decision table on the rule engine?

      Delete
    2. Hi, I got the exception after starting the process and then going through its steps as a user, up to the point where the decision tree is used. I cannot paste the whole stack trace because this blog does not accept entries bigger than 4096 characters. So, I will add a little piece.
      01:33:18,287 [http-nio-8080-exec-3] ERROR org.activiti.dmn.engine.impl.RuleEngineExecutorImpl - decision table execution failed
      org.activiti.dmn.engine.ActivitiDmnExpressionException: error while executing output entry
      at org.activiti.dmn.engine.impl.mvel.MvelExpressionExecutor.executeOutputExpression(MvelExpressionExecutor.java:91)
      at org.activiti.dmn.engine.impl.RuleEngineExecutorImpl.composeOutputEntryResult(RuleEngineExecutorImpl.java:244)
      at org.activiti.dmn.engine.impl.RuleEngineExecutorImpl.executeOutputEntryAction(RuleEngineExecutorImpl.java:228)
      at org.activiti.dmn.engine.impl.RuleEngineExecutorImpl.executeRule(RuleEngineExecutorImpl.java:205)
      at org.activiti.dmn.engine.impl.RuleEngineExecutorImpl.evaluateDecisionTable(RuleEngineExecutorImpl.java:108)
      ...
      at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
      at java.lang.Thread.run(Thread.java:745)
      Caused by: [Error: illegal use of operator: <=]
      [Near : {... <= 1 ....}]
      ^
      [Line: 1, Column: 1]
      at org.mvel2.ast.OperatorNode.getReducedValueAccelerated(OperatorNode.java:51)
      at org.mvel2.MVELRuntime.execute(MVELRuntime.java:85)

      Delete
  8. This is really amazing. I am using 6.0.0.Beta4 and am happy with what I see. I am reading the book Activiti in Action (2012) and am translating as I go along to the latest version. I have been looking for a good BPM solution in the open source world for some time now.

    How could I get involved to help this along?

    ReplyDelete
    Replies
    1. Thanks Kent. I have moved to Flowable (http://flowable.org) where we forked the Activiti project. We are releasing a 6.0.0 RC1 shortly there with more good things (evolution of 6.0.0.Beta4). If you would like to get involved in Flowable, a good place to get started is the forum (http://forum.flowable.org), and the github page (https://github.com/flowable/flowable-engine). Plenty of stuff to do in Flowable ;-).

      Best regards,

      Tijs

      Delete
  9. This fork news is interesting. Regarding getting involved, I checked the wiki and the Github Project view and didn't see anything major there. Is there some place else I should check for the roadmap?

    ReplyDelete
  10. hi, do you have any recommendations for team working.
    i'm interested to develop processes and forms with activiti app but i don't know the best way to do it with a team, and also... to keep the proceses and forms under version control like GIT. Any recomendation? how to o more people can work in the same process?

    ReplyDelete
    Replies
    1. Hi Joel, we are thinking of providing a GIT storage option for models as well, but that will need some development time. A possible approach now would be to work with a model server that the team can access, so that's the "source of truth" for the models. When a model has a certain maturity and you want to do testing with it you could store the bpmn xml and form json or the full app zip file in git as well.

      Delete
  11. Are you planning to release a new version of Activiti 6? Beta 5 or Production?
    How can I contribute to the project (test, translation, documentation / help manual)?
    In beta 4 I found some bugs, what is the best place to report them?

    ReplyDelete
    Replies
    1. Hi Robson, like I mentioned to Kent I've moved to the Flowable project (http://flowable.org) where we forked the Activiti project. We released a Flowable 6 RC 1 that contains a lot of improvements already, and you can always contribute to the project by getting involved in the forum discussions on http://forum.flowable.org/ and by raising issues on https://github.com/flowable/flowable-engine/issues

      Best regards,

      Delete