Skip to main content

Custom macros

Macros give you the ability to add variable data (configuration settings) to an unattend file or post-installation script. Lenovo XClarity Administrator allows you to define your own custom settings by creating a custom configuration-settings file, using JSON format.

The value for each custom configuration setting varies based on user input that is specified during OS deployment.

When you import custom configuration settings in XClarity Administrator, XClarity Administrator validates the JSON schema. If the validation passes, XClarity Administrator generates custom macros for each setting.

To inject custom macros in to an unattend file or post-installation script, use the unique name of the object, separate nested objects using a period, and then surround the macro name with a hash symbol (#), for example, #server_settings.server0.locale#.

Note

  • Do not include the top-most object name.

  • When an object is created from a template, the name is appended with a unique number, starting with 0 (for example, server0 and server1).

  • You can see the name for each macro from the Deploy OS Images dialog on the Custom Settings tabs by hovering over the Help icon (Help icon) next to each custom setting.

Configuration settings​

You can define custom configuration settings that:

  • Are common to all target servers or unique to a specific target server.

  • Have static (non-configurable) values or with dynamic (configurable) values that are entered when you deploy the OS-image profile.

  • Have a variable number of elements based on a template. For example, you can define a configuration setting that let's you specify 0 – 3 NTP servers during deployment.

Common settings

During OS deployment, the UI elements on the Common Settings tabs on the Deploy OS Image dialog are rendered based on the objects that are represented in the content object. The objects describe the settings and values that the all target servers need for OS deployment.

To represent settings that are common to all servers, the JSON file must contain a parent object with a nested object that contains the "common":true name/value pair.

The following example uses the same configurable (dynamic) NTP servers for all servers.
{
   "category": "dynamic",
   "content": [{
      "category": "dynamic",
      "common": true,
      "description": "NTP Servers",
      "label": "NTP Servers",
      "maxElements": 3,
      "minElements": 0,
      "name": "common-ntpservers",
      "optional": true,
      "template": [{
         "autoCreateInstance": true,
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver",
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string"
      }],
      "type": "array"
   },
   ...,
}
The following example uses the same non-configurable (static) post-installation script log directory.
{
   "category": "dynamic",
   "content": [{
      "category": "static",
      "common": true,
      "description": "Directory location for post-installation script logging.",
      "name": "logpath",
      "optional": false,
      "type": "string",
      "value": "/tmp/mylogger.log"
   },
   ...,
}
Server-specific settings

During OS deployment, the UI elements on the Server-Specific Settings tab on the Deploy OS Image dialog are rendered based on the objects that are represented in the template’s content objects. The objects describe the settings and values that a specific target server needs for OS deployment.

After the server-specific values are gathered in the UI, a content object is created in the JSON for each target server based on the template object. Each content object contain a unique name and targetServer field, and any values that were inputted for that server.

To represent the server-specific settings, the JSON file must contain a parent object with the following content:

  • The "category":"dynamic" name/value pair.

  • A nested object that contains the "common":false name/value pair. Only one "common": false object is supported in the content of the parent object.

  • A template object with an embedded content object. This template array can contain only one object.

For example, if you want to define a unique OS locale for each target server
{
   "category": "dynamic",
   "content": [{
      "category": "dynamic",
      "common": false,
      "name": "server-settings",
      "optional": false,
      "template": [{
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         }],
         "name": "server",
         "optional": false,
         "type": "assoc_array"
      }],
      "type": "assoc_array"
   },
   ...,
}

JSON specification​

The following table describes the fields that are allowed in the JSON specification.

ParameterRequired / OptionalTypeDescription
autoCreateInstanceOptionalBooleanIndicates whether an instance of the template object is created automatically in JSON file at deployment time. This can be one of the following values.
  • true. An instance of the template object is created automatically in JSON file at deployment time.
  • false. (default) An instance of the template object is not created automatically in JSON file at deployment time
Note
This field can be placed only in the template object.
categoryRequiredStringIndicates how the value of each setting is populated. This can be one of the following values:

  • dynamic. The value is input by the user at run time. Lenovo XClarity Administrator prompts you for this value during OS deployment.

  • predefined. The value is preset by Lenovo XClarity Administrator.

  • static. The value is specified in the schema and does not change at run time.

Nested objects inherit the value of this field from its parent object.

If category is set to static in the parent object, then it must be set to static in all nested objects as well. If category is set to dynamic in the parent object, it can be either static or dynamic in the nested objects.

choicesOptionalArray of values that match the type propertyArray of static values (such as strings or integers) for the configuration setting from which the user can select during OS deployment (for example, ["enabled","disabled"]).
commonOptionalBooleanIndicates whether this configuration schema applies to all target servers.

  • true. The object applies to all target servers.

  • false. (default) The object applies to a specific target server.

Nested objects inherit the value of this field from its parent object.

If common is set to true in the parent object, then it must be set to true in all nested objects as well. If common is set to false in the parent object, then it must be set to false in all nested objects.

contentOptionalArray of objectsPattern that represents nested objects in the schema.

After user-inputted data is gathered during OS deployment, this field is used to represent the final values for a given template in the instance of the configuration-settings file that is created for the deployment.

defaultOptionalVaries depending on the typeThe default value.
descriptionOptionalStringDescription of the object
labelOptionalStringLabel for the setting in the user interface that is displayed during OS deployment
maxOptionalIntegerMaximum value, when type is set to integer.

The default value is unlimited.

maxElementsOptionalIntegerMaximum number of entries in the array for this object.
minOptionalIntegerMinimum value, when type is set to integer.

The default value is 0.

minElementsOptionalIntegerMinimum number of entries in the array for this object.
nameRequiredStringUnique name of the object.

This name can contain only the following characters: alphanumeric characters (a-z, A-Z, and 0-9), underscore (_), and dash (-).

You can reference the name as a custom macro in the unattend file. When referencing a nested name object, separate each object using a period (for example, mydeploy.node.locale).

optionalRequiredBooleanIndicates whether the object is optional. This can be one of the following values.

  • true. The field is optional

  • false. The field is required.

regexOptionalStringRegular expression for validating the value (for example, "[\\w\\.]{1,64}$")
scriptOptionalArray of stringsList of scripts, separated by a comma, that have dependencies on the data in this object (for example, ["/opt/lenovo/saphana/bin/saphana-create-saphana.sh", "create_hana.sh"]).
Note
The scripts must be available to the OS-image profile as an installation script or custom software.
targetServerOptionalStringUUID of the server that is the target for the OS deployment.

If common is true, this field can be empty or null, and the target server is specified during OS deployment.

templateOptionalArray of objectsPattern that represents reusable objects.

During OS deployment, this template can represent multiple instances of the object. The minElements and maxElements fields can be used to limit the number of instances.

The following example uses a template to represent an array of 1 - 3 NTP servers.
{
   "category": "dynamic",
   "common": true,
   "description": "NTP Servers",
   "label": "NTP Servers",
   "maxElements": 3,
   "minElements": 0,
   "name": "common-ntpservers",
   "optional": true,
   "template": [{
      "autoCreateInstance": true,
      "category": "dynamic",
      "common": true,
      "description": "A NTP Server",
      "label": "NTP Server",
      "name": "ntpserver",
      "optional": true,
      "regex": "[\\w\\.]{1,64}$",
      "type": "string"
   }],
   "type": "array"
},
After user-inputted values are gathered during OS deployment, an instance of the configuration-settings file is created with specific content for each device on which the OS is to be deployed.
{
   "category": "dynamic",
   "common": true,
   "description": "NTP Servers",
   "label": "NTP Servers",
   "maxElements": 3,
   "minElements": 0,
   "name": "common-ntpservers",
   "optional": true,
   "content": [{
      "category": "dynamic",
      "common": true,
      "description": "A NTP Server",
      "label": "NTP Server",
      "name": "ntpserver0",
      "optional": true,
      "regex": "[\\w\\.]{1,64}$",
      "type": "string",
      "value": "192.0.2.1"
   }],
   "template": [{
      "category": "dynamic",
      "common": true,
      "description": "A NTP Server",
      "label": "NTP Server",
      "name": "ntpserver",
      "optional": true,
      "regex": "[\\w\\.]{1,64}$",
      "type": "string"
   }],
   "type": "array"
}
Note

  • A template is required at the top level of server-specific objects (common=false).

  • If category is static, the template field is ignored.

typeRequiredStringData type for the object. This can be one of the following values.

  • array

  • assoc_array

  • boolean

  • integer

  • password

  • string

  • user_data

valueOptionalStringA single static value for the configuration setting.
Note

  • If default is set, this field can be empty or null; otherwise, specify a value that matches type.

  • If type is password, specify a non-encrypted string.

  • If type is assoc_array or array, you must also specify an empty content field.

  • If type is user_data, specify valid JSON-formatted value.

  • If regex is set, this value is validated using the specified regular expression.

The following example configuration settings define locale settings for SLES deployments that can be added to a custom profile.
{
<span id="osdeploy_configschema__schema_file" className="ph">   "category": "dynamic",
   "content": [{
      "category": "dynamic",
      "common": false,
      "name": "server-settings",
      "optional": false,
      "template": [{
         "autoCreateInstance": true,
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the OS language locale to use with this deployment. 
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         },
         {
            "category": "dynamic",
            "choices": ["english-us", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the keyboard locale to use with this deployment. 
                           English, Brazilian Portuguese, and Japanese are supported.",
            "label": "Keyboard Locale",
            "name": "keyboardLocale",
            "optional": false,
            "type": "string",
            "value": "english-us"
         }],
         "name": "server",
         "optional": false,
         "type": "assoc_array"
      }],
      "type": "assoc_array"
   },
   {
      "category": "dynamic",
      "common": true,
      "description": "NTP Servers",
      "label": "NTP Servers",
      "maxElements": 3,
      "minElements": 0,
      "name": "common-ntpservers",
      "optional": true,
      "template": [{
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver",
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string"
      }],
      "type": "array"
   },
   {
      "category": "static",
      "common": true,
      "description": "Directory for post-installation script logging.",
      "name": "logpath",
      "optional": false,
      "type": "string",
      "value": "/tmp/mylogger.log"
   }],
   "description": "Custom configuration file for deployment of custom locale, NTP server, 
                   and directory for post-installation script logs.",
   "label": "My Custom Deployment",
   "name": "myCustomDeploy",
   "optional": false,
   "type": "array"</span>
}
The following example is the instance of the configuration settings file that is created on the host system after user-inputted values are defined during deployment.
{
<span id="osdeploy_configschema__config_schema" className="ph">   "category": "dynamic",
   "content": [{
      "category": "dynamic",
      "common": false,
      "name": "server-settings",
      "optional": false,
      "content": [{
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the OS language locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         },
         {
            "category": "dynamic",
            "choices": ["english-us", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the keyboard locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "Keyboard Locale",
            "name": "keyboardLocale",
            "optional": false,
            "type": "string",
            "value": "english-us"
         }],
         "name": "server0",
         "optional": false,
         "type": "assoc_array",
         "targetServer": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      },
      {
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the OS language locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         },
         {
            "category": "dynamic",
            "choices": ["english-us", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the keyboard locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "Keyboard Locale",
            "name": "keyboardLocale",
            "optional": false,
            "type": "string",
            "value": "english-us"
         }],
         "name": "server1",
         "optional": false,
         "type": "assoc_array",
         "targetServer": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
      }],
      "template": [{
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the OS language locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         },
         {
            "category": "dynamic",
            "choices": ["english-us", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the keyboard locale to use with this deployment.
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "Keyboard Locale",
            "name": "keyboardLocale",
            "optional": false,
            "type": "string",
            "value": "english-us"
         }],
         "name": "server",
         "optional": false,
         "type": "assoc_array"
      }],
      "type": "assoc_array"
   },
   {
      "category": "dynamic",
      "common": true,
      "description": "NTP Servers",
      "label": "NTP Servers",
      "maxElements": 3,
      "minElements": 0,
      "name": "common-ntpservers",
      "optional": true,
      "content": [{
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver0,
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string",
         "value": "192.0.2.1"
      },
      {
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver1",
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string",
         "value": "192.0.2.2"
      }],
      "template": [{
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver",
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string"
      }],
      "type": "array"
   },
   {
      "category": "static",
      "common": true,
      "description": "Directory for post-installation script logs.",
      "name": "logpath",
      "optional": false,
      "type": "string",
      "value": "/tmp/mylogger.log"
   }],
   "description": "Custom configuration file for deployment of custom locale, NTP server, 
                   and directory for post-installation script logs.",
   "label": "My Custom Deployment",
   "name": "myCustomDeploy",
   "optional": false,
   "type": "array"</span>
}