Custom Code Actions in Blue Prism

Custom Code Activities in Blue Prism

As a developer in the software industry, I know that we have all
worked on many different frameworks, tools, and libraries.

This blog will teach you how to write custom code in Blue Prism using the Code stage. In order to understand this, we are writing custom actions for
collection manipulation in Blue Prism, with actual examples.

Collection in Blue Prism:

There is a specific data type in Blue Prism that is specific to your
needs. The data is stored in a table. To access the data from the
collection, you need to loop through each row and get the information
by using the column’s name.

There are several ways to access information in an Excel file using Blue Prism: through the “collections” VBO, the “Utility Collection Manipulation“ VBO, or by using the built-in functions for working with collections. Remove Column, Remove Row Filter Collection, Sort Collection, etc.

Let’s start with writing our own custom utility actions for collection manipulation. To write custom actions, we are going to use the Code stage from the Object Studio.

The coding stage has the following properties.

+---------------+--------------------------------------------------+
| Property name | Description                                      |                   
+---------------+--------------------------------------------------+
| Name          | The name you want to give to the code stage.     |
| Description   | Text to describe the purpose of the code stage.  |                     
| Input         | List of Data Items as an input to a code stage.  |                    
| Output        | List of Data Items returns to parent stage       |
| Code          | Code written in VB script or C#                  |                    
+---------------+--------------------------------------------------+

Examples:

Blue Prism collection is a combination of rows and columns, like a table. So, you need to iterate on every row of the collection, even if we want a single particular column value from the collection.

Creating a configuration object:

We often saved configuration or settings related to the target process
implementation inside an Excel sheet while implementing the RPA
process. Before our process runs, we should create a configuration object in
memory and make it accessible to all sub-pages of our process.

We can do this by using Microsoft Excel VBO in Blue Prism. The table below shows some configuration information saved in the excel sheet.

Name: column name from the excel sheet which represents the
configuration name

Value: column name from the excel sheet, which represents the
actual value of the configuration.

+-----------------+-----------------------------------+
|      Name       |               Value               |
+-----------------+-----------------------------------+
| Credential_Name | xxxxx-xxx-xxx-xxx                 |
| Queue_Name      | default                           |
| Application_URL | https://some.appliocation.url.com |
| Input_Dir       | C:\Input                          |
| Out_Dir         | C:\Output                         |
| Mail_Username   | xxx-xx-xx-xx                      |
| Mail_Password   | *********                         |
| Mail_Host       | smtp.gmail.com                    |
+-----------------+-----------------------------------+

In other languages, we are saving configuration objects as below:

const Settings = {
 Credential_Name:’xxxxx-xxx-xxx-xxx’ ,
 Queue_Name: ‘default’,
 Application_URL: ‘https://some.appliocation.url.com',
 Input_Dir: ‘C:\\Input\\’,
 Output_Dir: ‘C:\\Output\\’,
 Mail_Username: ‘xxx-xx-xx-xx’,
 Mail_Password: ‘***********’,
 Mail_Host: ‘smtp.gmail.com’,
}

But, as we access configuration objects in many programming languages like

Settings.max_retries

We can’t access the property of the collection in Blue Prism. We can
access the value of a specific column from a collection by using a for-loop.

This will affect the performance of the process. To simplify the
task of parsing a two-column list into a single row, we have a custom
function.

I wrote this function using Visual Basic. You can use C# well. To create this function you can create a new procedure/page in your existing object or in MS VBO.

Drag the Code stage from the left side stage panel of the object studio and give it the following details.

• Input: The collection which has been generated after reading the configuration excel sheet.
• Output: Name of the collection you want to save the newly generated single-row collection.
• Code: Code to work this magic.

Here is the code below that should go inside the code tab of the Code stage.

New_Collection = New DataTable
Dim New_Row As System.Data.DataRow

For Each r As System.Data.DataRow In Collection.Rows
 New_Collection.Columns.Add(r("Name"), GetType(String))
Next

New_Row = New_Collection.NewRow()
For Each dr As System.Data.DataRow In Collection.Rows
 New_Row(dr("Name")) = dr("Value")
Next

New_Collection.Rows.Add(New_Row)

This will produce the new collection as shown in the below image:

