Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuring Workflow Inputs

Learn how to configure and customize inputs for your Workflow's frontend.

The frontend of Harness IDP workflows can be customized to accept different input fields based on specific requirements. It acts as the entry point where users provide details to run workflows using predefined input parameters.

A well-structured frontend improves the user experience by ensuring the right input types and validations. There are various input types and validation use cases. Let’s explore them in detail.

Define workflow inputs

You can define workflow inputs using the spec.parameters property in your workflow.yaml. Parameters are specified at the beginning of a workflow YAML file and define the inputs required from the user. These inputs allow users to pass values, such as repository names, versions, or other configurable items, that can be referenced throughout the workflow.

YAML syntax

Example YAML

# Example of defining parameters <a href="#example-of-defining-parameters" id="example-of-defining-parameters"></a>
parameters:
  - title: Project Configuration
    properties:
      projectName:
        title: Project Name
        type: string
        description: The name of the new project
      githubRepo:
        title: GitHub Repository
        type: string
        description: The GitHub repository where the project will be initialized
      environment:
        title: Deployment Environment
        type: string
        enum:
          - dev
          - staging
          - production
        description: The environment for deployment

YAML breakdown

  • parameters: This key holds an array of parameter definitions. Each parameter is defined as an object that specifies its title, type, and additional details, such as whether it is required or has specific options like enums (choices).

    • title: The title of the input form displayed in the frontend when prompting the user for input.

    • properties: Defines individual input fields, where each property corresponds to a separate and specific input field.

      • title: The label or name for the parameter input field, shown in the frontend.

      • type: The expected data type of the input. Common types include:

        • string: A free-text input field.

        • number: Accepts numeric values.

        • boolean: A true/false checkbox.

      • description: A brief explanation of the parameter's purpose.

      • required: Indicates whether the input is mandatory.

      • enum: A list of predefined options the user can choose from, useful for fields like deployment environments (e.g., dev, staging, production).

      • ui:widget: Specifies the UI element used for input (e.g., text field, dropdown).

Customize workflow header and button text

You can customize the workflow's header title, subtitle, and the create button text to provide a more personalized and context-specific experience for users. This is done using the spec.presentation property in your workflow.yaml.

YAML syntax

Configuration options

  • customTitle: Customizes the main title/header displayed at the top of the workflow form. This replaces the default workflow title.

  • customSubTitle: Adds a descriptive subtitle below the main title to provide additional context about the workflow's purpose.

  • customCreateButtonText: Changes the text on the workflow creation/execution button (e.g., from the default "Create" to "Deploy Now", "Launch", "Submit", etc.).

These customizations help make your workflows more user-friendly and aligned with your specific use case terminology.

Input types

Here are the different ways to design form inputs in IDP workflows:

Static inputs

Static inputs are fields where users manually enter their details as defined in the frontend. These inputs come in various types:

  • string – Single-line text input

  • textarea – Multi-line text input

  • number – Numeric input

  • boolean – Checkbox (true/false)

  • enum – Dropdown selection from a predefined list

  • array – List of values (e.g., strings, numbers)

  • object – Key-value pair inputs

  • password – Masked input for sensitive values

Dynamic inputs

Dynamic inputs are fields that automatically retrieve data from external sources or runtime context, eliminating the need for manual entry.

  1. Harness-Specific UI Pickers

    • HarnessOrgPicker – Select a Harness organization

    • HarnessProjectPicker – Select a Harness project

    • HarnessAutoOrgPicker – Auto-populate organization based on project selection

    • HarnessUserGroupPicker – Select a Harness user group with filtering options

    • HarnessOwnerPicker – Select an owner (Group or User) from the catalog

  2. Standard Workflow UI Picker

    • Entity Picker – Select an entity from the catalog

    • Owner Picker – Select a user or group

    • Repository Picker – Choose a repository from a version control provider

  3. API Based Dynamic Workflow UI Picker

    • Dynamic API Picker – Fetch options dynamically via an API request

    • Autocomplete Fields – Suggestions based on previous inputs or external data fetched using Dynamic API Picker.

  4. CustomField Component

    • CustomField – A single schema-driven field for text, dropdown, button, and JSON inputs, with optional API integration, validation, and form context wiring. Recommended for new workflows.

Workflows playground

The Workflows Playground does not render accurate previews for advanced user inputs and complex use cases such as conditional fields or complex input formats. It is recommended to use the editor only for lightweight input previews. For accurate validation of advanced inputs, test the Workflow Form Inputs in an actual Workflow execution.

