excel utilities · 2020-03-31 · the excel utilities bot can be used directly in a calling atmx...

Excel Utilities

Readme

Version 1.0

29/01/2020

Table of Contents

of 42

Table of Contents

1. Introduction .............................................................................................................. 3

1.1 Overview ........................................................................................................... 3 1.2 Common Use cases .......................................................................................... 4

2. Requirements & Prerequisites ................................................................................ 5

2.1 System Requirements ....................................................................................... 5 2.2 Prerequisites ..................................................................................................... 5

2.3 Security Measures ............................................................................................ 5

2.4 Disclaimers ....................................................................................................... 5

3. Getting Started ......................................................................................................... 6

3.1 Skill Matrix ........................................................................................................ 6 3.2 Installation Hierarchy ........................................................................................ 6

3.3 Quick Start ........................................................................................................ 6 3.3.1 Setup .......................................................................................................... 6 3.3.2 Configuration .............................................................................................. 6

4. Reports ................................................................................................................... 37

5. Logs ........................................................................................................................ 38

6. Troubleshooting & Support .................................................................................. 39

6.1 Support ........................................................................................................... 39

6.2 FAQs ............................................................................................................... 39

Appendix A: Record of Changes ............................................................................... 40

Appendix B: Acronyms ............................................................................................... 41

Appendix C: References ............................................................................................. 42

of 42

1. Introduction

This document contains all the essential information for the user to make full use of the Excel Utilities bot. This manual includes a description of the functions and capabilities and step-by-step procedures for setup & configuration of the Bot.

1.1 Overview

Automation Anywhere provides users with a rich set of features for extracting and manipulating data within an excel workbook; however, there is a gap when it comes to the full formatting features of the Excel Application. The Excel Utilities bot fills this gap by allowing users to create new workbooks, edit workbook properties (New Sheets, renaming sheets), worksheet properties (Inserting rows, columns columns), format worksheets (Cell colour, font etc.), image extraction/insertion and Pivot table helpers. Excel Utilities bot also does not require the Excel application to be installed on the machine the bot is running on.

Create WorkbookNew Excel Workbook

Excel Utilities Bot – New Workbook Actions

of 42

Set Workbook Instance

Save Workbook

Save Workbook As

Workbook Excel Helpers

Worksheet Excel Helpers

Formatting Excel Helpers

Pivot Excel Helpers

Image Excel Helpers

Another Action?

Yes

No

Excel Utilities Bot – Existing sheet actions

1.2 Common Use cases

Common use cases for the Excel Utilities bot include where situations where new workbooks need to be created, output for reports needs to be formatted for consumption and additional functionality involving pictures and pivot tables. The Excel Utilities bot is also key for situations where there are licensing issues for installing office applications on virtual machines, as it can create the excel output without Excel installed.

of 42

2. Requirements & Prerequisites

2.1 System Requirements

The Excel Utilities bot should work on all systems with the minimal hardware specification for the AA Client installation.

2.2 Prerequisites

The Excel Utilities bot has been successfully tested with Automation Anywhere v11.3.x. Feel free to report any issues with other versions, and the developers will happily adjust to support other versions wherever possible.

2.3 Security Measures

N/A

2.4 Disclaimers

N/A

of 42

3. Getting Started

3.1 Skill Matrix

N/A

3.2 Installation Hierarchy

The Excel Utilities bot itself will not generate any new folders.

3.3 Quick Start

The Excel Utilities bot is contained within the “My Metabots” folder and will need to be copied into the main “My Metabots” folder. There is a sample task called MasterBot.atmx which will demo the metabot.

3.3.1 Setup

The Excel Utilities bot can be used directly in a calling atmx task.

3.3.2 Configuration

The Excel Utilities bot can be run independently of external config files or the credential vault. There are 5 groupings of logic within the metabot:

1. Workbook Excel Helpers

2. Worksheet Excel Helpers

3. Formatting Excel Helpers

4. Image Excel Helpers

5. Pivot Excel Helpers

3.3.2.1 CreateNewWorkbook

Creates a new Excel Workbook in the provided workbook path with a default sheet named "Sheet1"

Folder: Workbook Excel Helpers

Name Type Description

$vWorkbookFilePath$ Input Name of workbook to be

