Migration steps without PDUR

Complete the following steps to migrate from v5 to v10 when your v5 catalogs do not use Portal Delegated User Registries (PDUR).

Before you begin

Important: Do not use these instructions if your v5 catalogs use Portal Delegated User Registry. Instead, see Migration steps with PDUR.
  • Ensure you planned your migration, obtained the migration utility, and installed a v10 deployment, as described in Migration steps
  • Review Migration considerations.
  • Ensure you have system administrator privileges.
  • To use apicm to convert the API definitions, you must have Node version 14.20.0 (or greater) installed.

About this task

Use the apicm utility to migrate your API Connect v5 data to a new API Connect v10 installation.
Tip:

To achieve a smooth and successful migration, we recommend these best practices:

  • Before you push your v5 data to v10, your v10 system must be up and running, with gateway services, provider organizations, user registries, etc, ready to receive the data.
  • Plan to do several test iterations of migration. You can use the --dry-run option to do iterations of the migration push, to test for any errors or warnings to address before the actual data push.
  • Use the apicm <command> --help command to review the command options and their purpose. To see the list of commands you can run: apicm help.
  • Complete all the steps in this topic in the order listed, unless the step is marked optional and does not apply to your scenario. You can push provider orgs as many times as needed.

Procedure

  1. Log in to the command line interface of the v5 appliance. Use the following command to create a tar.gz export of the v5 configuration database and place it on an sftp server: 
    config dbextract sftp <host_hame> user <user_name> file <path/name>
    • Specify a name of your choice for the compressed file to contain the dbextract. For example, v5mgmt_data.tgz.
    • If you are not familiar with the v5 appliance CLI, see The Command Line Interface. For information on config dbextract, see Configuration commands.
  2. Optional: Setup a temporary SMTP server.

    During migration, if subscription approval is needed to enable an application to subscribe to a plan, notifications are sent to all users, within the organization, who have subscription approval permission. In some cases, this results in a large number of emails. To avoid the sending of these emails, set up a temporary email server prior to running the migration, and use it to collect all notifications rather than sending them to users' email accounts.

    If subscription approvals are not needed during your migration, you can skip this step.
  3. Optional: If necessary, set up a temporary LDAP server. This can be needed if you are temporarily behind a firewall.
    1. Install a server: 
      git clone https://github.com/veo-labs/ldap-server-mock
      npm install
    2. Creating the configuration files:
      • ldap-server-mock-conf.json
        {
  "port": 3004,
  "userLoginAttribute": "cn",
  "searchBase": "dc=test",
  "searchFilter": "(&(objectclass=person)(cn={{username}}))"
}
      • users.json
        [
  {
    "dn": "cn=user,dc=test",
    "cn": "user-login"
  }
]
    3. Run the LDAP server: 
      node server.js --conf=./ldap-server-mock-conf.json --database=./users.json
    4. Modifying a current LDAP provider.

      The following file is a dummy user registry file that maps to a read-only test server. The fields in bold font (admin_dn and endpoint) have been changed to fit the dummy server configuration. Change these on all user registries that need to be fixed.

      api_version: 2.0.0
configuration:
  admin_dn: cn=user,dc=test 
  admin_password: xxxx
  authenticated_bind: "true"
  authentication_method: search_dn
  bind_prefix: ""
  bind_suffix: ""
  protocol_version: "3"
  search_dn_base: ""
  search_dn_filter_prefix: (examplelegacyuid=
  search_dn_filter_suffix: )
  search_dn_scope: sub
endpoint:
  endpoint: ldap://172.20.20.11:3004
  tls_client_profile_url: idurl://..\..\..\..\admin-org\tls-client-profiles\tls-profile-for-ldap-1.0.0.yml
integration_url: file://..\..\..\..\integrations\user_registry\ldap.yml
metadata:
  v5_id: xxxxxx40cf2fc09a9ba0d6c
  v5_scope: '["api"]'
  v5_type: ldap
