Automagica

Automagica 项目始于 2018 年，旨在开发开源软件，确保机器人流程自动化技术能够惠及所有人。

随着 Automagica 各个版本的发布，诸如 Wand 和 Portal 等更高级的功能需要一套服务基础设施来支持更可靠的机器人运行、先进的服务以及管理和控制功能。

随着这些服务使用量的增加，服务层的托管和维护成本也随之上升。

为了推动这些重要服务进入下一发展阶段，我们很高兴地宣布：2020 年 10月13 日，领先的低代码、客户互动及联络中心软件提供商 Netcall plc 已收购 Oakwood Technologies BV（以“Automagica”名义运营）。

Netcall 将把 Automagica 的 RPA 集成到其 Liberty 平台中，从而提供 RPA、低代码和客户互动解决方案的强大组合。

Automagica Robot 现已不再依据 AGPL3 许可证条款提供。

不过，我们不会停止对已部署机器人的服务支持。这些机器人将继续免费使用 Wand 和 OCR 功能，为期三个月，自今日（2020年10月13日）起算。

现有 Automagica Portal 用户在未来三个月内也可免费访问该平台；在此期间，我们将为用户提供迁移到商业服务的选项。

在此，我们衷心感谢所有为该项目做出贡献的人士。

组件

Automagica 套件由以下组件构成：

• Automagica Bot：负责执行自动化任务的运行时/代理。
• Automagica Flow：可视化流程设计器，可快速构建自动化流程，并全面支持 Python 代码。
• Automagica Wand：基于 AI 的 UI 元素选择器。
• Automagica Lab：基于 Jupyter Notebooks 的笔记本式自动化开发环境（需安装 Jupyter）。
• Automagica Portal：用于管理机器人、凭据、自动化流程、日志等。

示例

浏览器与 Excel 协同工作：

活动

Automagica 所有官方活动概览：

