ScriptRunner

ScriptRunner

External application can indirectly invoke DataSpider scripts registered to DataSpiderServer using ScriptRunner program. ScriptRunner exits when the script finished executing.

How to launch a script runner

ScriptRunner is typically invoked by typing its name followed by command-line arguments, or string values sent to a program being called.
The command-line arguments include path to the script's launch configuration file and values passed to the variables defined in it.
If the launch configuration file is omitted then $DATASPIDER_HOME/<server|client>/bin/scriptrunner.xml is used.

The command line arguments are passed to the variables specified in the launch configuration file.
Click here to learn how variables can be defined in the launch configuration file.

Launch configuration file

The file path to the launch configuration file is the 1st command-line argument passed to the ScriptRunner program.
The ScriptRunner program uses $DATASPIDER_HOME/bin/scriptrunner.xml as default, if no launch configuration file is specified.

Example of a Launch configuration file

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <host>localhost</host>
    <port>7700</port>
    <ssl>false</ssl>
    <description>Execute from ScriptRunner.</description></description>
    <user>root</user>
    <password>password</password>
  </connection>
  <params>
    <param project="root@project" script="script">
      <input key="var">value</input>
      <option key="TYPE">production</option>
      <option key="ENABLE_TYPE_SWITCH">false</option>
      <option key="ENABLE_XML_LOG">true</option>
      <option key="LOG_LEVEL">FINFO</option>
    </param>
  </params>
</scriptrunner>
If <option> element used to specify TYPE is omitted, the value of TYPE defaults to 'Default'.

Elements and Attributes

Elements and attributes defined in the launch configuration file are explained in the following table.

Element Attribute Required / Optional Description Remarks
scriptrunner - Required    
connection - Required Specify connection information as the element's value.Appears only once in the scriptrunner element  
host - Optional Specify DataSpiderServer's hostname or its IP address.The value defaults to 127.0.0.1 if it is omitted.  
port - Optional Specify DataSpiderServer port.Defaults to 7700 if omitted.
If ssl attribute is set to true, specify the https port configured in [Control Panel]-[DataSpiderServer Settings]-[Security]		  
ssl - Optional Specify whether to use https connection with DataSpiderServer or not.
  • [true]:
    Connects to DataSpiderServer using HTTPS.
    [Enable HTTPS] found in [Control Panel]-[DataSpiderServer Settings]-[Security] needs to be enabled.
  • [false]:(default)
    Connects to DataSpiderServer using HTTP.
    If [Enable HTTPS] in [Control Panel]-[DataSpiderServer Settings]-[Security] is enabled, traffic is redirected to HTTPS port.
If the ssl element is specified a string value other than [true], or if the value is omitted, the value defaults to [false] 		 
description - Optional Specify session information when executing ScriptRunner.The information specified here is shown in [Session]-[Description] in "Task Manager" in Control Panel.  
user - Required user executing script  
password - Required user's password executing script  
encrypt Optional Whether to encrypt the value set to the password element.
  • [true]:
    the specified password string is obfuscated.
    Password is deobfuscated when connecting to DataSpiderServer.Use HTTPS connection if encrypted connection to DataSpiderServer is desired.
  • [false]:(default)
    the specified password string is not obfuscated.
If encrypt attributes is specified a string value other than [true], or if the value is omitted, the value defaults to [false]
Consult the Obfuscating password string in the launch configuration file section to obfuscate a password. 		 
params - Required    
param - Required Each param element encompasses properties necessary to launch a script.The params element can have multiple param elements.  
project Required Specify a service name.The default string format to specify a service is <user>@<project name>  
script Required Specify the name of the script  
input - Optional Specify arguments that are passed to the script.Arguments are expressed as a <key>-<value> pair. <param> element can have multiple <input> elements  
key Required Specify the argument name.It must much the argument name that the script expects.  
option - Optional Specify optional arguments that are passed to the script.Arguments are expressed as a <key>-<value> pair. <param> element can have multiple <option> elements.
See Option section for further details.		  
key Required Specify the option's name.  

