Script package

Use the command-line interface to administer script packages.

Scripts object
Script object
Script attributes
Scripts methods
Script methods
Script.Archive object

Scripts object

A Scripts object represents the collection of script packages defined to Cloud Pak System. Objects of this type are used to create, delete, iterate over, list and search for script packages on IBM® Cloud Pak Software.

Help is available for the Scripts object on the command-line interface. To get help, pass the Scripts object as an argument to the help() function, as shown in the following example:

>>> help(deployer.scripts)

For more information about working with resource, resource collections, and methods, see the related links.

Script object

A Script object represents a particular script defined on IBM Cloud Pak Software. Use the Script object to query and manipulate the script definition on Cloud Pak System. Attributes of the script and relationships between the script and other resources in Cloud Pak System are represented as Jython attributes on the Script object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data in Cloud Pak System.

Help is available for the Script object on the command-line interface. To get help, pass the Script object as an argument to the help() function, as shown in the following example:

>>> help(deployer.script)

Script attributes

The pattern Script object has the following attributes:

acl

The access control list for this script. This field is read-only. For additional help on using this ACL object, see the related links or enter the following command:

>>> help(deployer.acl)

archive

The script archive object associated with this script. See Script.Archive object for more information. This field is read-only.

command

The command to be run for this script package. This field contains a string value with a maximum of 4098 characters.

commandargs

The arguments passed to the command. This field contains a string value with a maximum of 4098 characters.

created

The creation date and time of the script package, stored as the number of seconds since midnight, January 1, 1970 UTC. When details of the script package are displayed, this value is shown as the date and time in the local timezone. This field is read-only.

currentstatus

The status of the script package. This field contains an eight character string value that is generated by Cloud Pak System.

currentstatus_text

A textual representation of currentstatus in the preferred language of the requester. This string is automatically generated by Cloud Pak System. This field is read-only.

description

The description of the script package. This field contains a string value with a maximum of 1024 characters.

environment

Manages the key/value pairs that define the environment, or parameters, of the script. The environment property holds the script keys and default values for the script package. It is used such as a Jython dict object, as shown in the following example:

   >>> myscript.environment
   {
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   }
   >>> myscript.environment['scriptkey1']
   'value for scriptkey1'
   >>> myscript.environment['foo'] = 'bar'
   >>> myscript.environment
   {
     "foo": "bar",
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   }
   >>> del myscript.environment['foo']
   >>> myscript.environment
   {
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   }

This attribute is read-only.

envonly

A flag that controls whether script package variables are written to the script_parms.json file. This attribute is read-only.

See the related links for more information about configuring script packages using the extendedattributes.json object file.

execmode

This attribute specifies when the script package is run on the virtual machine. The following values can be used for this attribute:

deployer.script.VIRTUAL_SYSTEM_CREATION_EXECMODE: This value specifies that the script is run when the virtual system instance is created.
deployer.script.VIRTUAL_SYSTEM_DELETION_EXECMODE: This value specifies that the script is run when the virtual system instance is deleted.
deployer.script.USER_INITIATED_EXECMODE: This value specifies that the script is run when requested by the user. The script can be run an unlimited number of times on a virtual machine.
deployer.script.VIRTUAL_SYSTEM_CREATION_AND_USER_INITIATED_EXECMODE: This value specifies that the script is run either when the virtual system instance is created or when requested by the user. The script can be run an unlimited number of times on a virtual machine.

filename

The name of the script package archive file.

id

The ID of the script. The value of this attribute is an integer and is read-only.

label

The label for the script.

license

The license agreement details for the script package.

licensestatus

The status (accepted or not accepted) of the license agreements for the script.

location

The directory, on the virtual machine, into which files for this script package are to be placed. This field contains a string value with a maximum of 4098 characters.

locations

This attribute is present if you used the "location" filter on the list() method to retrieve objects from one or more systems in a multisystem management domain. When present, this attribute is a list of dictionaries with the following keys. One dictionary appears in the list for each system from which this object was retrieved:

