RoboServer Users Guide.pdf

Kapo

w M

ashu

p Se

rver

6.4

RoboServer User’s Guide

RoboServer User’s Guide

Copyright 1999-2007 Kapow Technologieshttp://www.kapowtech.com All rights reserved.

CONTENTS iii

Contents

INTRODUCTION ........................................................................................ 1 What is RoboServer?...........................................................................1 What is RQL? .....................................................................................1 This is Not a Specification ....................................................................1 Before You Read On ............................................................................1 Other Resources .................................................................................2

STARTING ROBOSERVER............................................................................. 3 How to Start RoboServer .....................................................................3 Shutting Down RoboServer ..................................................................5 Example............................................................................................5

GETTING A FEEL FOR ROBOSERVER ............................................................... 6 UNDERSTANDING RQL............................................................................... 8

RQL Requests.....................................................................................9 Execute Request ..............................................................................9 Stop Request................................................................................. 12 Ping Request ................................................................................. 12

RQL Responses................................................................................. 13 Server Execution Event Response..................................................... 13 Ping Response ............................................................................... 14 Server Error Response .................................................................... 14 Robot Extracted Object Response ..................................................... 15 Robot Message Response ................................................................ 15 Robot Error Response ..................................................................... 15

RQL SERVICES ...................................................................................... 17 INDEX.................................................................................................. 19

INTRODUCTION 1

Introduction

What is RoboServer? RoboServer is the application for running robots as a service to clients. Once started, RoboServer accepts requests from clients, such as robot execution requests, and sends back responses, such as the objects that a robot extracted during its execution.

RoboServer can run any kind of robot. Usually, however, it executes robots that require input objects in order to run. See the RoboMaker User's Guide for more information on how to create robots that take input objects.

Kapow Mashup Server also includes an application called RoboClient. RoboClient is an example of a client communicating with RoboServer, and can be used for the purposes of demonstrating and testing RoboServer. Normally, however, a client communicating with RoboServer will be an integrated part of your own system as a means of executing robots in realtime.

What is RQL? Clients communicate with RoboServer using the Robot Query Language (RQL). RQL can be represented in many different ways, including XML.

In many ways, RQL is like SQL, e.g. it is also a uniform interface for interacting with (i.e. reading to and writing from) a data source. However, unlike SQL, RQL can be used to invoke robots taking input objects. These robots can both query (i.e. read) and submit (i.e. write) data to one or more data sources (normally web sites).

This is Not a Specification This User's Guide describes how to use and communicate with RoboServer in the normal (i.e. simple) case. It is not a complete specification. Therefore, it does not cover every aspect of RoboServer behavior. If you have any questions that this User's Guide does not answer, please visit the support site at the URL given in the section “Other Resources” below.

Before You Read On Before you proceed to the following chapters on how to use RoboServer and RoboClient, make sure that you have already installed both RoboServer and RoboClient correctly as described in the Installation Guide.

2 ROBOSERVER USER'S GUIDE

Other Resources You should check out the support site at this URL:

http://support.kapowtech.com/

STARTING ROBOSERVER 3

Starting RoboServer This chapter describes how to start RoboServer.

How to Start RoboServer RoboServer can be started by clicking the RoboServer program icon, by invoking it from a command-line, or by running it as a service. For more information about running RoboServer as a service, see the Installation Guide.

Open up a command window and type:

RoboServer

followed by Enter. If you have installed RoboServer correctly as described in the Installation Guide, then the following is printed in the command window after which RoboServer terminates:

RoboServer 6.4 (C) 1999-2007 Kapow Technologies Detected the following plugins: ... Usage: RoboServer [-maxConcurrentRobots <num>] [-maxQueuedRobots <num>] [-maxClippingSessions <num>] [-verbose] [-version] -service <service-name:service-parameters> Available services: ...

The dots indicate information that depends on your installation. If something different than the above is printed in the command window, then please confirm that you have installed RoboServer as described in the Installation Guide.


No matter how RoboServer is started, it accepts the following parameters:

Parameter Description