creating including full path e.g.

C:\Example\Test.xlsx

3.3.2.2 CreateNewWorkbookWithNamedSheet

Creates a new Excel Workbook with a user defined sheet name

of 42



$vWorkbookFilePath$ Input Name of workbook to be

creating including full path e.g.


$vWorksheetName$ Input Name of worksheet to add to

new workbook

3.3.2.3 CreateNewWorkbookWithNamedSheets

Creates a new Excel Workbook with multiple user defined worksheet names



3.3.2.4 AddWorksheetToWorkbook

Adds a new Worksheet to an existing Workbook



$vWorksheetName$ Input Name of worksheet to add to

existing workbook

3.3.2.5 AddWorksheetsToWorkbook

Adds multiple new Worksheets to an existing Workbook



$arrWorksheetName$ Input Name of Worksheets to add to

existing Workbook

3.3.2.6 RemoveWorksheetFromWorkbook

Removes a Worksheet from a Workbook


of 42


$vWorksheetName$ Input Name of Worksheet to remove

from Workbook

3.3.2.7 MoveWorksheetByName

Moves a named Worksheet to a new position



$vWorksheetName$ Input Name of Worksheet to rename

in Workbook

$vWorksheetPosition$ Input Position to move existing

Worksheet to e.g. 2

3.3.2.8 MoveWorksheetByPosition

Moves a Worksheet by ordinal position to a new position



$vWorksheetPosition$ Input Position to move existing

Worksheet to e.g. 2

$vWorksheetNewPosition$ Input Position of existing Worksheet

to move e.g. 1

3.3.2.9 RenameExistingWorksheet

Renames an existing worksheet with the provided text



$vWorksheetName$ Input Name of Worksheet to rename

in Workbook

$vNewWorksheetName$ Input Worksheet name to rename

existing Worksheet to

of 42

3.3.2.10 ChangeWorksheetTabColour

Changes a Worksheet tab colour



$vWorksheetName$ Input Name of existing Worksheet in

Workbook

$vTabColour$ Input Colour to Worksheet change

tab to e.g. Red

3.3.2.11 ChangeWorksheetVisibilty

Changes Worksheet Visibility (default is Visible)




Workbook

$vVisibilityOption$ Input Change Worksheet Visibilty

Option: Visible, Hidden,

VeryHidden

3.3.2.12 CopyWorksheetToANewWorkbook

Copy a Worksheet into a new Workbook



$vSourceWorksheetName$ Input Name of existing Worksheet in

source Workbook

$vTargetWorkbookFilePath$ Input Full file path to existing target

Excel Workbook e.g.


$vTargetWorksheetName$ Input Name of existing Worksheet in

target Workbook

of 42

3.3.2.13 CopyWorksheetToAnotherWorkbook

Copies a Worksheet from one Workbook to another



$vSourceWorksheetName$ Input Name of existing Worksheet in

source Workbook

$vTargetWorkbookFilePath$ Input Full file path to existing target

Excel Workbook e.g.


$vTargetWorksheetName$ Input Name of existing Worksheet in

target Workbook

3.3.2.14 AddAutoFilter

Add autofilter to worksheet

Folder: Worksheet Excel Helpers



Workbook

3.3.2.15 AddCellComment

Add comment to cell on worksheet




Workbook

$vCommentText$ Input Text for in cell comment

$vCell$ Input Cell to add comment to e.g. A1

3.3.2.16 AddColumns

Adds a number of columns


of 42



Workbook

$vColsToInsert$ Input Number of columns to insert

e.g. 3

$vStartColumn$ Input Column position to insert new

columnsfrom e.g. D

$vInsertAfter$ Input value to determine if columns

should be inserted after or

before startring column

poosition e.g. true

3.3.2.17 AddRows

Inserts a given number of rows to an Excel Worksheet




Workbook

$vInsertBelow$ Input value to determine if rows

should be inserted before or

after starting row position e.g.

true

$vRowsToInsert$ Input Number of rows to insert e.g. 3

$vStartRow$ Input Row position to insert new

rows from e.g. 2

3.3.2.18 CreateExcelTableFromRange

Create an excel table from a given range




Workbook

$vTableName$ Input Name to give excel table

of 42

$vTheme$ Input Theme for excel table e.g.

