How to call a REST API from Blue Prism
Happy New Year! This post walks thru a simple REST API call made by a Blue Prism RPA bot. APIs are the web’s enterprise plumbing. The API layer, specifically REST APIs, provide a simple, low code way to exchange data between systems.
For RPA, APIs provide an opportunity to expand the reach and breadth of a process. Cloud services and data, both internal and external, can be securely accessed. The bot provides teams a low overhead framework for calling and manipulating this data. Having worked with a full-fledged Enterprise Service Bus and API Platform, I can tell you in confidence an RPA tool is not going to replace this layer. ESB is a whole practice unto itself and is not a simple undertaking to build or replace.
Instead, technologies like ESB, APIs, BPM are complementary to RPA, and vice versa, it should not be one vs. another choice.
I buy into the notion of RPA bots as digital workers, and better yet peers to human co-workers. The Bot can be a resource to use other tools, like an API, and be a value-added component of the “digital supply chain” for modern workflow.
Per Blue Prism documentation:
“Blue Prism web services are natively SOAP, WSDL-based services. Blue Prism can expose Business Objects as SOAP web services and consume an external SOAP web service.
Blue Prism also provides support for REST web services via a series of VBOs (REST, HTTP, JSON). Blue Prism can consume REST web services using the REST VBO; however, it cannot expose REST web services and does not provide native support for creating them.”
If you are looking for tools to create APIs you could look at enterprise level tools such as: Mulesoft, AWS API services, Dell Boomi and others, or you could certainly develop your own with .NET, Java, Python, etc.
For an example API endpoint I am going to use the HubSpot CRM Contacts API to retrieve contacts records. HubSpot has a fantastic API with excellent documentation and samples. You can sign up for a free version of their CRM if you would like to play along.
Ok lets prep our ingredients for this recipe:
We need an RPA - I am using Blue Prism, most RPAs can make HTTP calls
We need some built-in Business Objects to
Make HTTP calls
Handle the JSON data response
We need an API - HubSpot CRM
We need an API key (Oauth is also an option)
We need the API endpoint URL
We need to understand how to call the API and what we are getting back.
We need firewall access in/out over port 443 for HTTPS traffic
With Blue Prism, you need to confirm that you have the following VBOs imported:
Utility - HTTP
Utility - JSON
Webservices - OAuth2.0
Webservices - REST
If you do not see these objects within Studio -> Objects, you should be able to do File -> Import and navigate to your VBO directory, C:\Program Files\Blue Prism Limited\Blue Prism Automate\VBO . See your Blue Prism Admin if you have issues/questions. After importing, I found I needed to restart studio to get the new objects to register.
The Blue Prism Webservices - REST object model is an excellent example of how to leverage objects as reusable components. It may seem more comfortable to put all of your logic in one object, but reuse is a worthy consideration to think about for future components.
Conceptually we have:
A process, which acts as the primary program, calling
the web services-REST object, which in-turn calls
and Webservices-OAuth objects as needed.
This design sets up a library of reusable components for different use case scenarios.
The great thing about REST APIs vs. a SOAP-based API is the simplicity. SOAP APIs provide rich semantic information contained in the WSDL and XML representations but require much more programming. SOAP is still widely used and as mentioned above, Blue Prism uses SOAP to expose blue prism processes (future post) as an API end point.
For REST APIs you merely need a URL and HTTP for communication (still need to program and configure the endpoint). In our example, HubSpot’s documentation explains that the API call to get a list of contacts looks like this:
https://api.hubapi.com - base domain URL
/contacts/v1/lists/all/contacts/all - the specific endpoint path
?hapikey=demo - required, links the call to your instance of the CRM data
&count=2 - optional parameters to refine the list
The image below highlights the different parts of a REST API query.
We are using an API key as a simple authentication mechanism. Another more robust option is to use OAuth. Blue Prism supports either use case. To keep things simple we can use the demo key using this REST url, https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey=demo&count=2.
The response from this HTTP GET URL should be two CRM contacts, delivered back to us in the JSON data format. JSON is a very popular format for sending and retrieving data. If you are not familiar with JSON you can read more about it here.
JSON is not a default data type in Blue Prism but no worries, Blue Prism has us covered via .NET and provides a VBO, Utility - JSON, to handle the translation of JSON into a Blue Prism Collection data type or vice-versa. Once you have a populated collection variable you can process the returned data set as needed using the normal pallet of Blue Prism stages.
API testing tools like https://smartbear.com/ or https://www.getpostman.com/, both have free options, can be very helpful when working with REST APIs. These tools allow you to simulate calls from your desktop or browser, to APIs. Much like I recommend developing your .NET custom code fragments outside of Blue Prism in an IDE such as Visual Studio or Visual Code, it is similar when working with APIs. API tools provide a better GUI for testing and debugging. Once you have the API call nailed down, you can copy it over to Blue Prism.
We have our endpoint URL, we have objects installed, now what? Well all you need to do is pass in the URL to the HTTP VBO and voila! In my simple business object:
I have a text data item to hold the URL
an empty, undefined collection to hold the HTTP Response data
and an Action stage using the web services-REST VBO
Clearly for a real-world project you probably would have many more actions dealing with the data, perhaps some additional input/output parameters to handle run-time configuration, but essentially this is all you need to make a REST API call.
The returned collection is an interesting example of nested collections. The Utility - JSON VBO was automatically called by the Webservices - REST VBO to translate the JSON payload into a collection. You can see in the screenshots below, check out breadcrumb navigation, how the nested JSON arrays get split into nested collections.
As you can see Blue Prism makes it very easy to extend the RPA Bot via REST APIs. I hope this post was helpful. Thanks!