Teneo Developers

Blue Prism

This example shows how to create bidirectional communications between a Blue Prism server and Teneo. This page will guide you on how to trigger a Blue Prism process from a Teneo flow, and how to have a Blue Prism process request conversational responses from Teneo. You can download both the Teneo and the Blue Prism solutions below.

blueprism logo long

Getting Conversational Data from Teneo in Blue Prism

  1. Create a Web API Service in Blue Prism Go to System -> Objects -> Web API Services (A). Add a new Service (B)

Blue Prism 1

Give your webservice a name and set the URL of your deployed Teneo VA.

Blue Prism 2

This can be found is the Publish Menu in Teneo Studio:

Blue Prism 3

Set up a Common Parameter with name viewtype and an initial value of tieapi

Blue Prism 4

Create two actions, one to send text to Teneo for processing and another to end the sessions as needed.

Blue Prism 5

Make sure both Actions have the Enable Request Data Output Parameter box ticked.

Blue Prism 6

In the GET Action, define three Parameters, command, userinput and sessionID.

Blue Prism 7

Do the same for the End Session action, but with only the sessionID parameter.

Blue Prism 8

In the GET Action, set the URL Path of the Request to the following. The values in brackets are variables that we will set further on. Leave the Body empty.


Blue Prism 9

Then repeat for the End Session Action with the following values:


Blue Prism 10

Then in the Response part of the GET Action, define two parameters, Output (as a collection) and SessionID (as text).

Blue Prism 11

Repeat with the End Session Action, using parameters Status and Message.

Blue Prism 12

  1. Add VBOs to Blue Prism The next step is to add two of the VBOs included in Blue Prism to help us read an Excel file with test phrases and create a JSON output. The two VBOs needed are
  • MS Excel
  • Utility - JSON

To import them, go to File -> Import -> Process/Object:

Blue Prism 13

  1. Create a Blue Prism Process to iterate over the test phrases

In the Process Studio, right-click to create a new Process called Run Test Phrases.

Blue Prism 14

Double click on the Start stage and add two Inputs, Excel File Path and Excel Sheet Name. Then click on the blue rectangle icon in the Store In column to automatically create the Data Items in the Process.

Blue Prism 15

Once in the Process, create two new pages, Load Data and Process Data. Then add these pages to the Process in order, so that the final result looks like this:

Blue Prism 16

In the End Stage set a Phrase Data variable to collect the results.

Blue Prism 17

Make sure the Phrase Data Data Item has the Hide from other pages in the process checkbox unticked.

Blue Prism 18

Then go to the Load Data page, where we will load the testing data from the Excel page so we can run those dialogs against Teneo.

Drag an Action into the Process and set the Business Object to MS Excel VBO and the Action to Create Instance. Leave the inputs as they come in defaults and set a handle output.

Blue Prism 19

Drag another Action into the Process with the same Business Object but the Action set to Open Workbook. Use the Handle variable from the last step and the File Name one from the start stage as inputs. Create an Output called Workbook Name and use the automatic Data Item creation button:

Blue Prism 20

Blue Prism 21

Drag a third Action stage into the Process, same VBO, with Action Get Worksheet As Collection. Here you need to use the variables created by the previous steps as inputs and create a collection for the outputs:

Blue Prism 22

Blue Prism 23

Finally, drag a new Action for the same VBO and give it Action Close All Instances, no inputs or outputs needed.

Blue Prism 24

In the End Stage, add an output called Excel Data to store the information that came from the Excel Sheet.

Blue Prism 25

The final shape of the page should look like this:

Blue Prism 26

Now go to the Process Data page; there are no parameters for this Start stage.

Drag a Loop stage into the page and set the Collection value to Phrase Data

Blue Prism 27

Create a Data Item of type number to keep track of the conversation the phrase being looped belongs to abd give it an initial value of 1. Then use a Calculation Stage to set the current conversation number.

Blue Prism 28

Create another number type Data Item to keep track of the conversation the previous phrase was a part of. Then use a Decision Stage to see if it is the same conversation.

Blue Prism 29