Process	Description
Cryptography	‌‌
Random key	Generate random Fernet key.
Encrypt text	Encrypt text with (Fernet) key,
Decrypt text	Dexrypt bytes-like object to string with (Fernet) key
Encrypt file	Encrypt file with (Fernet) key. Note that file will be unusable unless unlocked with the same key.
Decrypt file	Decrypts file with (Fernet) key
Key from password	Generate key based on password and salt. If both password and salt are known the key can be regenerated.
Hash from file	Generate hash from file
Hash from text	Generate hash from text. Keep in mind that MD5 is not cryptographically secure.
Random	‌‌
Random number	Random numbers can be integers (not a fractional number) or a float (fractional number).
Random data	Generates all kinds of random data. Specifying locale changes format for some options
Random boolean	Generates a random boolean (True or False)
Random name	Generates a random name. Adding a locale adds a more common name in the specified locale. Provides first name and last name.
Random words	Generates a random sentence. Specifying locale changes language and content based on locale.
Random address	Generates a random address. Specifying locale changes random locations and streetnames based on locale.
Random beep	Generates a random beep, only works on Windows
Random date	Generates a random date.
Today's date	Generates today's date.
Generate unique identifier	Generates a random UUID4 (universally unique identifier).
Output	‌‌
Display overlay message	Display custom OSD (on-screen display) message. Can be used to display a message for a limited amount of time. Can be used for illustration, debugging or as OSD.
Print message in console	Print message in console. Can be used to display data in the Automagica Flow console
Browser	‌‌
Chrome	Open Chrome Browser
Save all images	Save all images on current page in the Browser
Browse to URL	Browse to URL.
Find elements by text	Find all elements by their text. Text does not need to match exactly, part of text is enough.
Find all links	Find all links on a webpage in the browser
Find first link on a webpage	Find first link on a webpage
Get all text on webpage	Get all the raw body text from current webpage
Highlight element	Highlight elements in yellow in the browser
Exit the browser	Quit the browser by exiting gracefully. One can also use the native 'quit' function
Find all XPaths	Find all elements with specified xpath on a webpage in the the browser. Can also use native 'find_elements_by_xpath'
Find XPath in browser	Find all element with specified xpath on a webpage in the the browser. Can also use native 'find_elements_by_xpath'
Find class in browser	Find element with specified class on a webpage in the the browser. Can also use native 'find_element_by_class_name'
Find class in browser	Find all elements with specified class on a webpage in the the browser. Can also use native 'find_elements_by_class_name' function
Find element in browser based on class and text	Find all elements with specified class and text on a webpage in the the browser.
Find id in browser	Find element with specified id on a webpage in the the browser. Can also use native 'find_element_by_id' function
Switch to iframe in browser	Switch to an iframe in the browser
Credential Management	‌‌
Set credential	Add a credential which stores credentials locally and securely. All parameters should be Unicode text.
Delete credential	Delete a locally stored credential. All parameters should be Unicode text.
Get credential	Get a locally stored redential. All parameters should be Unicode text.
FTP	‌‌
Create FTP connection (insecure)	Can be used to automate activites for FTP
Download file	Downloads a file from FTP server. Connection needs to be established first.
Upload file	Upload file to FTP server
List FTP files	Generate a list of all the files in the FTP directory
Check FTP directory	Check if FTP directory exists
Create FTP directory	Create a FTP directory. Note that sufficient permissions are present
Keyboard	‌‌
Press key	Press and release an entered key. Make sure your keyboard is on US layout (standard QWERTY).If you are using this on Mac Os you might need to grant access to your terminal application.
Press key combination	Press a combination of two or three keys simultaneously. Make sure your keyboard is on US layout (standard QWERTY).
Type text	Simulate keystrokes. If an element ID is specified, text will be typed in a specific field or element based on the element ID (vision) by the recorder.
Mouse	‌‌
Get mouse coordinates	Get the x and y pixel coordinates of current mouse position.
Display mouse position	Displays mouse position in an overlay.
Mouse click	Clicks on an element based on the element ID (vision)
Mouse click coordinates	Clicks on an element based on pixel position determined by x and y coordinates. To find coordinates one could use display_mouse_position().
Double mouse click coordinates	Double clicks on a pixel position determined by x and y coordinates.
Double mouse click	Double clicks on an element based on the element ID (vision)
Right click	Right clicks on an element based on the element ID (vision)
Right click coordinates	Right clicks on an element based pixel position determined by x and y coordinates.
Move mouse	Moves te pointer to an element based on the element ID (vision)
Move mouse coordinates	Moves te pointer to an element based on the pixel position determined by x and y coordinates
Move mouse relative	Moves the mouse an x- and y- distance relative to its current pixel position.
Drag mouse	Drags mouse to an element based on pixel position determined by x and y coordinates
Drag mouse	Drags mouse to an element based on the element ID (vision)
Image	‌‌
Random screen snippet	Take a random square snippet from the current screen. Mainly for testing and/or development purposes.
Screenshot	Take a screenshot of current screen.
Folder Operations	‌‌
List files in folder	List all files in a folder (and subfolders)
Create folder	Creates new folder at the given path.
Rename folder	Rename a folder
Open a folder	Open a folder with the default explorer.
Move a folder	Moves a folder from one place to another.
Remove folder	Remove a folder including all subfolders and files. For the function to work optimal, all files and subfolders in the main targetfolder should be closed.
Empty folder	Remove all contents from a folderFor the function to work optimal, all files and subfolders in the main targetfolder should be closed.
Checks if folder exists	Check whether folder exists or not, regardless if folder is empty or not.
Copy a folder	Copies a folder from one place to another.
Zip	Zip folder and its contents. Creates a .zip file.
Unzip	Unzips a file or folder from a .zip file.
Return most recent file in directory	Return most recent file in directory
Delay	‌‌
Wait	Make the robot wait for a specified number of seconds. Note that this activity is blocking. This means that subsequent activities will not occur until the the specified waiting time has expired.
Wait for folder	Waits until a folder exists.Note that this activity is blocking and will keep the system waiting.
Word Application	‌‌
Start Word Application	For this activity to work, Microsoft Office Word needs to be installed on the system.
Save	Save active Word document
Save As	Save active Word document to a specific location
Append text	Append text at end of Word document.
Replace text	Can be used for example to replace arbitrary placeholder value. For example whenusing template document, using 'XXXX' as a placeholder. Take note that all strings are case sensitive.
Read all text	Read all the text from a document
Export to PDF	Export the document to PDF
Export to HTML	Export to HTML
Set footers	Set the footers of the document
Set headers	Set the headers of the document
Quit Word	This closes Word, make sure to use 'save' or 'save_as' if you would like to save before quitting.
Word File	‌‌
Read and Write Word files	These activities can read, write and edit Word (docx) files without the need of having Word installed.
Read all text	Read all the text from the document
Append text	Append text at the end of the document
Save	Save document
Save as	Save file on specified path
Set headers	Set headers of Word document
Replace all	Replaces all occurences of a placeholder text in the document with a replacement text.
Outlook Application	‌‌
Start Outlook Application	For this activity to work, Outlook needs to be installed on the system.
Send e-mail	Send an e-mail using Outlook
Retrieve folders	Retrieve list of folders from Outlook
Retrieve e-mails	Retrieve list of messages from Outlook
Delete e-mails	Deletes e-mail messages in a certain folder. Can be specified by searching on subject, body or sender e-mail.
Move e-mails	Move e-mail messages in a certain folder. Can be specified by searching on subject, body or sender e-mail.
Save attachments	Save all attachments from certain folder
Retrieve contacts	Retrieve all contacts
Add a contact	Add a contact to Outlook contacts
Quit	Close the Outlook application
Excel Application	‌‌
Start Excel Application	For this activity to work, Microsoft Office Excel needs to be installed on the system.
Add worksheet	Adds a worksheet to the current workbook
Activate worksheet	Activate a worksheet in the current Excel document by name
Save	Save the current workbook. Defaults to homedir
Save as	Save the current workbook to a specific path
Write cell	Write to a specific cell in the currently active workbook and active worksheet
Read cell	Read a cell from the currently active workbook and active worksheet
Write range	Write to a specific range in the currently active worksheet in the active workbook
Read range	Read a range of cells from the currently active worksheet in the active workbook
Run macro	Run a macro by name from the currently active workbook
Get worksheet names	Get names of all the worksheets in the currently active workbook
Get table	Get table data from the currently active worksheet by name of the table
Activate range	Activate a particular range in the currently active workbook
Activate first empty cell down	Activates the first empty cell going down
Activate first empty cell right	Activates the first empty cell going right
Activate first empty cell left	Activates the first empty cell going left
Activate first empty cell up	Activates the first empty cell going up
Write cell formula	Write a formula to a particular cell
Read cell formula	Read the formula from a particular cell
Insert empty row	Inserts an empty row to the currently active worksheet
Insert empty column	Inserts an empty column in the currently active worksheet. Existing columns will shift to the right.
Delete row in Excel	Deletes a row from the currently active worksheet. Existing data will shift up.
Delete column	Delete a column from the currently active worksheet. Existing columns will shift to the left.
Export to PDF	Export to PDF
Insert data as table	Insert list of dictionaries as a table in Excel
Read worksheet	Read data from a worksheet as a list of lists
Quit Excel	This closes Excel, make sure to use 'save' or 'save_as' if you would like to save before quitting.
Excel File	‌‌
Read and Write xlsx files.	This activity can read, write and edit Excel (xlsx) files without the need of having Excel installed.
Export file to dataframe	Export to pandas dataframe
Activate worksheet	Activate a worksheet. By default the first worksheet is activated.
Save as	Save file as
Save as	Save file
Write cell	Write a cell based on column and row
Read cell	Read a cell based on column and row
Add worksheet	Add a worksheet
Get worksheet names	Get worksheet names
PowerPoint Application	‌‌
Start PowerPoint Application	For this activity to work, PowerPoint needs to be installed on the system.
Save PowerPoint	Save PowerPoint Slidedeck
Save PowerPoint	Save PowerPoint Slidedeck
Close PowerPoint Application	Close PowerPoint
Add PowerPoint Slides	Adds slides to a presentation
Slide count	Returns the number of slides
Text to slide	Add text to a slide
Delete slide	Delete a slide
Replace all occurences of text in PowerPoint slides	Can be used for example to replace arbitrary placeholder value in a PowerPoint.
PowerPoint to PDF	Export PowerPoint presentation to PDF file
Slides to images	Export PowerPoint slides to seperate image files
Office 365	‌‌
Send email Office Outlook 365	Send email Office Outlook 365
Salesforce	‌‌
Salesforce API	Activity to make calls to Salesforce REST API.
E-mail (SMTP)	‌‌
Mail with SMTP	This function lets you send emails with an e-mail address.
Windows OS	‌‌
Find window with specific title	Find a specific window based on the name, either a perfect match or a partial match.
Login to Windows Remote Desktop	Create a RDP and login to Windows Remote Desktop
Stop Windows Remote Desktop	Stop Windows Remote Desktop
Set Windows password	Sets the password for a Windows user.
Check Windows password	Validates a Windows user password if it is correct
Lock Windows	Locks Windows requiring login to continue.
Check if Windows logged in	Checks if the current user is logged in and not on the lockscreen. Most automations do not work properly when the desktop is locked.
Check if Windows is locked	Checks if the current user is locked out and on the lockscreen. Most automations do not work properly when the desktop is locked.
Get Windows username	Get current logged in user's username
Set clipboard	Set any text to the Windows clipboard.
Get clipboard	Get the text currently in the Windows clipboard
Empty clipboard	Empty text from clipboard. Getting clipboard data after this should return in None
Run VBSscript	Run a VBScript file
Beep	Make a beeping sound. Make sure your volume is up and you have hardware connected.
Get all network interface names	Returns a list of all network interfaces of the current machine
Enable network interface	Enables a network interface by its name.
Disable network interface	Disables a network interface by its name.
Get default printer	Returns the name of the printer selected as default
Set default printer	Set the default printer.
Remove printer	Removes a printer by its name
Get service status	Returns the status of a service on the machine
Start a service	Starts a Windows service
Stop a service	Stops a Windows service
Set window to foreground	Sets a window to foreground by its title.
Get foreground window title	Retrieve the title of the current foreground window
Close window	Closes a window by its title
Maximize window	Maximizes a window by its title
Restore window	Restore a window by its title
Minimize window	Minimizes a window by its title
Resize window	Resize a window by its title
Hide window	Hides a window from the user desktop by using it's title
Terminal	‌‌
Run SSH command	Runs a command over SSH (Secure Shell)
SNMP	‌‌
SNMP Get	Retrieves data from an SNMP agent using SNMP (Simple Network Management Protocol)
Active Directory	‌‌
AD interface	Interface to Windows Active Directory through ADSI. Connects to the AD domain to which the machine is joined by default.
Get AD object by name	Interface to Windows Active Directory through ADSI
Utilities	‌‌
Get user home path	Returns the current user's home path
Get desktop path	Returns the current user's desktop path
Get downloads path	Returns the current user's default download path
Open file	Opens file with default programs
Set wallpaper	Set Windows desktop wallpaper with the the specified image
Download file from a URL	Download file from a URL
System	‌‌
Rename a file	This activity will rename a file. If the the desired name already exists in the folder file will not be renamed. Make sure to add the exstention to specify filetype.
Move a file	If the new location already contains a file with the same name.
Remove a file	Remove a file
Check if file exists	This function checks whether the file with the given path exists.
Wait until a file exists.	Note that this activity is blocking and will keep the system waiting.
List to .txt	Writes a list to a text (.txt) file.Every element of the entered list is written on a new line of the text file.
Read list from .txt file	This activity reads the content of a .txt file to a list and returns that list.Every new line from the .txt file becomes a new element of the list. The activity willnot work if the entered path is not attached to a .txt file.
Read .txt file	This activity reads a .txt file and returns the content
Append to .txt	Append a text line to a file and creates the file if it does not exist yet.
Make text file	Initialize text file
Read .txt file with newlines to list	Read a text file to a Python list-object
Copy a file	Copies a file from one place to another.If the new location already contains a file with the same name, a random 4 character uid is added to the name.
Get file extension	Get extension of a file
Print	Send file to default printer to priner. This activity sends a file to the printer. Make sure to have a default printer set up.
PDF	‌‌
Text from PDF	Extracts the text from a PDF. This activity reads text from a pdf file. Can only read PDF files that contain a text layer.
Merge PDF	Merges multiple PDFs into a single file
Extract page from PDF	Extracts a particular range of a PDF to a separate file.
Extract images from PDF	Save a specific page from a PDF as an image
Watermark a PDF	Watermark a PDF
System Monitoring	‌‌
CPU load	Get average CPU load for all cores.
Count CPU	Get the number of CPU's in the current system.
CPU frequency	Get frequency at which CPU currently operates.
CPU Stats	Get CPU statistics
Memory statistics	Get memory statistics
Disk stats	Get disk statistics of main disk
Partition info	Get disk partition info
Boot time	Get most recent boot time
Uptime	Get uptime since last boot
Image Processing	‌‌
Show image	Displays an image specified by the path variable on the default imaging program.
Rotate image	Rotate an image
Resize image	Resizes the image specified by the path variable.
Get image width	Get with of image
Get image height	Get height of image
Crop image	Crops the image specified by path to a region determined by the box variable.
Mirror image horizontally	Mirrors an image with a given path horizontally from left to right.
Mirror image vertically	Mirrors an image with a given path vertically from top to bottom.
Process	‌‌
Windows run	Use Windows Run to boot a processNote this uses keyboard inputs which means this process can be disrupted by interfering inputs
Run process	Use subprocess to open a windows process
Check if process is running	Check if process is running. Validates if given process name (name) is currently running on the system.
Get running processes	Get names of unique processes currently running on the system.
Kill process	Kills a process forcefully
Optical Character Recognition (OCR)	‌‌
Get text with OCR	This activity extracts all text from the current screen or an image if a path is specified.
Find text on screen with OCR	This activity finds position (coordinates) of specified text on the current screen using OCR.
Click on text with OCR	This activity clicks on position (coordinates) of specified text on the current screen using OCR.
Double click on text with OCR	This activity double clicks on position (coordinates) of specified text on the current screen using OCR.
Right click on text with OCR	This activity Right clicks on position (coordinates) of specified text on the current screen using OCR.
UiPath	‌‌
Execute a UiPath process	This activity allows you to execute a process designed with the UiPath Studio. All console output from the Write Line activity will be printed as output.
AutoIt	‌‌
Execute a AutoIt script	This activity allows you to run an AutoIt script. If you use the ConsoleWrite function, the output will be presented to you.
Alternative frameworks	‌‌
Execute a Robot Framework test case	This activity allows you to run a Robot Framework test case. Console output of the test case will be printed.
Run a Blue Prism process	This activity allows you to run a Blue Prism process.
Run an Automation Anywhere task	This activity allows you to run an Automation Anywhere task.
General	‌‌
Raise exception	Raises an exception
SAP GUI	‌‌
Quit SAP GUI	Quits the SAP GUI completely and forcibly.
Log in to SAP GUI	Logs in to an SAP system on SAP GUI.
Click on a SAP GUI element	Clicks on an identifier in the SAP GUI.
Get text from a SAP GUI element	Retrieves the text from a SAP GUI element.
Set text of a SAP GUI element	Sets the text of a SAP GUI element.
Highlights a SAP GUI element	Temporarily highlights a SAP GUI element
Portal	‌‌
Create a new job in the Automagica Portal	This activity creates a new job in the Automagica Portal for a given process. The bot performing this activity needs to be in the same team as the process it creates a job for.
Get a credential from the Automagica Portal	This activity retrieves a credential from the Automagica Portal.
Vision	‌‌
Check if element is visible on screen	This activity can be used to check if a certain element is visible on the screen.Note that this uses Automagica Portal and uses some advanced an fuzzy matching algorithms for finding identical elements.
Wait for an element to appear	Wait for an element that is defined the recorder
Wait Vanish	This activity allows the bot to wait for an element to vanish.
Read Text with Automagica Wand	This activity allows the bot to detect and read the text of an element by using the Automagica Portal API with a provided sample ID.
	‌‌

