wpm install

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, webMethods Package Manager looks for the highest numerical version number available in the source repository. 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. Optionally, if you have multiple packages in the same repository, you can install a specific package by entering the full path to the package. For example: `https://github.com/[username]/Package_C`.
`-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 Software AG username. Optional. Required when you install 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 Package Manager 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 Package Manager checks for dependent packages and automatically installs them. If set to `false` or not present, Package Manager 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 Package Manager scans branches and tags in the repository for the specified version number of a packages. If set to `true`, Package Manager scans branches and tags; `false` scans only tags. Optional. The default is `true`.
`-kr {true\|false}`	Whether 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`.
`-kg {true\|false}`	Whether wpm retains the .git folder of the repository where the package is hosted. By default, when installing a package, wpm removes the .git folder. A value of `true` preserves the full GitHub metadata. Keeping the .git folder is helpful for debugging, testing, or contributing upstream. 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.
`-wr [package-manager-registry]`	Name of the registry in the IBM webMethods Package Registry from which to install packages. Unless specified, Package Manager uses the default registry you configured in the wpm.yml configuration file. 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, Package Manager 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 Package Manager 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. Package Manager is not in the same installation directory as the target server.
`-ks {true\|false}`	Whether Package Manager preserves the enabled or disabled state of a package. If the `-ks` argument is not supplied, Package Manager 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, Package Manager 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). Package Manager 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, Package Manager 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, Package Manager cancels the install operation and adds an error to the operation result.
- If the target_server_version attribute is present in the package but Package Manager cannot determine the runtime version of the destination Integration Server, Package Manager cancels the install operation and adds an error to the operation result. Package Manager 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, Package Manager does not check the runtime version of the destination Integration Server. Instead, Package Manager 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]
```
Package Manager accesses the GitHub repository using the provided username and token. When cloning from GitHub, Package Manager clones the https://github.com/[username]/PackageA repository.

If the repository contains a manifest.v3 file at the top level, Package Manager downloads the entire repository contents as the package body. Alternatively, if the repository does not contain the manifest.v3 file at the top level, Package Manager 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]
```
Package Manager accesses the GitHub repository using the provided username and personal access token. When cloning from GitHub, Package Manager clones the https://github.com/[username]/PackageA repository.

When resolving which version of the PackageA to install, Package Manager first looks for the highest numerical version in the repository tags and branches. If Package Manager cannot locate a version of PackageA in the tags and branches, Package Manager 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]
```
Package Manager 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]
```
Package Manager 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]
```
Package Manager 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 [username] -p [password] -d [target-installation]
```
Package Manager uses the Software AG credentials [username] and [password] to log into the registry. Package Manager 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 [username] -p [password] -d [target-installation]
```
Package Manager uses the supplied Software AG credentials [username] and [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]
```
Package Manager uses the supplied OAuth token to access the registry.
To install the WxCloudReadinessAnalyzer package from the public registry of IBM webMethods Package Registry into the specified target installation and preserve the .git folder:
```
wpm install WxCloudReadinessAnalyzer -ws https://packages.webmethods.io -wr public -d [target-installation] -kg true
```

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
```
Package Manager 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/
```