-maxConcurrentRobots <num> This parameter specifies the maximum number of robots that can run at the same time. Additional robot execution requests will be queued. The parameter is optional. The default value is 20. The minimum value is 1, and the maximum value is 50.

Example: -maxConcurrentRobots 3

-maxQueuedRobots <num> This parameter specifies the maximum number of robots that can be queued for execution. If this queue size is reached, additional robot execution requests will be rejected by RoboServer. The parameter is optional. The default value is 50.

Example: -maxQueuedRobots 25

-maxClippingSessions <num> This parameter specifies the maximum number of clipping sessions that can exist on this RoboServer. This parameter is optional. The default value is 50. The minimum value is 0.

Example: -maxClippingSessions 20

-verbose This optional parameter causes Robo-Server to output status and runtime events.

-version This optional parameter causes Robo-Server to output the version number, and then exit.

-service <service-name:

service-parameters> This parameter specifies an RQL service that RoboServer should start. This parameter must be specified at least once, and may be specified multiple times to start multiple services in the same RoboServer. The available services depend on your installation.

Example: -service socket:50000

STARTING ROBOSERVER 5

There is no required ordering of the parameters. For more information on RQL services, see the “RQL Services” section.

Shutting Down RoboServer There are two ways of shutting down RoboServer. You can connect to the server from ControlCenter and shut it down from there. You can also use the command line tool ShutDownRoboServer. Run ShutDownRoboServer without arguments to see the arguments needed to shut down the server.

Example The command below starts a RoboServer that will run up to 5 robots at the same time, and that accepts socket connections to the Socket-based RQL Service listening on port number 50000.

RoboServer -maxConcurrentRobots 5 –service socket:50000


Getting a Feel for RoboServer You communicate with RoboServer by sending RQL requests to it. Robo-Server will respond to an RQL request by sending back one or more RQL responses. Before we look at all the RQL requests and responses and how and when they are passed between the client and RoboServer, let us get a feel for how RoboServer works.

First, start RoboServer as described in the "Starting RoboServer" chapter above, using the Socket-based RQL Service with 50000 as the socket port number.

Then launch RoboClient by clicking the RoboClient program icon. This brings up the RoboClient Main Window as shown below.

In the left part of the window is the RQL Request Specification View. Here, you select and configure your RQL request and the RQL protocol to use for communicating with RoboServer. In the RQL Protocol property, select the Socket RQL protocol. Using the Execute Request in the RQL Request property, click the browse button and select a robot (written in RoboMaker) taking input objects. Then configure the Input Object Environment by adding the input

GETTING A FEEL FOR ROBOSERVER 7

objects needed by the robot. Finally, click the icon to submit the Execute Request.

Now, if everything has been installed correctly, RoboServer will respond by sending various RQL responses back to RoboClient. These can be seen in the upper half of the RQL Responses View in the right part of the window. Try clicking on an RQL response. The clicked RQL response is then displayed in the lower half of the RQL Responses View.

You can ignore the remaining responses from a request by clicking the icon. Note that this will not cause RoboServer to abort the request; it will simply make RoboClient ignore the remaining responses and be ready for sending a new request. You can remove the responses in the RQL Responses View by clicking the icon.

You might wish to experiment with RoboClient and RoboServer while you read on to get a feel for how RQL requests and RQL responses relate. When you need to program your own client, you will find that RoboClient can be very useful for testing RoboServer and viewing the exact RQL requests and responses passed between the client and RoboServer.

Note that RoboClient is using the robot library in the current robot project. You can only add and configure input objects that are contained in this robot library. Also, you can only view extracted objects contained in this robot library. To execute robots that do not belong to the robot library in the current robot project, you should first switch to the appropriate robot project using the Settings application, and then restart RoboClient for the change to take effect. See the RoboMaker User’s Guide for more on robot projects and robot libraries.


Understanding RQL RQL is the language used to communicate between a client and RoboServer. RQL consists of RQL requests that a client can send to RoboServer, and RQL responses that RoboServer can send back to the client. This chapter describes the RQL requests and responses in detail.