name: xxxxxxxxxxxxxx
title: xxxxxxxxxxxxxxxxxxxxxx
type: user_registry
  4. Unpack the V5 configuration data onto the local filesystem.
    Important: Migration on Windows 10

    Windows has path length limits that can interfere with large extracts. It is recommended that you keep the initial path for migration on Windows as short as possible. The AMU must be run in a command window with administrative privileges on Windows. Running from a Linux VM on your Windows system may be a better option for doing migration.

    1. Copy the v5 extract tar file from the sftp server to the location where you have v10 migration utility installed.
    2. Run apicm archive:unpack command from the directory where you downloaded the v5 extract file. 
      ./apicm archive:unpack <v5_extract_file>.tgz

      When you invoke apicm for the first time, you are prompted to accept the license. Accept the license to continue.

      You can optionally limit the unpack to only specific provider orgs. See Table 1.

    Table 1. apicm archive:unpack command options
    Parameters Description
    <v5_extract_file> Can be compressed file (.tgz, tar.gz) or uncompressed file (.tar). Use any file name of your choosing. Example:
    ./apicm archive:unpack v5_DBextract_data.tgz
    --provider-orgs One or more provider orgs to unpack. This flag is optional. Use it when you want to unpack only specific provider orgs rather than the entire archive. Example:
    ./apicm archive:unpack v5_DBextract_data.tgz --provider-orgs=<pOrg1_name>

    Use a comma-separated list to specify multiple provider orgs:

    ./apicm archive:unpack v5_archive_data.tgz 
 --provider-orgs=<pOrg1_name>,<pOrg2_name>,<pOrg3_name>
    Note:
    • Important: Any Warnings or Errors that occur during archive:unpack should be investigated for remediation. See Migration troubleshooting
    • You can avoid the license prompt by adding --accept-license to the command line.
    • The unpack command ensures that catalog names and API properties contain only valid characters. Any invalid characters are mapped to '-'. See Parity between Version 5 and Version 10.
    • The unpack command issues warning messages for APIs and Products that fail validation against the OpenAPI specification. See the limitations section in Migration considerations.
    • For troubleshooting tips, see Migration troubleshooting
    • The unpack command might return error messages related to PDUR, such as: 
      ERRO[3414] PDUR backup data for IDP PortalDelegatedIdentityProvider-123b81fbe4b06de411580e2e 
(123b81fbe4b06de411580e2f) not provided: not found 
ERRO[3414] PDUR backup data for IDP PortalDelegatedIdentityProvider-123b820de4b06de411580e32 
(123b820ee4b06de411580e33) not provided: not found

      If you are not migrating PDUR backup data, and your command did not include a <pdur_user_export>.tgz, the error indicates that you do in fact have a PDUR registry, and that you should have included a PDUR backup. Follow the migration instructions in Migration steps with PDUR.

    When the command completes, the data is unpacked to the /cloud directory. The /cloud directory is located in the same directory as apicm, and populated with yaml files representing the configuration objects in the export. The unpack processes produce output in the format required for v10 configuration.

    Note: The unpack directory must be named /cloud. Do not rename the directory.

    Example output in /cloud for admin-org: 

    
cloud
├── admin-org
│   ├── availability-zones
│   │   └── availability-zone-default
│   │       ├── availability-zone.yml
│   │       └── gateway-services
│   │           ├── g-w-1-8f82
│   │           │   └── gateway-service.yml
│   ├── keystore
│   │   └── default-ssl-profile.yml
│   ├── provider-org.yml
│   ├── tls-client-profiles
│   │   ├── default-ssl-profile-1.0.0.yml
│   │   ├── new-tls-profile-1-1.0.0.yml
│   │   ├── testclientprofile-1.0.0.yml
│   ├── tls-server-profiles
│   │   └── default-ssl-profile-1.0.0.yml
│   ├── truststore
│   │   └── default-ssl-profile.yml
│   └── user-registries
│       ├── api-manager-lur
│       │   ├── user-registry.yml
│       │   └── users
│       │       ├── adminuser1-catalog1-com-3ac2.yml
│       │       ├── adminuser2-catalog1-com-39c1.yml
│       ├── cloud-manager-lur
│       │   ├── user-registry.yml
│       │   └── users
│       │       ├── admin.yml
│       ├── ldap1
│       │   ├── user-registry.yml
│       │   └── users
│       │       ├── user1-gmail-com-47e5.yml
│       ├── oauth-ldap
│       │   └── user-registry.yml
│       ├── user-ldap
│       │   ├── user-registry.yml
│       │   └── users
│       │       ├── testuser1.yml
│       └── vrp-authurl
│           └── user-registry.yml
.
.
.

    Example output in /cloud for provider-orgs:

    cloud
