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.

Advertisements

25 pensaments sobre “Embedding process forms on your applications (I)

  1. Hi

    Thanks for this great library, It is really a big need, but how can I use it?
    Is it enabled in jbpm 6.1 master branch, for test?

    Thanks again

    • Hi greenday777,

      at the moment this library is still on development, I hope that it will be merged to the master branch soon.

      The main idea is to give an easy solution to embed forms, just adding the js library on your app, create a instance of the class defined on the library and start to work with it. You can take a look at this example to start.

      At the moment I’m working on a example app to show how it works, If I don’t have any problem I’ll be finished this week and I’ll write a post sharing the code and explaining a little bit more how to use it.

  2. Hi,
    I’m working on a similar idea implemented by the new rest service “showTaskForm” but with jbpm 6.0.1. Would you mind to share some thoughts about the implementation? At this moment I’m having problems trying to get the form file.
    Thanks!

    • This can be done but it can be a bit difficult, can you share with me what are you doing now? If I see what are you doing I could help you better.

      Regards,

      Pere

      • Hi, this is my walkthrough to get formtask with the API available in JBPM 6.0.1.
        1.- Use Rest API to get the task id.
        2.- I make a Rest Service class and inject the FormProviderServiceImpl to get the Form Context with the task id.
        3.- With the Form Context obtained in the before step and using the servlet “Controller” I get the HTML form to response and render the form.

        If you have some suggestion I will be very grateful the receipt.

        Regards,

        nbaker

  3. Hi,
    I m just trying to use the rest api for showtask form. Seems the JaxbTaskFormResponse is not available yet in Git?

    • Hi, at the moment this is still under development. It will be merged to the master branch soon. I’ll try to post a running example about it on sunday with a war containing the rest end point to enable to test it.
      I’m sorry for the delay writing the new post, I have a lot of work and I can’t find time to do it.

  4. Great. Yeah I understand. Tou gave a very good example. But we got struck in the JaxbTaskFormResponse which is not there. Thanks for putting this. Looking forward for your updated example soon. Thanks.

  5. Hello, When I run your example I get authentication error. I see there is no authorization in jbpm-forms-rest-integration.js. So how is this run?

      • I have a problem with your library
        in my gwt web application I try to run your functions (showProcessForm()) in this way

        function showProcessForm() {
        var onsuccessCallback = function(response) {
        document.getElementById(“showformButton”).style.display = “none”;
        document.getElementById(“startprocessButton”).style.display = “block”;
        }

        var onerrorCallback = function(errorMessage) {
        alert(“Unable to load the form, something wrong happened: ” + errorMessage);
        formsAPI.clearContainer(“myform”);
        }
        formsAPI.showStartProcessForm(“http://localhost:8080/kie-wb/”, “org.jbpm:HR:1.0”, “hiring”, “myform”, onsuccessCallback, onerrorCallback);
        }

        but when I run my project I receive this message from server

        Unable to load the form, something wrong happened: JBoss Web/7.0.13.Final – Error report HTTP Status 401 – Validation fails.type Status reportmessage Validation fails.description This request requires HTTP authentication (Validation fails.).JBoss Web/7.0.13.Final

        it seems that i must authenticate at first, “This request requires HTTP authentication (Validation fails.)”
        what is the best way to do that?

        thanks

      • Hi, have you configurated the jboss to use SSO?

        You should edit your standalone-full.xml and edit your virtual-server to look like:

        <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
        <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
        <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
        <sso/>
        </virtual-server>
        </subsystem>

  6. Hi,

    I have a separate web application that runs on a Tomcat server that uses Remote REST API to connect to jBPM, which is running on JBoss AS 7, to retrieve task, etc.

    I need to embed the task forms on my web application and so far, after adapting your examples, no task forms were rendered on my application.

    This cross server implementation is necessary due to client’s requirement.

    I’d like to ask if what I’m doing is possible or do my application need to be also residing on the same server as jBPM.

    I’m running jBPM 6.1.0 CR1.

    Thank you.

    • Hi,

      if you want to embed forms or execute any REST request to a Kie-workbench from a remote application you should provide a SSO mechanism between the two apps. The easiest solution is deploying both apps on the same application server and make the client app use the container authentication, but it seems that this is what your client wants :S

      I’m really sorry to say that I’m not an expert on SSO policies and I cannot give you any advice on how to do that.

      If you find the solution please let me know, I’ll be happy to test it.

  7. 16 maig 2014 at 18:00

    Hi,
    I m just trying to use the rest api for startform. and the resulte “500 (Internal Server Error)” what is this pronlem

Deixa un comentari

Fill in your details below or click an icon to log in:

WordPress.com Logo

Esteu comentant fent servir el compte WordPress.com. Log Out / Canvia )

Twitter picture

Esteu comentant fent servir el compte Twitter. Log Out / Canvia )

Facebook photo

Esteu comentant fent servir el compte Facebook. Log Out / Canvia )

Google+ photo

Esteu comentant fent servir el compte Google+. Log Out / Canvia )

Connecting to %s