The default values of <input> element

When the value of an element is absent such as the string <input key="var"></input>, one of the default values in the following table is used accordingly to the type of argument expected by the script.
lightbulbThe initial values specified for the arguments declared in a script can be overridden by the values of the <input> elements defined.

Variable Type Default Remarks
String Empty string  
Integer 0 The value which is not an integer such as a string defaults to "0".
Decimal 0 The value which is not a decimal such as a string defaults to "0".
Date/Time 1970-01-01T09:00:00.000+0900  
Boolean false  
Binary null  
XML Empty string  

Options

[option] defined in the launch configuration file is explained in the following table.

Key Value Description Remarks
TYPE - Type used at runtime.  
default Uses "Default" type at runtime.
Also when TYPE is not explicitly specified, "Default" is used at runtime.		  
test Uses "Test" type at runtime.  
production Uses "Production" type at runtime.  
<User-specified type> Uses the type defined by user at runtime.  
ENABLE_TYPE_SWITCH - Whether to fallback to default type or not, in case the global resource of the specified type is missing.  
true use default type  
false Report an error
Default behavior when ENABLE_TYPE_SWITCH is not explicitly specified.		  
ENABLE_XML_LOG - Specify whether to enable XML Log or not  
true XML Log is enabled  
false XML Log is not enabled(default)  
LOG_LEVEL - Specify Log Level  
NOTICE Logs severe errors that cause premature termination or unexpected conditions that are critical.(default)  
INFO Logs informative runtime events occurred but the messages are kept at its minimum.  
FINFO Logs informative runtime events occurred.  
FINEST Shows more detailed messages than FINFO Log Level.  
DEBUG Provides messages useful for debugging.  

Receiving command line arguments

The command line argument references surrounded by %{position} (e.g. %{1}, %{2}) defined in the launch configuration script are scanned and replaced by the corresponding arguments specified on the command line.

Example

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <host>%{1}</host>
    <port>%{2}</port>
    <ssl>false</ssl>
    <description>Execute from ScriptRunner.</description></description>
    <user>root</user>
    <password>password</password>
  </connection>
  <params>
    <param project="root@project" script="%{3}">
      <input key="var">%{4}</input>
      <option key="TYPE">production</option>
      <option key="ENABLE_TYPE_SWITCH">false</option>
      <option key="ENABLE_XML_LOG">true</option>
      <option key="LOG_LEVEL">FINFO</option>
    </param>
  </params>
</scriptrunner>

Command Line Example

> ScriptRunner.exe <launch configuration file> localhost 7700 script value

In the command line example above, the values specified are localhost, 7700, script, and value.
Empty strings are set to the references if no corresponding values are found in the command line.

Exit status

The value returned from the script upon exit of ScriptRunner can be a value generated automatically or the value specified for the end component in the script by user.
See Exit Status for further details.

How to determine the exit status in shell or command prompt.

How the exit status can be determined are different depending on shell or command prompt that executed ScriptRunner.

Command Prompt(Windows)

> echo %errorlevel%

bash(UNIX/Linux)

$ echo $?

csh(UNIX/Linux)

% echo $status

Script execution timeout

It is possible to set a timeout value for the script to be executed; if no timeout is set, then the execution of the script does not expire.

Timeout setting can be performed with ScriptRunner.lax. For fetails, please refer to "Property reference".
If the time specified to the property is shorter than the time needed for the script to end, timeout occurs before the script ends.The script will not be terminated in this case.

Obfuscating password string in the launch configuration file

The string value of <password> in the launch configuration file can be obfuscated by executing ScriptRunner in the following ways. src - An original launch configuration file in which the specified password string is not obfuscated and the 'encrypt' attribute of <password> element is either set to false or not defined.
dst - A launch configuration file whose <password> string value will be obfuscated.
lightbulbAlthough the ScriptRunner program is invoked to perform password string obfuscation,

Specification limit

Notes