This configuration object is visible to all pages in your process, so you
can access any property, such as the queue name.

[Config.Queue_Name]

This will give you the Queue name that you have saved in your configuration file. Similarly, you access the other properties from the configuration object.

Dynamically creating the nested collection:

Let’s understand this with a use case.

Consider a scenario where you have a collection for a specific field name that may be available in a collection or not. If it is available, then we have to add a collection against that column name/field name and if it is not, then we create that column in a collection and assign the target collection against that field.

For example, we have two collections with us.

• One is employee name collection and
• Report names we need to add to every employee

By using these two collections, we have to prepare a single-row collection, which will have a report name collection under each employee's name.

In other programming languages (Consider JavaScript as of now) we can achieve this as below:

let reports = ['Report1', 'Report2', 'Report3'];
let employees = ['E001', 'E002', 'E003'];
let userCompletedReports = {};
for (var employee in employees) {
  if (!userCompletedReports.hasOwnProperty(employees[employee])) {
      // does not exist hence creating collection for E003
      var emp = employees[employee];
      userCompletedReports[emp] = [];
      userCompletedReports[emp] =  {"ReportNames" : []}
  }
  
  for (var report in reports) {
    userCompletedReports[emp].ReportNames.push(reports[report]);
  } 
}
// Print the result
document.write(JSON.stringify(userCompletedReports, null, '\t'));

This will generate an output as:

{
    "E001": {
        "ReportNames": ["Report1", "Report2", "Report3"]
    },
    "E002": {
        "ReportNames": ["Report1", "Report2", "Report3"]
    },
    "E003": {
        "ReportNames": ["Report1", "Report2", "Report3"]
    }
}

The Blue Prism collection works differently. While defining the collection, we need to provide column information and the type of value to store.

This requires custom code actions. This Result Collection does not have any record yet.

Employee Collection:

Common report name collection that needs to add under each employee:

Process:

The process to create a single-row employee collection with nested report name collection

To create this function, you can create a new action/page in your existing object or in MS VBO. Then drag the Code stage from the left side stage panel of the object studio and provide the following details. This Code stage has the following properties:

+----------------------+----------------------+--------------------+
|       Input          |        Output        | Code               |   
+----------------------+----------------------+--------------------+
| Source Collection    | Result collection    | Code to work this  |  
| Collection to Append | will hold the single | magic              |
| Field Name to append | row nested           |                    |
| collection           | collection           |                    |
+----------------------+----------------------+--------------------+

Code that needs to be put inside the coding stage:

Code:

Dim RequestorCollection As DataTable
Dim objColumn As DataColumn
Dim newColumn As DataColumn

Dim RowsCount As Integer 
'Check If the current requestor name column does not exist'
RequestorCollection = new DataTable

If Not Source_Collection.Columns.Contains(Field_Name) Then

 'Create a column name with the input requestor name'
 objColumn = New DataColumn
 objColumn.DataType = GetType(DataTable)
 objColumn.ColumnName = Field_Name.Trim
 Source_Collection.Columns.Add(objColumn)
 
 For Each c As System.Data.DataColumn In Collection_To_Append.Columns
  newColumn = New DataColumn 
  newColumn.DataType = c.DataType
  newColumn.ColumnName = c.ColumnName
  RequestorCollection.Columns.Add(newColumn) 
 Next
Else
 
 For Each r As System.Data.DataRow In Source_Collection.Rows
  For Each c As System.Data.DataColumn In Source_Collection.Columns
   if (Field_Name = c.ColumnName)
    RequestorCollection = r(Field_Name)
   End If
  Next
 Next

End If

For Each R As DataRow in Collection_to_Append.Rows
 RequestorCollection.ImportRow(R)
Next

RowsCount = Source_Collection.Rows.Count

if RowsCount > 0 
 'Adding all the collection at 0 index'
 Source_Collection.Rows(0)(Field_Name) = RequestorCollection
Else 
 Dim New_Row as DataRow

 New_Row = Source_Collection.NewRow()
 New_Row(Field_Name) = RequestorCollection
 Source_Collection.Rows.Add(New_Row)
End if 
Result_Collection = Source_Collection

Result collection:

So by using this simple code activity, we can create a useful collection utility function that will be helpful in every Blue Prism project.