Managing Golden Configurations

  • Published on May 23, 2025
Prev Next

Previously in the Itential Platform, if a Golden Configuration with the same name already existed and you attempted to import a new one, you would get an error. This limitation is now removed in the UI, thereby enabling you to manage Golden Configs in Configuration Manager through a set of actions that will enhance how you handle the standard by which your devices should be configured.

Importing Golden Configs

When importing Golden Configurations, certain characteristics and behaviors occur if you do not pass in an extra property with each tree. These include:

  • If the name is a duplicate, a unique index is used, such as GC Name (1).
  • If the name is not a duplicate, then the original name is used in the export, such as GC Name.
  • Devices are not imported.
  • Task instances are imported.

To import a Golden Configuration:

  1. Navigate to Configuration Manager under Operation on the main Itential Platform page.
  2. Select the Search icon (top toolbar) to display the Collection dialog.
  3. Select the Golden Configurations tab. (Note: For IAP 2023.1 and IAP 2023.2 Only).
  4. Click the Import icon in the upper-left of the Collection dialog to open your file manager.
  5. Locate and select the Golden Configurations that you want to import (represented as JSON files).
  6. Confirm you want to import the file. A notification banner displays in the upper-right upon successful file import.
  7. If the file is a duplicate, an import dialog will open and prompt you to overwrite the existing version or rename rename it.

Figure 1: Downloads Folder
07-Import-GC-JSON-22.1

 

Figure 2: Golden Config Import Dialog
08-ImportGC-OverwriteRenameDialog-22.1

Exporting Golden Configs

Use the following steps to export a Golden Configuration for import:

  1. Login to Itential Platform to open the home page and click Configuration Manager under Operation in the left navigation menu to open the application.

  2. Select the Search icon (top toolbar) in Configuration Manager to display the Collection dialog.

  3. Select the Golden Configurations tab from the Collection window to display all the card options.

  4. Select the checkbox at the bottom of each Golden Configuration you want to export and then click the Export icon (upper-left).

     

    Figure 3: Golden Configurations Collection Tab
    03-GoldenConfigsCollectionTab-22.1

     

    Figure 4: Select and Export Golden Configuration
    04-SelectButton-ExportGoldenConfig-22.1

     

  5. A message box appears asking you to confirm the export of the selected configurations. Click Okay.

  6. The output file format is JSON. A download of the export file is shown in your browser. Once the download is complete, locate the export file in the downloads folder and perform an import.

Figure 5: Confirm Export
05-ConfirmExportGoldenConfig-22.1

 

Figure 6: Export File Output JSON
06-GoldenConfigExportFile-FF-22.1

Overwriting Golden Configs

When overwriting Golden Configurations, certain behaviors occur if you pass the overWrite: true property with each tree. These behaviors are as follows:

  • The entire Golden Configuration is replaced except for devices and task instances.
  • Versions in the current Golden Configuration that do not exist in the imported Golden Configuration​ are deleted.
  • Versions in the imported Golden Configuration that exist but are not available in the current Golden Configuration are added.

To overwrite a Golden Configuration:

  1. Navigate to Configuration Manager under Operation on the main Itential Platform page.

  2. Select the Search icon (top toolbar) to display the Collection dialog.

  3. Select the Golden Configurations tab.

  4. Click the Import icon in the upper-left of the Collection dialog to open your file manager.

  5. Locate and select the primary file that you want to overwrite with a secondary file of the same name.

    1. Cisco 3650 - User FW was imported as a primary file.
    2. Cisco 3650 - User FW in the Downloads folder is the secondary file.

  6. Click Open. A warning message appears indicating the primary file already exists.

  7. Click Overwrite. The primary file is overwritten. A success banner appears in the upper-right of the Collections window showing the overwritten Cisco 3650 - User FW file.

Figure 7: Open File from Download Folder
09-Import-GC-Collections-Downloads

 

Figure 8: Import Dialog Warning
10-Import-GC-Warning-21.2

 

Figure 9: Overwrite Success Banner
11-Overwrite-ImportGC-Success-22.1

Renaming a Golden Configuration

When renaming Golden Configurations, certain behaviors occur if you pass the newName": "some gc name" property. These behaviors are as follows:

  • The Golden Configuration is imported with a new name.
  • If that new name already exists, the new name is indexed as New GC Name (1).
  • Devices are not imported along.
  • Task instances are imported.

To rename a Golden Configuration:

  1. Navigate to Configuration Manager under Operation on the home page.

  2. Select the Search icon (top toolbar) to display the Collection dialog.

  3. Select the Golden Configurations tab.

  4. Click the Import icon in the upper-left of the Collection dialog to open your file manager.

    Figure 10: Downloads Folder
    07-Import-GC-JSON-22.1

  5. Select the Golden Configuration that you want to rename. In the example, JSON is the file to rename.

    Figure 11: JSON File
    12-Rename-GC-Collections-22.1

  6. Click Open. A warning message appears indicating the file already exists.

    Figure 12: Warning Dialog
    13-GC-Rename-Warning-22.1

  7. Rename the file name directly in the error message by clicking on the name (e.g., JSON to JSON Copy). Notice that the error message and the Overwrite button changes to Rename instead.

    Figure 13: Rename File
    14-GC-New-Name-22.1

  8. Click Rename. A success banner (Figure 5) appears and the original JSON and the newly named JSON Copy file are displayed in the Collections window.

    Figure 14: Success Confirmation
    15-GC-Rename-Success-22.1

Using the Import API in Golden Configuration

This section provides the backend developer information for importing, overwriting, and renaming Golden Configurations. Here are the parameters for calling the API:

{
    "trees": [
        {
            "data": [{treeVersion1}, {treeVersion2}],
            "overwrite": true
        },
        {
            "data": [{treeVersion1}, {treeVersion2}],
            "newName": "New GC Name"
        },
        {
            "data": [{treeVersion1}, {treeVersion2}]
        }
    ],
    "options": {}
}

Each element in the trees array represents a Golden Configuration. Within each Golden Configuration, the data array represents each version that belongs to a Golden Configuration. For example, if a Golden Configuration has three versions, then the data array is going to have three objects inside of it for each version. Essentially, the payload is saying to import three Golden Configurations and each of those three Golden Configurations has two versions each.

To import a Golden Configuration, you can just pass in the import data and nothing else . It will:

  • Either import the tree normally, assuming it’s not a duplicate.
  • Index the name if it is a duplicate in which a tree name already exists. For example, if a tree called IOS Tree already exists then it will import as IOS Tree (1).

Overwrite Property

To overwrite for a Golden Configuration, you have to pass the 
overwrite: true property.

Renaming Property

To rename a Golden Configuration, you have to pass in the newName  property.