Installing Envision

Learn how to install the Envision analytics and monitoring solution.

Table of Contents

Installation Procedure: Completely new installation

Installation Procedure: Adding Envision to an existing installation

Installation Tasks/Reference

Upgrading the Akana API Platform and Moving to an Aggregation Rollup Strategy

Installation Procedure: Completely new installation

Introduction

Installation of the Envision 1.2.1 analytics and monitoring solution requires:

  • Installation of the applicable version of the Akana Platform.
  • Installation of the corresponding version of the PM Analytics Plugin. See Installation files below.
  • Installation and setup of a MongoDB database. For information on supported versions, see Supported MongoDB versions.
  • Setting up at least one Policy Manager container.
  • Installation and configuration of the Envision feature on the Policy Manager container.

Note: If you're installing Envision in a separate container from Policy Manager, see Installing Envision in its own container.

Installation files

Make sure you get the correct Envision installation file for your Akana API Platform version. The installation procedure is the same for all versions, other than the file versions and, potentially, any instructions stated to be only for a specific version.

You can download the file or files as part of Step 3: Download ZIP files for Envision and the PM Analytics Plug-In or at any point beforehand.

Note: Login to the download site is required.

To download the installation ZIP file

  1. Log in to the Rogue Wave Support Center (https://library.roguewave.com).
  2. In the My Resources section, click Product Downloads, and then click Akana - Product Downloads.
  3. Click the link for the applicable major release version.
  4. Expand the Plugins link at the top of the page. The available plugins are listed.
  5. Download the applicable file.

Review MongoDB Setup Guide

Before starting, install and configure MongoDB. For information and links to MongoDB documentation, refer to the MongoDB Setup Guide for Akana Envision.

Step 1: Install Akana Platform

The Envision product must be installed to the Akana Platform. For detailed instructions on installing the Akana Platform, refer to the installation documentation. Go to Installing the Akana API Platform.

If the Akana Platform is already installed, skip to the next step.

Step 2: Run Configurator to create a Policy Manager container

Note: If you're installing Envision in a separate container from Policy Manager, see Installing Envision in its own container.

The Configurator steps you through creating a container, specifying basic values about the container.

Create a Policy Manager container. For detailed instructions, refer to Run Configurator to create the first container and Install Policy Manager/Community Manager features on the container. You don't need to install Community Manager to run Envision, only the Policy Manager features. Choose features applicable for your installation, but at a minimum the Policy Manager features.

Step 3: Download ZIP files for Envision and the PM Analytics Plug-In

Envision and the PM Analytics Plug-In must be installed to the Akana Platform.

  1. Log in to the Rogue Wave Support Center (https://library.roguewave.com).
  2. In the My Resources section, click Product Downloads, and then click Akana - Product Downloads.
  3. Click Akana Envision Product Downloads.
  4. Expand the top section, and download the applicable Envision ZIP file or files.

Step 4: Install Envision into the Policy Manager container

For detailed instructions for installing Envision into the Policy Manager container, follow Existing Policy Manager installation: Steps for installing Envision.

Step 5: Install and Configure Sample Datasets

  1. On the Available Features screen, from the Filter menu at the top left, select Plug-ins.
  2. Select the Akana Sample Datasets for Demo Charts plug-in, and click Install Feature.
  3. After installation is complete, click Configure and continue.
  4. On the Configure Sample Datasets screen, select the checkbox for each dataset you want to install.
  5. Click Finish, and then click OK to restart the container.
  6. When the restart is complete, click Close.

Note: After the installation is compete, you can manage (install / uninstall) datasets via the Configuration tab by selecting Configure Sample Datasets.

For additional information, see Using the Akana Sample Datasets for Demo Charts Feature.

The next step is to install and configure Policy Manager.

Step 6: Launch Envision Console

  1. Enter the following URL to launch the Envision Console:

    http://{hostname}:{port}/analytics/login

  2. Log into the Envision Console using the Username/Password you defined for your Envision container, and then click the Dashboards tab.

    Note: Sign in using the Local Domain, not the Admin Console domain.

    Envision

  3. If you do not see the datasets and/or have problems logging into the Envision Console, restart the Envision container (See Starting and Stopping a Container Instance and refer to the MongoDB documentation for instructions on how to start MongoDB. For links to MongoDB documentation, refer to the MongoDB Setup Guide for Akana Envision.

Installation Procedure: Adding Envision to an existing installation

Prerequisites

You'll need the following:

Existing Policy Manager installation: Steps for installing Envision

The steps below assume an existing installation of a supported version of Akana API Platform. The installation should already have the Akana MongoDB Support plugin enabled for all Akana containers.

These steps are for manual installation of the Envision feature. If you want to use the automation script to enable this feature, please consult with your Akana Professional Services representative.

These steps cover installation of applicable components into:

  • The first Policy Manager container
  • Additional Policy Manager containers
  • Network Director containers

To install Envision in an existing Policy Manager installation

  1. Follow the file download and installation instructions for the applicable version of the Akana API Platform. Go to Installing the Akana API Platform. Follow the instructions for downloading the ZIP files and extracting the files.
  2. Choose one Policy Manager container for installation of Envision. It must be installed directly on one of the PM containers.
  3. Restart the container.

    After restart, you'll see the following Envision features or plug-ins in the Akana Administration Console for the container:

    • Akana Envision Metrics Collector (plug-in)
    • Akana Envision (feature)
    • Akana Envision Policy Manager Service Extensions (plug-in)
    • Akana Envision Policy Manager Console Extensions (plug-in)
    • Akana Policy Manager Analytics Security Provider (plug-in)
    • Akana Sample Datasets for Demo Charts (plug-in)
  4. Install the following feature:
    • Akana Envision
  5. Install the following plug-ins:
    • Akana Policy Manager Analytics Security Provider
    • Akana Envision Policy Manager Service Extensions
    • Akana Envision Policy Manager Console Extensions (choosing this option also installs the Akana Envision Metrics Collector plug-in)
  6. Restart the container.
  7. For any additional Policy Manager containers after the first: Conditional: if the PM container is installed on a different machine, repeat Step 1. Then, install only the following plug-ins:
    • Akana Envision Policy Manager Service Extensions
    • Akana Envision Policy Manager Console Extensions (choosing this option also installs the Akana Envision Metrics Collector plug-in)
  8. For all Network Director containers: Conditional: if the ND container is installed on a different machine, repeat Step 1. Then, install only the following plug-in:
    • Akana Envision Metrics Collector
  9. Log in to the Envision portal running on http://{PM/Envision URL}/analytics.

If you're running Envision in its own container, see Installing Envision in its own container for an installation feature list.

Installation Tasks/Reference

Database and Container Shutdown Procedure

When shutting down your Envision system, it's important to shut down the Envision container, and MongoDB database in the following sequence to avoid data loss and/or the requirement of performing data repair.

  1. First, shut down the container. Refer to Starting and Stopping a Container Instance for shutdown options.
  2. Then, shut down the MongoDB container. For information on installation instructions and shutdown procedures for your specific deployment, refer to the MongoDB documentation at this URL: https://docs.mongodb.org/v3.6/tutorial/manage-mongodb-processes.

Configuration Action: Configure Envision Time Zone

Data aggregation for Envision requires that you set up a Policy Manager rollup time zone to match the Envision time zone setting. When Envision retrieves data for a chart, it selects only records that match exactly the time zone set in this configuration action. If the Envision time zone isn't set, or is set incorrectly, charts might include data for an incorrect time period, or might not show any data at all, because of time zone differences.

Configuring the global time zone for rollups

Set the Default Time Zone, Rollup Time Zone, and Time Zone Alias, as needed.

Configuration properties: Configuring the denylist characters

Valid in Version: 2020.2.4 and later

You can configure the list of characters that are rejected in Envision when creating charts, dashboards, or database objects. There is a default set of values, but if you find you need to add to it, or remove characters that you want to allow, you can just change the list as needed.

A user trying to use one of the characters on the denylist, in Envision, sees an error message and cannot add the restricted character.

Navigation in the Akana Administration Console: Configuration tab > com.soa.analytics.console > analytics.validation.text.denylist.

Default set of denylist characters: `~!@#$%^&*()+=[]\\;/{}|:"<>?

Configuring the denylist characters

Remove characters from the denylist, or add new ones, as needed.

Supported MongoDB versions

For information on the MongoDB versions supported with Envision, refer to the System Requirements documentation for the applicable Akana Platform version: see System Requirements.

Installing Envision in its own container

You can install Envision on a separate container from the Akana API Platform, so that it's only reading data from the MongoDB database, not running on the same container where API traffic is processed and transactions are written to the database.

By running Envision in a separate container, you can avoid having to expose the Envision user interface and authentication on your main runtime container.

In this scenario, you still need to have Policy Manager installed on the container. This is needed so that you can use the local domain for authentication of the Envision user.

If the instance is on a separate machine, you'll need to get the ZIP files (see To install Envision in an existing Policy Manager installation, Step 1 above).

Then, if you're installing Envision into a standalone container, you'll need to make sure you install the following features in the different installation containers:

These are the minimum required features and/or plug-ins for each type of container, so that a standalone container running Envision will work correctly.

Standalone Envision container

Features:

  • Akana Policy Manager Console
  • Akana Policy Manager Services
  • Akana Envision

Plug-ins:

  • Akana Policy Manager Analytics Security Provider

Primary Policy Manager container

Plug-ins:

  • Akana Envision Policy Manager Service Extensions
  • Akana Envision Policy Manager Console Extensions (choosing this option also installs the Akana Envision Metrics Collector plug-in)

Network Director containers

Plug-ins:

  • Akana Envision Metrics Collector

Upgrading the Akana API Platform and Moving to an Aggregation Rollup Strategy

Upgrading the Akana API Platform

Learn how to upgrade the Akana API Platform from an earlier version to version 2024.1.x. For more information, see Upgrading the Akana API Platform.

Moving to an Aggregation Rollup Strategy

You can upgrade the aggregation criteria using an automation recipe, see Upgrading Aggregation Criteria using an Automation Recipe.