REFramework Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 34

UiPath REFramework Manual

Author: Mihai Dunareanu

Peer reviewer: Andrei Cioboata

Revision 1.0

2 
Table of contents 
About the framework and its purpose 4 
Understanding a business process 5 
Introduction 7 
About state machines 7 
Framework component functions 8 
Global Variables 9 
Init State 10 
InitAllSettings.xaml workflow 10 
InitAllApplications.xaml workflow 10 
Init Transitions 11 
Get Transaction Data State 12 
GetTransactionData.xaml workflow 12 
Get Transaction Data Transitions 13 
Process Transaction State 14 
Process.xaml workflow 14 
SetTransactionStatus.xaml workflow 15 
TakeScreenshot.xaml workflow 17 
CloseAllApplications.xaml workflow 17 
KillAllProcesses.xaml workflow 17 
Process Transaction Transitions 18 
End Process State 19 
CloseAllApplications.xaml workflow 19 
KillAllProcesses.xaml workflow 19 
End Process Transitions 19 
Additional Functions 20 
GetAppCredentials.xaml workflow 20 
Logging 21 
Logged Messages 22 
Custom Log Fields 24 
Field Descriptions and explanations 25 
Getting started, examples 27 
Deploying the framework 27 
Defining the scope of the process component and preparing the framework 27 
Usage example 1 29 
Changes to GetTransactionData.xaml 29 
Changes to Process.xaml 31 
 
UiPath_REFramework manual 

3 
Changes to InitAllApplications.xaml 31 
Changes to CloseAllApplications.xaml 32 
Changes to KillAllApplications.xaml 32 
Usage example 2 32 
Changes to GetTransactionData.xaml 32 
Changes to Process.xaml 33 
Changes to InitAllApplications.xaml 33 
Changes to CloseAllApplications.xaml 33 
Changes to KillAllApplications.xaml 33 
Glossary of terms (marked in italics) 34 
 
   
 
UiPath_REFramework manual 

About the framework and its purpose

The framework is meant to be a template that helps the user design processes that offer, at a

barebones minimum, a way to store, read, and easily modify project configuration data, a robust

exception handling scheme and event logging for all exceptions and relevant transaction

information.

Because logs generated by each process are a vital component of its report generation, the

framework logs messages at each relevant step toward solving a business transaction and

sends those logs to the Orchestrator



server



. This is turn can be connected to the ELK



stack

(Elasticsearch,



logstash,



kibana



platform)



 which enables data storage and countless ways of

representing the data.

When we build tools, we try to first define their purpose and, in this scenario, the purpose of our

framework is to solve a collection of business transactions. Notice i did not write business

process, as all but the most simple business processes are typically composed of multiple,

distinct in scope and in purpose, collections of business transactions. Thus, let us henceforth

call such a collection of relatable business transactions a business



process



component



, a part

of a complete business process.

Thus, we could define a business process component as the sum of actions by which the data

needed for a set of transactions is obtained, processed, and is input into or out of an IT

resource



Such a component needs to be easily deployed to the machines it will run on (Orchestrator

server maintains versioning and easy deployment across all runtime machines), needs to be

scalable and needs to be able to communicate it’s output data with external mediums so that

other components of the business process may pick up the work where it left off. Such a

medium could be a shared folder, a data server, ftp server, email, Orchestrator server queue

e.t.c.

UiPath_REFramework manual

Understanding a business process

Take the following business process: a user has to check fuel prices using web resource 1

(external company website) weekly and update a file with the new values. Another user will then

utilize web resource 2 (internal company website) to obtain information about distances traveled

by vehicles in company service and correlates this information with the new costs of fuel. He

then uses web resource 3 (external company website) to pay for the deliveries.

In this example, we could use three business process components:

● The first, a weekly one, would read data from resource 1 to check and update the fuel

price file.

● The second would download information about distances from resource 2 and reference

the values obtained by the previous sub-process to filter and further refine that data.

Once done, it would save the data.

● The third component would read the information produced by process 2 use it to input

data into resource 3.

This business process could, of course, be expressed as the sum of two business process

components instead of three, for example by grouping sub-processes 1 and 2 together.

And, of course, it could be also broken up, for example sub-process 2 might be broken up into

two further pieces, one that downloads information from resource 2 and another that reads both

resource 1 and 2 information and processes it.

This technique of splitting a problem into easily definable, simple components is a great tool in

solving any business process, no matter how complex.

It also helps deal with a fundamental aspect of reality, time.

To see exactly how, let’s make a change to the business process described above: after the file

containing fuel prices was updated a user would need to confirm the validity of the values by

opening the file and signing it.

