Keywords are the primary building blocks implementing your automation. From a business perspective a Keyword symbolize a functionality to be automated. It might represent a fully automated flow or be of a finer granularity such as a single user action or service call. A Plan as the representation of an automated scenario combines one or more Keywords. The occurrence of a Keyword in a Plan results in a Keyword call at Plan execution time.

This chapter focus on the use of Keywords in Plans and addresses the following topics:

• How to call a Keyword from a Plan?
• How to pass data (Inputs) to a Keyword
• How to read and process data returned by a Keyword (Output)?
• How to group Keywords?
• How to route Keywords to specific Agents?

The development of new Keywords is covered in the Development section The deployment and configuration of Keywords is covered in the Keyword page

Calling Keywords

Adding a Keyword to a Plan using the Visual Plan Editor is as simple as follow:

All the available Keywords are listed under “Keywords”. The Keywords table can be filtered using the column search fields to search for the desired Keywords. Per default the Keyword table displays one column “Name” to search Keywords by name. You can add other columns under Admin > Settings to organize your Keywords

Keyword resolution and advanced keyword call

When adding a keyword to a plan from the UI, the criteria to select the underlying keyword during an execution are automatically set. This is usually the keyword name as well as any other custom attributes that you defined (application name, version,…). See the customization page fore more details.

By toggling the edit mode next to the keyword name, you can define the keyword selection criteria in a more complex and dynamic manner:

The basic syntax for calling an existing Keyword without data (Input) using the Plain-text syntax is:

Login
Search_product
Open_product
Add_product_to_basket

If your keyword contains spaces in its name, you have to put it between double quotes:

"Log in" 
"Search product"
"Open product"
"Add product to basket"

Using the PlanParser the syntax is the same as the Plain-text syntax

Keyword Inputs

An important aspect of Step Keywords is the ability to take data as argument. The data passed to Keywords are called Input parameters. In simple terms the Input parameters passed to Keywords is a list of key-values. Technically and more specifically the data is passed to Keywords as JSON Object.

Passing data to a Keyword using the Visual Plan Editor is as simple as follow:

Without activating the lightening symbol of the value fields, the value is passed as string as it is without interpretation. By activating the lightening symbol variables or complex expressions can be used for the Input values. See Variables for more details.

The syntax for calling an existing Keyword with data (Input) using the Plain-text syntax is:

Login
Search_product product_name="Hand blender"

If your input contains spaces in its name, you have to put it between double quotes:

Search_product "product name"="Hand blender" 

Using the PlanParser the syntax is the same as the Plain-text syntax

Keyword Outputs & Asserts

A no less important aspect of Step Keywords is the ability to return data after execution. The data returned by Keywords are called Keyword Outputs or simply Outputs. In simple terms the Output returned by Keywords is a list of key-values. Technically and more specifically the data is returned as JSON Object.

In a Plan Output values can be reused in further steps or be asserted using the out-of-the-box assert operators provided along with Step.

Assuming that our Keyword “Search product” returns the product id of the first result under the Output value “first_product_id”, asserting that the returned data matches the expected result using the Visual Plan Editor is as simple as follow:

If you now want to save the content of the Output value “first_product_id” you can use the Set control as follow:

You can then inject the saved value to the Input data of the next Keywords as follow:

The object output refers to the Output of the parent Keyword.

Please note the importance of the lightening icon.

The syntax for calling an existing Keyword with data (Input) using the Plain-text syntax is:

Login
Search_product product_name="Hand blender"
Assert first_product_id = "Trisa"
Open_product id = "${previous.first_product_id}"

The object “previous” refers to the Output of the previous Keyword execution

Using the PlanParser the syntax is the same as the Plain-text syntax

Grouping Keywords (Session control)

Depending on what you want to achieve you might use fine-grained Keywords that represent single actions in the automated application and thus rely on preconditions set by other Keywords, such as Login, etc… Keywords that rely on the prior execution of other Keywords as prerequisite are called stateful Keywords. Working with stateful Keywords require that all the Keywords are executed on the same Agent. In a normal Plan Keywords might be distributed randomly to different Agents. If you need to enforce the execution of a Keyword sequence on the same Agent i.e the same application session, then you have to tell Step this explicitly using the Session control.

The Session control ensures that all the Keywords inside of it are executed on the same Agent Token.

