Post-Install Tasks

Now that you have completed the installation of the Akana API Platform, here are some tasks you might want to do next.

Table of Contents

Supported databases

To view the database versions supported by the Akana API Platform 2025.1, see System Requirements.

For more configuration details and considerations related to specific databases:

Database notes

This section includes notes and additional information relating to installation with supported databases. It includes:

For database driver information for all database types, see Database drivers.

Database notes, all: User permissions

Grant database permissions based on user roles as follows:

  • User creating the database: This user requires permissions to:
    • Create a user.
    • Create the schema, including the ability to create, alter, and drop tables, indices, and constraints.
  • Runtime user: The runtime user created by the scripts must have a minimal set of permissions for runtime plus schema updates. If you remove this user's ability to add, alter, or drop objects, you must add them back when it's time to perform schema updates.

Database notes: Oracle

When working with an Oracle database, see:

Database drivers

For Oracle database drivers, see Database drivers.

Oracle database password restriction

If you are creating a new Oracle database using the Create New Database wizard (standard installation procedure), ensure the Oracle database password does not start with a number or special character.

Use Oracle Service Name, not SID

During setting up an Oracle database, the wizard offers two options, Oracle Service Name and SID.

For Oracle versions 12cR1 and later, consider using the Oracle Service Name, as per best practices.

Database permissions, Oracle 12c R2 or later

When using Oracle 12c or later to configure a new database, the DBA must GRANT SELECT ON SYS.USER$ TO SYSTEM; (substitute the SYSTEM user for the user specified for the administrator credentials). This is because Oracle 12c introduced restricted access to SYS.USER$, which the platform uses to query on.

Database creation, Oracle 18c or later

When using Oracle version 18c or later and deploying with the new Oracle component database architecture (CDB), it's important to create the database first. In the Configure Database Options wizard, select the Use Existing Database option, see Installation wizard: Add Database. This is because the Create option in the wizard does not currently support the new Oracle architecture for component/pluggable databases.

When creating the database, follow the steps to create the tablespace and the user.

Create tablespace

Run the following, substituting your own values for the MYTABLESPACE and MYDATAFILE values:

CREATE TABLESPACE MYTABLESPACE DATAFILE MYDATAFILE.dbf' SIZE 100M REUSE AUTOEXTEND ON NEXT 50M MAXSIZE UNLIMITED NOLOGGING;

Create user

Run the following, substituting your own values for the AKANAUSER, Password, and MYTABLESPACE values:

CREATE USER AKANAUSER IDENTIFIED BY "Password" DEFAULT TABLESPACE MYTABLESPACE;
GRANT CONNECT TO AKANAUSER;
GRANT RESOURCE TO AKANAUSER;
GRANT UNLIMITED TABLESPACE TO AKANAUSER;
GRANT CREATE ANY VIEW TO AKANAUSER;
GRANT CREATE ANY SYNONYM TO AKANAUSER;
GRANT DROP ANY SYNONYM TO AKANAUSER;

When you run the Configure Database Options wizard, select the option to connect to an existing database rather than letting the wizard create the database.

Database notes: Microsoft SQL Server

When working with a Microsoft SQL Server database, see:

For additional information on using a Microsoft SQL Server database with Akana products, see Microsoft SQL Server Database Installation and Configuration.

Verifying the quartz trigger property for Microsoft SQL Server

If you are using a Microsoft SQL Server, ensure that the quartz trigger property in the Admin Console is set to True.

  1. Log in to the Admin Console for the Community Manager container.
  2. Click the Configuration tab.
  3. On the left panel, under Configuration Categories, locate the com.soa.scheduler.quartz category.
  4. On the right panel, find the org.quartz.jobStore.acquireTriggersWithinLock property and ensure it is set to True.
  5. Save your changes.

Database notes: Microsoft SQL Server with Lifecycle Repository

When using any version of MSSQL with Lifecycle Repository, the database administrator must manually alter the database to set read committed snapshot and enable snapshot isolation mode. These settings are not required during installation; however, it will affect how the application behaves once asset content is being populated.

Run the following:

ALTER DATABASE {db.instance.name}
  SET READ_COMMITTED_SNAPSHOT ON;
ALTER DATABASE {db.instance.name}
  SET ALLOW_SNAPSHOT_ISOLATION ON;

Database notes: MySQL

When working with a MySQL database, see:

Database notes: MySQL with Lifecycle Coordinator/Lifecycle Repository

