Reference Template DSL Definition
The reference template in this section includes Domain-specific Language (DSL) reference details about how to define a template. Use the reference template to understand the syntax and structure of the composite template definition and to refer to examples.
#
# Composite Template DSL
#
# Convention Description
# REQUIRED The key/value is required
# OPTIONAL The key/value is optional
# IMPLICIT The key/value always exists even when not directly defined
# CONVENTIONAL The key/value is a non-nomenclature convention
alias: reference # REQUIRED A unique alias for the template. Validated, do not use ^\w+[\w\-\.]*$
description: Template DSL # OPTIONAL Description, not validated.
dslVersion: "1.2" # OPTIONAL The version of the composite template DSL. DSL "1.2" is supported in Command Central 10.4 and higher.
version: 0.1 # OPTIONAL The version of the template definition file (based on user-defined versioning of the updates to the
# template definition).
changes: # OPTIONAL List of changes/updates of the template definition file.
- 0.1 Created template definition
- 0.2
- 0.3
- ...
options: # OPTIONAL Modifies how Command Central processes a template during the template application.
abortOnConfigFailure: true # OPTIONAL Default: true (when applying a template for installations 10.4). If set to "true", executing
# the entire template fails when a product configuration cannot be applied.
abortOnLayerStartupFailure: false # OPTIONAL Default: false (when applying a template for installations 10.4). If set to "false", Command
# Central returns a warning when a run-time component does not start and continues processing the template.
forceRestartWhenDone: false # OPTIONAL Default: false. If set to "false", Command Central does not restart the run-time components at the end
# of the template application. Cannot use this parameter for product installations 10.1 or lower.
startupLayers: true # OPTIONAL Default: Default: true. If set to "true", after applying a layer, Command Central starts all run-time
# components created for the layer.
environments: # OPTIONAL Input parameters for this template.
default: # OPTIONAL Global defaults.
# environment.type: default # IMPLICIT The type of the environment, for example "envType1".
param1: defaultValue # OPTIONAL Parameter with a default value, you can refer to ${param1} from anywhere in the template.
param2: ${} # REQUIRED Parameter without a default value. You must provide a value. Fails fast.
param3: # OPTIONAL Parameter without a default value, but you do not have to provide a value. Might fail late.
runtimes.skip.start: <rcId1>,<rcId2> # OPTIONAL. Comma-separated list of run-time components that Command Central will not start when applying
# the template. You can use a regular expression.
param4: ${@credentials.credentialsAlias.username} # OPTIONAL Existing credentials alias that matches the username for different sets
# of credentials, such as repo or product user credentials.
param5: ${@credentials.credentialsAlias.password} # OPTIONAL Existing credentials alias that matches the password for different sets
# of credentials, such as repo or product user credentials.
spm.username: ${@credentials.credentialsAlias.username} # OPTIONAL Existing credentials alias that matches the username that Command Central
# uses to connect to Platform Manager nodes.
spm.password: ${@credentials.credentialsAlias.password} # OPTIONAL Existing credentials alias that matches the password that Command Central
# uses to connect to Platform Manager nodes.
actions: # OPTIONAL Actions in the default section are executed as part of any environment.type.
# All actions in the "environments" section are local, which means that the actions are executed on the Command
# Central server host. In addition to that, actions are executed as local if the node on which the actions get
# executed is the local node. All other actions are remote.
defaultAction1: # REQUIRED The name of the action. Fow Windows, the name must end with .bat
description: "default action 1"
phase: post # OPTIONAL Default: post; "pre" actions are executed before any other operation and
# "post" actions are executed after all other operations.
failOnError: true # OPTIONAL Default: true; If set to "true", executing the entire template fails if the action fails.
# If set to "false", executing the templat e continues.
skipOnTemplateError: true|false # OPTIONAL Default: false; If set to "true", does not execute the action if the template application fails.
# If set to "false", executes the action before stopping the template application.
target: POSIX # OPTIONAL Default: POSIX; If "WINDOWS" the action will be executed only on Windows. If "POSIX",
# the action will be executed on "POSIX"-compliant systems. Note that the "target" parameter is used only for
# local actions. All remote actions are executed in a "POSIX" environment.
verbose: false # OPTIONAL Indicates whether to include the standard output from the shell actions defined in the template in the Command
# Central logs. Valid values: true (include the standard output) | false (do not include the standard output) Default: false
# Note that when “verbose: true” for actions that contain sensitive information (such as plain text passwords), the sensitive
# information will get included in the Command Central logs.
script: | # REQUIRED (except when you specify "file") The code of the action. The code can use any interpreter available
# on the system, such as Perl, Python, Ruby, and PHP.
#!/bin/sh
touch default_action1
file: /path/to/executable # REQUIRED (except when you specify "script"). If you set both "file" and "script" parameters, "script" is used
# and "file" is ignored. The path can be absolute or relative to the composite template archive.
# If the path is relative, the file is taken from the composite template archive.
envType1: # Parameters used when environment.type=envType1
param1: envTypeDefaultValue1 # Parameter 1 with a default value for this environment.type.
param2: envTypeDefaultValue2 # Parameter 2 with a default value.
param3: envTypeDefaultValue3 # Parameter 3 with a default value.
migration.pre.cleanup: true|false # OPTIONAL. When set to true, Command Central cleans up the migration registry before executing the
# template. When "migration.pre.cleanup" and "migration.post.cleanup" are not set or their value is
# false, Command Central automatically cleans up the migration registry 60 hours after a successful
# template execution.
migration.post.cleanup: true|false # OPTIONAL. When set to true, Command Central cleans up the migration registry after
# executing the template.
actions: # OPTIONAL See the comments for environments/default/actions.
dev: # CONVENTIONAL Development or test environment type with a single node instance.
server: # CONVENTIONAL (Pre)production environment type with single a host/server.
layer: # CONVENTIONAL (Pre)production environment type with multiple hosts/servers, but not in a cluster.
cluster: # CONVENTIONAL (Pre)production environment type with multiple hosts/servers in a cluster.
repositories: # OPTIONAL Repository definition for centralized Comand Central repositories.
product: # OPTIONAL Repositories for installing products.
webMethods-9.8: # REQUIRED MASTER repository with default name "webMethods-<version>" from the closest geographic location.
credentials: ${repo.product.credentials.alias} #The alias of a default or user-defined COMMON-CREDENTIALS configuration instance.
My-9.8-linux: # IMAGE repository name.
location: path/to/product/image/file.zip # REQUIRED The relative path to a product image archive.
fix: # OPTIONAL Repositories for installing fixes.
webMethods: # REQUIRED MASTER global fix repository with a default name.
credentials: ${repo.fix.credentials.alias} #The alias of a default or user-defined COMMON-CREDENTIALS configuration instance.
My-9.8-fixes: # IMAGE repository name.
location: path/to/fix/image/file.zip # REQUIRED The relative path to a fix image archive.
asset: # OPTIONAL Repositories for assets.
assets-repo: # REQUIRED The name of the asset repository.
type: # REQUIRED The type of the asset repository. Valid values: flatfile and git.
description: # OPTIONAL Description of the repository.
location: # REQUIRED The location of the flatfile image on the file system or the URL of the git repository.
credentials: ${repo.git.credentials.alias} # REQUIRED For a git repository: the alias of a default or user-defined COMMON-CREDENTIALS
# configuration instance.
nodes: # OPTIONAL The managed Platform Manager nodes.
default: # OPTIONAL Default parameters for all managed nodes.
aliasMapping: # OPTIONAL Specifies the type of policy to use when mapping host names to node aliases.
policy: HOSTNAME|INDEX|EXISTING # OPTIONAL Default: HOSTNAME. "HOSTNAME" maps each layer defined in provision/envType to a list of node
# aliases or hostnames. "EXISTING" uses the details of a Platform Manager node that already exists in Command
# Central and ignores any parameters included in the "nodes" section of the template, except the node alias.
# "INDEX" uses node aliases with a custom prefix and an index number.
prefix: ${node.alias.prefix}# OPTIONAL The custom prefix to use in a node alias when "policy: INDEX". Default: node
delimiter: "_" # OPTIONAL The character to use as delimiter in the indexed node alias, for example "-". Default: "_"
default: # OPTIONAL Default parameters for ANY <nodeAlias> that does not have an explicit definition.
# host: nodeAlias # IMPLICIT Mapping <nodeAlias> to a hostname for this node.
actions: # OPTIONAL (executed on the respective remote nodes) See environments/default/actions
port: 8093 # OPTIONAL The Platform Manager port number. Default: 8093
secure: true # OPTIONAL Indicates whether to use SSL. Valid values: true (use SLL)|false (do not use SSL). Default: true
credentials: ${spm.credentials.alias} # REQUIRED The credentials alias for the Platform Manager "Administrator" user. Default: ADMINISTRATOR
bootstrapInfo: # OPTIONAL Bootstrapping details.
installer: bootstrap.installer # OPTIONAL The file name of the Command Central bootstrap installer to use for
# bootstrapping Platform Manager.
installDir: /install/dir # OPTIONAL The installation directory. The default value depends on the target operating system,
# for example /opt/webmethods on UNIX
substituteUserCredentials: substCredentialsAlias # OPTIONAL For remote bootstrap: the alias of the substitute user credentials
# to use to install and start Platform Manager.
credentials: SSHCredentialsAlias # REQUIRED For remote bootstrap: the SSH credentials to connect to the remote hosts for
# authenticationMethod: PASSWORD.
authenticationMethod: # OPTIONAL Valid values: PASSWORD, INTERACTIVE, or CERTIFICATE
privateKey: ~/.ssh/id_rsa # OPTIONAL, The location of the privateKey file for authenticationMethod: CERTIFICATE
node1: # REQUIRED The unique alias of node1. Validated, do not use ^\w+[\w\-\.]*$
host: node1host.com # The hostname for node1.
actions: # OPTIONAL (executed on the respective remote node) See environments/default/actions
envType1: # OPTIONAL The environment type.
aliasMapping: # OPTIONAL The type of policy to use when mapping host names to node aliases for envType1.
policy: HOSTNAME # OPTIONAL Uses HOSTNAME as the node alias mapping policy for envType1.
node1: # The alias of node1.
host: localhost # The hostname for node1 in envType1
port: 8192 # The Platform Manager port, different from the default port.
bootstrapInfo:
installDir: /other/path # The installation directory. Specify a location path different from the default installation directory.
layers: # OPTIONAL The definition of layers.
default: # OPTIONAL The default parameters for all layers.
productAdministrator:
credentials: <administratorCredentialsAlias> # OPTIONAL The credentials alias defined for the administrator user credentials for the products in
# the layer. The default is ADMINISTRATOR.
changeOnFirstLogin: true|false # OPTIONAL Indicates whether the product requires administrator password change on the first login.
# Valid values: true (password change required)| false (password change not required). Default: false
productRepo: repositoryName # REQUIRED The name of a product repository. You can specify a repository defined in the "environments"
# section or run this command to get a list of repositories: cc list repository products properties=displayName
fixRepo: repositoryName # REQUIRED The name of a fix repository. You can specify a repository defined in the "environments"
# section or run this command to get a list of repositories:
# sagcc list repository fixes properties=displayName
actions: # OPTIONAL (executed on the respective remote nodes) See environments/default/actions
layer1: # REQUIRED A unique alias for the layer (the alias is unique within THIS template), validation: ^\w+[\w\-\.]*$
description: Layer One # OPTIONAL A description of the layer. Not validated.
productRepo: repositoryName # OPTIONAL The name of a product repository. Default: layers/default/productRepo
fixRepo: repositoryName # OPTIONAL The name of a fix repository. Default: layers/default/fixRepo
templates: # REQUIRED An ordered list of templates. The list can be empty.
- inlineTemplate1 # OPTIONAL An alias of an inline template. The alias should be defined in THIS template.
- inlineTemplate2 # OPTIONAL Another alias of an inline template. The alias should be defined in THIS template.
actions: # OPTIONAL The actions are executed on the respective remote nodes.
# See the comments for environments/default/actions
databases: # OPTIONAL Database actions, such as creating a database schema and storage (performed by DBConfigurator).
dbAction1: # REQUIRED The name of the action.
description: IS/TN storage and schemas
components: [STR] # REQUIRED (except when you specify "products") The DBConfigurator codes for the database components.
products: [IS,TN] # REQUIRED (except when you specify "components") The DBConfigurator IDs of products.
db.type: sqlserver # OPTIONAL Any number of arbitrary properties.
db.url: "jdbc:sqlserver://dbhost1.eur.ad.sag:1433"
db.username: foo
db.password: bar
db.admin.username: sa
db.admin.password: manage
dbAction2:
components: [STR]
db.type: sqlserver
db.url: "jdbc:sqlserver://dbhost2.eur.ad.sag:1433"
db.username: foo
db.password: bar
dbAction2:
products: [MWS]
db.type: sqlserver
db.url: "jdbc:sqlserver://dbhost2.eur.ad.sag:1433"
db.username: foo
db.password: bar
layer2: # REQUIRED, A unique alias of another layer.
templates: [] # An empty template list means that the nodes of this layer will not get processed.
migration: # OPTIONAL The environment migration details.
sourceType: NODES # OPTIONAL The source type to use for migration. Valid values: NODES|ARCHIVES. Default: NODES
archives: # OPTIONAL The configuration of the source archives. This parameter is used only when "sourceType"
# is set to ARCHIVES.
targetPath: /home/myuser/backup.zip # OPTIONAL The location of the source archive.
options: # OPTIONAL Options to prepare the source node for migration.
snapshot: # OPTIONAL Indicates whether to create a template from each source node.
execute: false # OPTIONAL Executes the "create" template. Valid values: true|false. Default: false
pause: # OPTIONAL Indicates whether to pause all source runtime components.
execute: true # OPTIONAL Executes "pause" lifecycle operation. Valid values: true|false. Default: true
shutdown: # OPTIONAL Stop all source runtime components, including Platform Manager.
execute: true # OPTIONAL Executes "stop" lifecycle operation. Valid values: true|false. Default: true
backup: # OPTIONAL Indicates whether to create a backup of the source installation directory
# on the same host machine and transfer the backup archive to Command Central.
execute: true # OPTIONAL Executes "backup" of source installation directory. Valid values: true|false.
# Default: false when doing migration on same hosts
excludes: # OPTIONAL Indicates which files to exclude from the backup archive.
patterns: ["*.log", "*.jar", "*.zip", "path/to/directory/to/exclude/*"] # OPTIONAL Excludes the specified file types and
# file directories. Default: ["*.log"]
except: ["wm-caf-server.jar", "dd-cjdbc.jar", "template.zip"] # OPTIONAL Excludes specific files, identified by file name.
# Valid values: a list of file names. Default: []
rename: # OPTIONAL Indicates whether to rename the source installation directory.
execute: true # OPTIONAL Executes "rename" the source directory. Valid values: true|false,
# Default: true when doing an overinstall migration (migration on the same host and installation directory).
targetPath: /install/dir_renamed # OPTIONAL The location of the renamed source installation directory.
# Default: migration_source_<sourceVersion>_<installDir>
source: # OPTIONAL A map of layers to source nodes. Default: layers to nodes provisioning map
default: # OPTIONAL Default parameters that apply to any environment type.
layer1: node1 # REQUIRED A list of source node aliases for "layer1"
layer2: # REQUIRED A list of source node aliases for "layer2". An empty list indicates that source nodes
# are not allocated for this layer.
envType1: # OPTIONAL A migration source map for "envType1" if different from "default".
layer1: [node1, node2] # OPTIONAL A list of source node aliases for "layer1" if different from "default".
layer2: [node1] # OPTIONAL A list of source node aliases for "layer2" if different from "default".
nodes: # OPTIONAL The source nodes from which to migrate. Default: managed provisioning nodes.
default: # OPTIONAL The default source parameters.
default: # OPTIONAL The default parameters for ANY "nodeAlias" that does not have an explicit definition.
# host: nodeAlias # IMPLICIT The mapping of the "nodeAlias" to a hostname for this source node.
port: 8093 # OPTIONAL The number of the Platform Manager port. Default: 8093
secure: true # OPTIONAL Indicates whether to use SSL. Valida values: true|false. Default: true
bootstrapInfo: # OPTIONAL The information required for bootstrapping Platform Manager.
installDir: /install/dir # OPTIONAL The source node installation directory. Default: depends on the target operating system,
# for example /opt/webmethods on UNIX.
credentials: # OPTIONAL The remote SSH connection credentials.
authenticationMethod:# OPTIONAL Valid values: PASSWORD, INTERACTIVE, or CERTIFICATE
privateKey: ~/.ssh/id_rsa # OPTIONAL The privateKey file location when authenticationMethod: CERTIFICATE
envType1: # OPTIONAL The type of the source environment.
node1: # The alias of "node1".
host: localhost # The hostname for "node1" in "envType1".
port: 8192 # A non-default port.
bootstrapInfo:
installDir: /other/path# A non-default location path for the installation directory.
provision: # REQUIRED when the node alias mapping policy is INDEX. OPTIONAL when policy HOSTNAME|EXISTING.
# Maps which layers to provision on which nodes.
default: # OPTIONAL Default properties that apply to any environment type.
spm: # REQUIRED for "aliasMapping/policy: INDEX". The first layer in a provisioning/envType section is the
# infrastructure layer and always includes the "hosts" parameter.
hosts: [host1, host2, host3] # REQUIRED A list of all Platform Manager nodes to use in all layers defined in the template.
layer1: # REQUIRED A list of node aliases on which to apply "layer1".
aliases: [nodePrefix_1,nodePredfix_2] # REQUIRED when "aliasMapping/policy:INDEX". A list of node aliases. Each alias is formed from
# "aliasMapping/prefix:" parameter and an index number that indicates the consecutive
# the value of the order of the host in the "spm/hosts" parameter. Use "_" as a separator in
# the indexed node alias.
layer2: # REQUIRED A list of node aliases for "layer2".
index: [2,3] # REQUIRED when "aliasMapping/policy:INDEX". A list of indexes. Each index in the list indicates the
# consecutive order of the host (on which to install the layer) in the "spm/hosts" parameter.
layer3: # REQUIRED A list of node aliases for "layer3". An empty list indicates that no nodes are allocated
# for this layer.
envType1: # OPTIONAL The provisioning map for "envType1" if different from the "default" section.
layer1: [node1,node2] # OPTIONAL A list of node aliases for "layer1" if different from the "default" section.
layer2: [node1] # OPTIONAL A list of node aliases for "layer2" if different from the "default" section.
templates: # OPTIONAL The inline templates.
default: # OPTIONAL The default template. You can define only actions for the "default" template.
actions: # OPTIONAL The actions are executed on the respective remote nodes. See the comments for
# environments/default/actions
templateActionDefault: # REQUIRED The name of the action.
namePrefix: hexTimestamp|none # OPTIONAL Indicates whether Command Central adds a prefix to the names of action files created
# on the file system. "hexTimestamp" (default) - the filename for an action is prefixed by
# a hexadecimal representation of the timestamp at the time of template evaluation.
# "none" - the filename for an action does not get a prefix.
# If not included (default), Command Central adds prefixes to action file names to prevent
overwriting the files.
inlineTemplate1: # REQUIRED A unique alias for the template. The alias is unique within THIS template.
# Validated, do not use ^\w+[\w\-\.]*$
description: example1 # OPTIONAL A description of the template. Not validated.
files: # OPTIONAL A list of files to copy from the template to the target installation directory.
"target/file1": "src/file" # The syntax is "target path": "template source file"
"file2": "src/path/file" # Another file to copy.
licenses: # OPTIONAL A list of license key aliases to copy from the license repository to the target
# installation directory.
"target/licenseKey1": "${alias1}" # The syntax is "target license key path": "license key alias". The "${alias}" value is not
# case-sensitive and you can use wildcard characters, for example:
"licenseKey2": "${alias2}" # "target/licenseKey": "*_<productCode>_<majorVersion>.*_${os.platform}" Another license key to copy.
actions: # OPTIONAL The actions are executed on the respective remote nodes. See the comments for
# environments/default/actions
products: # OPTIONAL A list of products to install from "productRepo: repositoryName" defined for the parent layer.
product1: # REQUIRED The ID of "product1".
# To retrieve a list of product IDs, run this command: sagcc list repository products content repositoryName
product2: # REQUIRED The ID of "product2".
instance1: # REQUIRED An instance name for "product2". You specify the name as reference ${instance.name} within its scope.
# The instance name can be "default" for products that do not support instance management.
instanceParam1: value1 # OPTIONAL Parameter1 of the product instance.
instanceParam2: value2 # OPTIONAL Parameter2 of the product instance.
configuration: # OPTIONAL The configuration settings for product2/instance1
runtimeComponent1: # REQUIRED The ID of run-time component1. You can use the implicit ${instance.name} variable.
CONFIG-TYPE1: # REQUIRED A supported configuration type1 for "runtimeComponent1".
CONFIG-TYPE1-i1: # REQUIRED An existing or new configuration instance "i1" of the parent "CONFIG-TYPE1".
Field1: v1 # YAML or JSON representation of the configuration data.
Field2: # Based on the CONFIG-TYPE1 schema, some fields are required and some are optional.
Field3: v3 # The field values can use ${parametersAsVariables}
Field4: ${param1}
CONFIG-TYPE2: # Another configuration type.
CONFIG-TYPE2-i2: "${param2}" # REQUIRED You can format the configuration data as plain text.
CONFIG-TYPE3:
CONFIG-TYPE3-i3: | # You can format the configuration data a as multi-line plain text.
multi line1
multi line2
multi line3
CONFIG-TYPE3: &reference # OPTIONAL A label that can be used for re-use (see the next CONFIG-TYPE3 parameter).
CONFIG-TYPE3-i3: | # If a configuration type supports XML format, you can format the configuration data as XML.
<foo>
<bar/>
</foo>
rcid-${instance.name}: # REQUIRED The ID of another run-time component. You can use the implicit ${instance.name} variable.
CONFIG-TYPE3: *reference # Re-uses the definition of the same configuration type.
fixes: [fix1_v1, MWS_10.3_Fix2]|ALL # OPTIONAL A list of fixes to install from "fixRepo: repositoryName" defined for the parent layer.
# To retrieve a list of fix names (with or without the version) or fix IDs,
# run this command: sagcc list repository fixes content repositoryName
# When "fixes: ALL", Command Central installs all fixes for the products defined in the template.
patches: [patchKey1, patchKey2] # OPTIONAL A list of support patch IDs. The support patches are installed in the order in which they are listed.
# If the list is empty "[]", Command Central does note install any support patches. If you specify a list
# of "fixes:" and a list of "patches:", Command Central first installs the fixes and then the patches.
inlineTemplate2: # Another inline template definition. An empty template definition does nothing.
originally: fix: # OPTIONAL Repositories for installing fixes. Empower: # REQUIRED MASTER global fix repository with a default name. credentials: ${repo.fix.credentials.alias} #The alias of a default or user-defined COMMON-CREDENTIALS configuration instance.