# OM View™ Plug-in for Zowe™ CLI <!-- omit in toc -->

The OM View™ Plug-in for Zowe™ CLI lets you interact with OM View for z through
a Zowe™ CLI plug-in.

- [Use cases](#use-cases)
- [Software requirements](#software-requirements)
- [Install the Plug-in](#install-the-plug-in)
- [Configure the Plug-in](#configure-the-plugin)
- [Migrate from Zowe™ v1 LTS](#migrate-from-zowe-v1-lts)
- [Migrate to Zowe™ v3 LTS](#migrate-to-zowe-v3-lts)
- [Getting Started](#getting-started)
- [Uninstall the Plug-in](#uninstall-the-plug-in)

# Use cases

The plug-in lets you perform the following operations on OM View data:

- Query repositories (OM View databases), reports, and export rules.
- Query report logical views and index values.
- Search for report data using cross-report indexes.
- Download report data and convert text reports to PDF.
- Use predefined export rules to export text reports to spreadsheets.
- Query and change user settings.

# Software requirements

Before you install and use the plug-in:

- Install [Zowe™ CLI](https://www.npmjs.com/package/@zowe/cli).
- Ensure that an [OM Web Viewer for z](https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/traditional-management/web-viewer/14-0.html)
instance is installed and running in your mainframe environment. The instance must meet __one__ of the following minimum requirements:
    - Release 14 service pack 0000.
    - Release 14 service pack INC00 with PTF SO10218 applied.
- (Optional) The ability to use OM View permanent filters as part of the `download report` command
  requires PTF SO11441 to be applied.

# Install the Plug-in

To install the `@latest` version of the plug-in, issue the following command:

```
$ zowe plugins install @broadcom/caview-for-zowe-cli
```

__Note:__ The `@latest` npm tag installs an active development version of the plug-in, which accepts breaking changes. You can use different npm tags to install other versions of the product. For more information about tag usage, see [NPM Tag Names](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md#npm-tag-names).

# Configure the Plugin

You can set `caview` profile options in your configuration, so you do not have to type your
connection details for every command. The profile options include connection and authentication
information for the OM Web Viewer REST API instance of your choice.

**Example**

Use the following command to initialize your global Zowe™ CLI configuration: `zowe config init --global-config`

This command results in a prompt for basic information that is shared between multiple Zowe™ CLI
plugins and populates your global configuration.

You can subsequently use one of the following methods to customize the values in the global
configuration:

- Use the `zowe config edit --global-config` command to open the whole configuration file in your default text editor.
- Use the `zowe config set --global-config <option> <value>` command to set individual values. The `caview` plugin profile supports the following specific options:
    - `protocol`
    - `host`
    - `port`
    - `base-path`
    - `user`
    - `password`

**Example**

Use the following command to update the `port` value in your `caview` global configuration profile
to 8080:

```
zowe config set --global-config profiles.caview.properties.port 8080
```

You can create multiple profiles and switch between them as necessary. You can also have global,
user, and shared configurations. For full details on all of these options refer to the general Zowe™
CLI documentation.

# Migrate from Zowe™ v1 LTS

After you upgrade from a v1 LTS version of the Zowe™ CLI to a v2 LTS version, your existing profiles
continue to function. However, if you want to take full advantage of the improved configuration
functionality, convert your v1 profiles to their v2 counterparts.

To convert your legacy profiles to the new configuration format in your global configuration, use
the `zowe config convert-profiles` command.

# Migrate to Zowe™ v3 LTS

The plug-in package name has changed starting with the Zowe™ CLI v3 LTS version.
Specifically, the name has changed from `@broadcom/caview-for-zowe-cli` to `@broadcom/om-view-for-zowe-cli`.

In order to migrate, you must first uninstall the old package using the following command:

```
$ zowe plugins uninstall @broadcom/caview-for-zowe-cli
```

After you uninstall the old package you can install the new package using the following command:

```
$ zowe plugins install @broadcom/om-view-for-zowe-cli
```

Note that the plug-in command group and profile names have also changed from `caview` to `omview`.
While the old `caview` variants are still supported, we encourage you to update your configuration
files and scripts, replacing `caview` with `omview` in all cases.

# Getting Started

To get help for the available command groups, issue the following command:

```
$ zowe caview --help
```

For example, you might start by listing the available repositories:

```
$ zowe caview list repositories
```

To obtain context-sensitive help, append the `--help` argument to your command.
For example, to get help with the `list reports` command, issue the following command:

```
$ zowe caview list reports --help
```

# Update the Plug-in

To update the plug-in, issue the following command:

```
$ zowe plugins update @broadcom/caview-for-zowe-cli
```

# Uninstall the Plug-in

To uninstall the plug-in, issue the following command:

```
$ zowe plugins uninstall @broadcom/caview-for-zowe-cli
```