Upgrading Akana API Platform from Version 8.2 to Version 8.4x

Learn how to upgrade from Akana API Platform 8.2x to 8.4x.

Note: If you're upgrading Policy Manager for DataPower, follow the steps in this document that you would use for upgrading Network Director.

Note: This document covers instructions for the combined features available in version 8.4x. For versions prior to 8.4x, see http://docs.akana.com/ag/assets/AAP_80_82_Upgrade_Guide.pdf.

Micro-Upgrade: If you're upgrading to a micro version—for example, 8.4.1 to 8.4.22—it's important to follow through the entire upgrade procedure. For additional notes and information about upgrading to a micro version, see Micro-Version Upgrade.

Using Admin Console Installing Tools Installing Plug-ins

Configuration Categories Configuration Actions

Supported Platforms: 8.4x

Table of Contents

Planning the Upgrade
  1. Overview
  2. Step 1-1: Review release notes
  3. Step 1-2: Plan the upgrade for additional features
  4. Step 1-3: Gather ZIP files and create folder
Performing the Upgrade
  1. Overview
  2. Step 2-1: Turn off scheduled jobs
  3. Step 2-2: Back up and stop all containers for previous version
  4. Step 2-3: Extract new ZIP files in sequence
  5. Step 2-4: Copy applicable version 8.2 files to version 8.4 folder
  6. Step 2-5: Clear Configurator cache (if needed)
  7. Step 2-6: Upgrade container
  8. Step 2-7: Upgrade additional containers
  9. Step 2-8: (Conditional): Unregister and re-register the Windows service
  10. Step 2-9: Start the containers
  11. Step 2-10: Clear browser cache
  12. Step 2-11: Launch the Akana Administration Console
  13. Step 2-12: Refresh repository
  14. Step 2-13: Verify that features were updated correctly
  15. Step 2-14: Run pending installation tasks and restart container
  16. Step 2-15: Upgrade all containers before installing the upgrade tool
  17. Step 2-16: Install and run upgrade tool: "Akana 8.2 to 8.4 model upgrade" (CM containers only)
  18. Step 2-17: Turn scheduled jobs back on
  19. Step 2-18: Update container metadata and authentication options
Post-Upgrade Tasks
  1. Upgrade tasks when upgrading to 8.4: Overview
  2. Step 3-1: Post-Upgrade Tasks for upgrades to 8.4: Provisioning
  3. Step 3-2: Post-Upgrade Tasks for upgrades to 8.4: Upgrade CM Models
  4. Step 3-3: Post-Upgrade Task for upgrades to 8.4: Rebuild CM Styles
  5. Step 3-4: Repeat configuration actions for additional containers and restart all containers
  6. Step 3-5: Post-Upgrade task when upgrading to 8.4: delete and install object mappings
  7. Step 3-6: Post-Upgrade Task for upgrades to 8.4: MongoDB Updates
  8. Step 3-7: Conditional, MongoDB/OAuth: Post-Upgrade Task for Data Migration
Upgrade Procedures/Reference:
  1. Contacting Akana Technical Support
  2. Container upgrade sequence
  3. Troubleshooting: error: "Some of the model objects are not updated"
  4. Upgrading by creating new containers: notes

Planning the Upgrade

Overview

There are some steps you might need to take before starting the upgrade process, and some information you'll need to consider to determine how to proceed, including:

  • Review the Akana API Platform release notes.
  • Plan the upgrade for additional features.
  • Gather ZIP files and create folder.
  • Check if there are any constraints or requirements associated with the type of database you're using, such as permissions required. For details, see Database Notes (install doc).

back to top

Step 1-1: Review release notes

Review the release notes so that you are aware of changes to the platform. Check for upgrade notes.

