Apache Velocity is the templating framework used to retrieve configuration information from within packet files and instance attributes.
See http://velocity.apache.org/ for more information.
All information in an environment is made available through Velocity. Enable checkbox “Parse with Velocity” in attribute definitions and packet files to use it. Reference an object by prefixing it with a Dollar-sign: $environment, $instance, …
The following table lists all objects and functions that are available when using Velocity.
| Name | Object type | Description |
| environment | Environment | The environment root |
| container | Container | The container of the current instance |
| instance | Instance | The current instance |
| D | java.lang.String | Use ${D} to insert a dollar-sign |
| Long | java.lang.Long | Long-class to enable its functions |
| String | java.lang.String | String-class to enable its functions |
| velocityUtils | VelocityUtils | Some extra helper functions |
| executingUsername | java.lang.String | The username of the currently active user |
The following table lists all variables that can be accessed directly through Velocity. The following will output the directory containing the environments: $environmentsRoot
| Variable | Type | Description |
| parserVersion | String | Version of the Infraxys Velocity parser |
| environmentsRoot | String | Path to the root of the environments-directory as it will exist when running actions in the Docker provisioning container. |
| modulesRoot | String | Path to the root of the modules-directory as it will exist when running actions in the Docker provisioning container. |
| D | String | The Dollar-sign is used by Velocity. If you need to use it in a file, then ${D} will do that. |
| executingUsername | String | The username of the user that is executing the Velocity parser. |
The tables below lists all available functions available to get information from the environment where the script or attribute currently lives.
There are 3 scopes:
Instances can be retrieved in many ways. The instance tree is walked recursively for all methods in the following tables unless the name starts with “getParent”. In that case, the tree is walked in the reverse order up-to the root instance on the container.
“getParent”-methods and getInstanceByAttributeVelocityName are only available for instances.
Recursive functions that are called on the container-object will loop over all instances of that container. All containers are included if this is done at the environment level.
Every instance has a field “Velocity name”. If this field has a value like “myPublicACL”, then anywhere in files or attributes that have Velocity enabled can use this instance through “$myPublicACL”.
If 2 instances have the same Velocity name, then only one of those instance is assigned the name. When script generation fails, this is displayed as a warning.
The following table contains an alphabetical list of functions that return no instance or only one. Most functions are self-explanatory, so no extra info is provided for brevity.
| Function | Description |
| getInstanceByAttributeValue(attributeName, value [, throwExceptionIfNotFound=false]) | |
| byVelocity(attributeName[, failIfEmpty][, failIfNotFound]) | On instances only. Gets the value from the specified attribute and returns the instance with that Velocity name |
| getInstanceById(id) | id is the Long value of the row in the database |
| getInstanceByPacketGuid(guid) | |
| getInstanceByPacketGuidAndAttributeValue(guid, attributeName, value [, throwExceptionIfNotFound=false]) | |
| getInstanceByPacketKey(packetKey) | |
| getInstanceByPacketKeyAndAttributeValue(packetKey, attributeName, value) | |
| getInstanceByPacketType(packetType) | |
| getInstanceByPacketTypeAndAttributeValue(packetType, attributeName, value) |
The following functions return a list with zero or more instances.
| Function | Description |
| getInstancesByAttributeName(attributeName) | |
| getInstancesByAttributeValue(attributeName, value) | |
| getInstancesByFileExtension(fileExtension) | |
| getInstancesByFilename(filename) | |
| getInstancesByGroup(group) | |
| getInstancesByPacketGuid(guid) | |
| getInstancesByPacketGuidAndAttributeValue(guid, attributeName, value) | |
| getInstancesByPacketKey(packetKey) | |
| getInstancesByPacketKeyAndAttributeValue(packetKey, attributeName, value) | |
| getInstancesByPacketKeys(packetKey, packetKey, ...) | Specify a comma-delimited list of keys |
| getInstancesByPacketType(packetType) | |
| getInstancesByPacketTypeAndAttributeValue(packetType, attributeName, value); | |
| getParentInstancesByPacketKey(packetKey) |
| Function | Description |
| getAttributes() | Get a list of the attributes of this instance |
| getAttribute(attributeName [, defaultValue]) | Get the string-value of the specified attribute `$instance.getAttribute("name")` |
| getAttributeAsBoolean(attributeName [, initCap] [, valueIfNull = false) | Get the attribute value as a "True", "true", "False" or "false". 0 (unchecked checkbox value) and "false" return the false value, otherwise the true value or valueIfNull is returned |
| getParent() | Get the direct parent |
| getParentInstanceByAttributeValue(attributeName, value [, throwExceptionIfNotFound=false]) | Retrieve the first parent instance with the specified attribute and value. |
| getParentInstanceByPacketKey(packetKey) | Retrieve the first parent instance of a packet with the specified key. |
| getParentInstanceByPacketType(packetType) | Retrieve the first parent instance of a packet with the specified type. |
| getPacketFileByFileExtension(fileExtension) | Retrieve the file with the specified extension from the packet of this instance |
| getPacketFileByFilename(filename) | Retrieve the file with the specified name from the packet of this instance |
| getPacketFileByKey(key) | Retrieve the file with the specified key from the packet of this instance |
| getRelativePath([includeEnvironment=true]) | Get the path to this instance including the container directory and optionally including the environment directory |
| hasAttributeDefined(attributeName) | Returns true if the packet of this instance has the specified attribute |
| isAttribute(attributeName) | Returns true if the packet of this instance or any parent instance has the specified attribute |
| isPacketType(packetType) | returns true if this instance's packet has the specified type |
| toJson([recurseLevels=0]) | Return a JSON-string for the instance and attributes with values. recurseLevel specifies how many instance-levels to recurse. 0 means only the current instance, -1 this instance and all child-instances recursive. Specify another value to control how deep to recurse. |
| Attribute | Description |
| container | |
| directory | The name of the directory on the provisioning server for this instance |
| groups | |
| id | Database record id |
| instanceLabel | |
| instances | Get a hierarchical list of all instances under this one |
| name | |
| packetGuid | |
| packetKey | |
| packetType | |
| velocityName |
| Function | Description |
| getContainerVarValue(attributeName[, defaultValue]) | Get the value of attribute |
| getContainerVarValues(attributeName) | Get a list of the values for the specified attribute that's defined at the "Container"-scope |
Calling these attributes: $container.id or $myLovelyInstance.container.name
| Attribute | Description |
| containerVars | A list of attributes that are defined with container-scope. |
| directory | The name of the directory on the provisioning server for this container |
| environment | |
| id | Database record id |
| instances | Get a hierarchical list of all instances under this one |
| keywords | |
| name | |
| description |
| Function | Description |
| getAllPackets() | Get a list with all packets that are used in the current environment |
| getAllPacketGuids() | Get a list of all packet GUIDs that are used in the current environment |
| getAuthorizationPolicy() | Returns a com.google.gson.JsonObject with the value of the authorization-policy tag or null if it's not defined for this environment |
| getContainerByName(containerName) | Get a list of containers of the current environment. This includes containers that where made available by linking it to the environment or through one of the parent projects |
| getContainers() | |
| getEnvironmentVarValue(attributeName[, defaultValue]) | Get the value of attribute |
| getEnvironmentVars() | Get a list of the values for the specified attribute that's defined at the "Environment"-scope |
| getTag(name) | Get the string-value for the tag with the specified name |
| getTagNames() | Returns a list of tag names that are defined for this environment |
| getTagsMap() | Returns a HashMap with name as the key |
| throwException(message) | Throw an exception and stop parsing |
Calling these attributes: $environment.id
| Attribute | Description |
| environmentVars | a list of attributes that are defined with environment-scope. |
| id | Database record id |
| name |
Loop over environment vars and generate a list of name-value pairs
#set ($environmentVars = $environment.getEnvironmentVars())
#foreach ($environmentVar in $environmentVars)
$environmentVar.attributeName=$environmentVar.attributeValue
#end
This example copies all files with a specific name to the temporary directory under a new, unique name for Terraform. When an instance script is run, it’s current directory is
This example also calls an init.sh script, if it exists. This can be used to insert dynamic attribute values into a file. In the case below, an AMI-ID is retrieved from AWS and set as a TF_VAR-environment variable.
${D} is used to put a Dollar-sign in the bash script.
#[[ and ]]# are used so Velocity doesn’t parse the contents in between these.
log_info is one of the functions available from the Infraxys core-module.
#foreach ($terraformInstance in $instance.getInstancesByFilename("main.tf"))
log_info 'Adding main.tf from "$terraformInstance.name" and copying all files ending with .tpl';
dir="$terraformInstance.getRelativePath()";
if [ -f "../../../${D}dir/init.sh" ]; then
log_info "Executing init.sh";
. "../../../${D}dir/init.sh";
fi;
cp ../../../${D}dir/main.tf /tmp/main__${terraformInstance.getId()}.tf;
for f in $(find ../../../#[[$]]#dir -type f -name *.tpl); do
cp #[[$f]]# /tmp/
done;
#end