# Flow instructions
Recipe
are json file, edited with theRecipe IDE, and can also be imported from the template Marketplace.
A Recipe
with Flow
instruction and calling with API
is the principle of Browser Automation
.
A recipe example
Wait for the website to load to finish getting the title of the website
[
{
"action": "waitload",
"timeout": 5000
},
{
"action": "text",
"name": "title",
"selector": "title"
}
]
Recipe result example:
{
"page":1,
"data":{
"title":"Example Domain"
}
}
The results of Flow will be stored in data
, which is a JSON Object
, that if Flow specifies a name, the running results will be put into data
In the this example,
Waitload
does not specify a name, then the Flow will be executed, but the execution result will not be stored indata
; the second instructionText
provides a name, if the result of the Flow is notundefined
, it will be used as a field ofdata
.
# Default fileds
action
is a required field, which is the instruction of Flowname
is optional, if not specified, theFlow
run structure will not be saved todata
# waitload
Wait Load
waitload
Wait LoadResult: int
, Time spent, in milliseconds
Wait for the page to load, refer to document.readyState (opens new window), The document and all sub-resources have finished loading.
document.readyState == 'complete'
Paging
,Open
these two instructions will open a new page, it is recommended to add aWaitLoad
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
timeout | int | 0 | YES | Maximum wait timeout, in milliseconds |
# Example:
{
"action": "waitload",
"timeout": "5000"
}
# wait
Wait Ready
wait
Wait ReadyResult: boolean
, is element ready
Waiting for Element to appear, usually waiting for the page to change after clicking, such as waiting for data to load after clicking a button
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath selector |
timeout | int | 0 | NO | Maximum wait timeout, in milliseconds, return immediately when 0 |
name | string | "" | NO | Field name |
# Example:
{
"action": "wait",
"selector": ".table th",
"timeout":2000,
"name":"is_table_exist"
}
# delay
Delay
delay
DelayResult: int
, Time spent, in milliseconds
Similar to sleep, blocks until timeout
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
timeout | int | 0 | YES | Maximum wait timeout, in milliseconds |
# Example:
{
"action": "delay",
"timeout":2000
}
# input
Input
input
Input Result: boolean
, is element ready
Enter text into form
controls that can be entered, such as input
, textarea
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath selector |
value | string | "" | YES | Value to input |
timeout | int | 0 | NO | Timeout to wait for the control to be available, in milliseconds |
name | string | "" | NO | Field name |
# Example:
{
"action": "input",
"name":"is_input_exist",
"selector":"#password",
"value":"YOUR_PASSWORD_HERE",
"timeout":2000
}
# click
Click
click
ClickResult: boolean
, is element ready
Click element
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath selector |
timeout | int | 0 | NO | Timeout to wait for the control to be available, in milliseconds |
name | string | "" | NO | Field name |
# Example:
{
"action": "click",
"name":"is_btn_exist",
"selector":"#login",
"timeout":2000
}
# text
Text
text
Text Result: string
, innerText of element.
Get innerText
of element
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath selector |
timeout | int | 0 | NO | Timeout to wait for the control to be available, in milliseconds |
name | string | "" | NO | Field name |
multiple | boolean | false | NO | Is multiple value, got array when true |
limit | int | 0 | NO | If multiple is true , limit the number of values |
# Example:
{
"action": "text",
"name":"jobtitle",
"selector":".card .title",
"multiple":false,
"limit":2,
"timeout":2000
}
# attr
Property
attr
PropertyResult: string
, the property value of element
Get element property. If the property does not exist, get the Attribute of the DOM object.
Javascript Code:
let elm = document.querySelector(selector)
if (elm[n]) {
return elm[n]
}
return elm.getAttribute(n)
Attributes are defined by HTML. Properties are defined by the DOM (Document Object Model). Property vs Attribute (opens new window)
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath selector |
value | string | "" | YES | Property/Attribute name |
timeout | int | 0 | NO | Timeout to wait for the control to be available, in milliseconds |
name | string | "" | NO | Field name |
multiple | boolean | false | NO | Is multiple value, got array when true |
limit | int | 0 | NO | If multiple is true , limit the number of values |
# Example:
{
"action": "attr",
"name":"avatar",
"selector":".avatar img",
"value":"src",
"multiple":false,
"limit":2,
"timeout":2000
}
# code
Code
code
CodeResult: Object
, code execution result
Execute javascript
code
Javascript
code is an advanced feature that can do complex jobs like text extraction or composing content.
The format of the code, only two formats are supported:
()=> {
// your code here
}
or asynchronous code:
async ()=> {
await ...
}
# built-in value
The code has two built-in objects: brlify
and context
. In the code, you can use:
- Ends the current task early
()=> {
if (some_thing_happend) {
// stop the flows
brlify.stop = true
return
}
}
- Get the
context
parameter of the api
()=> {
// get context from api
let elm = document.querySelector(context.keyword);
//...
}
- Update the value of
context
and use it in the next code block
()=>{
//
// api.contxt.value = 'hello'
console.log(contxt.value);
// output : hello
// update value
context['value'] = 'nice'
}
// next code
//
()=> {
console.log(contxt.value);
// output: nice
}
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
value | string | "" | YES | Javascript Code |
name | string | "" | NO | Field name |
# Example:
{
"action": "code",
"name":"getcontact",
"value":"()=>{return 'contact'}"
}
# stop
Stop
stop
StopResult: undefined
Stop the flows.
# Example:
{
"action": "stop"
}
# scroll
Scroll
scroll
ScrollResult: int
, Time spent, in milliseconds
Scroll to the specified screen position
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
value | string | "" | YES | Format: "x,y,step" , the default step is 20 , the bigger means the more time it takes |
# Example:
{
"action": "scroll",
"value":"800,200,10"
}
# download
Wait Download
download
Wait DownloadResult: Object
Wait for the file to download after clicking the link that can be downloaded
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | Array | [] | YES | Click the element to start the download |
name | string | "" | YES | Field name, is required |
timeout | int | 0 | NO | Timeout to begin download, in milliseconds |
# Example:
{
"action": "download",
"name:":"report",
"selector": "#result_file",
"timeout":10000,
}
# Result
The return value is a JSON Object
, when the filesize is >= 50KB
, the downloaded content will be stored in the object storage, and the url
address that can be downloaded will be returned, otherwise the file content will be stored in the data
field according to Base64
encoding.
{
"error":"", // optional, When an error occurs, error is the cause
"name":"hello.xlsx", // required, File Name
"size":"1024", // required, File size
"url":"", // optional, The url address where the downloaded content is stored
"data":"" // optional, Base64 encoded download content
// data and url choose one of the two
}
# open
Open
open
OpenResult: undefined
Open a webpage, if it is <A>
with selector, open href
, otherwise try to open it as url
address.
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | It can be the css selector of <a> , or it can be a normal url address |
timeout | int | 0 | NO | Maximum wait page load timeout, in milliseconds, return immediately when 0 |
# Example:
{
"action": "open",
"selector":".search_next_btn",
"timeout":5000
}
{
"action": "open",
"selector":"https://next_url.com/",
"timeout":5000
}
# paging
Paging
paging
PagingResult: Array
It is a very powerful function to obtain the content of multiple consecutive pages, for example, after the query results, paging to obtain the query results.
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath Selector for the next page |
flows | Array | [] | YES | Instructions for getting paginated content |
timeout | int | 0 | NO | Maximum wait page load timeout, in milliseconds, return immediately when 0 |
limit | int | 0 | NO | Limit the number of paging, 0 not limit. |
# Example:
{
"action": "paging",
"selector":".search_next_btn:not(.disable)",
"name":"users",
"flows": [
{
"action":"text",
"name":"nickname",
"selector":".nick"
}
],
"limit":10,
"timeout":5000
}
# array
Array
array
ArrayResult: Array
Get the contents of an array, such as each row in a table
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
selector | string | "" | YES | CSS/XPath Selector for element |
flows | Array | [] | YES | Instructions for getting array content |
timeout | int | 0 | NO | Maximum wait element ready timeout, in milliseconds, return immediately when 0 |
limit | int | 0 | NO | Limit the number of array, 0 not limit. |
# Example:
{
"action": "array",
"selector":".table tr",
"name":"users",
"flows": [
{
"action":"text",
"name":"nickname",
"selector":".nickname"
}
],
"limit":10,
"timeout":5000
}
# flows
Flows
flows
FlowsResult: Object
Sub flows
# Option:
Name | Type | Default | Required | Description |
---|---|---|---|---|
flows | Array | [] | YES | Instructions for sub flows |
# Example:
{
"action": "flows",
"flows": [
{
"action":"text",
"name":"nickname",
"selector":".nickname"
}
],
}