TableStyleDark1

$vDataRange$ Input range of table data e.g. A1:H10

3.3.2.19 CreateExcelTableByUsedRange

Create an excel table from the worksheet used range




Workbook

$vTableName$ Input Name to give excel table


TableStyleDark1

3.3.2.20 DeleteColumns

Deletes columns from worksheet




Workbook

$vColumnsToDelete$ Input Column letters to delete e.g. A,

F:G

3.3.2.21 DeleteRows

Deletes rows from worksheet




Workbook

$vRowsToDelete$ Input Row numbers to delete e.g. 2,

7:8

of 42

3.3.2.22 GetFormula

Gets forumula from a cell




Workbook

$vCell$ Input Cell to set formula to e.g. A1

$vFormula$ Output Formula of cell in string format

3.3.2.23 GetLastColumnUsed

Returns last used column on worksheet




Workbook

$vLastColumnUsed$ Output Letter of the last column used

ont he sheet

3.3.2.24 GetLastRowUsed

Returns last used row on worksheet




Workbook

$vLastRowUsed$ Output Number of the last row used

ont he sheet

3.3.2.25 GetUsedRange

Returns used range on worksheet

of 42




Workbook

$vUsedRange$ Output Used range of the worksheet

3.3.2.26 GetValue

Returns cell value




Workbook

$vCell$ Input Cells to get value of e.g. A1

$vValue$ Output value of cell

3.3.2.27 HideColumns

Hides columns on worksheet




Workbook

$vColumnLetters$ Input Column letters to hide e.g.

A,F:G

3.3.2.28 HideRows

Hides rows on worksheet




Workbook

of 42

$vRowNumbers$ Input Row Numbers to hide e.g.

2,4:5

3.3.2.29 SetColumnWidth

Sets width of columns on worksheet




Workbook

$vColumnLetters$ Input Colunn letters to resize e.g. A,

D:E

$vColumnWidth$ Input Width value for column e.g. 50

3.3.2.30 SetFormula

Sets cell formula




Workbook

$vCell$ Input Cell to set formula to e.g. A1

$vFormula$ Input formula to set e.g. A1+5 (Does

not require = but can be

included)

3.3.2.31 SetFormulas

sets formula on range




Workbook

of 42

$vFormula$ Input formula to set e.g. A1+5 (Does

not require = but can be

included)

$vRange$ Input Ranges to set formula to e.g.

A1,B1:B2

3.3.2.32 ProtectWorksheet

Adds sheet protection with flags




Workbook

$vWorksheetPassword$ Input Password for worksheet, leave

blank to not set

$vSetAutoFilter$ Input Flag if user is allowed to set

autofilter when protected e.g.

false

$vSetDeleteColumns$ Input Flag if user is allowed to delete

columns when protected e.g.

false

$vSetDeleteRows$ Input Flag if user is allowed to delete

rows when protected e.g. false

$vSetFormatCells$ Input Flag if user is allowed to

format cells when protected

e.g. false

$vSetFormatColumns$ Input Flag if user is allowed to

format columns when

protected e.g. false

$vSetInsertHyperlinks$ Input Flag if user is allowed to

inserthyperlinks when

protected e.g. false

$vSetInsertRows$ Input Flag if user is allowed to insert

rows when protected e.g. false

$vSetSort$ Input Flag if user is allowed to set

sort when protected e.g. false

of 42

$vSetPivotTables$ Input Flag if user is allowed to edit

pivots when protected e.g.

false

$vSetInsertColumns$ Input Flag if user is allowed to insert

columns when protected e.g.

false

$vSetObjects$ Input Flag if user is allowed to edit

objects when protected e.g.

false

$vSetSelectLockedCells$ Input Flag if user is allowed to select

locked cells when protected

e.g. false

$vSetSelectUnlockedCells$ Input Flag if user is allowed to select

unlocked cells when protected

e.g. false

$vSetScenarios$ Input Flag if user is allowed to edit

scenarios when protected e.g.

false

3.3.2.33 SetValue

Sets a value for the given range




Workbook

$vRange$ Input Range of cells to set value to

e.g. A1,G5:H7

$vValue$ Input value to set e.g. 67, =A1

3.3.2.34 SetNamedRange

Sets a named range on worksheet



