Overriding configuration

For this discussion the Data.hid_target_ad component is used as the desired component to override. The Data.hid_target_ad component is responsible for installing the default Active Directory target with most reference build component installations.

From the component fully qualified name (fqname for short) of Data.hid_target_ad, it is deduced that this override should go under the Data key. So, adding the component name (without the type) to the Data dictionary, gives the environment file entry:

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
		}
	}
}

Now the name of the file that the configdata entries exist in for this component needs to be determined. To do so, navigate to the directory of the component in question and open the manifest.xml file. In the manifest file there is a specification for configdata that includes a filename. The name of the file in that section of the manifest file is what you are looking for.

For the Data.hid_target_ad component:

It becomes clear that the ad.json file is the one containing configdata entries due to its placement in the configdata portion of the manifest.

Since only the filename is needed, you may wonder why it's necessary to look in the manifest file. This is because had the ad.json file been nested in a directory, the type of slash (\ or /) indicated in the manifest file matters to the environment file script.

Meaning:

<filename>files/ad.json</filename>

is not the same as:

<filename>files\ad.json</filename>

When writing the environment file override, the same type of slash needs to be specified in the environment file as in the manifest file.

Now that the name of the file is known, adding it to the environment file looks like:

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {}
		}
	}
}

Past this point, the override syntax in the environment file depends on the type of configuration being overridden. Types of overrides include configuration object (IDMConfig) and policy table (ExtDB) overrides.

IDMConfig handles all configuration you would do inside of the product, from things like Account Attribute Definitions, to Target addresses, and System Variables, IDMConfig handles reading the data from a .json file and loading it into the product so it can be leveraged.

To override IDMConfig data, the replacement in the environment file is written similarly to the structure in the .json component file. Building on the Data.hid_target_ad example from before, the agenttime field of our target configuration is accessed by looking through the ad.json file and locating the "agenttime" row of the file.

Opening the ad.json file shows top lines:

"Fields": {
	"address": "{server=demo.local;listNestedGrps=true}",
	"adminclaimhide": true,
	"adminresethide": false,
	"adminunlockhide": false,
	"agenttime": 300,
	...
}

Adding the agenttime field override to the environment file so that the agenttime target configuration option is overridden to 600 uses the syntax:

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {
				"Fields": {
					"agenttime": 600
				}
			}
		}
	}
}

The other common type of configuration to override is data provided from components to External Data Store tables (ExtDB). These are overridden similarly to the IDMConfig data shown before, but with a few slight differences that allow the writer to override specific rows and columns in the csv configuration data that may be included with a particular component.

For this discussion, the steps necessary to override the value for the association_attrs configuration setting in the hid_global_configuration ExtDB policy table are detailed. The default value of association_attrs is employeeNumber and will be overridden in an environment file to be mail instead.

Finding the component

To change the association_attrs row value in the hid_global_configuration ExtDB table, the component we are trying to alter needs to be found. The component for an ExtDB entry can be found by viewing the ComponentOwnerFQN field in the row you are looking to alter.

For the row containing the association_attrs setting, the component name in the ComponentOwnerFQN field is Scenario.im_corp_loaddb .

Finding appropriate CSV rows

Finding the appropriate .csv file that contains the configdata information for the component is a similar process to finding the appropriate .json for IDMConfig overrides.

For the Scenario.im_corp_loaddb component:

Other useful CSV row syntax

Add or exclude rows

Rows can be added or removed from .csv files by adding appropriate syntax to the environment file. This is done by adding a plus + or minus - sign to the row indicator. For example:

{"+[0]":{1,2,3}}

would insert three integers as the first three values in the first row and:

{"-[1]": {}}

would exclude the second row from the indicated .csv file.

Be careful when overriding specific elements in arrays, such as "[0]" (the first element) in the example above. If you use a number out of range, you will get an error at component install that will not mention the environment file. This will make it difficult to trace the source of the error. What you will see is, after an info entry saying the Data component config.json has been loaded, a long Python Traceback that ends in a statement about an item type mismatch.

Replace all values with the same variable in a list

To replace an item for all the rows in a .csv list with the same input, you would use a * row indicator. Here is an example where the "value" item is changed for all rows of the global_configuration.csv file to equal "@shortID,mail" :

{
"Scenario": {
  "im_corp_loaddb": {
    "data\\global_configuration.csv": {
      "[*]": {
        "value": "@shortID,mail"
      }
    }
  }
},
"Functional": {},
"Data": {}
}

Components with two csv files

Components that have multiple .csv files can have numerous files, rows and items altered within the same environment file.

In the example below, the Scenario.pam_vault_management component has one specified row item replaced in the policy_attrval_validation.csv and a different item in two different specified rows replaced within the policy_attrval_calculation.csv file:

{
"Scenario": {
  "pam_vault_management": {
    "data\\policy_attrval_validation.csv": { 
      "[0]": { 
        "set_visible": "True"
      } 
    }, 
    "data\\policy_attrval_calculation.csv": { 
      "[1]": { 
        "SkipRemaining": "Stage" 
      }, 
      "[2]": { 
        "SkipRemaining": "All" 
      } 
    }
  }
},
"Functional": {},
"Data": {}
}