Process Dispatch Framework

USER GUIDE
Version: 1.1
Document Revision: 1.1

www.blueprism.com
Contents
1. Introduction...................................................................................................................... 3
2. Solution Overview............................................................................................................ 4
3. Pre-Requisites and Environment Configuration................................................................6
3.1. Additional VBOs.......................................................................................................... 6
3.2. Credentials................................................................................................................. 6
3.3.information
The Steps to Implement....................................................................................................
contained in this document is the proprietary and confidential information of Blue Prism 9
Limited and should not be disclosed to a third party without the written consent of an authorised Blue Prism
4.representative.
Utility – Process
No partDispatcher............................................................................................
of this document may be reproduced or transmitted in any form or by any means, 11
electronic or mechanical, including photocopying without the written permission of Blue Prism Limited.
4.1. Run Process.............................................................................................................. 11
© Blue Prism Limited, 2001 – 2019
4.2. Prism
®Blue Get Process Status...................................................................................................
is a registered trademark of Blue Prism Limited 13
5.All Customizing
trademarks are the Process
hereby Callback
acknowledged andTemplate..................................................................14
are used to the benefit of their respective owners.
6.Blue Prism is not responsible for the content of external websites referenced by this document.
Support........................................................................................................................... 16
Blue Prism Limited, Centrix House, Crow Lane East, Newton-le-Willows, WA12 9UY, United Kingdom
Registered in England: Reg. No. 4260035. Tel: +44 870 879 3000. Web: www.blueprism.com

Commercial in Confidence Page 2 of 16

1. Introduction
This framework is a collection of processes, VBOs, work queues, and environment variables
that can be used to provide a means for launching Blue Prism processes asynchronously via
SOAP request and receiving process results either through polling or a callback.

NOTE: This framework relies on the use of a resource pool to support the execution of
multiple processes in parallel. It is recommended that you create a dedicated resource pool
with enough runtime resources to handle your projected volume of concurrent processes.
For testing purposes, you may configure the resource pool with a single resource PC.

Commercial in Confidence Page 3 of 16

2. Solution Overview
This framework includes the following components:
 Processes
o Dispatched Process Monitor
 Used to periodically check processes that were started via the Process
Dispatcher VBO to determine if they have completed.
 VBOs
o Utility – Process Dispatcher
 Used to invoke a Blue Prism process asynchronously.
o Template – Process Callback
 A template VBO that should be customized based on your specific
callback needs.
 Work Queues
o Dispatched Processes
 A work queue used by the Process Dispatcher VBO and Dispatched
Process Monitor process to keep track of processes that have been
launched via the framework.
 Environment Variables
o Process Dispatcher Credential Name
 A variable that holds the name of a credential, defined in Credential
Manager, that will be used by the Process Dispatcher VBO to invoke the
specific Blue Prism processes.
o Process Dispatcher Resource Pool
 The name of the resource pool the framework will use when executing
processes.
o Queue: Dispatched Processes
 A variable that holds the name of the work queue that keeps track of
processes launched via the framework.

Commercial in Confidence Page 4 of 16

The following graphics provide a high-level conceptual view of how the framework
functions.

Resource Pool

Process X
Process Y
Process Z

SOAP Request
Process
Dispatcher
Session ID

Work Queue

Figure 1 - Dispatching a Process

No

Blue Prism DB

Callback Process Callback Yes Completed?

Server

Dispatched Process
Monitor
Work Queue

Figure 2 - Process Monitor and Callback

Commercial in Confidence Page 5 of 16

3. Pre-Requisites and Environment Configuration
3.1. Additional VBOs
This framework leverages the following additional Blue Prism VBOs which are available on
the Blue Prism Digital Exchange:
 Utility – Blue Prism Process Info
 Utility – JSON
 Data – SQL Server
Ensure these VBOs are deployed in your Blue Prism environment, otherwise you will
encounter exceptions.
3.2. Credentials
This framework utilizes credentials in three areas:

 Web Service Invocation

 AutomateC Execution

 Querying the Blue Prism Database

3.2.1. SOAP Web Service Invocation

The following VBOs must be exposed as SOAP web services within Blue Prism:
 Utility – Process Dispatcher
 Utility – Blue Prism Process Info
Invoking Blue Prism processes or VBOs requires that credentials be provided by the caller
for HTTP Basic Authentication.
To set up a user account for use with the web services:
1. Start the Blue Prism Interactive Client
2. Go to System → Security → Users
3. Right-click and select Create User
4. Fill in the various attributes for the user account.
5. From the list of Blue Prism roles, select Web Service Consumers. This role provides
the minimum necessary permission to be able to execute Blue Prism processes or
VBOs exposed as SOAP web services.

