Configuring Actions Manual Inputs

Manual inputs allow users to add contextual information to an action as it is being invoked. They are defined using YAML markup. The screenshot below shows an example of manual inputs configured for an action that allows a developer to provision an S3 bucket:

The schema supports two root level keys:

	Description
version	The schema version (current version: 1).
inputs	A list of input objects. See the Input Object Schema for more information.

Example configuration (this configuration is the yaml that drives the example screenshot above):

---
version: 1
inputs:
- identifier: bucketName
  required: true
  type: text_input
  displayName: Bucket Name
  description: The name of the S3 bucket that will be provisioned
  maxLength: 20
  defaultValue: my-bucket
  pattern: "^[\\w-]+$" # Note: the escaped backslash.

- identifier: bucketDescription
  required: false
  type: text_area
  displayName: Bucket Description
  description: The description of the S3 bucket that will be provisioned
  placeholder: Enter the description

- identifier: region
  required: true
  type: dropdown
  displayName: AWS Region
  description: The AWS Region that the bucket will be provisioned in
  defaultValue: us-west-2
  values:
    - us-west-1
    - us-west-2
    - us-east-1

Input object schema

All inputs require the following properties:

Property	Required	Description
identifier	true	Define how to reference the input’s value from the action’s context.
label	true	The input title displayed to the invoking user.
type	true	Supported types: `text_input`, `text_area`, and `dropdown`.

The input schema also contains additional optional properties. Whether or not these optional properties are allowed can depend on the value provided to the type property.

Property	Description	`text_input` type	`text_area` type	`dropdown` type
binding	The configuration details for fetching catalog data to populate the values for a dropdown input. Note: exactly one of `binding` or `values` must be set for inputs with `dropdown`type.	❌	❌	✅
defaultValue	The initial value for this input.	✅	✅	✅
defaultValueExpression	A `jq` expression for the initial value of this input. Allows for dynamic default values based on other manual inputs. Note: only one of `defaultValue` or `defaultValueExpression` may be used for a field.	✅	✅	✅
description	Additional information displayed to the invoking user. This field supports Markdown.	✅	✅	✅
maxLength	The invoking user will receive an error if they invoke the action with a value longer than maxLength.	✅	✅	✅
multiple	Indicates the field supports selecting multiple values, if set to true. Defaults to false if not provided.	❌	❌	✅
pattern	The invoking user will receive an error if they attempt to submit an input which does not match this regular expression. Note: Backslashes must be escaped. `\\w` must be written as `\\\\w`.	✅	✅	❌
placeholder	The input placeholder displayed to the invoking user.	✅	✅	❌
required	The invoking user will receive an error if they invoke the action without providing a value to this input.	✅	✅	✅
sensitive	Indicates the field contains a sensitive value (e.g. a password). The value will be obfuscated when executing the action and when viewing the execution history.	✅	❌	❌
values	The select options available to the invoking user. Note: exactly one of `binding` or `values` must be set for inputs with `dropdown`type.	❌	❌	✅
visibilityExpression	A `jq` expression for the visibility of this input. Allows for conditional visibility based on other manual inputs. Fields are visible by default unless `visibilityExpression` is defined and does not evaluate to `true`.	✅	✅	✅

Values Schema

The values array allows for two methods of configuration:

Value only:

values:
- value1
- value2
Value and Display:

values:
- value: value1
  display: display 1
- value: value2
  display: display 2

Binding Schema

The binding option allows the use of catalog data in Actions dropdowns, and replaces manual enumeration of dropdown options. This ensures that dropdown data is in sync with the catalog. The following properties are supported for the binding object.

	Required	Description
resource	true	The named OpsLevel resource used to populate the dropdown items. Supported values: `environments`, `teams`, `systems`, `domains`, and `infrastructure`.
filters	false	An array of filters, each with a `field` key and a `value` key, used to limit the field to a subset of the bound resources. Only valid when `resource` is set to `infrastructure`.

The following filter fields are supported for the infrastructure resource binding:

	Description
provider_resource_type	The type of the resource according to the upstream provider (e.g. "EC2", "RDS", "S3", etc).
source.external_account_id	The account ID of the source integration (e.g. the AWS account ID).
source.type	The type of the source integration (e.g. "AWS", "GCP", etc).
type	The type of the infrastructure resource in OpsLevel (e.g. "Compute", "Database", "File Storage").

Dropdown configuration examples

---
version: 1
inputs:
  - identifier: value_only_example
    displayName: Value Only Example
    description: This input shows a dropdown using value-only configurations
    type: dropdown
    values:
    - us-west-1
    - us-west-2
    - us-east-1
    defaultValue: us-west-2
    required: true
  - identifier: value_and_display_example
    displayName: Value And Display Example
    description: This input shows a dropdown using value and display configurations
    type: dropdown
    values:
    - value: us-west-1
      display: US West 1
    - value: us-west-2
      display: US West 2
    - value: us-east-1
      display: US East
    defaultValue: us-west-2
    required: true
  - identifier: mixed_example
    displayName: Mixed Example
    description: This input shows a dropdown using a mix of value-only and value and display configurations
    type: dropdown
    values:
    - value: us-west-1
      display: US West Primary
    - us-west-2
    - value: us-east-1
      display: US East
    defaultValue: us-west-2
    required: true
  - identifier: binding_example
    displayName: Example using fetched data
    description: This input is populated from teams data from OpsLevel.
    type: dropdown
    binding:
      resource: teams
    required: true
  - identifier: filtered_binding_example
    displayName: Example using filtered fetched data
    description: This input is populated with EC2 instances, from infrastructure data from OpsLevel.
    type: dropdown
    binding:
      resource: infrastructure
      filters:
        - field: provider_resource_type
        - value: EC2
    required: true

Visibility and Default Value Expressions

visibilityExpression and defaultValueExpression must be valid jq expressions. For both expressions, other inputs in the form can be accessed under .manualInputs using their identifiers.

By default, inputs are visible unless visibilityExpression is defined and evaluates to something other than true. defaultValueExpression enables dynamic default values based on other manual inputs. Note that only one ofdefaultValueExpression or defaultValue may be used for a given field.

The example below lets users choose an environment and bucket name. If the user selects Production for the environment, then the default value for region becomes us-east-1 and the Enable Versioning field becomes visible.

---
version: 1
inputs:
  - identifier: environment
    displayName: Environment
    type: dropdown
    values:
      - Staging
      - Production
    required: true
    defaultValue: Staging

  - identifier: bucket_name
    displayName: S3 Bucket Name
    type: text_input
    placeholder: Enter the bucket name
    required: true

  - identifier: region
    displayName: AWS Region
    type: dropdown
    values:
      - us-east-1
      - us-west-1
      - eu-central-1
    defaultValueExpression: |
      if .manualInputs.environment == "Production" then "us-west-1" else "us-east-1" end
    required: true

  - identifier: enable_versioning
    displayName: Enable Versioning
    type: dropdown
    values:
      - "true"
      - "false"
    visibilityExpression: .manualInputs.environment == "Production"
    defaultValue: "true"
    required: true