.
.
.
└── provider-orgs
    ├── demo
│   │   ├── catalogs
│   │   │   ├── develop
│   │   │   │   ├── catalog-settings.yml
│   │   │   │   ├── catalog.yml
│   │   │   │   ├── configured-gateway-services
│   │   │   │   │   └── g-w-1-8f82
│   │   │   │   │       └── configured-gateway-service.yml
│   │   │   │   ├── members
│   │   │   │   │   └── testuser2-example-com-b9ed.yml
│   │   │   │   ├── products
│   │   │   │   │   ├── account-1.0.0.api.meta.yml
│   │   │   │   │   ├── account-1.0.0.api.yml
│   │   │   │   └── roles
│   │   │   │       ├── owner.yml
│   │   │   │       └── viewer.yml
│   │   │   ├── my-catalog
│   │   │   │   ├── catalog-settings.yml
│   │   │   │   ├── catalog.yml
│   │   │   │   ├── configured-gateway-services
│   │   │   │   │   └── g-w-1-8f82
│   │   │   │   │       └── configured-gateway-service.yml
│   │   │   │   ├── members
│   │   │   │   │   └── testuser2-example-com-b9ed.yml
│   │   │   │   ├── products
│   │   │   │   │   ├── ibm-apim-banka-1.0.0.api.meta.yml
│   │   │   │   │   ├── ibm-apim-banka-1.0.0.api.yml
│   │   │   │   └── roles
│   │   │   │       ├── owner.yml
│   │   │   │       └── viewer.yml
│   │   │   └── sandbox
│   │   │       ├── catalog-settings.yml
│   │   │       ├── catalog.yml
│   │   │       ├── configured-gateway-services
│   │   │       │   └── g-w-1-8f82
│   │   │       │       └── configured-gateway-service.yml
│   │   │       ├── members
│   │   │       │   └── testuser2-example-com-b9ed.yml
│   │   │       └── roles
│   │   │           ├── admin-catalog.yml
│   │   │           ├── deployment-manager-catalog-94d9.yml
│   │   │           ├── developer-catalog.yml
│   │   │           ├── owner.yml
│   │   │           ├── prodmgr-catalog.yml
│   │   │           └── viewer.yml
  5. Remove unneeded configuration objects.

    Inspect the set of configuration objects and their attributes, and remove the ones that are not needed. In many cases, some of the configuration objects present in the v5 system are not needed in the new v10 environment. For example, there is no value in preserving inactive users, obsolete apps, obsolete consumer organizations, and so on.

    When deleting objects, make sure that you do not delete objects that have other dependent objects, such as products with subscriptions on them or users that are active. If you delete a consumer organization make sure you also delete all apps and subscriptions associated with that consumer org. Be aware of any groups that include these consumer orgs or visibility settings that include the consumer orgs.

  6. Map v5 object names to v10 object names.

    Most deployments adjust the names or quantities of gateway services, provider organizations, and user registries when setting up a new environment for v10. Be sure to specify any changed v10 destinations for the v5 data in a migration mapping file so that the migration utility can automatically move the data.

    Complete the following, as needed. You can skip the steps for any objects that are unchanged from v5 to v10.

    1. What is a mapping file?
    2. Mapping a gateway service
    3. Mapping a provider organization
  7. Optional: If your v10 deployment uses a DataPower API Gateway, convert the v5 API definitions to v10 DataPower® API Gateway.

    To convert API definitions using the default migration configuration, use the following syntax.

    ./apicm archive:port-to-apigw <path>
    Important: Ensure that the DataPower Gateway version that you are using with your API Connect v10 deployment is compatible with the version of the migration utility that you are using. For details, see the version compatibility information in Configuring and managing your server environment.
    Important: If you are running the migration utility in Windows, Administrator privileges are required to complete this step.
    Table 2. Parameter for archive:port-to-apigw
    Parameter Description
    <path> Specify the unpacked cloud directory as input:
    ./apicm archive:port-to-apigw /cloud

    By specifying /cloud, apicm ports all artifacts within the directory, including APIs, Products, OAuth providers, custom policies, subscriptions and so on. Running a subsequent archive:push pushes all the artifacts to API Gateway.

    Running archive:port-to-apigw on any subdirectory within the unpacked /cloud directory could leave the directory in an inconsistent state, and cause the subsequent archive:push of artifacts to API Gateway to fail. Custom policies and OAuth providers are not migrated if a directory other than /cloud is specified.

    Note: However, if you decide to rewrite one API at a time, to migrate them to API Gateway, you can use:
    ./apicm archive:port-to-apigw <path>
    where <path> is a single API file, or a directory that contains only APIs or Products.

    In this case, you cannot use archive:push to push artifacts to API Gateway. All the ported APIs and Products must be pushed (or imported) into API Manager by either the toolkit or UI.

    Usage notes:

    • The conversion produces a draft output YAML file. Review the entire draft output YAML file for conformance, performance, and errors. Review the log files for messages about any manual actions that might be needed. For more information, see Reviewing APIs converted to DataPower API Gateway.
    • By default, all changes that the migration utility makes when rewriting APIs are logged as comments within the API YAML file. You can use the enable-api-logging parameter to disable logging of these changes.
      ./apicm archive:port-to-apigw <folder> --enable-api-logging=false
    • You can also specify migration configuration parameters using either a YAML configuration file or from the command line, but not both. For information about configuration options and DataPower requirements for certain configuration parameters, see Configuring migration options for DataPower API Gateway.
    • Multiple runs of ./apicm archive:port-to-apigw on the same /cloud folder will skip artifacts that have already been converted to DataPower® API Gateway.
    • If your v10 deployment uses DataPower MultiProtocol Gateway (v5-compatible) you do not need to convert the API definitions.
  8. Use apicm commands to push the Cloud Manager admin organization data onto your v10 Management Server.
    1. Log in to the Cloud Manager on the destination v10 Management Server as an Owner of the admin organization:
      Important: You must be logged in as an Owner of the admin organization to be able to migrate Cloud Manager admin organization data.
      • Syntax:
        ./apicm login --server <cloud_manager_endpoint> --realm admin/identity_provider --username admin --password admin_password
      • Example on API Connect v10 standalone 
        ./apicm login --server cloud-admin-ui.mgmt.dev.apic10-stack.example.test --realm admin/default-idp-1 --username admin --password 'myadminpassword'
      • Example on Cloud Pak for Integration
        ./apicm login --server cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod --realm admin/default-idp-1 --username admin --password ‘XXXXXXXXXXXX’

      The values to supply for the login parameters depend on whether your management server is deployed on API Connect v10 standalone or as part of Cloud Pak for Integration. See Table 3 to review how to obtain each parameter.

      Note: If you want to login using an OIDC user registry, see Logging in to a management server with an OIDC registry.
      Table 3. apicm login command parameters
      Parameters Description
      --server <cloud_manager_endpoint> The endpoint on the management server for communication with the Cloud Manager user interface.
      v10 standalone
      Example:
      cloud-admin-ui.mgmt.dev.apic10-stack.example.test

      The endpoint was specified when the management subsystem was installed. View the apiconnect_api definition in the apiconnect-up.yml file in the API Connect v10 installation project directory that you created for initial deployment of v10. Examples:

      Cloud Pak for Integration
      Syntax:
      <cpd-APIC_namespace.your-company.domain.com>/integration/apis/<APIC_namespace>/<APIC_instance>

      Example:

      cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod

      where e2e is <APIC_namespace> and prod is <APIC_instance>.

      Note: How to obtain the server parameter on Cloud Pak for Integration

      Use the Platform Navigator UI to determine the parameter. Note that you cannot get the endpoint by using oc get routes because Zen modifies the route internally.

      1. Locate the Platform UI panel with entries for the deployment. Identify the row that has a Type column entry with the description API management administration
      2. To display the endpoint, hover over the entry in the Name column for that row. For example, hover over the prod entry, as shown in bold font, and the URL displays at the bottom of the panel. 
        Name                   Type