isLocal: This boolean value is set to true if the object exists on the local system; otherwise, the object originates at a remote system.
location: This value is a string containing the name of the location in the multisystem domain on which the object resides.
message: If present, this is a status message about connection to the remote location.
metaSignature: This value is a string containing a unique signature for the object's metadata.
signature: This value is a string containing a unique signature for the object.
status: If present, this value is an HTTP status code about connection to the remote location.
subdomain: If present, this value is a string containing the name of the multisystem subdomain in which the system providing this artifact resides.

log

The directory on the virtual machine to hold the log files generated by this script package. This field contains a string value with a maximum of 4098 characters.

name

The name associated with this script package. Each script package must have a unique name. This field contains a string value with a maximum of 1024 characters.

owner

A user object that references the owner of this script package. For more information about the properties and methods supported by user objects, see the related links, or enter the following command:

>>> help(deployer.user)

productids

The product ID. This attribute is read only.

savevars

defines whether or not script parameter changes that are made after virtual system pattern deployment are persisted and used for subsequent script package execution. The following values can be specified for this attribute:

0: Script package parameter changes made after deployment are not persisted; you will have to manually apply script parameter changes each time the script package is run.
1: Script package parameter changes made after deployment are persisted and applied to subsequent runs of the script package.

See the related links for more information about configuring script packages using the extendedattributes.json object file.

timeout

The maximum amount of time to wait for this script package to finish running on the virtual machine. Specify the timeout, as the number of milliseconds to wait, or 0 (zero) to wait indefinitely for the script package to complete. The value of this attribute is an integer. If timeout occurs, Status.TIMEOUT_FAILED is returned, and execution is stopped.

updated

The date and time when the script package was last updated, stored as the number of seconds since midnight, January 1, 1970 UTC. When the script is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

version

The version of the script package archive file. This attribute is read only.

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

Scripts methods

The Scripts object has the following methods:

create

Creates a script package by uploading a script archive file. The cbscript.json in the archive file must contain the script package name and can optionally contain the version. This method has one required parameter: archivepath and three optional parameters:

name: Use this parameter to override the script package name in cbscript.json.
version: Use this parameter to override the script package version in cbscript.json.
replace: Boolean value. If this parameter is present and set to True, replace only the script archive if the script package exists and is unlocked. A script package is uniquely identified by a combination of name and version. If a script archive file is uploaded and the script package exists and is not locked, the archive file is replaced with the uploaded one by default. If you are not sure whether the script package exists in the system and you want to avoid replacing the archive file accidentally, use 'replace' : False.

Examples:

>>> deployer.scripts.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip'})

Override the name that is defined in cbscript.json:

>>> deployer.scripts.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'name' : 'newName'})

Override the name and version that is defined in cbscript.json:

>>> deployer.scripts.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'name' : 'newName', 'version' : 'newVersion'})

Replace only the archive file if the script package exists:

>>> deployer.scripts.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'replace' : False})

list

Lists the scripts on this system or, optionally, on other systems in the multisystem management domain to which you have access. This method takes one optional parameter, which is a dictionary of attributes on which to filter.

Examples:

>>> deployer.scripts.list()

You can filter by execution mode:

>>> deployer.scripts.list({'execmode': 0})

With appropriate privileges, you can display all scripts in your multisystem subdomain.

>>> deployer.scripts.list({'location': 'domain'})

With the location option, you can also display connection status in your multisystem subdomain. The connection status data with artifact name None is added to the list of scripts containing a nested object name location.

>>> deployer.scripts.list({'location': 'domain',
'includeStatusData': 'true'})

Script methods

In addition to the methods shared with other resources, the Script object has the following methods:

acceptLicense

Accepts the license agreement for the script package.

addProductid

Add a new product ID to the script package. This method accepts the following parameters:

