Aws-cdk: Step Machine definition lacks proper formatting

[kristianpaul]

The synthesized Cloudformation from of a step-machine cdk definition lacks formatting.

State machine ( AWS::StepFunctions::StateMachine) JSON Strings (DefinitionString) is generated in a single line, new lines characters (\n) and spaces could be added to provide proper visualization in the AWS Console since this is still used to check step-machine execution steps. Been able to visualize the step machine code properly helps the Developer User Experience. Currently this is an undesired outcome.

There is a workaround to fix this and consists in Editing State machine definition and formatting it from the AWS Console.

Reproduction Steps

Create CDK Typescript App with following code:

import * as cdk from '@aws-cdk/core';
import * as sfn from '@aws-cdk/aws-stepfunctions';

export class CdkWorkshopStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const pass = new sfn.Pass(this, 'Pass');

    const step_definition = pass;

    new sfn.StateMachine(this, 'StateMachine', {
      definition: step_definition,
      timeout: cdk.Duration.seconds(30)
    });
  }
}

Comparison

Generated cloudformation resource property for the AWS::StepFunctions::StateMachine type:

DefinitionString: '{"StartAt":"Pass","States":{"Pass":{"Type":"Pass","End":true}},"TimeoutSeconds":30}'

Expected output:

DefinitionString":"{\n \"StartAt\": \"Pass\",\n \"States\": {\n \"Pass\": {\n \"Type\": \"Pass\",\n \"End\": true\n }\n },\n \"TimeoutSeconds\": 30\n}"

Environment

• *CLI Version :1.38.0 (build d5fa31f)*
• Framework Version:
• *OS :Ubuntu 20.04*
• *Language :en*

Other

Side comparison of AWS Console.
Default:

Expected:

*With lager state machine definition the cumbersome is to visualize it in the editor

This is :bug: Bug Report

[nija-at]

Hello @kristianpaul -

Thanks for filing this issue. While this is not a desirable outcome, this is not a bug. We don't expect customers to edit the state machine definition after generating it out of the CDK.
However, this is a reasonable request given that the CloudFormation template we generate is well formatted.

I've re-marked this as a feature request, instead of a bug.

[kristianpaul]

@nija-at Agree. I don't expect customer editing the state machine editor but at least been able to visualize it properly since is there going to be some interaction expected from the AWS Console having the json un-formatted doesn't help much.

[erik-telesoftas]

If you edit state machine in AWS Console there is option to format JSON there.

I would not expect CDK to output formatted JSON, which takes more bandwidth and increases template size.

[kristianpaul]

@erik-telesoftas Your comment is actually described as workaround already as part of the description of this issue.

About the JSON template size isnt your concern applicable when definiting other resources anyway? Whats the difference here?

[erik-telesoftas]

No difference then, just used seeing non-beautified JSON going through the network.
In fact I would expect same for actual templates or at least option to enable compression.
Although that is not focus of this topic, but can be something to consider.

[wong-a]

@kristianpaul By "visualize" you're just referring to viewing the JSON in the Step Functions console, right? Whether the definition is in a single line or pretty-printed has no effect on the rendering of the graph. Pretty-printing the definition without having to edit is something we could add to the Step Functions console.

I don't think the CDK should do this by default for the reasons others already mentioned. State machines and CFN templates have size limits. Existing stacks could exceeded these limits if they became the default. I don't see any concerns in making formatting optional though.

Do you look at the JSON definition in any place besides the console?

[kristianpaul]

Pretty-printing the definition without having to edit is something we could add to the Step Functions console.

Please

I don't see any concerns in making formatting optional though.

That works also. I wouldn’t bother asking for this if I haven’t had to use the console but as of right now I cant easily visualize step function execution by CLI only.

Do you look at the JSON definition in any place besides the console?

Just the console.

[wong-a]

@kristianpaul As an alternative to the console, you can visualize the graph (and format the code) in VS Code using the AWS Toolkit.

See:

• https://aws.amazon.com/blogs/compute/aws-step-functions-support-in-visual-studio-code/
• https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode

[shivlaks]

discussed this with @wong-a earlier today, and I think the issue has been described and summarized nicely already, but I'll recap just in case.

We are going to shoot for improving this experience by formatting the state definition string in the Step Functions console so it's human readable.

This solution will not require CDK customers to make any code changes, upgrade their versions, and most importantly does not run the risk of bloating template sizes beyond their limits.
Optimizing for downstream rendering at the CDK layer is not the right place to address the issue for the reasons mentioned in this thread.

Internal tracking issue: SFNDX-1378

[kristianpaul]

@wong-a I’m fully aware of vscode + aws toolkit capabilities (.asl file creation and visualizing among others) and i don’t see the relation of those features with the cdk feature request described here. Both cdk and vscode + aws toolkit offers their own ways to model aws step functions. I’m not looking to compare or replace each with the other but rather focusing on the usability of resources generated by cdk through the development process of a step function.

[wong-a]

@kristianpaul I understand that and supporting formatting the JSON definition in CDK and the Step Functions console are not mutually exclusive. I suggested the AWS Toolkit only as an alternative to the console for visualizing existing state machines created through the CDK, not as a replacement for creating resources. This was in response to your previous reply.