prod                       API management administration
prod                          API management


cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod/admin
      3. Remove the trailing /admin from the endpoint, to obtain the parameter for the login command:
        cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod
      --realm admin/default-idp-1 The apicm login example shows the expected --realm parameter values for a default API Connection administration organization. The default user is admin and the identity provider is default-idp-1.
      You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
      apic identity-providers:list --scope admin --server mgmt_endpoint_url --fields title,realm
      For example:
      apic identity-providers:list --scope admin --server myserver.com --fields title,realm
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: admin/default-idp-1
  - title: Corporate LDAP user registry
    realm: admin/corporate-ldap
      The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.
      --username admin Administrative user with permissions to modify API Connect admin-org. The default user is admin.
      --password myadminpassword Administrative user password.

      Cloud Pak for Integration: When you installed with the top-level CR for CP4I, the password was auto-generated. To obtain the password, see step 3 in Installing API Connect:

    2. Run /apicm archive:push to migrate data for the Cloud Manager administrative org (admin-org).
      • Syntax
        ./apicm archive:push  <cloud_manager_endpoint> <path_to_admin_org> [optional flags]
      • Example for v10: 
        ./apicm archive:push cloud-admin-ui.mgmt.dev.apic10-stack.example.test cloud/admin-org
      • Example for Cloud Pak for Integration:
        ./apicm archive:push cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod cloud/admin-org

      See Table 4 to review how to obtain each parameter.

      Tip: First run the command with the optional flag --dry-run to test for errors or warnings. Review the command parameters, examples and guidance that follow before you run it.
      Table 4. apicm archive:push command parameters for admin org
      Parameters Description
      <cloud_manager_endpoint> The endpoint on the management server for communication with the Cloud Manager user interface.
      v10 standalone
      Example:
      cloud-admin-ui.mgmt.dev.apic10-stack.example.test

      The endpoint was specified when the management subsystem was installed. View the apiconnect_api definition in the apiconnect-up.yml file in the API Connect v10 installation project directory that you created for initial deployment of v10. Examples:

      Cloud Pak for Integration
      Syntax:
      <cpd-APIC_namespace.your-company.domain.com>/integration/apis/<APIC_namespace>/<APIC_instance>

      Example:

      cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod

      where e2e is <APIC_namespace> and prod is <APIC_instance>.

      See How to obtain the server parameter for Cloud Pak for Integration.
      <path_to_admin_org> Must be cloud/admin-org.
      --dry-run Optional flag. You can test the Admin org migration output first view by using the --dry-run option. 
      ./apicm archive:push <cloud_manager_endpoint> <path_to_admin_org> --dry-run

      This option creates a project directory similar to cloud, titled .workdir-<apim_admin_server> where you can view how the data will be loaded into your new system. The option also displays the objects that will fail due to existing already or missing dependencies. Use this option to view the resolved URLs for where the data will be loaded, without creating resources on the new system. See apicm command line help.
      --apigw-only Optional flag. Use when migrating to a DataPower API Gateway. For example: 
      ./apicm archive:push <cloud_manager_endpoint> <path_to_admin_org> --apigw-only
      Important: Usage notes:
      • Run /apicm archive:push in the same directory where you ran apicm: archive:unpack.
      • If you run migration and observe error messages in your log output, you can take troubleshooting steps, and run the migration again. See Migration troubleshooting.
      • The apicm login obtains a token that 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. See also Token expiration in Migration troubleshooting
      • An alternative method of viewing endpoints is to run kubectl get ingress and get the values from the output. For example, see the values in bold in the following sample output: 
        r7c221d8a33-apic-portal-director         api.portal.dev.apic10-stack.example.test                80, 443   21h