Harness IDP also provides a built-in editor to help you build your Workflow's Frontend. It offers a real-time preview of the corresponding UI based on the YAML definition. Here, you can create a new workflow or edit an existing one. '

Note: The editor is for preview purposes only; changes made here cannot be saved. Once you have tested the modifications, you must manually copy the updated YAML and add it to the Workflow definition YAML stored in your Git provider.

For more information on accessing the Workflow Playground, check out the details here.

Input examples

Simple text input

Basic input

Basic form inputs allow users to enter structured data while ensuring it meets predefined rules. You can enforce limits such as character counts, patterns, and UI hints to guide users in filling out the form accurately.

Example workflow.yaml

This example demonstrates a simple text input field with:

  • A title and description for clarity.

  • A maximum length constraint (maxLength: 8).

  • A regex pattern validation (pattern) to enforce naming rules.

  • UI enhancements like autofocus and helper text.

Example YAML

Multi-line text input

Multi-line text inputs are useful for capturing larger blocks of text, such as descriptions, configuration snippets, or scripts. This example demonstrates how to use a textarea widget to enable multi-line input, with additional UI options for better usability.

Example workflows.yaml

This configuration includes:

  • A textarea widget (ui:widget: textarea) for multi-line input.

  • Custom row height (ui:options: rows: 10) for better visibility.

  • A placeholder example showcasing a shell script.

  • Helper text (ui:help) to guide users.

Example YAML

Array options

Array inputs allow users to provide multiple values, either as strings, numbers, or complex objects. These can be structured to ensure uniqueness, predefined options, or flexible custom objects.

Array with strings

You can add an array to the workflow with string values, allowing users to select one option when filling out the workflow.

Example workflows.yaml

Array with distinct values

Values mentioned under enum needs to be distinct, duplicate values are not allowed under enum.

Example YAML
Arrays With Distinct Values

Array with duplicate values

Allows multiple values, including duplicates, by using enumNames to provide user-friendly labels.

Example YAML
Arrays With Duplicate Values

A multiple choices list with checkboxes

Users can select multiple predefined values from checkboxes.

Key Features:

  • Supports multiple selections

  • Uses checkbox UI for easy selection

  • Ensures unique selections with uniqueItems: true

Example workflows.yaml

Example YAML

Array with custom objects

This allows users to enter an array of complex objects, each containing multiple fields. It supports adding, removing, and reordering objects dynamically.

Example workflows.yaml

A user needs to provide a list of configurations, each containing:

  • A dropdown selection (array)

  • A boolean flag (flag)

  • A free-text input (someInput)

Example YAML

Comparison table of array input types

The table compares array input types based on key features:

  • Distinct Values: Dropdowns ensure unique values, checkboxes allow duplicates.

  • Duplicate Values: Checkboxes support duplicates, dropdowns do not.

  • Multiple Choice: Checkboxes and custom arrays allow multiple selections, dropdowns do not.

  • Custom Objects: Only custom object arrays support complex data.

  • User-friendly Labels: Checkboxes and custom arrays can have labels, dropdowns cannot.

Feature
Distinct Values
Duplicate Values
Multiple Choice List
Custom Object Array

Dropdown Selection

✅

✅

❌

❌

Checkbox UI

❌

❌

✅

❌

Allows Multiple Selections

❌

❌

✅

✅

Supports Complex Objects

❌

❌

❌

✅

User-friendly Labels (enumNames)

❌

✅

❌

✅

Pass an array of inputs to a Harness pipeline

Harness Pipelines only support three variable types:

  • String

  • Number

  • Secret

This means that arrays cannot be directly passed as pipeline inputs. Instead, if you need to pass multiple values, you should convert the array into a comma-separated string using join in Nunjucks.

  • Use Case: You want users to select multiple values from a enum list, and then pass those values as a single comma-separated string into the Harness Pipeline’s inputset.

  • How It Works:

  1. User selects multiple options from an enum list (Option1, Option2, Option3).

  2. The selected options are joined into a single string using parameters.exampleVar.join(',').

  3. The pipeline receives the values as a single string, ensuring compatibility with Harness’ input format.

Boolean options

Boolean inputs allow users to select between true/false or yes/no values in forms. These inputs are useful for enabling/disabling features, selecting configuration options, and making binary choices.

Basic boolean (checkbox input)

A simple checkbox allows users to toggle a setting on/off.

Boolean yes or no options (radio button)

Instead of a checkbox, you can use radio buttons for a clearer Yes/No selection.

Boolean multiple options

For cases where multiple boolean choices are needed, you can use an array of checkboxes.

Example YAML

When to use each boolean input type

Input Type

Best Use Case

