Blue Prism RPA Integration Application

Blue Prism Example Process

Appian has partnered with Blue Prism, the pioneer of Robotic Process Automation (RPA) software, to allow business users to easily create processes that automate interactions with existing legacy applications within an Appian workflow.

This page documents the Blue Prism Integration application. The application contains everything you need to hit the ground running with your integration with Blue Prism.

Prerequisites

To fully leverage the application, you will need the following infrastructure and privileges:

  1. A running Blue Prism installation and access to a user account that can import objects and processes
  2. A running Appian installation that can communicate with your Blue Prism installation and access to a Designer user account
  3. A basic understanding of both Appian and Blue Prism

Setup

BluePrismConnectedSystem.png

The following steps detail how to get the Blue Prism Integration application running and integrated into your Blue Prism and Appian environments.

Installing the Appian Application

First, you need to install the Appian application.

  1. If you have not done so already, download the application from our Appian AppMarket.
  2. Unzip the downloaded file and navigate to the created directory.
  3. Open the file titled Blue Prism Integration.properties in your preferred text editor and edit the following values:
    1. Replace http(s)://[machine name]:[port]/ws/ in content._a-0000dfaf-f68f-8000-a320-01ef9001ef90_23173.VALUE to the base URL of your Blue Prism instance, following the template shown.
    2. Set connectedSystem._a-0000dfae-d665-8000-a320-01ef9001ef90_23369.username= to the Blue Prism user you want to authenticate as.
    3. Set connectedSystem._a-0000dfae-d665-8000-a320-01ef9001ef90_23369.password= to the password of your specified Blue Prism user.
  4. Save your change to Blue Prism Integration.properties.
  5. In Appian, import the Blue Prism Integration.zip application file, and provide the Blue Prism Integration.properties file during import.

Installing the Blue Prism Release

Next, install the Blue Prism release and expose the included process and object.

  1. In Appian, navigate to the newly imported Blue Prism Integration Application and find the document called Example Blue Prism Release. Download this file.
  2. In Blue Prism, import the Example Blue Prism Release release.
  3. Then, expose the myObject object and allDataTypes process as web services.

Validating your Setup

To validate that you completed the steps correctly, navigate to Appian and open the interface, BP_exampleCallBluePrismObjectInterface. In the live view, click the button labeled "Call Blue Prism Object". If the interface field labeled "Response" shows a green check, you are ready to continue. If you received an error, follow the steps below:

  • If you receive a "404 Not Found" error, ensure your object is exposed as a web service in Blue Prism.
  • If you receive a "401 Unauthorized" error, ensure that your credentials were correct in your customization file and are correct in your connected system.
  • If your interface timed-out, ensure the URL you supplied in the customization file is correct.

If you still cannot connect after checking the above items, open a support case.

Using Your Own Blue Prism Objects and Processes

Adapting the interface-helper objects and process helper objects to your own Blue Prism objects and processes is as simple as supplying the correct object and process names and creating the necessary data types.

First, create a text constant for each object action and process that you want to call. The value of the constant should be the corresponding action or process name. This way, you can track dependencies.

Next, create your data types. In the example data types section, we show you how data types in Blue Prism can be represented in Appian. To understand what data types you need to build, follow the steps below.

If you are calling an object action:

  1. Create an Appian data type with the same name and casing as the action you are calling. In our example, we call the Echo action of the myObject object.
  2. Set this data type's fields to the fields of the action. In the Echo action, we have three variables: text, date, and number. The names and types of the fields must match. For mapping collections, see the example data types section.
  3. Add a field called bpInstance of type Text to your data type. Notice we have done the same in our Echo type. This allows you to set the instance ID you want to use for your call. In all of our examples, we use auto-initialization per Blue Prism best practice. This means that this value will always be set to cons!BP_AUTO_INITIALIZE_VALUE, or auto.
  4. Create an Appian data type with the name "[action name]Response" where "[action name]" is the name of the action and the name of the data type you just created. In our example, we created the "EchoResponse" data type.
  5. Set the fields of the data type to the outputs of the action. In the Echo action, we output three variables: text, date, and number.

