Creating an IBM® Workload Script Package Project

You can use the Plug-in Development Kit to create script packages.

1. If you are using the Plug-in Development Kit Eclipse plug-in, open the Workload Plug-in Development perspective by clicking Window > Open Perspective > Other > Workload Plug-in Development. Then, click OK.

   The Plug-in Development Kit welcome page opens.

2. Import an existing script package or create a new script package.
   • To import an existing script package, click File > Import > IBM Workload Script Package.
     • Browse to a local script package file or select a script package from the remote server.
     • Click Next.
     • Specify a name for the project to use for the imported script package. If the project does not exist, it is created during the import process.
     • Click Finish.
     • Double-click the cbscript.json file to open the Script Package Configuration page.
   • To create a script package, click the Create an IBM Workload Script Package Project link on the welcome page. You can also create a script package project by clicking File > New > Project > IBM Workload Script Package Project.
     • Enter the information for the project:

       Project name

       Set the name for your project. A script package project can contain one or more script packages.

       Location

       Set the location where the files for your project are stored.

       Script name

       Set the name for the script package.

       Note: One script package is created when you initially create the script package project. To add more script packages to the project later, right-click the project node and select New > Script Package.

       Included

       By default, cbscript.json is created for the script package. If you want to configure more attributes for the script package by using extendedattributes.json, select the check box to create this file.

     • Click Finish.

       The Script Package Configuration page opens.

3. Configure the script package. The parameters that you configure on the Script Package Configuration page are stored in cbscript.json. You can view the contents of cbscript.json by clicking the cbscript.json tab.

   Name

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

   Example of what is written to cbscript.json:

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

   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.

   Example of what is written to cbscript.json:

   "version": "1.0.0",

   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 page when the compressed script package is uploaded. The text string can have a maximum of 1024 characters.

   Example of what is written to cbscript.json:

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

   Location

   The 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 page when the compressed script package is uploaded. The string value can have a maximum of 4098 characters. The default value is /tmp. On supported Windows operating systems, the default is C:\temp.

   Example of what is written to cbscript.json:

   "location": "/tmp",

   Command

   A 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 page when the compressed script package is uploaded. The string value can have a maximum of 4098 characters, and can include environment variables.

   Example of what is written to cbscript.json:

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

   Command Arguments

   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 page 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 by using the backslash as an escape character (\"). If this parameter is specified, when the script package is downloaded this string replaces the string in the cbscript.json file.

   Example of what is written to cbscript.json:

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

   Executes

   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 are 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:

   at virtual system instance creation

   Specifies that the script is run when the virtual system is finished starting during the initial creation.

   This option is written to cbscript.json as "execmode": "0",.

   at virtual system instance deletion

   Specifies that the script is run when the virtual system is deleted.

   Important: Scripts that run when a virtual system instance is deleted are run only if the virtual system instance is running when it is deleted.

   This option is written to cbscript.json as "execmode": "1",.

   when I initiate it

   Specifies that the script is 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. A script can be run an unlimited number of times by using this method.

   This option is written to cbscript.json as "execmode": "2",.

   at virtual system creation and when I initiate it

   Specifies that the script is run when the virtual system is 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. A script can be run an unlimited number of times by using this method.

   This option is written to cbscript.json as "execmode": "3",.

   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 page when the compressed script package is uploaded.

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

   "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:

   Type

   An optional string that indicates 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 value is the default value)

   Example of what is written to cbscript.json:

   "type": "password",

   Script Key

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

   Example of what is written to cbscript.json:

   "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 of what is written to cbscript.json:

   "scriptkey": "DATABASE_PASSWORD",

   Default Value

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

   Example of what is written to cbscript.json:

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

   Locked

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

   Example of what is written to cbscript.json:

   "locked": "true",

   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 a user edits the package properties in the Pattern Editor.

   Required

   An optional control that indicates whether the environment variable is a required or optional variable. Valid values are true or false. The default value is true.

   Example of what is written to cbscript.json:

   "required": "false",

   Valid Values

   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 that is specified by scriptdefaultvalue must be one of these valid values.

   Example of what is written to cbscript.json:

   "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": [],

   Example of what is written to cbscript.json:

   "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"
     }
   [

   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 page when the compressed script package is uploaded. The string value can have a maximum of 4098 characters.

   Example of what is written to cbscript.json:

   "log": "/tmp/SCAS_scriptpkg_logs",

   OS Type

   The type of operating system for which this script is supported. This parameter is useful when you must 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 value 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",

   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 page 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 of what is written to cbscript.json (timeout value of 2 minutes, specified as 120,000 milliseconds):

   "timeout": "120000",

   Type

   An optional indication of the type of script package. The only valid value (and the default if not specified) is Application.

   Example of what is written to cbscript.json:

   "type": "APPLICATION",

4. If you chose to create an extendedattributes.json file, change to the Extended Attributes tab to configure more attributes. The parameters that you configure on the Extended Attributes page are stored in extendedattributes.json. You can view the contents of extendedattributes.json by clicking the extendedattributes.json tab.

   Save environment variables

   Specifies whether changes made to script package parameter values are persisted after deployment, and reapplied to subsequent runs of the script package. For more information, see the Related reference section.

   Product ID

   The product ID associated with the license, as represented in the license catalog. Example of what is written to extendedattributes.json:

   "productid": "5725L53"

   License type

   Defines the type of license. The following values are valid:

   SERVER

   This type of license charges users according to the number of virtual servers used.

   PVU

   This type of license charges users according to the processor value units used.

   PerCore

   This type of license charges users according to the number of processor cores that are used.

   COMPUTE_NODE

   This type of license charges users according to the number of compute nodes that are used.

   Example of what is written to extendedattributes.json:

   "licensetype": "PVU"

   License CPU

   When the type of license is SERVER, this required attribute specifies the processor count limit for this server license. Example of what is written to extendedattributes.json:

   "licensecpu": "4"

   License memory

   When the type of license is SERVER, this required attribute specifies the memory limit in GB for this server license. Example of what is written to extendedattributes.json:

   "licensememory": "4"

   Read only

   Check this box to set the script package as read-only when it is imported to the system. The script package is locked to prevent further editing.

   Console Links

   Define the name and URL for console links. Console links display on the virtual system instance page in the Virtual machines > Consoles section. You can use these links to provide an easy way for a user to access a console that is used to administer the virtual machine, such as VNC or the Integrated Solutions Console for WebSphere® Application Server.

   For more information about defining console links, see "Configuring script packages by using the extendedattributes.json object" in the Related reference section.