Upgrade log analysis

Policy Studio provides graphical features to help you detect and analyze upgrade issues. You can perform the following in Policy Studio:

  • If sysupgrade has identified issues during the upgrade (for example, web service configuration issues), you can use the Tools > Upgrade Log Analysis option in Policy Studio to analyze the upgrade.log file. See Manual upgrade log analysis.
  • If you create a new project in Policy Studio from an existing configuration, or if you import a configuration fragment, an automatic upgrade is triggered and the Upgrade Log Analysis window opens. This allows you to view the log and resolve any issues. See Automatic upgrade log analysis.

This topic describes both cases with examples of how to resolve critical upgrade issues in Policy Studio.

Manual upgrade log analysis

The sysupgrade upgrade command might generate errors or warnings that need to be resolved in Policy Studio. This includes, for example, issues with web service or REST API configuration, or with OAuth credentials. For more details, see Example critical/major issues and recommended solutions.

When prompted to perform upgrade log analysis in Policy Studio, perform the following steps:

  1. Open the problematic API Gateway configuration in Policy Studio. For example, in Policy Studio version 7.6.2, create a new project using From .fed file or From .pol and .env files, and select the correct files under the following directory:

/opt/Axway-7.6.2/apigateway/upgrade/bin/out/upgrade/esgroups/groups/group-2/

  1. Select Tools > Upgrade Log Analysis from the main menu.

Upgrade Log Analysis screen

  1. Select the upgrade.log file generated by sysupgrade, for example: 
/opt/Axway-7.6.2/apigateway/upgrade/bin/out/log/upgrade.log
  1. Click Open.
  2. If the log file contains data on multiple groups, select the group configuration to analyze in the dialog.
Note   The upgrade.log file generated by sysupgrade can contain upgrade information for multiple groups, whereas the automatic upgrades triggered by Policy Studio are specific to the project upgraded.
  1. In the Upgrade Log Analysis pane, click View Log. For more details, see Example upgrade log analysis.

Automatic upgrade log analysis

An automatic upgrade can be triggered in Policy Studio when you create a new API Gateway project from an existing:

  • API Gateway configuration package (.fed, .pol or .env file)
  • API Gateway configuration directory

You can also trigger an automatic upgrade by importing an API Gateway configuration fragment (FileImport Configuration Fragment).

In either case, in the Upgrade Log Analysis pane, click View Log. For more details, see Example upgrade log analysis.

Policy Studio-triggered upgrade logs are stored under the policystudio/trace directory and are prefixed with the project name or configuration fragment name, for example:

  • webservice_fragment_upgrade_20160317125324.log
  • my_project_upgrade_20160417125319.log

For more details on creating API Gateway projects and importing configuration fragments, see Create a Policy Studio project and Import API Gateway configuration fragment.

Example upgrade log analysis

When upgrading an earlier version API Gateway configuration to version 7.6.2, the Upgrade Log Analysis pane on the right lists the upgrade issues that need to be resolved.

For example, when upgrading a version 7.3.1 API Gateway configuration, the following example shows an OAuth-specific issue and its recommended solution.

Upgrade log analysis issue

You can click the eraser icon on the left of each issue to mark the issue as complete when it has been resolved.

The following example shows a critical web service issue encountered when upgrading a version 7.2.2 configuration:

Upgrade log analysis issue

Tip   To see this informational window in Policy Studio, hover over an issue.

In this case, the web service could not be upgraded, and has been discarded. You must reimport the WSDL into your new API Gateway7.6.2 installation using Policy Studio. For more details, see Example critical/major issues and recommended solutions.

Upgrade indicators in Policy Studio tree

You can view the critical upgrade issues for web services (for example, the Discarded Web Services, or WSDL files using an Old Repository Format) as text in the Policy Studio tree on the left. If you close the Upgrade Log Analysis view or ignore the issues, the indicator text is no longer displayed.

View more details in upgrade log

To view more details on a specific upgrade issue in the right pane, click View Log to display the relevant entry in the upgrade log file.

Restore completed issues

All completed issues are persisted to disk. This means that you can shut down Policy Studio or the Upgrade Log Analysis view and continue later. To restore completed issues to the view at any time, click Show All Issues in the right pane.

