Migration steps with PDUR

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

Before you begin

Important: If your v5 deployment does not use Portal Delegated User Registry (PDUR), do not use these instructions. See Migration steps without 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

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.

The migration of v5 catalogs that use PDUR to a v10 deployment contains all of the steps for migration a non-PDUR v5 deployment to a v10 deployment (as described in Migration steps without PDUR) plus additional steps that are needed to migrate Portal Delegated User Registry data.

In IBM API Connect Version 5, when Portal Delegated User Registry (PDUR) was selected for a Catalog, the user management was delegated from the management server to the Developer Portal. The site administrator within the Portal site then performed the configuration. The management server recorded that the delegation had taken place, and stored a record of the users which existed in the catalog. However, the management service maintained no information about the configuration of the specific registries or how users mapped to them.

PDUR in IBM API Connect v5 was highly configurable. A single Portal site (catalog) could be configured to use multiple different registry types or different registries of the same type. Details of this configuration, and which users map to which registry, is all stored in the Portal.

However, IBM API Connect Version 10 and later supports new registries, and no longer needs the PDUR. Instead, functionally equivalent registries can be configured in v10 and used. To migrate the PDUR user registries and users from v5 to v10, we must gather configuration information from both the management server and the Portal node.

PDUR supported 4 different types of user registries. The following table shows the mapping of these types to the v10 equivalents:

Table 1. Mapping of Registry types
v5 PDUR Registry	v10 Equivalent Registry
LDAP	LDAP
OIDC	OIDC
HybridAuth	OIDC
Local User Registry (LUR)	Local User Registry (LUR)

In this scenario, if you want to migrate users from an IBM API Connect V5 Developer Portal to an IBM API Connect v10 Developer Portal, you must export the user information that is stored in the Developer Portal local database. This information can then be used by the migration tooling to migrate the PDUR user registry. You complete this action after you have exported the v5 configuration database for the management server.

Procedure

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.
Log in to Developer Portal CLI to export Portal Delegated User Registry user information for all of the sites on a Developer Portal server. Use the following command to create a *.tgz file:
```
pdur_user_export
```
The status of the export is displayed. For example:
```
admin@apimxxx123:~$ pdur_user_export
portal123.company.com/api-provider/production: Exporting pdur users
portal123.company.com/api-provider/preprod: Exporting pdur users
portal123.company.com/api-provider/uat: Exporting pdur users
portal123.company.com/api-provider/development: Skipping as not a pdur enabled site
portal123.company.com/api-provider/sandbox: Skipping as not a pdur enabled site
~/pdurexport ~
5c20b903e4b0485cbbd81775.5c20bf43e4b0485cbbd81795.json
5c20b903e4b0485cbbd81775.5c2cddbae4b0485cbbd818a0.json
5c20b903e4b0485cbbd81775.5c335211e4b0485cbbd8196e.json
~
Output can be found in /home/admin/pdurexport.tgz
```
Results:
- When the command completes, you can see the output *pdurexport.tgz in /home/admin/pdurexport.tgz.
- This compressed file contains all of the JSON user-mapping files for that server. Each .json file contains a list of all of the PDUR user information that is stored in the Developer Portal local database. The naming convention used for the individual user-mapping files is <provider_org_id>.<catalog_id>.json.
- The user information for all of the user registration methods that are used in the specific Developer Portal are included in the same file. For example, local user registry, LDAP user registry, third-party authentication, OpenID Connect, and any custom user registration method.
- If a site doesn't contain any PDUR data, that site is skipped. The example output shows that there was one provider organization on the server, and that organization had five Developer Portal sites, three of which contained PDUR user information. The PDUR user information for all of the sites on the server is exported into a pdurexport.tgz file.
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.

Optional: If necessary, set up a temporary LDAP server. This can be needed if you are temporarily behind a firewall.

Install a server:

git clone https://github.com/veo-labs/ldap-server-mock

npm install

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"
  }
]

Run the LDAP server:

node server.js --conf=./ldap-server-mock-conf.json --database=./users.json

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

Unpack both the v5 management data backup and the PDUR tar file.

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.

Copy the v5 extract tar file (<v5mgmt_data>.tgz) and the PDUR extract file (pdurexport.tgz) from the sftp server to the location where you have v10 migration utility installed.
Run apicm archive:unpack command from the directory where you downloaded the v5 extract file.
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 2.

