wappman command

Imports, replaces, deletes, exports, displays and lists a workload application.

Note: On Windows 2012, the command is not supported on Windows PowerShell.

Authorization

You must have add access if you import a new workload application. If the object already exists in the database you must have modify access to the object.

The justification is propagated to all objects created, updated, or deleted.

Syntax

wappman [connection_parameters]
[-u]|[-V]
| {-import|-replace}  <definition_xml_file> <mapping_properties_file>
[-translationRules <translation_rules_file>]
[-workloadApplicationName [folder/]<workload_application_name>]
       [-contents]
-list
-delete [folder/]<workload_application_name> [-noContents]
-export [folder/]<workload_application_template>  [-path <export_path>]
[-zip <export_zip_name>]
-display [folder/]<workload_application_name>

Arguments

[connection_parameters]

A list of or a custom file containing the connection parameters to be used to connect to the server where you want to import, list, delete, export or display the workload application. You can use connection parameters to override the values specified in the useropts and localopts files. To determine which connection properties to use, a check is made in the following order:

Parameters specified in the command string itself.
Parameters specified in the custom properties file.
The useropts file.
The localopts file.
The jobmanager.ini file.

Valid values include:

[-file <custom_properties_file>]

The custom properties file where you can specify connection parameters that override the values specified in the useropts, localopts, and jobmanager.ini files. Connection parameters specified in the custom properties file must have the following syntax:


 HOST=<hostname>
 PORT=<port>
 PROTOCOL=<http/https>
 USERNAME=<username>
 PASSWORD=<password>

[-host <hostname>]

The name of the host that you want to access by using wappman command line.

[-port <port_number>]

The TCP/IP port number used to connect to the specified host.

[-protocol {http | https}]

The protocol used to connect to the specified host.

[-jwt JSON Web Token]

Specify the JWT to be used for authentication between the master domain manager and agents. You can retrieve the token from the Dynamic Workload Console. This parameter is mutually exclusive with the username and password parameters. The JWT authentication applies to the commands you launch in the shell where you specify the JWT.

[-username user_name]

An HCL Workload Automation user with sufficient privileges to perform the operation. This parameter is mutually exclusive with the jwt parameter.

[-password password]

The password of the HCL Workload Automation user. This parameter is mutually exclusive with the jwt parameter.

Note: If host, port, and protocol parameters are specified in a file, all of them must be specified in the same file.

-u

Displays command usage information and exits.

-V

Displays the command version and exits.

{-import|-replace} <definition_xml_file> <mapping_properties_file> [-translationRules <translation_rules_file>] [-workloadApplicationName <workload_application_name>] [-contents]

The name of the definitions file and mapping file to use when importing or replacing a workload application. The operation of importing a workload application is the same as deploying a workload application.

-import

After customizing the mapping file, the mapping file together with the definitions file are passed as input to the wappman -import command to deploy the workload application in an HCL Workload Automation environment different from the source environment where the workload application template was originally created.

-import -contents: Imports only the objects contained in the workload application template and not the workload application itself. Any association to the workload application is not created.

-replace

The behavior of the replace operation depends on whether or not the objects to be replaced are tied to a workload application.

If the objects are tied to a workload application then, when an updated version of the workload application template is reimported into the target environment, the objects in the target environment are updated if they are still present in the database, created if they are no longer present, and deleted if they are no longer present in the updated workload application template.

If the objects are not tied to a workload application or, if the objects are tied to a workload application different from the one specified with the replace operation, then the objects are not replaced and an error message is issued.

The replace operation fails if an object external to the workload application references an object in the workload application and with the replace operation the referenced object is deleted because it is no longer present in the updated workload application.

If references were made from the workload application to an external element, the reference is deleted with the replace action.

The same mapping file used to originally deploy the workload application can be used to update it, making any necessary changes to reflect the updated workload application. The mapping file together with the definitions file are passed as input to the wappman -replace command.

-replace -contents: The behavior of the replace operation depends on whether or not the objects to be replaced are tied to a workload application. If the objects already exist and are not tied to a workload application, then the objects are replaced, but the workload application is not created. If the objects do not exist in the target environment, then they are created without any ties to the workload application. If the objects already exist and are tied to a workload application, then the replace operation fails and an error message is issued.

Additional optional parameters that you can specify are:

-translationRules: The name of the file containing rules defined using regular expressions that wappman -import|-replace command will use to customize the mapping file. For more information about using reular expressions to customize the mapping file, see Using regular expressions to modify the mapping file.
-workloadApplicationName: The name of the workload application, in case you want to import it with a new name.