r7c221d8a33-apic-portal-web              portal.dev.apic10-stack.example.test                    80, 443   21h
re314d70920-apiconnect-api               platform.mgmt.dev.apic10-stack.example.test             80, 443   22h
re314d70920-apiconnect-apim-ui           apim.mgmt.dev.apic10-stack.example.test                 80, 443   22h
re314d70920-apiconnect-cm-ui             cloud.mgmt.dev.apic10-stack.example.test                80, 443   22h
re314d70920-apiconnect-consumer-api      consumer.mgmt.dev.apic10-stack.example.test             80, 443   22h
rfe867a858b-dynamic-gateway-service      service.gw.dev.apic10-stack.example.test                80, 443   21h
rfe867a858b-dynamic-gateway-service-gw   api.gw.dev.apic10-stack.example.test                    80, 443   21h
rfff5043330-analytics-client             ac.dev.apic10-stack.example.test                        80, 443   21h
rfff5043330-analytics-ingestion          ai.dev.apic10-stack.example.test
  9. Migrate the API Manager provider organizations.
    1. If you have not already done so, create the provider organizations on your API Connect v10 deployment.
    2. Use apicm to log in to the API Manager user interface as an Owner of the provider organization that you want to migrate.

      If you want to login using an OIDC user registry, see Logging in to a management server with an OIDC registry.

      Important: You cannot migrate a provider organization while you are logged in with the Cloud Manager admin organization. You must be logged in as an Owner of the provider organization to be able to migrate that organization's data.
      • Syntax:
        ./apicm login --server <api-manager-ui-endpoint> --realm provider/identity_provider --username org_owner --password org_password
      • Example for API Connect v10:
        ./apicm login --server api-manager-ui.dev.apic10-stack.example.test --realm provider/default-idp-2 --username org_owner1@example.com --password myorgpassword
      • Example for Cloud Pak for Integration:
        ./apicm login -server cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod --realm provider/default-idp-2 --username org_owner1@example.com --password myorgpassword
      Table 5. apicm login parameters for logging in to provider orgs on API Connect v10 standalone
      Parameters Description
      --server <api-manager-ui-endpoint> API Manager URL endpoint on the management server for communication with the API Manager user interface.
      API Connect v10 standalone

      For example:

      api-manager-ui.dev.apic10-stack.example.test
      The endpoint was specified when the management subsystem was installed. To verify your endpoint setting you can:
      • View the apiconnect-apim-ui definition in the apiconnect-up.yml file in the API Connect v10 installation project directory.
      • In the Cloud Manager UI, select Settings > Endpoints and view API Manager URL.
      Cloud Pak for Integration
      Syntax (line-break is for table formatting only; your value will not include a line-break):
      <cpd-APIC_namespace.your-company.domain.com>/integration/apis