This means that before we utilize web resource 2 to obtain information we first need to wait for

the fuel cost file to be signed by a supervisor.

You can easily see how, If we implemented this using 3 components, the change would be

small, as we would need to only add one check in subprocess number two: is the file signed. If it

is, proceed. If it is not, exit and try again later. This also means that the robot is free to process

other tasks.

UiPath_REFramework manual

If, on the other hand, we had grouped components 1 and 2 together, we would have to

needlessly refetch data or implement an additional check on the fuel file, and this is obviously

not desirable.

We must also acknowledge that business practices do change over time, making small changes

like this one likely over long periods of time.

UiPath_REFramework manual

Introduction

About state machines

As you know, UiPath Studio has 3 types of data flow representations: sequence, flowchart and

state machine.

While the framework does contain all 3 data flow representations, we chose the state machine

for the main body of the program because it provided a cleaner solution to representing our

desired dataflow.

This is how wikipedia defines a finite state machine:

“A finite-state machine (FSM) or finite-state automaton (FSA, plural: automata), finite

automaton, or simply a state machine, is a mathematical model of computation. It is an abstract

machine that can be in exactly one of a finite number of states at any given time. The FSM can

change from one state to another in response to some external inputs; the change from one

state to another is called a transition. An FSM is defined by a list of its states, its initial state, and

the conditions for each transition.”

Basic rules when using a state machine:

● Since the system can be in only one state at a time, at least one transition condition from

a given state to another must become true either by generating a condition in the code

running inside the state, an external condition, or a combination of both.

● The transition conditions from each state must be exclusive (two transitions cannot be

true at the same time, thus allowing two possible paths of exit from a state).

● Another rule that is agreed upon is that no heavy processing must be done in the

Transition actions. All processing should be done inside the state.

Going back to the first chapter, the problems we needed to solve with this template were:

1. Store and read project configuration data

2. Separate IT



resource



 start, usage and end

a. For all retried transactions



, restart the IT



resource

3. Implement a robust exception handling and transaction retry scheme

a. Capture exceptions by type

b. Use exception type to retry transactions that failed with an application exception

4. Capture and transmit logging for all exceptions and relevant transaction information

UiPath_REFramework manual

Framework component functions

Table 1 shows the calling structure of the framework. That is, which workflows are called, the

order in which they are called, and the State of the main state machine where you can find the

workflow invoke.

Table 1 - Component call tree structure

Component file names and locations

State where it is called

Main.xaml

Framework\InitAllSettings.xaml

Init

Framework\KillAllProcesses.xaml

Init

Framework\InitAllApplications.xaml

Init

Framework\GetTransactionData.xaml

GetTransactionData

Process.xaml

Process

Framework\SetTransactionStatus.xaml

Process

Framework\TakeScreenshot.xaml

Process

Framework\CloseAllApplications.xaml

Process

Framework\KillAllProcesses.xaml

Process

Framework\CloseAllApplications.xaml

End Program

Framework\KillAllProcesses.xaml

End Program

Aside from these, there are additional workflows included but not called by default.

You can read about them in the “Additional functions” chapter.

UiPath_REFramework manual

Global Variables

The global variables are those variables whose scope is the main program, or main workflow.

They can be found in the main.xaml workflow file, by first clicking anywhere inside the main

state machine and then clicking the variables pane. Table 2 is a list of the project’s global

variables.

These are used to store information that will be available throughout the runtime of the process.

It is important to understand where each variable is written and where it is read.

The red cell background represents workflows in which the variable is written and the green cell

background workflows in which it is read.

Table 2 - Global variables table

Name

Data type

Is written in workflows

Is read in workflows

TransactionItem

QueueItem

GetTransactionData.xaml

Process.xaml

SetTransactionStatus.xaml

TransactionData

GetTransactionData.xaml

SystemError

Exception

Main.xaml

Main.xlsx

SetTransactionStatus.xaml

BusinessRuleException

Main.xaml

Main.xlsx

SetTransactionStatus.xaml

TransactionNumber

Int32

SetTransactionStatus.xaml

GetTransactionData.xaml

Config

Dictionary(x:String, x:Object)

InitAllSettings.xaml

InitAllApplications.xaml

GetTransactionData.xaml

Process.xaml

SetTransactionStatus.xaml

RetryNumber

Int32

SetTransactionStatus.xaml

TransactionID

string

GetTransactionData.xaml

SetTransactionStatus.xaml

TransactionField1

string

GetTransactionData.xaml

SetTransactionStatus.xaml

TransactionField2

string

GetTransactionData.xaml

SetTransactionStatus.xaml

UiPath_REFramework manual