Release notes are available from the Rogue Wave Support Center (https://library.roguewave.com).

back to top

Step 1-2: Plan the upgrade for additional features

If you have a specific add-on feature installed, such as the Integration Services option pack, SiteMinder Security Provider, or SAML Web SSO Security Provider feature, it's important that you download the new release version package for the same feature.

Note: In version 8.2, some of the additional packages have been incorporated into the Akana API Platform along with Community Manager and Policy Manager. Depending on the additional features you're using, you might not have to install updates.

If one of the features is installed in a container that you copy over from the earlier version during the upgrade process, and you don't upgrade the add-on, container startup might fail after you complete the upgrade process. When you upgrade, make sure you have the latest version for any features you're using. See Step 2-13: Verify that features were updated correctly.

Note: The SAML Web SSO feature remains at version 8.0. There is no upgrade to version 8.4.

back to top

Step 1-3: Gather ZIP files and create folder

Before starting the upgrade, gather all the ZIP files from the Rogue Wave Support Center (https://library.roguewave.com, and collect any other information needed for the entire process.

You'll need all the ZIP files listed below. They are listed in the order in which they should be installed.

All files listed below are available from the Rogue Wave Support Center (https://library.roguewave.com). In the My Resources section, click Product Downloads, then click Akana - Product Downloads.

You'll need to install files for:

  1. The Akana Platform: an OSGI environment. Akana features run within this environment, obey its constraints, and make use of its facilities. The platform supports Windows and Unix (Linux, Solaris, AIX) environments.
  2. The Akana API Platform.
  3. Add-Ons: Any platform add-ons you are using that are not included in the Akana API Platform.
Gather ZIP files and create folder
  1. On your installation machine, create a folder for the new version: for example, AP84 for API platform 8.4.
  2. In this folder, copy all the ZIP files listed below. You should have at minimum two files, with additional files if there are updates and/or add-ons.
ZIP files for upgrade to version 8.4
  1. To upgrade the Akana platform, first locate the appropriate file for the operating system you're using. You'll see the below or a later version (online doc not yet updated):
    1. Windows (includes JRE): akana-platform-win-jre-8.4.xxx.zip
    2. Linux only (includes JRE): akana-platform-linux-jre-8.4.xxx.zip
    3. Windows, Linux, or Solaris (does not include JRE; provide your own JRE, version 1.8): akana-platform-8.4.xxx.zip

      Note: When using this JRE you must modify the bin/setDEMS.sh script and comment out lines that relate to your JRE and then ensure you have JAVA set correctly.

  2. Check if there are any Akana platform updates. If there are any updates, locate the latest cumulative update ZIP file.

    Note: Akana API Platform 8.4 requires Akana Platform 8.4.

  3. To upgrade the Akana API platform to version 8.4, locate the file below, which contains all necessary files for Akana API Platform installation, including Policy Manager and Community Manager installation:
    • akana-api-platform-8.4.xxx.zip
  4. Check if there are any Akana API platform updates. If there are any updates, locate the latest cumulative update ZIP file. For example:

    akana-api-platform-update-cumulative-8.4.1.zip

ZIP files for add-ons

Check the Rogue Wave Support Center (https://library.roguewave.com) for the latest ZIP file for any additional add-ons you are using in your installation. In the My Resources section, click Product Downloads, then click Akana - Product Downloads. Get all applicable update files for your installation. You'll extract these after the other files.

For product compatibility information, refer to the applicable matrix in the Rogue Wave Support Center (https://library.roguewave.com).

Note: For notes about limitations and extra steps for specific databases, see Supported databases (install doc). If you're using a MySQL database with API Platform and the Lifecycle Repository feature, see Database notes: MySQL with Lifecycle Repository.

back to top

Performing the Upgrade

Overview

Note: The instructions in this document are for upgrade from Akana API Platform 8.2 to Akana API Platform 8.4. If you're upgrading from a version earlier than 8.2, you'll need to perform additional steps first, to upgrade to Policy Manager 8.0. For instructions, see http://docs.akana.com/ag/assets/AAP_80_82_Upgrade_Guide.pdf.

At a high level, to perform the upgrade, you'll complete the following actions:

  1. Install the Akana API Platform 8.4 in a new location.
  2. Copy the AP82 container instances to the instances folder for the AP84 installation (except the configurator instance).
  3. Perform the upgrade steps from the AP84 installation, following the exact sequence given below.

back to top

Step 2-1: Turn off scheduled jobs

Before upgrading, you must turn off scheduled jobs in the configuration settings, including the following two scheduled jobs in this sequence:

  1. com.soa.scheduler.quartz
  2. simple.scheduler.enabled

When upgrade is complete, you'll turn these properties back on again (see Step 2-17: Turn scheduled jobs back on).

Note: Perform this step for all AP84 containers with Policy Manager features installed.

To turn off scheduled jobs
  1. Log in to the Akana Administration Console using Administrator credentials.
  2. Click the Configuration tab.
  3. In the Configuration Categories section, find com.soa.scheduler.quartz.
  4. Locate the org.quartz.scheduler.enabled property and change it to false.
  5. Click Apply Changes.
  6. In the Configuration Categories section, find com.soa.scheduler.
  7. Locate the simple.scheduler.enabled property and change it to false, as shown below.

    Turning off scheduled jobs

  8. Click Apply Changes.

back to top

Step 2-2: Back up and stop all containers for previous version

The next step is to back up and stop the current version, before you upgrade. Follow the steps below.

To back up and stop version 8.2
  1. Stop any containers that are currently running.

    This is required to update the database schema to AP84. Stopping the containers ensures that the database is not locked while the update is in progress. For more information, refer to Starting and Stopping a Container Instance.

  2. Back up your AP82 database, using your database management tool, and save the backup file to a safe location. For example, if you're using MySQL, the backup command might look something like the below:
    C:\Program Files\MySQL\MySQL Server 5.6\bin>mysqldump.exe -e -u root -p -h localhost AP82 > C:\backups\ap82-20170331
  3. Back up your AP82 release directory, and save the backup file to a safe location.

back to top

Step 2-3: Extract new ZIP files in sequence

Now you're ready to install the new version. Make sure you install from the various ZIP files in the correct sequence.

Note: the filenames used below are examples. When you download files from the Rogue Wave Support Center (https://library.roguewave.com), you might have an updated variation.

To extract the new ZIP files

Note: When unzipping files, if you are prompted to replace a file, choose All to accept all the new files.

  1. Go to the folder with the downloaded ZIP files, which you created earlier. See Step 1-3: Gather ZIP files and create folder.

    Make sure the folder includes all the ZIP files you'll need for upgrade. You should have at least two files, and possibly more, as detailed in ZIP files for upgrade to version 8.4.

  2. Extract the Akana platform files:
    1. Main platform file: extract akana-platform-win-jre-8.4.xxx.zip or comparable file for Linux or other operating system.
    2. Possible updates: If there are any updates for the Akana Platform, extract the update next.
  3. Extract the Akana API Platform files (contains all necessary files for Policy Manager and API Platform/Community Manager installation):
    1. Main API Platform file: extract akana-api-platform-8.4.xxx.zip.
    2. Possible updates: If there are any updates for the Akana API Platform, extract the update next.
  4. Extract the ZIP files for any add-ons you're using.

Note: After the installation is complete, do not launch the Configure Container Instance Wizard/configure the API Platform container until you've completed the next step, below.

back to top

Step 2-4: Copy applicable version 8.2 files to version 8.4 folder

The next step is to copy container instances to your new installation.

Note: Do not copy the Configurator instance.

To copy version 8.2 files to version 8.4 folder
  1. Go to the AP82 backup directory, and locate the AP82 container instances. For example: AP82/instances/{instance}
  2. Copy the AP82 container instances. Note:
    • Include AP82, Network Director, and Agent container instances.
    • Do not include the AP82 configurator or the AP82 default container folder.

      An example is shown below.

      Copy container instances

  3. In the AP84 container instances folder (AP84/instances/{pm_instance}, paste the container instances that you copied.
  4. Delete the log folder so that the logs will only include information for the new version, not for the old version.

back to top

Step 2-5: Clear Configurator cache (if needed)

Before performing the upgrade, make sure the configurator cache is clear. At this point, there won't be any cache unless you launched the Configurator at the end of Step 2-3. To be sure, follow the steps below.

To clear configurator cache
  1. Locate the configurator cache folder: \instances\configurator\cache, as shown below.

    Configurator cache folder

  2. Delete the folder if it exists (if there is no cache, the folder will not be there).

back to top

Step 2-6: Upgrade container

You'll need to perform the upgrade procedure on each container you're upgrading to AP84, using the Configure Container Instance wizard.

Note: These instructions follow a sequence of upgrading the first Policy Manager container, then additional Policy Manager and Community Manager containers, and then Network Director and Agent containers. However, once you've done an initial Policy Manager upgrade to upgrade the database, the sequence of containers really doesn't matter. See Container upgrade sequence below.

Note: Before you upgrade, make sure you've completed all previous steps, including copying the container instances (see Step 2-4: Copy applicable version 8.2 files to version 8.4 folder).

There are three ways you can upgrade the container:

Upgrade container to Akana API Platform 8.4 (GUI)

Upgrade via the GUI launches the Configurator wizard, which walks you through the upgrade process.

To upgrade the container to Akana API Platform 8.4 (via the GUI)
  1. Open up a command prompt.
  2. Go to the new folder where you unzipped the version 8.4 files, then navigate to the \bin subfolder and run the following command:
    startup configurator
  3. The Configurator starts, and the Welcome to Configure Container Instance Wizard page displays. Click Next.
  4. At the Instance Name screen, specify the name of the Akana container instance the upgrade will be applied to, as shown in the example below (same name as previous installation). Leave the Container Key field blank; the upgrade process will use the container key for the container being upgraded. Click Next.

    Instance Name page

  5. At the Instance Already Exists page, to apply the AP82 to AP84 upgrade, click Update, as shown below, and then click Next. Note: This updates the instance you copied over in Step 2-4: Copy applicable version 8.2 files to version 8.4 folder.

    Instance Already Exists message

  6. At the Instance Configuration Summary page, shown below, verify that the instance has been stopped, and then click Finish.

    Instance Configuration Summary page

  7. When the container update process is complete, the Update Complete page displays with a summary of the number of bundles that were updated.
  8. Click OK to close the wizard.

back to top

Upgrade container to Akana API Platform 8.4 (silent upgrade)

You can set up the Configure Container Instance Wizard update process to run in an automated mode (silent mode).

To do this you essentially need to set up a properties file that contains a set of property values that the wizard uses to automatically configure a container instance.

To upgrade to Akana API Platform 8.4 using silent mode
  1. Define a properties file for upgrade in silent mode:
    1. Choose a file name; for example, upgrade.properties.
    2. In the file, add the following default content:
      container.instance.name=[container_instance_name]
      wizard.mode=update

      For example:

      container.instance.name=policymanager
      wizard.mode=update
  2. Determine system properties you want to use when running the upgrade in silent mode. There are two possible properties, which together are used to perform the silent upgrade:
    1. silent (If true, silent configuration will be performed)
    2. properties (path/filename for properties file to be used for configuration)
  3. Run the upgrade in silent mode, using either of the following commands, depending on the operating system:
    • Windows:
      \bin>startup.bat configurator "-Dsilent=true" "-Dproperties={property file directory location}\upgrade.properties"
    • Unix:
      /bin>startup.sh configurator -Dsilent=true -Dproperties=opt/{property file directory location}/upgrade.properties
  4. Repeat for Network Director or Agent containers:
    1. Before upgrading each instance, clear configurator cache. See Step 2-5: Clear Configurator cache (if needed).
    2. Then, for each container, repeat the steps above.
  5. Optional post-upgrade step for silent mode users not using the Admin Console:
    1. If you will not be using the Akana Administration Console, you can install the Policy Manager 8.4.0 schema manually using a third-party database schema management tool.
    2. For assistance in installing the schema, contact Akana Customer Support.

Note: If you are not using the Akana Administration Console, you are done with the upgrade; skip the rest of the upgrade steps.

Upgrade container to Akana API Platform 8.4 (command line)

You can also perform the upgrade process from the command line. Follow the steps below.

To upgrade to Akana API Platform 8.4 from the command line
  1. Execute the following in the \bin folder depending on your operating system:
    • Windows:
      startup.bat configurator "-Dsilent=true" "-Dcontainer.instance.name={Instance name}"  "-Dwizard.mode=update"
    • Unix:
      startup.sh configurator -Dsilent=true -Dcontainer.instance.name={instance name} -Dwizard.mode=update

back to top

Step 2-7: Upgrade additional containers

Repeat the upgrade process for all additional containers. A suggested sequence is:

  1. First, any additional containers running Policy Manager and/or the API Platform.
  2. Then, any Network Director or Agent containers.

Note: These instructions follow a sequence of upgrading the first Policy Manager container, then additional Policy Manager and Community Manager containers, and then Network Director and Agent containers. However, once you've done an initial Policy Manager upgrade to upgrade the database, the sequence of containers really doesn't matter. See Container upgrade sequence below.

To upgrade additional containers
  1. Before upgrading each instance, clear configurator cache. See Step 2-5: Clear Configurator cache (if needed).
  2. Then, for each container, repeat Step 2-6: Upgrade container.

back to top

Step 2-8: (Conditional, Windows only): Unregister and re-register the Windows service

If your containers are registered as a Windows service, so that the container will start automatically when Windows starts, you must unregister the old version and register the new version, for each container.

If you're not sure which containers are registered as a Windows service, you can check in the Windows Control Panel (Administrative Tools > Services). To change the services, you must run as Administrator.

To unregister and register the Windows service
  1. Open a command prompt in Administrator mode (If you don't use Administrator mode, Windows prompts for Admin permission before unregistering/registering the service, but doesn't actually start the service).
  2. Unregister the previous version as a windows service:
    .\{AP82_install_folder}\bin\unregisterContainerServiceYAJWS.bat {instance_name}
  3. Register the new version as a Windows service:
    .\{AP84_install_folder}\bin\registerContainerServiceYAJWS.bat {instance_name}
  4. If you're running in Administrator mode, Windows registers the service and also starts it.
  5. Repeat steps 2 and 3 for each additional container that's registered as a Windows service.

back to top

Step 2-9: Start the containers

Note: If you registered your containers as Windows services, in the previous step, the containers should already be running.

There are several ways you can start a container: Windows, as Windows service, or Unix. Follow the applicable procedure below.
To start the container (Windows)
  1. Navigate to the \{AP84_install_folder}\bin\ folder.
  2. Type the following:
    startup {instance_name}
To start the container (as Windows service)
  1. Launch the Program Group (Settings > Control Panel > Administrative Tools > Services).
  2. Select the Akana Container Instance (the instance name is displayed as the Container Key).
  3. From the Actions menu, select Start.
To start the container (Unix)
  1. Navigate to the /{AP84_install_folder}/bin/ folder.
  2. Type the following:
    startup.sh {instance_name}
To start the container (Unix, Background)
  1. Navigate to the /bin folder.
  2. Type the following:
    startup.sh {instance_name} -bg

back to top

Step 2-10: Clear browser cache

Before launching the Akana Administration Console, clear the browser cache and then refresh the page, or start a new session in a browser private window. This ensures that you see the user interface changes included in the update.

This completes the product installation. The next steps walk you through additional updates you'll need to make to complete the process, including updating database schemas and data.

back to top

Step 2-11: Launch the Akana Administration Console

Now it's time to launch the Administration Console and complete the installation tasks.

Note: The rest of the installation tasks are completed on containers running PM/CM only. There is no need to run them on Network Director containers.

To launch the Akana Administration Console
  1. Launch the Akana Administration Console for the updated container instance:
    http://{hostname}:{port}/admin
  2. Log in to the Akana Administration Console as an Administrator. The Akana Administration Console launches and displays the Available Features tab, as shown below.

    Available Features tab

back to top

Step 2-12: Refresh repository

Verify that the repository is there. Refresh if needed.

To verify/refresh the repository
  1. Click the Repository tab and verify that the Akana Platform Repository 8.4.0 and the Akana API Platform Repository 8.4.0 are both present, as shown below.

    Repository tab

  2. Conditional: if you don't see both these repositories, click Refresh to update.

Further installation steps are conditional:

  • If your container doesn't have Policy Manager features installed (Akana Policy Manager Console and Akana Policy Manager Services), the upgrade is complete.
  • If your container does have Policy Manager features installed (Akana Policy Manager Console and Akana Policy Manager Services), continue.

back to top

Step 2-13: Verify that features were updated correctly

At this point, check that all the features installed in your implementation have been correctly upgraded to the new version you're installing:

  1. In the Akana Administration Console, go to Installed Features.
  2. Look at the Version column to make sure each feature has the correct version number. An example is shown below.

    8.4 features installed tab

If there are any issues, check that you followed all steps correctly.

If needed, contact Technical Support.

back to top

Step 2-14: Run pending installation tasks and restart container

Once you've installed and configured the Policy Manager features (Akana Policy Manager Console and Akana Policy Manager Services) on your container, the next step is to run any pending installation tasks. Some tasks start automatically; some might need to be started manually.

Pending Installation tasks should include at least the below:

  • Manage Schemas: Updates the database schemas for the new version. This task needs to be done only once.
To run pending installation tasks

Note: Pending installation tasks might vary according to your upgrade process. When you click Complete Configuration, the upgrade process leads you through tasks.

  1. In the Akana Administration Console, go to Installed Features > Pending Installation Tasks. At the bottom left, click Complete Configuration, as shown below.

    Click Complete Configuration

  2. The Manage Schemas wizard starts. In the Available Schemas section, add the schemas listed. It should look something like the below. There might be variations depending on the features you're using. Click Finish.

     Available Schemas section

  3. The schemas are installed. At the summary page, click Next Task if there is another task. Otherwise, click Finish.
  4. Restart the container. Note: If the container doesn't restart automatically, restart it manually.
  5. Check to make sure all the bundles have started correctly: In the Admin Console, go to the System tab. It should show a lifecycle state of STARTED for all bundles, with no errors listed, as shown below.

    Check that bundles are running

back to top

Step 2-15: Upgrade additional containers

Make sure:

  • All containers are upgraded.
  • Pending installation tasks are complete for all containers.
  • All bundles start correctly for each container.

Essentially, make sure all steps, from Step 2-5: Clear Configurator cache (if needed) through to Step 2-14: Run pending installation tasks and restart container, are complete for every container.

back to top

Step 2-16: Install and run upgrade tool: "Akana 8.2 to 8.4 model upgrade" (CM containers only)

The next step is to run the 8.2 to 8.4 upgrade tool, to update database objects from version 8.2 to 8.4.

This step is applicable only if Community Manager is installed on the container. If the container doesn't include Community Manager, skip to Step 2-17: Turn scheduled jobs back on.

Before running this tool, change the failure.data.capture.enabled setting in the configuration file. Changing this setting will save memory for logging events during the upgrade process. It's important to change this setting; if you don't, there might be memory issues during upgrade. If you want to, you can change the setting back afterwards. When set to true, this setting indents entries in the log file.

Follow these three steps:

  1. Step A: To turn off the failure.data.capture.enabled configuration setting
  2. Step B: To install and run the 8.2 to 8.4 upgrade tool
  3. Step C: To restore the failure.data.capture.enabled configuration setting

Note: Perform these steps only once, on one container that has database connectivity and has Policy Manager Service installed.

Step A: To turn off the failure.data.capture.enabled configuration setting
  1. Log in to the Akana Administration Console for your upgraded installation, using Administrator credentials.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, find the com.soa.framework category.
  4. Locate the failure.data.capture.enabled property and change it to false, as shown below.

    Changing the failure.data.capture.enabled property

  5. Click Apply Changes.
Step B: To install and run the 8.2 to 8.4 upgrade tool
  1. Launch the Akana Administration Console for your upgraded installation, using Administrator credentials.
  2. Click the Available Features tab.
  3. From the Filter drop-down, select Tool.
  4. Select Akana 8.2 to 8.4 model upgrade, as shown below, and click Install Feature. The upgrade tool is installed.

    8.2 to 8.4 upgrade tool

  5. At the Installation Complete message, click Configure.
  6. At the Perform 8.2 to 8.4 upgrade page, make sure Upgrade APIs is checked, as shown below, and click Finish.

    Upgrade tool configuration

  7. At the system restart prompt, click OK to restart.
Step C: To restore the failure.data.capture.enabled configuration setting

Log in to the Akana Administration Console, using the instructions in Step A: To turn off the failure.data.capture.enabled configuration setting. Change the setting back to true, and save the changes.

back to top

Step 2-17: Turn scheduled jobs back on

Now it's time to turn back on the properties that you turned off in Step 2-1. Restart the scheduled jobs in the opposite sequence; first the simple scheduler, and then the Quartz scheduler.

Note: Perform this step for all the AP82 containers with Policy Manager features installed, which have now been upgraded to AP84. Before performing this step, make sure the container was restarted.

To turn scheduled jobs back on
  1. Log in to the Akana Administration Console using Administrator credentials.
  2. Click the Configuration tab.
  3. In the Configuration Categories section, find com.soa.scheduler.
  4. Locate the simple.scheduler.enabled property and change it to true.
  5. Click Apply Changes.
  6. In the Configuration Categories section, find com.soa.scheduler.quartz.
  7. Locate the org.quartz.scheduler.enabled property and change it to true.
  8. Click Apply Changes.

back to top

Step 2-18: Update container metadata and authentication options

The final step in the upgrade process is to update the Metadata URL and Authentication Options of each container you upgraded, in Policy Manager. This updates the container capabilities to support the latest features.

To update container metadata and authentication options
  1. Log in to the Policy Manager Management Console as the Administrator.
  2. In the left pane, from the Containers folder, select the AP84 container.
  3. In the right pane, from the Actions Portlet, select Update Container Metadata, as shown below.

    Update Container Metadata

  4. Enter the metadata URL for the container being updated (http://{pm_host}:{pm_port}/metadata or http://{nd_host}:{nd_port}/metadata), or the metadata path for the Network Director. An example is shown below.

    Metadata path for the ND

  5. Conditional: If Authentication options are being used or updated, select the authentication options.
  6. If the metadata URL is not accessible from Policy Manager, you can update the metadata from a file:
    1. First, access the metadata URL from a machine that has access to the container and save the metadata document to a file.
    2. Then, upload the file to Policy Manager.

That completes the upgrade.

After upgrading, run the post-install tasks on one of the containers with the Akana API Platform feature installed, as covered in the next group of tasks.

back to top

Post-Upgrade Tasks

Upgrade tasks when upgrading to 8.4: Overview

Once you've completed the product version update, there are additional post-upgrade tasks you'll need to complete. Run these tasks on one of the containers with the Akana API Platform feature installed. Some of these steps are conditional depending on platform features you're using. They include:

back to top

Step 3-1: Post-Upgrade Tasks for upgrades to 8.4: Provisioning

If you're upgrading from any previous version to version 8.4, you'll need to complete the Provisioning task as part of the upgrade process, in all containers where the Policy Manager feature is installed.

The provisioning step must be completed for each container running PM/CM.

To complete the Provisioning configuration action
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose the Provisioning configuration action, as shown below.

    Running Provisioning manually

  3. On the Provisioning page, make sure Perform Provisioning is checked, as shown below, and then click Finish.

    Provisioning Summary

  4. When provisioning is complete, click Close.

back to top

Step 3-2: Post-Upgrade Tasks for upgrades to 8.4: Upgrade CM Models

If you're upgrading from any previous version to version 8.4, you'll need to complete the Upgrade CM Models configuration action as part of the upgrade process, in all containers where the Community Manager feature is installed.

To complete the Upgrade CM Models configuration action
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose Upgrade CM Models.

    Note: if you get an error after running this process, see Troubleshooting: error: "Some of the model objects are not updated".

  3. When done, click Close.

back to top

Step 3-3: Post-Upgrade Task for upgrades to 8.4: Rebuild CM Styles

As part of every upgrade, if you are using the developer portal, you'll need to run the Rebuild CM Styles configuration action as part of the upgrade process, in all containers where the Community Manager feature is installed.

This makes sure that you have the latest style updates, for all themes and tenants.

To rebuild CM styles
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose Rebuild CM Styles.
  3. When done, click Finish.

back to top

Step 3-4: Repeat configuration actions for additional containers and restart all containers

You might need to repeat some of the configuration actions for additional containers.

To complete configuration actions
  1. Repeat these tasks as needed for additional containers:
    1. Step 3-1
    2. Step 3-2
    3. Step 3-3
  2. Stop and restart all containers.

back to top

Step 3-5: Post-Upgrade task when upgrading to 8.4: delete and install object mappings

Because of specific changes in the Elasticsearch mappings in version 8.3 and 8.4, as part of the upgrade process you'll need to delete the object mappings, and then add the updated mappings. This is because an additional object, Organizations, was added.

You'll need to delete the existing Elasticsearch app and API mappings and then update app, API, and business organization mappings from the installation bundle.

There are three steps to this:

  1. In the Policy Manager console, grant admin permissions to send API calls, to the current user. This is needed so that Step 2 will be successful. If you don't complete this step, the API calls return a 401 (unauthorized) response. See To grant Admin permission below.
  2. Delete mappings using the API: see To delete mappings using the API below.
  3. Run a database script: see To reindex objects using a database script below.
To grant Admin permission
  1. Log in to the Policy Manager console as the Administrator.
  2. Click the Workbench tab and then, on the left, click Registry.
  3. On the right, click the Security tab, as shown below.

    Add permissions: Security tab

  4. In the right pane, scroll down to the Role Memberships section, and find the System Administrator role. On the right, click Manage Role, as shown below.

    Add permissions: modifying the permission

  5. In the Object Based Security Role page, use the search feature to locate the user. In the example below, choosing Contains with no value and clicking Save returns a full list of users. Click the username in the left pane and click the arrow icon (>>) to move the admin user to the right pane, to assign the role.

    Add permissions: assigning user to role

  6. Click Apply. The admin user now has the System Administrator role and can use the API.

Note: You can also grant permissions in the developer portal: Administration > Users. See How do I assign security roles to users for my organization? However, you might find that the System Administrator permission isn't displayed on the list.

To delete mappings using the API

Note: When running the API operations below:

  • Replace {protocol}:{hostname} with the URL for the container.
  • Log in first. You'll need values from the login response to authenticate so that you can run these operations. For information on the login operation, refer to the API documentation: POST /api/login.
  • If the client you're using doesn't automatically detect the login cookie (AtmoAuthToken_{fedmemberid}), get the cookie from the login response and send it in the request for each of the operations below. See Getting Started and Session Cookies.
  • Get the value from the Csrf-Token_{fedmemberid} cookie in the login response, and use it to compose the X-Csrf-Token_{fedmemberid} custom header, which you'll need for authentication. See Sending the CSRF Token.

Run the following API operations:

  1. Run the operation below to delete the existing API mappings:
    Accept: text/plain
    DELETE
    {protocol}:{hostname}/api/index/default/api/mapping

    For example: http://open:9900/api/index/default/api/mapping

  2. Run the operation below to delete the existing app mappings:
    DELETE
    {protocol}:{hostname}/api/index/default/app/mapping
  3. Run the operation below to update the API mappings from the new files in the installation bundle:
    Content-Type: application/x-www-form-urlencoded
    PUT
    {protocol}:{hostname}/api/index/default/api/mapping
  4. Run the operation below to update the app mappings from the new files in the installation bundle:
    Content-Type: application/x-www-form-urlencoded
    PUT
    {protocol}:{hostname}/api/index/default/app/mapping
  5. Upgrade from 8.3 to 8.4 only: Run the operation below to update the business organization mappings from the installation bundle:
    Content-Type: application/x-www-form-urlencoded
    PUT
    {protocol}:{hostname}/api/index/default/business/mapping

    Note: Since business organization objects were introduced in version 8.3, you can skip this step if you're upgrading from 8.2 to 8.4.

To reindex objects using a database script

When you've completed the above steps, you'll need to reindex the API, app, and business objects by running this database command:

delete from {database_name}.INDEX_STATUS where OBJECTTYPE in ('api', 'app', 'business');

For example:

Example database script to reindex objects

back to top

Step 3-6: Post-Upgrade Task for upgrades to 8.4: MongoDB Updates

Version 8.4 includes some changes to the MongoDB database schema. To implement these updates, the upgrade process includes a new configuration action, Install Configuration Data and Indexes in MongoDB. Make sure you complete this configuration action along with all others when upgrading.

The upgrade wizard steps you through the configuration action; if you don't complete the installation in one session, be sure to go back and make sure all configuration actions are complete. In the Akana Administration Console, Configuration tab, at the bottom left, the Configuration Actions section should be empty when the upgrade process is complete.

back to top

Step 3-7: Conditional, MongoDB/OAuth: Post-Upgrade Task for Data Migration

Note: This task was introduced in version 8.4.4 and is applicable for upgrades to 8.4.4 and later versions.

If you’re migrating from RDBMS to MongoDB and you use OAuth, you’ll need to run a data migration task, introduced in the upgrade to version 8.4.4, to ensure that OAuth tokens issued before the upgrade can still be used.

After migrating the data, you'll need to update a configuration property and restart the container. Follow the steps below.

To migrate OAuth data to MongoDB
  1. In the Akana Administration Console for the Policy Manager/Community Manager instance, Configuration Actions, run the Migrate OAuth Data to MongoDB task, as shown below.

    Migrate OAuth Data to MongoDB configuration task

  2. In the Akana Administration Console, click the Configuration tab.
  3. Under Configuration Categories, find the com.soa.oauth.provider.server category.
  4. Find the com.soa.oauth.provider.server.config.datasource property and change the value from JDBC to NOSQL.
  5. Click Apply Changes.
  6. Restart the Policy Manager/Community Manager container and then, when PM/CM is started, restart the Network Director container.

After updating this property, the server for the OAuth Provider is now the NOSQL database (MongoDB).

back to top

Upgrade Procedures/Reference

Contacting Akana Technical Support

If you need to contact Technical Support, submit an email to support@akana.com.

When sending a support query, please provide the following information:

  • Your name
  • Email address
  • Subject
  • As much information as possible regarding your question.

You'll receive an acknowledgment email and one of our support staff will contact you.

You can also access the Support site at https://servicedesk.akana.com/servicedesk/customer/user/login.

Back to top

Container upgrade sequence

In terms of the sequence of containers, it's best to start by upgrading one of the Policy Manager containers. This accomplishes the database upgrade as well.

After that point, the sequence of containers really doesn't matter. These upgrade instructions suggest the following sequence once the first container has been updated:

  1. First, any additional containers running Policy Manager and/or the API Platform.
  2. Then, any Network Director or Agent containers.

However, the sequence is not important after the first container. You could upgrade the Network Director container at any point. There is no dependency; containers that have been upgraded will work with containers that haven't yet been upgraded. You can even upgrade additional containers in parallel.

Just make sure you upgrade an initial Policy Manager container first, with the associated database upgrade, and then follow any logical approach, making sure that each step completes successfully before starting the next one.

Back to top

Troubleshooting: error: "Some of the model objects are not updated"

If your Elasticsearch setup is not complete, you might encounter the message below after running the Upgrade CM Models task:

Some of the model objects are not updated. Refer to log files for the specific errors.

Error: Some of the model objects are not upgraded

If you encounter this error, follow the steps below:

  1. Make sure that you've installed the Akana Embedded Elasticsearch Node feature, shown below.

    Installing the Akana Embedded Elasticsearch Node feature

  2. Then, from Configuration > Configuration Actions, run the Configure Elasticsearch Global Configuration task, shown below. This step was required in version 8.2 and is not required in 8.4; but if you are upgrading from 8.2 and didn't complete the step in 8.2, you'll need to complete it now.

    Configure Elasticsearch Global Configuration task

  3. In the Configure Elasticsearch Global Configuration page, shown below, accept the default values or change as needed, and then click Finish.

    Configure Elasticsearch Global Configuration page

  4. Run the Upgrade CM models task again.

Back to top

Upgrading by creating new containers: notes

If you're upgrading by creating new containers, rather than upgrading existing containers, it's important that you delete the existing container from the Policy Manager workbench before creating the new container.

If you don't delete the old container before creating the new one, you might encounter an error on the provisioning step, similar to the one shown below (WSDL binding cannot be disassociated from service):

[425] com.digev.fw.exception.GException: Wsdl binding [uddi:4b0aba1c-8ca7-e61c-5575-25361578c179] 
cannot be disassociated from service [uddi:soa.com:metadataattachment-servicekey]. 
Binding is attached to service endpoint.

If you encounter this message, delete the old container, and then retry the provisioning.

Back to top