/<APIC_namespace>/<APIC_instance>

      Example:

      cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod

      where e2e is <APIC_namespace> and prod is <APIC_instance>.

      See How to obtain the server parameter for Cloud Pak for Integration.
      --realm provider/identity_provider The apicm login example shows the expected realm parameter values for a default API Connection provider organization. The default user is provider and the identity provider is default-idp-2.
      You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
      apic identity-providers:list --scope provider --server mgmt_endpoint_url --fields title,realm
      For example:
      apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
      The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
      --username <org_owner> A user with permissions to modify the provider organization. Typically this is the owner of the organization.
      --password <org_owner_password> Organization owner password.
    3. Run /apicm archive:push to migrate data for the Provider organization.
      • Syntax:
        ./apicm archive:push <api-manager-ui-endpoint> cloud/provider-orgs/<pOrg_name> [optional flags]
      • Example on v10:
        ./apicm archive:push api-manager-ui.mgmt.dev.apic10-stack.example.test cloud/provider-orgs/production_Org
      • Example on Cloud Pak for Integration
        ./apicm archive:push cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod cloud/provider-orgs/production_Org

      See Table 6 to review how to obtain each parameter.

      Tip: First run the command with the optional flag --dry-run to test for errors or warnings.
      Table 6. apicm archive:push command parameters for Provider orgs
      Parameters Description
      <api-manager-ui-endpoint> API Manager URL endpoint on the management server for communication with the API Manager user interface.
      API Connect v10 standalone
      For example:
      api-manager-ui.dev.apic10-stack.example.test
      The endpoint was specified when the management subsystem was installed. To verify your endpoint setting you can:
      • View the apiconnect_api definition in the apiconnect-up.yml file in the API Connect v10 installation project directory.
      • In the Cloud Manager UI, select Settings > Endpoints and view API Manager URL.
      Cloud Pak for Integration
      Syntax (line-break is for table formatting only, your value will not include a line-break).
      <cpd-APIC_namespace.your-company.domain.com>/integration/apis
