Example: Create environment files to capture idmconfig changes

In this use case, a product implementer for ABC company has set up two product server environments, one for development and one for production. Each environment has a different Active Directory (AD) target address.

The following instructions will walk you through the steps required to create and configure the environment files for both the development (dev) and production (prod) environments. When the environment files are loaded into their respective environments, they will install the component to create the AD target and input the correct address for their environment specific AD system within the target configuration.

Environment details

The Active Directory (AD) target address for each environment is:

dev.corp for the dev environment.
prod.corp for the prod environment.

Creating the dev and prod environment files

The Data.hid_target_ad component provides a base AD target with a sample targeting address. The Data.hid_target_ad component is called upon and installed as a dependency to many other scenario and functional components.

The sample placeholder AD target address that the Data.hid_target_ad component inputs is server=demo.local;listNestedGrps=true. We know the addresses we want the component to set when installed for both the dev and prod environments, so we need to write the files dictating those addresses. We start by creating two environment files, one for dev and one for prod.

To create the environment files:

Navigate to the \<instance> directory.
If the folder called \<instance>\environments does not currently exist in the instance directory, create it.
Create two files within the newly created environments folder; one called abc-dev.json and the other abc-prod.json.

Identify the component that you want to add the override for

To be able to override configuration data provided by a component, the component you need to override must be identified first. For IDMConfig changes there is no direct way to tell which component is responsible for the configuration information, so there is no definitive way to figure this out. It requires using intuition to guess and then confirm you are correct by searching through the component files. Here are some tips to help identify the component you need to override.

To identify the component:

Note the type of object you are trying to override; in this case the aim is to override a target address, so we care about a target component of sorts.
If the component is installed as the dependency of a RefBuild component, you can sometimes identify the component by visually inspecting the manifest.xml of the RefBuild or Scenario components.
Most product IDMConfig changes will be housed in the Data component directory. In this use case you are looking for a target address IDMConfig change, so a good guess would be that you are looking for a Data component.
Most base product Data components follow the naming convention hid_<type>_<identifier> .

Using the pointers noted above, it can be deduced that for overriding the AD target addresses, you should be looking at Data components.

Open the \<instance>\component\default\Data directory.
Searching through the list of Data components you will find a folder called \Data\hid_target_ad . Intuitively this seems like the correct Data component because it includes both "target" and "ad" in the name, but you should verify by inspecting the files.
Inspect the files within the \<instance>\component\Default\Data\hid_target_ad directory. It becomes clear that we’re interested in the ad.json file, as it provides the target address field.
The address field from the ad.json file is the one that provides the default placeholder of server=demo.local;listNestedGrps=true when the component is installed, so we know that the address field is what we have to write the override for in the abc-dev.json and abc-prod.json environment files.
Now that the data component and specific file we want to provide an override has been determined, the override needs to be specified in our respective environment files for dev and prod. We will start with the abc-dev.json file for the dev environment.

Write the override in the environment files

We have identified the component and field we need to provide an override for and will now specify the override in our respective environments, starting with abc-dev.json.

A good starting point for your environment file is to add three keys, one for each component directory (Data, Functional, Scenario) to help visualize how the overrides apply according to the component's directory. This helps when adding many overrides to environment files since it will keep them organized by component type.

To start the dev environment file:

Open the abc-dev.json file in a plain-text file editor, and add the 3 keys to indicate the component directories by entering the following:
```
{
	"Scenario": {},
	"Functional": {},
	"Data": {}
}
```
Now that there is a basic skeleton, you know our component of interest is in the Data directory, so add the component name to the Data key. The file now looks like:
```
{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
		}
	}
}
```
Next, specify which file from the component is being overridden. It was determined above that file will be the ad.json file. Adding that information makes the environment file look like:
```
{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {}
		}
	}
}
```
For the configuration override itself, the right dictionary structure needs to be used to enter into the abc-dev.json environment file to ensure the replacement is applied in the correct location. To do this, navigate to the <instance>\default\Data\hid_target_ad directory and open the ad.json file.
You will notice that it is a .json file with a dictionary inside. Find the target address field you want to override by inspecting the objects. From the contents of the ad.json file, the "address" is located under "Fields" . The dictionary structure is then ad.json["Fields"]["address"] , so that is what we need to add to the abc-dev.json file.
Navigate back to the abc-dev.json file, open it in the file editor, and add the dictionary structure ad.json["Fields"]["address"] so your file looks like the following:
```
{
  "Scenario": {},
  "Functional": {},
  "Data": {
    "hid_target_ad": {
      "ad.json": {
        "Fields": {
          "address": "{server=dev.corp;listNestedGrps=true}"
        }
      }
    }
  }
}
```
From the addition, now abc-dev.json is applying an override to the ad.json file provided by Data.hid_target_ad to change the value of the ["Fields"]["address"] to the dev environment's custom server=dev.corp value.
Save the abc-dev.json file.
Now we can complete a similar change to our abc-prod.json, but using the required value of server=prod.corp for the production environment. Open the abc-prod.json file in the file editor and add the following:
```
{
  "Scenario": {},
  "Functional": {},
  "Data": {
    "hid_target_ad": {
      "ad.json": {
        "Fields": {
          "address": "{server=prod.corp;listNestedGrps=true}"
        }
      }
    }
  }
}
```
Save the abc-prod.json file.

Load the dev environment

The environment files have been successfully written. In order to apply the configuration overrides from the environment file to the product, the environment file needs to be loaded. To do this for the dev environment:

On your development product server install the product. This is your dev environment.
Create the \environments directory as described above and place the abc-dev.json file into it.
Launch a command prompt as an Administrator and navigate to the \<instance> directory.
Run the command:
instance.bat
Navigate to the \<instance>\script directory.

Load the environment by running the commands:

manage_components.py load
manage_components.py env load abc-dev

Install the Data.hid_target_ad component

It is important to note that you can install the data component individually or as part of the Scenario or Functional component that has it listed as a dependency. Either way, the data component will be installed with the environment file overrides. In this case we will install the data component directly.

While still in the \<instance>\script directory, install the Data.hid_target_ad component by running the command (note: the component is case sensitive):
```
manage_components.py install Data.hid_target_ad
```
You know that the command has run successfully if the command prompt shows the skins being built and installed.
Verify that your Active Directory target address has now been changed to server=dev.corp;listNestedGrps=true by clicking Manage the system > Resources > Target systems > Manually defined > AD and looking at the value for the Address .
If the address is changed to server=dev.corp;listNestedGrps=true in the AD target configuration, then you know you have written and applied the environment file correctly.

In this section:

Example: Create environment files to capture idmconfig changes

Search results