The available RQL requests are shown in Figure 1.

RQL Request Description

Execute Request Requests that a robot should be executed.

Stop Request Requests that a robot execution should be stopped.

Ping Request Ping the RoboServer.

Figure 1: RQL Requests

The available RQL responses that RoboServer can send back to the client as a result of these requests are shown in Figure 2.

RQL Response Description

Server Execution Event Response

Sent when the execution status of a robot has changed, such as when the robot execution has started or ended.

Ping Response Sent as a response to a Ping Request.

Server Error Response Sent when a fatal error occurs during the processing of a request.

Robot Extracted Object Response

Sent when a robot has extracted an output object.

Robot Message Response Sent when a robot has generated a message.

Robot Error Response Sent when a robot has reported an error.

Figure 2: RQL Responses

Now, let us take a closer look at each of the requests and responses.

UNDERSTANDING RQL 9

RQL Requests This section describes each of the available RQL requests.

Execute Request The Execute Request requests RoboServer to execute a robot. The Execute Request has the properties shown in Figure 3.

Property Description

Robot URL The URL of the robot to execute.

Robot Library The robot library that the robot belongs to.

Environments A list of environments to execute the robot in.

Figure 3: Execute Request Properties

The Robot URL property specifies the URL of the robot to execute. The Robot Library property specifies the robot library that the robot belongs to. The robot library can be specified in several ways:

Default Robot Library: This is the default robot library on the particular RoboServer. In the current version, the default robot library is always the robot library in the current robot project of the Kapow Mashup Server installation that the particular RoboServer is part of. The current robot project can be configured using the Settings application. After changing the current robot project, RoboServer must be restarted for the change to take effect.

Robot Library Folder at URL: This is a robot library represented as a folder at a URL. Currently, the URL must always be a file URL that refers to a folder that is accessible in the file system of the particular RoboServer.

Robot Library File Embedded in Request: This is a robot library represented as a robot library file that is embedded in the Execute Request itself. Thus, the robot library is sent to RoboServer as part of the Execute Request.

Robot Library File at URL: This is a robot library represented as a robot library file at a URL. In this case, RoboServer can optionally cache the robot library file, to avoid reloading it for every Execute Request that uses this particular robot library file. When caching is enabled, a cache timeout must be specified that determines how long Robo-Server is allowed to cache this particular robot library file.

In most cases, you want RoboServer to load the robot from the robot library that you specify. To achieve this, you specify the robot URL the non-standard library protocol. For example, if the robot file is named MyRobot.robot and


is located in the folder MyFolder in the robot library folder, you can specify the following URL in the Robot URL property:

library:/MyFolder/MyRobot.robot

This URL will cause RoboServer to load the robot from the robot library, no matter how the robot library is specified in the Robot Library property.

If you use the library protocol to refer to the robot, and specify the robot library as a Robot Library File Embedded in Request, your Execute Request will be completely self-contained. This means that the robot and the robot library do not have to be available to RoboServer in any other way, such as in the file system or at a URL.

For more on robot libraries, including how to create robot library files, refer to the RoboMaker User’s Guide.

The Environments property of the Execute Request contains the environments to execute the robot in. If the robot takes input objects, you must specify an Input Object Environment containing the input objects to pass to the robot. You can also specify other environments, such as a Storage Environment or a Message Environment. If you do not specify such other environments, default environments will be used. For example, if you do not specify a Storage Environment, a default Storage Environment will be used that sends the extracted objects back to the client of RoboServer. Similarly, if you do not specify a Message Environment, a default one will be used that sends the messages generated by the robot back to the client. For more information on environments, see the Environments section under the RoboRunner section of the online RoboHelp.

When RoboServer begins the processing of an Execute Request, it responds by sending a Server Execution Event Response signaling that the robot execution has been requested. The response also specifies an execution id that you can use to refer to this robot execution. The execution id can for all practical purposes be considered globally unique across RoboServers and machines.