Init State

InitAllSettings.xaml workflow

This workflow outputs a settings Dictionary with key/value pairs to be used in the project.

Settings are read from local config file then fetched from Orchestrator assets. Assets will

overwrite the config file settings

Table 3 - InitAllSettings.xaml Arguments and values

dataType and Name

Argument Type

Values

String: in_ConfigFile

Input

"Data\Config.xlsx"

String[]: in_ConfigSheets

Input

{"Settings", "Constants"}

Dictionary(x:String, x:Object): out_Config

Output

Config

InitAllApplications.xaml workflow

Description: Open and initialize application as needed.

Pre Condition: N/A

Post Condition: Applications opened

Table 4 - InitAllApplications.xaml Arguments and values

dataType and Name

Argument Type

Values

String: in_Config

Input

Config

UiPath_REFramework manual

Init Transitions

At the end of the Init State we should have read our configuration file into the dictionary Config,

a global variable, cleaned the working environment by calling the KillAllApplications.xaml

workflow only during startup, and initialised all the applications we will work with.

Table 5 - Init Transitions

Name

Condition

Transition to

State

Description

SystemError

SystemError isNot Nothing

End Process

If we have an application exception

during the initialisation phase than

we lack vital information to begin the

process. That is why we end by

going to the End Process State

Success

SystemError is Nothing

Get Transaction Data

If during initialisation we have no

error than Get Transaction Data.

UiPath_REFramework manual

Get Transaction Data State

GetTransactionData.xaml workflow

Description: Get data from spreadsheets, databases, email, web API or UiPath server queues. If

no new data, set out_TransactionItem to Nothing.

For a linear process (not repetitive), set out_TransactionItem only for in_TransactionNumber 1 -

first and only transaction.

If the process is repeatable, set io_TransactionData once for in_TransactionNumber 1, then

assign a new out_TransactionItem by using the in_TransactionNumber to index

io_TransactionData. Be aware that, at the end of the io_TransactionData collection, it is your

responsibility to set out_TransactionItem to Nothing, thus ending the process.

Table 6 - GetTransactionData.xaml Arguments and Values

dataType and Name

Argument Type

Values

Int32: in_TransactionNumber

Input

TransactionNumber

Dictionary(x:String, x:Object): in_Config

Input

Config

QueueItem: out_TransactionItem

Output

TransactionItem

Datatable: io_TransactionData

Input/Output

TransactionData

String: out_TransactionID

Output

TransactionID

String: out_TransactionField1

Output

TransactionField1

String: out_TransactionField2

Output

TransactionField2

UiPath_REFramework manual

Get Transaction Data Transitions

From the GetTransactionData state we have two possible outcomes. The first is that we have

obtained new transaction data in TransactionItem variable and so we move on to the Process

Transaction state. The other outcome is that either we have exhausted our data collection, and,

as a consequence of this, we have set the TransactionItem variable to Nothing or that we get an

Application Exception while processing GetTransactionData.xaml, in which case we cannot get

Data. This error causes us to go to the End Process State.

Table 7 - Get Transaction Data Transitions

Name

Condition

Transition to State

Description

No Data

TransactionItem is Nothing

End Process

If TransactionItem is Nothing

than we are at the end of our

data collection, go to End

Process.

New Transaction

TransactionItem isNot Nothing

Process Transaction

If TransactionItem contains

data, process it.

UiPath_REFramework manual

Process Transaction State

Process.xaml workflow

In this file all other process specific files will be invoked. If an application exception occurs, the

current transaction can be retried. If a BRE is thrown, the transaction will be skipped. Can be a

flowchart or sequence. If the process is simple, the developer should split the process into

subprocesses and call them, one at a time, in the Process.xaml workflow.

Table 8 - Process.xaml Arguments and values

dataType and Name

Argument Type

Values

QueueItem: in_TransactionItem

Input

TransactionItem

Dictionary(x:String, x:Object): in_Config

Input

Config

UiPath_REFramework manual

SetTransactionStatus.xaml workflow

This workflow sets the TransactionStatus and Logs that status and details in extra Logging

Fields.

The flowchart branches out into the three possible Transaction Statuses: Success, Business

Exception and Application Exception.

Each branch analyzes the type of content of TransactionItem. If its not empty and is a

QueueItem, then it means we are using a Orchestrator queue, so we must call the “Set

Transaction Status” activity to inform Orchestrator about the outcome of our transaction. If

TransactionItem is not a QueueItem, we can skip passing it and the “Set Transaction Status”

activity will not be triggered.

After that we log the result of the transaction within custom log fields to make it easier to search

for within results.

