Add input hints in configuration items

The input hints feature enables Deploy plugin developers to guide users through the process of creating complex configuration items. Input hints can provide information such as: drop-down lists with the valid values for a configuration item property or messages that inform a user what type of data is expected in a property.

In the Deploy data model, deployable types are generated automatically based on the format of the deployed types. Deployed types have optional and mandatory properties that require data to be provided in a specific format. The generated deployable types, where the user enters these values, are all treated as optional strings. When the user creates a configuration item (CI) of a particular deployable type, Deploy does not perform input validation on these properties. The user can perform these actions at configuration time:

• Fill in the property with a value in the required format
• Fill in the property with a placeholder, which Deploy will resolve from a dictionary at deployment time
• Leave the property empty, so that a value can be entered at deployment time

When you set up a deployment, Deploy maps each deployable to a target and generates the corresponding deployed. During this process, Deploy validates the values of deployable CI properties. If a deployable CI property contains incorrect data that cannot be used to fill in the corresponding deployed CI property, Deploy returns an error. The input hint feature helps ensure that users provide the correct data for properties when they create deployable CIs, so that these types of errors do not occur at deployment time.

With the input hint feature in the Deploy GUI, users are given guidance during the configuration process to help them specify the correct data before deployment time and resolve potential deployment errors earlier in the process. Input hints help shift the troubleshooting process from deployment time to creation time ensuring CIs are configured correctly and without deployment errors.

important

For a detailed description of deployables and deployeds, see Understanding deployables and deployeds.

Define input hints for CI properties

To define an input hint for a property in a configuration item, add the <input-hint> element in the CI property in the synthetic.xml file. In the <input-hint> add a <rule> element to create a validation rule that is applied to the property. The <input-hint> can be added manually in a deployed or generated in deployables from defining rules on deployeds.

Scenarios for using input hints in CI definitions

With input hinting in CI definitions, you can:

• Validate if a mandatory field matches the expected type or contains a placeholder referencing a dictionary value.
• Provide a drop-down list the with appropriate values when a field is expecting the value of an enum member.
• Issue a warning that a mandatory field is empty. The rule is not enforced because the mandatory field may be entered at deployment time. If left empty, you will be prompted for a value at deployment time.
• Provide a mandatory prefix. Example: Fields that represent an Amazon Resource Name always start with arn:.
• Copy a value used throughout a set of configuration items to other fields. You can consistently use the same name for related properties within a configuration item.

Validation rules in input hints

Example of a deployed definition with a specified rule:

<property name="iAmRoleARN" label="IAM role ARN" kind="string" required="false" category="IAMRole" description="The Amazon Resource Name (ARN) of the IAM instance profile.">
<rule type="regex" pattern="arn:[a-z0-9]{20}" message="ARN should start with arn: and be followed by 20 alphanumerical characters"/>
</property>

The generated deployable becomes:

<property name="iAmRoleARN" label="IAM role ARN" kind="string" required="false" category="IAMRole" description="The Amazon Resource Name (ARN) of the IAM instance profile.">
<input-hint>  
<rule type="regex" pattern="arn:[a-z0-9]{20}" message="ARN should start with arn: and be followed by 20 alphanumerical characters"/>
</input-hint>
</property>

In this example, when the deployable object is saved, the CI property value will be validated against the specified regex pattern. If the validation fails, an error will not be thrown and user will still be allowed to save the deployable. A warning message in the UI will be displayed underneath the related field.

The rules defined on a deployed type will be created on the generated deployable as input hints.

IntegerOrPlaceholder or BooleanOrPlaceholder validation rules

To validate integer fields effectively and early on the deployable, these rules IntegerOrPlaceholder BooleanOrPlaceholder are available in the type system. They are used to validate deployable (string) properties created from (integer/boolean) properties on deployed to ensure the value entered is either a number/boolean or a placeholder which may resolve to a number/boolean.

This will be displayed as a warning. These warning rules will automatically be added to all deployable input hints, derived from integer or boolean type on the related deployeds. You are not required to manually specify this. You cannot specify these rules directly on a property via synthetic.xml as they are internally inferred.

Default validation rules on properties and input hints

Certain validation rules are applied by default on deployed properties within the system. Example: properties with required="true" automatically have a RequiredValidator set on them.

Any default validation rules are automatically copied when creating a generated-deployable out of a deployed. All these rules will be validated when the deployable is saved or updated. Warning messages will be displayed for each of them.

Required attribute in input hints

For a required property in a deployed, the generated deployable has the required attribute stripped out. If you leave this field empty, you will be prompted for a value at deployment time.

Unless otherwise specified, all deployed properties defined in synthetic.xml are required by default. The required attribute for such a property is set in the generated deployable inside the input hint.

Kind attribute in input hints

The kind attributes for non-string primitive type properties in a deployed are currently converted to string in generated deployables.

If a deployed has a input hint specified on it, the kind attribute of the input hint in the deployable will automatically be set to the same value as the kind of the property.

The original kind attribute (string, integer, boolean, and so on) is added to input hint in deployables and is not converted to string.

Enum values in input hint

Enum properties in a deployed are converted to string in the generated deployable. The enum-values are stripped out.

You can provide these enum-values inside the input hint to be passed to the UI. You can use the enum-values to present a list of potential values. Users can also enter other values including placeholders.

Example:

<property name="shutdownBehavior" kind="enum" default="stop" category="Execution" required="false">
    <enum-values>
        <value>stop</value>
        <value>terminate</value>
    </enum-values>
</property>

Possible input values

To provide a set of values for an enum type for a string field which can act as a suggested value and is not strictly enforced, add these to the input hint. These are displayed as drop down suggestions. A user can also enter other values.

Example:

<property name="region" kind="string" description="AWS region to use.">
  <input-hint>
    <values>
        <value label="EU (Ireland)">eu-west-1</value>
        <value label="EU (London)">eu-west-2</value>
    </values>
  </input-hint>
</property>

These values are reflected as an input hint in the generated deployable.

Input hint in type modification

You can override any property's input hint definition through a type modification in the generated deployable.

These are the possible situations:

1. Override input hint information for a field in a derived type. Example: Supply a custom set of value-label suggestions.
2. Provide input hint information for a generated deployable property which should only apply in the deployable and not in the deployed.

Example: The validation rule in the following block will only throw a warning in the aws.ec2.InstanceSpec deployable but will not perform any error validation in the aws.ec2.Instance.

<type-modification type="aws.ec2.InstanceSpec">
    <property name="instanceBootRetryCount" >
        <input-hint>
           <rule type="regex" />
        </input-hint>
    </property>
</type-modification>

This overrides any input-hint metadata added to the property in the original deployed type.

Input hint with property mirroring suggestions

To implement a suggestion box that has the value of another populated form field, the metadata in the synthetic.xml is translated to a JSON payload for the UI.

You can use the property mirroring option to copy a value used throughout a set of configuration items to other fields. You can consistently use the same name for related properties within a configuration item.

Example:

<property name="instanceName" kind="string" description="Name of instance." required="false">
  <input-hint>
    <copy-from-property>name</copy-from-property>
</input-hint>
</property>