Friday, February 12, 2016

BPMN REST tasks with WSO2 BPS

WSO2 BPS supports invoking rest endpoints out of the box. Follow the following steps to add a RESTTask to your workflow using Activity BPMN 2.0 designer.

  1. Add the BPMN designer to your Eclipse installation using the update site here. 
  2. Start a new BPMN project.
  3. Add a new service task from the tasks palette.
  4. Go to the task properties panel and open main config tab.
  5. Select "Java class" as task type.
  6. Give "org.wso2.carbon.bpmn.extensions.rest.RESTTask" as the Class name.
  7. Now add fields with following names, and values in String value field, under documentation section.
    • serviceURL - rest service endpoint
    • method - http method to use
    • basicAuthUsername - username if the endpoints are secured
    • basicAuthPassword - password for the username above
    • input - payload to be sent
    • outputVariable - process variable to save the response
    • headers - header values in the format "key1:value1,key2:value2"
Now you can retrieve the response from the variable specified above in the succession steps of the workflow.

Refer the screenshot below to find out the important places you require inside eclipse designer.


Changing the endpoint after process deployment

The REST endpoint could not change after deploying the process in above method. If you want to change the endpoint after deploying the process also, pointing to a registry location which contains an endpoint reference as mentioned in Endpoint+References. For this add a field with name "serviceRef" instead of the "serviceURL" field and give the registry location of the service reference as the value.

Using json payloads

You can send json as the payload also.

Give the json payload to the input field. This time use the expression box in add field dialog to give the json value instead of string value box. Add new field called "outputMappings" and mention the mapping format from response json, similar to "var2:customer.name,var3:item.price" format.

EDIT on 14/05/2016

REST task sample

I have added a sample at BPMNRESTSample. This sample  make a REST call to a mocky.io endpoint and display the response in a user task. Deploy the sample in WSO2 BPS and start a new process instance from BPMN Explorer shipped with BPS.

Enjoy with REST!!



21 comments:


  1. Good morning , you can see a complete example ?

    ReplyDelete
    Replies

    1. if you can a simple example , with a video on youtube ?

      Delete
    2. I'll try to upload a sample soon.

      Delete
    3. I just added a simple sample.

      Delete
    4. Link please for example?
      I have great difficulty in using BPMN rest bees . I need to start a process

      Delete
    5. It's there in the post. Check the last section.

      Delete

  2. My question is another , after I deploy BPMN , I want to create a software application that through the use of rest api start BPMN deploy without having to access the BPMN - explorer

    ReplyDelete
  3. You can use the REST API provided with the BPS. Check in the doc in https://docs.wso2.com/display/BPS351/BPMN+REST+API.

    It's better if you could use the dev@wso2.org mail group for further queries. More people will see your questions and you will get quick answers.

    ReplyDelete
  4. Thank you for the post, i was struggling to search this kind of post for consuming rest services, However can you please tell me whether it is possible to call a SOAP web service as well, if yes could you please provide some documents on the same

    ReplyDelete
    Replies
    1. Hi Amit,
      I do not have such doc. Anyway, it is possible with BPS 3.6.0. Follow the instructions given in class comment of this source file [1] for the moment. It is much similar to invoking a rest endpoint.

      [1] -https://github.com/wso2/carbon-business-process/blob/master/components/bpmn/org.wso2.carbon.bpmn.extensions/src/main/java/org/wso2/carbon/bpmn/extensions/soap/SOAPTask.java

      Delete
  5. This comment has been removed by the author.

    ReplyDelete
  6. Hi Vinod ,

    Thank you for providing the Code, I build the code and the JAR file was placed under /components/plugins.

    I have created a SOAP process and have deployed in wso2 BPS 3.5.1

    However when i start the process i get the error "org.activiti.engine.ActivitiException: couldn't instantiate class org.wso2.carbon.bpmn.extensions.soap.SOAPTask"

    So i need to add the soap dependencies in any file.

    Could you please help me with this

    ReplyDelete
    Replies
    1. Hi Vinod ,

      I guess i had placed the JAR file at the wrong place, as this JAR file is not a part of wso2 bps 3.5.1, so it is a custom JAR file hence i placed the JAR file under /components/lib and now i am not getting the same error.

      However i am getting a different error now "org.activiti.engine.ActivitiIllegalArgumentException: Field definition uses unexisting field 'Request' on class org.wso2.carbon.bpmn.extensions.soap.SOAPTask".

      So i guess i need to look into the Code to see how it is handling the SOAP request.

      Delete
  7. Hello Vinod, I'm using BPS 3.6.0, and I obtained the next error with the demo:
    ERROR {org.wso2.carbon.bpmn.extensions.rest.RESTTask} - Failed to execute GET http://www.mocky.io/v2/57360c780f00003b01b10269 within task resttask:Rest Task in process instance 12543 {org.wso2.carbon.bpmn.extensions.rest.RESTTask}
    com.fasterxml.jackson.core.JsonParseException: Unexpected character ('W' (code 87)): expected a valid value (number, String, array, object, 'true', 'false' or 'null')
    at [Source: java.io.StringReader@23ea0a3f; line: 1, column: 2]
    some idea?, thanks

    ReplyDelete
  8. i have tried to call soap task, but i have the following error: ERROR {org.wso2.carbon.bpmn.rest.common.provider.ExceptionMapper.BPMNExceptionHandler} - Activiti Exception Occured {org.wso2.carbon.bpmn.rest.common.provider.ExceptionMapper.BPMNExceptionHandler}
    org.activiti.engine.delegate.BpmnError: No catching boundary event found for error with errorCode 'SOAP_CLIENT_INVOKE_ERROR', neither in same process nor in parent process (errorCode='SOAP_CLIENT_INVOKE_ERROR') (errorCode='SOAP_CLIENT_INVOKE_ERROR')

    ReplyDelete
    Replies
    1. Please write to dev@wso2.org. The wso2 community will help you. Thanks.

      Delete
    2. Hi

      I am getting the same issue. Is there a way to fix this ?

      Delete
  9. This comment has been removed by the author.

    ReplyDelete
    Replies
    1. Hello,

      You have written on github that "You can import this project to Eclipse BPMN designer and make changes". But I could not import the project to eclipse. How can we import?

      Thanks a lot.

      Delete
    2. Clone the project from GIT. In Eclipse, File > Import > Maven > Existing maven project
      and select the cloned project.

      Delete