This workflow is also where incrementing of the io_TransactionNumber variable takes place. If

we have an application exception and our MaxRetryNumber has not been reached, we

increment the io_RetryNumber variable and not the io_TransactionNumber variables. This is

done in the Robot Retry flowchart, which manages the retry mechanism of the framework and

which is part of the "Handle System Error" sequence.

Table 9 - SetTransactionStatus.xaml Arguments and values

dataType and Name

Argument Type

Values

Dictionary(x:String, x:Object): in_Config

Input

Config

Exception: in_SystemError

Input

SystemError

BusinessRuleException: in_BusinessRuleException

Input

BusinessRuleException

QueueItem: in_TransactionItem

Input

TransactionItem

Int32: io_RetryNumber

Input/Output

RetryNumber

Int32: io_TransactionNumber

Input/Output

TransactionNumber

String: in_TransactionField1

Input

TransactionField1

UiPath_REFramework manual

String: in_TransactionField2

Input

TransactionField2

String: in_TransactionID

Input

TransactionFieldID

UiPath_REFramework manual

TakeScreenshot.xaml workflow

Usage: Set in_Folder to the folder Name where you want to save the screenshot. Alternatively,

supply the full path including file name in io_FilePath. Description: This workflow captures a

screenshot and logs it's name and location. It then saves it. If io_FilePath is empty, it will try to

save the picture in in_Folder. It uses .png extension.

Table 10 - TakeScreenshot.xaml Arguments and Values

dataType and Name

Argument Type

Values

String: in_Folder

Input

in_Config("ExScreenshotsFolderPath").T

oString

String: io_FilePath

InputOutput

CloseAllApplications.xaml workflow

Here all working applications will be soft closed.

Pre Condition: N/A

Post Condition: Applications closed

KillAllProcesses.xaml workflow

Here all working processes will be killed

Pre Condition: N/A

Post Condition: N/A

UiPath_REFramework manual

Process Transaction Transitions

The Process Transaction State is where the processing work for all transactions takes place.

After the Process.xaml file is executed, we look for an exception having been generated (either

Business Rule or Application). In case no exception was caught, it means we were successful.

The SetTransactionStatus.xaml workflow manages both the logging of the Process.xaml output,

as well as the management of the next transaction or the retrying of the current one. This

workflow is where TransactionNumber and RetryNumber are written, allowing for automatic retry

in case of an Application Exception.

Table 11 - Process Transaction Transitions

Name

Condition

Transition to State

Description

Success

BusinessRuleException is Nothing

AND SystemError is Nothing

Get Transaction Data

If we have a Business Rule Exception

we log it and go to the next transaction.

Rule Exception

BusinessRuleException isNot

Nothing

Get Transaction Data

If we have a business rule exception we

log it and move to the next transaction

by going to the Get Transaction Data

State.

Error

SystemError isNot Nothing

Init

If we have an Application Exception we

close all programs, kill them if they fail to

close, take a screenshot at the moment

the exception happened, and go to Init,

where we will reinitialize our working

environment and begin anew from the

transaction that failed (retrying until we

have reached the maximum retry limit)

UiPath_REFramework manual

End Process State

CloseAllApplications.xaml workflow

Here all working applications will be soft closed.

Pre Condition: N/A

Post Condition: Applications closed.

KillAllProcesses.xaml workflow

Here all working processes will be killed.

Pre Condition: N/A

Post Condition: N/A

End Process Transitions

This is the final state, out of which there are no transitions.

UiPath_REFramework manual

Additional Functions

Aside from the functions above, we included a useful workflow that will make credential

management easy to implement and secure.

GetAppCredentials.xaml workflow

Usage: Change in_Credential to a previously created Orchestrator asset or a Windows

credential and use outputs out_Username and out_Password.

Description: This workflow securely fetches or creates and uses a set of credentials defined at

it's input. It first tries to fetch them from Orchestrator. Failing that, it tries to fetch them from the

Windows credential manager. If they do not exist, it creates them and then outputs them.

Table 12 - GetAppCredentials.xaml Arguments and values

dataType and Name

Argument Type

Values

String: in_Credential

Input

"TestRobot-Credential"

String: out_Username

Output

SecureString: out_Password

Output

UiPath_REFramework manual

Logging

Log messages are very important to any business process design as they offer a report of what

has happened.

As previously stated, log messages are composed of multiple log fields, each with

corresponding values. Logs are automatically generated by the robot when important events

happen, but also by the developer using a “Log Message” activity, and are pushed to the

Orchestrator server, which implements a component that will further push these logs to the

Elasticsearch database.

UiPath_REFramework manual