/APIC_namespace/<APIC_instance>

      Example:

      cpd-e2e.apps.test1.cp.example.com/integration/apis/e2e/prod

      where e2e is <APIC_namespace> and prod is <APIC_instance>.

      See How to obtain the server parameter for Cloud Pak for Integration.
      cloud/provider-orgs/<pOrg_name> The location of your Provider org within the /cloud file hierarchy you created when you ran apicm archive:unpack. 
      cloud/provider-orgs/production_Org
      --catalogs=<name> Optionally, you can push data for only specified Catalogs if you don't want to push the entire Provider organization. Use this flag to specify the name of the Catalog you want to push:
      ./apicm archive:push <api-manager-ui-endpoint> cloud/provider-orgs/<pOrg_name>
 --catalogs=<catalog_name>
      Note: Type the command on a single line.

      When a catalog is mapped, specify the mapped new catalog name.

      To specify multiple catalogs, use a comma-separated list: 
      ./apicm archive:push <api-manager-ui-endpoint> cloud/provider-orgs/<pOrg_name>
 --catalogs=<catalog_name1,catalog_name2,catalog_name3>
      Note: Type the command on a single line.
      --dry-run You can test the Provider org migration output first view by using the --dry-run option. This will create a project directory similar to cloud, titled .workdir-<apim_admin_server> where you can view how the data will be loaded into your new system. The option also displays the objects that will fail due to existing already or missing dependencies. Use this option to view the resolved URLs for where the data will be loaded, without creating resources on the new system. See apicm command line help.
      ./apicm archive:push <api-manager-ui-endpoint> cloud/provider-orgs/<pOrg_name>
 --dry-run
      Note: Type the command on a single line.
      --no-drafts Do not push any Draft APIs or Products. Draft objects are objects that have not been published.
      ./apicm archive:push <cloud_manager_endpoint> <path_to_provider_org>
 --no-drafts
      Note: Type the command on a single line.

      This option can be used with or without --catalogs=a,b,c.
      --overwrite When this option is used, draft products, draft APIs, published products and their APIs, and OAuth Providers that are already on the v10 system will be overwritten. When this option is not used these artifacts will be skipped.
      Important: Usage notes
      • Run /apicm archive:push in the same directory where you ran apicm: archive:unpack.
      • If you run migration and observe error messages in your log output, you can take troubleshooting steps, and run the migration again. See Migration troubleshooting.
      • The apicm login obtains a token that 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. See also Token expiration in Migration troubleshooting
      • An alternative method of viewing endpoints is to run kubectl get ingress and get the values from the output. See kubectl example.
  10. When migration finishes, complete the following steps:
    1. If a user in a Local User Registry is owner of a Consumer Organization, the user must reset their password.
    2. If applicable, reapply any customized configurations from your v5 deployment. See Customizations to recreate.
    3. Optional: If necessary, switch the provider organization ownership to the identity that owned it in v5.

      This step might be necessary if you created and migrated the provider organization using a different identity (such as administrative account) than the user identity of the v5 provider org. Note that the UI does not provide this function, but you can use the API /orgs/{org}/transfer-owner to switch ownership.