of 42


Workbook

$vRange$ Input Range of cells to set value to

e.g. A1,G5:H7

$vRangeName$ Input Name to give named range

3.3.2.35 SetRowHeight

Sets the heigh of provided rows




Workbook

$vRowNumbers$ Input Row numbers to resize e.g.

1,5:6

$vRowHeight$ Input Height value for row e.g. 50

3.3.2.36 UnhideColumns

Unhide columns




Workbook

$vColumnLetters$ Input Column letters to unhide e.g.

A,F:G

3.3.2.37 UnhideRows

Unhide rows




Workbook

of 42

$vRowNumbers$ Input Row Numbers to unhide e.g.

2,4:5

3.3.2.38 UnprotectWorksheet

Unprotect a worksheet with password




Workbook

$vWorksheetPassword$ Input Password for worksheet

protection, leave blank if non

has been set

3.3.2.39 AddCellBorder

Adds a cell border with a given colour and line type

Folder: Formatting Excel Helpers



Workbook

$vRange$ Input Range of cells to apply borders

to e.g. A1,G5:H7

$vBorderColour$ Input Colour for cell border e.g. Red,

Aqua

$vBorderLineType$ Input Type of line for border e.g.

DashDot

DashDotDot

Dashed

Dotted

Double

Hair

Medium

of 42

MediumDashDot

MediumDashDotDot

MediumDashed

None

SlantDashDot

Thick

Thin

3.3.2.40 AddCellFill

Adds background colour and patterns to a cell




Workbook

$vRange$ Input Range of cells to apply fill

colouring to e.g. A1,G5:H7

$vBGColour$ Input Colour to fill cell range with

e.g. Red, Aqua

$vPatternColour$ Input Colour to change cell pattern

to e.g. Red, Aqua

$vPattern$ Input Pattern to add to cell range

e.g.

DarkDown

DarkGray

DarkGrid

DarkHorizontal

DarkTrellis

DarkUp

DarkVertical

Gray0625

Gray125

of 42

LightDown

LightGray

LightGrid

LightHorizontal

LightTrellis

LightUp

LightVertical

MediumGray

None

Solid

3.3.2.41 SetCellDateFormat

Sets cell date format




Workbook

$vRange$ Input Range of cells to apply Text

formats to to e.g. A1,G5:H7

$vDateFormat$ Input Date format e.g. yyyy-MMM-

dd

3.3.2.42 SetCellFont

Sets a cell font and defaults to Calibri




Workbook


to e.g. A1,G5:H7

of 42

$vFontName$ Input Name of the font to update

cells to e.g. Calibri

3.3.2.43 SetCellFontAlignment

Sets alignment of cell font e.g. Subscript




Workbook

$vRange$ Input Range of cells to apply

alignment type to e.g.

A1,G5:H7

$vAlignment$ Input Sets alignment type on cell

e.g.

Baseline

Subscript

Superscript

3.3.2.44 SetCellFontBold

Toggles font Bold emphasis




Workbook

$vRange$ Input Range of cells to apply bold

emphasis to e.g. A1,G5:H7

$vBold$ Input Bold emphasis flag e.g. true

3.3.2.45 SetCellHorizontalAlignment

Sets cells horizontal alignment value


of 42



Workbook

$vRange$ Input Range of cells to apply vertical

alignment to to e.g. A1,G5:H7

$vHorizontalAlignmentValue$ Input Type of vertical alignment for

cell e.g.

Center

CenterContinuous

Distributed

Fill

General

Justify

Left

Right

3.3.2.46 SetCellFontUnderline

Sets cell underline type on cell




Workbook


underline emphasis to e.g.

A1,G5:H7

$vUnderline$ Input Sets underline type on cell e.g.

Double

DoubleAccounting

None

Single

SingleAccounting

of 42

3.3.2.47 SetCellFontStrikethrough

Sets the given ranges font to strikethrough




Workbook



A1,G5:H7

$vStrikethrough$ Input StrikeThrough flag e.g. true

3.3.2.48 SetCellFontSize

Sets cell font size




Workbook

$vRange$ Input Range of cells to apply font

formatting to to e.g. A1,G5:H7

$vFontSize$ Input Font Size to format cell e.g. 11.

Will default to 11