productid: The product ID that you want to add. This parameter is required.
licensetype: The license type for this product ID. The default value is PVU. This parameter is optional.
licensecpu: The CPU count limit for this server license. The default value is 0.
licensememory: The default value is 0.

Example:

>>> test_script = deployer.scripts.list({'name': 'My test script'})[0]
>>> test_script.addProductid('5725R92','PVU')

clone

Creates a copy of this script package with all the same files, fields, and settings. The name of the new script is provided and the acl attribute is empty.

copyTo

Given appropriate permission, copy a script package from this system to another system in your multisystem management domain. This method accepts one parameter, a dictionary, with the following keys:

location: Set this value to the name of the system to which the resource will be copied.

deleteProductid

Delete a product ID from the script package. This method accepts the following parameters:

productid: The product ID that you want to delete. This parameter is required.
licensetype: The license type for this product ID. The default value is PVU. This parameter is required.

The following example shows the deleteProductid method:

>>> test_script.deleteProductid('5724-X89', 'PVU')

isDraft

Indicates if this script is in draft mode.

isReadOnly

Indicates if this script is read-only.

makeReadOnly

Makes this script read-only. When the script is made read-only, the script cannot be modified.

syncTo

Given appropriate permission, update an existing script package on another system n your multisystem management domain based on this object. This method accepts one parameter, a dictionary, with the following keys:

location: Set this value to the name of the system to which the resource will be synchronized.
metadataOnly: Optional. If present, set this to true to synchronize only metadata such as access control lists. Set it to false or omit it to synchronize the entire object. If the script package on the target system is read-only, only metadata can be synchronized.

Script.Archive object

A Script.Archive object represents the archive file associated with a particular script in Cloud Pak System. This object supports methods to query and manipulate the script archive on Cloud Pak System.

Script.Archive methods

The Script.Archive object supports the following methods:

get

This method retrieves the archive currently associated with the script. This method has one required parameter that indicates where the script archive is to be saved. It can be either of the following values:

A string containing the name of a file in which to save the archive. If the file name does not end in .zip, .zip is automatically appended to the file name.
A Jython file object, as shown in the following example:
```
>>> myscript.archive.get('/path/to/foo.zip')
```
You must ensure that the file object can correctly handle binary data. The script archive is returned in a compressed (.zip) file format.

__lshift__

This method is started implicitly when the Archive object is used as the left argument of a left shift operator ( << ). It calls the set() method with the right argument of the operator. This method is shown in the following example:

>>> myscript.archive << '/path/to/file'

__rshift__

This method is started implicitly when the Archive object is used as the left argument of a right shift operator ( >> ). It calls the get() method with the right argument of the operator. This method is shown in the following example:

>>> myscript.archive >> '/path/to/file.zip'

set

This method sets the archive associated with the script. It has one required parameter that indicates the source of the script archive to be uploaded. It can be either of the following values:

A string containing the name of a file from which to get the archive.
A Jython file object.

Ensure that the file object can correctly handle binary data. This method is shown in the following example:

>>> myscript.archive.set('/path/to/foo')

Here is an interactive example showing the use of the scripts.create method to first create a script package named MyScriptPackage, and then use the archive.set method to upload the compressed file MyCompressedFile.zip:

>>> scriptPackageName = 'MyScriptPackage'
>>> filePath = '/uploaded/test/MyCompressedFile.zip'
>>> scriptPackage = deployer.scripts.create({'name' : scriptPackageName})
>>> scriptPackage.archive.set(filePath)

Here is another example, which assumes that the script package has already been created. It uses a single line to find the first script package containing the string MyScriptPackage, and then applies the set method to upload the compressed file.

>>> deployer.scripts['MyScriptPackage'][0].archive.set('/uploaded/test/MyCompressedFile.zip')

For more information about working with resource objects, see the related links.

You can control the users and user groups access to scripts with the ACL object. For more information about the ACL object, see the related links.