Camunda Team Blog

camunda BPM: Power to Embedded Taskforms

Written by Nico Rehwaldt on , under Execution category.
For everyone out there using embedded task forms in the camunda tasklist there is great news:
The forms are getting way more powerful.

The upcoming alpha of camunda 7.1 introduces two extensions for embedded task forms: Client side form validation and form extensions via JavaScript.

Form Validation

Validation directives provided by AngularJS may now be attached to form fields to activate simple client-side validation constraints for them.

The following form field will only accept one of the strings demo, john, mary or peter due to the defined pattern:

<input form-field type="string" name="assignee" ng-pattern="/^(demo|john|mary|peter)$/" />

If a user enters an invalid value in a form field the field will be marked as invalid. Additionally the complete task button will be disabled and the form may not be submitted.

An invalid form
The validation state of both the form as well as single form fields may be queried through the variable variablesForm that represents the form inside the scope of an embedded task form.

The following snipped is a valid form markup that renders the message Your form contains errors!
when the form itself is invalid. In addition, it renders a red Not a valid user! message to the user for specific validation problems of the assignee form field:

<p ng-if="variablesForm.$invalid">
  Your form contains errors!
</p>
<p ng-if="variablesForm.assignee.$invalid" style="color: red">
  Not a valid user!
</p>

JavaScript Form Extensions

More complex validations may be performed using form script - JavaScript embedded into task forms. form script is injected into the task form context via a special <script form-script type="text/form-script" /> tag:

<input form-field type="string" name="approver" ng-change="approverChanged()" />

<script form-script type="text/form-script">
  $scope.approverChanged = function(e) {
    var formField = $scope.variablesForm.assignee, 
        value = formField.$modelValue;
        allowedNames = ['demo', 'john', 'mary', 'peter'];

    // value must be contained in allowed names
    if (allowedNames.indexOf(value) == -1) {
      value.$setValidity('validAssignee', false);
    } else {
      value.$setValidity('validAssignee', true);
    }
  };
</script>

The above form script performs the same validation as the ng-pattern directive but via JavaScript. To do that it registers a change listener on the form input that is attached to the forms $scope inside the form script.

For even more elaborated use cases application services such as $http may be injected into the form script. using the inject callback. Given the $http service backend validation may be performed for a form or its attributes: 

<script form-script type="text/form-script">

  inject([ '$scope', '$http', function($scope, $http) {

    $scope.approverChanged = function(e) {
      var formField = $scope.variablesForm.assignee, 
          value = formField.$modelValue;

      $http.get("...?assignee=" + value).success(function(data) {
        if (data == "ok") {
          value.$setValidity('validAssignee', true);
        } else {
          value.$setValidity('validAssignee', false);
        }
      });
    };
  }]);
</script>
Find all of this including an improved documentation of embedded task forms in the next camunda BPM alpha release.

Power to the forms!