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

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


Article ID: 42942


Updated On:


STARTER PACK-7 CA Rapid App Security CA API Gateway



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.


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.


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

    <Please see attached file for image>

    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

      <Please see attached file for image>

      User-added image
    • Fill in the URL for the source Gateway and the port and click Next

      <Please see attached file for image>

      User-added image
    • Select the 'Outbound SSL Connections' option

      <Please see attached file for image>

      User-added image
  8. Enter in the following URL in a browser:

    • to align the policy fragments

    • to align services



Component: APIESM


1558722784214000042942_sktwi1f5rjvs16wko.jpeg get_app
1558722782407000042942_sktwi1f5rjvs16wkn.jpeg get_app
1558722779571000042942_sktwi1f5rjvs16wkm.jpeg get_app
1558722777408000042942_sktwi1f5rjvs16wkl.jpeg get_app
1558534565515TEC0000001158.zip get_app