Example Scenario

Checkbox Boolean

Single feature toggle

Enable/Disable Dark Mode

Radio Button Boolean

Explicit Yes/No choice

Confirming a deletion

Multi-Select Boolean

Selecting multiple options

Enable multiple monitoring features

Workflow UI pickers

For new workflows, consider the CustomField component instead. It covers text, dropdown, button, and JSON inputs from a single field extension, and it is validated against a type-safe schema. The pickers documented below remain fully supported.

User input is a crucial aspect of Workflows. However, built-in components and fields may not always meet specific requirements, and at times, you may want to enhance the form with more intuitive and tailored inputs.

This is where Workflow UI Pickers come in.

Harness specific UI pickers

1. EntityFieldPicker (fetch values from catalog)

The EntityFieldPicker can be used to fetch information for workflows that are already defined in the catalog, such as data under metadata.annotations.

Only string data type is supported for the EntityPicker.

The input props that can be specified under ui:options for the EntityFieldPicker field extension.

displayField

This is used to fetch the value from catalog dynamically, corresponding to the key mentioned.

In the above example it will fetch all the jiraProjectId for the software components kind mentioned under catalogFilter.

allowArbitraryValues

Whether to allow arbitrary user input. Defaults to true.

allowArbitraryValues provides input validation when selecting an entity as the values you enter will correspond to a valid entity.

  • Adding a valid entity with allowArbitraryValues as false

  • Adding an arbitrary entity with allowArbitraryValues as true (default value)

catalogFilter

catalogFilter supports filtering options by any field(s) of an entity.

  • Get all entities of kind Group

  • Get entities of kind Group and spec.type team

defaultKind

The default entity kind.

defaultNamespace

The ID of a namespace that the entity belongs to. The default value is default.

  • Listing all entities in the default namespace (default value)

2. HarnessOrgPicker

Fetches all the organization, under the account dynamically.

3. HarnessProjectPicker

Fetches all the Harness project ID, available in the account dynamically

4. HarnessAutoOrgPicker

It autopopulates org ID on project selection. So now when you select a project ID as an input the org ID gets selected automatically if required as an input.

  1. For HarnessAutoOrgPicker to work, it is suggested to name the Project Identifier under Properties as projectId and using the HarnessProjectPicker.

  1. In case the properties Project Identifier is named something else other than projectId in that case for the Workflow action to function as desired we need to add it as a dependency under projectPickerRef

5. HarnessUserGroupPicker

The User Group Picker allows template users to select a Harness user group from a dropdown list. The list can be filtered based on organization, project, and the current user's memberships.

filterByUserMembership

When set to true, only shows user groups where the logged-in user is a member. Defaults to false.

includeChildScopes

When set to true, includes user groups from child scopes (e.g., project-level groups when viewing at org level). Defaults to false.

Dependencies with organization and Project pickers

The user group list updates automatically when the user selects an organization or project using dependencies:

additionalScopes

Fetch user groups from the current scope plus additional organizations or projects. Each entry can specify orgIdentifier, projectIdentifier, and includeChildScopes.

6. HarnessOwnerPicker

The Owner Picker allows template users to select an owner (typically a Group or User) from the Backstage catalog. It can filter by the current user's memberships and supports custom values.

filterByUserMembership

When set to true, only shows groups/users where the logged-in user is a member. Defaults to false.

catalogFilter

catalogFilter supports filtering options by any field(s) of an entity.

  • Get all entities of kind Group

  • Get entities of kind Group and spec.type team

defaultNamespace

Default namespace for entities. Entities in this namespace will not show namespace prefix.

Other UI pickers

1. OwnerPicker

OwnerPicker is used for developers to pick a User Group from the list of Groups that exist in the account.

allowArbitraryValues

Whether to allow arbitrary user input. Defaults to true.

allowArbitraryValues provides input validation when selecting an owner as the values you enter will correspond to a valid owner.

  • Adding a valid owner with allowArbitraryValues as false

  • Adding an arbitrary owner with allowArbitraryValues as true (default value)

catalogFilter

catalogFilter supports filtering options by any field(s) of an entity.

  • Get all entities of kind Group

  • Get entities of kind Group and spec.type team

defaultNamespace

The ID of a namespace that the owner belongs to. The default value is default.

  • Listing owners in the default namespace (default value)

  • Listing owners in the payment namespace

2. EntityPicker

Only string data type is supported for the EntityPicker.

The input props that can be specified under ui:options for the EntityPicker field extension.

allowArbitraryValues

Whether to allow arbitrary user input. Defaults to true.