./apicm archive:unpack <v5_extract_file>.tgz pdurexport.tgz

Table 2. `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: `v5_DBextract_data.tgz`
`pdurexport.tgz`	The Portal Delegated User Registry export file generated by the `pdur_user_export` utility. Example: `pdurexport.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 pdurexport.tgz --provider-orgs=<pOrg1_name>` Use a comma-separated list to specify multiple provider orgs: `./apicm archive:unpack v5_archive_data.tgz pdurexport.tgz --provider-orgs=<pOrg1_name>,<pOrg2_name>,<pOrg3_name>`

Note:

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

The error means that when the migration utility unpacked pdurexport.tgz, it could not find all the specified Portal user registries. To resolve the errors, re-run pdur_user_export and re-run the unpack..

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 provider-org:

└── provider-orgs
    └── pOrg1
        ├── catalogs
            ├── catalog1
            │   ├── ...
        └── user-registries
            ├── pdur-ldap-5c38c102e4b0485cbbd81a84
            │   ├── mapping.yml
            │   ├── user-registry.yml
            │   └── users
            │       ├── gauss.yml
            │       └── riemann.yml
            ├── git-hub-5c38c102e4b0485cbbd81a84-bbfe
            │   ├── user-registry.yml
            │   └── users
            │       └── apictestgithub-apictestgithub-c646.yml
            ├── google-5c38c102e4b0485cbbd81a84
            │   ├── user-registry.yml
            │   └── users
            │       └── demo-account-7a25.yml
            ├── lur-5c38c102e4b0485cbbd81a84
            │   ├── user-registry.yml
            │   └── users
            │       └── lur-user-1.yml
            ├── portal-delegated-identity-provider-5c20b903e4b0485cbbd81781-7293
            │   └── user-registry.yml
            ├── portal-delegated-identity-provider-5c20bf43e4b0485cbbd81795-954
            │   ├── user-registry.yml
            │   └── users
            │       ├── anotheruser.yml
            │       ├── onemore.yml
            │       └── pduruser.yml
            ├── portal-delegated-identity-provider-5c2cddbae4b0485cbbd818a0-986d
            │   ├── user-registry.yml
            │   └── users
            │       ├── einstein.yml
            │       ├── euclid.yml
            │       ├── euler.yml
            │       ├── gauss.yml
            │       └── riemann.yml
            ├── portal-delegated-identity-provider-5c335211e4b0485cbbd8196e-833b
            │   ├── user-registry.yml
            │   └── users
            │       ├── demo-account-7a25.yml
            │       └── demo-demo-e666.yml
            ├── portal-delegated-identity-provider-5c347868e4b0485cbbd819b8-1137
            │   ├── user-registry.yml
            │   └── users
            │       └── demo-account-7a25.yml
            ├── portal-delegated-identity-provider-5c3622e9e4b0485cbbd81a11-9f8e
            │   └── user-registry.yml
            └── sandbox
                └── user-registry.yml

If the v5 Developer Portal used LDAP, HybridAuth, or OIDC (such as social login through Google, GitHub, or Slack) user registries, you must manually configure them in v10 before using apicm archive:push to migrate PDUR.

See the following instructions for your registry type:
- LDAP
  1. Manually configure LDAP
    The user registries which are required in the target v10 system are described in the user-registry.yml file. Where possible the configuration for the v10 registries is complete in these files. However, for LDAP the configuration of the registry is not possible due to differences in the way the v5 Portal (Drupal) and v10 API Manager (apim) specify user registry configuration.
    
    For LDAP with v10, create a user registry manually, using the same LDAP server and configuration as used with v5. Where it is possible, the v5 configuration is provided as helpful information in the metadata.v5_config property. To view the v10 configuration instructions, see Configuring an LDAP user registry.
    
    For example: An ldap.tar.gz file, when unpacked, creates the following directory hierarchy, for an LDAP directory example:
```
── user-registries
    └── example-5c38556de4b0c5f69db90ee0
        ├── user-registry.yml
        └── users
            ├── testuser1.yml
            └── testuser2.yml