When installing the Akana API Platform with the Lifecycle Coordinator or Lifecycle Repository features, there are some constraints.

The Lifecycle Repository feature requires the following installation features:

  • Akana Lifecycle Repository (Provides metadata repository and configuration services)
  • Akana API Platform Repository Plug-In (Extended Properties and Workflow feature)

The Lifecycle Coordinator feature requires the following installation features:

  • Akana Lifecycle Coordinator (Lifecycle Coordinator for the Akana Platform)

See following information:

LC/LR: Additional database privileges required for installation

When installing LC/LR on MySQL, you must complete one of the following:

  • Disable MySQL binary logging. However, this may not be feasible in some cases because binary logging is a requirement for replication. If you are using AWS RDS with a Multi-AZ deployment, the replication used for Multi-AZ implicitly enables binary logging.

    For more information on binary logging, refer to the MySQL documentation.

  • Grant the super privilege to the database user used by the Akana API Platform for the duration of the time that Lifecycle Coordinator/Lifecycle Repository features are being installed and libraries (either tenant libraries or topology libraries) are being created.

    An alternative to granting the super privilege is to modify the log_bin_trust_function_creators variable. See LC/LR: Set the log_bin_trust_function_creators system variable.

LC/LR: Add the correct database permissions

When using the Lifecycle Coordinator or Lifecycle Repository features, the database user requires specific additional grants with MySQL. These grants are required for successful completion of the Initialize Repository Database configuration task; otherwise, the task fails.

For MySQL installs, ensure a user must have the following grants:

  • TRIGGER
  • CREATE ROUTINE
  • ALTER ROUTINE

Run the following MySQL statement to add the correct permissions:

GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON {database_instance_name}.* TO '{database_user}'@'%';

For example:

GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON LXC1PM8X21.* TO 'LXC1PM8X21'@'%';

In the above example, LXC1PM8X21 is both the database instance name and the database user name.

Use the following command to confirm the change:

mysql> show grants for 'LXC1PM8X21'@'%';

You will see the following response, which confirms that the grants were updated successfully:

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Grants for LXC1PM8X21@%                                                                                                                                                                                                                               |
 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, EXECUTE, CREATE VIEW, SHOW VIEW ON *.* TO 'LXC1PM8X21'@'%' IDENTIFIED BY PASSWORD '*2A5FDEE54AE88A62B88A1A6C5389C23A529F20EE' |
 | GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON 'LXC1PM8X21'.* TO 'LXC1PM8X21'@'%'                                                                                                                                                                                   |
 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 2 rows in set (0.00 sec)
Lifecycle Coordinator and/or Lifecycle Repository with MySQL imposes limitations on Advanced Queries using custom XPathCriteria and only a limited number of fixed XPathCriteria are supported in the default searches.

LC/LR: Set the log_bin_trust_function_creators system variable

To successfully initialize the repository database, additional user privileges are required. Without the privileges, the Initialize Repository Database task might fail with the following error message:

exception:java.sql.SQLException: You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable)

In some cases, it might not be feasible to grant the super privilege to the database user or to disable binary logging. An alternative approach is to set the log_bin_trust_function_creators system variable to a value of 1:

mysql> set global log_bin_trust_function_creators=1;
Query OK, 0 rows affected (0.00 sec)

However, this is only an in-memory variable. For persistence, you can add the following to the /etc/my.cnf file:

log-bin-trust-function-creators=1

For more information on the log_bin_trust_function_creators system variable, refer to the MySQL documentation, specifically sections A.4.25 and A.4.26.

LC/LR: Create libraries before enabling extended properties in the Community Manager developer portal

When using the Akana API Platform with MSSQL, tenant (repository) libraries must initially be created by using the Synchronize Lifecycle Manager Data admin task, before enabling the Extended Properties and Workflow flag in the Community Manager developer portal settings under Admin > Site.

Database notes: Enable IAM token-based authentication for Amazon RDS

Amazon RDS supports IAM token-based authentication, allowing you to connect to a DB instance using IAM credentials. For more information, see Enable IAM Token-Based Authentication for Amazon RDS.

Restriction: The Akana Platform has added support for AWS Identity and Access Management (IAM) database authentication. Due to some limitations, it is not certified with Lifecycle Coordinator, Lifecycle Manager, and Lifecycle Repository, which includes Promotions and Custom Properties.

Database drivers

Depending on the database server you are using, install a database driver before running the Configure Database Options Wizard.

If you need to install a database driver, place it in the /instances/{container_name}/deploy location.