-list

Lists all of the workload applications present in the environment.

-delete <workload_application_name>

Deletes the specified workload application and all the objects that were added to the environment when the workload application was originally deployed.

-delete <workload_application_name> -noContents: The operation deletes the specified workload application, but maintains the objects that were originally tied to it. There is more flexibility in updating the objects as there is no longer an association to the workload application.

-export <workload_application_template>

Creates the compressed file, named workload application template, containing all the files and information required to deploy the workload application into the target environment.

-path: The file path where the workload application template is exported.
-zip: The name of the workload application template zip file.

-display <workload_application_name>

Displays the contents of the specified workload application.

Displays all of the objects contained in the workload application that were created during the import process.

Comments

You can skip objects when importing a workload application template by adding the SKP prefix before the object you want to skip. If you skip an object, an object with the same name must be present in the target environment, otherwise an error message is returned.

Each line in the mapping file specifies the objects to be imported in the new environment. To avoid importing a specific object, modify the mapping_properties_file by adding the SKP prefix before each object you want to skip.

Consider a mapping file containing two objects, as follows:

JOBSTREAM_TESTJS=TESTJS
JOB_TESTJOB1=TESTJOB1

If the JOB_TESTJOB1 job already exists in the target environment, modify the mapping_properties_file by adding the SKP prefix before the JOB_TESTJOB1 job, as follows:

JOBSTREAM_TESTJS=TESTJS
SKPJOB_TESTJOB1=TESTJOB1

Storing scheduling objects in folders is supported starting from version 9.5 and later. When importing a workload application from a product version earlier than 9.5, all imported objects are stored in the root folder. Ensure you have write access to the root folder before starting the import.

Users can decide to maintain an audit trail recording any changes they perform and the related justifications. To enable the justification option, set up in a system shell the HCL Workload Automation environment variables listed below before running the wappman commands:

IWS_DESCRIPTION: Specify the description to be recorded for each change performed by commands in the shell. The maximum length for this value is 512 characters. A warning message displays if you exceed the maximum and excess characters are truncated.
IWS_CATEGORY: Specify the category to be recorded for each change performed by commands in the shell. The maximum length for this value is 128 characters. A warning message displays if you exceed the maximum and excess characters are truncated.
IWS_TICKET: Specify the ticket to be recorded for each change performed by commands in the shell. The maximum length for this value is 128 characters. A warning message displays if you exceed the maximum and excess characters are truncated.

To set up the environment, proceed as follows, depending on your operating system:

On Windows operating systems

type one or more of the following commands, depending on the variable you want to define:

set IWS_CATEGORY='my category'
set IWS_DESCRIPTION='my desc'
set IWS_TICKET=12345

On UNIX operating systems

type one or more of the following commands, depending on the variable you want to define:

export IWS_CATEGORY='my category'
export IWS_DESCRIPTION='my desc'
export IWS_TICKET=12345

After setting the environment variables, all the commands you enter in the shell inherit the values you defined for the shell. The auditing information from the shell is stored as is in the Tivoli Common Reporting auditing reports. While the information you provide in the Dynamic Workload Console is guided using a pull-down menu, the information you provide from the command line is not filtered.

For more information about the justification option and auditing reports, see Keeping track of changes to scheduling objects and Reporting.

Logs and traces

You can configure the wappman command line by modifying the parameters in the CLI.ini file located in the path TWA_home/TWS/ITA/cpa/config. This file contains parameters for the message logs and trace files related to workload applications. You should only change the parameters if advised to do so in the HCL Workload Automation documentation or requested to do so by HCL Software Support.

Examples

To import a workload application into a new environment, run:

wappman -import <definition_xml_file> <mapping_properties_file>

To import only the contents of a workload application into a new environment, without any ties to the workload application, run:

wappman -import <definition_xml_file> <mapping_properties_file> -contents

To replace an existing workload application, run:

wappman -replace <definition_xml_file> <mapping_properties_file>

To replace objects that are not tied to any workload applications in an environment, run:

wappman -replace <definition_xml_file> <mapping_properties_file> -contents

To delete a workload application, run:

wappman -delete <workload_application_name>

To free objects from any ties to a workload application, run:

wappman -delete <workload_application_name> -noContents

To list all the workload applications available in an environment, run:

wappman -list

To display a specific workload application, run:

wappman -display <workload_application_name>

To export a specific workload application from a remote host, by using a custom properties file, run:

wappman -export <workload_application_name> -path <export_path>
  -host <remote_host> l <custom_properties_file>