This section describes some critical and major upgrade issues displayed by Policy Studio and provides recommended solutions.

Discarded web service

Problem: The WSDL file for the web service could not be upgraded.

Solution: You must re-register the WDSL in the web service repository. Perform the following steps:

  1. Copy the original WSDL URL displayed in Policy Studio to the clipboard.
  2. Click the Discarded web service hyperlink to locate the web service group it was originally registered in.
  3. On that web service group, right-click and select Register Web Service.
  4. In the WSDL registration wizard, paste the URL in the WSDL URL field.
  5. Click Next and complete the wizard to register the WSDL.
  6. Click the Mark this item as complete icon in the Upgrade Log Analysis window.

Old repository format

Problem: The WSDL file for the web service uses an old web service repository format (versions earlier than API Gateway 7.3.0).

Solution: You must re-register the WDSL in the web service repository. Perform the following steps:

  1. Click the Old repository format hyperlink to locate the web service to be re-registered.
  2. Right-click the web service, select Resynchronize Web Service, and select Yes.
  3. Copy the original WSDL URL to the clipboard, and select Cancel from the wizard.
  4. Right-click the web service node, select Delete, and select Yes.
  5. On that web service group, right-click, and select Register Web Service.
  6. In the WSDL registration wizard, paste the URL in the WSDL URL field.
  7. Click Next and complete the wizard to register the WSDL.
  8. Click the Mark this item as complete icon in the Upgrade Log Analysis window.

Web Service error: Failed to find binding for operation

Problem: The WSDL file the web service has no binding for a particular operation.

Solution: You must re-register the WDSL in the web service repository. Perform the steps listed in Old repository format.

OAuth Client Application Registry

Problem: A new mechanism for authenticating OAuth client application users in the REST servlet was introduced in API Gateway version 7.4.0. This issue only occurs if you are upgrading from versions earlier than API Gateway 7.4.0.

Solution: You must configure OAuth authentication settings in Policy Studio. Click Server Settings in the Policy Studio tree and select Security > Client Application Registry. In the Circuit for Authentication field, select a policy for authenticating users. This policy must authenticate the user against a user store of your choice and set the message attributes authentication.subject.role and user.email.The message attribute authentication.subject.role must be set to either admin or resourceowner. For more information on the Client Application Registry settings, see the API Gateway OAuth User Guide.

A sample policy for authenticating users is provided in apigateway/samples/oauth/authzserver/sampleUserAuthnPolicy.xml. This sample policy authenticates the user credentials against the local user store and sets the two required attributes on the message whiteboard, which are used to complete authentication and authorization process. If you use the sample policy, you must manually add a role (for example, role=admin) for the regadmin and sampleuser users. To add the role in Policy Studio, select Environment Configuration > Users and Groups > Users and add the role on the Attributes tab for each user. For more information on adding users, see the API Gateway Administrator Guide.

Migrated resolver for web service

Problem: In API Gateway 7.6.2, WebService resolvers are migrated to path resolvers during upgrade, because the WebService resolver had issues if the web service was renamed.

Solution: The migration to the path resolver removes this issue. The upgrade log contains the following minor warning if this migration affects a web service:

StockQuoteService Migrated resolver on path '/svcpath'. Confirm path is correct.

In some cases, the migration of the WebService resolver results in a conflict with another path resolver. In this case, the path resolver is renamed to avoid conflict. You are alerted to this with the following critical warning:

StockQuoteService Migrated resolver on path '/svcpath' was renamed to '/*** Path Conflict ‘/svcpath’' to avoid conflict. Please update appropriately.

You must enter a new unique path.

Discarded Contivo filter

Problem: The Contivo filter is not supported in API Gateway 7.5.1.

Solution: We recommend that you replace this filter with the Execute Data Map filter.

This section describes some warnings displayed by Policy Studio and provides recommended solutions.

Fastest scripting language not used

Problem: A warning appears if you are using a Scripting Language filter in your old installation with the Language field set to JavaScript (Rhino engine JRE7 and earlier).