If creating a call to a process:

  1. Create an Appian data type with the same name and casing as the process you are calling. In our example, we call the allDataTypes process.
  2. Set this data type's fields to match the process's fields. In the allDataTypes process, we have seven variables: textInput, dateInput, numberInput, datetimeInput, timeInput, flagInput, and collectionInput. The names and types of the fields must match. For mapping collections, see the example data types section.
  3. Create an Appian data type with the name "[process name]Response" where "[process name]" is the name of the process and the name of the data type you just created. In our example, we created the "allDataTypesResponse" data type.
  4. Set the fields of the data type to the outputs of the process. In the allDataTypes process, we output seven variables: textOutput, dateOutput, numberOutput, datetimeOutput, timeOutput, flagOutput, and collectionOutput.

Finally, test the data types and constants.

If you are calling an object action:

  1. Create and open duplicate of BP_exampleCallBluePrismObjectInterface.
  2. Update the echoResponse rule input to your new "[action name]Response' data type.
  3. In the Expression View, replace all instances of ri!echoResponse with your new rule input.
  4. In the Expression View, replace cons!BP_EXAMPLE_OBJECT_NAME with the constant you created in the first step.
  5. In the Expression View, update the input type constructor, 'type!{urn:com:appian:types:bp:example}Echo'(...) to a type constructor for your "[action name]" data type.
  6. Click "Call Blue Prism Object". If you see a green check, everything is working correctly!

If you are calling a process:

  1. Create and open duplicate of BP_exampleCallBluePrismProcessInterface.
  2. Update the allDataTypesResponse rule input to your new "[process name]Response' data type.
  3. In the Expression View, replace all instances of ri!allDataTypesResponse with your new rule input.
  4. In the Expression View, replace cons!BP_EXAMPLE_PROCESS_NAME with the constant you created in the first step.
  5. In the Expression View, Update the input type constructor, 'type!{urn:com:appian:types:bp:example}allDataTypes'(...) to a type constructor for your "[process name]" data type.
  6. Click "Call Blue Prism Process". If you see a green check, everything is working correctly!

If you instead see an error, use the guidelines below to troubleshoot:

  • If you receive a "404 Not Found" error, your object or process name is incorrect.
  • If you receive a "SOAP Fault" saying that Blue Prism "Couldn't process soap inputs - Could not process parameter [input name]", ensure that you:
    • Updated the process or object name constant.
    • Have correctly mapped that [input name] input to the action or process input.
  • If your response value has null values for fields that should be populated, ensure your mappings for those fields are correct.

Understanding the Application Contents

The contents of the application can be split into two categories:

  1. Example Objects and Blue Prism objects that provide a drop-in example integration of Blue Prism and Appian
  2. Helper Objects for sending data to and retrieving data from Blue Prism

The sections below explain how learn from the examples and how to use the helper objects.

Example Objects

The purpose of the example objects is to provide you with a drop-in integration that connects your Appian instance to your Blue Prism instance. The objects are not intended to be a part of your application.

If you've followed the steps in the Setup section, then you've already interacted with some of these objects. The Appian objects are no different than any other object you would build when integrating with an external system, but there are a couple items worth pointing out specifically.

Example Interfaces

CallBluePrismObjectTestInterface.png

The two example interfaces, BP_exampleCallBluePrismProcessInterface and BP_exampleCallBluePrismObjectInterface, show you how to use the Interface helper rules that can call Blue Prism from an interface. These interfaces make a call to Blue Prism and show the structured response consumed by Appian.

Example Data Types

BluePrismDataType.png

The application contains 8 data types. First, notice that the naming convention of the data types is not uniform. This is done to illustrate when data types are required to match the names of the objects or processes that you are calling through the web services. Echo is the name of the Blue Prism object action that can be called through the BP_exampleCallBluePrismObjectInterface interface. allDataTypes is the name of the Blue Prism process that can be called in the BP_exampleCallBluePrismProcessInterface interface. For more information on how to name your data types, see the section on using your own objects. Nested collections, which are detailed below, do not need to have names that match their respective field names in objects or processes. They can be named however you choose.

