Embedding process forms on your applications (I)

Since I started to work on the jBPM team many times I’ve been asked how to embed process/task forms on client applications. I’m happy to say that I’m working on this feature that will be released on the new 6.1 version. At the moment this is under development but I want to share with you the current state and get your comments about it. Let’s start!

Basically the I’m working in two parts:

• A REST endpoint that receives the information needed to obtain the form (deployment ID, process ID, task ID…). The endpoint will check that the information is correct and will generate an url that client app can use to show the form on a iframe.
• A Javascript library that can be added to the client application and will allow the client to interact with the rest end point in order to show the forms and also interact with the form that is being shown and execute callback functions after any task.

Let’s see the key functions:

• showStartProcessForm(hostUrl, deploymentId, processId, divId, onsuccess, onerror): This function will comunicate with the REST endpoint and will show the specified process form on a given div, the params nedded are:
  • hostURL: the server URL that provides the KIE Workbench
  • deploymentId: the GAV of the project that contains the process
  • processId: the process identifier
  • divId: the id of the div that will contain the form
  • onsuccess (optional): the callback function that will be executed after the form is embedded. This function will receive the server response as a parameter
  • onerror (optional): the callback function that will be executed if any error occurs loading the process form. This function will receive the server response as a parameter

  Look at this snippet to see a sample usage:

  var jbpmRestAPI = new jbpmRestAPI();
  jbpmRestAPI.showStartProcessForm('http://localhost:8080/kie-wb', 'org.jbpm:HR:1.0', 'hiring', 'mydiv', onsuccess, onerror);
  

• startProcess(divId, onsuccess, onerror): Once the process form is loaded you can use this function to submit the form and start the process with the form data. The parameters needed are:
  • divId: the id of the div that contains the form
  • onsuccess (optional): the callback function that will be executed after submit the form and start the process. This function will receive the server response as a parameter
  • onerror (optional): the callback function that will be executed if any error trying to start the process form. This function will receive the server response as a parameter

  Look at this snippet to see a sample usage:

  jbpmRestAPI.startProcess('mydiv', onsuccess, onerror);
  

• showTaskForm(hostUrl, taskId, divId, onsuccess, onerror);: This function will comunicate with the REST endpoint and will show the specified task form on a given div, the params nedded are:
  • hostURL: the server URL that provides the KIE Workbench
  • taskId: the task identifier
  • divId: the id of the div that will contain the form
  • onsuccess (optional): the callback function that will be executed after the form is embedded. This function will receive the server response as a parameter
  • onerror (optional): the callback function that will be executed if any error occurs loading the process form. This function will receive the server response as a parameter

  var jbpmRestAPI = new jbpmRestAPI();
  jbpmRestAPI.showTaskForm('http://localhost:8080/kie-wb', 1, 'mydiv', onsuccess, onerror);
  

When the task form is shown on the selected div you’ll be ready to work with it using the following functions:

• claimTask(divId, onsuccess, onerror): use this function to claim the task for the current user.
• startTask(divId, onsuccess, onerror): use this function to start the user task and reload the form on write mode.
• releaseTask(divId, onsuccess, onerror): use this function to release the current task.
• saveTask(divId, onsuccess, onerror): use this function to save the form data.
• completeTask(divId, onsuccess, onerror): use this function to complete the current task.

As the startProcess function, these functions use the same parameters to interact with the task form:

• divId: the id of the div that contains the form
• onsuccess (optional): the callback function that will be executed after the task is claimed.
• onerror (optional): the callback function that will be executed if any error occurs.

You can see  simple usage examples here and here.

On the following weeks I’ll be creating a sample application that will use that library to embedd and use forms, as soon as I have it I’ll write another post showing it and explaining the code.

Please leave your comments or doubts and I’ll be answering as soon as I can.