Logged Messages

The following is a list of all the message logs within the framework, the places where the

corresponding “Log message” activity is called, the message and the level of the log (info, warn,

error, fatal).

Table 13 - Message logs

Message

Workflow

Log

Level

Stop process requested

Main.xaml

Info

Config("LogMessage_GetTransactionDataError").ToString+TransactionNumber.ToString+

". "+exception.Message+" at Source: "+exception.Source

Main.xaml

Fatal

"SetTransactionStatus.xaml failed: "+exception.Message+" at Source: "+exception.Source

Main.xaml

Fatal

Config("LogMessage_GetTransactionData").ToString+TransactionNumber.ToString

Main.xaml

Info

"Applications failed to close normally. "+exception.Message+" at Source:

"+exception.Source

Main.xaml

Warn

Process finished due to no more transaction data

Main.xaml

Info

"System error at initialization: " + SystemError.Message + " at Source: " +

SystemError.Source

Main.xaml

Fatal

"Loading asset " + row("Asset").ToString + " failed: " + exception.Message

Framework\InitAllSett

ings.xaml

Warn

No assets defined for the process

Framework\InitAllSett

ings.xaml

Trace

Opening applications...

Framework\InitAllApp

lications.xaml

Info

in_Config("LogMessage_Success").ToString

Framework\SetTrans

actionStatus.xaml

Info

in_Config("LogMessage_BusinessRuleException").ToString +

in_BusinessRuleException.Message

Framework\SetTrans

actionStatus.xaml

Error

UiPath_REFramework manual

in_Config("LogMessage_ApplicationException").ToString+" Max number of retries

reached. "+in_SystemError.Message+" at Source: "+in_SystemError.Source

Framework\SetTrans

actionStatus.xaml

Error

in_Config("LogMessage_ApplicationException").ToString+" Retry:

"+io_RetryNumber.ToString+". "+in_SystemError.Message+" at Source:

"+in_SystemError.Source

Framework\SetTrans

actionStatus.xaml

Warn

in_Config("LogMessage_ApplicationException").ToString+in_SystemError.Message+" at

Source: "+in_SystemError.Source

Framework\SetTrans

actionStatus.xaml

Error

"Take screenshot failed with error: "+exception.Message+" at Source: "+exception.Source

Framework\SetTrans

actionStatus.xaml

Warn

"CloseAllApplications failed. "+exception.Message+" at Source: "+exception.Source

Framework\SetTrans

actionStatus.xaml

Warn

"KillAllProcesses failed. "+exception.Message+" at Source: "+exception.Source

Framework\SetTrans

actionStatus.xaml

Warn

"Screenshot saved at: "+io_FilePath

Framework\TakeScre

enshot.xaml

Info

Closing applications...

Framework\CloseAll

Applications.xaml

Info

Killing processes...

Framework\KillAllPro

cesses.xaml

Info

You can see that many of the messages of the logs are made up of a concatenation (the + sign)

between strings stored in variables and static strings.

Let’s take one such example and break down its meaning. From there, every other log follows

the same logic. The message is the following:

in_Config("LogMessage_ApplicationException").ToString+"



Retry:



"+io_RetryNumber.ToString+".

"+in_SystemError.Message+"



Source:



"+in_SystemError.Source

The first part of the message,



in_Config("LogMessage_ApplicationException").ToString



, is read from

the Config dictionary, which enables easy modification if it is required. It is located in the

Constants sheet of the Config excel file, and it’s content at the moment of writing this is “System

exception.”

Next we append the constant string “



Retry:



“



 to which we append the value of the

io_RetryNumber, that is the retry we have reached.

Next we append the in_SystemError





message and source, as they will shows where the

exception occurred and what it’s message is.

As you can glean from the explanation of that single log message, it is composed of both static

and dynamic parts which are concatenated to form a whole.

UiPath_REFramework manual

Custom Log Fields

Since Elasticsearch is a NO-SQL type database (not relational), we want to have the ability to

group logs based on certain criteria. Those criteria will be additional log fields that we have

added throughout the framework.

Most of these you need only know about and not modify, while some of them require the

developer to modify the values written in those fields. In the table below is a list of the log fields

added to the framework, their values, whether or not a developer implementing using the

framework needs to change these values and the location, in the program, where they are

added.

Table 14 - Custom log fields

Field Name

Values

Value

Change

required

Location field is added

logF_BusinessProcessName

"Framework"

Yes

Main.xaml, Init State

logF_TransactionStatus

“Success”

“BusinessException”

“ApplicationException”

SetTransactionStatus.xaml, Success branch

SetTransactionStatus.xaml, Business exception branch