Second, note that allDataTypes and allDataTypesResponse contain collections as fields. A collection in Blue Prism is analogous to a complex data type in Appian. When sending these types through Blue Prism web services, however, the collection takes on a unique structure in Blue Prism that needs to be reflected in Appian.

Take the below data structure as an example. This is a data structure present in our example Blue Prism process:

1
2
3
4
5
6
7
8
9
10
11
allDataTypes
    |-textInput (Text)
    |-numberInput (Decimal)
    |-flagInput (Boolean)
    |-dateInput (Date)
    |-datetimeInput (Date and Time)
    |-timeInput (Time)
    |-collectionInput (List of Collections)
        |-numberField (Integer)
        |-textField (Text)
        |-datetimeField (Date and Time)

In Appian, that structure needs to be represented differently:

1
2
3
4
5
6
7
8
9
10
11
12
allDataTypes
    |-textInput (Text)
    |-numberInput (Decimal)
    |-flagInput (Boolean)
    |-dateInput (Date)
    |-datetimeInput (Date and Time)
    |-timeInput (Time)
    |-collectionInput (BP_CollectionInput)
        |-row (List of BP_CollectionRow)
            |-numberField (Integer)
            |-textField (Text)
            |-datetimeField (Date and Time)

Notice the extra row field on the Appian data type. The same structure change is seen in the allDataTypesResponse data type. We do this because Blue Prism web services expose collection variables in their WSDLs in this way. Keep this in mind when creating your own data types to map to the Blue Prism request and response structures.

Example Process Model

In App Process

The example process model, Call Blue Prism Object, shows you an example usage of the process helper objects. To see the process run from start to finish, follow the steps below:

  1. Go to your action list in Tempo and start the "Call Echo Action".
  2. Enter values for the three inputs
  3. Click "Send to Blue Prism"
  4. See your values returned to you by Blue Prism

The two process helper rules, BP_getResultForOutput and BP_getErrorForOutput are used in the outputs of the integration node, Call Blue Prism Object. The usage would be the same if we were to call a process instead. For more information on these objects, see the section on using the process helper objects.

Using the Interface Helper Objects

CallObjectRule.png

The application includes four expression rules for making calls to Blue Prism from interfaces or web APIs. Each of these expression rules wraps an HTTP Post integration object and can be used generically to call different web services exposed by Blue Prism. Each of the wrapped integrations is set to modify data so that we don't start multiple processes in one interface request. For questions related to Blue Prism web services, see their Web Services documentation.

The purpose of the expression rule is to call the integration and update the response so that torecord() can successfully convert the XML to an Appian data type. Because the expression rules all call an integration that alters an external system, they can only be called in a saveInto or web API. The underlying integrations can also be called from process, but in that case, you would use the process helper functions. For details on the individual interface-helper rules, see the sections below.

rule!BP_callObject()

This expression rule should be your default rule to integrate with Blue Prism. This rule will run the specified Blue Prism object action using the given instance ID. When constructing the inputValue data type–Echo in our example–you should use cons!BP_AUTO_INITIALIZE_VALUE as the instance id, per Blue Prism best practices. Otherwise, you will need to manually initialize and clean-up the object which could impact license usage.

Input Name Type Description
objectName Text The name of the Blue Prism object to call. In the example application, the action is called Echo.
inputValue Any Type The value to send to the Blue Prism object's action. In the example application, we send data contained in an Echo data type.
responseType Any Type A variable (local, PV, type!MyType(), etc…) that is of the type that the response should be cast to. This is required to parse the XML returned by Blue Prism. In the example application, we pass type!EchoResponse().
responseSaveInto List of Save The variable or list of variables to update when the object is successfully called. The save value will be a variable of the type passed in responseType.
errorSaveInto List of Save The variable or list of variables to update if the object call fails. The save value will be a Dictionary containing an error field and a result field.

rule!BP_initializeObject()

Use this function to initialize an object. We recommend you use auto-initialization for business objects, but if business needs require you to use one session for multiple calls, you will need to manually initialize and clean-up business objects before calling them.