For the cases where is not the same conversation, we need to make a small detour to end the session before trying the phrase. For that, use an Action Stage to call the End Session Action we defined in the Web API Service. No inputs are necessary and the outputs will be populated from the Web API Service, you can use the automatic Data Item generation to create the variables that will receive the response from the Teneo server regarding the ending of the session.

Blue Prism 30

Then use a Decision Stage to see if the session ended successfully. If ending the session failed, use an Exception Stage to handle it, if it succeeded, use a Calculation Stage to clear the Session ID Data Item.

Blue Prism 31

Now we set up a Calculation Stage to assign [Phrase Data.Conversation] to Last Conversation Number.

Blue Prism 32

On this stage the branch for a new conversation and the branch to continue one merge back again.

Blue Prism 33

Drag another Action Stage into the page and set it up as follows:

Blue Prism 34

Blue Prism 35

Use a Multicalc Stage to populate the fields in the Phrase Data Data Item.

Blue Prism 36

At this point you can close the Loop Stage and set up an End Stage with no outputs. The final shape of the Process looks like this:

Blue Prism 37

  1. Create Test Excel sheet For testing we will need an Excel sheet that contains the phrases we want to test, as well as the rest of the fields we want to use later. You can download the sample file here or create your own. Make sure you have the following headers in the first row:
  • Conversation - The number of the conversation. Use this ordinal to separate different conversations. The actual effect is that different conversations will happen on different Teneo Sessions.
  • Phrase - The text you want to test against Teneo.
  • Expected - The outcome you believe should be returned from Teneo.
  • Actual - The outcome that was returned from Teneo (leave this, Matches and Session columns empty, they will be filled in the collection)
  • Matches - Whether the actual response matches the expected one.
  • Session - The session ID of the test.
  1. Create Test Conversation in Teneo Switch to Teneo Studio and create a new Flow with a Syntax trigger for testing.

Blue Prism 38

Set up the condition in the Trigger so that it reflects the wording of the first phrase you want to test. followed by an Output Node with the first response you expect. Then repeat this as conditions for every subsequent condition and output node, make sure to have paths to give you an answer different from the one expected, like so:

Blue Prism 39

  1. Test Process Go to the Main Page of the Run Test Phrases process and give the Excel File Path and Excel Sheet Name initial values (these will emulate the values that are going to be passed from Teneo in the next part).

Blue Prism 40

Then run the process and let it finish. If there are no errors, it should have the tested items in the Phrase Data Data Item, under Current Values.

Blue Prism 41

If the values are there, you have successfully run a Teneo Dialog from Blue Prism.

Triggering a Blue Prism Process from Teneo

The last part showed how to start a Teneo Dialog from Blue Prism, this part will show you how to start a Blue Prism process from Teneo.

  1. Create User for Connections in Blue Prism

The first thing that we need to do is create a user in Blue Prism that is allowed to access an exposed Process. It is highly recommended to set up a new user separate from your Blue Prism user. Go to System->Security->Users and right-click on the user list to create a new user:

Blue Prism 42

Go through the Wizard screens and on the Roles screen, set it to Web Service Consumer.

Blue Prism 43

  1. Create a Blue Prism Process to handle incoming requests

This process only has a Main page, and its Start Stage has the inputs that are going to be sent from the Teneo solution, namely, the path where the target Excel file is and the name of the sheet in the workbook that is going to be loaded. To contain these value, create two text type Data Items.

Blue Prism 44

Pull a Process Stage into the page, and set the Process dropdown to Run Test Phrases and pass the two Data Items from the point above as inputs. Create a collection type Data Item to receive the outputs.

Blue Prism 45

Blue Prism 46

Then, use an Action Stage to call on the JSON VBO we imported before. We will use the Collection to JSON Action, with the collection from the last point as an input and a new text type Data Item for an output.

Blue Prism 47

Finally, in the End Stage set the Process Results JSON output to the text type data item we created in the previous point.

Blue Prism 48

The final form of this process should be like this:

Blue Prism 49

  1. Expose Process

