Configuring script packages using the cbscript.json object

Use a special JSON object, cbscript.json, to include all the information needed to configure a script package that you add to the catalog.

Overview

When you add a new script package to the catalog, whether by creating a new one or cloning an existing package and configuring it for your needs, you need to specify a number of configuration parameters as defined in the Script Packages pane of the catalog. After uploading your compressed file (.zip and .tgz file types are supported) containing the main executable file and associated artifacts that support the execution, configure the various commands and arguments, working and log files, environment variables needed by the script, and other items that are required to complete the script package definition.

Even though you can do this manually in the Script Packages pane, a best practice is to define these configuration settings once in a special JSON object file that you can include as part of the compressed file before uploading into your script package. The file must be named cbscript.json, and must be located in the root directory of the uploaded compressed file. You can use the Plug-in Development Kit to create this file. See the topic "Creating an IBM® Workload Script Package Project" in the Related tasks section for more information.

The cbscript.json object describes the script package and points to the location of the main script (the script that is the starting point of execution). The cbscript.json file can also contain all of the configuration parameters that you would manually specify in the Script Packages pane. When the compressed file containing the cbscript.json file is uploaded into the script package, the various fields in the Script Packages pane are populated with the contents of the file.

Including a cbscript.json file in your compressed file helps you to ensure that if the same script package needs to be reloaded or shared among multiple virtual system patterns, or if you need to move the virtual system pattern to another system, its definition will be consistent.

Note: After you upload the compressed file into the script package definition, refresh the Script Packages pane to display the updated configuration settings from the cbscript.json file.

Example of a cbscript.json object file

The following example shows the contents of a typical cbscript.json object file, its basic syntax, and many of the variables that define the configuration settings for the script package. You can use this example to install an application:

[
  {
      "name": "Application Install",
      "version": "1.0.0",
      "description": "This script package installs the specified application",
      "command": "/bin/sh ${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
      "log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
      "location": "/opt/tmp/installapp",
      "timeout": "0",
      "commandargs": "-lang jython -f /opt/tmp/installapp/install_app.jy $APP_LOCATION $INSTALL_ARGS",
      "ostype": "linux/unix",
      "type": "APPLICATION",
      "keys":[
         {
          "scriptkey": "APP_LOCATION",
          "scriptvalue": "",
          "scriptdefaultvalue": ""
         },
         {
          "scriptkey": "INSTALL_ARGS",
          "scriptvalue": "",
          "scriptdefaultvalue": ""
         }
       ]
  }
]

Parameters in the cbscript.json object

The basic syntax for parameters specified in the cbscript.json object file is of the form:

"<parameter_name>": "<parameter_value>",

You can specify the following parameters in the cbscript.json object:

name

A required plain text string that identifies the script package. The text string can have a maximum of 1024 characters.

Example:

"name": "Install and configure the ITM OS agent",

When the script package is downloaded, this value is written in the cbscript.json file.

Important: Do not include a trailing space in the parameter or parameter value or errors might occur when you import the script package.

version

An optional plain text string that provides version information. If specified, the value of this parameter represents the version of the script package. If you do not specify a value, the default value 1.0.0 is used.

Restriction: Multiple versions of the same script package are not supported for use with classic virtual system patterns.

Example:

"version": "1.0.0",

When the script package is downloaded, this value is written in the cbscript.json file.

description

An optional plain text string that describes the script package function. This text string is displayed in the Description field of the Script Packages pane when the compressed script package is uploaded. The text string can have a maximum of 1024 characters.

Example:

"description": "This script package creates a JDBC Provider and Data Source for a highly available DB2 Enterprise database cluster",

When the script package is downloaded, this value is written in the cbscript.json file.

command

An optional command string that runs the main script in the script package. The value of this parameter is displayed in the Executable field of the Script Packages pane when the compressed script package is uploaded. The string value can have a maximum of 4098 characters, and can include environment variables.

Example:

"command": "/bin/sh /tmp/createDB2DataSource/createDB2DataSource.sh",

When the script package is downloaded, this value is written in the cbscript.json file.

log

An optional location on the virtual machine for log files that are written resulting from the script package execution. The value of this parameter is displayed in the Logging directory field of the Script Packages pane when the compressed script package is uploaded. The string value can have a maximum of 4098 characters.

Example:

"log": "/tmp/SCAS_scriptpkg_logs",

When the script package is downloaded, this value is written in the cbscript.json file.

location

The optional location where the script package files are stored and unpacked when the compressed script package is uploaded. The value of this parameter is displayed in the Working directory field of the Script Packages pane when the compressed script package is uploaded. The string value can have a maximum of 4098 characters. The default value is /tmp, but the best practice is to specify a new directory under /tmp, for example, /tmp/myscriptdir. On supported Windows operating systems, the default is C:\temp.

