REST, SOAP and Blue Prism
Blue Prism can readily interact with a REST API as it supports the abilities to call the various REST verbs to facilitate communication. What is a little more involved is calling to an exposed Blue Prism object or process as to do this, we need to use SOAP.
What is, or more accurately, what was SOAP?
There are two main formats for data to be transferred around the internet. These are XML and JSON. XML is an acronym for eXtensible Markup Language. We are going to cover XML and more importantly, its associated lightweight communication protocol, SOAP, or Simple Object Access Protocol.
Let’s clear something right from the start; SOAP is old. Here is the spec . It’s from 2007, and that was the last update it received. SOAP comes from a time when communications between computers was relatively new it was not easy for a Unix based computer to talk to a Windows computer. The benefits that SOAP offered were easy, it was text, or instead, it was XML. XML is text, and sometimes human-readable, sometimes not so human-readable.
SOAP relies on the HTTP protocol for transport, but any reliable transport protocol could be used. SOAP also works across LANs and WANs, not just the internet.
To understand SOAP, it helps to understand XML. You do not need guru level knowledge but knowing the structure of a SOAP file and, hence its XML will help you in your journey of understanding SOAP and ultimately making a success of working with Blue Prism.
Microsoft created SOAP, but its support extends to numerous vendors. At least it did until JSON came along. SOAP, however, is embedded in multiple systems and because it is text-based, it doesn’t require firewall changes or individual permissions.
The three key features of SOAP are as follows:
It has no ties to existing component technologies. SOAP should work with anything.
- SOAP has no ties to any programming language. Any language that can output text can use SOAP. You might need a toolkit to help with the formatting thought.
- Easy to learn and to extend.
SOAP is intertwined with other technologies. XML we have previously mentioned, XSLT is eXtensible Stylesheet Language Transformations and is used to alter the format of the XML into other XML documents.
The other primary document type is the WSDL or Web Services Description Language. WSDL describes all documents and objects on a web server in the form of a schema.
The ideal use of SOAP is a quick-connect, do work, disconnect. Long-running processes don’t work well with SOAP, and there are other options to deal with requirements like these.
We are going to provide a method by which we can call into a Blue Prism object, via a REST interface, using NodeJS. We are going to call the Blue Prism SOAP endpoint from NodeJS, and we will call into NodeJS from a web browser, where we will see the results of our REST call.
So, we are going to create a NodeJS app that will be a REST API façade for the calculator VBO. The Calculator VBO is a simple four-function calculator providing Add, Subtract, Multiply and Divide to the two-parameter numbers that we provide.
What we are going to do is create a straightforward REST API using NodeJS and Express to call the SOAP endpoints in the Blue Prism object. The NodeJS application will make use of the Strong-Soap and Express npm packages as this provides a lot of the heavy-lifting for us with the SOAP communication and REST API endpoints.
The NodeJS code is meant to be an example or proof of concept. It is not textbook code; it is code that works and does the job. It can be refactored and likely made much better. It would be excellent if you can make the NodeJS code better, to fork the project and make your modifications for all to use. By doing this, you are helping to make our excellent development community even better.
So, as we have already stated, we are creating a NodeJS application, so in case this is new to you, we will go and find NodeJS, get it installed and then we can progress from there. In a browser, enter nodejs.org into the URL bar. You should see the following, dependent on your locale. If you are already ‘node savvy’ you might want to skip ahead a little.
It will usually be okay to work with the LTS version. However, you are free to choose as you deem necessary. NodeJS is a command-line tool, which means you will spend a fair amount of your time in a command or terminal window. Powershell is also a suitable tool along with Cmder (https://cmder.net/) Be aware that some corporate networks may dislike Cmder, as will the SmartScreen facility of Windows 10. You will need to address this in the way appropriate for your circumstances.
When you get NodeJS downloaded and installed, we need to move on to the additional items we need.
The source for all things node is the node package manager or npm. https://www.npmjs.com Node will install the tools you need to make use of npm, but in case you want to investigate other packages, this is the door to the world of extending NodeJS.
The extensions that we need are as follows:
ExpressJS – https://expressjs.com
Strong-Soap - This is part of a broader framework called loopback.io. This may be worth some further investigation as there is scaffolding support for SOAP and many other technologies; however you will need experience of Typescript for this, and right now, that goes beyond the scope of this document.
The packages mentioned above are available from npm. The individual sites will provide documentation support.
The most important item we need to have installed, though, is Blue Prism. A free learning licence is available from the Blue Prism website.
We are going to use the Calculator VBO and expose this in Blue Prism as a SOAP endpoint. We will then connect to each SOAP endpoint from our NodeJS app but from a lightweight REST API that we have built using ExpressJS.
REST, taking a slight detour.
So, what is this REST? REpresentational State Transfer is an architectural style that defines a set of rules for web-services. If you want the whole story, then Wikipedia has a great explaination here
So, let’s get to it.
The Calculator VBO
The Calculator VBO is a simple four-function calculator, add, subtract, multiply and divide. The actual build of the object isn’t significant. We will look at how to expose the object as a SOAP endpoint and how to access it from an external location through SOAP.
To expose an object, or for that matter, a process, we use the icon-bar on the left. The lower icon with the spanner and screwdriver, this is the system tab.
The above image shows objects that are already exposed. To expose the CalculatorBO object, click the Expose a business object link on the right of the screen.
Select the object you want to expose. In our case here, we are exposing the Calculator object.
While we aren’t using either of the two checkboxes shown above, their explanations are as follows:
Document Literal Encoding: Can be enforced when exposing a web service in the user-interface and also via the command line with a /forcedoclitencoding switch. This will force all actions (including Initialize and Cleanup) to use the specified format. If this enforcement is not selected, the initialize and cleanup actions will use RPC encoding, and the encoding for customer actions will be determined based on whether a collection data type is defined as an input or output parameter.
With RPC Encoding, use legacy namespacing: When calling a process or object which has been exposed as a web service, outputs that are simple types no longer have an empty XML namespace (xmlns=””). For backwards compatibility, users can specify that a process or object using RPC encoding should continue to use legacy namespacing when first exposing the process or object.
The CalculatorBO object is now exposed, and if we take a look in our windows system tray, we can see an icon that is of interest to us.
As you can see, the highlighted icon shows a Blue Prism icon; this is an internal web server that Blue Prism provides for the hosting of your objects and processes. The default there is showing that we are hosting on port 8181, this can be customized if required.
What does the browser say?
So, we have exposed our business object, let us go and see how it looks in the browser.
We are using the localhost IP address of 127.0.0.1/ws/, and it will list all the currently exposed processes and objects.
If we look at the list of Business Objects, we can see the discovery page of the CalculatorBO. The endpoint will reveal the WSDL or web services definition language. The image is displaying XML, and it describes the endpoints and services offered by this particular business object.
There is a little over two screenfuls of WSDL data. In the data, you will see the various functions (add, subtract, multiply, divide) wrapped into their functionality area. Each function can be seen with its parameter types, as each mathematical operation requires two parameters they are displayed as value1 and value2 respectively. We will meet these parameters later on when we call them from our node application.
We now need to make use of our calculator by calling it from our node application. At this point, it’s worth being aware that your firewall configuration could impede the functionality here. If you see any timeout errors, they are likely to be caused by your computer firewall configuration.
The REST-SOAP Proxy Code
We will now examine the code for the RSP (Rest-Soap Proxy).
The variables bluePrismUserName and bluePrismPassword are for your usage. Set these to the appropriate credentials on your installation. Make sure your user has the needed permissions to execute these objects.
The URL variable is holding the WSDL endpoint. When this is passed into Strong-soap, it will build a client object in NodeJS that does all the heavy lifting concerning communication with your Blue Prism object or process. We will see this in more detail later. Finally, we provide a value for some http_options, and these are used when creating the soap client, Blue Prism works better when these parameters are set.
Here we are providing two REST endpoints. They use the GET verb and will give the following output, respectively.
They are meant as information only and can be removed from any production code you may wish to implement.
Now, this code can be refactored. Indeed it should be; it is done this way to explain the concepts. There is a lot of repeated code here, and that is not good from a maintenance point of view. There are some console statements that display a start time and end time of each operation, these may also be removed, there are there simply to reveal the time taken to make the call. The timers are not precisely accurate; they are meant to give an idea only.
The final code snippet is shown below and this is what sets the actual express server listening for requests. As you can see it makes use of the port variable we defined earlier and it will display a message on the terminal screen when it is active.
Where have we been?
So, we have taken a Blue Prism Business Object (VBO) and successfully exposed it as a SOAP service. We have taken some NodeJS code and connected to that SOAP service while at the same time presenting the world with a set of REST endpoints from which to call the calculator functions.