Now that the process is complete, we need to expose it as a web service so that we can call it from Teneo. Under System -> Processes -> Exposure and click on Expose a Process. Follow the steps in the wizard and leave the default values. Select the Recieve Teneo Data process.

Blue Prism 50

  1. Add Connection class to Solution Loaded in Teneo

Now switch to Teneo Studio and go to Globals -> Scripts -> Solution Loaded.

Blue Prism 51

Open to edit and add the following code to it:

import wslite.http.auth.HTTPBasicAuthorization import wslite.soap.SOAPClient import wslite.soap.SOAPClientException import wslite.soap.SOAPFaultException class BluePrismConnectorProcess{ static def start(sheetName, filePath, soapClientUrl, basicAuth) { def client = new SOAPClient(soapClientUrl) client.authorization = new HTTPBasicAuthorization(basicAuth.username, basicAuth.password) try { def response = client.send(""" <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:blueprism:webservice:recieveteneodata"> <soapenv:Header/> <soapenv:Body> <urn:RecieveTeneoData> <urn:SheetName>${sheetName}</urn:SheetName> <urn:FilePath>${filePath}</urn:FilePath> </urn:RecieveTeneoData> </soapenv:Body> </soapenv:Envelope> """) println(response.httpResponse) println(response.header) return response.body } catch (SOAPFaultException sfe) { println sfe.message println sfe.text println sfe.httpResponse.statusCode println sfe.fault.detail.text() } catch (SOAPClientException sce) { println sce.message } } }

5. Create Integration

Then go to Resources-> Integration and click on 'Add' to create a wrapper for the function we put in the Solution Loaded script. This is not strictly necessary, since you can call the method from any script or output node, but it is good practice, makes the flows more readable, and allows for easy reuse while keeping concerns separate.

Give your integration a name and click on 'Save'.

Blue Prism 52

Rename the default method to Start and add the following code:

testResults = BluePrismConnectorProcess.start(sheetName, filePath, soapClientUrl, basicAuth)

Add four input parameters to will be passed on to the method, namely, sheetName, filePath, soapClientUrl and basicAuth.

Then add an output parameter in which to store the test results, called testResults.

Click 'Save' and close the integration.

Blue Prism 53

  1. Create Triggering Flow

Now go back to the Main Teneo window and create flow with a Syntax trigger as before.Give it a name and save to proceed to the flow window. Set the value in the trigger to something unique so that you can try it out easily and delete the output node (we'll add one later).

Blue Prism 54

Then create the variables that you will need to pass to the Integration. This is the master set of variables that will be passed between both platforms:

Variable NameExample valueDescription
sheetName'Sheet1'The name of the Sheet in the Workbook that contains the test phrases.
filePath'C:\Users\xxxxxx\Desktop\xxxxx.xlsx'The path of the file in the computer running Blue Prism where the Excel sheet is.
soapClientUrlhttp://bc94bxxxx1.ngrok.io/ws/xxxxTeneoDataThe URL of the exposed process.
basicAuth'[username:"Teneo", password:"Abcdxxx"]'Username and password of the Blue Prism user we created to consume the Web Service.
testResults''Placeholder for the results of the phrase testing.

Blue Prism 55

Then click on the integration you built before from the top menu to add into your flow and assign the variables we just created to it.

Blue Prism 56

Then create an output node to read out the JSON we received from Blue Prism phrase processing.

Blue Prism 57

And that's all we need for this flow. You can trigger it in Try Out or publish it and try it from your development environment. Now we can trigger a Blue Prism process from Teneo, which in turn will run a process which will trigger Teneo dialogs.

The Teneo dialogs, whether on Try Out or on a Published solution do not occur locally, but in one of our servers. If you have deployed Blue Prism to a cloud server, you can use the address of the exposed process directly. However, if you are running Blue Prism locally, ie, you are accessing the exposed webservice over http://localhost:8181, you will need a tunnel like ngrok to allow the Teneo server to make requests from the Blue Prism one.


  • You can download the completed Blue Prism Release with the steps in this guide already completed Teneo Connector.
  • Download the solution here.
  • Download the testing Excel
  • Import the solution into Teneo. For more details see: How to import solutions.