ScriptRunner for Amazon SQS

ScriptRunner for Amazon SQS

ScriptRunner for Amazon SQS is an interface to execute sever enrolled service script via Amazon SQS. ScriptRunner for Amazon SQS is composed of "ScriptRunner for Amazon SQS Client" that sends script execution request and "ScriptRunner for Amazon SQS Manager" that executes script after receiving the script execution request.
For details on receiving setting of script execution request, refer to "ScriptRunner for Amazon SQS Setting" in control panel.
For details on queues used in ScriptRunner for Amazon SQS, refer to "script execution request storing queue/script execution result storing queue".
For details on IAM authorization that ScriptRunner for Amazon SQS requires, refer to "IAM Authorization that ScriptRunner for Amazon SQS Requires".

Operation Image

  1. Start ScriptRunner for Amazon SQS client, and send script execution request to script execution request storing queue on Amazon SQS.
  2. ScriptRunner for Amazon SQS manager watches script execution request storing queue on Amazon SQS in server side, and receives the script execution request.

  3. ScriptRunner for Amazon SQS manager executes script, and receives end status or messages.

  4. ScriptRunner for Amazon SQS manager responds the script execution result to the script execution result storing queue on Amazon SQS.

  5. ScriptRunner for Amazon SQS client receives script execution result.

Start ScriptRunner for Amazon SQS Client

When running ScriptRunner for Amazon SQS client, the character string specified followed by ScriptRunnerSQS.exe or ScriptRunnerSQS is called "Command line argument".
In Command line argument, specify start setting file or other information.
The value specified in command line argument is delivered to the variable defined in the start setting file.
For details on how to define variables, refer here.

If required parameter is not defined to the start setting file which ScriptRunner for Amazon SQS client refers, values of property file will be referred.
For details on property file, refer to "Descriptions on start settings with property file".

Start setting file

Specify the script you want to start with this setting file. Then, specify the first argument of ScriptRunner for Amazon SQS client.

Example of start setting file

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <credential>
      <accesskey>AKIAIDWXMMTS4L4IXXXXX</accesskey>
      <secretkey>eukotvrxG/7KTT79yAb+Ya0SBVnILxxxxxxxxxx</accesskey>
    </credential>
    <region>ap-northeast-1</region>
    <requestqueuename>runner_sqs_ixxxxx_req</requestqueuename>
    <receivequeuename>runner_sqs_ixxxxx_recv</receivequeuename>
    <description>Execute from ScriptRunner for Amazon SQS.</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>
<option> element that specifies TYPE is optional. In that case, executes as "default" classification.

Description of Element/Attribute

Description of element and attribute that is specified with start setting file.

In ScriptRunner for Amazon SQS, only one param element can be specified within params.
Element Attribute Required/Optional Description Remarks
scriptrunner - Required    
connection - Required Writes one connection information to scriptrunner element.  
credential - Required Writes one Amazon Web Services credential information to scriptrunner element.  
accesskey - Required Writes one Amazon Web Services access key to credential element.  
secretkey - Required Writes one Amazon Web Services secret key to credential element.  
encrypt Optional Shows whether the contents(secret key) of secretkey element is encrypted or not.
  • [true]:
    Regards secret key as encrypted.
  • [false]:(default)
    Regards secret key as not encrypted.
If encrypt attribute content is not [true], or is omitted, set [false].
Uses secret key after decryption to communication with Amazon Web Services despite encrypt settings. However, whole communication with Amazon Web Services will be encrypted by HTTPS.
For how to encrypt secret key specified with plain text, refer to "Secret key and password encryption of start setting file". 		 
requestqueuename - Required Specify the queue name of script execution request storing queue. Then, writes one to connection element.  
receivequeuename - Required Specify the queue name of script execution result storing queue. Then, writes one to connection element.  
region - Required Writes the region that belongs to the queue specified in requestqueuename/receivequeuename. Then, writes one to connection element.
Region you can specify is as follows.
Region Region name
ap-northeast-1 Asia Pacific (Tokyo)
ap-southeast-1 Asia Pacific (Singapore)
ap-southeast-2 Asia Pacific (Sydney)
us-east-1 US East (N. Virginia)
us-west-1 US West (N. California)
us-west-2 US West (Oregon)
eu-west-1 EU (Ireland)
sa-east-1 South America (Sao Paulo)
 
