Wizard: Types and UI

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 to 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 JSDOC 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 - 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 - 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 - Perform 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 - Display 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 - Change 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 - Append a randomized alphanumeric string of a specified length to the option.
• Example - @defaultEntropy 5

@placeholder string (optional)

• Requires - N/A
• Usage - Change text field default placeholder.
• Example - @placeholder type project name here

@textArea number (optional)

• Requires - N/A
• Usage - Convert 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 - Hide 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 -

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

@showName boolean (optional)

• Requires - N/A
• Usage - Can only be used on an EnvironmentDefinition type. Shows hidden name input. Defaults to default_environment.
• Example -

/**
  * @showName true
  */
environment: EnvironmentDefinition<{
    ...
}>;

To show the environment name in a read only state, use @showName readOnly.

@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
  */
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 -

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

@requires blueprintName

• Requires - Annotates the Options interface.
• Usage - Warns user to apply 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 {
...

@filter regex

• Requires - Annotates the Selector or MultiSelect interface.
• Usage - Filters dropdown in wizard to options matching the specified regex.
• Example - @filter /blueprintPackageName/

 /**
     * @filter /myPackageName/
     */
    blueprintInstantiation?: Selector<BlueprintInstantiation>;
...

Supported TypeScript types

The following TypeScript types are supported 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

{
  name: string
  ...
}

String list

• Requires - Option to be an array of type string.
• Usage - Generate a string list input.
• Example: nameList: string[]

{
  nameList: string[];
  ...
}

Checkbox

• 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 pair input.
• Supported types: Array of 2 types (string or number)
• 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.
• Supported types: Array of 2 types (string or number)
• 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.
• Supported types: SourceRepository, BlueprintInstantiation, SourceRepository | string
• Example - sourceRepo: Selector<SourceRepository>

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

Multiselect

• Requires - Option to be of type MultiSelect.
• Usage - Generate a multiselect input.
• Supported types: string, number, SourceRepository, BlueprintInstantiation
• Example - multiselect: MultiSelect<['A' | 'B' | 'C' | 'D' | 'E']>

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

Region Selector

The region type can be added to your custom blueprint's Options interface to generate a component in the blueprint wizard that allows users to input one or more AWS regions. The region type can be imported from your base blueprint in your blueprint.ts file. For more information, see AWS regions.

JSDOC tags can be added to each field in the Options interface to customize how a field appears and behaves in the wizard. For the region type, the following tags are supported:

• The @displayName annotation can be used to change the field's label in the wizard.
  • Example: @displayName AWS Region
• The @placeholder annotation can be used to change the select/multiselect component's placeholder.
  • Example: @placeholder Choose AWS Region

In your blueprint.ts file, add the following:

import { Region } from '@caws-blueprint/blueprints.blueprint';

The region type parameter is an array of AWS region codes to choose from, or you can use * to include all supported AWS regions.

Example 1: Choosing a region from specified list

blueprint.ts file:

export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Region
   */
  region: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>;
}

Wizard UI:

Example 2: Choosing one or more regions from a specified list

blueprint.ts file:

export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Regions
   */
  multiRegion: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>[];
}

Wizard UI:

Example 3: Choosing one of any AWS region

blueprint.ts file:

export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Region
   */
  region: Region<['*']>;
}

Environment selector

The environment selector renders a selection panel for an AWS account connection. For more information, see Environment components.

Secret definition

The secret definition renders an input for a secret that can be referenced in a workflow. For more information, see Secret component.

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.'
})

It can be used to perform complex validation with code.