Upgrading Akana API Platform to Version 2020.1.x, 2020.2.x, or 2022.1.x

Learn how to upgrade the Akana API Platform from an earlier version to version 2020.1.x, 2020.2.x, or 2022.1.x.

These upgrade instructions cover the process for a manual upgrade, creating new containers. Automation options are also available (Linux-only for container creation, Windows and Linux for all other automation tasks).

This upgrade addresses a simple container scenario of:

  • One container with Policy Manager and Community Manager installed
  • One container running the API Gateway (Network Director)

The documentation includes some notes and additional information that would be applicable if you're creating other container scenarios—for example, if you have multiple PM/CM containers, or a separate Scheduled Jobs container—but the main path is to create these two containers.

This document covers instructions for any scenario where you are upgrading from any earlier version to 2020.1.x, 2020.2.x, or 2022.1.x:

  • Upgrading from any earlier major/minor version to 2020.1.x, 2020.2.x, or 2022.1.x.
  • When applicable: Upgrading from a major version to a later minor update for the same major version; for example, 2020.2.12 to 2020.2.15. For additional notes, see Minor-Version Update Notes.

You can also use automation to standardize the upgrade process. Automation might take a little more time to set up, but it has great benefits including standardization and reusability. For information on automation, see Automation Reference. For information about which automation recipes to use for upgrade, see Automating the upgrade.

Previous versions of this document recommended an incremental approach, upgrading from one major version to the next and then to the next. Incremental upgrade is not necessary. You can upgrade from an earlier version to the latest version in one upgrade process. This documentation takes you through the steps to create new containers and then transfer existing settings, including container key, keys and certificate from an external keystore, and configuration settings, to the new container.

Note: For information on migrating any customization you might have in place, if you're using Hermosa Theme in the Community Manager developer portal and are migrating from a version earlier than 2019.1.0, see Community Manager: Migration Guide. User interface changes in 2019.1.0 might affect customization in place for earlier versions of the Community Manager developer portal.

Supported Platforms: 2020.1.x, 2020.2.x

Table of Contents

Planning the Upgrade

Performing the Upgrade

Additional Tasks

Upgrade Procedures/Reference:

Planning the Upgrade

Upgrade strategy

There are several approaches you can take to upgrading:

  1. Manual upgrade, creating a new container and then using it to replicate an old one. This documentation steps through that approach.

    Note: If you have custom container configuration settings, we highly recommend that you use automation to replicate those properties in the new container.

  2. Manual upgrade, creating new containers, and then configuring the new containers to suit your requirements. This is essentially a fresh install.
  3. Automated upgrade, using automation recipes to help make your upgrade faster, more standardized, and more error-free. For information on automation, see Automation Reference. For information about which automation recipes to use for upgrade, see Automating the upgrade.