receivetimeout - Optional Specify the time(second) to wait when receiving script execution result. If you omit, sets 3600(1 hour).  
description - Optional Specify the session information when the ScriptRunner for Amazon SQS was executed. The specified information is the contents showed in Control panel "Task Manager"-[Session]tab-[Description] page.  
user - Required User executing script  
password - Required Password of user executing script  
encrypt Optional Shows whether password element contents(password) is encrypted or not.
  • [true]:
    Regards secret key as encrypted.
  • [false]:(default)
    Regards secret key as not encrypted.
If encrypt attribute content is not [true], or is omitted, set [false].
Uses secret key after decryption to communication with Amazon Web Services despite encrypt settings. However, whole communication with Amazon Web Services will be encrypted by HTTPS.
For how to encrypt secret key specified with plain text, refer to "Secret key and password encryption of start setting file". 		 
params - Required    
param - Required Setup start script. one param corresponds to one starting script.  
project Required Specify service name. Default service name format is <Creator>@<Project name>.  
script Required Specify script name.  
input - Optional Setup argument delivering to script. Multiple input can be specified in param element.  
key Required Name of argument delivering to script. It is required to be the same name as the argument name setup in script.  
option - Optional Option delivering to script. Multiple option can be specified in param element.
For details on options, refer to "Option".		  
key Required Key of option  

Default value of input element

When empty element was made after specifying key attribute to input element such as <input key="var"></input>, default value corresponding to script variable type will be set to the script variable specified to key attribute.
lightbulbTo use defalut value of the script variable set in designer, variable must not be specified to the key attribute of input attribute.

Type of script variable Default value Remarks
Character string type Empty character  
Whole number type 0
  • "0" is set even though values other than whole number is setup.(Ex: Character string)
Decimal degit type 0
  • "0" is set even though values other than Decimal degit is setup.(Ex: Character string)
Date/Time type 1970-01-01T09:00:00.000+0900  
True false value type false  
Binary type null  
XML type Empty type  

Option

[option] Description of element.

Key Value Description Remarks
TYPE - Specifies Classification when executing.  
default Executes with "default" classification.
Even if TYPE is not specified, executes with "default".		  
test Executes with "For test" classification.  
production Executes with "For production" classification.  
<User specification type> When enrolling service, executes with classification specified with user when creating global resource.  
ENABLE_TYPE_SWITCH - If the global resource of specified type does not exist, setup ON/OFF whether to re-search by changing the classification.  
true If the global resource of specified type does not exist, re-search with "default" classification.  
false Errors, if the global resource of specified type does not exist.
If ENABLE_TYPE_SWITCH is omitted, operates as "false".		  
ENABLE_XML_LOG - Sets ON/OFF of XML log  
true Outputs XML log  
false Does not output XML log(Established value)  
LOG_LEVEL - Sets log level.  
NOTICE Log level that outputs only important logs(Established value)  
INFO Log level that is recommended when operating  
FINFO Log level that is recommended when developing  
FINEST Log level that outputs more detailed logs  
DEBUG Log level that outputs well detailed logs  

How to define variables

Text value, project attribute value, script attribute value of all elements can receive the value from command line argument.
To receive command line argument, variable is described to the start setting file with %{1}, %{2}, ... format.

Example of start setting file that defined variable

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <credential>
      <accesskey>%{1}</accesskey>
      <secretkey>%{2}</accesskey>
    </credential>
    <region>ap-northeast-1</region>
    <requestqueuename>runner_sqs_ixxxxx_req</requestqueuename>
    <receivequeuename>runner_sqs_ixxxxx_recv</receivequeuename>
    <description>Executes ScriptRunner for Amazon SQS.</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>

Example of command execution

> ScriptRunnerSQS.exe <Start setting file> AKIAIDWXMMTS4L4IXX eukotvrxG/7KTT79yAb+Ya0SBVnILxx  Script  Input variable value

