Modifying blueprint features with a front-end wizard

A blueprint selection wizard on CodeCatalyst is auto-generated by the Options interface in the blueprint.ts file. The front-end wizard supports modifications and features of a blueprint's Options using JSDOC style comments and tags. You can use JSDOC style comments and tags to perform tasks. For example, you can select the text displayed above an option, enable features such as input validation, or make an option collapsible. The wizard works by interpreting an abstract syntax tree (AST) generated from the TypeScript type from the Options interface. The wizard configures itself automatically to the type described as best as it can. Not all types are supported. Other supported types include the region selector and environment selector.

The following is an example of a wizard that uses JSDOC comments and tags with blueprint's Options:

export interface Options {
  /**
   * What do you want to call your new blueprint?
   * @validationRegex /^[a-zA-Z0-9_]+$/
   * @validationMessage Must contain only upper and lowercase letters, numbers and underscores
   */
  blueprintName: string;

  /**
   * Add a description for your new blueprint.
   */
   description?: string;

   /**
    * Tags for your Blueprint:
    * @collapsed true
    */
  tags?: string[];
}

The display name of each option of the Options interface appears in camelCase by default. Plain text in the JSDOC style comment is displayed as text above the option in the wizard.

Supported tags

The following JSDOC tags are supported by a custom blueprint's Options in the front-end wizard.

@inlinePolicy ./path/to/policy/file.json

• Requires - Option to be a type Role.

• Usage - Allows you to communicate the inline policies a role needs. The policy.json path is expected to be under source code. Use this tag when you need a custom policy for a role.

• Dependencies - blueprint-cli 0.1.12 and above

• Example - @inlinePolicy ./deployment-policy.json

environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @inlinePolicy ./path/to/deployment-policy.json
       */
      cdkRole: Role[];
    };
   };

@trustPolicy ./path/to/policy/file.json

• Requires - Option to be a type Role.

• Usage - Allows you to communicate the trust policies a role needs. The policy.json path is expected to be under source code. Use this tag when you need a custom policy for a role.

• Dependencies - blueprint-cli 0.1.12 and above

• Example - @trustPolicy ./trust-policy.json

environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @trustPolicy ./path/to/trust-policy.json
       */
      cdkRole: Role[];
    };
   };

@validationRegex Regex expression

• Requires - Option to be a string.

• Usage - Performs input validation on the option by using the given regex expression and displays @validationMessage.

• Example - @validationRegex /^[a-zA-Z0-9_]+$/

• Recommendation - Use with @validationMessage. Validation message is empty by default.

@validationMessage string

• Requires - @validationRegex or other errors to review usage.

• Usage - Displays validation message on @validation* failure.

• Example - @validationMessage Must contain only upper and lowercase letters, numbers, and underscores.

• Recommendation - Use with @validationMessage. Validation message is empty by default.

@collapsed boolean (optional)

• Requires - N/A

• Usage - Boolean that allows a suboption to be collapsible. If the collapsed annotation is present, its default value is true. Setting the value to @collapsed false creates a collapsible section that is initially open.

• Example - @collapsed true

@displayName string

• Requires - N/A

• Usage - Changes option display name. Allows formats other than camelCase for the display name.

• Example - @displayName Blueprint Name

@displayName string

• Requires - N/A

• Usage - Changes option display name. Allows formats other than camelCase for the display name.

• Example - @displayName Blueprint Name

@defaultEntropy number

• Requires - Option to be a string.

• Usage - Appends a randomized alphanumeric string of a specified length to the option.

• Example - @defaultEntropy 5

@placeholder string (optional)

• Requires - N/A

• Usage - Changes default text field placeholder.

• Example - @placeholder type project name here

@textArea number (optional)

• Requires - N/A

• Usage - Converts string input into a text area component for larger sections of text. Adding a number defines the number of rows. The default is five rows.

• Example - @textArea 10

@hidden boolean (optional)

• Requires - N/A

• Usage - Hides file from user unless validation check fails. Default value is true.

• Example - @hidden

@button boolean (optional)

• Requires - N/A

• Usage - Annotation must be on a Boolean property. Adds a button that will synthesize as true when chosen. Not a toggle.

