Template functions

StackState Self-hosted v4.5.x

This page describes StackState v4.5.x. The StackState 4.5 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.5 version range to upgrade to a more recent release.

Go to the documentation for the latest StackState release.

Overview

StackState Template JSON (STJ) incorporates several custom handlebars functions that can be used, for example, to get existing nodes from the graph, create new nodes or join texts together. The available StackState functions are described below.

Functions

add

Adds number variables together.

Arguments

Two or more number variables.

Examples

Template

{{# add a b c }}

Data

[ a: 1, b: 2, c: 3 ]

Result

6

concat

The concat function concatenates two values:

concat "Type=ComponentType;Name=" element.type.name

get

The get function finds a node of a certain type by its unique identifier without needing to specify the type of the node. The function finds a node in a nested way, first finding the identifier and then finding the type and name in the scope of the first resolved node.

get <identifier> Type=<type>;Name=<name>

Examples

• Resolve the Production Environment using:

  get "urn:stackpack:aws:environment:production"

• Resolve the Parameters metrics from the CheckFunction identified by urn:stackpack:aws:check_function:basic using:

  get "urn:stackpack:aws:check_function:basic" "Type=Parameter;Name=metrics"

getFirstExisting

Gets the first node from a list of node identifiers (URNs).

Arguments

Two or more URNs strings.

Examples

Template

{{ getFirstExisting "urn:stackpack:aws:domain:Old" "urn:stackpack:aws:domain:New" }}

Data

This example assumes urn:stackpack:aws:Old: does not exist, whereas urn:stackpack:aws:domain:New does exist.

Result

urn:stackpack:aws:domain:New

getOrCreate

The getOrCreate function first tries to resolve a node by its identifier and then by the fallback create-identifier. If none are found, the function will create a node using the specified Type and Name arguments and the newly created node will be identified with the create-identifier value.

getOrCreate <identifier> <create-identifier> Type=<type>;Name=<name>

Note that:

• getOrCreate works only with the following (simple) types: Environment, Layer, Domain, ComponentType and RelationType.

• create-identifier must be a value in the "urn:system:auto" namespace.

We strongly encourage to use get and getOrCreate as resolving nodes by identifier is safer than by name due to the unique constraint enforced in the identifier values.

Examples

Find the Production Environment by its identifier and fallback identifier, or otherwise create it:

getOrCreate "urn:stackpack:aws:environment:production" "urn:system:auto:stackpack:aws:environment:production" "Type=Environment;Name=Production"

identifier

The identifier function creates an identifier out of an identifier prefix, a component type and a component name.

identifier "urn:stackpack:common" "ComponentType" element.type.name

include

This function will only work when the template is loaded from a StackPack.

Includes the content of another file inside this template. This can come in handy when template files become exceedingly large, when working with images or when you want to reuse the same template fragments in multiple locations.

Arguments

include "<filename>" "<encoding>"

1. filename - The name of the file to include from the StackPack. The file must exist in the provisioning directory or one of its sub-directories (see StackPack packaging.

2. encoding (optional, default = handlebars) - Choice of:

   • handlebars - Included file will be interpreted as StackState Templated JSON.

   • identity - Included file will be not be interpreted, but simply will be included as text.

   • base64 - Included file will be loaded using a BASE64 encoding. This is possible for the image types: png, jpg, gif and svg.

Examples

• Include a script:

Template

{
  "_type": "CheckFunction",
  "description": "Converts AWS state to Stackstate run state",
  "identifier": "urn:stackpack:aws:shared:check-function:aws-event-run-state",
  "name": "AWS event run state",
  "parameters": [
    {
      "_type": "Parameter",
      "multiple": false,
      "name": "events",
      "required": true,
      "system": false,
      "type": "EVENT_STREAM"
    }
  ],
  "returnTypes": [ "RUN_STATE" ],
  "script": "{{ include "./scripts/AWS event run state.groovy" }}"
}

Data

The file /provisioning/script/AWS event run state.groovy in the AWS StackPack contains return RUNNING

Result

{
  "_type": "CheckFunction",
  "description": "Converts AWS state to Stackstate run state",
  "identifier": "urn:stackpack:aws:shared:check-function:aws-event-run-state",
  "name": "AWS event run state",
  "parameters": [
    {
      "_type": "Parameter",
      "multiple": false,
      "name": "events",
      "required": true,
      "system": false,
      "type": "EVENT_STREAM"
    }
  ],
  "returnTypes": [ "RUN_STATE" ],
  "script": "return RUNNING"
}

• Include an image:

Template

{
  "_type": "ComponentType",
  "identifier": "urn:stackpack:aws:shared:component-type:aws.cloudformation",
  "name": "aws.cloudformation",
  "iconbase64": "{{ include "./icons/aws.cloudformation.png" "base64" }}"
}

Data

The file /provisioning/icons/aws.cloudformation.png contains an image of the AWS CloudFormation logo.

Result

{
  "_type": "ComponentType",
  "identifier": "urn:stackpack:aws:shared:component-type:aws.cloudformation",
  "name": "aws.cloudformation",
  "iconbase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAfkYAhBBGAIQQCgAhhAJACKEAEEIoAIQQCgAhhAJACKEAEEIoAIQQCgAhhAJACKEAEEIoAIQQCgAhhAJACKEAEEL65P8BEaL9HlGPnesAAAAASUVORK5CYII"
}

join

Joins array or map data as a text usign a separator, prefix and suffix. This is especially handy when producing JSON arrays.

Arguments

# join <iteratee> "<separator>" "<prefix>" "<suffix>"

1. iteratee - the element to repeat and join together.

2. separator - the text that is used to separate the elements.

3. prefix (optional) - text that is placed at the beginning of the joined text.

4. suffix (optional) - text is appended at the end of the joined text.

Examples

• Join an array of labels to create a JSON array of objects:

Template

{{# join labels "," "[" "]" }}
{
  "_type": "Label",
  "name": "{{this}}"
}
{{/ join }}

Data

[ labels: [ 
    "hello", 
    "world" 
] ]

Result

[{
  "_type": "Label",
  "name": "hello"
},{
  "_type": "Label",
  "name": "world"
}]

• Join a map of labels to create a JSON array of objects:

Template

{{# join labels "," "[" "]" }}
{
  "_type": "Label",
  "name": "{{key}}:{{this}}"
}
{{/ join }}

Data

[ labels: [ 
    "key1": "hello", 
    "key2": "world" 
] ]

Result

[{
  "_type": "Label",
  "name": "key1:hello"
},{
  "_type": "Label",
  "name": "key2:world"
}]

See also

• Using StackState Template JSON (STJ)