Enterprise Service Manager (ESM): Error when migrating policies - "(name) must be unique" for API Gateways version 7 and lower

Document ID : KB000042942
Last Modified Date : 14/02/2018
Show Technical Document Details

Solution

Note: This article does not apply to API Gateways on version 8 or higher! For version 8 or higher, please refer to the related article applicable to version 8 and higher.
?

Introduction

While using the ESM to migrate policies between environments, the following error occurs due to a naming / GUID problem:

Migration failed: Import failed when processing entity: POLICY, <name> (#<GUID>) due to: (name) must be unique ().

This error occurs as the policy GUID's for the same service do not match between the two environments. ?A typical cause of this problem is when a policy is manually created in the destination environment which will assign a new GUID. At this point the two environments services cannot be matched by the ESM.

Resolution

To correct this error, you can use the attached policy to update a Destination environment from a Source environment. ?The Source environment is read for the policy GUID's and the Destination environment has the policy GUID's updated to match those from the Source environment. ?The GUID alignment needs to be rolled through all the available environments. ?For example, PROD will be used to update UAT which will then update DEV.

While following this process, there are certain restrictions that must be observed, including the following:

  • No development work is being done on either environment

  • For the services to be re-aligned, it is essential that they have unique names as these are used to match services. ?The policy does not check for unique names but you can use a SQL statement similar to below to ensure there are no duplicates;

    • SELECT published_service.name, count(*)?
      FROM published_service, policy?
      WHERE published_service.policy_oid = policy.objectid?
      group by published_service.name?
      having count(*) > 1;?

The steps for deploying and running the re-alignment are as follows:

  1. As this process will directly update the database, it is strongly recommended to take a backup of the database before starting. This will allow easy rollback in the event of any problems. On the Destination envrironment run the following command;
    mysqldump --all-databases -u root -p'<password>' | gzip > ~/all.sql.gz
    where <password> is replaced with the correct value for the MySQL root account

  2. Create a JDBC connection name 'Migration' that points to the local MySQL database. Do this on both nodes.?

    User-added image
  3. Create a REST service in the target destination for the alignment with a resolution path of?/migration?

  4. Import the attached policy and ensure the JDBC connection has the correct username and password?

  5. Use the ESM to copy the /migrate policy to the Prod environment. This ensures the migration policy has matching GUID's

  6. Ensure the Prod service has the correct username and password entered for the MySQL connection

  7. On the Destination environment, within the Task 'Manage Certificates' import in the SSL certificate for the Source environment and make sure to enable use for SSL?connections

    • Click Add
      User-added image
    • Fill in the URL for the source Gateway and the port and click Next
      User-added image
    • Select the 'Outbound SSL Connections' option
      User-added image
  8. Enter in the following URL in a browser:

    • to align the policy fragments
      http://<target_environment_FQDN>:8080/migration?type=align&mode=policyFrag&source=<source_environment_FQDN>

    • to align services
      http://<target_environment_FQDN>:8080/migration?type=align&mode=services&source=<source_environment_FQDN>

Attachments:

File Attachments:
TEC0000001158.zip