许可

版权与许可

本仓库中的所有源代码及其他文件，除非另有说明，均受 Netcall plc 版权保护。

商业许可

有关许可、试用及商业使用的更多信息，请参阅此页面。

Automagica 快速上手指南

⚠️ 重要提示：Automagica 开源项目已于 2020 年 10 月被 Netcall plc 收购。原有的 AGPL3 开源许可已停止，官方云服务（如 Portal、Wand）仅对现有用户提供有限时间的免费过渡期，随后将转为商业服务。本指南基于其开源架构整理，适用于本地开发与学习，生产环境请评估商业授权或迁移方案。

Automagica 是一个旨在让机器人流程自动化（RPA）技术普及化的开源项目。它结合了 Python 的强大功能与可视化流程设计，支持浏览器自动化、文件处理、数据生成等多种任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows 10/11（推荐，部分功能如声音提示仅限 Windows），Linux 或 macOS。
• Python 版本：Python 3.6 或更高版本。
• 前置依赖：
  • pip (Python 包管理工具)
  • Google Chrome 浏览器及其对应的 ChromeDriver（用于浏览器自动化）。
  • Jupyter Notebook（如果计划使用 Automagica Lab 进行开发）。

国内加速建议： 在安装 Python 依赖时，建议使用清华或阿里云镜像源以提升下载速度。

