Migration troubleshooting

apicm command line help

You can use command line help to review usage syntax for apicm. For example:

 ./apicm help
APIConnect migration toolkit

Usage:
  apicm [command]

Available Commands:
  archive:port-to-apigw Port artifacts to apigw
  archive:push          Push catalog archive content to APIConnect server
     Locate PLATFORM_API_ENDPOINT in the apiconnect-up.yml file used during apic install
  archive:unpack        Unpack a V5 management/portal archive
  help                  Help about any command
  login                 Log in to IBM API Connect
  version               APIConnect migration toolkit version 

Flags:
  -h, --help   help for apicm

Use "apicm [command] --help" for more information about a command.

Example usage for more information about a command:

$ ./apicm archive:push help

Usage:
  apicm archive:push PLATFORM_API_ENDPOINT ARTIFACT_PATH [flags]

Flags:
      --apigw-only   Only attempt to push APIGW artifacts
      --dry-run      Prepare the working directory but do not push to server
  -h, --help         help for archive:push
  -f, --overwrite    Delete and re-push resource if it exists on server

Log files for apicm

The apicm command creates log files that you can use to review messages produced by the unpack and push actions. All logs are saved in the logs directory. Unique files are saved for each run. All default log names can be overridden via the command line.

Error log

Includes all warning and error level messages. Default file:

logs/ErrorLog<timestamp>.log

You can optionally give the file a different name:

apicm --saveErrorLog= '<filename>'

For example:

apicm archive:unpack  apic33-2020-02-19-1650.tar.gz  --saveErrorLog= ‘unpack.txt’

This command creates a file unpack.txt in the logs directory:

~/example/migration-cli/logs/unpack.txt

Info Log

Includes all info, warning and error level messages. Default file:

logs/InfoLog<timestamp>.log

You can optionally give the file a different name:

apicm --saveInfoLog= '<filename>'

For example:

apicm archive:unpack  apic33-2020-02-19-1650.tar.gz  --saveInfoLog= ‘unpack_info.txt’

This will create a file unpack_info.txt in the logs directory:

~/example/migration-cli/logs/unpack_info.txt

Debug Log

Includes all info, warning, error and debug level messages. If you encounter errors or limitations that are not documented on this page, access the DebugLog<timestamp>.log which located in the directory where you extracted apicm. Contact your IBM representative for help with using the Debug log.

logs/Debug/DebugLog<timestamp>.log

Common errors

You can use the --saveErrorLog flag to specify that all the errors are saved in a file in logs folder, as described in Saving the error log. Common errors:

• API Validation Failed:

  This error occurs when an API within the v5 extract does not conform to the Open API specification. Due to stricter validation on v10, the API must be corrected to get added to the new system in v10. Use the error message and particular files references to resolve the API issue. The error is usually is caused by a missing property definition default or invalid default value.

  Example:

  time="2020-01-27T18:15:24-08:00" level=error msg="unable to create Product access-points:1.0.0"
  time="2020-01-27T18:15:24-08:00" level=error msg="access-points:1.0.0: API property 'authURL' does not have default value."
  time="2020-01-27T18:15:24-08:00" level=error msg="access-points:1.0.0: The multipart 'openapi' field contains 
  an OpenAPI definition accesspointsoap:1.0.0 (AccessPointSoap) that has validation errors."
  

  Following is the section of the AccessPointSoap API definition for the concerned API where the field in question exists:

  EFS-PerfTest:
     properties:
        authURL:https://test1.example.com/test-icdc/efs-perftest/reststub/25
        invokeURL:https:///test1.example.com/test-icdc/efs-perftest/fivekbsoap/650

  The backend does not expect authURL field as a part of the properties and hence is validation fails.

• Long chain of error messages hours into a push:

  This scenario typically occurs due to expiration of an authentication token. To resolve this issue, either reauthenticate and or extend the token timeout. See Token expiration.

• Unable to find User Registry when migrating (pushing) a provider-org:

  Occurs when the admin-org user registry artifacts are not shared prior to pushing provider organization artifacts. To resolve the issue, use the cloud admin account to change the visibility of the registry to public, and push the provider organization again.