Example:

"location": "/tmp/myscriptdir",

When the script package is downloaded, this value is written in the cbscript.json file.

Important: The script architecture assumes that every script is run from its own private directory, usually under the /tmp directory.

After the script completes, the system makes a list of all of the files under its working directory and its subdirectories that do not have the suffix .rpm, .tgz, .gz, .zip, .exe, .BIN, or .bin. The files that are in this list are included in the script_log.zip file.

timeout

The maximum amount of time, expressed in milliseconds, in which the script is expected to complete its execution. The value of this parameter is displayed in the Timeout field of the Script Packages pane when the compressed script package is uploaded. The default value is 60000000 (1000 minutes). A value of 0 specifies to wait indefinitely for the script to complete. If the timeout value is exceeded, Status.TIMEOUT_FAILED is returned, a message is logged to trace.log, and execution is stopped.

Example (timeout value of 2 minutes, specified as 120,000 milliseconds):

"timeout": "120000",

When the script package is downloaded, this value is written in the cbscript.json file.

execmode

Specifies when the script package is run on the system. The default behavior is for the script package to run after all the virtual machines have successfully started and all the nodes are federated, where applicable. The default behavior occurs when the virtual system instance is created. The following values are valid for this parameter:

0: Specifies that the script is run when the virtual system has finished starting during the initial creation. This is the default value if this parameter is not specified.
1: Specifies that the script is run when the virtual system is deleted.
2: Specifies that the script is started manually using the start icon that is displayed next to the script name for a virtual machine. Click the icon to run the script. There is no limit on the number of times a script is run using this method.
3: Specifies that the script is run when the virtual system has finished starting during the initial creation, and is also available to be started manually by using the start icon that is displayed next to the script name for a virtual machine. Click the icon to run the script. There is no limit on the number of times a script is run using this method.
Note: If a script package with "execmode": "3" is associated with a virtual system pattern on a Windows image component, then during the initial start it runs under the Administrator user. During subsequent runs, started manually by using the start icon, it runs through a system service under the system user.

Example:

"execmode": "2",

When the script package is downloaded, this value is written in the cbscript.json file.

ostype

The type of operating system for which this script is supported. This parameter is useful when you need to indicate that the script is valid only for a specific operating system. The following values are valid for this parameter:

linux/unix: The script is valid only on supported Linux and UNIX operating systems. This is the default value if this parameter is not specified.
windows: The script is valid only on supported Windows operating systems.
both: The script is valid on all supported Windows and Linux/UNIX operating systems.

For example, if you create a virtual system pattern with a Windows operating system image, any scripts that are included in that pattern must be able to run on that operating system. In this case you specify the supported operating system as:

"ostype": "windows",

When the script package is downloaded, this value is written in the cbscript.json file.

type

An optional indication of the type of script package. The only valid value (and the default if not specified) is Application. Other values are for internal use only.

Example:

"type": "APPLICATION",

When the script package is downloaded, this value is written in the cbscript.json file.

commandargs

