wpm install
Downloads and installs specified Integration Server packages from a source repository into a target installation. Packages can either be the entire contents of the repository or subfolders in the repository.
Synopsis
wpm install [package-name:version-number package-name2:version-number … package-nameN:version-number] [optional arguments]
where package-name is a space-separated list of Integration Server packages to install.
Specifying version-number is optional. If version-number is not specified, IBM webMethods Package Manager looks for the highest numerical version number available in the source repository. IBM webMethods Package Manager first looks in the tags and branches, looking in branches only if -sb=true (the default), and then falls back to the main branch.
Arguments
The following table lists all available arguments for the wpm install command and their descriptions:
Argument | Description |
-r [repository] | The repository from which to install packages. The repository can be an absolute path to a GitHub repository, a URL, or an alias of a repository defined in the wpm.yml configuration file. Optional if a single repository is defined in the wpm.yml configuration file. Required if the wpm.yml file does not define any repositories or defines more than one repository. |
-u [username] | Username for the repository from which to install packages. For a GitHub repository, specify a GitHub user name. For a Package Registry repository, specify an Empower username. Optional. Required when installing packages from a private GitHub repository or a private repository in the Package Registry. |
-p [password] | When creds\private_key_path is set in the wpm.yml file or in the -k argument, specify a passphrase in wpm.yml configuration file or in the -p argument. |
-k [private-key] | Relative or absolute path to the location of the private key file to use for SSH authentication with the remote GitHub repository. The relative path is relative to the location of the wpm launch script (usually \wpm\bin). Required if SSH authentication is used and the creds\private_key_path property is not set in the wpm.yml configuration file. |
-j [token] | OAuth token for obtaining packages from the GitHub repository or IBM webMethods Package Registry protected by token authorization. Required only if remote GitHub repository or IBM webMethods Package Registry repository requires an OAuth token for authentication and jwt_token is not set in the wpm.yml file. |
-ad {true|false} | Whether IBM webMethods Package Manager checks for dependent packages and automatically installs them. If set to false or not present, wpm does not attempt to automatically install dependencies. All missing dependencies are listed as warnings in the output. If set to true, wpm attempts to install all dependent packages and reports errors for any it cannot install. Optional. The default is false. |
-sb {true|false} | Whether IBM webMethods Package Manager scans branches and tags in the repository for the specified version number of a packages. If set to true, wpm scans branches and tags; false scans only tags. Optional. The default is true. |
-kr {true|false} | Whether IBM webMethods Package Manager keeps the local repository or cleans it up after the install command completes. A value of true keeps the repository; false indicates that webMethods Package Manager deletes all the local repositories once the install command completes successfully. Keeping the local repository can be useful if multiple instances of Integration Server reside on the same machine and you want to update the packages in multiple instances or if different versions of the same package will be installed. Use wpm clean to delete local repositories. Optional. The default is false. |
-ws [package-manager-server] | URL of the IBM webMethods Package Registry that contains the package to install. Optional. Specify -ws argument when you want to install a package located in the IBM webMethods Package Registry and one of the following is true:  The wpm.yml configuration file does not set a IBM webMethods Package Registry. You want to override the value configured in the wpm.yml configuration file. A wpm.yml file is not used with wpm. |
-wr [package-manager-registry] | Name of the IBM webMethods Package Registry from which to install packages. The IBM webMethods Package Registry can contain multiple registries in addition to the default registry. Optional. Supply -wr if also supplying -ws and you want to install packages from a registry other than the default registry. If the -wr argument is not supplied but the -ws argument is supplied, wpm uses the default registry for the install operation. |
-d [target-installation] | Relative or absolute path to the target server installation. The relative path is relative to the location of the wpm launch script (usually \wpm\bin). Required if all of the following are true: The target_installation property is not set in the wpm.yml file. The wpm.home environment variable is not specified. IBM webMethods Package Manager is not in the same installation directory as the target server. |
-ks {true|false} | Whether IBM webMethods Package Manager preserves the enabled or disabled state of a package. If the -ks argument is not supplied, wpm sets the state of a package as enabled. The -ks argument also affects any dependent packages. Optional. The default is false. |
Usage Notes
Argument values specified in the command override related property values in the wpm.yml configuration file.
The
wpm install command does not activate the installed packages. You must restart
Integration Server to activate the package.
The
wpm install command checks for any dependent packages and, if possible, installs them based on the value of the
-ad argument. If wpm cannot install the dependent packages, it returns an error or a warning based on the value of the
-ad argument.
The
wpm install command places the installed packages in
Integration Server_directory/packages. It does not place packages in
Integration Server_directory/
instance_name/replicate/inbound.
During package installation,
wpm compares the runtime version of the target
Integration Server with the value of the
target_server_version attribute in the package manifest. (The runtime version of an
Integration Server is located in the MANIFEST.MF file located in
Integration Server_directory\lib\wm-isserver.jar).
wpm does this to ensure that the functionality in the package is available in the target
Integration Server. One of the following occurs during comparison:
If the
target_server_version attribute is present in the package and the destination
Integration Server's runtime version is higher than or equal to the attribute value,
wpm installs the package into the destination folder.
If the
target_server_version attribute is present in the package and the destination
Integration Server's runtime version is lower than the attribute value,
wpm cancels the install operation and adds an error to the operation result.
If the
target_server_version attribute is present in the package but
wpm cannot determine the runtime version of the destination
Integration Server,
wpm cancels the install operation and adds an error to the operation result.
wpm might be unable to detect a version number due to reasons such as an invalid destination location, a missing JAR file, or a corrupted JAR file.
If the
target_server_version attribute is not present in the package,
wpm does not check the runtime version of the destination
Integration Server. Instead,
wpm installs the package and writes a warning message in the operation result. The
target_server_version attribute might be absent if the package was created in an
Integration Server version that does not support the
target_server_version attribute, which was added in
Integration Server version 11.1.
Examples Which Do Not Use the wpm.yml Configuration File
The following examples of the wpm install command outline common use cases which do not use the wpm.yml configuration file:
To install version 1.0.0 of package called PackageA from the specified GitHub repository into the specified target installation:
wpm install PackageA:1.0.0 -r https://github.com/[username]/ -u [username] -p [personal-access-token] -d [target-installation]
wpm accesses the GitHub repository using the provided username and token. When cloning from GitHub, wpm clones the https://github.com/[username]/PackageA repository.
If the repository contains a manifest.v3 file at the top level, wpm downloads the entire repository contents as the package body. Alternatively, if the repository does not contain the manifest.v3 file at the top level, wpm looks for a folder named PackageA within the repository.
To install the highest version of PackageA from the specified GitHub repository into the specified target installation:
wpm install PackageA -r https://github.com/[username]/ -u [username] -p [personal-access-token] -d [target-installation]
wpm accesses the GitHub repository using the provided username and personal access token. When cloning from GitHub, wpm clones the https://github.com/[username]/PackageA repository.
When resolving which version of the PackageA to install, wpm first looks for the highest numerical version in the repository tags and branches. If wpm cannot locate a version of PackageA in the tags and branches, wpm falls back to the main branch of the repository.
To install PackageA version 1.0.0 and the highest versions of PackageB and PackageC from the specified GitHub repository into the specified target installation:
wpm install PackageA:1.0.0 PackageB PackageC -r https://github.com/[username]/ -u [username] -p [git-token] -d [target-installation]
wpm accesses the GitHub repository using the supplied username and token [git-token].
To install the latest version of PackageA from the specified GitHub repository into the specified target installation:
wpm install PackageA -r https://github.com/[username]/ -k [private-key-location] -p [passphrase] -d [target-installation]
wpm accesses the GitHub repository using the private key file located at [private-key-location] and passphrase specified in [passphrase].
To install PackageA from the GitHub repository
[git-repo] into the specified target installation:
wpm install PackageA -r [git-repo] -j [oauth-token] -d [target-installation]
wpm uses the provided OAuth token [oauth-token] to access the repository.
To install the WmJDBCAdapter package from the default
IBM webMethods Package Registry repository into the specified target installation:
wpm install WmJDBCAdapter -ws https://packages.webmethods.io -wr licensed -u [empower-user] -p [empower-password] -d [target-installation]
wpm uses the Empower credentials [empower-user] and [empower-password] to log into the registry. wpm resolves the GitHub location information using the information contained in the registry and then proceeds to download and install the package.
To install the WmJDBCAdapter package from the default
IBM webMethods Package Registry repository into the target installation:
wpm install WmJDBCAdapter -ws https://packages.webmethods.io -u [empower-user] -p [empower-password] -d [target-installation]
wpm uses the supplied Empower credentials [empower-user] and [empower-password] to access the registry.
To install the WmJDBCAdapter package from the
IBM webMethods Package Registry into the specified target installation:
wpm install WmJDBCAdapter -ws https://packages.webmethods.io -wr licensed -j [oauth-token] -d [target-installation]
wpm uses the supplied OAuth token to access the registry.
Examples Which Use the wpm.yml Configuration File
The following examples of the wpm install command rely on information from the wpm.yml configuration file:
To install package PackageA from the GitHub repository my_packages for which connection information, including location, is defined in the wpm.yml configuration file:
wpm install PackageA -r my_packages
Example wpm.yml configuration file:
my_packages:
type: git
location: https://github.com/[username]
creds:
user: [username]
password: [personal-access-token]
working_dir: [working-dir-location]
To install package PackageA from a repository configured in the wpm.yml file into an target installation configured in the wpm.yml file:
wpm install PackageA
This approach works if the wpm.yml configuration file contains only one defined repository.
To install the WmJDBCAdapter package from the registry defined in the repositories section of the wpm.yml configuration file into the installation location specified in the wpm.yml configuration file:
wpm install WmJDBCAdapter
wpm uses the connection information in the repositories\wpm properties to connect to and access the registry.
Example wpm.yml configuration file:
repositories:
wpm:
type: wpr
location: https://packages.webmethods.io
registry: licensed
creds :
token : [oauth-token]
working_dir: ./Temp/repositories/