The following are the database options with driver information:

  • MySQL 8.0.x:

    Install the file mysql-connector-java-8.0.x.jar. Download from the mysql/mysql-connector-java repository.

  • Oracle 12c Release 2, Oracle 18c (18.3) supported in 2019.1.0 and later, Oracle 19c:

    Install the file Ojdbc8.jar. Download from the Oracle JDBC page.

    Also, see Database permissions, Oracle 12c R2 or later.

  • Microsoft SQL Server 2012 SP4: No database driver installation is required.
  • Microsoft SQL Server 2016 SP2: No database driver installation is required. If you don't install a driver, the default JTDS driver is used.

    The Akana API Platform has also been tested with the mssql-jdbc-7.2.2.jre8.jar driver. If you use this driver, install it by using the default JTDS driver. Complete the two pending tasks, Manage PKI Keys and Add Database, and then modify the configuration settings, and restart the container. You can modify the settings in the Admin Console or by editing the configuration file ({install_dir}/instances/{instance}/cm/com/soa/database/config/{config_file}). The settings to update are:

    • com.soa.database.config > driver change to com.microsoft.sqlserver.jdbc.SQLServerDriver.
    • com.soa.database.config > url change to jdbc:sqlserver://{server}:{port}/{database};user={user};password={password}. Be sure to substitute the correct values for your installation.

    After you have updated the settings, restart the container, and then resume the standard installation process from Step 6: Complete pending tasks to configure container features with the Manage Schemas pending task.

Installation folder structure (Akana Platform)

When you install the Akana Platform, the installation process creates a predefined folder structure.

Installation folder structure: Akana Platform

Installation includes the following folders:

bin
Includes the Akana Platform shell and batch scripts. This includes Start/Stop scripts for all the Akana Platform processes, scripts used to register and un-register Windows services, and scripts for launching the Akana Platform administration and configuration wizards. This folder also includes a script to run the Akana Platform product as a unique Cron job.
config
Includes Akana Platform properties files. Reserved for system use.
docs
Includes product documentation.
instances
After installation, the initial instances folder includes config.properties and system.properties files.
When you launch and complete the Configure Container Instance wizard, a Configurator folder is created that includes the following sub-folders:
  • asynchworkflow—Stores code samples for platform APIs.
  • cache—Stores OSGi bundles for installed features.
  • deploy—Includes properties files (com.soa.config.cfg and com.soa.log.cfg) that include Akana Platform default configuration settings. These files are used to push default configuration information to the Administration Console and are typically for one-time use only. After initial configuration, you can update properties in the Administration Console via the Configuration tab. Bundles and other .cfg files can also be added to the \deploy folder and will be published to the Administration Console. These properties can also be updated via the Configuration tab.
  • log—Stores log files that are automatically generated when an Akana Platform function is operating. The logging process records the actions performed for each Akana Platform function and stores the information in the log file. You can archive log files for historical record as needed.
Each time a new container instance is created, the platform creates a new folder using the container name. For example, if you install the Policy Manager ZIP file and name the container instance, the associated folder includes the above folders and the following:
  • cachedir—Reserved for system use.
  • cm—Stores configuration data associated with the Admin Console Configure tab.
  • scriptStore—Stores code samples for platform APIs.
  • snapshot—Stores changes to a container made during updates. Also used for update rollbacks.
  • wsdlStore—Stores code samples for platform APIs.
jre
A Java Runtime Environment (JRE) folder that is automatically created during an Akana product installation. The Akana Platform is packaged with the applicable JRE version for each release.
lib
Includes the jar files needed by the available Akana features.
recipes
A set of JSON files to be used in automating processes.
scripts
Includes script utilities to create containers without using the Configure Container Instance wizard UI.
yajsw
Includes files used by the Akana Platform to support YAJSW. See YAJSW.

Clear Configurator cache

If you are experiencing issues, you might need to clear the Configurator cache.

To clear configurator cache

  1. Locate the configurator cache \instances\configurator\cache folder.

    Configurator cache folder

  2. Delete the cache folder if it exists. If the folder isn't there, the cache doesn't exist and no action is needed.

Start a container

You can start a container in various ways depending on your operating system.

To start a container on Windows

  1. Open a command prompt and go the \bin folder. For example: c:\akana\aap202501\bin.
  2. Type: 
    startup {containername}

The container may take a few moments to start.