This documentation takes you through the steps to create new containers and then transfer existing settings to the new container (#1 above). For example, as part of Step 2-5: Create and configure the first container you'll upload the same keys and certificate, which you used for the old container, from your secure external keystore to the new container.

Some of the steps are the same for all approaches.

Note: If you are using Runtime Configuration and want to use some of the new runtime configuration properties in an existing library, you'll have to manually update certain library files after performing the upgrade. For details and instructions, see Updating an existing library to a newer version.

Overview

These instructions address the scenario of creating new containers for your 2020.1.x, 2020.2.x, or 2022.1.x installation.

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

Step 1-0: Check for version-specific upgrade notes

When upgrading from a major/minor version to another major/minor version, there are certain actions, such as upgrading the database schemas, that are built into the upgrade process.

In general, these types of actions are not necessary when upgrading from a minor version to another minor version. In most cases, key components such as the database schema do not change. However, in some cases they do. In these scenarios, it's important to manually perform the upgrade tasks as part of your upgrade process to make sure the updates are fully complete.

The table below lists the action to take, when upgrading to or across a specific version, to make sure your installation is fully updated.

When upgrading to or across this version... Perform this upgrade task...
2020.2.10

From 2020.2.10 onwards, MongoDB indexes on METRIC_ROLLUP_DATA and METRIC_RAW_DATA are not automatically dropped and recreated on update. Instead, any intended index changes are logged as an error. The MongoDB administrator has the responsibility to apply the changes as needed.

This modification helps avoid unnecessary recreation of large indexes, which could potentially take hours, on production systems.

After running the Install Configuration Data and Indexes in MongoDB post-upgrade task, check the Akana container logs ({release_directory}\instances\{containername}\logs folder) for indexes that were not automatically created. If there are any, review with the MongoDB database administrator to determine if and when to run the updates.
2019.1.6 After performing the upgrade, run the Manage Schemas post-upgrade task.
2019.1.7 After performing the upgrade, run the Manage Schemas post-upgrade task.

Step 1-1: Review release notes

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

Go to the Akana Release Notes page and choose the version.

Step 1-2: Plan the upgrade

Before you start downloading and installing, plan your upgrade. You'll need to gather information about the old container so that you can correctly set up and configure the new container. Do the following:

  1. In your existing installation, in the Akana Administration Console for each container, note the features and add-ons that are installed in each container, so that you can replicate this in the new containers. When you're following the steps of the procedures below, install the features for your own containers.
  2. In the Akana Administration Console for each container, take all steps needed to save out any container configuration settings that you've customized, so that you can reproduce the configuration on the new container, where applicable. Save all container properties that you've customized.

    Note: You can use an automation task to save out the configuration settings.

  3. Make a note of the container key value. This is needed for replicating the existing container in your new container. You can get the container key from the Akana Administration Console for the container. For instructions, see Finding the container key. When you're setting up the new container, you'll use this key (Step 2-5: Create and configure the first container below).
  4. Make sure you have the same keys and certificate, from your external keystore, which you used to create the original container. You can then upload the certificate when configuring the new container. See To perform the post-upgrade tasks for the first container, Step 2, Setting up the certificate for the container below.
  5. Conditional: If standalone Elasticsearch is new for your implementation, determine where you'll install Elasticsearch, needed for the search feature. For full information on Elasticsearch, see Installing and Configuring Elasticsearch.
  6. Conditional: If you plan to upgrade an existing MongoDB deployment from version 4.4 to 6.0 and depending on your specific MongoDB deployment, refer to the MongoDB documentation to perform an upgrade. After the MongoDB upgrade to 6.0, no additional steps are required to upgrade the Akana Platform. However, if the deployment structure of MongoDB requires downtime while upgrading, you must shutdown the Akana Platform to avoid data loss or inconsistent behavior.

    Note: To upgrade from MongoDB version 4.4 to 6.0, an upgrade to 5.0 is necessary as an intermediate step.

Step 1-3: Install and configure Elasticsearch (if not already done)

Standalone Elasticsearch is required. For instructions, see Installing and Configuring Elasticsearch.

Performing the Upgrade

Step 2-1: Shut down and back up the previous version

  1. Shut down all containers in your installation. See Stopping a container (installation doc).
  2. Copy the entire installation folder structure to a secure backup location.
  3. Back up your database.

Step 2-2: Download and extract ZIP files

Download:

The first step is to download the required ZIP files. You'll need to:

  • Create a folder for your 2020.1.x, 2020.2.x, or 2022.1.x installation; for example, aap202201.
  • Download the ZIP files for the latest version.

For detailed instructions on this step, refer to the installation guide, Download ZIP files.

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

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 also download the corresponding version of the same feature.

Extract:

The next step is to extract the files.

For detailed instructions on this step, refer to the installation guide, Step 2-2: Extract installation files.

Note: You'll need passwords to unzip the files. If you don't know the passwords, contact your Akana representative.

Step 2-3: Save properties from old container

You'll need to save out the information on any custom properties, from the old container, so that you can reconfigure the new container with the same properties in Step 2-5: Create and configure the first container (or subsequent containers).

To save out the properties from the old container

  1. Start up the old container. See Starting a container (installation doc).
  2. With the old container running, extract the information on custom property settings from the old container. If you're using the automated process to extract the properties, see Automating the transfer of container properties.
  3. When you have the configuration information, shut down the old container. See Stopping a container (installation doc).

Step 2-4: Verify that Elasticsearch is running

Elasticsearch is a separate installation. Make sure it's installed successfully and is running.

For example, run this command:

ps -ef

If there is response content, Elasticsearch is running. For example:

/usr/share/elasticsearch/modules/x-pack/x-pack-ml/platform/linux-x86_64/bin/controller

See also:

Step 2-5: Create and configure the first container

Create the first Community Manager/Policy Manager container. For features to install, see Community Manager/Policy Manager container features with access to MongoDB. Follow these three main groups of steps:

Notes:

  • In creating the containers, make sure that you set up at least one container running Policy Manager before you set up the Network Director container.
  • Depending on the version that you're upgrading from, you might need to install one or more upgrade tools, in the Akana Administration Console for the container. Install and run the upgrade tools one at a time, from the version you're upgrading from, up to the newest version. For more information, see Installing and running upgrade tools.
  • If you're using automation to replicate the container property settings, follow the sequence of steps in Automating the transfer of container properties below.

To create the first container and install features and plug-ins

  1. Run Configurator to create the first container, either via the GUI or using silent install. See Step 2-3: Run Configurator to create the first container.

    Note: Rather than letting a new container key be assigned, you'll need to use the container key from the old container, which you saved in Step 1-2: Plan the upgrade above.

  2. In the Akana Administration Console for the container, install Policy Manager/Community Manager. See Step 2-4: Install Policy Manager/Community Manager features on the container (installation doc).
  3. At the Installation Complete summary, do not click Configure yet. Instead, click Close; you'll need to install plug-ins and upgrade tools and then turn off the scheduled jobs before running the post-upgrade tasks.
  4. Install any plug-ins that you want to install. See Step 2-5: (as needed) Install plug-ins on the container. At the end, click Cancel.
  5. If you're upgrading from an older version, such as 8.0, you'll need to install one or more upgrade tools, in the Akana Administration Console for the container. Install and run the upgrade tools one at a time, from the version you're upgrading from, up to the newest version. For more information, see Running upgrade tools. At the end, click Cancel.

    Note: Upgrade tools update the database, so they only need to be run once per installation. Install upgrade tools on the first container and run the resulting post-upgrade tasks once.

  6. Turn off the scheduled jobs. For instructions, see Turning the scheduled jobs off.
  7. Go to the next procedure below.

To perform the post-upgrade tasks for the first container

  1. In the Akana Administration Console for the container, under Installed Features, check at the bottom of the page under Pending Installation Tasks.
  2. Run any tasks that are pending. The specific list depends on the version you're upgrading from and the features you're installing. Complete all tasks. For information about specific tasks, see Running post-upgrade tasks. Some tasks are run once per installation, some are once per container. Examples of key tasks:
    • Setting up the certificate for the container. At the Manage PKI Keys wizard (Generate PKI Keys & X.509 Certificate page), upload the container certificate from your secure external keystore. See Manage PKI Keys.

      For more information about using an external keystore to manage your container identity, see Managing Container Identity Across Upgrades.

    • Configuring the database (once per installation). See Configure Database Options.

      Note: When you're configuring the database, choose Use Existing Database and put in the values and credentials for the database from your prior version of the Akana API Platform. Depending on the database you're using, you might need to put a database driver in place, or take some other steps. See Database notes and Database drivers (installation doc).

    • Provisioning. For instructions, see To perform provisioning.
  3. When pending installation tasks are all complete, restart the container. For instructions, see Starting a container.
  4. Turn the scheduled jobs back on. For instructions, see Turning the scheduled jobs back on.
  5. Go to the next procedure below.

To update container properties

When you've created the new container and installed the features, it's time to set the configuration properties. You'll need to transfer any customized settings that were set on the old container, to the new container.

Use the setting values that you saved out in Step 2-3: Save properties from old container, and set them on the new container.

If you used automation to extract the properties, run the extracted recipe that you created, to set the properties so they are the same as the old container. For instructions, see Automating the transfer of container properties.

Step 2-6: Create and configure additional containers

Once you have the first container set up, it's time to create and configure additional containers. Essentially you'll follow the same set of steps as above for each container, including creating the container, installing features, performing post-upgrade tasks, and updating container properties. Follow all steps for these additional containers:

  1. Optional: Subsequent Community Manager/Policy Manager containers. If you're following the sample deployment scenario, see Community Manager/Policy Manager container features with access to MongoDB.
  2. Network Director container. For features to install, see API Gateway/Internal Gateway (Network Director).

    Note: In a version prior to 2019.1.0, you might have installed the Akana OAuth Provider Agent or Akana Community Manager OAuth Provider Agent features in your Network Director container. In version 2019.1.x, do not install these features. If you do, your Network Director container will not work correctly. These features will be removed in a later version.

    For Network Director, pending tasks might include the pending tasks below, and/or others:

    1. WS-Metadata Exchange Options: see Installation wizard, ND container: Configure WS-Metadata Exchange Options.
    2. Manage PKI Keys wizard (Select Key Management Option page): see Installation wizard: Manage PKI Keys.

    For a full list of possible tasks, see Configuration Actions.

  3. OAuth container. For features to install, see OAuth Provider.
  4. Scheduled Jobs container. For features to install, see Job Scheduler.

For each container:

Create containers in this sequence:

  1. First, create all Policy Manager/Community Manager containers.
  2. Then, create all Network Director containers.

    You can create a Network Director container using either GUI or Silent options. For instructions on how to install a Network Director Container, install and configure the Network Director feature, and register a new Network Director container in Policy Manager, refer to Using the Network Director Feature.

For information about the features and plug-ins to install for additional container configurations, see Sample Deployment Scenarios (Install doc).

Additional Tasks

Additional tasks: overview

Once you've completed the product version update, and performed the post-upgrade tasks for each container, there are a few additional steps to complete the upgrade. You might have completed some of the steps below.

Perform configuration actions

If you're upgrading from a previous version, it's a good idea to run the following configuration actions, even if they were not listed under Pending Installation Tasks:

Check system health

Optional, recommended.

After installation, it's a good idea to check the system health.

Log into the Akana Administration Console for the PM/CM container and check the system health (Health tab).

Configure Elasticsearch

The Community Manager developer portal is now available, but search will not work until you configure Elasticsearch.

Note: These steps assume that Elasticsearch is already installed and configured. See Step 1-3: Install and configure Elasticsearch (if not already done).

Steps:

  1. Configure global settings
  2. Clear the Elasticsearch index
  3. Check Elasticsearch status
  4. Restart the container
  5. Verify that search is working

Configure global settings

As part of installation or upgrade, you'll need to configure a couple of global settings in the Akana Administration Console so that the Elasticsearch feature will work correctly.

In the Akana Administration Console for any one container:

Configuration > Configuration Actions > Configure Elasticsearch Global Configuration.

For instructions, see How do I configure Elasticsearch?

Clear the Elasticsearch index

You'll need to clear out the old Elasticsearch index so it can be refreshed. To do this, complete these two steps, at the same time:

  • Empty the INDEX_STATUS table in the database by running this database command: 
    delete from {database_name}.INDEX_STATUS;

    For example:

    Clearing the Elasticsearch index

  • Delete the index folders from their storage location, so that new index folders will be created when the index is regenerated.

Check Elasticsearch status

You can use the Elasticsearch API to check the status of your Elasticsearch, to make sure all is running smoothly. In the below, substitute the node where Elasticsearch is running:

GET {protocol}://{hostname}:{port}/

The response is a JSON object with information about your Elasticsearch. For more information, refer to the Elasticsearch website: Connect to Elasticsearch.

Restart the container

Stop and restart the container.

For instructions, see:

Verify that search is working

Log in to the Community Manager developer portal user interface and verify that search is now working. For example, search for an API or an app.

This completes the Elasticsearch steps.

Post-upgrade task for Elasticsearch indexing when upgrading to or across 2019.1.12

In version 2019.1.12, the Community Manager developer portal search capability for APIs was extended to support searching for both partial and complete API endpoint. To search for a complete endpoint, users can use surrounding double quotes.

Example: "https://example.com/v1/payments" searches for the full endpoint.

To enable endpoint searching for existing APIs, delete the indexes for api and metadata, and then reindex the api objects.

The steps below use localhost:9200 as an example.

  1. Delete the search indexes: 
    $ curl -XDELETE 'localhost:9200/default_api'
$ curl -XDELETE 'localhost:9200/default_metadata'
  2. Run this query: 
    "delete from INDEX_STATUS where OBJECTTYPE ='api';"

Post-upgrade task for Elasticsearch indexing when upgrading to or across 2019.1.14 (Lifecycle Repository only)

In version 2019.1.14, the Community Manager developer portal search capability was extended to support searching extended metadata in Lifecycle Repository APIs, apps, and users.

To enable metadata search for existing data if you are using Lifecycle Repository, delete the search indexes for APIs, apps, and users, and then reindex the objects.

The steps below use localhost:9200 as an example.

  1. Delete the search indexes: 
    $ curl -XDELETE 'localhost:9200/default_api'
$ curl -XDELETE 'localhost:9200/default_app'
$ curl -XDELETE 'localhost:9200/default_user'
$ curl -XDELETE 'localhost:9200/default_metadata'
  2. Run this query: 
    delete from INDEX_STATUS where OBJECTTYPE in ('api', 'app', 'user');

Restart all containers

After running the configuration actions on all containers, stop and restart all containers.

For instructions, see:

Note: If you are using Runtime Configuration and want to use some of the new runtime configuration properties in an existing library, you'll have to manually update certain library files after performing the upgrade. For details and instructions, see Updating an existing library to a newer version.

Upgrade Procedures/Reference

Launching the Akana Administration Console

Installation and configuration tasks are performed in the Akana Administration Console for the container. First you create the container, and then you install features into the container and configure them.

To launch the Akana Administration Console

  1. Launch the Akana Administration Console for the 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. See Installation Options: Full List (installation doc).

Installing and running upgrade tools

Sometimes, if there are significant changes to the database between versions, upgrade includes a specific upgrade tool that performs certain actions on the database to bring it up to date.

Depending on the version that you're upgrading from, you might have to install one or more of the following upgrade tools, in the Akana Administration Console for the container:

  • Akana 8.2 to 8.4 Model Upgrade
  • Akana PM 8.2 Upgrade
  • Akana PM 8.0 Upgrade
  • Akana PM 7.2 Upgrade

Note: Install and run the upgrade tools and their associated post-upgrade tasks manually, one at a time, running the oldest one first and finishing up with the most recent version.

For information on tools, see Installation Tools (installation doc).

When you install an upgrade tool, it creates a post-upgrade task that makes changes to the database to upgrade it.

Post-upgrade tasks relating to upgrade tools are once per installation, not per container.

Install all tools that are applicable to the version you're upgrading from.

Running post-upgrade tasks

The specific post-upgrade tasks you'll need to run for a specific container depends on the version you're upgrading from, the features you're installing on the container, and the post-upgrade tasks that have already been done. For example, Configure Database Options is done once per installation; some other tasks are done for each container. Some tasks are only applicable if you're upgrading from a specific earlier version.

This section contains information about tasks you're likely to run into when upgrading using the simple scenario described in this document.

Common post-upgrade tasks are:

Upgrading from a much earlier version: Each of the upgrade tools creates a post-upgrade task which you must run. For a full list of possible tasks, see Configuration Actions (Akana Administration Console doc).

Manage PKI keys

At the Manage PKI Keys wizard (Generate PKI Keys & X.509 Certificate page), upload the container certificate from your secure external location. You'll need to upload a .JKS or .P12 file.

In the Akana Administration Console for the container, go to Configuration > Manage PKI Keys and choose Import Private Key & X.509 Certificate. See Installation wizard: Manage PKI Keys (Akana Administration Console doc).

For general information about container identity in the context of upgrading, see Managing Container Identity Across Upgrades.

See Installation wizard: Manage PKI Keys (Akana Administration Console doc).

Configure Database Options

Configure Database Options wizard (Select Database Options page): here, choose Use Existing Database and put in the values and credentials for the database from your prior version of the Akana API Platform.

See Installation wizard: Add Database (installation doc).

Note: Depending on the database you're using, you might need to put a database driver in place, or take some other steps.

See Database notes and Database drivers (installation doc).

Manage Schemas

Manage Schemas wizard (Install Schemas page): Manages the database schemas for the container.

See Installation wizard: Manage Schemas (installation doc).

Create Policy Manager Admin User

Create Policy Manager Admin User (Define Policy Manager Administrator Credentials page): Creates the top-level Policy Manager user.

See Installation wizard: Define Policy Manager Administrator Credentials (installation doc).

Provisioning

Provisioning initializes resources associated with the features installed on the container.

Must be completed for each container running PM/CM.

See Installation wizard: Provisioning (installation doc).

To perform provisioning

  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.

    Note: Make sure the Provisioning task is 100% complete before moving to the next task.

    Provisioning Summary

  4. When provisioning is 100% complete, click Close.

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.
  3. When done, click Close.

The Rebuild CM Styles task makes sure that you have the latest style updates, for all themes and tenants.

To rebuild CM styles in the Akana Administration Console

  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.

Note: The action in the Akana Administration Console rebuilds styles for all tenants. If you have different instances of the Community Manager developer portal, and want to rebuild styles for a specific tenant, see To rebuild styles in the Community Manager developer portal.

Install Configuration Data and Indexes in MongoDB

The Install Configuration Data and Indexes in MongoDB task appears on the post-upgrade task list for manual upgrades only if there are new or changed documents or index collections that are needed by the product when using MongoDB.

If you are using automation recipes, and this task is needed, it is run automatically as part of the upgrade recipe.

For more information, and an illustration, see Install Configuration Data and Indexes in MongoDB (Akana Administration Console documentation).

Checking that features were installed correctly

When you've installed features in a container, it's a good idea to check to make sure that features have been installed correctly.

  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.

    Features installed tab

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

If needed, contact Technical Support.

Finding the container key

To find the container key for your old container in the Akana Administration Console for the container, follow the steps below.

To find the container key

  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.config. An example is shown below.

    Finding the container key

  4. Locate the container.key property and note the value.

Turning the scheduled jobs off

If you turn off the scheduled jobs, turn off these two jobs, for all containers with Policy Manager installed, in this sequence:

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

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.

Turning the scheduled jobs back on

If you turned the scheduled jobs off, and are ready to turn them back on again, turn them on in this sequence, the reverse of the sequence in which you turned them off, for all containers with Policy Manager installed:

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

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.

Unregistering and re-registering 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: 
    .\{install_folder}\bin\unregisterContainerServiceYAJWS.bat {instance_name}
  3. Register the new version as a Windows service: 
    .\{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.

Starting a container

There are several ways you can start a container: Windows, as Windows service, or Unix. Follow the applicable procedure:

To start the container (Windows)

  1. Navigate to the \{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 /{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

Automating the transfer of container properties

In many cases, you might have set customized values for one or more of the containers in your installation, or even have added new properties.

When upgrading by creating a new container, you'll need to transfer, or re-create, the configuration settings on the new container. There are two ways to do this:

  • Manual configuration: Create the new container, install the features into it, then manually replicate any custom settings from the old container, to the new container.
  • Automated configuration (recommended): With the old container running, use automation to extract the custom configuration properties, into a recipe. Next, create the new container and install the features into it. Finally, use automation to run the recipe you created, to replicate the configuration of the old container.

    For instructions to run the recipe, see Extracting a Recipe. An example is shown below. Use the name of the recipe that you used when you extracted the properties.

    > ./jython.sh -m akana.recipe --recipe <name of extracted recipe> --url http://localhost:9900 --user administrator --password mypassword_01

To transfer configuration properties from an old container to a new container via automation

  1. Before creating the new container, and with the old container running, extract the custom properties. See Step 2-3: Save properties from old container.

    For instructions, see Extracting a Recipe (Automation doc).

  2. Create the new container. See Step 2-5: Create and configure the first container, Step #6, after doing the initial configuration steps, shut down the container. Rather than restarting as in Step #7, save out the new configuration settings at that point.
  3. Compare the new settings with the old settings to arrive at the settings that will need to be configured on the new container.
  4. If available, use automation to update the container configuration.
  5. Now complete Step 2-5: Create and configure the first container by restarting the container, and verify that the configuration properties are set correctly.
  6. Follow steps 2 through 5 for additional containers until they are all configured.
  7. Continue with the post-install steps.

Automation recipes for upgrade

The table below lists some of the automation recipes you could use to automate the upgrade process.

Recipes are in the {install_dir}/recipes folder of your installation.

Note: Automation recipes for creating containers are valid for Linux only. See Running automation recipes on Windows.

Use this recipe... To...
cm-upgrade Perform CM upgrade recipe.
pm-cm-new-upgrade Create new PM/CM container on an existing database and perform any upgrade tasks.
pm-cm-upgrade Perform PM/CM upgrade recipe.
pm-upgrade Perform PM upgrade recipe.

Note: If you want to create a new Network Director container, rather than replicating an existing one, you will need to re-register the new container. For an example of doing this via automation, see Registering the ND container (automation doc).

Troubleshooting: Styles

In some cases, platform styles change between versions. If you encounter differences in the way the Community Manager developer portal page display, and you don't feel that the display is correct, check these steps:

  1. First, clear your browser cache and then refresh the page. You might be viewing a cached version of the page.
  2. If the issue is still not resolved, close and re-open the browser.
  3. If the issue is still present, do one of the following:
    • If you have customization—Rebuild platform styles to make sure that all the latest style updates have been applied. See To rebuild styles in the Community Manager developer portal.
    • If you do not have customization—Delete the style folder. This folder is created when styles are rebuild. Go to Admin > File Manager. In the Resources section, click the File Manager button. Delete the style folder for each theme: resources/theme/<theme-name>/style.

Contacting Technical Support

For information about how to contact Technical Support, and what information to provide, see Customer Support.