Solution: Change the Language of the filter to JavaScript and ensure that the JavaScript syntax in the script conforms with Nashorn engine syntax. Alternatively, you can ignore the warning, meaning that the script continues to work but not with the optimal performance.

Cassandra connection details

Problem: A warning about the Cassandra connection details appears when you are upgrading from API Gateway versions earlier than 7.5.1 to 7.6.2.

If you upgrade your entity store configuration using sysupgrade, you can set the Cassandra connection details for the 7.6.2 installation using the upgrade command options --cass_host, --cass_port, --cass_username and --cass_password. If you have done this correctly, you can ignore the warning.

If you upgrade your entity store configuration in Policy Studio, the Cassandra settings are set to the default settings (for example, localhost).

Solution: After the upgrade, ensure that the Cassandra connection details are correct.

ActiveMQ path update

Problem: A warning appears if ActiveMQ is enabled in your old installation, reminding you to update the Shared Directory field if necessary. Upgrading your entity store in Policy Studio does not automatically update the Shared Directory field or backup the data. This warning indicates you might need to take some actions.

If you upgrade your entity store configuration using sysupgrade, and the Shared Directory field is an absolute path under the old installation directory (for example, /opt/Axway/7.3.1/apigateway/activemq), sysupgrade automatically updates the directory to be the equivalent directory under the new installation directory (for example, /opt/Axway/7.6.2/apigateway/activemq), and copies the data over to the new installation.

If you upgrade your entity store configuration using sysupgrade, and the Shared Directory field is an absolute path that is unrelated to the installation directory (for example, /mynetworkdrive/activemq), sysupgrade backs up the data, but does not update the Shared Directory field.

Solution: After the upgrade, ensure that the path defined in the Shared Directory field for ActiveMQ is not an absolute path that can be accessed by both the old and new installations of API Gateway. You can ignore the warning if the field points to a directory that is not shared between the old and new installations, for example, any non-absolute path.

Default SSL ciphers/options not used

Problem: If an API Gateway group or Node Manager configuration contains an SSL interface that has old SSL settings (default ciphers and SSLv2/v3 allowed), a warning appears suggesting that you reconfigure the SSL settings. Similar warnings are generated for system ports and custom ports.

Solution: Reconfigure the affected HTTPS listeners to use the recommended ciphers and protocol settings. Alternatively, you can ignore these warnings.

Amazon Web Services filters

Problem: A warning appears if an Amazon Web Services filter without a setting for either AWS Credential or Client settings is found.

Solution: During the upgrade, dummy settings are added to affected AWS filters. A warning message indicates the affected filters. Replace the dummy settings with valid values, so the filters work correctly.

API Gateway KPS collection

Problem: A warning appears when configuration from an old installation does not contain the KPS schema required by the OAuth Client Application Registry. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.

Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/APIServerKPSDefinition.xml.

KPS table PortalExternalClientStore missing

Problem: A warning appears when configuration from an old installation does not contain the KPS table PortalExternalClientStore. This table is required by API Manager. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.

Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/APIServerKPSDefinition.xml.

OAuth resource owner login

Problem: This warning appears if an old installation is configured to use the same cookie name for both OAuth client and OAuth server configurations. It is a minor issue that only affects test environments where client and server share the same host name (for example, localhost).

Solution: Change the cookie name for OAuth logins on either the client or the server.

OAuth services interface

Problem: This warning appears when multiple listeners implementing OAuth services are found in the old configuration. Upgrade can only successfully upgrade canonical listeners that follow the naming construct of OAuth 2.0 Services.

Solution: Ensure that the Servlet and Path definitions of additional OAuth listeners match those of the default listener OAuth 2.0 Services. If the standard listener definition is not in the configuration, it can be imported from samples/oauth/authzserver/config.xml.

OAuth KPS definitions missing

Problem: A warning appears when configuration from an old installation does not contain the KPS schema required for OAuth token storage. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.

Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/OAuthTokenKPSDefinition.xml.

OAuth authorizations table missing

Problem: A warning appears when configuration from an old installation does not contain the KPS schema required for OAuth authorization storage.This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.

Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/OAuthTokenKPSDefinition.xml.

Related Links