AWS SAM passing path parameters to state machine triggered by api call

Question

I am creating a state machine in SAM that is triggered by API Gateway.

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'

Resources:

ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: dev
 
  PartnerDownloadFileMachine:
    Type: 'AWS::Serverless::StateMachine'
    Properties:
      DefinitionUri: statemachines/partner-download-file.asl.json
      DefinitionSubstitutions:
        CheckPartnerCredentialsArn: !GetAtt CheckPartnerCredentials.Arn
      Events:
        PartnerDownloadFileEvent:
          Type: Api
          Properties:
            Method: get
            Path: /DownloadFile/{partnerId}/{accessToken}/{fileId}
            RestApiId: 
              Ref: ApiGateway
      Policies:
        - LambdaInvokePolicy:
            FunctionName: !Ref CheckPartnerCredentials

CheckPartnerCredentials:
    Type: AWS::Serverless::Function 
    Properties:
      CodeUri: src/
      Handler: checkPartnerCredentials.handler
      Runtime: nodejs16.x

Globals:
  Api:
    Cors:
      AllowMethods: "'*'"
      AllowHeaders: "'*'"
      AllowOrigin: "'*'"

Outputs:
  PartnerDownloadFileMachineArn:
    Value: !Ref PartnerDownloadFileMachine
  PartnerDownloadFileMachineRole:
    Description: "IAM Role created for PartnerDownloadFile Machine based on the specified SAM Policy Templates"
    Value: !GetAtt PartnerDownloadFileMachineRole.Arn

And first lambda definition in my state machine definition

"States": {
  "Check Partner Credentials": {
    "Type": "Task",
    "Resource": "${CheckPartnerCredentialsArn}",
    "Next": "Valid Partner Credentials?"
  },

And the state machine is triggered by the api call but what I need is access to the path parameters in the api call but my lambda function cannot see them. What do I need to do so that I have access to the path parameters?  Am I missing a permission?  All the examples I have found on the web that triggers a state machine from the api gateway with sam are not using path parameters.

Answer

Firstly, to start a step function execution from API Gateway (i.e. invoke step function from API gateway), I recommend you to refer the following document [1]. And to have Lambda function invocation in Step function, refer this document [2]

As mentioned in [3] StartExecution API need three parameters, 1. input json to Step Function 2. Name of execution 3. Step function ARN. In the example [1] the input is passed as {} i.e. an empty json, so the step function will be executed with empty json.

To invoke Step function with path parameters, you need to pass/modify the Mapping template json in the Integration request as per your requirement. The main field to be modified is ‘input’.

Refer 'Note' section in step 3 of [1] and the document [4].

[1] Creating a Step Functions API using API Gateway - https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-api-gateway.html
[2] Creating a Step Functions state machine that uses Lambda - https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-creating-lambda-state-machine.html
[3] StartExecution - Request Syntax - https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html#API_StartExecution_RequestSyntax
[4] Understanding mapping templates - https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html

AWS SAM passing path parameters to state machine triggered by api call

Relevant content