allowArbitraryValues provides input validation when selecting an entity as the values you enter will correspond to a valid entity.

  • Adding a valid entity with allowArbitraryValues as false

  • Adding an arbitrary entity with allowArbitraryValues as true (default value)

catalogFilter

catalogFilter supports filtering options by any field(s) of an entity.

  • Get all entities of kind Group

  • Get entities of kind Group and spec.type team

defaultKind

The default entity kind.

defaultNamespace

The ID of a namespace that the entity belongs to. The default value is default.

  • Listing all entities in the default namespace (default value)

3. MultiEntityPicker

The input props that can be specified under ui:options for the MultiEntityPicker field extension.

allowArbitraryValues

Whether to allow arbitrary user input. Defaults to true.

allowArbitraryValues provides input validation when selecting an entity as the values you enter will correspond to a valid entity.

  • Adding a valid entity with allowArbitraryValues as false

  • Adding an arbitrary entity with allowArbitraryValues as true (default value)

catalogFilter

catalogFilter supports filtering options by any field(s) of an entity.

  • Get all entities of kind Group

  • Get entities of kind Group and spec.type team

defaultKind

The default entity kind.

defaultNamespace

The ID of a namespace that the entity belongs to. The default value is default.

  • Listing all entities in the default namespace (default value)

  • Listing all entities in the payment namespace

Repository picker

To simplify working with repository providers, we’ve built a custom picker that can be used by overriding the ui:field option in the uiSchema for a string field. Instead of displaying a standard text input, this picker renders a custom component that allows users to easily select a repository provider and enter details like project/owner and repository name.

You can see this in the full example , where it appears as a separate step and looks something like this:

The allowedHosts part should be set to where you wish to enable this Workflow to publish to. And it can be any host that is listed in your integrations config in app-config.yaml.

Besides specifying allowedHosts you can also restrict the Workflow to publish to repositories owned by specific users/groups/namespaces by setting the allowedOwners option. With the allowedRepos option you are able to narrow it down further to a specific set of repository names. A full example could look like this:

For a list of all possible ui:options input props for RepoUrlPicker, visit here.

Use the users oauth token

There is a little extra magic that you get out of the box when using the RepoUrlPicker as a field input. You can provide some additional options under ui:options to allow the RepoUrlPicker to grab a oauth token for the user for the required repository.

This is great for when you are wanting to create a new repository, or wanting to perform operations on top of an existing repository.

A sample Workflow that takes advantage of this is like so:

Example YAML

You will see from above that there is an additional requestUserCredentials object that is passed to the RepoUrlPicker. This object defines what the returned secret should be stored as when accessing using ${{ secrets.secretName }}, in this case it is USER_OAUTH_TOKEN. And then you will see that there is an additional input field into the publish:github action called token, in which you can use the secret like so: token: ${{ secrets.USER_OAUTH_TOKEN }}.

There is also the ability to pass additional scopes when requesting the oauth token from the user, which you can do on a per-provider basis, in case your Workflow can be published to multiple providers.

Note, that you will need to configure a connector for your source code management (SCM) service to make this feature work.

Conditional inputs

Workflows support dynamic parameter handling using conditional logic. You can control how inputs are assigned based on specific conditions, allowing for greater flexibility in user selections and workflow execution.

Conditionally set parameters

You can use the if keyword within a parameter to apply conditional logic using Nunjucks templating. Since the not keyword is unavailable, use JavaScript-style equality instead.

Example: If parameters.branchName is set, use its value; otherwise, append a timestamp to a default name,${{ parameters.branchName if parameters.branchName else appendTimestamp("default-branch-name-") }}

These conditionals could be used only under steps

Example YAML

Use parameters as conditional for fields

Example YAML

  1. One Of: Helps you create a dropdown in the Workflow, where only one of all the options available could be selected.

Example workflows.yaml

Example YAML

  1. All Of: Helps you create a dropdown in the Workflow, where only all the options available could be selected.

Example workflows.yaml

Example YAML

  1. Any Of: Helps you to select from multiple properties where both cannot be selected together at once.

Example workflows.yaml

Example Workflow Explained

  1. Parameters Structure The parameters section includes age as an integer and items as an array. Each item in the array can contain either a foo or bar property, utilizing anyOf.

  2. Identification Methods The Workflow allows for two methods of identification using anyOf. Users can provide either:

  • A first name and last name (defaulting firstName to "Chuck"), or

  • An ID code.

  1. Required Fields The age field is required, while the fields under the two identification methods are optional but must comply with the anyOf logic.

  2. Display Step The steps section includes a debug:log action to display the collected information based on the provided input.