• Example - buttonExample: boolean;

  /**
    * @button
    */
  buttonExample: boolean;

@showName boolean (optional)

• Requires - N/A

• Usage - Can only be used on an account connection type. Shows hidden name input. Defaults to default_environment.

• Example - @showName true

  /**
    * @showName true
    */
  accountConnection: AccountConnection<{
      ...
  }>;

@showEnvironmentType boolean (optional)

• Requires - N/A

• Usage - Can only be used on an account connection type. Shows hidden environment type dropdown menu. All connections default to production. Options are Non-production or Production.

• Example - @showEnvironmentType true

  /**
    * @showEnvironmentType true
    */
  accountConnection: AccountConnection<{
      ...
  }>;

@forceDefault boolean (optional)

• Requires - N/A

• Usage - Uses the default value provided by the blueprint author instead of the value that was used previously by the user.

• Example - forceDeafultExample: any;

  /**
    * @forceDefault
    */
  forceDeafultExample: any;

@requires blueprintName

• Requires - Annotates the Options interface

• Usage - Warns user to add specified blueprintName to project as a requirement for the current blueprint.

• Example - @requires '@amazon-codecatalyst/blueprints.blueprint-builder'

  /*
   * @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
   */
  export interface Options extends ParentOptions {
  ...

Supported TypeScript types

The following TypeScript types are supported by a custom blueprint's Options in the front-end wizard.

Number

• Requires - Option to be a type number.

• Usage - Generate a number input field.

• Example - age: number

{
  age: number
  ...
}

String

• Requires - Option to be a type string.

• Usage - Generate a string input field.

• Example - name: string

{
  age: string
  ...
}

String list

• Requires - Option to be a type boolean.

• Usage - Generate a checkbox.

• Example - isProduction: boolean

{
  isProduction: boolean
  ...
}

Radio

• Requires - Option to be a union of three or fewer strings.

• Usage - Generate a radio selected.

  Note

  When there are four or more items, this type renders as a dropdown.

• Example - color: 'red' | 'blue' | 'green'

{
  color: 'red' | 'blue' | 'green'
  ...
}

Dropdown

• Requires - Option to be a union of four or more strings.

• Usage - Generate a dropdown.

• Example - runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'

{
  runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
  ...
}

Expandable section

• Requires - Option to be an object.

• Usage - Generate an expandable section. Options in the object will be nested inside the expandable section in the wizard.

• Example -

{
     expandableSectionTitle: {
         nestedString: string;
         nestedNumber: number;
     }
}

Tuple

• Requires - Option to be of type Tuple.

• Usage - Generate a key-value paid input.

• Example - tuple: Tuple[string, string]>

{
    tuple: Tuple[string, string]>;
    ...
}

Tuple list

• Requires - Option to be an array of type Tuple.

• Usage - Generate a tuple list input.

• Example - tupleList: Tuple[string, string]>[]

{
  tupleList: Tuple[string, string]>[];
  ...
}

Selector

• Requires - Option to be of type Selector.

• Usage - Generate a dropdown of source repositories or blueprints applied to a project.

• Example - sourceRepo: Selector<SourceRepository>

{
    sourceRepo: Selector<SourceRepository>;
    sourceRepoOrAdd: Selector<SourceRepository | string>;
    blueprintInstantiation: Selector<BlueprintInstantiation>;
  ...
}

Multiselect

• Requires - Option to be of type Selector.

• Usage - Generate a multiselect input.

• Example - multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>

{
  multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>;
  ...
}

Communicating to the user during synthesis

As a blueprint author, you can communicate back to users beyond only validation messages. For example, a space member might view a combination of options that produces a blueprint that isn't clear. Custom blueprints supports the ability to communicate error messages back to users by invoking the synthesis. The base blueprint implements a throwSynthesisError(...) function that expects a clear error message. You can invoke the message by using the following:

//blueprint.ts
this.throwSynthesisError({
   name: BlueprintSynthesisErrorTypes.BlueprintSynthesisError,
   message: 'hello from the blueprint! This is a custom error communicated to the user.'
})