安装步骤

1. 安装核心库

打开终端（Terminal）或命令提示符（CMD），运行以下命令安装 Automagica 核心包：

pip install automagica -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装浏览器驱动

Automagica 默认依赖 Chrome 进行网页自动化。请确保已安装 Google Chrome 浏览器，并下载对应版本的 chromedriver。

将 chromedriver 的可执行文件路径添加到系统环境变量 PATH 中，或者将其放置在项目根目录下。

提示：也可以使用 webdriver-manager 自动管理驱动：

pip install webdriver-manager -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 可选组件安装

如果您需要使用笔记本风格的开发环境（Automagica Lab），请安装 Jupyter：

pip install jupyter -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Automagica 的核心是通过简单的 Python 函数调用（Activities）来执行自动化任务。您可以直接在 Python 脚本或 Jupyter Notebook 中运行。

示例：浏览器操作与 Excel 数据处理

以下示例演示了如何打开浏览器、访问网页、提取文本，并生成随机数据。

from automagica import *

# 1. 打开 Chrome 浏览器
Chrome()

# 2. 访问指定 URL
browse_to('https://www.example.com')

# 3. 获取网页上的所有文本内容
page_text = get_text_on_webpage()
print_console(page_text)

# 4. 查找页面上的第一个链接
first_link = find_first_link()
print_console(f"First link found: {first_link}")

# 5. 生成一些随机测试数据（例如随机姓名和日期）
random_name = generate_random_name(locale='zh_CN') # 尝试生成中文名字
random_date = generate_random_date()

print_console(f"Generated Name: {random_name}")
print_console(f"Generated Date: {random_date}")

# 6. 在屏幕上显示一条临时消息（OSD）
display_osd_message("自动化任务完成！", duration=3)

# 7. 优雅地关闭浏览器
exit()

进阶：使用 Flow 进行可视化编排

如果您更喜欢低代码方式，可以启动 Automagica Flow（如果已安装图形界面组件）：

1. 在命令行输入 automagica flow 启动可视化设计器。
2. 通过拖拽组件构建流程。
3. 在需要复杂逻辑的地方，直接嵌入上述 Python 代码片段。

常用活动速查

• 文件加密/解密: encrypt_text_with_key(), decrypt_file_with_key()
• 随机数据: generate_random_number(), generate_random_address()
• 元素定位: by_xpath(), by_class(), find_elements_by_text()
• 调试输出: print_console(), display_osd_message()

通过以上步骤，您即可快速搭建本地的 Automagica 开发环境并开始编写自动化脚本。