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 ScriptRunner

ScriptRunner is launched from the executable file located in the $DATASPIDER_HOME/<server|client>/bin folder. When launching ScriptRunner, the strings specified after the executable file are called "command-line arguments".
The command-line arguments include path to the script's launch settings file and values passed to the variables defined in it.
If the launch settings file is omitted then $DATASPIDER_HOME/<server|client>/bin/scriptrunner.xml is applied.

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

Launch settings file

Specify the script you want to start with this settings file.
For details about the specification method of files on startup, refer to here.

Example of a launch settings 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 settings 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 encrypted.
    Password is decrypted when connecting to DataSpiderServer. Use HTTPS connection if encrypted connection to DataSpiderServer is desired.
  • [false]:(default)
    the specified password string is not encrypted.
If encrypt attributes is specified a string value other than [true], or if the value is omitted, the value defaults to [false]
Consult the “Password encryption of launch settings file” section to encrypt 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 settings 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 settings file 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 settings file> localhost 7700 script value

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

Request for a script process to be stopped when ScriptRunner terminates

You can configure the settings to allow DataSpiderServer to request that a script process be stopped when ScriptRunner terminates.

This function is executed in the following steps:
  1. ScriptRunner periodically sends a heartbeat (an indication that its process is in progress) to DataSpiderServer.
  2. If DataSpiderServer does not receive a heartbeat from ScriptRunner within a certain period, it requests that the script process started by that ScriptRunner be stopped.
  3. As the result of the request that the process be stopped, the script process is forcefully stopped and then "InterruptedException" is output to the XML log.
You can adjust the length of the period from when ScriptRunner terminates to when DataSpiderServer requests that the script process be stopped ("a certain period" stated in step 2) by configuring the settings. For details on the settings and defaults, refer to "Properties for detecting termination of ScriptRunner".
ScriptRunner launches the JVM process.This feature requires terminating the JVM process. As a result, DataSpiderServer detects the termination of ScriptRunner and requests the stop of the script processes executed by ScriptRunner.
For example, in a Windows environment, ScriptRunner launches multiple processes, including the executable file and other processes, in addition to the JVM process. In this case, terminating only the JVM process will activate the stop request for the script processes.
A communication failure between ScriptRunner and DataSpiderServer or other events may be detected as termination of ScriptRunner.

Properties for detecting termination of ScriptRunner

You can describe the parameters shown below in the ScriptRunner property file.
The property file is "$DATASPIDER_HOME/<server|client>/bin/scriptrunner.properties".

Key Description Remarks
cancel.script.on.heartbeat.stop To enable the function for requesting that a script process be stopped when ScriptRunner terminates, specify "true".
  • The default value is "false".
  • If you specify "true", the value specified for "sun.net.client.defaultReadTimeout" in "$DATASPIDER_HOME/<server|client>/bin/ScriptRunner.lax" is ignored.
heartbeat.period Specify the interval to send a heartbeat from ScriptRunner to DataSpiderServer.
  • This setting is enabled if "cancel.script.on.heartbeat.stop" is "true".
  • The default value is "1000".
  • The unit is milliseconds.
heartbeat.retry.max.count Specify the number of retries to attempt when sending a heartbeat from ScriptRunner to DataSpiderServer fails.
  • This setting is enabled if "cancel.script.on.heartbeat.stop" is "true".
  • The default value is "5".
connection.timeout Specify how long to wait for a connection to be established from ScriptRunner to DataSpiderServer ("connection timeout" in network communication).
  • This setting is enabled if "cancel.script.on.heartbeat.stop" is "true".
  • The default value is "1000".
  • The unit is milliseconds.
read.timeout Specify how long to wait for a response after establishing a connection from ScriptRunner to DataSpiderServer ("read timeout" in network communication).
  • This setting is enabled if "cancel.script.on.heartbeat.stop" is "true".
  • The default value is "3000".
  • The unit is milliseconds.

If you use the default values for the above parameters, ScriptRunner and DataSpiderServer behave as follows: To avoid DataSpiderServer mistakenly interpreting a communication failure or other events as termination of ScriptRunner, adjust the above parameters according to your environment.

Example of property file

cancel.script.on.heartbeat.stop=true
heartbeat.period=1000
connection.timeout=1000
read.timeout=3000
heartbeat.retry.max.count=5

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.

Password encryption of launch settings file

By specifying -e as the first command-line argument, the content of the password element (the password) in the launch settings file can be encrypted.
lightbulb"Password encryption of launch settings file" execution does not depend on DataSpiderServer's launch condition.
lightbulbA launch settings file in which the password is encrypted can only be decrypted in the environment where the encryption was performed.
To use a launch settings file with an encrypted password in another environment, the password must be set again.

Command-line arguments

The table below details the command-line arguments required to encrypt the password in the launch settings file.

UsageScriptRunner -e [ -f ] [ -p | -P <password> ] [ <src> [ <dst> ] ]

Command-line argument Description Remarks
-e Encrypts the content of the password element in the launch settings file specified by <src>.
  • Encrypting the password in the launch settings file is required.
-f Overwrites if the file specified by <dst> exists.
  • If <dst> is omitted, the file specified by <src> will be overwritten.
-p Encrypts the password entered at the prompt, ignoring the password contained within the password element of the file specified by <src>.
  • -p and -P cannot be specified together.
-P <password> Encrypts the password specified as a command-line argument, ignoring the password contained within the password element of the file specified by <src>.
  • -p and -P cannot be specified together.
<src> Specifies the launch settings file whose password you want to encrypt.
  • If <src> is omitted, $DATASPIDER_HOME/<server|client>/bin/scriptrunner.xml is applied.
<dst> Specifies the destination for the launch settings file with the encrypted password.
  • Can be omitted if -f is specified.

Command Execution Examples

> ScriptRunner.exe -e <src> <dst>
If only -e is specified, the password in the file specified by <src> is encrypted and then written to the destination set by <dst>.
The password must be in plaintext(The encrypt attribute of the password element is either [false] or not defined).

> ScriptRunner.exe -e -f <src> <dst>
If -f is specified with <dst>, it will overwrite the file specified by <dst>.

> ScriptRunner.exe -e -f <src>
If -f is specified without <dst>, the file specified by <src> will be overwritten.

> ScriptRunner.exe -e -p <src> <dst>
Password: <password>
With the -p option specified, the command initiates a prompt.
The password entered at this prompt is then encrypted and written to the file specified by <dst>.

> ScriptRunner.exe -e -P <password> <src> <dst>
With the -P option followed by the password, the command encrypts the specified string and writes it to the file specified by <dst>.

> ScriptRunner.exe -efp <src>
Password: <password>
Options used for password encryption must lead with -e and can be clustered together.

Specification limit

Notes