Use this section to look up information on steps, helper functions and run options you can use. You can explore using the navigation headers.
The steps you can use in TagUI are listed here.
Mouse and keyboard¶
click Main concepts click //nav/div/div/ul/li/ul/li/a click (500,200) click button.png
See click for examples.
See click for examples.
See click for examples.
type [DOM/XPath/Point/Image] as [text to type]
type search-term as John Wick type //input[@name="search"] as John Wick type (500,200) as John Wick type input_field.png as John Wick type search-term as [clear]John Wick[enter] type //input[@name="search"] as [clear]John Wick[enter] type (500,200) as [clear]John Wick[enter] type input_field.png as [clear]John Wick[enter]
Enters keystrokes directly.
You can use the following special keys:
- [shift] [ctrl] [alt] [win] [cmd] [enter]
- [space] [tab] [esc] [backspace] [delete] [clear]
- [up] [down] [left] [right] [pageup] [pagedown]
- [home] [end] [insert] [f1] .. [f15]
- [printscreen] [scrolllock] [pause] [capslock] [numlock]
keyboard [win]run[enter] keyboard [printscreen] keyboard [ctrl]c keyboard [tab][tab][tab][enter] keyboard [cmd][space] keyboard safari[enter] keyboard [cmd]c
Visits the provided URL.
select [DOM/XPath of select input element] as [option value or text]
select variant as blue
Saves table data to a csv file, base on the table number on webpage or its XPath identifier.
table [table number] to [filename.csv] table [XPath] to [filename.csv]
table 1 to regional_exchange_rates.csv table (//table) to global_exchange_rates.csv table //table[@name='report'] to report.csv
Modifies the next steps to be run in a new tab.
popup [unique part of new tab's URL] [steps]
popup confirm click Confirm
Modifies the next steps to use the DOM or XPath in a frame or subframe.
frame [frame name] [steps] frame [frame name] | [subframe name] [steps]
frame navigation click Products frame main | register click Register
download to [folder location]
upload [DOM of upload element] as [filename]
upload #element_id as report.csv
Call a web API and save the raw response to the variable
If the response is in JSON,
api_json will automatically be created.
api https://api.github.com/repos/kelaberetiv/TagUI/releases echo `api_result` author = api_json.author.login
Perform read, write, copy, delete actions on Excel files using standard Excel formula like this one
[workbook]sheet!range. This feature works with both Windows and Mac Excel apps. See this link for notes of passed test cases and known limitations for this feature. To access a password-protected Excel file, use
excel_password = 'password'.
You can use variables in your Excel formula, for eg
[`workbook`.xlsx]`sheet`!`range` = 123 data = [`workbook`.xlsx]`sheet`!`range`
By default, the Excel app will be opened and run in the background. If you want the automated actions on Excel to be in focus in foreground, you can set it with
excel_focus = true in your workflow. Use
excel_focus = false to set it off again in your workflow.
For some usage scenarios, you might not even want the Excel app to be visible in the background. In that case, you can set
excel_visible = false in your workflow to run Excel invisibly. Use
excel_visible = true to make Excel visible again in your RPA workflow.
Read data from Excel files. Both relative and absolute file paths supported. Error will be shown if the specified file or sheet does not exist. In below line, range can be a cell or range in Excel.
variable = [workbook]sheet!range
Reading columns and rows can be done using standard Excel formula for range, for example A:A (column A), B:D (columns B to D), 2:2 (row 2), 3:5 (rows 3 to 5). There is no standard Excel formula for selecting the entire range of a sheet, so you will have to provide the actual range required.
top_profit = [Monthly Report.xlsx]August!E10 top_salesman = [Monthly Report.xlsx]August!E11 data_array = [Quarterly Metrics.xlsx]Main!B3:G100 data_array = [C:\Reports\June.xls]Sheet1!A1:C2 data_array = [C:\Reports\June.xls]Sheet1!A:A data_array = [C:\Reports\June.xls]Sheet1!B:D data_array = [C:\Reports\June.xls]Sheet1!2:2 data_array = [C:\Reports\June.xls]Sheet1!3:5
// to work on data in data_array cell by cell for row from 0 to data_array.length-1 for col from 0 to data_array[row].length-1 echo `data_array[row][col]`
Note - There was a limitation on reading multiple rows and columns, for eg B:D and 3:5 (data array returned will be a 1 x N array instead of the correct row x column array). This is now fixed in v6.87. Get your copy with
tagui update command or from MS Word Plug-in
Update TagUI button.
Write data to Excel files. Both relative and absolute file paths supported. If the specified file does not exist, a new file will be created. If the sheet does not exist, a new sheet will be created. If the data is an array, the given cell will be used as the top-left cell to write the range of cells.
[workbook]sheet!cell = variable
[Monthly Report.xlsx]August!E10 = 12345 [Monthly Report.xlsx]August!E11 = "Alan" [Monthly Report.xlsx]August!E12 = variable [Quarterly Metrics.xlsx]Main!B3 = data_array
// to assign a set of range data with 2 rows of 3 columns [C:\Reports\June.xls]Sheet1!A1 = [[1, 2, 3], [4, 5, 6]] [C:\Reports\June.xls]Sheet1!A1 = [[variable_1, variable_2, variable_3], [4, 5, 6]] // example spreadsheet data with #, name and country [Participants.xlsx]Sheet1!A1 = [['1', 'John', 'USA'], [2, 'Jenny', 'Russia'], [3, 'Javier', 'Serbia']] // get the next row count for the example spreadsheet column_A = [Participants.xlsx]Sheet1!A:A next_row = column_A.length + 1 // write a new row accordingly to example spreadsheet [Participants.xlsx]Sheet1!A`next_row` = [[next_row, 'Janice', 'Brazil']]
Copy data across Excel files. Both relative and absolute file paths supported. Error will be shown if the specified source file or sheet does not exist. If the specified destination file does not exist, a new file will be created. If the destination sheet does not exist, a new sheet will be created. If the data is an array, the given cell will be used as the top-left cell to write the range of cells.
[workbook]sheet!cell = [workbook]sheet!range
[Monthly Report.xlsx]August!A1 = [Jennifer Report.xlsx]August!A1 [Monthly Report.xlsx]August!A1 = [Jennifer Report.xlsx]August!A1:E200
Delete data in Excel files. Both relative and absolute file paths supported. Error will be shown if the specified file or sheet does not exist. Delete a range of cells by assigning an empty array to it.
[workbook]sheet!cell = ""
[Monthly Report.xlsx]August!E10 = "" [Quarterly Metrics.xlsx]Main!A1 = [["", "", ""], ["", "", ""]]
You can read the text contents of a PDF file simply by assigning its filename to a variable as follows. TagUI will automate the PDF viewer app to copy out the text contents and assign to the variable. On Windows, you will need the free Adobe Acrobat Reader and set it as your default PDF viewer. On Mac, TagUI will use the default Preview app that can already view PDF files.
Examples for Windows
pdf_text = [Research Report.pdf] pdf_text = [C:\Users\Jennifer\Desktop\Report.pdf] pdf_text = [FY2021 Reports\Research Report.pdf] filename = 'C:\\Users\\Jennifer\\Desktop\\Report' pdf_text = [`filename`.pdf] filename = 'Research Report' pdf_text = [`filename`.pdf]
Examples for Mac
pdf_text = [Research Report.pdf] pdf_text = [/Users/jennifer/Desktop/Report.pdf] pdf_text = [FY2021 Reports/Research Report.pdf] filename = '/Users/jennifer/Desktop/Report' pdf_text = [`filename`.pdf] filename = 'Research Report' pdf_text = [`filename`.pdf]
read [DOM/XPath/Region/Image] to [variable]
When you provide a Region or Image identifier, TagUI uses OCR (Optical Character Recognition) to read the characters from the screen.
read //p[@id="address"] to address read //p[@id="address"]/@class to address-class read (500,200)-(600,400) to id-number read frame.png to email
Saves text to a variable.
[variable] = [value]
count = 5 username = "johncleese" fullname = firstname + lastname
Saves text to a new file.
dump [text] to [filename] dump [`variable`] to [filename]
// creates blank CSV file with header dump First Name,Last Name to names.csv
Saves a new line of text to an existing file.
write [text] to [filename] write [`variable`] to [filename]
write firstname,lastname to names.csv write `fullreport` to report.txt
Loads file content to a variable.
load [filename] to [variable]
load report.txt to report
Shows some output on the command line.
echo [text] echo [`variable`]
echo Flow has started echo The user is `username`
Shows some output on the command line based on a condition.
check [condition] | [text if true] | [text if false]
check header_home_text equals to "Home" | "header text is correct" | "header text is wrong"
js obj = JSON.parse(api_result) dump `obj` to result.json js begin obj = JSON.parse(api_result) randomInteger = Math.floor(Math.random() * Math.floor(5)) + 1 js finish dump `obj` to result.json
Runs Python code and saves the stdout to the variable
py_result as a string.
py [Python statement] py begin [Python statements] py finish
py result = 2 + 3 py print(result) echo `py_result` py begin import random random_integer = random.randint(1,6) print(random_integer) py finish echo `py_result`
See this link for more examples and usage patterns on running Python code.
Runs a command in Command Prompt or Terminal and saves the stdout to the variable
run [shell command]
run cmd /c mkdir new_directory
Runs Sikuli code.
vision [Sikuli statement] vision begin [Sikuli statements] vision finish
Runs code in the browser dom and saves returned value to the variable
// goes back to previous page dom window.history.back() // returns text of an element dom return document.querySelector('#some_id').textContent
Runs R statements and saves the stdout to the variable
r [R statement] r begin [R statements] r finish
Explicitly wait for some time.
wait [seconds to wait] wait [seconds to wait] s wait [seconds to wait] seconds
wait 5.5 wait 10 s wait 20 seconds
Changes the auto-wait timeout when waiting for web elements to appear (default 10 seconds).
timeout [seconds to wait before timeout]
Prompts user for input and saves the input as the variable
ask What is the date of the receipt? (in DD-MM-YYYY) type search as `ask_result`
Run steps interactively and immediately see the output. The user must enter “done” before the flow continues.
Runs another TagUI flow. Checks the flow’s folder.
tagui [flow file] tagui [folder/flow file]
tagui update-forex.tag tagui flows/update-forex.tag
Sends a Telegram notification, for example, to update on automation completion or exception.
First, message @taguibot to authorise it to send messages to your Telegram. Then in TagUI:
telegram [id] [message]
// this line sends message to Telegram user with ID 1234567890, \n means a new line telegram 1234567890 Hello Alena,\n\nYour HR onboarding bot has completed successfully. // show telegram_result variable - 'success' means sent, 'fail' means sending failed echo Telegram message - `telegram_result` // if condition to check telegram_result 'success' or 'fail' and handle accordingly if telegram_result equals to 'success' echo Message sent successfully. else echo Message sending failed.
Note that the telegram step requires an internet connection. This feature is being hosted at https://tebel.org, but the source code is on GitHub if you wish to host this feature on your own cloud or server. The implementation is in pure PHP without any dependencies.
The only info logged is chat_id, length of the message, datetime stamp (to prevent abuse). If you wish to host on your own, first read through this link to learn more about Telegram Bot API, creating your bot API token and setting up the webhook - https://core.telegram.org/bots
You can use the below options when running
For example, the command below runs
my_flow.tag without showing the web browser, while storing the flow run result in
tagui my_flow.tag -headless -report
-deploy or -d¶
Deploys a flow, creating a shortcut which can be double-clicked to run the flow. If the flow file is moved, a new shortcut must be created. The flow will be run with all the options used when creating the shortcut.
-headless or -h¶
Runs the flow with an invisible Chrome web browser (does not work for visual automation).
-nobrowser or -n¶
Runs without any web browser, for example to perform automation only with visual automation.
-report or -r¶
Tracks flow run result in
tagui/src/tagui_report.csv and saves html logs of flows execution.
-turbo or -t¶
Run automation at 10X the speed of normal human user. Read caveats at Advanced concepts!
-quiet or -q¶
Runs without output to command prompt except for explicit output (echo, show, check steps and errors etc). To have fine-grained control on showing and hiding output during execution (eg hiding password from showing up), use
quiet_mode = true and
quiet_mode = false in your flow.
-edge or -e¶
Runs using Microsoft Edge browser instead of Chrome (can be used with -headless option).
Uses the specified csv file as the datatable for batch automation. See datatables.
Add your own parameter(s) to be used in your automation flow as variables p1 to p8.
For example, from the command prompt, below line runs
register_attendence.tag workflow using Microsoft Edge browser and with various student names as inputs.
tagui register_attendence.tag -edge Jenny Jason John Joanne
Inside the workflow, the variables
p4 will be available for use as part of the automation, for example to fill up student names into a web form for recording attendence. The following lines in the workflow will output various student names given as inputs.
echo `p1` echo `p2` echo `p3` echo `p4`
Formats an array for writing to csv file.
read name_element to name read price_element to price read details_element to details write `csv_row([name, price, details])` to product_list.csv
Gets the number of elements matching the identifier specified. Note that the identifier needs to be in single quotes
rows = count('table-rows')
Puts text onto the clipboard, or gets the clipboard text (if no input is given).
clipboard('some text') keyboard [ctrl]v keyboard [ctrl]c contents = clipboard()
Gets the URL of the current web page.
if url() contains 'success' click button1
Gets the title of the current web page.
if title() contains 'Confirmation' click button1
Gets all text content of the current web page.
if text() contains 'success' click button1
Gets the time elapsed in seconds in between each running of this function.
timer() click button1 click button2 click button3 echo `timer()`
falsedepending on whether it exists or not.
if exist('//table') click button1
if present('//table') click button1
Gets the x coordinate of the current mouse position as a number, eg 200.
hover element.png x = mouse_x() + 200 y = mouse_y() click (`x`,`y`)
Gets the y coordinate of the current mouse position as a number, eg 200.
hover element.png x = mouse_x() + 200 y = mouse_y() click (`x`,`y`)
Returns an array of files and folders in a given folder. Both relative and absolute paths supported.
Extracts text between 2 provided anchors from given text. Optional 4th parameter for occurrence during multiple matches (for example 3 to tell the function to return the 3rd match found).
pdf_text = 'Name: John State: Texas City: Plano Contact: ...' name = get_text(pdf_text, 'Name:', 'State:') state = get_text(pdf_text, 'State:', 'City:') city = get_text(pdf_text, 'City:', 'Contact:') echo `name`, `state`, `city`
Cleans data by removing provided character(s) from given text and returning the result.
pdf_text = 'Name: John\n State: Texas\t City: Plano\n Contact: ...' echo `del_chars(pdf_text, '\n\t:')`
Returns the value of given environment variable from the operating system.
// getting %USERPROFILE% variable for Windows echo `get_env('USERPROFILE')` home_dir = get_env('USERPROFILE') // getting $HOME variable for Mac or Linux echo `get_env('HOME')` home_dir = get_env('HOME')