Using the Visual Plan editor telling Step to group the execution of Keywords on the same agent token is as simple as:

This will ensure that the 3 Keywords will be executed on the same Agent Token

The syntax for telling Step to group the execution of Keywords on the same agent token is:

Session
 Login
 Search_product product_name="Hand blender"
 Open_product
End

This will ensure that the 3 *Keywords* will be executed on the same *Agent Token*

Using the PlanParser the syntax is the same as the Plain-text syntax

Keyword Routing

Keywords are executed on Step Agents and more precisely on Agent tokens. Each Agent emits a configurable number of Tokens in the Grid that are made available for Keyword execution. At Plan execution, when the Plan reaches a Keyword, a Token is selected from the Grid to execute the Keyword on the Agent. The process of selecting a Token for Keyword execution is called Token selection.

Token selection

Each Agent Token can be given a list of key-values called agent token attributes that can be matched during token selection. These agent token attributes are configured in the Agent Configuration

The token selection i.e the matching of a token for the keyword execution works like a query on a set of objects. On one side the set of agent tokens with their token attributes (key-value pairs) and on the other side the list of selection criteria (the query) configured in the Keyword routing.

The selection criteria i.e the keyword routing can be defined in many places in Step giving the user the maximum flexibility to select agent tokens on which Keywords should be executed.

• In the Plan on the Keyword node: to defined call-specific routing criteria that are specific to one Keyword call in one specific Plan
• In the Plan on the Session node: to define Session-specific routing criteria that are specific to a group of Keywords (Session) in one specific Plan
• In the Keyword configuration window to define specific routing criteria for a specific keyword
• Centrally using the special variable route_to_

Defining Keyword routing in the Plan on the Keyword node

Using the Visual Plan Editor defining token selection criteria is as simple as:

This will select an agent token that has the attribute OS=“Windows” to execute the keyword “Search in Google”.

Please also note that you have the possibility to execute the Keyword directly on the Controller if you untick the “Execute on Agents” box. If you choose to do so, the token selection criterias will be ignored.

Currently the Plan-text syntax doesn’t support the specification of selection criteria at Keyword call level

Using the PlanParser the syntax is the same as the Plain-text syntax

Defining Keyword routing in the Plan on the Session node

Using the Visual Plan Editor defining token selection criteria on the Session node is as simple as:

This will select an agent token that has the attribute OS=“Windows” and OS_Version=“10” to execute both keywords grouped by the Session control.

Session OS="Windows" OS_Version="10"
 Login
 Search_product product_name="Hand blender"
 Open_product
End

This will select an agent token that has the attribute OS="Windows" **and** OS_Version="10" to execute both keywords grouped by the Session control.

Using the PlanParser the syntax is the same as the Plain-text syntax

Defining Keyword routing in the Keyword configuration window

Defining token selection criteria per Keyword has to be done in the web interface on the configuration screen of the Keyword:
This will add the selection criteria OS=“Linux” for the execution of the executions of the keyword “Open Chrome” in all Plans.

Defining Keyword routing using the special variable route_to_

You can use the reserved variable “route_to_{key}” in order to define additional selection criteria either in your Plan or centrally under Parameters. For instance, if you want to add the selection criteria OS=“Linux” centrally for all the token selections you can define the Parameter route_to_OS=“Linux”

As “route_to_{key}” is handled like any other normal variable, you could also declare it in a Plan:

This would add the selection critera to all the nodes that are in the scope of the variable.

Token selection (query and precendence)

As discussed Token selection criteria can be defined at many places in Step. When defining multiple selection criteria the following rules apply:

Precedence

When defining selection criteria for the same token attribute at different places the following precedence apply (from the highest priority to the lowest):

1. Selection criteria defined by the special variable route_to_
2. Selection criteria defined in the Keyword configuration window
3. Selection criteria defined on the Session node
4. Selection criteria defined on the Keyword call node

Compilation of different selection criteria

When defining different selection criteria for different token attributes the query used to select the agent token for Keyword execution is built as follow: All the selection criteria are concatenated in a query using a logical AND operator.

For instance:

• you’ve defined the selection criteria OS=“Windows” on the configuration screen of the Keyword “Open IE”
• you’ve defined an additional selection criteria Windows_Version=“10” on the Session node of your Plan

=> At Keyword execution Step will look for an agent token having both the agent token attributes OS=“Windows” and Windows_Version=“10”