Example YAML

Advanced use-cases

Usage of dependencies and reusable references.

Example YAML

Example workflows.yaml

The workflow defines an Infrastructure Provisioning setup with parameters, within infracomponent, the resource_type field is defined. The dependencies section ensures that, if resource_type is either s3 or vpc, an additional field Operationtype (referenced from myregion/operation) is required.

What Happens Here?

  • If a user selects s3 or vpc, then Operationtype must also be provided.

  • The dependencies field ensures Operationtype is only required when resource_type is s3 or vpc.

  • The use of $ref: "#/myregion/operation" allows referencing another part of the YAML file, ensuring DRY (Do not Repeat Yourself) principles.

  • Users only see the relevant fields based on their selections.

Understand dependencies usage and indentations

The dependencies keyword specifies conditional relationships between fields. When a field depends on another, its presence or properties change based on the value of the controlling field.

Structure of dependencies:

Things to take care of:

  1. Ensure dependencies is at the same level as properties.

  2. Inside oneOf, allOf, or anyOf, indent properties and required correctly.

  3. Each field inside dependencies should align with its controlling field.

For more such references and validate your conditional steps take a look at the react-json schema project.

Advanced input configurations

Upload a file using workflows

Workflow supports a limited form of file types as input, in the sense that it will parse the file contents to Workflow inputs as data-urls.

There are 3 types of file upload.

  1. Single File: There are two formats available data-url and file.

  2. Multiple Files: Multiple files selectors are supported by defining an array of strings having data-url as a format.

  3. Single File with Accept Attribute: You can use the accept attribute to specify a filter for what file types the user can upload.

Large file upload support

IDP Workflows support uploading files up to 16MB in size. This allows you to upload larger configuration files, datasets, or other resources that your workflow may need to process. Files larger than 16MB cannot be uploaded and will be rejected by the system.

Example YAML

Hide the uploaded file contents in workflow review page

When you upload a file in Workflows, you can see the base-64 encoded content of the file on the review page, to hide them you can use ui:backstage.

Example workflow.yaml

How to use the contents of the file uploaded

Files uploaded to workflows are automatically encoded in base64 format. To use the contents of an uploaded file, the base64-encoded data must first be decoded. This can be achieved using the Run Step in IDP stage.

  1. Start with a Run Step in IDP stage, write a script in the step to:

  • Extract the base64-encoded content from the uploaded file.

  • Decode the content back to its original format.

  1. Process or utilize the decoded content as needed in the steps that follow.

Without decoding, the uploaded file contents cannot be directly used.

Here is an example harness pipeline that uses PowerShell in run step to decode the content of the file uploaded to Workflows.

Use secrets

You may want to mark things as secret and make sure that these values are protected and not available through REST endpoints. You can do this by using the built-in ui:field: Secret and ui:widget: password.

ui:widget: password needs to be mentioned under the first page in case you have multiple pages.

You can define this property as any normal parameter, however the consumption of this parameter will not be available through ${{ parameters.myKey }} you will instead need to use ${{ secrets.myKey }} in your workflow.yaml.

Parameters will be automatically masked in the review step.

Example YAML

Pre-fill workflows with URL params

We can now automatically load IDP Workflow forms pre-filled using the formData URL query parameter. e.g.: https://app.harness.io/ng/account/account_id/module/idp/create/templates/default/a-python-lambda?formData=%7B%22project_name%22%3A%22auto%20filled%22%7D

The query parameters ?formData=%7B%22project_name%22%3A%22auto%20filled%22%7D in the end of the URL allow you to automatically fill in values of the form. See the below table for explanation of individual tokens in the query param.

Item
Example Value
Explanation

formData

formData

Key of the query param.formData object is used to fill out IDP Workflow forms.

{"key"%3A"value"}

{"title"%3A"Title from query params"}

Value of the query param. A JSON object with invalid URL characters encoded.: encodes to %3A

Add read only fields

Using automatically filled out values is handy when wanting to direct users to use IDP Workflows with known good values. This also allows automation to be constructed around the Workflows, where the automation can provide fully constructed IDP URLs to the user. You can also prevent user from modifying the form values inserted from query params by making the form fields readonly. See below example of a minimal form which would be filled using query params defined in the above explanation.

Example YAML

For use cases not listed here

For scenarios not covered in this guide, it is recommended to use the react-jsonschema-form playground to design the UI for input fields. Additionally, Nunjucks serves as the templating engine for Self-Service Workflows.

PreviousCreate Workflow YAML
NextSetup Harness IDP Pipeline

Last updated

Was this helpful?