```
    You can create an LDAP user registry for the PDUR by either modifying user-registry.yml or by creating the registry in the UI:
    - Modify the user-registries/example-5c38556de4b0c5f69db90ee0/user-registry.yml file directly and add the required LDAP fields based on the extracted info provided in the metadata. Remove the metadata after you are done.
      The modification of user-registry.yml is preferred over using the UI. This method enables any APIs that depend on the user registry to be satisfied when the migration command apicm archive:push is run in Step 10.
    - Create the registry in the UI.
      The creation of the registry in the UI requires more manual setup of the organization and catalog. In addition, you must provide a mapping file to map from the example-5c38556de4b0c5f69db90ee0 to the ID of the registry that was created manually.
  2. Create a mapping file entry for the LDAP user registry.
    In the /cloud directory, go to provider-org/<provider-org>/user-registry/<PDUR_LDAP_User_registry> and create a mapping file to tell migration utility the name of the migration endpoint for the LDAP user registry used with v5 PDUR:
```
user-registry:
  name: <pdur-ldap-v10-name>
```
    To determine which name to use for the v10 LDAP registry, go to the management user interface, click on Resources -> User Registries then use Name not Title.
    
    For more information on how to create mapping files, see Migration mapping files.
- OIDC
  1. Manually configure OIDC
    - Note that v10 supports OAuth 2.0 but does not support OAuth 1.0. Deployments, such as Twitter, which use Oauth 1.0 with APIC version 5, can not use OAuth 1.0 when migrating to v10.
    - Automatic migration is not supported for the OIDC user registries which you use in your v5 Portal. Thus if you are using OIDC OAuth 2.0, e.g., Google, GitHub, or Slack, please complete the following manual steps.
    - The OIDC data from the Portal Delegated User registry does not contain the client_id and client_secret that are needed to migrate a user registry automatically. You must obtain the data and update the user registry manually if you are using client_id and client_secret.
    On the Version 10 system:
    1. Edit user-registry.yml. For example, for GitHub:
      cloud/provider-orgs/test-user1-org1/user-registries/git-hub-5c5xyz6ee4b0c5f69db94xxxx-a339/user-registry.yml
```
api_version: 2.0.0
configuration:
  client_id: ""
  client_secret: ""
  authorization_endpoint: https://github.com/login/oauth/authorize
  provider_type: github
  token_endpoint:
    endpoint: https://github.com/login/oauth/access_token
integration_url: file://../../../../integrations/user_registry/oidc.yml
metadata:
  v5_id: 5c5xyz6ee4b0c5f69db94xxxx
name: git-hub-5c5xyz6ee4b0c5f69db94xxxx-a339
registry_type: oidc
title: GitHub
type: user_registry
```
    2. Insert the values for client_id and client_secret. Once the client id and client secrets have been updated in the user-registry.yml file just described, the apicm archive:push can be successfully executed.
      Upon creation and configuration of the Developer Portal, you can log in by using, as in this example, an account such as a GitHub account.
      
      To verify that the manual configuration succeeded, view the log file for entries for the users after you run apim archive:push in Step 10.
      - Example success message:
        INFO[0012] User registry git-hub-5c5xyz6ee4b0c5f69db94xxxx-a339 created INFO[0013] User test-user1-4d48 created
      - Example error message:
        ERRO[0010] unable to create User registry git-hub-5c5xyz6ee4b0c5f69db94xxxx-a339 ERRO[0010] git-hub-5c5xyz6ee4b0c5f69db94xxxx-a339: The properties client_id, client_secret are required.
  2. Create a mapping file entry for the OIDC user registry.
    In the /cloud directory, go to provider-org/<provider-org>/user-registry/<PDUR_OIDC_User_registry> and create a mapping file to tell migration utility the name of the migration endpoint for the OIDC user registry used with v5 PDUR:
```
user-registry:
  name: <pdur-OIDC-v10-name>
```
    For more information on how to create mapping files, see Migration mapping files.
Optional: 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.
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.

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 3. 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.

Use apicm commands to push the Cloud Manager admin organization data onto your v10 Management Server.

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 4 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 4. `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: VMware: see the `cloud-admin-ui` endpoint in Deployment overview for endpoints and certificates. Kubernetes: see the `admin` endpoint in Deployment overview for endpoints and certificates. 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. 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` 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` 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:

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 5 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 5. `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: VMware: see the `cloud-admin-ui` endpoint in Deployment overview for endpoints and certificates. Kubernetes: see the `admin` endpoint in Deployment overview for endpoints and certificates. 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

Migrate the API Manager provider organizations.

If you have not already done so, create the provider organizations on your API Connect v10 deployment.

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 6. `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.

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 7 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 7. `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.

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.