An optional list of arguments and their values that are passed to the script at run time. This list of arguments is displayed in the Arguments field of the Script Packages pane when the compressed script package is uploaded. The string can have a maximum of 4098 characters, and can include environment variables. If the argument can contain the space character, the argument must be wrapped with double quotation marks using the backslash as an escape character (\"). When the script package is downloaded, if this parameter is specified, this string replaces the string in the cbscript.json file.

Example:

"commandargs": "-user \"$(WAS_USERNAME)\" -password $(WAS_PASSWORD)
 -lang jython -f /tmp/myLabApp/appInstall.jy",

keys

The list of environment variables that are added to other system environment variables and made available to the script at run time. These environment variables and their values are displayed in the Environment field of the Script Packages pane when the compressed script package is uploaded.

The list of environment variables and their values are defined in the following format:

"keys":
[
  {
     "scriptkey": "<ENV_NAME>",
     "scriptvalue": "",
     "scriptdefaultvalue": "<default_env_value>"
  },
  {
     "scriptkey": "<ENV_NAME>",
     "scriptvalue": "",
     "scriptdefaultvalue": "<default_env_value>",
     "locked": "<ENV_LOCK>"
  },
  {
     "scriptkey": "<ENV_NAME>",
     "scriptvalue": "",
     "scriptdefaultvalue": "<default_env_value>",
     "type": "<ENV_TYPE>",
     "locked": "<ENV_LOCK>"
  }
]

Each environment variable is defined with the following attributes:

scriptkey

The name of the environment variable. This attribute is required.

Example:

"scriptkey": "DATABASE_HOST",

If the text string value of this attribute includes password, the key is treated the same as if the password type attribute is specified. Example:

"scriptkey": "DATABASE_PASSWORD",

When the script package is downloaded, this attribute is written to the cbscript.json file.

scriptvalue

This attribute is currently not used by the system, but is required to be included for each scriptkey. Set it to an empty string value.

Example:

"scriptvalue": "",

When the script package is downloaded, this attribute is written to the cbscript.json file.

scriptdefaultvalue

An initial default value for the environment variable that you can modify later if needed. This attribute is required, but the value can be blank. If validvalues is specified, the value specified for this default must be one of the valid values specified in the validvalues list.

Example:

"scriptdefaultvalue": "mainhost.ibm.com",

When the script package is downloaded, this attribute is written to the cbscript.json file.

label

An optional plain text string that is the display name for the key in the user interface.

Example:

{
     "type": "positiveinteger",
     "scriptkey": "TOMCAT_PORT",
     "label": "Tomcat port",
     "scriptdefaultvalue": "8080",
     "locked": "false",
     "required": "true"
},

When the script package is downloaded, this attribute is not written to the cbscript.json file.

description

An optional plain text string that describes the script key function. This text string is displayed as descriptive help text for the script key attribute when you are configuring the script key parameter for deployment. The text string can have a maximum of 128 characters.

Example:

{
     "scriptkey": "NPM_PROXY_URL",
     "scriptvalue": "",
     "scriptdefaultvalue": "http://192.168.1.1:8080",
     "description": "Proxy Server Settings",
     "type": "string",
     "locked": "false"
 }

When the script package is downloaded, this attribute is written to the cbscript.json file.

type

An optional string indicating the type of environment value. the following values are valid:

boolean
integer
positiveinteger
password (the value is obscured in the user interface or in log files)
string (this is the default value)

Example:

"type": "password",

When the script package is downloaded, if this attribute is present, it is written to the cbscript.json file.

regex

A regular expression as a sequence of characters that forms a search pattern to validate the script key value. If present, this attribute is used for validating values during script package import or when modifying values by using the console, as well as during deployment and when running script packages on demand. The maximum length of this text string is 128 characters.

Example:

{
  "scriptkey": "KEY-TWO",
  "scriptdefaultvalue": "two",
  "type": "string",
  "regex": "t+.*",
  "description": "Must start with 't'"
}

When the script package is downloaded, if this attribute is present, it is written to the cbscript.json file.

Note:

If a valid regular expression is used in a pattern to validate a user input field, the user input is validated and validation messages are provided in the Pattern Builder and at deployment time.
If an invalid regular expression is used to validate a user input field, the user input is ignored and no validation messages are provided.

Use a regular expression validation tool to make sure your regex value is correct.

locked

An optional control indicating if the environment variable can be modified at deployment time. Valid values are true or false. The default value is false.

Example:

"locked": "true",

Note that this locking feature sets the locked state of the parameter (to locked) when it is added to the Pattern Editor canvas, and is only in effect at the time of deployment. This setting does not affect your ability to do any of the following tasks:

Remove the parameter from the script package in the catalog.
Change the value of the parameter within the script package in the catalog.
Reset the parameter to an unlocked state when editing the package properties in the Pattern Editor.

When the script package is downloaded, this attribute is written to the cbscript.json file.

required

An optional control indicating if the environment variable is a required or optional variable. Valid values are true or false. The default value is true.

Example:

"required": "false",

When the script package is downloaded, this attribute is written to the cbscript.json file.

validvalues

If the value of the environment variable is to be selected from a predefined list of values, include this parameter in the environment variable configuration, and specify the valid values in a list. The value specified by scriptdefaultvalue must be one of these valid values.

Example:

"validvalues": ["a", "b", "c"],

If you specify this attribute, the list of valid values cannot be empty. For example, the following statement is not valid:

"validvalues": [],

When the script package is downloaded, this attribute is written to the cbscript.json file.

Example:

"keys":
[
  {
    "scriptkey": "DATABASE_NAME",
    "scriptvalue": "",
    "scriptdefaultvalue": ""
  },
  {
    "scriptkey": "DATABASE_PORT",
    "scriptvalue": "",
    "scriptdefaultvalue": "50000",
    "type": "integer",
    "required": "true",
    "validvalues": ["50000", "50001", "50002"],
    "locked": "false"
  },
  {
    "scriptkey": "SSL_ENABLED_ON_PORT",
    "scriptvalue": "",
    "scriptdefaultvalue": "true",
    "type": "boolean"
  }
]

The information in the following additional fields on the Script Packages pane is not included in the cbscript.json file when the script package is downloaded:

Current status
Access granted to
Comments