When the first Server Execution Event Response is sent, the actual robot execution has not yet started. The execution may be queued until RoboServer is able to start it. When RoboServer starts the actual execution of the robot, it will send a Server Execution Event Response signaling that the execution has started.

During the robot execution, RoboServer may send any of the following RQL responses:

• A Robot Extracted Object Response each time the robot has extracted an object, unless a Storage Environment other than the default one was specified in the Execute Request.

• A Robot Message Response each time the robot generates a message, unless a Message Environment other than the default one was specified in the Execute Request.

UNDERSTANDING RQL 11

• A Robot Error Response each time the robot reports an error. This is the kind of error that a robot can be configured to report, ignore, or otherwise handle. This is not a fatal error. Robot execution will continue after reporting such an error, and it will be considered to have completed successfully if it runs to completion. See the RoboMaker User’s Guide for more on handling and reporting errors in a robot.

• A Server Execution Event Response signaling that a stop has been requested for the robot execution.

In the normal case where the robot execution completes successfully, it will end with RoboServer sending a Server Execution Event Response signaling that execution has ended.

If the robot execution was stopped before it completed, RoboServer will first send a Server Execution Event Response signaling the stop, and then a Server Execution Event Response signaling that the execution has ended.

At any time after receiving an Execute Request, RoboServer may send a Server Error Response to signal that a fatal error has occurred during the processing of the request. For example, this will happen in the following cases:

• The Execute Request is invalid, for example if the XML representation of it is malformed.

• The maximum number of robots that can be queued for execution has been reached.

• RoboServer cannot load the robot or the robot library.

• RoboServer has too many ongoing robot executions to handle the Execute Request.

• The RoboServer license does not allow the Execute Request to be performed.

• An internal error occurred in RoboServer.

After receiving a Server Error Response, the client cannot rely on getting any additional responses related to this particular Execute Request, although the client may get additional responses.

A fatal error like this should not normally occur in a well-functioning system. But a client should, of course, be prepared to handle such a fatal error reasonably, similar to how it would handle, say, a fatal I/O error.


Stop Request The Stop Request requests RoboServer to stop the execution of a robot. The Stop Request has the properties shown in Figure 4.


Execution Id The execution id of the robot execution to stop.

Figure 4: Stop Request Properties

The Execution Id property specifies the execution id of the robot execution to stop. This is the execution id that was sent back to the client in a Server Execution Event Response when the execution was requested.

RoboServer responds to a Stop Request by sending a Server Execution Event Response signaling that a stop has been requested. The robot execution will then stop at the next point where it is possible to stop it, unless something else happens before such a point is reached. When the execution has stopped, RoboServer will send a Server Execution Event Response signaling that execution has stopped, followed by another Server Execution Event Response signaling that execution has ended.

Note that if the execution id in the Stop Request is unknown to RoboServer ⎯ for example, if the execution id is wrong, or the robot has already completed its execution ⎯ RoboServer will ignore the Stop Request and not send back any response.

Ping Request The Ping Request serves the purpose of a quick way to determine if RoboServer is up and running. The Ping Request has no properties. RoboServer responds to a Ping Request by sending a Ping Response.


RQL Responses This section describes the RQL responses that RoboServer can send back in reply to an RQL request.

Server Execution Event Response The Server Execution Event Response is sent when the execution status of a robot execution has changed, such as when the robot execution has started or ended. The Server Execution Event Response has the properties shown in Figure 5.


Time The time when the response was sent.

Execution Id The execution id of the robot execution that changed execution status.

Type The type of change in the execution status.

Figure 5: Server Execution Event Response Properties

Figure 6 shows the possible changes in execution status.

Type Description

Start Requested The robot execution has been requested, but has not yet started.

Started The robot execution has started.

Stop Requested A stop has been requested on the robot execution, but the execution has not yet stopped.

Stopped The robot execution has stopped.

Failed The robot execution has failed because of a fatal error.

Ended The robot execution has ended.

Figure 6: Possible Changes in Execution Status


Ping Response The Ping Response is sent as a response to a Ping Request and contains the RoboServer version and IP Address of the RoboServer The response has the properties shown in Figure 7.



