Control Files

HFMCmd uses a control file that contains commands and parameters in YAML (Yet Another Markup Language) format. YAML is a plain-text data format similar in capability to XML, but is significantly more human-readable. This is primarily because it uses indentation to determine the nesting of data structures, so there is no need to worry about opening/closing tags.

Commands

When a command takes properties, the command name should be followed by a colon, and the properties should then be specified one per line, and indented by a consistent amount of whitespace (typically 2 or 4 spaces).

Properties may be either single-valued or a collection. Single-valued properties should specify the property name followed by a colon and then the property value. List-of-value properties can be specified using either:

the property name followed by a colon, and then a comma-delimited list of values; or
the property name followed by a colon, and then a property value per line, indented further, and preceded by a dash.

Examples:

   property: value
   property: value1, value2, value3
   property:
     - value1
     - value2
     - value3

A sample control file:

SetLogonInfo:
    UserName: admin
    Password: password

OpenApplication:
    Cluster: TEST
    Application: Simple

Consolidate:
    Scenario: Actual
    Years:
        - 2013
        - 2014
    Periods: {Months}
    Entities: {[Hierarchy]}
    ConsolidationType: Impacted

The sample control file above contains three commands (SetLogonInfo, OpenApplication, and Consolidate), and the arguments needed for each command.

Pre-Processor

A control file may also contain pre-processor directives, which are used to modify the YAML content before it is parsed. Pre-processor directives come in three varieties:

comments
substitution variables, and
directives.

Comments

Comments are any lines beginning with # or any comment on a line preceded by #. Comments are stripped out by the pre-processor before the YAML parser parses the control file. Examples:

# This is a comment line

SetLogonInfo:   # This part of the line is ignored

Substitution Variables

Substitution variables can be used in control files to make them more dynamic, and to avoid the need to hard-code sensitive information such as user ids and passwords.

Substitution variables can appear anywhere in a control file, and are identified by the form:

    %variable%

When a control file is loaded, the pre-processor replaces all %variable% placeholders with the value of the substitution variable before the line is parsed by the YAML parser.

    SetLogonInfo:
        UserName: admin
        Password: %password%

Substitution variable values can be set:

in control files, via the use of the %set directive, e.g.
```
%set application Simple
```
on the command-line, via keyword arguments, e.g.
```
HFMCmd control.yaml password:secret
```
via environment variables; if no other value can be found for a substitution variable, and an environment variable exists with the same name, the environment variable value is used.

Directives

Directives are used to modify the document being parsed, or the state of the variable dictionary used for replacing substitution variable placeholders.

Variable Directives

Pre-processor directives can be used to set (or unset) variable values, with the changes taking place from that point in the control file forward.

%set: Sets the substitution variable to the specified value:
```
%set <variable> <value>
```
Note that the <variable> name should omit the leading and trailing % symbols.
%unset: Unsets (i.e. clears) the substitution variable value.
```
%unset <variable>
```

Include Directive

To facilitate re-use of common commands or fragments, the pre-processor provides the %include directive.

Syntax:

    %include <file>

When an %include directive is encountered, the contents of the specified control file are immediately included into the current control file at the point of the %include directive.

Included files may also include other files, so long as the includes do not result in a cycle.

Conditional Directives

Conditional directives can be used to conditionally include or exclude a section of the control file, based on whether or not a substitution variable is set.

%if-def: The subsequent block of the control file will only be processed if the specified substitution variable has a value.
```
%if-def <variable>
    ...
[%else]
    ...
%end-if
```
%if-undef: The subsequent block of the control file will only be processed if the specified substitution variable does not have a value.
```
%if-def <variable>
    ...
[%else]
    ...
%end-if
```

Conditional directives are particularly useful for setting default values when no value is supplied on a command-line, and for ensuring that pre-requisite commands are only performed once.