Kapow Mashup Server 6.

Users Guide

RoboRunner

RoboRunner
Users Guide

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

CONTENTS

iii

Contents
INTRODUCTION ........................................................................................ 1 What is RoboRunner? ..........................................................................1 Running Robots in Batch ......................................................................1 Before You Read On ............................................................................1 Other Resources .................................................................................1 USING ROBORUNNER ................................................................................ 2 How to Start RoboRunner ....................................................................2 Using Environments ............................................................................4 EXAMPLES............................................................................................... 8 Run a Single Robot .............................................................................8 Run All Robots in a Directory ................................................................8 INDEX.................................................................................................... 9

INTRODUCTION

Introduction
What is RoboRunner?
RoboRunner is the Kapow Mashup Server application for running robots from a command-line prompt, such as Microsoft's Command Prompt, or a Unix shell. Unlike RoboServer, RoboRunner cannot be used to run robots that require input objects. Only RoboServer can run robots that require input objects. Please refer to the RoboServer User's Guide for more information.

Running Robots in Batch

When used in conjunction with a scheduler, such as Microsoft's Scheduled Tasks or Unix's crontab, RoboRunner can run selected robots at selected times, such as once a day. This is called running robots in batch. This User's Guide will only describe how to use RoboRunner. It will not describe how to use a scheduler. If you need more information on how to use a scheduler, then please refer to the documentation of the scheduler you intend to use.

Before You Read On

Before you proceed to the chapter on how to use RoboRunner, make sure that you have already installed it correctly as described in the Installation Guide.

Other Resources
Additional, mostly referential, documentation on RoboRunner is available at the RoboRunner entry in RoboHelp. You should also check out the support site at this URL: http://support.kapowtech.com/

ROBORUNNER USER'S GUIDE

Using RoboRunner
This chapter describes how to use RoboRunner.

How to Start RoboRunner

RoboRunner is started from the command-line. Open up a command window and type: RoboRunner and then press Enter. If you have installed RoboRunner correctly as described in the Installation Guide, then the following is printed in the command window, after which RoboRunner terminates:
RoboRunner 6.3 (C) 1999-2007 Kapow Technologies Detected the following plugins: ... General parameters: -url <url> (run robot at this URL) -file <file> (run robot in this file) -dir <dir> (run all robots in this directory) -threads <num> (number of concurrently running robots, default 1) Environment parameters: Common Robot Environment (optional): -CommonRobotEnvironment bypassObjectRefinder=false,maxExecutionT ime=999999,maxTimeBetweenObjects=999999,minObjectsLimit=1,maxObjects Limit=999999 Robot Info Environments (one environment must be specified): -SimpleRobotInfoEnvironment robotName=MyRobot,robotRunId=0 -DatabaseRobotInfoEnvironment databaseName=robomanagerdb Storage Environments (one environment must be specified): -DatabaseStorageEnvironment databaseName=objectdb -FileStorageEnvironment fileName=objects.txt,fileFormat=XML,file Encoding=UTF-8 -MultipleFilesStorageEnvironment rootFolder=folderName,fileNameA ttribute=fileName,fileContentAttribute=content,fileEncoding=UTF-8 Message Environments (one or more environments must be specified): -DatabaseMessageEnvironment databaseName=robomanagerdb -FileMessageEnvironment fileName=messages.txt,fileEncoding=UTF-8 -EmailMessageEnvironment emailAddress=john.doe@somedomain.com,ma ilServer=mail.somedomain.com Examples: ... Use RoboRunner -help to get more information.

The dots indicate information that depends on your installation or has been left out of the figure for compactness. If something different than the above is

USING ROBORUNNER

printed in the command window, then please confirm that you have installed RoboRunner as described in the Installation Guide. RoboRunner accepts the following general parameters: Parameter -url <url> Description This parameter refers to a robot by a URL. The robot referred to by the URL will be added to the list of robots to be run. The parameter is optional. It can be repeated multiple times in order to refer to (and hence run) more than one robot. Example: -url http://www.mysite.com/myrobot.robot -file <file> This parameter refers to a robot by a filename. The robot referred to by the filename will be added to the list of robots to be run. The parameter is optional. It can be repeated multiple times in order to refer to (and hence run) more than one robot. Example: -file c:\robot\myrobot.robot -dir <dir> This parameter refers to all robots located in a directory. The robots located in this directory will be added to the list of robots to be run. The parameter is optional. It can be repeated multiple times. Example: -dir c:\robot -threads <num> RoboRunner can run robots concurrently, i.e. at the same time. This parameter specifies the maximum number of robots to be run at the same time. The parameter is optional. The default value is 1, that is, only a single robot will be run at a time. Example: -threads 3 -<environmentname> See the description of the environments below.

There is no required ordering of the parameters. At least one robot must be referred to by -url, -file, or -dir. If not, then the error message: Error: No robots were specified.

ROBORUNNER USER'S GUIDE

is printed to the console. RoboRunner can only run robots that belong to the robot library in the current robot project. You can change the current robot project in the Project tab in the Settings application. Note that this will affect all Kapow Mashup Server applications, and that all Kapow Mashup Server applications must be restarted for the change to take effect. For more on robot projects and robot libraries, see the RoboMaker Users Guide. For examples on how to use the RoboRunner parameters, please refer to the Examples chapter.