• Unable to find xxxx when migrating (pushing) a provider organization:

  Occurs when admin-org artifacts are not pushed prior to pushing provider organization artifacts. Ensure that all of admin org data is pushed without errors, and then push your provider organization again.

• Object.PropertyName does not match format uri

  This error occurs during artifact validation when a specific property does not match a proper URI identifier. Check the mentioned field and change it to its proper URI format (https://example.com/optionalPath)

• Unable to create an identity provider portal-delegated-identity-provider xxxx because the PDUR backup data is not provided.

  This error occurs if certain Portal delegated user registries are missing from the PDUR extract provided. If the missing user registries are not no longer used, they can be skipped. If they are still used, you must create a fresh backup of the PDUR.

• Unable to create product xxxx. The OpenAPI definition <xyz> requires the policy <sample-policy> that is not configured on the gateway-service <sample-gateway>:

  This error occurs when the specified policy is not configured on the gateway for the catalog that contains the product. To resolve this, you must configure, on the v5 system, the specified policy on the gateway for the catalog, and re-extract the data.

• Fixing API Errors

  When encountering API issues, you might see the following error:

  WARN[0100] skipping product “EXAMPLE/FILE/PATH”  one or more OpenAPI definitions are invalid

  Prior to this error, you will see some additional lines that detail the particular issues with the OpenAPI definition.

  For example:

  WARN[0100] - Additional property bakonline.backend.url is not allowed (context: 
  (root).x-ibm-configuration.catalogs.properties, line: 0, col: 0)

  In this example, the property bakonline.backend.url with element at x-ibm-configuration.catalogs.properties in the OpenAPI spec is broken. Remove or correct the incorrect property.

• For apicm archive:push: Error: A resource of type gateway_extension with the key <key_value> already exists.

  When multiple v5 gateway services are mapped to the same API Gateway, then custom policies of only the first gateway service are migrated. Note, that if custom policies are not used, the following error is generated, but can be ignored:

  An error occurred while attemping to push  
  .workdir-api.example.com-1589574253/cloud/admin-org/availability-zones/availability-zone-default/gateway-services/dp612-upgrade/gateway-extension.zip.  
  Error code: 409, Reason: [A resource of type gateway_extension with the key  
  cf763bf9-9827-4fb6-92d7-7d9a5eae14be:eed7875b-036f-43de-ad82-dc34ee6670df:b67614e2-e27b-4e46-9a4d-2b8bab879164  already exists.]

• v5 emulated policies and custom policies not deployed to gateway. Make sure the following was done during the migration steps:
  • xml-manager is enabled in default domain of all gateways
  • Mapping of gateways was done before the porting step
  • gateway-extension.zip shows up under cloud/admin-org/availability-zones/availability-zone-default/gateway-services/<gw-name>/gateway-extension.zip
  • Ensure push of admin-org is done after all of the above is verified

Common errors with OAuth Providers

• Message: Multiple OAuth Providers matching basePath: <X> and scopes: <Y>....

  Occurs when the migration utility attempts to match an OAuth Provider to an API but cannot determine a single matching OAuth Provider. In this case, the utility lists all of the matching OAuth Providers and selects the first one. If this selection is not correct, you must manually set the OAuth Provider in the .yml file for the API.

• Message: Could not find an OAuth Provider that matches calculated basePath: <X> but did find one to match the Scopes: <Y>

  Occurs when the migration utility could not properly calculate the basePath from the TokenURL or AuthorizationURL of the API, but was able to find an OAuth Provider based upon matching Scopes. In this case, the TokenURL or AuthorizationURL is overridden with a working value. Verify that the match and calculated values in the API are correct.

• Message: Could not find an OAuth Provider than matches calculated basePath: <X> but did find multiple that match the Scopes: <Y>

  Occurs when the migration utility could not properly calculate the basePath from the TokenURL or AuthorizationURL of the API , but found multiple OAuth Providers based upon matching Scopes. In this case, the TokenURL or AuthorizationURL are overridden with a working value, and all matching OAuth Providers are listed, and the utility selects the first one. If this selection is not correct, you must manually set the OAuth Provider in the .yml file for the API.

• Messages Unable to find an OAuth Provider to extract from Token URL or Authorization URL %s with basePath %s and scopes %s

  Occurs when the migration utility could not match the basePath and Scope to an existing OAuth Provider. The utility creates a placeholder OAuth Provider value for the API in the .yml file. You must replace it with the appropriate OAuth Provider. In the .yml file, you must also set the TokenURL or AuthorizationURL and the scopes to acceptable values. This error message can occur when the appropriate OAuth Provider was not migrated.

Error messages and warnings from archive:unpack

"AMUAU000E": "The migration tool failed to initialize."

The migration utility could not access files or directories needed to establish its working environment. Ensure that file permissions allow write access to the current working directory and that the cloud directory is empty or non-existent.

"AMUAU001E": "The {{.Type}} {{.Name}} contains content that could not be unpacked and will not be included."

The migration utility is unable to read the API Connect v5 representation of an object in the migration archive. This content is skipped and will not appear in the unpacked migration data.

"AMUAU002F": "The archive content at {{.DocPath}} cannot be read."

The migration utility is unable to read the internal contents of a collection in the API Connect v5 migration archive. This is likely to indicate a corrupt migration archive file. The archive:unpack operation cannot be completed.

"AMUAU003E": "The portal delegated user registry file {{.File}} cannot be unpacked and will be skipped."

The migration utility is unable to read a PDUR archive. User information associated with this user registry will not be included in the unpacked migration contents.

"AMUAU004E": "The archive content at {{.FilePath}} cannot be read and will not be unpacked.",

The migration utility is unable to read the internal contents of an individual file in the API Connect v5 migration archive. This is likely to indicate a corrupt migration archive file. This content is skipped and will not appear in the unpacked migration data.

"AMUAU005W": "{{.Type}} {{.Name}} requires updating before it can be pushed to a target system."

The migration utility has unpacked a configuration object for which modifications are required because the content is incorrect or missing information required by a target API Connect v10 system. The unpacked file must be updated by the user before it can be published successfully to the target system.

"AMUAU006W": "The {{.Type}} {{.Name}} has been linked to OAuth provider {{.Provider}}. Please update the security definition {{.Security}} if another OAuth Provider should be used instead."

The migration utility has added a reference from an OAuth security definition in the named API to an OAuth provider resource. The migration utility uses the authorization URL, token URL and scope information where possible to determine which OAuth provider resource is to be used with each OAuth-secured API. In some cases, the migration utility cannot accurately determine which OAuth provider is intended for use with a particular API. The OAuth provider reference can be modified if needed by editing the security definition in the unpacked API file and changing the x-ibm-oauth-provider property value to match the intended OAuth provider resource. The reference value is a relative file path that identifies an unpacked OAuth provider resource.

"AMUAU007W": "The {{.Type}} {{.NameVersion}} could not be linked to an OAuth provider. Please update the security definition {{.Security}} to select an OAuth provider."

The migration utility has been unable to add a reference from an OAuth security definiton in the named API to an OAuth provider resource.

The migration utility uses the authorization URL, token URL and scope information where possible to determine which OAuth provider resource is to be used with each OAuth-secured API. In some cases, the migration utility cannot accurately determine which OAuth provider is intended for use with a particular API. The OAuth provider reference can be added by editing the security definition in the unpacked API file and setting the x-ibm-oauth-provider property value to match the intended OAuth provider resource. The reference value is a relative file path that identifies an unpacked OAuth provider resource.

"AMUAU008W": "{{.Type}} {{.Name}} could not be introspected for OAuth provider API references."

The migration utility has attempted to determine which OAuth providers should be configured in support of an API product, but a reference to an OAuth provider API in the product cannot be correlated with an OAuth provider resource.

"AMUAU009W": "{{.Type}} {{.Name}} contains invalid content that cannot be unpacked.",

The migration utility has encountered an entry in the API Connect v5 migration archive that contains unexpected or corrupt data. This content is skipped and will not appear in the unpacked migration data.

"AMUAU010E": "{{.Type}} {{.Name}} cannot be unpacked to the local filesystem."

The migration utility has attempted to unpack an entry in the API Connect v5 migration archive that could not be written to the local filesystem during the archive:unpack operation. This may be the result of a local file permissions problem, an unexpectedly long file name resulting from the unpack, or a shortage of space on the local filesystem.

"AMUAU011E": "{{.Type}} {{.Name}} contains a {{.Target}} reference that cannot be resolved."

The migration utility has encountered a SOAP API entry in the API Connect v5 archive that refers to a WSDL definition that cannot be found in the archive. This entry will not be included in the unpacked content.

"AMUAU012W": "The {{.Type}} {{.Name}} contains a {{.Target}} reference that cannot be resolved."

The migration utility has encountered an entry in the API Connect v5 archive that refers to another entry that cannot be found in the archive. This entry will not be included in the unpacked content.

"AMUAU013E": "Portal delegated user registry information could not be loaded for user registry {{.Name}}.

The migration utility has encountered a portal delegated user registry definition in the API Connect v5 archive for which no PDUR file name has been provided as an argument to the archive:unpack command. The user registry contents will not be included in the unpacked content.

"AMUAU014E": "The migration tool failed to load content for the admin organization."

The migration utility was unable to find the admin organization while unpacking provider organization information in the API Connect v5 archive. This is likely to result in further errors while unpacking the provider organization contents.

"AMUAU015E": "The migration tool failed to load provider organization contents."

The migration utility was unable to find the load provider organization contents while unpacking the API Connect v5 archive. This message indicates an internal error with the migration utility.

"AMUAU016E": "The {{.Type}} information belonging to organization {{.Org}} could not be unpacked."

The migration utility was unable to process the provider organization contents while unpacking the API Connect v5 archive. This message indicates an internal error with the migration utility.

"AMUAU017W": "The settings update for {{.Type}} {{.Name}} could not be completed."

The migration utility was unable to update the settings for a configuration object while unpacking the API Connect v5 archive.

"AMUAU018E": "Apps belonging to provider organization {{.Org}} could not converted to consumer apps."

The migration utility was unable to convert registered applications belonging to the provider organization into applications in each catalog. The conversion occurs because the representation of applications differs between API Connect v5 and API Connect v10. This message indicates an internal error in the migration utility.

"AMUAU019W": "User registry {{.UserRegistryName}} must be migrated to a different user registry type."

The migration utility has encountered a user registry in the API Connect v5 migration archive that is not directly supported in API Connect v10. User entries can be migrated if a mapping file is used to override the user registry name and refer to another user registry that has been created in the target API Connect v10 environment.

"AMUAU020W": "User {{.User}} in portal delegated user registry {{.Registry}} is not associated with any OIDC provider and will be skipped."

The migration utility has encountered a user entry in the API Connect v5 migration archive that belongs to a portal delegated user registry but cannot be associated with any backing identity provider. This can occur if no PDUR export file has been provided, or if the user entry information is incomplete.

"AMUAU021W": "the TLS profile {{.Name}} includes an unsupported protocol {{.Protocol}} that will not be included in the configuration."

The migration utility has encountered a TLS profile entry in the API Connect v5 migration archive that uses a protocol that is not supported in the API Connnect v10 environment. This protocol will be omitted from the unpacked entry for the TLS profile.

"AMUAU022W": "User {{.UserName}} ({{.ID}}) will need a password reset"

The migration utility has encountered a user entry in the API Connect v5 migration archive that is associated with a local user registry but does not have a password configured. The user entry will be migrated, but the user's password reset must be reset before logging in. This may occur when user registry mappings are used to migrate users to a local user registry from some other user registry type.

"AMUAU023W": "Uniqueness of names cannot be guaranteed when using the --sluggify-no-checksum option during unpack"

he archive:unpack command has been invoked with an option that could in unusual cases result in duplicate names being used for different unpacked entries. This is likely only for names with near-identical spelling but differ only in their use of upper and lower case letters or symbols that are converted to a hyphen during the unpack process. If duplicate names appear for entries of the same type in the same context, further messages indicating problems with the duplicate will appear.

"AMUAU024E": "The stats summary could not be generated"

The migration utility was unable to produce information listing the total numbers of entries of different types that were unpacked from the API Connect v5 migration archive. This message indicates an internal error in the migration utility.

"AMUAU025I": "{{.Type}} {{.Name}} contains an invalid value that will be removed."

The migration utility has encountered an entry in the API Connect v5 migration archive that contains a value that is not valid for the property in which it appears. The invalid value is automatically removed. This can occur with values such as email or URL properties that contain values that do not match the required format.

"AMUAU026I": "{{.Type}} {{.Name}} contains an invalid value that will be replaced."

The migration utility has encountered an entry in the API Connect v5 migration archive that contains a value that is not valid for the property in which it appears. The invalid value is automatically corrected. This can occur with values such as email or URL properties that contain values that do not match the required format.

"AMUAU027W": "The product subscription {{.Name}} cannot be pushed to the target system."

The migration utility has encountered a subscription entry in the API Connect v5 migration archive that refers to a product that is in a state that does not allow subscriptions. The subscription is removed and will not appear in the unpacked data.

"AMUAU028E": "The migration tool failed to create default roles for {{.Type}} {{.Name}}."

The migration utility has encountered an error while attempting to create the default roles for an organization, catalog, or space. This may be the result of a local file permissions problem or a shortage of space on the local filesystem.

"AMUAU029W": "The OAuth provider {{.OAuthProvider}} with base path {{.BasePath}} could not be unpacked."

The migration utility has failed to create an OAuth Provider with a particular base path. This can occur if there is an OAuth provider of this name with a different base path that has already been created in this provider organization. In API Connect v5, OAuth providers existed at the catalog level. In API Connect v10, they exist at the provider organization level, which can cause this issue to occur.

Error messages and warnings from archive:push

"AMUAP001E": "The {{.Type}} {{.Name}} contains nested content that cannot be published."

The migration utility is unable to read or load nested configuration content during the archive:push operation. After the migration unpack has been completed, some configuration objects are comprised of a directory with one or more nested files. For example, information about catalogs in their unpacked form consists of a directory with a name matching the catalog name, and a nested catalog.yml and catalog-settings.yml file. This message indicates that one or more of these files cannot be opened or loaded.

"AMUAP002E": "The {{.Type}} {{.Name}} cannot be published."

The migration utility is unable to read or load configuration content during the archive:push operation. This message indicates that the file representing the named configuration object is unreadable or contains unexpected content.

"AMUAP003W": "Skipping mapping file {{.Name}}."

The migration utility found a mapping file (mapping.yml) with invalid contents. The archive:push operation proceeds as if this mapping file were not present.

"AMUAP004E": "The file {{.Filepath}} could not be loaded and will not be published."

The migration utility is unable to read or load configuration content during the archive:push operation. This message indicates that the file representing a configuration object cannot be read or loaded.

"AMUAP005E": "The file {{.Filepath}} contains references that could not be loaded and will not be published."

The migration utility is unable to read or load configuration content during the archive:push operation. This message indicates that the file representing a configuration object cannot be read or loaded.

"AMUAP006E": "Unable to update reference to {{.Path}} in file {{.File}}."

The migration utility is unable to resolve a reference in the named file to another configuration object. This message indicates that the content in the file refers to other objects that are not found in the unpacked content, or the referenced content is not of the expected format.

"AMUAP007E": "The {{.Type}} {{.Name}} cannot be published because of a missing prerequisite."

The migration utility is unable to publish the named object because it refers to another object that cannot be found in the target API Connect system. This message indicates that the object contains an incorrect reference, or that the referenced object has not been successfully created or has been deleted from the target system.

"AMUAP008W": "The update to the {{.Type}} {{.Name}} could not be verified and may not have been successful."

The archive:push operation has attempted to update an object in the target API Connect system, but the results of the update were not received or indicated an error. This can occur in the event of a network interruption or timeout between the migration utility and the target API Connect system. If this occurs, it is safe to retry the archive:push operation; the same update will be attempted.

"AMUAP009E": "The {{.Type}} {{.Name}} was not published because it could not be checked in the target system."

The migration utility has attempted to check the existence of an object in the target API Connect system, but the check did not complete successfully. The migration utility will not overwrite objects in the target system if it cannot successfully determine whether or not a conflict will occur.

"AMUAP010W": "The creation of the {{.Type}} {{.Name}} could not be verified and may not have been successful."

The migration utlity has attempted to create an object in the target API Connect system, but the results of the creation were not received or indicated an error. This can occur in the event of a network interruption or timeout between the migration utility and the target API Connect system. If this occurs, it is safe to retry the archive:push operation; if the named object was created, then it will subsequently be skipped unless the overwrite option is used.

"AMUAP011W": "The deletion of the {{.Type}} {{.Name}} could not be verified and may not have been successful."

The migration utility has attempted to delete an object in the target API Connect system, but the results of the deletion were not received or indicated an error. This can occur in the event of a network interruption or timeout between the migration utility and the target API Connect system. If this occurs, it is safe to retry the archive:push operation.

"AMUAP012W": "The ownership transfer of the {{.Type}} {{.Name}} could not be verified and may not have been successful."

The migration utility has attempted to transfer ownership of an object in the target API Connect system, but the results of the ownership transfer were not received or indicated an error. This can occur in the event of a network interruption or timeout between the migration utility and the target API Connect system. If this occurs, it is safe to retry the archive:push operation.

"AMUAP013E": "The endpoint settings for catalog {{.Name}} could not be updated."

The migration utility has attempted to update the endpoint settings for a catalog in the target API Connect system, but the update was not successful. This can occur if the catalog settings refer to a gateway service for which the configuration cannot be found in the unpacked migration contents.

"AMUAP014E": "The {{.Type}} {{.NameVersion}} could not be {{.Action}} in the target system."

The migration utility has attempted to create or modify an object in the target API Connect system, but the target system returned an error. The reason associated with the message indicates the error returned by the server.

"AMUAP015E": "The gateway extension for the gateway service {{.Name}} could not be published."

The migration utility has attempted to publish a gateway extension zip to the target API Connect system, but the target system returned an error. The reason associated with the message indicates the error returned by the server.

"AMUAP016W": "The {{.Type}} for the gateway service {{.Name}} could not be updated."

The migration utility has attempted to update the OAuth shared secret or SNI items for a gateway service in the target API Connect system, but an OAuth shared secret or SNI items were previously set. The migration utility will not overwrite an OAuth shared secret or SNI items that have already been set.

"AMUAP017W": "The product {{.NameVersion}} could not be validated and may contain errors."

The migration utility has attempted to validate a product before publishing, but the validation operation did not complete successfully. If validation errors are present in the product file, then the publish to the target API Connect system will not be successful.

"AMUAP018W": "The product {{.NameVersion}} contains API {{.APIName}} that could not be validated and may contain errors.",

The migration utility has attempted to validate the APIs in a product before publishing, but the validation operation did not complete successfully. If validation errors are present in the API file, then the publish to the target API Connect system will not be successful.

"AMUAP019W": "The product {{.NameVersion}} contains validation errors: {{.Errors}}"

The migration utility has validated the content of a product before publishing, and the validation revealed errors in the product file contents. The product cannot be published to the target API Connect system unless the validation errors in the product file are corrected.

"AMUAP020W": "The product {{.NameVersion}} contains an API {{.APINameVersion}} with validation errors: {{.Errors}}"

The migration utility has validated the content of a product and its associated APIs before publishing, and the validation revealed errors in the API file contents. The product cannot be published to the target API Connect system unless the validation errors in the API file are corrected.

"AMUAP021W": "The product {{.NameVersion}} contains API content that could not be updated."

The migration utility has attempted to update the state of an API in the named product, but the metadata file (*.api.meta.yml) containing extra API attributes could not be read or contained unexpected content.

"AMUAP022W": "Subscription {{.Name}} will not be published."

The migration utility has encountered a subscription for which the subscribed product cannot be found. The subscription cannot be created in the target API Connect system.

"AMUAP023W": "The user registry {{.Name}} cannot be published."

The migration utility has encountered a user registry object that cannot be published to the target API Connect system. This can occur for user registry types that may appear in an API Connect v5 system but are not directly supported in API Connect v10. A mapping file in the unpacked user registry directory may be used to identify an alternative user registry into which user entries can be migrated.

"AMUAP024I": "Subscriptions for the product {{.NameVersion}} will not be published."

The migration utility has encountered a product that contains no subscribable APIs. This can occur when a product originating in API Connect v5 contains one or more OAuth provider APIs, and no REST or SOAP APIs. OAuth provider APIs are converted to OAuth provider resources by the archive:unpack operation, and do not appears as APIs in API Connect v10. OAuth provider instances in API Connect v10 use subscription information associated with the REST or SOAP APIs that refer to the OAuth provider in a security definition.

"AMUAP025E": "Non-fatal errors were found while running the preflight check: {{.Errors}}"

The migration utility encountered a non-fatal error during its preflight check before the start of archive:push. The details of any of these errors will be reported back here and the archive:unpack will continue.

Troubleshooting tips

• The migration utility may have issues when running across a VPN. The connection might fail if you use a corporate VPN to attempt to access an API Connect subystem (API Manager UI) located behind an internet firewall. To workaround this problem, add the IP addresses of the API Connect management server and API manager to your local /etc/hosts.
• Token expiration: By default, 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. In this case, log in again and re-run apicm archive:push. (The token is refreshed every time you log in.)

  Optionally, you can extend the token expiration time when logging in as the admin user:

  apicm login --expireHours=<number_of_hours>

  The expireHours flag overrides the default authentication token expiration of 8 hours. Use this flag when pushing data sets that take longer than 8 hours to complete. Note that the revised value persists after the session ends. Best practice is to revert the value to the default (8 hours) after migration.

• If your prior migration created an incorrect artifact on v10, you must manually remove the artifact before re-running migration.
• When you re-run migration, the utility will not recreate any artifacts that already exist on v10. If a collision occurs, the older artifact takes priority. Also, the utility will not delete any artifacts from v10. Thus, you can re-run migration to cover any gaps in artifact creation on v10 without affecting existing artifacts.
• The steps you need to take depend on whether you need to change the v5 export data. For example, if you need to publish or replace a v5 API, you need to export the v5 data and run unpack again. If you do not need to change the v5 data, you can skip those steps.

Example 1: Re-using the v5 export data

For example, your v5 export data is accurate and current, but you migrated a consumer-org that is no longer needed on v10, and you mapped a catalog to an incorrect name. Complete the following steps:

1. Delete the incorrect artifacts from the v10 deployment /cloud directory. For this example, delete the unneeded consumer-org and the incorrectly named catalog.
2. Edit the contents of the /cloud directory as needed. For example, remove the unneeded consumer-org entry.
3. Edit your mapping entries as needed. For example, remap the catalog name.
4. Run apicm archive:push <server> <project_directory>.

Example 2: Revising v5 export data

In this example your v5 export data is not current because you want to publish or replace a v5 API and then migrate it to v10. Complete the following steps:

1. In the v10 /cloud directory, delete the incorrect artifacts created by the migration. For this example, delete the API you want to replace.
2. On v5, recreate the export data: config dbextract sftp <host_hame> user <user_name> file <path/name>
3. On v10, delete the /cloud directory.
4. Run apicm archive:unpack to create the v10 hierarchy in /cloud directory.
5. Recreate any edits you made to the /cloud directory.
6. Recreate any mappings.
7. Run apicm archive:push <server> <project_directory>.

Failure to convert API definitions to API Gateway

When you change gateway types from DataPower Gateway (v5-compatible) to DataPower API Gateway, you use ./apicm archive:port-to-apigw <path> to convert API definitions to API Gateway format. The conversion requires Node version 14.21.3 or greater. If Node is not installed, this error is displayed:

ERRO[0000] Error getting node version: exec: "node": executable file not found in $PATH

If an unsupported version of Node is installed, an error is displayed as in the following example:

ERRO[0000] Node version installed must be >=14.21.3. Currently installed version: 4.9.1.

To resolve the error, install Node and re-run the command.

To view the conversion step, see Migration steps without PDUR or Migration steps with PDUR. For information about the conversion, see Reviewing APIs converted to DataPower API Gateway.

Custom policies not appearing in the policy palette after migration