DCM Definitions File Format

DCM Definitions File Format

The DCM definitions file provides a straightforward way to pass information to DCM targets (and task definitions if you work directly with those). Each definition file has this form:

<dcm:definition xmlns:dcm="urn:datapower:configuration:manager">
  ...
</dcm:definition>

The contents of the <dcm:definition> element depend on the targets that you want to use it with. It may contain multiple elements to accomplish different goals. For example, a definition file may contain all the <dcm:deployment-policy>, <dcm:idcred>, and <dcm:valcred> elements required to import a service and to configure its SSL/TLS aspects correctly.

Filtering for target environment and appliance

Each definition file is automatically processed to optionally remove elements that are not appropriate for the target environment or appliance. The key is the presence or absence of the environment="..." or deviceid="..." attributes.

Each XML element checked for an environment="..." or deviceid="..." attribute. When one is present and it doesn't match the ${environment} or ${device} property then that element is filtered out.

Note that the ${environment} and ${device} are standard DCM properties that are already specified for any deployment.

For example, given ${environment} is sit then this definition:

<dcm:definition xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:upload from="from/**.*" .../>
</dcm:definition>

would not be filtered out since neither of the XML elements contains environment="sit". On the other hand, this example would be changed by filtering:

<dcm:definition xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:upload environment="dev" local="fromDev/**.*" .../>
  <dcm:upload environment="sit" local="fromSit/**.*" .../>
  <dcm:upload environment="uat" local="fromUat/**.*" .../>
  <dcm:upload environment="prod" local="fromProd/**.*" .../>
</dcm:definition>

would become:

<dcm:definition xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:upload local="fromSit/**.*" .../>
</dcm:definition>

Note that the environment="..." attribute has been removed and the only element remaining is for the 'sit' environment.

Filtering of elements based on deviceid=${device} is also done. Note when both environment="..." and deviceid="..." are present in an element then both must match ${environment} and ${device}, respectively or the element is filtered out.

Including definition files in other definition files

Including a definition file in other definition files is not commonly done since the design goal for definition files is to keep them simple and their meanings obvious. Situations may arise, however, where including <dcm:*> elements from other files may be useful.

A <dcm:include href="..."/> element may occur anywhere in DCM definition files. This element is replaced by the content of the referenced file. The href="..." attribute is relative to the including definition file but it may instead be a fully qualified path.

The <dcm:wrapper> element is critical to this process. Included files cannot contain <dcm:definition> elements since this is strictly a top-level element. Instead, the outermost element in included files shoule be <dcm:wrapper>. These are removed as part of the process of resolving <dcm:include href="..."/> elements.

You might think that this would be a reasonable approach to a top level definition file, but it isn't:

<dcm:wrapper xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:include environment="dev" href="defsDev">
  <dcm:include environment="sit" href="defsSIT">
  <dcm:include environment="uat" href="defsUAT">
  <dcm:include environment="prod" href="defsProd">
</dcm:wrapper>

With definition files in this form:

<dcm:definition xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:upload local="fromSit/**.*" .../>
</dcm:definition>

The reason this won't work is that include processing is performed, and completed, before the filtering process happens. The correct approach (which I haven't yet tested) would be this:

<dcm:wrapper xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:include href="defsDev">
  <dcm:include href="defsSIT">
  <dcm:include href="defsUAT">
  <dcm:include href="defsProd">
</dcm:wrapper>

With definition files in this form:

<dcm:definition environment="sit" xmlns:dcm="urn:datapower:configuration:manager">
  <dcm:upload local="fromSit/**.*" .../>
</dcm:definition>

Again, I haven't tested this approach and frankly don't recommend it, but it may be possible. Please update the wiki if you try it. ;-)