Commercial in Confidence Page 6 of 16

 Figure 3 - User Role

If your Blue Prism environment does not include a Web Service Consumers role, you can
create it with the following steps:
1. Go to System → Security → User Roles.
2. Click the Create button.

Figure 4 - Creating a Role

Commercial in Confidence Page 7 of 16

 3. Provide a name for your new role (ex. Web Service Consumers).
4. In the right-hand pane, expand the tree for Object Studio.
5. Place a check in the box next to Execute Business Object as Web Service.
6. Expand the tree for Process Studio.
7. Check the box next to Execute Process as Web Service.

Figure 5 - Selecting Available Permissions

8. In the bottom right corner of the UI, click Apply.

Congratulations! You now have a role available specifically for web service user accounts.
Return to section 3.2.1 and complete the steps for assigning this role to your dedicated web
service user account.
3.2.2. AutomateC Execution
AutomateC is a command-line utility included with Blue Prism. It provides various
capabilities, but to use the utility you must provide a user account with sufficient
permissions. The Process Dispatch Framework uses AutomateC to launch the requested
processes and query the status of a dispatched process.
Follow the steps outlined in section 3.2.1 above to create a user account for use with
AutomateC. For this user account, set the users role to Runtime Resources.

3.2.3. Querying the Blue Prism Database

This framework requires a user credential defined on the Blue Prism database. This
credential requires READ-ONLY access to the database. If you are unfamiliar with creating
user accounts within SQL Server, check with your local SQL Server database administrator.

NOTE: The framework does not write, delete, update, or otherwise change any information
within the Blue Prism database.

3.2.4. Credential Manager

The details of the various credentials, described above, must be stored in the Blue Prism
Credential Manager. Use of Credential Manager allows the processes and VBOs of the

Commercial in Confidence Page 8 of 16

dispatch framework to access the username and password in a secure manner without
having to hardcode those values within the actual processes/VBOs.
To add those credentials to Credential Manager, simply create a new General credential
for each of the user accounts and populate the Username and Password with the account
details. Within the various processes/VBOs of the framework simply reference the
credential name where required. The processes/VBOs will then request access to the
credential from Credential Manager.

Figure 6 - Credential Manager

NOTE: You must set the Access Rights of the credentials such that they can be accessed
by the processes/VBOs of the framework.

3.3. Steps to Implement

To deploy the Process Dispatch Framework:
1. Import the additional VBOs described in section 3.1.
2. Import the Process Dispatch Framework .bprelease.
3. Create the user credentials described in section 3.2.
4. Create a resource pool with sufficient resource PC’s assigned to handle your
maximum projected concurrent process volume.

Commercial in Confidence Page 9 of 16

NOTE: For directions regarding how to create a Resource Pool in Blue Prism, refer to the
Resource Pools and Groups guide on the Blue Prism Portal.

5. Expose the utility VBOs: Process Dispatcher and Process Info as SOAP web
services.
NOTE: For details about exposing a Blue Prism VBO as a SOAP web service refer to the
Web Services User Guide available on the Blue Prism Portal.
6. Open the Dispatched Process Monitor process. On the Get Process Results tab,
set the values of:
a. DB Server – The name of the SQL Server instance (ex. localhost\SQLEXPRESS)
b. DB Name – The name of the Blue Prism database within the SQL Server
instance.
c. DB Credential Name – The name of the credential you created in Credential
Manager to hold the read-only database user account information.
7. Open the VBO Template – Process Callback. On the tab, Execute Callback,
implement the necessary logic to support performing a callback in your environment.
NOTE: The implementation of the Execute Callback method is entirely dependent on your
environment and what applications you will be using to invoke Blue Prism processes. There
is an example implementation based on IBM’s Business Automation Workflow environment.
This is simply an example.
8. Verify the following environment variables have values:
a. Process Dispatcher Credential Name
b. Process Dispatcher Resource Pool
c. Queue: Dispatched Processes
9. Define an execution schedule for the process Dispatched Process Monitor (ex.
every 5 minutes).

Commercial in Confidence Page 10 of 16

