(aws-events-targets): Allow setting executionName on EventBridge => StepFunctions SfnStateMachine target

[dst-tr]

Describe the feature

Currently, the aws-events-targets.SfnStateMachine target in CDK does not allow setting a custom executionName when triggering a Step Function via EventBridge.

However, the Step Functions StartExecution API does support passing a custom name. This is extremely useful for observability, debugging, and idempotency — especially in recurring scheduled workflows.

In the CDK L2 construct, the SfnStateMachineProps interface does not include an executionName field.

Use Case

• Makes executions easier to track with human-readable names.
• Enables idempotency strategies (using name to dedupe).
• Avoids requiring a proxy Lambda just to pass through custom execution names.

Proposed Solution

Add an optional executionName property to SfnStateMachineProps:

interface SfnStateMachineProps {
  ...
  executionName?: string | events.EventField;
}

This would allow code like:

new events.Rule(this, 'MyRule', {
  schedule: events.Schedule.rate(Duration.minutes(15)),
  targets: [
    new targets.SfnStateMachine(myStateMachine, {
      executionName: "something" + events.EventField.fromPath('$.id'),
      input: events.RuleTargetInput.fromObject({ ... }),
    }),
  ],
});

Other Information

Workaround Today:

Only option is to use a Lambda as a proxy, which defeats the simplicity of direct EventBridge => Step Functions integration.

Acknowledgements

• [ ] I may be able to implement this feature request
• [ ] This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.196.1

AWS CDK CLI version

2.1016.0 (build 66e0b2d)

Environment details (OS name and version, etc.)

Ubuntu 24.04.2 LTS

[pahud]

Hi @dst-tr,

Thank you for this well-structured feature request! You're absolutely right that the AWS Step Functions StartExecution API supports custom execution names, and this capability should be exposed in the CDK's EventBridge targets.

This is a legitimate gap in the SfnStateMachine target implementation. The underlying CloudFormation and AWS APIs support this functionality, but our L2 construct doesn't currently expose it.

Your proposed solution looks correct - adding an optional executionName property that accepts either a string or events.EventField would provide the flexibility needed for both static and dynamic execution names.

The implementation would involve:

1. Adding the executionName property to the SfnStateMachineProps interface
2. Updating the bind() method to pass this parameter to the underlying CloudFormation template
3. Adding appropriate tests and validation

This would be a great contribution to the CDK! The change appears to be non-breaking since it's an optional property.

I am making it a p2 feature request and we welcome PRs!

--

Root Cause Analysis

The root cause is in the SfnStateMachine class implementation:

export interface SfnStateMachineProps extends TargetBaseProps {
  readonly input?: events.RuleTargetInput;
  readonly role?: iam.IRole;
  // Missing: executionName property
}

export class SfnStateMachine implements events.IRuleTarget {
  public bind(_rule: events.IRule, _id?: string): events.RuleTargetConfig {
    return {
      ...bindBaseTargetConfig(this.props),
      arn: this.machine.stateMachineArn,
      role: this.role,
      input: this.props.input,
      targetResource: this.machine,
      // Missing: No way to pass executionName to the underlying CloudFormation
    };
  }
}

The issue is that:

1. The SfnStateMachineProps interface doesn't include an executionName field
2. The bind() method doesn't have logic to handle execution names
3. The underlying CloudFormation AWS::Events::Rule target supports execution names, but the CDK construct doesn't expose this capability

Possible Fixes/Solutions

The implementation would need to:

1. Add executionName to the interface:

   interface SfnStateMachineProps extends TargetBaseProps {
     readonly input?: events.RuleTargetInput;
     readonly role?: iam.IRole;
     readonly executionName?: string | events.EventField;
   }

2. Update the bind() method to handle the execution name in the CloudFormation template generation

3. Add appropriate validation to ensure execution names follow AWS naming constraints

4. Add unit tests to verify the functionality works correctly

The fix would be straightforward since the underlying AWS EventBridge → Step Functions integration already supports this parameter.

[thomaswr]

@pahud Is there actual support for AWS statemachine-specific event target props in Cloudformation? I can't find anything in the docs.

[tmokmss]

As far as I researched, it is currently not possible to set name parameter when calling StartExecution directly from EventBridge. It is a limitation of EventBridge side. Instead we can add Lambda to call StartExecution API.