Forward references, auto-creation, and guidelines - BlueCat Integrity - 9.5.0

Address Manager Administration Guide
Locale
English
Product name
BlueCat Integrity
Version
9.5.0

Forward references and processing order

The migration engine processes input XML in a single pass. If element #1 references and requires element #2 which has not yet been processed by the engine, the processing of element #1 will be deferred until later. Once the engine processes element #2, element #1 is unblocked and processed. When possible, declare “dependency” elements before those that reference or otherwise depend on them. To avoid ambiguity and inconsistent behavior, entities should be created only once, and should not be created and deleted in the same XML.
Attention: If the creation of an entity depends on the creation of a different entity, the logs may indicate that it is unsafe to create the initial entity before the entity it depends on is created. For example, if the engine attempts to process an IPv4 address element with an associated MAC address, but the MAC address is not previously defined in the XML or already in the database, the logs will intially indicate that it is unsafe to create the IPv4 address entity. However, the IPv4 address will still be created after the MAC address it depends on is created:
Example log:
[INFO] [2023-03-21 18:03:16.914] Unsafe to auto-create 10.31.14.135 because there is a matching deferred element #6: 10.31.14.135 
[INFO] [2023-03-21 18:03:16.914] Deemed safe to attempt to auto-create REQUIRED mac-address for test / 10.31.14.135 
[NOTICE] [2023-03-21 18:03:16.944] Auto-created/discovered REQUIRED mac-address for test / 10.31.14.135 
[INFO] [2023-03-21 18:03:16.987] Created ip4-address test / 10.31.14.135
In this example the IPv4 address entity is deemed unsafe to create until MAC address auto-creation is processed. Once the MAC address entity is autocreated, the engine successfully creates the IPv4 address entity despite the intial warning message. To avoid log messages of this sort due to deferred processing of elements, the associated mac-address element should be defined before it is used in the ip4-address definition.

Auto-creation and semantic differences

In the same way that elements with dependencies are deferred for processing, the engine will hold off auto-creation of an entity until it becomes clear that the entity will not be created explicitly - essentially until the end of migration.

Autocreation is presently limited to the following:

  • IPv4 network gateway addresses are processed and potentially created at the same time the networks are processed.
  • IPv4 addresses are automatically created if missing and referenced by host records.

Support for the auto-create-network attribute of the host element has been removed.

Warning: Networks and blocks are not auto-created - they must be created manually.

Best practices when using the migration engine

  • Migrate data into an empty Address Manager database when possible.

  • Avoid migrating data that may be at risk for concurrent modification by UI or API usage.

  • Pre-test the migration process when possible.

  • Create backups of original data before migration is initiated. The migration engine does not have a “rollback” operation.

  • Monitor the progress of migration and be prepared to abort in unforeseen circumstances.

  • Keep a copy of the migration data, logs, and backups in case a follow-up analysis is needed.

  • Use compressed (zip) migration packages for better organization and less disk space usage.

  • Migration serves a specific use case, and is not intended to be a generic editing tool or replacement for the API. It is more efficient to use the UI or API to make small changes to data. For copying exact, complete data between Address Manager servers, use database backups and restores.