For the avoidance of doubt, except as permitted by the license or these terms, you cannot (a) copy, translate, reverse engineer, reverse
assemble, modify, adapt, create derivative works of, decompile, merge, separate, disassemble, determine the source code of or
otherwise reduce to binary code or any other human-perceivable form, the whole or any part of the Training Materials; (b) sublease,
lease, assign, sell, sub-license, rent, export, re-export, encumber, permit concurrent use of or otherwise transfer or grant other rights in
the whole or any part of the Training Materials; or (c) provide or otherwise make available the Training Materials in whole or in part in
any form to any person, without prior written consent from Blue Prism.
All trademarks are hereby acknowledged and are used to the benefit of their respective owners.
Blue Prism is not responsible for the content of external websites referenced by this document.
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
This course will cover the advanced principles of an integration method called Surface Automation. Surface
Automation is a technique for working with images and although primarily used on thin-client applications, it can
also be applied to any application with a user interface.
For the exercises in this document we will employ Blue Prism’s Surface Automation Training thick-client
application to simulate the effect of a thin client. And some of the exercises here will be deliberately less
prescriptive than in the basic training course.
Key Point
• Although we can spy the Surface Automation Training application as normal (i.e. using Win32 and AA), for
these exercises we are going to pretend that we can’t and work with it using Region mode.
• Import the Surface Automation Training - Base Objects.bprelease file to load the 5 Business Object
Templates.
• Open one or two of the Business Objects to see how they have been set up.
• The Surface Automation Training application has been designed to make things a little difficult by
displaying the current date in the title bar.
• As you know, a region is an area of a Win32 element, and as such the Window Text attribute can play a role
in identifying the region. Today the default attribute will work but tomorrow it will not.
• Change the Match Type of the Window Text attribute of your region to * (Wildcard) and change the Value
to Blue Prism Training*
• Now select the W32 element above your region and change the Window text attribute in the same way.
Importantly, this will ensure that any new region you create under this element will carry the same
wildcard setting.
• Create image regions for the User Name labels and the Log In and Reset buttons. Use the default
properties for all. If you recall from the previous course, the run time image search starts in the design time
position, so here reducing the padding won’t make the search more efficient.
• Create coordinate regions for the User Name and Password fields. Position the regions neatly just inside
the bounds of each field.
• Relate the coordinate regions to their respective labels.
• Recreate the logic from the basic training course to populate the Log In screen and press the button.
Remember to use the Pause After Each Step field to introduce pauses between Navigate actions. Note that
a set of global data items are available on the Initialise page.
• Run the page to check it works. Remember what we learnt in the basic training course about obscuring the
target app.
• Once you are happy with your Log In page, save and close your object.
2 Data Output
Exercise 2.1.1 Get Account Details
In this exercise we’ll concentrate on reading from the application, which by default uses Arial 9.5 as its font.
• Go back to Application Modeller, select one of your region elements and press the Regions button to open
Region Editor.
• Zoom the image to 500% and scroll one of the radio buttons into view.
• Create a coordinate region that sits precisely inside the radio button, without touching the sides.
• Then create an image region around the label that is the parent of the coordinate region.
• Connect the branches of the Wait stage to two Calculation stages, one to set a flag to False and the other
to True.
3 Data Input
Exercise 3.1.1 Text Boxes
You have already dealt with entering values into textboxes on the Log In screen and populating the Account Details
screen is no different.
• Manually press the New button to prepare the Account Details screen.
• At the start of the Set Details page of your object, place a Wait stage that checks for the Account ID field.
• After the Wait stage place a Navigate stage that populates the field. Recall from the Log In page that you
can send keys like {HOME}{DELETE 20} to make sure the field is empty before you enter your value.
Remember also that Global Send Keys requires that the target application is active and that the cursor is in
the right place.
• Once you have Global Send Keys working, try the ‘paste from clipboard’ method we used in the basic
training course.
Input Validation
In very rare circumstances, which are wholly dependent on the target application, you may see inconsistencies with
Send Keys, where the characters arrive in a different order, e.g. ‘12435’ instead of ‘12345’. Increasing the Interval
input value is likely to cure this problem, but it may also be necessary to read back the data entered to confirm the
input is correct.
• It is only recommended that this method of validating all text entry is used if a reliability issue has been
found with Send Keys during your testing.
• Even where testing has shown that such validation is not required, it may be deemed prudent to read back
any critical text entry (e.g. financial transactions) as a means of mitigating risk.
• Add a two-branch Wait stage to the Set Details page as before, so that you can detect whether the Verified
checkbox is ticked or not. On the ‘not ticked’ branch add a Navigate stage to click the checkbox.
• The Gender input is a little more work because it has wo radio button, but the same principle applies –
check the current state and then click if necessary.
• Manually prepare the Account Details screen in readiness for a new account.
• In your diagram, add a Navigate stage to focus the Title field with a Global Mouse Click Centre.
• Then use Global Send Keys to enter ‘Mr’. You should see that the correct list item is automatically selected.
• Manually Press the New button to reset the Account Details screen.
• Use a Navigate stage to open the Title list with a Global Mouse Click aimed at the button on the right-hand
end of the combo box. Coordinates x=190 and y=10 should work.
Key Point
• A Global Mouse Click can use coordinates outside the bounds of a region or element.
• Then use Global Send Keys to enter {DOWN} for the down arrow key.
Evidently this method assumes that the target item is below the current item. Where this is not the case, then it
may be necessary to use {UP} to travel up the list, or maybe use {HOME} to travel back to the first item and then
move down from the top. As awkward as this sounds, sometimes it is the only way to manage a combo box via
Surface Automation.
A simple solution would be to modify the expression in the Decision stage to compare the part of the Title that
Recognise text will see, e.g. [Screen Text]=Mid([Title], 2, Len([Title]))
Key Point
• The methods described above are examples of how a combo box might be handled. These techniques may
require adjustment to suit the combo boxes you will encounter in the real world.
Already you will have noticed the icon indicating the locked status of the account record and that it’s change of
state is not instantaneous. You will also be aware that the speed of execution in Control Room is far higher than in
Object Studio and that simply clicking the icon without waiting will not work. As always, we have to make our
object keep pace with the state of the target application.
• Run the page to check that it works. Remember to add in an Activate Application and to use the Pause
After Each Step field.
• If you wish, you could create an Unlock page to do the opposite operation.
• Create a coordinate region to the right of the New button where the spinning icon appears. Don’t worry
about the accuracy, the region only need to be approximate.
• Create another image region for the Save button.
• On the Save page of your Business Object use a Navigate to click the Save region.
• After the Navigate use a Wait stage with the Uniform Colour = False condition.
• Then add a second Wait that has the Uniform Colour = True condition.
Here the first Wait stage tells us that the save is in progress and the second tells us when it is complete.
Navigating between tabs is very much like the lock/unlock logic we created previously.
• Run the page to check that it works. Add an Exception stage to the time out of the Wait to finish off the
page.
• Then copy the Navigate, Wait, End and Exception stages from the page and paste onto the Navigate to
Details page.
• Adjust the Navigate and Wait properties to use the Account button region and then run the page to check
that it works.
5 Tabulated Data
As you will have seen, the Notes tab presents a large table of notes. In these next exercises we will learn how to
make a coordinate region move from row to row so that we can read the table.
• Close your SA Training - Account Details Business Object and open SA Training - Account Notes.
• Create a coordinate region that fits inside the first Agent cell around the text.
• Close Region Editor and set the Window Text attribute to wildcard, as we have done before. Remember to
change the region element and the Win32 element above it.
• Apply the Dynamic Match Type to the Start Y and End Y attributes of the region.
• Make a note of the Start Y value, which in this example is 161. Your value might be a little different.
• Return to Region Editor and create an image region on the Agent column header. As below, note that this
region does not need to sit perfectly around the word ‘Agent’ as we won’t be reading text from it. The role
of this region is to anchor the cell region, so it is enough that the header region is visually unique and has
enough padding to be found.
• Make the cell region position relative to the header region.
• Now add three number Data Items called Start Y, End Y and Row Height. Set the initial value of Row Height
as 25.
• After the Read stage, add a Multi-calculation stage to work out the values of Start Y and End Y. At run time
the Bounds collection will have a field called Top, and we will add the 17 (remember you might have a
slightly different value) to it to calculate the position of the top of cell region. We’ll assume a region height
of 20 and use that in the second calculation.
• After the calculation, add a Read stage that applies Read Image to the cell region. And because the cell
region has dynamic attributes, you will need to press the Params button to supply values for them.
• Add a new number Data Item called Row and set its initial value to zero.
• Drag the End stage away from the Read stage and introduce a Calculation stage to increment the Data Item
by one.
• Note that the training application displays thirteen rows at a time, but the thirteenth row is not fully visible.
With the Surface Automation mantra of ‘if you can’t see it then neither can Blue Prism’ in mind, for now
let’s concentrate on the first twelve rows only.
• Add a Decision stage after the Multi-calculation that uses the expression [Row] >= 12. Link the Yes branch
to the End stage.
• Create another Multi-calculation and add in the following expressions.
• Run the page and then look at the image Data Item. You should see an image of the Agent cell from the
twelfth row. The cell border should not be visible.
• As an example, change the initial value of the Row Data Item to 24 and re-run your page.
• Open the properties of the Notes collection and see that it has been set up with three fields.
• Add a new row to the cell Read stage and use Recognise Text to store a value in the Agent field of the
Notes collection.
• Press the Params button to supply the Start Y and End Y dynamic attributes.
• For the Font, you have the option of providing the font name in the Read stage or setting it in Region
Editor. In practice we would probably do the latter but here we will do the former. The font is Arial 9.5 and
because the application text is black, we don’t need to provide a foreground colour (or a background
colour).
• Run the page and then look at the current values in the Collection. You should see that the twelve cells
have been read.
• Open Application Modeller and press the Regions button to open Region Editor.
• Create a new coordinate region inside the first Date cell and relate it to the Agent header region. We could
create a new Date header region, but here we can simply reuse the Agent header region.
• Close Region Editor and use Copy Element Mask to copy the attribute selection from the Agent cell region
and paste it onto the Date cell region. This is a quick way to apply the same Match Type settings.
• Edit the Read stage properties to use Recognise Text to read the Date cell. Remember to set the dynamic
attributes Start Y and End Y, and to provide the font name Arial 9.5
• When reading character data from an application, it is usually better to use the Text data type, even for
values like dates. The reason for this is that it avoids any potential casting errors at the read stage and
provides the opportunity to resolve problems after the data has been captured.
• This principle applies to any read technique, not just Surface Automation.
• Copy the Navigate, Read, Multi-calculation and Data items from the start of the Get Details page of your SA
Training - Account Notes Business Object.
• Add two expressions to the new Multi-calculation stage to calculate the Start Y and End Y Data Items.
• Use these Data Items as dynamic attribute values for a Global Mouse Click Centre in the new Navigate
stage.
• As with any navigation, in practice we would use a Wait stage to confirm that the expected effect took
place, but for the purpose of this exercise we will do without.
• Take a moment to experiment with the Notes list and try different (manual) keystrokes and mouse clicks to
learn about how this list behaves.
• Add a new Navigate stage to do a Global Mouse Click Centre on the button region.
• Connect your new pieces to make you diagram look like below. The idea is that after reading the 12 row we
stop incrementing Start Y and End Y, so that our regions stay in the twelfth position. We then start to click
the button on each iteration.
• Run your page and you should see that table scrolls and that 20 rows of data are captured in the collection.
• Create a duplicate of the Get Details page y right-clicking on the page tab.
• Open the Navigate stage and delete one of the Global Mouse Click Centre lines, as we only need one here.
Add a new line and drag in the root element to send the {ESCAPE} key. On this training application the
mouse click has the effect of putting the cell into ‘edit mode’, which we don’t want, and the Escape key is
used to undo it.
• Change the other Navigate stage that was used to click the scroll down button. Change it so that it sends
{DOWN} via Global Send Keys.
• Now rearrange the loop so that the Down key is sent on every iteration, like this.
You may have been wondering what the List Region button is for. A list region is basically a repeating coordinate
region and it can make short work of reading a list.
• Create a new element in Application Modeller and spy the main window with Region mode.
• In Region Editor create a list region within the first Agent cell, much in the same way as we have done
before. Notice how when you hover over the region, a repeating series of regions is displayed.
List Direction is easy to understand, and almost always you will use the default, Top Down. The Padding property
however is not quite the same as the image region padding we’ve worked with before. Here, Padding controls the
spacing between the repeating regions.
• Change the Padding property to 5 and then hover over the list region and notice the difference. You should
see that the repeating regions are now separated and sit better over the other rows.
• Like the measurements of a dynamic region, a list region requires precision to work properly. Take time to
adjust the location, the size and the padding of your list region until the repeating regions sit neatly over
the other rows, like this.
And as mentioned earlier, the paging behaviour of an application may not work as neatly as you might expect; note
how in the training application the first Page Down key press does scroll a full page, whereas the subsequent pages
do. Again, dynamic adjustment of the First Element and Last Element inputs might be an ideal solution.
Adjoining Columns
The previous exercise showed the potential for a List Region to read a single column. In this exercise we see how to
join collection columns together.
• Add another Action stage and use the Merge Collection action to generate a third collection.
• Either reuse your Business Object from the basic training course or create a new one.
• Create an image region around the MPRN column header with an exaggerated Right padding.
• Create a list region around the first MPRN cell, and make the left-hand edge align with the header region
(the Region Editor ‘snap’ feature should help you do this). Adjust the list region so that the repeating
regions site over the rows correctly. Make a mental note of the region’s width (it should be about 75).
• In Object Studio, add a Read stage to extract the run time location of the MPRN Header region (i.e. Get
Bounds).
• Add another Read stage to perform Recognise Text in Range on the MPRN Cell region. Use the Bounds
collection output of the first Read as input to the second Read.
• Run the page, and you should find that the 9 cells in the column are read.
• Now load the 5.1.22b.png image and note that the columns are slightly different. Run the page again and
you should find that the column can still be read.
Identifying Fonts
When identifying system fonts, we have used the Automatic tab that allows Blue Prism to return the best matches.
From this you can select and test the returned fonts to determine the most appropriate. If no fonts are returned,
you can use the Manual tab to return samples from all available system fonts and manually select one.
Qualifying Fonts
Irrespective of whether the font was found automatically or manually, an important part of the interface
configuration is to qualify the font. This means proving all upper and lower case letters, numbers and symbols
match correctly. This may not always be possible, and workarounds may be required (see Character Conflicts
below).
Key Points
• Read as much text from labels as you can to provide a wide selection of alphanumeric characters and
symbols.
• Find an area of the application where you can enter text (e.g., note field or large input box) and read it
within Blue Prism to confirm values.
Blue Prism separates the distinct values and presents them to you so that you can set the characters. Above each
character is an input box for you to type the character and then click Merge Into Font.
Font Files
Once a font has been qualified, it can be exported to other Blue Prism Resources via a Blue Prism font file. You can
export a font to a font file in System Manager or as part of a Blue Prism Release. This allows your font to be
migrated to other Blue Prism Resources.
Character Conflicts
As you may have seen in the table reading exercises, Recognise Text can yield strange results. This occurs when the
application font contains characters that are visually identical. Commonly upper case ‘i' and lower case ‘L’ are
represented by and identical vertical line of pixels, although in our previous example it is the number 1 and the
lower case ‘L’ that are indistinguishable.
Although this is no problem for a human to interpret, a robot needs rules. The rules you implement to resolve
character conflicts will depend entirely on the context of your character recognition. For instance, if you know that
a field can only contain digits, then you can replace any misplaced letters with their conflicting digits. But if the field
does not have any such inbuilt restriction, it becomes harder to be certain what substitutions are required. You
could ‘clean’ the Recognise Text result using regular expressions, but you would need to be sure of the rules you
apply. Below is an example from a code stage to apply English rules.
‘A single l is probably an I
Unclean= Regex.Replace(Unclean, "(\b)l(\b)", "$1I$2")
• There are no universal rules for resolving character conflicts, and you will need to thoroughly test any logic
you implement.
6.2 Performance
As mentioned at the start of this course, Surface Automation is all about interpreting images at pixel level. As such,
it is beneficial to understand that the choice of image can have an impact on performance. Blue Prism locates a
smaller image within a bigger image by moving from pixel to pixel in both images, looking for a match, so it can be
useful to imagine how many pixels will need to be compared.
Recall from the basic training course we imagined an application with a single button. We used padding around an
image region to define an area where the run time location of the button might be found.
But if all we want to do is click the button, could we economise on the number of pixel checks Blue Prism will need
to make? For example, does the region need to surround the whole button? Could it not be tighter around the
word OK to make the image (and the number of pixels to compare) smaller? Does it even need to cover the whole
word?
Consider the Notes table, and suppose we wanted to know which row was currently selected? We could simply
make an image region in the orange highlighting and then select the ‘Anywhere’ padding option. Again, that would
work but we’d be making the search algorithm work unnecessarily hard (and slower). It would be more economic
to create a 1x1 region with a 1-pixel wide padding left and right and maximum padding top and bottom. We are
only interested in the vertical position of the highlighted row, so we need only ask Blue Prism to search in a narrow
vertical strip for the first orange pixel it can find.
8 Utilities
There are a couple of utility Business Object that it is useful to be aware of, although the new functionality of Blue
Prism version 6 has made them less vital to a Surface Automation project.
• Utility - Image Manipulation This object comes as standard in your local VBO folder.
• Utility - Image Search This object is available for download from the Portal.
• Regions take on some of the attributes of the parent Win32 element, and these attributes may need
adjustment from the default. We did this with the Window Title attribute to make it a wildcard match.
• Radio Buttons and Checkboxes cannot be read as text, but a Wait stage can be used to detect their
condition.
• Wait stages can also be used to detect, and wait for, a difference between a design time image and it’s run
time equivalent. This is how Surface Automation can keep pace with the state of an application.
• There are many varieties of combo box and drop-down lists, each with their own behaviour. As such there
is no single method of integration and the developer must be prepared to find the ideal technique, which
may be a combination of keystrokes, mouse clicks and Read stages.
• The behaviour of scrolling tables and lists is also idiosyncratic, and there are multiple techniques for
reading and navigating them.
• A ‘dynamic’ region can be used to travel down a list, or a ‘list region’ can be used to make a repeating
sequence of regions. Both require pixel level precision.
• Bespoke font definitions can be created from screenshots when necessary.
• Some characters in some fonts are visually identical, and such ‘character conflicts’ require logical
interpretation. Capital i and lower-case L are a classic example.
• Image searching and matching is achieved through pixel-by-pixel comparison, and the size of a region and
its search area can impact on performance. The Surface Automation developer should always have
efficiency in mind.
• The image utility Business Objects used in versions 5 and 4 are still useful and should not be disregarded.
SA Training – Log In
Action Start Screen End Screen Inputs Outputs
Launch Log In
Log In Log In Account Details User Name
Password
(password)
System
Close Log In
SA Training –Note
Action Start Screen End Screen Inputs Outputs
Get Details View Note View Note Name
Type
Note
Set Details Add Note Add Note Name
Type
Note
Close (OK) Add Note Account Notes
Close (Cancel) Add Note or View Account Notes
Note
The plus sign +, caret ^, percent sign %, tilde ~, and parentheses () have special meanings and to specify one of
these characters, curly brackets {} must be used. For example, to specify the plus sign, use {+}. To specify a curly
bracket character, enclose it in other curly brackets, like {{} or {}}. And although square brackets have no special
meaning, they too must be enclosed in curly brackets, eg {[}.
To specify characters that aren't displayed when you press a key, such as ENTER or TAB, and keys that represent
actions rather than characters, use the codes in the following table:
Key Code
BACKSPACE {BACKSPACE}, {BS}, or {BKSP}
BREAK {BREAK}
CAPS LOCK {CAPSLOCK}
DEL or DELETE {DELETE} or {DEL}
DOWN ARROW {DOWN}
END {END}
ENTER {ENTER} or ~
ESC {ESC}
HELP {HELP}
HOME {HOME}
INS or INSERT {INSERT} or {INS}
LEFT ARROW {LEFT}
NUM LOCK {NUMLOCK}
PAGE DOWN {PGDN}
PAGE UP {PGUP}
PRINT SCREEN {PRTSC}
RIGHT ARROW {RIGHT}
SCROLL LOCK {SCROLLLOCK}
TAB {TAB}
UP ARROW {UP}
F1 {F1}
F2 {F2}
F3 {F3}
F4 {F4}
F5 {F5}
F6 {F6}
F7 {F7}
F8 {F8}
To specify keys combined with any combination of the SHIFT, CTRL, and ALT keys, precede the key code with one or
more of the following codes:
Key Code
SHIFT +
CTRL ^
ALT %
To specify that any combination of SHIFT, CTRL, and ALT should be held down while several other keys are pressed,
enclose the code for those keys in parentheses. For example, to specify to hold down SHIFT while E and C are
pressed, use +(EC). To specify to hold down SHIFT while E is pressed, followed by C without SHIFT, use +EC.
To specify repeating keys, add a number inside the curly brackets, for example {LEFT 4} means send the LEFT
ARROW key four times; {h 10} means send h ten times.
If Send Keys does not work with your application, Send Key Events should be tried instead (see below).
Send Key Events can be thought of as using a keyboard – for ‘a’ press the A key, for ‘B’ hold SHIFT and press the B
key. Like Global Send Keys, curly brackets are used for special keys like {HOME} and {DELETE}.
By default, keys are sent as a ‘press down and release’ instruction. The less than < and greater than > characters
are used to modify the proceeding instruction to be a ‘key down and hold’ or ‘key up’, e.g. <{SHIFT}b>{SHIFT} for
‘hold SHIFT, press B then release SHIFT, i.e. B.
Critical Point
• Care should always be taken with the syntax of Send Key Events. A down keystroke for special keys must
always be followed by a corresponding up keystroke.
Description
A The A key.
Add The add key.
Alt or ALT The ALT modifier key.
Apps The application key (Microsoft Natural Keyboard).
Attn The ATTN key.
B The B key.
Back The BACKSPACE key.
BrowserBack The browser back key (Windows 2000 or later).
BrowserFavorites The browser favorites key (Windows 2000 or later).
BrowserForward The browser forward key (Windows 2000 or later).
BrowserHome The browser home key (Windows 2000 or later).
BrowserRefresh The browser refresh key (Windows 2000 or later).
BrowserSearch The browser search key (Windows 2000 or later).
BrowserStop The browser stop key (Windows 2000 or later).
C The C key.
Cancel The CANCEL key.
Capital The CAPS LOCK key.
CapsLock The CAPS LOCK key.
Clear The CLEAR key.
Control or CTRL The CTRL modifier key.
ControlKey The CTRL key.
Crsel The CRSEL key.