Migration considerations

Limitations and workarounds

• For an Admin organization, you must be logged in as admin in order to migrate TLS profiles, OAuth providers, and user registries.
• The apicm login token expires after eight hours. If the token expires while apicm archive:push is running, apicm generates errors due to lack of the necessary access permissions. There are two workarounds:
  • Log in again and re-run apicm archive:push. The token is refreshed with each new login.
  • Extend the token expiration time by logging in again with an optional argument: –expireHours=<number_of_hours>. See Token expiration.
• When migrating catalog spaces in an provider organization that uses a local user registry (LUR), ensure that the LUR is configured with the visibility setting of either Public or Custom. If set to Custom, ensure that the provider organization is selected. For information on configuring registries, see Setting visibility for a user registry.
• Migration of version 5 username token policy for authenticating the username token is not supported.
• Unable to publish, on version 10, products that contain an API with a Swagger property using regex that includes "(?" in the characters for the pattern. You can expect to see an error message similar to the following:

  (? The preceding token is not quantifiable

• The migration utility validates Products and APIs against the OpenAPI specification. The archive:unpack command issues warnings for any Product or API that fails validation. To resolve warnings, fix the Product or API an re-run the unpack command. Validation is not performed on draft Products and draft APIs. Example warning:

  WARN[0019] Error validating product cloud/provider-orgs/onlinebanking/catalogs/test/products/clientipfilter-policy-test-api-1.0.0.yml:
   Validation errors:
    Error validating API cloud/provider-orgs/onlinebanking/catalogs/test/products/api123-1.0.0.api.yml
    - Must validate one and only one schema (oneOf) (context: (root).securityDefinitions, line: 36, col: 3)
    - securityDefinitions.authorizationUrl Does not match format 'uri' (context: (root).securityDefinitions.authorizationUrl, line: 0, col: 0) 

• OAuth Provider APIs:
  • To ensure that APIs that use OAuth security definitions are mapped to the corresponding OAuth Provider APIs in version 10, make sure that either the Authorization URL or the Token URL defined in OAuth Security Definitions of APIs that use OAuth correctly point to the base path of the OAuth Provider API. Note that the Migration tool uses that logic to map Consumer APIs to Provider APIs, and adds x-ibm-oauth-provider in the OAuth Security Definition of the consumer API.
  • To verify whether OAuth Provider APIs are migrated correctly, ensure that all the APIs that use OAuth Security Definition have the new field x-ibm-oauth-provider added. Check the value of that field and make sure it points to a correct OAuth Provider resource object that was created and configured in the catalog to which the API is published.
  • In version 5 OAuth Providers are a specialized type of API that are published within products. In version 10, OAuth Providers are first class objects that are directly published in the provider organization and are not APIs that are published within products. Because of this, it is possible that you may have some version 5 products that only contained OAuth Provider APIs. Since these products do not contain any Open API definitions in version 10, they will not be published because all products in version 10 must contain at least one Open API definition.
• Automatic migration of vendor extensions is not supported. The version 5 dbextract output includes the original content of vendor extensions, but this output is not automatically unpacked by the apicm archive:unpack command. You must use your original zip files when manually configuring vendor extensions in a version 10 environment.

  Use the CLI to create the extensions you need. See the reference page for apic extensions:create: apic extensions:create.

• Portal Delegated User Registry migration limitations
  • Automated migration is not supported for some version 5 PDUR OIDC registries. You must manually supply the client_id and client_secret. See Step 6 in Migration steps with PDUR.
  • LDAP User Registry - automated configuration of the registry is not supported. You can configure manually. See Step 6 in Migration steps with PDUR.
• The SCIM (System for Cross-domain Identity Management) user registry type was supported in Version 4 but was deprecated for Version 5. The SCIM user registry type is not supported in version 10. If data with a SCIM identity provider type is detected during migration of version 5 data, the migration utility logs an error message:

  WARN[0614] manual fix required for cloud/provider-orgs/apimteam/user-registries/scimcv/user-registry.yml:
  The SCIM user registry type is no longer supported  

  Any v5 data with a SCIM identity provider type must be manually migrated. For version 10, you can use OIDC with a backend user registry that supports SCIM. You must develop custom code to complete the data flow between the OIDC provider and your backend user registry. The API Connect built-in OIDC registry interacts with your OIDC provider.

• Roles limitations

  Previously, in API Connect 5, it was possible to create a role (and associated permissions) at the organization level. This same role was inherited by the catalogs within this org. With the version 5 inheritance model it was possibly to modify the inherited role and add/remove permissions from it.

  In API Connect 10 the inheritance model has changed. It is no longer possible to remove permissions from an inherited role. Because of this design change, it becomes difficult to perform a true 1-to-1 migration keeping the original parent-child relationships. For example, in version 5 it was possible for an inherited role to contain less permissions than its parent role. This is parent-child relationship is not allowed to exist for roles in API Connect 10.

  In order to work-around this restriction, the parent-child relationship is purposely decoupled during migration. The child-level roles are treated as individual roles, separate from the original parent. However, the child-level roles cannot exist by themselves without a parent role. So, to satisfy this restriction a new artificial parent role is created for each of the children roles.

• Modifications made to default roles in version 5 are not migrated to version 10.
• If the version 5 settings server_name_indication and limit_renegotiation are not specified, the value defaults to true. However if they are specified with value of false that value is changed to true. Thus the settings are always true.
• Custom policies and Version 5 emulated policies

  For custom policies and Version 5 emulated policies, such as the Invoke 1.5.0 policy, to be available for migrated API or OAuth provider assemblies, the Sandbox Catalog in the target provider organizations must have the associated DataPower® API Gateway service enabled; see Creating and configuring Catalogs.

• Subscriptions on staged products are not be automatically migrated because in version 10 staged products cannot have subscriptions on them. In order to save those subscriptions you must change the state of the product to either deprecated or published before doing the archive:push. You can do this either in version 5 before running dbextract, or you can do it after the dbextract through mapping or editing of the product metadata and modifying the state of the product. If you have already pushed the staged product then you can publish the product in your version 10 environment and rerun archive:push in order to migrate the subscriptions.
• The migration utility appends -apigw to the end of the x-ibm-name of APIs to maintain uniqueness from the original version 5 artifacts. Therefore, custom backend services that rely on the x-ibm-name of the APIs to be matched must be updated to look for -apigw in the new API name. Alternatively, the custom backend service can be modified to strip -apigw from the API name.

Version 5 data that is not migrated

• APIs with LTPA policies are not migrated as this policy is not supported in version 10.
• Configuration in version 5 for gateway type Microgateway is not migrated because Microgateway is not supported in version 10.
• Transient or conflicting configuration data is not migrated
  • Tasks that are still active are not included in the Version 5 backup. For example, lifecycle approvals or subscription approvals that have been requested but not granted.
  • Drafts on version 5 that are local are not migrated. If you have draft APIs or draft products that you want migrated to version 10, use apic drafts:push to upload them prior to starting migration. See Working with drafts.
  • Pending invitees in user registries are not migrated.
  • Pending invitations for ownership of provider organization. Consumer organizations with pending ownership are migrated.

    If the Version 5 owner received an invitation for ownership but never accepted it, the owner identity is not migrated. This causes the organization to not be migrated. To avoid this issue, check for any unaccepted invitations prior to migration, and ensure they are accepted.

  • Conflicting user names within the same identity provider are not migrated.
  • Conflicting OAuth provider names or base paths. If the migration utility encounters conflicting names or base paths for OAuth providers, the provider is not migrated.
• OAuth Shared secret keys are not migrated unless you explicitly map them in the mapping.yml file for the gateway.

• Organizations without an active owner (user identity) are not migrated

  On the Version 5 deployment, verify that the owners of provider organizations and consumer organizations are current user identities. If the user identities of the owners no longer exist the identities are not migrated. One effect of this is that if the original owner of the organization is an identity that was not migrated, the provider organization or consumer organization cannot be migrated.

• Version 5 Analytics data is not migrated

  If you want to retain Version 5 analytics data, offload your Analytics prior to migrating to Version 10. Note that in Version 5 the analytics data is retained only for 90 days. For more information on Version 5 support for archiving Analytics data, see Viewing and exporting analytics and API event data.

Parity between Version 5 and Version 10

• The migration utility sluggifies the names and versions of some elements when moving from version 5 to version 10 to ensure that each element in version 10 passed Open API schema validation and that each is uniquely named. For the names of API properties, Catalogs, Provider Orgs, Consumer Orgs, Spaces, and some other elements, any character other than a-z, 0-9, or -, is converted to - and a unique suffix based on the checksum of the name or version is added. Uppercase letters are changed to lowercase, with - added between words. Leading - characters are removed, and multiple consecutive - characters are reduced to a single -. For versions of similar elements , the . (period) character is also allowed. Examples:

  Version 5 name	Example migrated name on version 10
  abc-def	abc-def (no change)
  Abc	abc-a2c6
  AbcDef	abc-def-dfc
  Abc Def	abc-def-1e82 With sluggify-no-checksum: abc-def
  abc_def	abc-def-c2bb
  abc--def	abc-def-813d
  -abc-def	abc-def-abb
  ABC-DEF	abc-def-d1e

  Version 5 version	Example version on version 10
  1.0.0	1.0.0 (no change)
  1.0_2	1.0-2-3933
  1.0 2	1.0-2-913
  1.0--2	1.0-2-5410
  -1.0-2	1.0-2-26cf

  You can use apicm sluggify <arg> to view how a name or version will be sluggified:

  $ ./apicm sluggify Abc
  abc-a2c6
  $ ./apicm sluggify -v 1.0_2
  1.0-2-3933
  $./apicm sluggify --version '1.0 2'
  1.0-2-913

• Version 10 does not support Spaces within the Sandbox Catalog.

  Spaces in Sandbox Catalogs are not migrated from Version 5 to Version 10. The names of Spaces found in Version 5 Sandbox Catalogs are logged in the migration output log. You can use a mapping file to rename the Sandbox Catalogs in order to preserve Spaces.

• In version 10, publish of an API will fail if enforced is set to true, and phase is set to either Specified or Identified instead of Realized. During migration the phase will be set to Realized in this case, so that the API can be successfully published.
• Enforcement of user subscription to an API is handled differently between version 5 and version 10. In version 5, subscription to a product is not allowed in the following scenario: An API is created with enforced set to false. The API is associated with a product, the product is published, and a user attempts to subscribe to a Product or Plan from the Developer Portal. In version 10, the subscription is allowed for this scenario.

  This change can affect migration because a version 5 Product that could not be subscribed to in version 5 can be subscribed to in version 10. Note that the change in behavior for version 10 accommodates the scenario where Products or Plans have multiple APIs, some of which are enforced and some of which are not enforced. The new behavior allows such Products or Plans to be subscribed to.

• In version 10, the API Manager handles all authentication methods. This change eliminates the need for configuration of a catalog with a Portal Delegated User Registry (PDUR). See Migration steps with PDUR.
• If OpenAPI info.contact.email contains more than one email address, only the first email is used by migration. If the email is not in valid RFC5322 email format then it is removed during migration.
• Provider-side applications

  In API Connect, registered applications are a fundamental concept representing an application identity known to the system. Applications have their own credential sets in the form of client ID and client secret pairs, and access to published API endpoints is governed by subscriptions associated with registered applications. Most commonly, registered applications are created by app developers belonging to a consumer organization in the context of a developer portal.

  However, API Connect 5 also provides the ability for provider organizations to register and manage applications, independent of any consumer organization. Provider-owned apps behave in the same way as consumer-owned apps and carry credentials and subscriptions in exactly the same way. Customers use provider-owned applications for API testing or for cases where the app and API are owned and managed directly by the same team.

  The API Connect 10.x platform API does not support the creation of provider-side apps, so migration of provider-side apps is only possible if they are converted to consumer-side apps. Each provider-side app is migrated as follows by the API Connect migration utility:

  • An instance of the app including its credentials (sets of client ID and secret) is created in each catalog belonging to the provider organization.
  • The app is owned by a consumer organization which is the existing Sandbox Test Organization (for the provider organization's automatically created sandbox catalog) or a consumer organization named Catalog-name Test Organization (for other catalogs).
  • The consumer organization's owner is a user named test-user. This user name already exists in the context of a provider organization's automatically created sandbox catalog.
  • The consumer organization's owning user belongs to a user registry named catalog-name-test-org.
  • The subscriptions belonging to the original provider-side app are retained.
  These definitions are added to the relevant locations subordinate to the cloud/ directory that is produced by the apicm archive:unpack command. When an apicm archive:push is performed, the definitions are propagated to the target system as part of the overall configuration.

Customizations to recreate

Version 5 provides methods to customize some configurations. After you complete the automated migration, manually reapply the following customizations.

• Customized email templates

  Customized email templates are not migrated from Version 5. You can customize email templates in Version 10 with greater flexibility and precision. See Customizing email templates.

• Developer Portal customizations are not migrated to a new Drupal version

  For the Developer Portal, none of the customizations are migrated because the Version 10 Drupal 9 baseline differs greatly from the Version 5 Drupal 7 baseline. This means that custom portal themes, custom modules, custom fields, custom blocks, custom pages, and more, cannot be migrated. For more information, see Migrating your Developer Portal from Version 5 to Version 10.