Blue Prism Attended Automation - Exposing & Testing Blue Prism Web Services

In the previous post I covered the basics of Blue Prism as a web service including a review of objects vs. processes, object run-modes, web service communication flow, and a few points on solution design. While you can choose to expose Blue Prism processes as web services, and this would be the most straightforward conceptual approach, changing to a solution design which directly communicates with objects for web service interactions presents significant benefits around license utilization, performance, and scale.

Before covering creative ways to use Blue Prism through web services, we need to first cover the steps required to make Blue Prism Objects & Process available as web services. This post is a “how to” guide on exposing Blue Prism Objects as web services, a rather critical detail about “initialization” introduced by using objects, and then testing an exposed object in the browser via Wizdler. The next post will cover some nuances around logging, security, and encryption related to web services and this object-first design. Then we will bring everything together to show how to integrate the object in this post into the Salesforce.com UI for a clean business user experience.

A video walkthrough of the major of topics in this post can also be found below.

[DEMO] Kevin Wilson - Using Wizdler to trigger Blue Prism web services

Exposing Objects as Web Services

I have created a very simple “MathTest” Object which performs add, subtract, and multiplication functions. This BP Object along with the pre-built SDFC Apex Classes, and SFDC Lightning Web Components I use in over the next several posts can be found on GitHub at https://github.com/blue-prism/NobleAttended.

Simple MathTest Object

The activities in this post require a Security Role with the following Permissions in Blue Prism:

• Execute Business Objects as a Web Service (under Object Studio Permissions)
• Business Objects – Exposure (under System Manager Permissions)

If you also have the "Import Business Object" permission then you can follow-along by importing my BP Object titled "BPA Object - MathTest (Josh).xml) found at the GitHub link above. After downloading the Object, just click File - Import from most screens in the BP Interactive Client and follow the prompts.

To expose an Object as a web service:

• Enter System Manager and select the Object area. Click "Exposure" and then "Expose a Business Object".
• A list of Objects which are not currently exposed as web services is presented. Select the target Object that is to be exposed and click "Next".

• The wizard will use the name of the Object to suggest a suitable name that will be used for the web service.
• It is possible to change the name at this point however if the name is a duplicate of a currently exposed Blue Prism web service or if any invalid characters are detected, a warning will be shown. Click "Auto Correct" to remove any invalid characters and ensure that the name is unique.

If necessary, adjust the encoding type that will be used for the object. By default, the following encoding types will be applied:

• RPC/encoded - The default encoding type for each action.
• Document/literal - The encoding type used for actions that contain an input or output parameter with a type of collection.

This setting requires a bit of familiarity with the system where you will embed the exposed Blue Prism web service. For salesforce.com I found that “enforce document / literal encoding” was required, or the WSDL2Apex conversion will throw an error.

• Once the name is acceptable, click "Finish".
• The newly exposed web service name will now appear in the list alongside the name of the Object.

• The WSDL-based web services that are exposed from Blue Prism can be confirmed by using the following URL which also provides the address of the UDDI.

https://[machinename]:<port>/ws/

NOTE - Where the Blue Prism Runtime Resource has been configured with certificate-based encryption, the prefix will be https.

In this example the machine name is resource001 and the default port of 8181 is in use: https://resource001:8181/ws/

Other UDDI syntax examples include https://52.##.###.213:8183/ws/ and https://blueprism###.southcentralus.cloudapp.azure.com:8199/ws/.

NOTE – This UDDI page is where we will pickup after installing the Wizdler Chrome or Firefox extension in the next section.

Object Initialization

In the previous post, I mentioned Blue Prism Digital Workers do not require a user interface for interacting with web services, work queues, and database function calls. Consequently, objects which only perform these types of functions can be set to background run-mode, which enables simultaneous requests to be received. This mode will allow for multiple instances of an object to run concurrently on the same Digital Worker.

In order to fully utilize the benefits of background mode in relation to web services, session initialization needs to be considered. Concurrent sessions will consume a Blue Prism license while running. However, non-UI functions operate extremely fast and initialization provides a workaround to minimize licensing. Triggering a process exposed via web services will always create a session. Exposing Objects via web services provides two options:

Manual Initialization – This method first calls the “initialize” action (tab) of an object to create & receive a session ID. This session ID is then used to populate the bpInstance input parameter on subsequent actions. This will have a license impact is multiple concurrent sessions are initialized. This mode can be used as a safeguard to prevent collisions if the Digital Worker is expected to handle other types of processing.

Auto-Initialization - A single session will be used for all actions taken against a given web service. This reduces the number of steps required as part of calling a Business Object action. It also allows a single session per Digital Worker to potentially handle unlimited web service requests. Most examples utilize this method because new sessions are not continually required, and license impact is limited. This is achieved by setting the bpInstance input parameter to the value of “auto”.

NOTE – There is not a setting in the Blue Prism Interactive Client for initialization. This is set externally through the web service call as shown below.

Testing a Blue Prism Web Service

Once a process or object has been exposed through a web service, we can connect these to a vast range of user experiences such as workflow systems, embedded buttons on existing enterprise systems, chatbots, mobile applications, etc. However, we should probably first test that the process or object works as expected in the raw WSDL format. Wizdler as it is a very simple Firefox and Chrome extension that was can use to test SOAP web services.

After installing the Wizdler browser extension, revisit the URL / UDDI for your exposed web services. The example above was at https://resource001:8181/ws/.

• Click the link for the WSDL for the exposed Object or Process you want to test. I am using the MathTest Object that we will integrate with Salesforce. Processes will show one activity that can be triggered, but with Objects, each action (tab) can be independently triggered.

As discussed previously, an Object can be manually or auto initialized. In this example we will use "auto" in the SimpleMultiply action to confirm our Blue Prism web service is functioning. We will embed this "auto" function when we setup the Salesforce Lightning Web Components.

• Select the appropriate action in the Widler extension drop-down.

Math Test WSDL

This will bring you to the request tab of the SimpleMultiply action. Note that Blue Prism utilizes the POST HTTP method.

• Enter "auto" as the bpInstance. If we were performing a manual initialization, the bpInstance would be a specific session ID.
• Enter the two values to be multiplied.

SimpleMultiply - Request (Auto)

Click “Go” - enter your Blue Prism credentials, and then click "Sign In".

SimpleMultiply - Enter Blue Prism Credentials

The WSDL will return the highlighted response below with the product of your two numbers (54 not 42).

SimpleMultiply - Response (Auto)

Now that we know the web service is operating, we can embed these actions into a more business friendly user interface. I will first cover a few topics around logging, security and encryption related to BP web services before the SFDC "how-to".

If you are jumping ahead, please first review “User Guide – Web Services” and “Data Sheet – Securing Network Connectivity” for additional information on interface design considerations, session management, licensing scenarios, certificate-based encryption, and consuming BP web services using Visual Studio.