4. Utility – Process Dispatcher
Below are the available actions in the Process Dispatcher VBO and the details of the
inputs/outputs that are available.
4.1. Run Process
Use this action to execute a specified Blue Prism process.
NOTE: The specified Blue Prism process must be published in the Blue Prism Control Room.
4.1.1. Inputs
Parameter Type Description
UseSSO Flag A flag indicating whether to use single sign-on or not. If
SSO is not used, a credential name must be supplied.
BPCredentialName Text The name of a credential, defined in Credential Manager,
with sufficient privilege to execute a Blue Prism process.
ProcessName Text Required – The name of the Blue Prism process you want
to execute.
ProcessParameters Text An XML-encoded string containing any input parameters
required by the specified process. The XML should consist
of a top-level, or parent, <inputs>…</inputs> element
that contains a number of <input /> child elements, one
for each input parameter of the specific process. Each
<input /> element must include three attributes: name,
type, and value where name is the name of the
parameter, type is the Blue Prism-specific type of the
parameter, and value is the actual value of the parameter.
Ex.
<inputs><input name=’Loop Count’ type=’Number’
value=’5’ /></inputs>
If the process requires a Blue Prism Collection as input the
XML of that parameter will change slightly. Instead of a
single value attribute, on the <input/> element, you will
have a number of <row> child elements within the
<input>…</input> element. Furthermore, each <row>…
</row> element will contain a number of <field/> children
equal to the number of fields within each row of the
collection.
Ex.
<inputs>
<input name=’Data’ type=’Collection’>
<row>
<field name=’Name’ type=’Text’ value=’John Doe’ />
<field name=’Address’ type=’Text’ value=’111
Somewhere Dr.’ />
<field name=’Age’ type=’Number’ value=’30’ />
</row>
<row>
<field name=’Name’ type=’Text’ value=’Sally
Smithers’ />
<field name=’Address’ type=’Text’ value=’2 Under
The Sea St.’ />

Commercial in Confidence Page 11 of 16

 <field name=’Age’ type=’Number’ value=’25’ />
</row>
</input>
</inputs>
CallbackInfo Text A string containing any information you wish to pass
through to the callback VBO when the specified process
completes. This data will be passed straight through the
callback function. No processing or validation will occur
within the Dispatcher.

NOTE: You may pass JSON encoded data via the ProcessParameters variable, but you
must pay close attention to the format and naming. Notice how each input variable name
starts with an “@”. This is required as the JSON will be converted to XML prior to being
passed to AutomateC. The “@” indicates that when the JSON is converted, the item name
should be created as an attribute on the specific XML element.
Ex.
{
'inputs': {
'input': {
'@name':'Loop Count',
'@type':'Number',
'@value':'5'
}
}
}

4.1.2. Outputs
Parameter Type Description
Success Flag A flag indicating whether the action completed
successfully.
Session ID Text The unique identifier of the process session instance.
Output Text The raw output of the AutomateC invocation. This may
contain error information in the event of an error.
Otherwise, it will contain the session ID and information
about which runtime resource the process is executing on.

Commercial in Confidence Page 12 of 16

4.2. Get Process Status
This action will return the status of a specific session.
4.2.1. Inputs
Parameter Type Description
UseSSO Flag A flag indicating whether, or not, to use single sign-on. If
SSO is not used, you must provide a credential name.
Credential Name Text The name of a credential defined in Credential Manager.
SessionID Text A unique session ID for a specific process instance.

4.2.2. Outputs
Parameter Type Description
Success Flag A flag indicating whether the action completed
successfully.
Process Status Text One of the following status messages:
 Pending
 Running
 Complete
Output Text The raw output of the AutomateC invocation. This may
contain error information in the event of an error.

Commercial in Confidence Page 13 of 16

5. Customizing the Process Callback Template
Once a process, that was launched via the Process Dispatch Framework, has completed,
the Dispatched Process Monitor will invoke the Execute Callback action on the Process
Callback Template. You must customize this action to implement the necessary logic to
notify your initiating platform (ex. IBM Business Automation Workflow, Oracle Integration
Cloud, RedHat Process Automation Manager, etc) that the Blue Prism process has
completed and to pass along any available output values from the process.

Figure 7 - Execute Callback Action

Within the Process Callback template VBO, there is an example callback implementation for
IBM Business Automation Workflow. This is an example of a callback process as it relates to
IBM DBA. You will need to implement the logic necessary for your initiating platform.

Commercial in Confidence Page 14 of 16

Figure 8 - IBM Digital Business Automation Example Callback

Commercial in Confidence Page 15 of 16

6. Support
This VBO is an open source project available on GitHub. For any issues please open a ticket
via the “Issues” page on the GitHub repository:
https://github.com/blue-prism/ProcessInfo

Additionally, support can be requested via the Blue Prism Community Portal at the link
below:
https://blueprism.connectedcommunity.org/home

Commercial in Confidence Page 16 of 16