Input Name Type Description
objectName Text The name of the Blue Prism object to initialize. In the example application, the action is called Echo.
responseType Any Type A variable (local, PV, type!MyType(), etc…) that is of the type that the response should be cast to. This is required to parse the XML returned by Blue Prism.
responseSaveInto List of Save The variable or list of variables to update when the object is successfully initialized. The save value will be a variable of the type passed in responseType
errorSaveInto List of Save The variable or list of variables to update if the object initialization fails. The save value will be a Dictionary containing an error field and a result field

rule!BP_cleanUpObject()

Use this function to clean-up an initialized object. We recommend you use auto-initialization for business objects, but if business needs require you to use one session for multiple calls, you will need to manually initialize and clean-up business objects before calling them.

Input Name Type Description
objectName Text The name of the Blue Prism object's action to clean up. In the example application, the action is called "Echo"
responseType Any Type A variable (local, PV, type!MyType(), etc…) that is of the type that the response should be cast to. This is required to parse the XML returned by Blue Prism.
responseSaveInto List of Save The variable or list of variables to update when the object is successfully cleaned up. The save value will be a variable of the type passed in responseType
errorSaveInto List of Save The variable or list of variables to update if the object clean-up fails. The save value will be a Dictionary containing an error field and a result field

rule!BP_startProcess()

This expression rule will start a Blue Prism process. This rule should be used sparingly and only when synchronous processes are mission critical. It is Blue Prism best practice to instead call an object and have that object put the data in a queue. We recommend this because processes can take a long time to complete, and a synchronous call to start a process could very easily time-out.

Input Name Type Description
objectName Text The name of the Blue Prism process to start. In the example application, the process is called allDataTypes.
inputValue Any Type The value to send to the Blue Prism process. In the example application, we send data contained in an allDataTypes data type.
responseType Any Type A variable (local, PV, type!MyType(), etc…) that is of the type that the response should be cast to. This is required to parse the XML returned by Blue Prism. In the example application, we pass type!allDataTypesResponse().
responseSaveInto List of Save The variable or list of variables to update when the process is successfully called. The save value will be a variable of the type passed in responseType.
errorSaveInto List of Save The variable or list of variables to update if the process call fails. The save value will be a Dictionary containing an error field and a result field.

Using the Process Helper Functions

The application includes two functions that will help you use the integrations in process. When using the Call Integration smart service with any of the four integration rules included in the application, use the expression rules below in custom outputs of the node. The rules will convert the results of the call into more easy-to-use values. See the Call Blue Prism Object process model for an example that uses these rules.

rule!BP_getResultForOutput()

This expression rule converts integration node outputs into the data type of your choice. Create a custom output to use this rule, and store the result in a pv of a data type you created to match the output of the process or object action. See the section on using your own objects and processes for details on how to create such a data type.

Input Name Type Description
error Text The error that was returned if an error occured. Pass ac!Error.
result Any Type The raw result of the call. Pass ac!Result.
processOrObjectName Text The name of the process or object that was called. In our example, we pass cons!BP_EXAMPLE_OBJECT_NAME.
outputTarget Any Type The variable that you will be storing the result in.

rule!BP_getErrorForOutput()

This expression rule converts integration node outputs into an integration error. We need to do this because the web services return a 200 response code even if a SOAP fault (meaning error) occurs. Create a custom output to use this rule and store the result in a pv of type IntegrationError.

Input Name Type Description
error Text The error that was returned if an error occured. Pass ac!Error.
result Any Type The raw result of the call. Pass ac!Result.

Following Blue Prism Best Practices

The following best practices, illustrated in the application, should be followed unless a strong business need requires deviation:

  1. Although this application provides rules for making 4 different kinds of calls to Blue Prism, it is best practice to leverage the BP_callObject and set the bpInstance value of your action data type to cons!BP_AUTO_INITIALIZE_VALUE. Business objects require less overhead to initialize than processes, and auto-initialization reduces the licensing impact of making a call.
  2. In addition, the only processing an invoked object should perform is to take the sent data and place that data in a queue to start a process. This minimizes the risk of a call timing out.
  3. Finally, all objects exposed as web services should be set to run in the background. That way, a single robot can service multiple requests at once.

For more information, see the Blue Prism web service documentation

FEEDBACK