Maps

Workflows supports maps (dictionaries) that can hold a user-defined structure of variables or lists.

For other map processing functions, see the Workflows standard library map module reference.

Map definition

To define a map, add an assign step to the workflow:

YAML

 - STEP_NAME_A:  assign:  - MAP_A:  KEY_1: VALUE_1  KEY_2:  KEY_3: VALUE_2

JSON

 [  {  "STEP_NAME_A": {  "assign": [  {  "MAP_A": {  "KEY_1": "VALUE_1",  "KEY_2": {  "KEY_3": "VALUE_2"  }  }  }  ]  }  }  ]

For example:

YAML

- createMap:  assign:  - dynamicKey: "MiddleName"  - myMap:  FirstName: "John"  ${dynamicKey}: "Apple"  LastName: "Smith"  Age: 26  Address:  Street: "Flower Road 12"  City: "Superville"  Country: "Atlantis"

JSON

[  {  "createMap": {  "assign": [  {  "dynamicKey": "MiddleName"  },  {  "myMap": {  "FirstName": "John",  "${dynamicKey}": "Apple",  "LastName": "Smith",  "Age": 26,  "Address": {  "Street": "Flower Road 12",  "City": "Superville",  "Country": "Atlantis"  }  }  }  ]  }  } ]

If a key name includes non-alphanumeric characters (for example, the exclamation point in "special!key": value), you must wrap the key name in quotes. For more information, in this document, see Access key names with non-alphanumeric characters.

Similarly, when using dynamic keys in a map defined with braces, wrap the expression in quotes (single or double) so that it is YAML-compliant. For example:

YAML

 - createMap:  assign:  - dynamicKey: "myKey"  - myMap: {"${dynamicKey}": "myValue"}  - myMap2: {'${dynamicKey + "Apple"}': "myValue"}

JSON

 [  {  "createMap": {  "assign": [  {  "dynamicKey": "myKey"  },  {  "myMap": {  "${dynamicKey}": "myValue"  }  },  {  "myMap2": {  "${dynamicKey + \"Apple\"}": "myValue"  }  }  ]  }  }  ]

Read map values

To read the values in a map, use one of the following structures within an expression:

${MAP.KEY} ${MAP[KEY_EXPRESSION]}

Access nested keys

Use an additional period or index to access the value of a nested key. For example, to return the value of Country from the previous example:

YAML

 - lastStep:  return: ${myMap.Address.Country}

JSON

 [  {  "lastStep": {  "return": "${myMap.Address.Country}"  }  }  ]

Access key names with non-alphanumeric characters

When accessing key names with non-alphanumeric characters (for example, the exclamation point in "special!key": value), you must wrap the key name in quotes:

YAML

 - createMap:  assign:  - var:  key:  "special!key": bar  - lastStep:  return: '${"foo" + var.key["special!key"]}'

JSON

 [  {  "createMap": {  "assign": [  {  "var": {  "key": {  "special!key": "bar"  }  }  }  ]  }  },  {  "lastStep": {  "return": "${\"foo\" + var.key[\"special!key\"]}"  }  }  ]

Perform a safe lookup on a map

You can use the standard library function, map.get, to perform a safe lookup on a map, returning null if the key is not found. For example:

YAML

 - lastStep:  return: ${default(map.get(myMap, "FirstName"), "Couldn't find key!")}

JSON

 [  {  "lastStep": {  "return": "${default(map.get(myMap, \"FirstName\"), \"Couldn't find key!\")}"  }  }  ]

For nested maps, a list of keys can be used to drill down into the map, using a nested key lookup. For example, map.get(my2DMap, ["key1", "key2"]) is equivalent to map.get(map.get(my2DMap, "key1"), "key2").

Insert and update map values

Use an assign step to update existing keys, or to assign a value to a new key.

Using index notation allows the use of expressions as the key. Note that the expression must evaluate to a string during execution.

YAML

 - update_map:  assign:  - my_map: {"Key1": "hello"}  - key_str: "Key"  - my_map.Key1: "Value1"  - my_map["Key2"]: "Value2"  - my_map[key_str]: "Value3"  - my_map[key_str + "4"]: "Value4"

JSON

 [  {  "update_map": {  "assign": [  {  "my_map": {  "Key1": "hello"  }  },  {  "key_str": "Key"  },  {  "my_map.Key1": "Value1"  },  {  "my_map[\"Key2\"]": "Value2"  },  {  "my_map[key_str]": "Value3"  },  {  "my_map[key_str + \"4\"]": "Value4"  }  ]  }  }  ]

You can create and update nested map values:

YAML

 - update_nested_map:  assign:  - my_map: {}  - my_map.NestedMapKey: {"Key1":"Value1"}  - my_map.NestedMapKey.Key2: "Value2"

JSON

 [  {  "update_nested_map": {  "assign": [  {  "my_map": {}  },  {  "my_map.NestedMapKey": {  "Key1": "Value1"  }  },  {  "my_map.NestedMapKey.Key2": "Value2"  }  ]  }  }  ]

You can update map keys dynamically in a for loop:

YAML

 - update_map_in_loop:  assign:  - keys: ["key1", "key2"]  - my_map: {}  - for_loop:  for:  value: v  index: i  in: ${keys}  steps:  - loop_step:  assign:  - my_map[v]: ${i}  - return_step:  return: ${my_map}

JSON

 [  {  "update_map_in_loop": {  "assign": [  {  "keys": [  "key1",  "key2"  ]  },  {  "my_map": {}  }  ]  }  },  {  "for_loop": {  "for": {  "value": "v",  "index": "i",  "in": "${keys}",  "steps": [  {  "loop_step": {  "assign": [  {  "my_map[v]": "${i}"  }  ]  }  }  ]  }  }  },  {  "return_step": {  "return": "${my_map}"  }  }  ]

The result of the preceding workflow should be {"key1":0,"key2":1}.

Check existence of a key in a map

To check whether a given key is present in a map, use the following expression: 

${KEY in MAP}

For example:

YAML

 - MyStep:  switch:  - condition: ${"Age" in myMap}  next: AgeExists

JSON

 [  {  "MyStep": {  "switch": [  {  "condition": "${\"Age\" in myMap}",  "next": "AgeExists"  }  ]  }  }  ]

To check whether a key is not in a map, use the not() function:

YAML

 - MyStep:  switch:  - condition: ${not("Age" in myMap)}  next: AgeMissing

JSON

 [  {  "MyStep": {  "switch": [  {  "condition": "${not(\"Age\" in myMap)}",  "next": "AgeMissing"  }  ]  }  }  ]

Get the length of a map

You can get the length of a map by using the len() expression helper. This built-in function accepts an attribute of type map and returns the number of elements in the map as an integer. For example, the following sample returns 2:

YAML

 - init:  assign:  - my_map: {"key1": "hello", "key2": "world"}  - returnStep:  return: ${len(my_map)} # returns `2`

JSON

 [  {  "init": {  "assign": [  {  "my_map": {  "key1": "hello",  "key2": "world"  }  }  ]  }  },  {  "returnStep": {  "return": "${len(my_map)}"  }  }  ]