In the above exapmles, "Access key", "Secret key", "Script name", "Script input variable var value" will be delivered from the command line of ScriptRunner for Amazon SQS client.
If command line argument does not exist, empty character will be set.

End status

End status of ScriptRunner for Amazon SQS will be returned as end process return value of execution script if set as the value, and if not, returns the return value that is set automatically by the system.
For details, refer to "End status".

How to get end status from shell and command prompt

How to get end status of ScriptRunner for Amazon SQS alters depending on the tool (shell and command prompt) to launch ScriptRunner for Amazon SQS client.

In case of command prompt (Windows)

> echo %errorlevel%

In case of bash system(UNIX/Linux)

$ echo $?

In case of csh system(UNIX/Linux)

% echo $status

Script execution timeout

Setting waiting time(timeout time), until end status is returned from script, is available. If this is not set, the default waiting time will be 1 hour.
Timeout setting will be executed with launch setting file "receivetimeout" element, or property file "RECEIVE_TIMEOUT" element.
If the specified time to launch setting file is shorter than script ending time, timeouts before the scrit ends. In this case, the script will not be forcibly finished.

Description of launch setting by property file

Of the parameter defining to launch setting file, part of the parameter of "Connection information" can be specified with property file.
Property file is "$DATASPIDER_HOME/<server|client>/bin/scriptrunnersqs.properties".
If setting value is written to both launch setting file and property file, description of launch setting file will be applied preferentially.

ScriptRunner for Amazon SQS property

Parameter that can be written to property file of ScriptRunner for Amazon SQS.

Key Description Remarks
AWS_ACCESS_KEY Access key of Amazon Web Services.
  • Equivalent to start setting file accesskey element.
AWS_SECRET_KEY Secret key of Amazon Web Services.
  • Equivalent to start setting file secretkey element.
REQUEST_QUEUE_NAME Queue name of script execution request storing queue.
  • Equivalent to start setting file requestqueuename element.
RECEIVE_QUEUE_NAME Specifies queue name of script execution result storing queue.
  • Equivalent to start setting file receivequeuename element.
AWS_REGION Region that queue specified in REQUEST_QUEUE_NAME / RECEIVE_QUEUE_NAME belongs to.
  • Equivalent to start setting file region element.
RECEIVE_TIMEOUT Time (second) that waits receiving of script execution result.
  • Equivalent to start setting file receivetimeout element.
ENCRYPTED Sets [true] if AWS_SECRET_KEY is encrypted and saved.  

Example of property file

AWS_ACCESS_KEY=AKIAIDWXMMTS4xxxxxxx
AWS_SECRET_KEY=eukotvrxG/7KTT79yAb+Ya0SBVnILxxxxxxx
AWS_REGION=ap-northeast-1
REQUEST_QUEUE_NAME=runner_on_demand_ixxxxx_req
RECEIVE_QUEUE_NAME=runner_on_demand_ixxxxx_recv
RECEIVE_TIMEOUT=3600

Secret key and password encryption of launch setting file

Contents of secretkey element and password element (Secret key and password) in launch setting file can be encrypted. Specify launch setting file that secret key and password is in plain text (encrypt attribute of secretkey element and password element is [false], or has no encypt attribute) to <launch setting file>.
launch setting file that secret key and password are encrypted in file name specified to <file name after encryption> is newly created.
lightbulb"Secret key and password encryption of launch setting file" execution does not depend on DataSpiderServer's launch condition.

Property file's secret key encryption

Encrypting property file AWS_SECRET_KEY element is available. Specify -ep option and execute in the condition where property file is not encrypting secret key.
Secret key written in property file is encrypted.
Property file before encryption is saved in "scriptrunnersqs.properties.bak".
lightbulb"Property file's secret key encryption" execution does not depend on DataSpiderServer's launch condition.
lightbulbIn -ep option, specification of encrypt targetted file name or file name after encryption by argument is not available.

Script execution request storing queue/script execution result storing queue

Specification Limits

Notes