How to use Camunda’s SOAP Connector

SOAP has been around for quite some time and there are many business applications using the protocol. We’re asked on a regular basis about how Camunda can help orchestrate processes that include these mission critical applications. As a result of this feedback from our customers, we have provided a SOAP Connector to help speed the time to value in the creation of your processes.

We’ll be using Camunda 8 Run and Desktop Modeler in this example though other options, like Web Modeler and Camunda 8 Self-Managed, can be used as well. We’ll also be using the ubiquitous SOAP UI application as an endpoint though you can use your own endpoints and utilize this as a tutorial if you’d like.  

Download and install Camunda 8 Run

You can use an already functioning Camunda 8 environment as the SOAP Connector is bundled in the latest releases. If you’re new to Camunda or if you want to get an environment up and running on your computer quickly, we highly recommend using Camunda 8 Run. For detailed instructions on how to download and install it, refer to our documentation here. Once you have it installed and running, continue on your journey right back here!

Download and install Camunda Desktop Modeler

You can download and install Desktop Modeler using instructions found here. You may need to scroll down to the Open Source Desktop Modeler section. Select the appropriate operating system and follow the instructions and be sure to start Modeler up.

Download and install SoapUI

In this example, we’ll use SoapUI and one of its tutorials as the SOAP endpoint. You can download SoapUI here. When you install SoapUI, be sure to also install the tutorials:

We’re almost there. With the latest releases of Camunda Desktop Modeler you may have noticed this message pop up when starting it:

Desktop Modeler creates connector template shortcuts for all of the out of the box connectors, with the exception of the SOAP Connector. To add the SOAP Connector template you’ll need to download and install it. The SOAP Connector template can be found here. Depending on which operating system you’re using, you’ll need to place the connector template in a particular folder and details about it can be found here. You’ll then need to either restart or reset Desktop Modeler (Ctrl-r or Cmd-r) for the connector template to be recognized.

Start SoapUI and start sample project

Start SoapUI locally and follow the instructions to import and start up the SOAP Sample Project as described here. Be sure to start ServiceSoapBinding MockService as shown here:

Once you have started the mock service you can explore the various web service requests. Expand ServiceSoapBinding in the navigator panel and expand the login node. Open login rq by double clicking on it. Your screen should look something like this:

You can run the request by clicking on the green play button to ensure that the service is running. You should get a response similar to the following:

 Next, what we’ll do is replicate this using the SOAP Connector in Camunda.

Create a process flow in Modeler

Go to Modeler and create a new Camunda 8 BPMN diagram. Build a simple one step process with a Start Event, a Task, and an End Event. Put focus on the task by clicking on it. Look for the SOAP Connector by clicking on the wrench icon in the context pad just to the right of the task to change the element. In the dialog box that appears, you can search for the SOAP Connector by typing in ‘soap’ in the search field or you can scroll through the templates. Your screen should look something like this:

Select SOAP Connector. Give the task a name. In this example the name is Call SOAP service. Now we need to fill in some parameters to make it work. You’ll notice the Service URL is in red to indicate a required field.

Go back to SoapUI and login rq and find the service URL. You should see it at the top:

Copy and paste the URL into the Service URL field:

http://127.0.0.1:8088/mockServiceSoapBinding

We’ll leave the fields of Authentication, SOAP version, and SOAP Header using default values:

For the SOAP body we will define a template with placeholders for variables that we’ll pass in. For SOAP body select Template from the drop down. For the XML Template itself you can copy and paste the contents of

<soapenv:Body>

In SoapUI login rq:

Into the XML Template field and replace the values of username and password with {{username}} and {{password}} placeholders. The XML should look something like this:

<sam:login>

<username>{{username}}</username>

<password>{{password}}</password>

</sam:login>

Next, enter in a variable name for the XML template context. We will pass in a JSON object with that name into the process. For this example we used usernamePasssword. That section of the properties panel should look something like this:

Now we need to enter the namespaces and this requires converting what is in XML into JSON. Heading back to SoapUI login rq, we can copy the namespaces defined in

<soapenv:Envelope...

Pasting them into the Namespaces field and editing them into JSON:

{ 
    "soapenv":"http://schemas.xmlsoap.org/soap/envelope/",
    "sam":"http://www.soapui.org/sample/"
}

Finally, set an output variable. You can dump the entire contents into a single variable and/or if you know the structure of the response you can use a FEEL expression to extract what you need. For now, let’s just dump the entire contents into a single variable and then we can create a suitable FEEL expression to retrieve needed contents. For the Result variable field we’ll use result.

Save your work.

Run the process

In Desktop Modeler go to the lower left hand corner and click on the Deploy button which resembles a rocket ship:

A dialog box should appear. Provide a deployment name, select Camunda 8 Self-Managed, enter a Cluster endpoint of:

http://localhost:26500

And set Authentication to None. Your screen should look something like this:

Click on Deploy. You should get a deployment successful message in Modeler:

Let’s run a process. In the lower left hand corner of Modeler, click on the Run icon that next the the Deploy button.

A dialog box should appear prompting you to enter in some JSON data. Copy and paste this into the JSON field:

{ "usernamePassword": 
   {
      "username": "Login", 
      "password": "Login123"
   } 
}

The dialog box should look something like this:

Click on Start.

View process in Operate

Open a browser and navigate to:

http://localhost:8080/operate

Log into Operate using demo/demo for username and password. The process will likely be completed by the time you navigate to the process instance in Operate. You should see the result variable with its contents. We’ll use this as a guide to extract the sessionid using FEEL in a little bit.

What happens if you run it again? What happens if you change the username or password?

Congratulations, you’ve successfully integrated with a SOAP endpoint using Camunda’s SOAP Connector!

Extracting the sessionid from the response

Before updating the process you’ll probably want to stop and restart ServiceSoapBinding MockService to avoid errors (ie user already logged in if you tried running it multiple times) when running the process again (see red box highlighting service stop and start):

Back in Modeler, go to the process diagram and open the Test SOAP Connector task. In the Output Mapping section in the Result expression field, use the following expression to create a variable called sessionid which extracts the sessionid from the response. The response is held in a variable called, oddly enough, response:

{sessionid: response.Envelope.Body.loginResponse.sessionid}

Your screen should look something like this:

Run the process again and head over to Operate to view the results:

You can see the new variable sessionid with the extracted data. While you can get to sessionid in the result variable using the following expression:

result.Envelope.Body.loginResponse.sessionid

It’s more elegant to extract the data you need. You can now use sessionid for the other calls in the SoapUI example – logout, search, buy. Have fun experimenting!

Try Camunda today

If you don’t already have a Camunda account, you can learn more about Camunda and get started with everything it has to offer for free. Note that Camunda 8 Run is a newly released distribution to help developers run Camunda 8 locally, so it requires a self-managed installation.