RoboSuite Version The version of RoboServer.

IP Address The IP Address of the RoboServer.

Figure 7: Ping Response Properties

Server Error Response The Server Error Response is sent if a fatal error occurs during the processing of an RQL request. The response has the properties shown in Figure 8.



Message A message describing the error.

Figure 8: Server Error Response Properties

After receiving a Server Error Response, the client cannot rely on receiving any more responses related to the request for which the error occurred, although it may receive such additional responses.


Robot Extracted Object Response The Robot Extracted Object Response is sent each time a robot has extracted an object, unless a Storage Environment other than the default one was specified in the Execute Request. Figure 9 shows the properties of the response.


Robot URL The URL of the robot that is being executed.

Robot Id The id of the robot.

Robot Run Id The run id of the robot execution. This is the run id assigned to the robot execution by the Robot Info Environment used.

Execution Id The execution id of the robot execution.


Object The object that was extracted.

Figure 9: Robot Extracted Object Response Properties

Robot Message Response The Robot Message Response is sent every time a robot has generated a message (any message other than an error report). The properties of the response are shown in Figure 10.







Message The message that was generated.

Figure 10: Robot Message Response Properties

Robot Error Response The Robot Error Response is sent each time a robot reports an error. This is the kind of error that a robot can be configured to report, ignore, or otherwise


handle. This is not a fatal error. Robot execution will continue after reporting such an error, and it will be considered to have completed successfully if it runs to completion. See the RoboMaker User’s Guide for more on handling and reporting errors in a robot.

The properties of the Robot Error Response are shown in Figure 11.







Error Message An error message describing the error.

Error Location The location of the error in the robot.

Error Location Code The location code for the location of the error.

Figure 11: Robot Error Response Properties

The location code in the Error Location Code can be used in RoboMaker to go directly to the step and iterations that generated the error. See the RoboMaker User’s Guide for more information.

RQL SERVICES 17

RQL Services A client always communicates with RoboServer via an RQL service running inside RoboServer. An RQL service determines the RQL message format and the RQL transport mechanism to use for the communication. The RQL message format specifies the representation of the RQL requests and responses, such as XML or Java object serialization. The RQL transport mechanism specifies how the RQL requests and responses are transported across the network to and from RoboServer, such as by using TCP/IP.

The default installation includes the following RQL services:

Socket: An RQL service that uses TCP/IP sockets as the transport mechanism.

Java Messaging Service : An RQL service that uses JMS as the transport mechanism.

Additional RQL services can be added as plugins to the installation.

The RQL services to use are specified as part of the parameters to RoboServer at startup. The same RoboServer can run more than one RQL service.

For more information on RQL services, including the RQL services in the default installation, see the RQL Service User’s Guide.

INDEX 19

Index

C current robot project, 7

E environments, 10

errors, 11, 14, 16

Execute Request, 9

maximum concurrent, 4

maximum queued, 4

execution id, 10

extracted objects, 10, 15

I Input Object Environment, 10

J JMS-based RQL Service, 17

M messages, 11, 15

P parameters, 4

Ping Request, 12

Ping Response, 14

R RoboClient, 1, 6

RoboServer, 1

parameters, 4

running as service, 3

starting, 3

Robot Error Response, 11, 16

Robot Extracted Object Response, 10, 15

robot library

in Execute Request, 9

library protocol, 10

used by RoboClient, 7

Robot Message Response, 11, 15

RQL, 1, 8

RQL message format, 17

RQL requests, 1, 6, 9

overview, 8

RQL responses, 1, 6, 13

overview, 8

RQL services, 17

command-line parameters, 5

default installed, 17

JMS-based RQL Service, 17

Socket-based RQL Service, 17

Socket-based RQL Service, 5, 6

RQL transport mechanism, 17

S Server Error Response, 11, 14

Server Execution Event Response, 11, 12, 13

Socket-based RQL Service, 17

Stop Request, 12

Documents

RoboServer Users Guide.pdf