First Example

Let's start by looking at the code required to execute the robot named NewsMagazine.robot, which is located in the Tutorials folder of the default project. The robot outputs its results using the Return Value step action, which makes it easy to handle the output programmatically using the API. Other robots (typically those run in a schedule by the Management Console) store their data directly in a database using the Store in Database step action, in which case data collected by the robot will not be returned to the API client.

In the following, we will look at how to execute the NewsMagazine robot and process the output programmatically.


import com.kapowtech.robosuite.api.java.repository.construct.*;
import com.kapowtech.robosuite.api.java.rql.*;
import com.kapowtech.robosuite.api.java.rql.construct.*;

/**
* Example that shows you how to execute NewsMagazine.robot from tutorial1
*/
public class Tutorial1 {

    public static void main(String[] args) throws ClusterAlreadyDefinedException {

        RoboServer server = new RoboServer("localhost", 50000);
        boolean ssl = false;
        Cluster cluster = new Cluster("MyCluster", new RoboServer[]{ server}, ssl);

        Request.registerCluster(cluster); // you can only register a cluster once per application

        try {
            Request request = new Request("Library:/Tutorials/NewsMagazine.robot");
            request.setRobotLibrary(new DefaultRobotLibrary());
            RQLResult result = request.execute("MyCluster");

            for (Object o : result.getOutputObjectsByName("Post")) {
                RQLObject value = (RQLObject) o;
                String title = (String) value.get("title");
                String preview = (String) value.get("preview");
                System.out.println(title + ", " + preview);
            }
        }
        catch (RQLException e) {
            e.printStackTrace();
        }
    }
}

Execute a Robot without input


Let's start by looking at the classes involved and their responsibilities.

RoboServer This is a simple value object that identifies a RoboServer which can execute robots. Each RoboServer must be activated by a Management Console and assigned KCU before use.
Cluster A cluster is a group of RoboServer functioning as a single logical unit.
Request This class is used to construct the robot request. Before you can execute any requests you must register a cluster with the Request class.
DefaultRobotLibrary A robot library instructs RoboServer where to find the robot identified in the request. Later examples will explore the various robot library types and when/how to use them.
RQLResult This contains the result of a robot execution. The result contains value responses, log and server messages.
RQLObject Each value that is returned from a robot using the Return Value action can be accessed as an RQLObject.


Now let's go through each line in the example an look at the specifics.

This tells the API that our RoboServer is running on localhost port 50000.


RoboServer server = new RoboServer("localhost", 50000);


This defines a cluster with a single RoboServer. The cluster is registered with the Request class, allowing you to execute request on this cluster. Each cluster can only be registered once.

boolean ssl = false;
Cluster cluster = new Cluster("MyCluster", new RoboServer[]{ server}, ssl);
Request.registerCluster(cluster);

Registering a cluster


This creates a request that will execute the robot named NewsMagazine.robot located at Library:/Tutorials. Library:/ refers to the robot Library configured for the request. Here the DefaultRobotLibrary is used, which instructs RoboServer to look for the robot in the servers local file system, see Robot Libraries for details on how to use robot libraries.

Request request = new Request("Library:/Tutorials/NewsMagazine.robot");
request.setRobotLibrary(new DefaultRobotLibrary());


This executes the robot on the cluster named MyCluster (the cluster we previously registered) and returns the result once the robot is done. By default execute will throw an exception if the robot generates an API exception.

RQLResult result = request.execute("MyCluster")


Here we process the extracted values. First we get all extracted values of the type named Post and iterate through them. For each RQLObject we access the attributes of the Post type and print the result. We will look at attributes and mappings in a later section.

for (Object o : result.getOutputObjectsByName("Post")) {
    RQLObject value = (RQLObject) o;
    String title = (String) value.get("title");
    String preview = (String) value.get("preview");
    System.out.println(title + ": " + preview);
}