Overcome the Biggest Barriers to Digital Transformation

Discover 3 factors you can’t ignore that drive change in businesses
Icon Close DOWNLOAD EBOOK

{ json : everywhere } – How to use json in a process

Since Camunda BPM platform 7.2 it is very easy to read, write and manipulate json objects by using Camunda Spin. Among other things, this feature is used to serialize Java objects inside a process instance in the process engine.

But what if you want to use Json Variables without mapping to Java objects? With the next alpha release we will introduce a new ValueType “json” (and “xml” but that is an other story).

In this post I demonstrate how you can use the json value type to

  • implement HTML Forms which work with a Json Variable,
  • implement BPMN Sequence Flow conditions based on the properties of the Json Variable.

Example Process

In this post I use the following example process:


Create a Json variable in a start form

The process instance is started by using a plain Html form inside camunda Tasklist.

<form role="form" class="form-horizontal">
  <script cam-script type="text/form-script">

    var customer = $scope.customer = {};

    camForm.on('form-loaded', function () {
      // declare a 'json' variable 'customer'
      camForm.variableManager.createVariable({
        name: 'customer',
        type: 'json',
        value: customer
      });
    });

  </script>
  <div class="control-group">
    <label class="control-label" for="firstName">First Name</label>
    <div class="controls">
      <input id="firstName" class="form-control"
               type="text" ng-model="customer.firstName" required />
    </div>
  </div>

  <!-- Additional fields omitted -->

</form>

The custom java script creates a new object and binds it to the angular $scope of the form as a variable named customer. Then a new process variable named customer will be created when the form has been loaded successfully. The type of the process variable is set to json, so that the variable will be persisted simply as json without the need to deserialize it to a custom Java object.

The form itself is a plain angular form (see ng-model binding of input field).

Accessing an existing Json variable in a task form

An existing json variable can be accessed using custom java script. The pattern is to fetch first the value of the variable and then bind it to an angular scope variable:

<form role="form" class="form-horizontal">
  <script cam-script type="text/form-script">

    camForm.on('form-loaded', function () {
      // tell the form SDK to fetch the json variable name 'customer'
      camFom.variableManager.fetchVariable('customer');
    });

    camForm.on('variable-fetched', function () {
      // work with the variable (bind it to current angular $scope)
      $scope.customer = camForm.variableManager.variableValue('customer');
    });

  </script>
  <div class="control-group">
    <label class="control-label" for="firstName">First Name</label>
    <div class="controls">
      <input id="firstName" class="form-control"
             type="text" ng-model="customer.firstName" required />
    </div>
  </div>

  <!-- Additional fields omitted -->

</form>

Accessing an existing json variable in an expressions

In the past you could already store Json as variable values. However, you needed to store it as a String variable. The problem with that is that in a sequence flow you cannot easily write EL Expressions using the properties of the json if it is stored as a String.

In Camunda 7.2 we introduced Spin and it became possible to pare the String within El and use the Spin API for formulating conditions:

${ JSON(customer).prop("age").numberValue() >= 21}

While this was a huge improvement the problem is that if you need to interpret the same variable as Json multiple times within a command, it needs to be parsed multiple times (among other downsides).
Now that we introduce Json variables as native ValueTypes, you can directly access the properties of a Json variable in conditions:

<sequenceFlow id="SequenceFlow_4" name="age above 21"
    sourceRef="ExclusiveGateway_1" targetRef="UserTask_2">
  <conditionExpression xsi:type="tFormalExpression">
    <![CDATA[
      ${ customer.prop("age").numberValue() >= 21 }
    ]]>
  </conditionExpression>
</sequenceFlow>

<sequenceFlow id="SequenceFlow_5" name="age under 21"
    sourceRef="ExclusiveGateway_1" targetRef="UserTask_3">
  <conditionExpression xsi:type="tFormalExpression">
    <![CDATA[
      ${ customer.prop("age").numberValue() < 21 }
    ]]>
  </conditionExpression>
</sequenceFlow>

The example resources can be found here.

  • Drafting Your Camunda Cloud Architecture – Part...

    When automating processes you typically integrate systems and services, or in other words you orchestrate various APIs. In order to achieve this you not only have different technical possibilities, but also can choose between various modeling possibilities in BPMN. This post will give you an overview and advice on how to decide between alternatives.

    Read more
  • What You Should Know About Using Camunda...

    Camunda Platform Run, or Camunda Run for short, is a lightweight distribution of Camunda Platform that works straight out-of-the-box and comes pre-configured for production environments. Camunda Run is an excellent option if you’re just getting started with Camunda, or if you’re ready to use Camunda Platform in production. You can download the open-source Community Edition for free, and easily upgrade to the Enterprise Edition to access more features and support options. After you download and extract Camunda Run, you’ll find a configuration folder that contains a file called production.yml. The properties defined in this file are important for production environments and are derived from our guide to securing your Camunda Platform installation. To start Camunda Run with the production.yml configuration,...

    Read more
  • Drafting Your Camunda Cloud Architecture – Part...

    Have you started your first project using process automation as a service with Camunda Cloud? One of your first tasks would be to sketch the basic architecture of your solution, and this blog post will guide you through some important early questions such as how to connect the workflow engine with your application or with remote systems? Or what’s a job worker, what should it do, and how many do you need? This post is the first piece of a series of upcoming blog posts: Part 1: Connecting Camunda Cloud With Your World (this post) Part 2: Service Interaction Patterns with BPMN and Camunda Cloud (coming soon) Part 3: Writing Good Job Worker Code For Camunda Cloud (coming soon) Connecting...

    Read more