Using Environments
Robots are run in environments. These environments affect how the robot is run and how output objects and generated messages are handled, i.e. preprocessed and stored. Several environments are available. Here, we only describe the most commonly used environments. Please refer to the Environments entry in RoboHelp for more information. Environments are grouped into four categories as shown in the table below. Category Common Robot Environment Robot Info Environment Storage Environment Message Environment Description Affects the execution of the robot. Provides information about a robot from some source. Determines how output objects are stored. Determines how generated messages are handled.

USING ROBORUNNER

The table below shows how the default environments are categorized into the four categories. Category Common Robot Environment Robot Info Environment Storage Environment Environments Common Robot Environment Database Robot Info Environment Simple Robot Info Environment Database Storage Environment File Storage Environment Multiple Files Storage Environment Message Environment Database Message Environment File Message Environment Email Message Environment When running robots with RoboRunner you must provide exactly one Robot Info Environment and exactly one Storage Environment. You can provide a Common Robot Environment if you wish to change the default values. You must provide at least one Message Environment, but are free to provide more if needed. If you do not provide a Common Robot Environment, RoboRunner assumes you want the default behavior of the Common Robot Environment. The environments are specified using the environment name followed by a comma-separated list of parameters. An example of using the File Storage Environment is -FileStorageEnvironment fileName=objects.xml,fileFormat=XML This will store the output object in a file called objects.xml and the format of the file will be XML. It is important that the comma-separated list of parameters contains no spaces. The table below provides a brief overview of the default environments. Please refer to the RoboRunner entry in RoboHelp for more detailed information on the environments. It will provide information about which parameters that are required. You can get more detailed help by executing RoboRunner help

ROBORUNNER USER'S GUIDE

Environment Common Robot Environment

Description Affects the execution of the robot. It includes properties limiting the maximum run time of a robot, a limit on the number of output objects, etc. All time limits are specified in seconds. Environment name: CommonRobotEnvironment Sample string: -CommonRobotEnvironment maxExecutionTime=1000,maxTimeBetweenObject=50

Database Robot Info Environment

Retrieves the robot info, such as the robot name, from a RoboManager database. Environment name: DatabaseRobotInfoEnvironment Sample string: -DatabaseRobotInfoEnvironment databaseName=robomanagerdb

Simple Robot Info Environment

Retrieves the robot info from the provided parameters. Environment name: SimpleRobotInfoEnvironment Sample string: -SimpleRobotInfoEnvironment robotName=name Stores the output objects in a database. Environment name: DatabaseStorageEnvironment Sample string: -DatabaseStorageEnvironment databaseName=objectdb Stores the output objects in a file. Environment name: FileStorageEnvironment Sample string: -FileStorageEnvironment fileName=objects.csv, fileFormat=CSV

Database Storage Environment

File Storage Environment

Multiple Files Storage Environment

Stores attributes of the output objects in separate files. Environment name: MultipleFileStorageEnvironment Sample string: -MultipleFileStorageEnvironment rootFolder=folderName,fileNameAttribute=fileName, fileContentAttribute=content,fileEncoding=UTF-8

USING ROBORUNNER

Database Message Environment

Stores the generated messages in a RoboManager database. Environment name: DatabaseMessageEnvironment Sample string: -DatabaseMessageEnvironment databaseName=robomanagerdb

File Message Environment

Stores the generated messages in a file. Environment name: FileMessageEnvironment Sample string: -FileMessageEnvironment fileName=messages.txt

Email Message Environment

Sends the generated error messages to an email address. Environment name: EmailMessageEnvironment Sample init. string: -EmailMessageEnvironment emailAddress=john.doe@domain.com, mailServer=mail.domain.com

Please refer to the Examples chapter for examples on how to use the different environments.

ROBORUNNER USER'S GUIDE

Examples
This chapter provides examples on how to use RoboRunner. Refer to the RoboRunner entry in RoboHelp for more information on how to adjust the examples to match your needs. Because the RoboRunner command-line parameters are usually quite long, you might want to create your own RoboRunner script or batch files.

Run a Single Robot

The command below executes a single robot called myrobot.robot located in the current directory. There are no limitations on the robot run (no Common Robot Environment). The output objects are written to a file called objects.csv (in CSV format, using UTF-8 encoding) located in the current directory. The generated messages are written to a file called messages.txt (in text format, using UTF-8 encoding) located in the current directory. The robot info is provided explicitly, the robot name being MyRobot and the robot run id being 0. RoboRunner -file myrobot.robot FileStorageEnvironment fileName=objects.csv,fileFormat=CSV FileMessageEnvironment fileName=messages.txt -SimpleRobotInfoEnvironment robotName=MyRobot,robotRunId=0 If you want to store the output objects in XML format instead, then replace fileName=objects.csv,fileFormat=CSV with fileName=objects.xml,fileFormat=XML

Run All Robots in a Directory

The command below executes all robots in the c:\robot directory. There are no limitations on the robot run. The output objects are stored in a database called objectdb. The generated messages are written to a database called robomanagerdb. The robot info is retrieved from the robomanagerdb database. Three robots are executed concurrently, i.e. at the same time. RoboRunner -dir c:\robot DatabaseStorageEnvironment databaseName=objectdb DatabaseMessageEnvironment databaseName=robomanagerdb DatabaseRobotInfoEnvironment databaseName=robomanagerdb -threads 3 Note that this example assumes that you have prepared both the objectdb and robomanagerdb databases. Please consult the Installation Guide for more information.

INDEX

Index
C
command-line parameters, 3 examples, 8 current robot project, 4

R
RoboRunner, 1 RoboServer, 1 robot library, 4

E
environments, 4 examples, 8

S
scheduling, 1

T
threads, 3