Develop > Automation Platform Extensions (APX) > The apxtool command

apxtool command

Use the apxtool command in an OGFS session to create and manage APXs. The apxtool command is available in the Global Shell in the directory /opsw/bin/apxtool.

For a tutorial on how to use the apxtool to create a web APX, see Tutorial: Creating a Web Application APX.

Syntax of apxtool

Invoke the APX tool from the OGFS command line as follows:

apxtool [-h | --help] {function} arguments

To obtain a complete list of commands and arguments supported by the APX tool, run apxtool from an OGSH command line with no arguments.

The APX Tool supports the following major functions:

APX tool functions

Function

Usage

new

Creates a new APX source directory and a new set of template files in the OGFS. Optionally registers the APX into SA. Registering assigns an APX ID and makes the name of your APX available to others (with appropriate permissions) using SA. See Creating a new APX - apxtool new for more information.

import

Imports your APX files into the SA Library and creates a new version of your APX. Optionally registers the APX into SA. Registering assigns an APX ID and makes the name of your APX available to others (with appropriate permissions) using SA. See Importing an APX into SA - apxtool import for more information.

setcurrent

Sets the current version of an APX in the SA Library. You can have multiple versions of an APX in SA, but only the current version can be executed. See Setting the current version of an APX - apxtool setcurrent for more information.

query

Displays information about an APX. See Querying APX information - apxtool query for more information.

export

Copies all of an APXs files from the SA Library to a separate set of files.

delete

Deletes an APX from the SA Library.

Using short and long command options

Most of the options to the apxtool command accept a short form or a long form.

  • The short form is a single hyphen and a character, for example, “-t“ and “-v”.
  • The long format is two hyphens followed by a word, for example, “--type“ and “--view“.

Some options require an argument following the option. For example, “-t webapp“ and “-t details“. Arguments can be specified in one of four formats, which are all equivalent. To illustrate, the following commands are equivalent and produce the same results:

apxtool query -t webapp
apxtool query -twebapp
apxtool query -tw
apxtool query --type webapp
apxtool query --type=webapp

Some options only require typing a minimum number of characters, enough to identify the option argument. For example, in the query function, the --view option requires argument “list“, “details“, “versions“. The following commands produce the same result:

apxtool query --view=details
apxtool query --view=d
apxtool query -vdetails
apxtool query -vd

 

Creating a new APX - apxtool new

You can use the APX tool to create a new APX and optionally register the name of the APX into SA. This command creates a set of template files for an APX that you can modify. For information on the files that make up an APX, see APX files.

Usage

apxtool new [options] {src_dir}

where the src_dir argument specifies the directory where the template files of the new APX are to be created. If this argument is omitted, the template files are placed into the current directory.

The following table lists the options for creating a new APX:

Options for apxtool new

Option

Usage

-h, --help

Show this help message and exit.

-t <type>

--type=<type>

(Required) The APX type. Valid values are: script or webapp. For example, -ts for script APX, -tw for web APX. (A script APX is also known as a program APX.)

-u <unique name>

--uniquename=<unique name>

(Required) The unique name of the APX. A unique name is a dot separated name that conforms to file system format. It must have at least one dot. Valid characters are: [a-zA-Z0-9_.].

Example:
com.hpe.sa.security.scan_ports

-n <name>

--name=<name>

(Optional) The display name of the APX in a folder. If a name is not specified, but a unique name is specified, the last part of the APX unique name is used as the display name. Note that this name must be unique within the specified folder.

For example, if the unique name were com.hpe.sa.MyWebExt, the default display name would be MyWebExt.

-d <description>

--description=<description>

(Required) A brief description of an APX. If the description is a filename with the extension .txt, the file is assumed to be a text file and its content is used as the APX description.

-r

--register

(Optional) Registers the name of the APX into the system. If you specify this option, you must also specify -f or --folder.

If you do not specify -r and -f with apxtool new, you must use -f with apxtool import.

-f <path>

--folder=<path>

(Optional) The SA folder path where the APX will be registered. This can be a full path, partial path, absolute path, or relative path, as long as it can uniquely identify a specific folder. This option is only needed if -r or --register is used.

