Intrinsic functions for JSONPath states in Step Functions

The States.Array intrinsic function takes zero or more arguments. The interpreter returns a JSON array containing the values of the arguments in the order provided. For example, given the following input:

{
  "Id": 123456
}

You could use

"BuildId.$": "States.Array($.Id)"

Which would return the following result:

“BuildId”: [123456]

Use the States.ArrayPartition intrinsic function to partition a large array. You can also use this intrinsic to slice the data and then send the payload in smaller chunks.

This intrinsic function takes two arguments. The first argument is an array, while the second argument defines the chunk size. The interpreter chunks the input array into multiple arrays of the size specified by chunk size. The length of the last array chunk may be less than the length of the previous array chunks if the number of remaining items in the array is smaller than the chunk size.

Input validation

For example, given the following input array:

{"inputArray": [1,2,3,4,5,6,7,8,9] }

You could use the States.ArrayPartition function to divide the array into chunks of four values:

"inputArray.$": "States.ArrayPartition($.inputArray,4)"

Which would return the following array chunks:

{"inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }

In the previous example, the States.ArrayPartition function outputs three arrays. The first two arrays each contain four values, as defined by the chunk size. A third array contains the remaining value and is smaller than the defined chunk size.

Use the States.ArrayContains intrinsic function to determine if a specific value is present in an array. For example, you can use this function to detect if there was an error in a Map state iteration.

This intrinsic function takes two arguments. The first argument is an array, while the second argument is the value to be searched for within the array.

Input validation

For example, given the following input array:

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "lookingFor": 5
}

You could use the States.ArrayContains function to find the lookingFor value within the inputArray:

"contains.$": "States.ArrayContains($.inputArray, $.lookingFor)"

Because the value stored in lookingFor is included in the inputArray, States.ArrayContains returns the following result:

{"contains": true }

Use the States.ArrayRange intrinsic function to create a new array containing a specific range of elements. The new array can contain up to 1000 elements.

This function takes three arguments. The first argument is the first element of the new array, the second argument is the final element of the new array, and the third argument is the increment value between the elements in the new array.

Input validation

For example, the following use of the States.ArrayRange function will create an array with a first value of 1, a final value of 9, and values in between the first and final values increase by two for each item:

"array.$": "States.ArrayRange(1, 9, 2)"

Which would return the following array:

{"array": [1,3,5,7,9] }

This intrinsic function returns a specified index's value. This function takes two arguments. The first argument is an array of values and the second argument is the array index of the value to return.

For example, use the following inputArray and index values:

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "index": 5
}

From these values, you can use the States.ArrayGetItem function to return the value in the index position 5 within the array:

"item.$": "States.ArrayGetItem($.inputArray, $.index)"

In this example, States.ArrayGetItem would return the following result:

{ "item": 6 }

The States.ArrayLength intrinsic function returns the length of an array. It has one argument, the array to return the length of.

For example, given the following input array:

{
   "inputArray": [1,2,3,4,5,6,7,8,9]
}

You can use States.ArrayLength to return the length of inputArray:

"length.$": "States.ArrayLength($.inputArray)"

In this example, States.ArrayLength would return the following JSON object that represents the array length:

{ "length": 9 }

The States.ArrayUnique intrinsic function removes duplicate values from an array and returns an array containing only unique elements. This function takes an array, which can be unsorted, as its sole argument.

For example, the following inputArray contains a series of duplicate values:

{"inputArray": [1,2,3,3,3,3,3,3,4] }

You could use the States.ArrayUnique function as and specify the array you want to remove duplicate values from:

"array.$": "States.ArrayUnique($.inputArray)"

The States.ArrayUnique function would return the following array containing only unique elements, removing all duplicate values:

{"array": [1,2,3,4] }

Use the States.Base64Encode intrinsic function to encode data based on MIME Base64 encoding scheme. You can use this function to pass data to other AWS services without using an AWS Lambda function.

This function takes a data string of up to 10,000 characters to encode as its only argument.

For example, consider the following input string:

{"input": "Data to encode" }

You can use the States.Base64Encode function to encode the input string as a MIME Base64 string:

"base64.$": "States.Base64Encode($.input)"

The States.Base64Encode function returns the following encoded data in response:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

Use the States.Base64Decode intrinsic function to decode data based on MIME Base64 decoding scheme. You can use this function to pass data to other AWS services without using a Lambda function.

This function takes a Base64 encoded data string of up to 10,000 characters to decode as its only argument.

For example, given the following input:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

You can use the States.Base64Decode function to decode the base64 string to a human-readable string:

"data.$": "States.Base64Decode($.base64)"

The States.Base64Decode function would return the following decoded data in response:

{"data": "Decoded data" }

Use the States.Hash intrinsic function to calculate the hash value of a given input. You can use this function to pass data to other AWS services without using a Lambda function.

This function takes two arguments. The first argument is the data you want to calculate the hash value of. The second argument is the hashing algorithm to use to perform the hash calculation. The data you provide must be an object string containing 10,000 characters or less.

The hashing algorithm you specify can be any of the following algorithms:

For example, you can use this function to calculate the hash value of the Data string using the specified Algorithm:

{
   "Data": "input data", 
   "Algorithm": "SHA-1" 
}

You can use the States.Hash function to calculate the hash value:

"output.$": "States.Hash($.Data, $.Algorithm)"

The States.Hash function returns the following hash value in response:

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

Use the States.JsonMerge intrinsic function to merge two JSON objects into a single object. This function takes three arguments. The first two arguments are the JSON objects that you want to merge. The third argument is a boolean value of false. This boolean value determines if the deep merging mode is enabled.

Currently, Step Functions only supports the shallow merging mode; therefore, you must specify the boolean value as false. In the shallow mode, if the same key exists in both JSON objects, the latter object's key overrides the same key in the first object. Additionally, objects nested within a JSON object are not merged when you use shallow merging.

For example, you can use the States.JsonMerge function to merge the following JSON objects that share the key a.

{
   "json1": { "a": {"a1": 1, "a2": 2}, "b": 2 },
   "json2": { "a": {"a3": 1, "a4": 2}, "c": 3 }
}

You can specify the json1 and json2 objects as inputs in the States.JsonMerge function to merge them together:

"output.$": "States.JsonMerge($.json1, $.json2, false)"

The States.JsonMerge returns the following merged JSON object as result. In the merged JSON object output, the json2 object's key a replaces the json1 object's key a. Also, the nested object in json1 object's key a is discarded because shallow mode doesn't support merging nested objects.

{
   "output": {
      "a": {"a3": 1, "a4": 2},
      "b": 2, 
      "c": 3 
   }
}

The States.StringToJson function takes a reference path to an escaped JSON string as its only argument.

The interpreter applies a JSON parser and returns the input's parsed JSON form. For example, you can use this function to escape the following input string:

{
 "escapedJsonString": "{\"foo\": \"bar\"}"
}
                

Use the States.StringToJson function and specify the escapedJsonString as the input argument:

States.StringToJson($.escapedJsonString)

The States.StringToJson function returns the following result:

{ "foo": "bar" }

The States.JsonToString function takes only one argument, which is the path that contains the JSON data to return as an unescaped string. The interpreter returns a string that contains JSON text representing the data specified by the Path. For example, you can provide the following JSON Path containing an escaped value:

{
  "unescapedJson": {
     "foo": "bar"
  }
}

Provide the States.JsonToString function with the data contained within unescapedJson:

States.JsonToString($.unescapedJson)
                

The States.JsonToString function returns the following response:

{\"foo\": \"bar\"}

Use the States.MathRandom intrinsic function to return a random number between the specified start number (inclusive) and end number (exclusive).

You can use this function to distribute a specific task between two or more resources.

This function takes three arguments. The first argument is the start number, the second argument is the end number, and the last argument controls the optional seed value, Note that if you use this function with the same seed value, it will return identical numbers.

Input validation

For example, to generate a random number between one and 999, you can use the following input values:

{
   "start": 1,
   "end": 999
}

To generate the random number, provide the start and end values to the States.MathRandom function:

"random.$": "States.MathRandom($.start, $.end)"

The States.MathRandom function returns the following random number as a response:

{"random": 456 }

Use the States.MathAdd intrinsic function to return the sum of two numbers. For example, you can use this function to increment values inside a loop without invoking a Lambda function.

Input validation

For example, you can use the following values to subtract one from 111:

{
   "value1": 111,
   "step": -1
}

Then, use the States.MathAdd function defining value1 as the starting value, and step as the value to increment value1 by:

"value1.$": "States.MathAdd($.value1, $.step)"

The States.MathAdd function would return the following number in response:

{"value1": 110 }

Use the States.StringSplit intrinsic function to split a string into an array of values. This function takes two arguments. The first argument is a string and the second argument is the delimiting character that the function will use to divide the string.

{
    "inputString": "1,2,3,4,5",
    "splitter": ","
}

"array.$": "States.StringSplit($.inputString, $.splitter)"

{"array":  ["1","2","3","4","5"] }

{
  "inputString": "This.is+a,test=string",
  "splitter": ".+,="
}

{
  "myStringArray.$": "States.StringSplit($.inputString, $.splitter)"
}

{"myStringArray": [
  "This",
  "is",
  "a",
  "test",
  "string"
]}

Use the States.UUID intrinsic function to return a version 4 universally unique identifier (v4 UUID) generated using random numbers. For example, you can use this function to call other AWS services or resources that need a UUID parameter or insert items in a DynamoDB table.

The States.UUID function is called with no arguments specified:

"uuid.$": "States.UUID()"

The function returns a randomly generated UUID, as in the following example:

{"uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }

Use the States.Format intrinsic function to construct a string from both literal and interpolated values. This function takes one or more arguments. The value of the first argument must be a string, and may include zero or more instances of the character sequence {}. There must be as many remaining arguments in the intrinsic function invocation as there are occurrences of {}. The interpreter returns the string defined in the first argument with each {} replaced by the value of the positionally-corresponding argument in the Intrinsic invocation.

For example, you can use the following inputs of an individual's name, and a template sentence to have their name inserted into:

{
 "name": "Arnav",
 "template": "Hello, my name is {}."
}

Use the States.Format function and specify the template string and the string to insert in place of the {} characters:

States.Format('Hello, my name is {}.', $.name)

or

States.Format($.template, $.name)

With either of the previous inputs, the States.Format function returns the completed string in response:

Hello, my name is Arnav.