To start a container as a Windows service

  1. Launch the Services list (Control Panel > Administrative Tools > Services).
  2. Select the instance name on the list.
  3. From the right-click Actions menu, select Start.

The container may take a few moments to start.

To start a container on Unix

  1. Open the command line and go to the /bin folder. For example: /akana/aap202501/bin.
  2. Type: 
    startup.sh {containername}

The container may take a few moments to start.

To start a container on Unix (background)

  1. Open the command line and go to the /bin folder. For example: /akana/aap202501/bin.
  2. Type: 
    startup.sh {containername} -bg

The container may take a few moments to start.

Stop a container

You can stop a container in various ways depending on your operating system.

To stop a container at a command prompt

  1. Open the command prompt window where the process is running.
  2. Press Ctrl+C or simply close the command prompt.

To stop a container as a Windows service

  1. Launch the Services list (Control Panel > Administrative Tools > Services).
  2. Select the instance name on the list.
  3. From the right-click Actions menu, select Stop.
You can start or stop a container as a Windows service if it was installed as a Windows service.

To stop a container on Unix

  1. Open the command line window where the process is running.
  2. Press Ctrl+C or send a KILL signal to terminate the process.

To stop a container on Unix (background)

  1. Open the command line and go to the /bin folder. For example: /akana/aap202501/bin.
  2. Type: 
    shutdown.sh

Create a container via the GUI

As part of Step 3: Run Configurator to create the first container, you can use the GUI-based installation wizard to guide you through the setup process. For more information on the wizard, see Installation wizard: Configure Container Instance.

To create a container via the GUI

  1. Open a command prompt on Windows.
    To install a container as a Windows service, open the command prompt in Administrator mode. For example, type cmd, right-click, and choose Run as Administrator.
  2. Go to the new folder where you unzipped the version 2025.1 files (for example, aap202501).
  3. Go to the \bin subfolder and run one of the following commands depending on your operating system:

    On Windows:

    startup.bat configurator

    On Unix:

    startup.sh configurator

    The Configurator starts with the Welcome to Configure Container Instance wizard page.

    Configurator

  4. Click Next. The wizard steps you through the following:
    1. Instance Name: Specify the name of the Akana container instance. For example, PMCM1. Click Next.
    2. Default Admin User: Specify the administrator credentials (username and password). Click Next.
    3. Default HTTP Listener: Specify the port, host IP address, and bind to all interfaces/specified interface only, or accept defaults. Click Next.
    4. Instance Startup: Choose Standalone, Install as Windows Service, or Do Not Start Instance. Click Next.

      If you want to install as Windows service, the command prompt you used to start the Configurator must be running in Administrator mode.

    5. Launch Admin Console: The checkbox is selected by default. If you do not want to launch the Admin Console, clear the checkbox. Click Next.
    6. Instance Configuration Summary: Review the summary and click Finish.

The container is configured. When configuration is complete, the Admin Console starts automatically (unless you cleared the checkbox in the previous step; if so, you will need to start it manually).

After the container is created, continue with the next step of the installation procedure. See Step 4: Install Policy Manager/Community Manager features on the container.

Create a container using silent install (Linux)

As part of Step 3: Run Configurator to create the first container, you may need to create a container using a silent install, especially in Linux environments. Ensure you have the administrator privileges on the machine before proceeding.

A silent installation is an automatic process that installs the Akana Platform without any user interaction. Before running the silent install, you must configure the properties file to be used for the installation. This file includes the specific values that must be provided in the user interface if you are doing an installation using the GUI. For example, you must specify a target installation directory, install set, and input options to be executed at the end of the installation. After you have configured the properties file, deploy the platform onto multiple machines in a scripted, non-interactive way.

The name of the properties file doesn't matter as long as you reference it correctly when running the silent install.

One way to generate a "starter" properties file is to first create a container using the GUI. The properties file for the container is automatically saved in the directory for the container (../instances/{container_name}/system.properties). For example, if you create a pm01 container via the GUI, you can then look in the /instances/pm01 folder and see the system.properties file for the container. You can use the values from this file in setting up the properties file for creating subsequent containers, such as pm02, using the silent install method.

Copy and modify the file rather than changing the original file and update the container.key property so that it is unique. The container.key can only be specified during container creation and cannot be changed later.

You can also create the properties file from scratch. The following is an example. For more details about the properties file, see Configure Container (Silent Option).

When you create the properties file, make sure there are no trailing spaces.

Properties file with placeholders: 