If you do not specify -r and -f with apxtool new, you must use -f with apxtool import.

-Q, --quiet

(Optional) Suppresses output messages.

-F, --force

(Optional) Suppresses confirmation prompts.

Deleting an APX - apxtool delete

You can use the APX tool to delete an existing APX from the SA library.

Usage

apxtool delete [options]

The following table lists the options for deleting an APX:

Options for apxtool delete

Option

Usage

-h

--help

Show this help message and exit.

-t <type>

--type=<type>

(Required) APX type. Valid values are: script or webapp. For example -ts for script.

--id=<APX id>

(Optional) The object identifier of the desired APX.

-u <unique_name>

--uniquename=<unique_name>

(Optional) The unique name of the APX. A unique name is a dot separated name that conforms to file system format. It must have at least one dot. Valid characters are: [a-zA-Z0-9_.].

Example:
com.hpe.sa.security.scan_ports

-n <name>, --name=<name>

(Optional) APX display name in a folder.

-f <path>, --folder=<path>

(Optional) SA folder path. Path can be a full path, partial path, absolute, or relative, as long as it can uniquely identify a specific folder.

-Q, --quiet

(Optional) Suppresses output messages.

-F, --force

(Optional) Suppresses confirmation prompts.

Exporting an APX from SA - apxtool export

You can use the APX tool to export an APX. Export downloads a specific version of an APX source archive file and places the files into a directory or into a .zip archive file.

Usage

apxtool export [options] {target_dir}

where the argument target_dir is the directory into which the APX source archive file is copied or into which the APX source archive content is expanded, depending on whether or not the --archive option is specified. If omitted, the current directory is used.

The following table lists the options for exporting an APX.

Options for apxtool export

Option

Usage

-h, --help

Show this help message and exit.

-t <type>, --type=<type>

(Required) APX type. Valid values are: script or webapp. For example, -ts for script.

--id=<APX id>

(Optional) The object identifier of the desired APX.

-u <unique_name>,
--uniquename=<unique_name>

(Optional) The unique name of the APX. A unique name is a dot separated name that conforms to file system format. It must have at least one dot. Valid characters are:
[a-zA-Z0-9_.].

Example:
com.hpe.sa.security.scan_ports

-n <name>, --name=<name>

(Optional) APX display name in a folder.

-f <path>, --folder=<path>

(Optional) SA folder path. Path can be a full path, partial path, absolute, or relative, as long as it can uniquely identify a specific folder.

-v v<ersion_string>, --version=<version_string>

(Optional) This option specifies which APX version to download. If omitted, the current version is downloaded.

-a, --archive

If specified, export the APX source in its original source archive as a ZIP or JAR file.

-Q, --quiet

(Optional) Suppresses output messages.

-F, --force

(Optional) Suppresses confirmation prompts.

 

Importing an APX into SA - apxtool import

You can use the APX Tool to import APXs. Import publishes a new version of an APX and optionally sets this version as the current version. If the APX was has not been registered yet, this command also registers the APX.

Only the current version of an APX can be run. If you do not set the current version, the APX will not be runnable. You can set the current version with either apxtool import or with apxtool setcurrent. See Setting the current version of an APX - apxtool setcurrent for more information.

Usage

apxtool import [options] {apx_src}

where apx_src can be an archived APX source file with extension .zip or .jar or it can be the name of a directory containing the APX files to be published. apx_src may be a relative or absolute path. If omitted, the current directory is used. The specified directory or archive file must contain the directory APX-INF.

The following table lists the options that are available when importing an APX:

Options for apxtool import

Option

Usage

-h, --help

Show this help message and exit.

-c, --setcurrent

If specified, set the newly published version as the current version of an APX.

--version=<version_string>

The new version of this APX. This option must not be used if version_string is already specified in apx.cfg. If no version is specified, one will be assigned automatically.

-f <path>, --folder=<path>

(Optional) SA folder path. Path can be a full path, partial path, absolute, or relative, as long as it can uniquely identify a specific folder.

If you did not specify -r and -f with apxtool new, you must use -r with apxtool import.

-Q, --quiet

(Optional) Suppresses output messages.

-F, --force

(Optional) Suppresses confirmation prompts.

Querying APX information - apxtool query

You can use the APX Tool to get and view APX information. You can specify additional options to limit resulting APXs. Multiple occurrences of the same option form a logical OR expression. If no matching result is found, this command returns exit code 100.

Usage

apxtool query [options]

The following table lists the options that are available when querying APX information:

Options for apxtool query

Option

Usage

-h, --help

Show this help message and exit.

-v <view>, --view=<view>

(Optional) Select one of the predefined views of the query results. Choices are list (default), details, and versions.

-v list is a single line representation of APX basic information presented in tabular format.

-v details is a multiple line representation of APX information.

-v versions lists all APX versions. You would only need to specify enough characters for the view type; for example, -vd, is the same as -v details. If the
versions layout is selected, the query must result in a single APX object.

-t <type>, --type=<type>

(Optional) Specifies the type of APX to display. Valid values are: script or webapp or interface. The default is to display all types.

-t script displays all script APXs.

-t webapp displays all web APXs.

-t interface displays all APXs that define one or more interfaces.

For example, apxtool query -ts displays all the script APXs.

--id=<APX id>

(Optional) The object identifier of the desired APX.

-u <unique_name>
--uniquename=<unique_name>

(Optional) The unique name of the APX. A unique name is a dot separated name that conforms to file system format. It must have at least one dot. Valid characters are: [a-zA-Z0-9_.].

Example:
com.hpe.sa.security.scan_ports

-n <name>, --name=<name>

(Optional) APX display name in a folder.

-f <path>, --folder=<path>

(Optional) SA folder path. Path can be a full path, partial path, absolute, or relative, as long as it can uniquely identify a specific folder.

--current

(Optional) if specified, only query APX objects that have a current version set.

--format=<format_string>

(Optional) This advanced option allows you to specify custom display formatting for an APX listing.

format_string is a string containing embedded tag names that are substituted with values at display time. Tag names must have a format of %(tag_name).

Use the format string “__show_tags__” to display a list of all the supported tag names.

--csv

(Optional) Displays the output in comma-separated values format. Ignored if the --format option is specified.

-Q, --quiet

(Optional) Suppresses extraneous output messages.

Setting the current version of an APX - apxtool setcurrent

You can use the APX tool to set an APX version as the current version.

Only the current version of an APX can be run. If you do not set the current version, the APX will not be runnable. You can set the current version with either apxtool import or with apxtool setcurrent. See Importing an APX into SA - apxtool import for more information.

Usage

apxtool setcurrent [options] {version_str}

where the argument version_str is required to uniquely identify an existing version of an APX.

The following table lists the options that are available when setting an APX version:

Options for apxtool setcurrent

Option

Usage

-h, --help

Show this help message and exit.

-t <type>, --type=<type>

(Required) APX type. Valid values are: script, webapp. For example, -ts for script.

--id=<APX id>

(Optional) The object identifier of the desired APX.

-u <unique_name>,
--uniquename=<unique_name>

(Optional) APX unique name. A unique name is a dot separated name that conforms to file system format.It must have at least one dot. Valid characters are
[a-zA-Z0-9_.].

Example:
com.hpe.sa.security.scan_ports

-n <name>, --name=<name>

(Optional) APX display name in a folder.

-f <path>, --folder=<path>

(Optional) SA folder path. Path can be a full path, partial path, absolute, or relative, as long as it can uniquely identify a specific folder.

-Q, --quiet

(Optional) Suppresses output messages.

-F, --force

(Optional) Suppresses confirmation prompts.

Error handling

The APX tool command conforms to the standard POSIX convention and returns 0 on success and a non-zero value for other errors. The APX tool sends normal output to STDOUT and errors and warnings to STDERR. When an error occurs, the APX tool typically returns a descriptive message to STDERR.

Error conditions are typically categorized as shown in the following table:

APX Tool Error Conditions

Return Code

Description

0

Success

1

Syntax or usage error

2

Permission related error

3

User canceled operation

4

Runtime error

There may be other undocumented exit codes. The only guarantee is that if the exit code is 0, the command completed its operation successfully.

Send Help Center feedback