3.3.2.49 SetCellFontItalic

Toggles font Italic emphasis




Workbook

$vItalic$ Input Italic emphasis flag e.g. true

of 42

$vRange$ Input Range of cells to apply italic

emphasis to e.g. A1,G5:H7

3.3.2.50 SetCellFontColour

Changes Colour of font in a given range




Workbook


to e.g. A1,G5:H7

$vFontColour$ Input Colour to apply to font within

range with e.g. Red, Aqua

3.3.2.51 SetCellNumberFormat

Sets cell number format




Workbook



$vNumberFormat$ Input Number format ID e.g. $

#,##0.00

3.3.2.52 SetCellProtection

Sets cell protection attribute




Workbook

of 42



A1,G5:H7

$vProtect$ Input Protect cell flag e.g. true

3.3.2.53 SetCellTextDirection

Sets text direction of cell




Workbook



$vTextDirectionValue$ Input Type of text rotation for cell

e.g.

ContextDependent

LeftToRight

RightToLeft

3.3.2.54 SetCellTextRotation

Set text rotation value for cell




Workbook



$vTextRotationValue$ Input Number of degrees to rotate

cell text e.g. 90

of 42

3.3.2.55 SetCellVerticalAlignment

Sets cells vertical alignment value




Workbook

$vVerticalAlignmentValue$ Input Type of vertical alignment for

cell e.g.

Bottom

Center

Distributed

Justify

Top

$vRange$ Input Range of cells to apply vertical

alignment to to e.g. A1,G5:H7

3.3.2.56 SetCellWrapText

Toggles Cell wrap text value




Workbook



$vWrapTextValue$ Input Wrap text flag e.g. true

3.3.2.57 CreatePivotTable

Creates a pivot table

Folder: Pivot Excel Helpers


of 42

$vDataWorksheetName$ Input Name of existing Worksheet in

Workbook with data

$vPivotWorksheetName$ Input Name of sheet to create pivot

on

$vDataRange$ Input Range of data for pivot e.g.

A1:H7

$vPivotName$ Input Name to give to pivot table

$vPivotStartCol$ Input Pivot Starting Column e.g. 3

$vPivotStartRow$ Input Starting row of pivot table

$vPivotRows$ Input Data to show on pivot row

$vPivotColumns$ Input Data to show on pivot column

$vPivotValues$ Input Data to show as values on

pivot

3.3.2.58 SetPivotBandedColumns

Toggles banded columns attribute




Workbook


$vBandedColumns$ Input Flag for banded columns on a

pivot table e.g. true

3.3.2.59 SetPivotBandedRows

Toggles banded rows attribute




Workbook


of 42

$vBandedRows$ Input Flag for banded rows on a

pivot table e.g. true

3.3.2.60 SetPivotLayout

Set pivot layout style




Workbook


$vPivotLayout$ Input change layout of pivot table

e.g.

Outline

Tabular

Compact

3.3.2.61 SetPivotShowBlanks

Toggle to show blank rows




Workbook


$vShowBlankRows$ Input Flag for Showing blank rows on

a pivot table e.g. true

3.3.2.62 SetPivotShowColumnHeaders

Toggle column headers


of 42



Workbook


$vShowColumnHeaders$ Input Flag for Showing column

headers on a pivot table e.g.

true

3.3.2.63 SetPivotShowColumnsGrandTotal

Toggle Column grand total




Workbook


$vShowGrandTotalColumns$ Input Flag for Showing column grand

totals on a pivot table e.g. true

3.3.2.64 SetPivotShowRowHeaders

Toggle Row Headers




Workbook


$vShowRowHeaders$ Input Flag for Showing row headers

on a pivot table e.g. true

3.3.2.65 SetPivotShowRowsGrandTotal

Toggle Row Grand Totals


of 42



Workbook


$vShowRowGrandTotals$ Input Flag for Showing grand totals

on a pivot table e.g. true

3.3.2.66 SetPivotSubTotalType

Toggle sub total type




Workbook


$vSubTotalType$ Input Sets type of sub total e.g.

DoNotShow

AtTop

AtBottom

3.3.2.67 SetPivotTheme

Set pivot table theme




TableStyleDark1


Workbook


of 42

3.3.2.68 AddColumnToPivotTable

Add a column to an existing pivot table


Variable Name Type Description

$vWorksheetName$ Input Name of existing Worksheet in Workbook


$vPivotCol$ Input Data to add as a column on pivot

3.3.2.69 AddRowToPivotTable

Add a row to an existing pivot table





$vPivotRow$ Input Data to show as a row on pivot

3.3.2.70 AddValueToPivotTable

Add a value to an existing pivot table





$vPivotValue$ Input Data to show as a value on pivot

3.3.2.71 RemoveColumnOnPivotTable

Remove a column from an existing pivot table


of 42




$vPivotCol$ Input Data to remove as a column on pivot

3.3.2.72 RemoveRowOnPivotTable

Remove a row from an existing pivot table





$vPivotRow$ Input Data to remove as a row on pivot

3.3.2.73 RemoveValueOnPivotTable

Remove a value from an existing pivot table





$vPivotValue$ Input Data to remove as a value on pivot

3.3.2.74 AddFilterToPivotTable

Adds a filter to an existing pivot table




of 42


$vPivotFilter$ Input Data to add as a filter on pivot

3.3.2.75 RemoveFilterOnPivotTable

Removes a filter on an existing pivot table





$vPivotFilter$ Input Data to remove as a filter on pivot

3.3.2.76 GetImagesFromWorkbook

Extract all images from a workbook

Folder: Image Excel Helpers


$vImageDownloadPath$ Input Path to download all images to

3.3.2.77 InsertImageToWorksheet

Inserts an image to a worksheet



$vWorksheet$ Input Name of the excel worksheet

e.g. Sheet1

$vImagePath$ Input Full path to image to insert

into excel e.g. D:\Test\test.png

$vCell$ Input Reference to cell to insert

image at e.g. A1

of 42

3.3.2.78 GetImageFromWorksheetByTopLeftCell

Downloads image defined by top left cell position



$vWorksheet$ Input Name of the excel worksheet

e.g. Sheet1

$vImageDownloadPath$ Input Path to download all images to

$vImageTopLeftCell$ Input Top left most cell of image on

worksheet e.g. A1

3.3.2.79 SaveWorkbook

Save changes to the workbook

Folder:


3.3.2.80 SaveWorkbookAs

Save changes to the workbook as a new file

Folder:


$vNewWorkbookName$ Input Full path to save workbook to

e.g. D:\Test\Test1.xlsx

3.3.2.81 SetWorkbookInstance

Set instance of workbook to edit

Folder:


$vWorkbookName$ Input Full path to the closed Excel

document

of 42

e.g. D:\Test\Test.xlsx

3.3.2.82 SetAccessCode

Sets access code provided by automation anywhere to validate paid bot. Recommended to create a

vault credential to hold this value. Must be set before other logics can be used

Folder:


$vAccessCode$ Input The access code provided by

automation anywhere to

validate paid bot.

Recommended to create a

vault credential to hold this

value.

of 42

4. Reports

N/A

of 42

5. Logs

N/A

of 42

6. Troubleshooting & Support

6.1 Support

For any feedback, including improvement suggestions, please contact [email protected]. Any feedback is (more than) welcome!

6.2 FAQs

6.2.1.1 Does this metabot require the application to be installed?

No, the metabot uses the OpenXML format and does not require an installation of Excel on the target machine reducing the cost of office licensing.

6.2.1.2 Can styles be applied to multiple ranges at once?

Yes, the majority of the logics that apply changes to cells, unless stated, will allow for multiple non contiguous ranges to be used, for example “A1,B7:B19,F1:H10”

6.2.1.3 Can this be used on open workbooks?

No, as the underlying XML is changed using OpenXML, the workbook will need to be shut whilst the metabot is updating it.

6.2.1.4 Is the bot reliable?

Yes, the metabot is 100% reliable as it uses the OpenXML format and so does not require the use of any keystrokes etc.

of 42

Appendix A: Record of Changes

No. Version Number Date of Change Author Notes

1 1.0 29/01/2020 Paul Hawkins Initial Submission to Bot Store

of 42

Appendix B: Acronyms

No. Acronym Description

of 42

Appendix C: References

No. Topic Reference Link

excel utilities · 2020-03-31 · the excel utilities bot can be used directly in a calling atmx...

Documents