//Required properties
container.instance.name={instancename}
credential.username = {username}
credential.password = {password}
default.host={hostname}
default.port={port}
//Optional properties
container.key={container_key_name}

Sample properties file with values: 

container.instance.name=aap202501
credential.username = administrator
credential.password = password
default.host=rhe12345.akana.local
default.port=9945
container.key=aap202501

To run the properties file in a Linux environment, go to the {release_directory}/bin folder and run the following command:

startup.sh configurator -Dsilent=true -Dproperties={full path to properties file}/{filename}.properties

For example:

startup.sh configurator -Dsilent=true -Dproperties=/root/akana/aap/properties/pmcm_silentinstall.properties

Then:

Unregister and re-register the Windows service

If you have a container registered as a Windows service, the container starts automatically when Windows starts and you want to unregister and re-register the Windows service, follow the steps for each container.

Unregistering and re-registering the Windows service is generally part of upgrade procedure or for troubleshooting purposes.

To see which containers are currently registered as Windows services, go to Control Panel > Administrative Tools > Services.

To change the services, you must run the process as an administrator. If you don't use administrator mode, Windows prompts for admin permission before unregistering/registering the service, but doesn't actually start the service.

To unregister and re-register the Windows service

  1. Open a command prompt in administrator mode.
  2. Run the following command: 
    .\{platform_folder}\bin\unregisterContainerServiceYAJWS.bat {instance_name}
  3. Register the new version as a Windows service: 
    .\{aap202501_foldername}\bin\registerContainerServiceYAJWS.bat {instance_name}

    If you are running in administrator mode, Windows registers the service and also starts it.

Repeat steps 2 and 3 for each additional container that is registered as a Windows service.

Linux install: Exporting the JAVA_HOME variable

Linux containers do not have a JAVA_HOME environment variable set, you must export the JAVA_HOME location to the installation directory.

For example:

export JAVA_HOME=/opt/akana/aap202501/jre

If you skip this step, the installation fails with an error.

Save the keystore/truststore and update the path

The default settings for the keystore/truststore are shown in the image.

Configuring the keystore and truststore location

If you change the JRE, you must update these settings so that the Akana Platform can access the truststore with the trusted certificates.

For example, you might create a new /{install_folder}/keystore folder and copy certificates into it.

To update the com.soa.security settings

  1. Install the Akana API Platform.
  2. Log in to the Admin Console.
  3. Click the Configuration tab.
  4. Update these two settings to the new location:
    • bootstrap.keystore.location. For example: file:///{install_folder}/keystore/certs.jks.
    • bootstrap.truststore.location. For example: file:///{install_folder}/keystore/certs.jks.
  5. Update other properties as needed, such as passwords for the new keystore and truststore locations.
  6. Save the changes.
If you don't set up a new location for this file and update the above properties, when you restart the container there will be issues due to missing certificates.

Install Repository Client (for the Lifecycle Coordinator or Extended Properties features)

If you use the Lifecycle Coordinator or Extended Properties features, it is best to use the Repository Client. This standalone, Eclipse-based IDE allows you to define the library functionality used within the Community Manager developer portal.

Follow the steps applicable for your operating system:

  1. Download the Repository Client file.
  2. Follow the installation instructions for your OS:

To download the Repository Client file

  1. Download the Lifecycle Manager ZIP file. See Installing Lifecycle Manager.
  2. Go to the /misc/ subfolder and get the Repository Client ZIP file based on your operating system:
    • Windows: RepositoryManagerClient.zip
    • Mac: RepositoryManagerClientMaxOSX.zip
  3. Copy the file to your installation location and unzip it.

To install the Repository Client file on Windows

Run the installer file RepositoryClientInstall.exe to install the Repository Client. After running the installer, the installation option is available in the Akana Administration Console.

You can now finish installing the applicable feature:

To install the Repository Client file on macOS

The Repository Client has not been certified to work on Mac machines with non-Intel processors. While some users have successfully installed it, but it has not been tested. If you have already installed the Repository Client file on macOS and are experiencing permission errors, see Cannot launch Repository Client app after installing on macOS.

  1. After unzipping the downloaded binaries, it is important to change permissions for the Repository Client app file:
    1. Open a terminal and go to the directory where the Repository Client app file is unzipped. For example: RepositoryClient_2019.1.30.00000.app.
    2. Run the following command: 
      chmod -R +x {RepositoryClient app filename}

      For example:

      chmod -R +x RepositoryClient_2019.1.30.00000.app

You can now finish installing the applicable feature: