Schema / Envelope for use with Step Functions

[jsvandeven-ws]

Looking at the built in schemas for the parser, I don't see one for use with step functions. Are any of the available parsers suitable for use with step function invocation of lambdas?

[dreamorosi]

Hi @jsvandeven-ws, could you share an example of a payload you're referring to, and a link to its documentation?

[jsvandeven-ws]

Hmm not sure if this helps, but for example I have a state machine defined in a cloud formation template as below:

  StepFunction:
    Type: AWS::Serverless::StateMachine
    Properties:
      Role: !GetAtt StepFunctionRole.Arn
      Definition:
        StartAt: ManageStackSet
        States:
          ManageStackSet:
            Type: Task
            Resource: !GetAtt ManageStackSet.Arn
            InputPath: $
            Parameters:
              StackSetNamePrefix: !Ref StackSetNamePrefix
              AccountPrefix.$: $.accountPrefix
              Accounts.$: $.accounts
              ExecutionId.$: $$.Execution.Name
            ResultPath: $.Result
            OutputPath: $
            Next: WaitForStackSet

Is there a schema that would match the event passed to the ManageStackSet lambda function? It looks like state machine states have a pretty unique payload in that you define the shape with the InputPath, if I'm understanding things correctly.

[dreamorosi]

Thanks for the example.

I think there might be some confusion with the scope/purpose of our Parser utility.

In its current form, the utility is meant to be used to parse and validate payloads received by a Lambda function. For example, when you configure a service to call your function, the service usually passes an object (aka the payload) to the function as first parameter (event).

In the case of StepFunctions, you can create a task that calls your Lambda function, and you can configure what gets passed to the function using the Payload parameter.

To give you an example, I have created a very simple workflow that calls a Lambda function (this uses CDK but the same applies to SAM):

const fn = new NodejsFunction(this, 'MyFunction', {
    functionName: 'StepfunctionFn',
    runtime: Runtime.NODEJS_20_X,
    entry: './src/index.ts',
    handler: 'handler',
  });

  const stateMachine = new StateMachine(this, 'MyStateMachine', {
    definitionBody: DefinitionBody.fromChainable(
      new LambdaInvoke(this, 'MyLambdaTask', {
        lambdaFunction: fn,
        payload: TaskInput.fromJsonPathAt('$'),
      }).next(new Succeed(this, 'GreetedWorld'))
    ),
  });

As you can see I am using the $ expression in the payload field, which means that Step Functions will pass to the function the entire payload as it was at that state.

For reference, this is the function that is being called:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

export const handler = async (event: unknown) => {
  logger.info('event', { event });
  return {
    statusCode: 200,
    body: JSON.stringify('Hello, World!'),
  };
};

As we can see, it's just logging the event as-is. Then, I started a new workflow using the payload { "hello": "world" } as initial input for the state machine, this is the graph representation and the details on the payload of that task:

Finally, this is the log emitted by the function:

{
    "level": "INFO",
    "message": "event",
    "sampling_rate": 0,
    "service": "service_undefined",
    "timestamp": "2024-07-31T09:55:19.843Z",
    "xray_trace_id": "1-66aa0a07-640cde29176d38c96c172f2e",
    "event": {
        "hello": "world"
    }
}

We can observe that the event key contains exactly the original payload that I specified in my state machine definition ($) and nothing else.

---

To sum up, it appears that there's no Step Functions-specific envelope for the payload sent to a Lambda function when configured as task. This is because Step Functions doesn't inject/include any metadata to the payload besides what you configure in your state machine definition.

I hope this helps, if I am missing something please let me know, and ideally provide a more comprehensive example to help me understand the gap.

[jsvandeven-ws]

No that's perfect, thank you for the comprehensive reply. My misunderstanding was just the incorrect assumption that there would be some context or structure to the event payload like my experience with other event types for lambda.