Adding user activities

Edit online

A user activity consists of one or more chat-based interactions to collect input and display results within an agentic workflow. It supports mid-flow interaction, allowing users to view and respond to information directly in the chat interface. Examples include approving a request, choosing from a list, answering follow-up questions, or reporting an issue.

To add a user activity to an agentic workflow:

In the workflow builder, click add flow items .
From the Flow nodes, click and drag User activity onto a connector line.

For an example video on how to add user activities, see "Building an agentic workflow with user activities in watsonx Orchestrate" in Videos.

Adding interactions

You can use interactions to collect information from the user or display information to the user in the chat or within a form. Interactions can appear in multi-turn user activities or inside forms. The type of interaction that you choose determines the UI widget that is displayed to the user.

Available interaction types

The following table summarizes all interaction types, the experiences that they support, and the UI widget that is displayed to the user.


Interaction type	Description	Available in	UI widget
Boolean choice	Collect yes or no response	Multi-turn and form	Multi‑turn: pills (buttons); Form: checkbox or radio button
Single choice	Collect one option from a list	Multi-turn and form	Dropdown list or table
Multi choice	Collect multiple selections	Form	Dropdown list or table
Text	Collect a text input	Multi-turn and form	Text field
Number	Collect a numeric input	Multi-turn and form	Number field
Date	Collect a date input	Multi-turn and form	Date picker
Date range	Collect a start date and end date	Form	Date‑range picker
File upload	Collect one or more files	Multi-turn and form	File upload control
List (input)	Collect multiple user‑entered values	Form	Table
List (output)	Display a list of values	Multi-turn and form	Bullet point list or table
Message	Display a text message	Multi-turn and form	Plain text, Markdown, or HTML
File download	Display a downloadable file	Multi-turn and form	Download link
Field	Display a single value in a form	Form	Field

This summary provides a unified view of interaction types across multi‑turn interactions and forms, and it helps you understand the UI widget that is displayed for each type.

Tip:

Files that are uploaded to a form are not deleted, and there is currently no mechanism to automatically remove them after a specific time period. You cannot access previously uploaded files in any form, either through the API or through the UI. Access to the file itself also has a signature expiration time, which prevents long‑term availability of the download URL.

Adding multi-turn interactions

To add a multi‑turn interaction to your user activity:

Click the connector line in the user activity.
Select Collect from user to collect information. You can choose from the following interaction types:

Boolean choice, Date, File upload, Number, Single choice, and Text.
Select Present to user to display information. You can choose from the following interaction types:

File download, List, and Message.

For message interaction, if you want braces to appear as plain text, escape them with double braces. For example, {{customer_id}} is displayed as {customer_id} in the output message, and the text inside the double braces is treated as plain text, not as a variable.

Adding form-based interactions

Forms support the same interaction types as multi‑turn interactions. They also include some interaction types that are available only in forms, such as multi‑select and list input. You can add these interactions by selecting Collect from user or Present to user while you are setting up the form fields.

For detailed steps on how to configure each field type, see the sections under Collect from user and Present to user in the Forms documentation.

In addition to field level interactions, forms support Dynamic rules that control how fields behave based on user input. Dynamic rules allow you to show or hide fields, change field labels, or populate field values dynamically as users complete the form. For information about dynamic rules and dynamic form behavior, see Dynamic forms.

Editing interactions

To edit an interaction in your user activity:

Click the interaction.
Hover over the name and click edit .
Enter the new name and press enter.

Deleting interactions

To delete an interaction in your user activity:

Click the interaction.
Select delete .

Tip:

The title of this node is displayed to the user in the chat.

Configuring variables for interactions

To configure variables for Collect from user interactions:

Configure a Single choice interaction node to collect single choice input from user.

Click the variable and choose the variable to collect single choice input from user. To create a custom choice, you can click the expression and enter a Python expression that returns the choices for the user to select.

To configure variables for Display to user interactions:

Configure a Text interaction node to display a text in the chat.
1. Enter the text to display in the Output message. If you want to include a value from a variable in your message, click variable , select the variable from the list.
Configure a List interaction node to display a list in the chat.
1. Click the Select source field.
2. Click the variable and choose the variable that provides the list of values to display in the chat. To create a custom list, you can click the expression and enter a Python expression that produces a list.
Configure a File download interaction node to display a downloadable file in the chat.
1. Click the Select source field.
2. Click the variable .
3. Select a variable that provides the file to be downloaded.

Forms in user activities

You can use forms in user activities to collect and present multiple pieces of information within a single turn of the conversation. For example, in an agentic workflow to book a flight, a form can collect travel dates, destinations, class preferences, and other details. The chat can then display a list of available flights based on the user's input.

Adding forms

To add a form to a user activity in an agentic workflow:

Click the connector line in the user activity.
Select Add a form. A dialog to add a form is displayed.

Click and enter the name of the form. By default, in the General settings for the form, the Instructions toggle switch, which is used to add instructions that are displayed in a chat for the user, is set to off. If you prefer to provide any instructions to the user, set the switch to on.
In the Primary action section, you can configure the Primary action button for the form.
- The Primary action button represents the main user action to complete the form. By default, the primary action is Submit, and you can rename it as needed.
In the Additional actions section, you can add more action buttons for the form.
- To provide more than one completion action, select the Add additional action button in the Additional actions field. An input field is displayed where you can enter a name for the additional action.
- Each Additional action button creates a separate branch in the workflow, which is displayed under the form as separate paths labeled with the action names, alongside the existing primary action branch.
- You can add flow items to each additional‑action branch to define the workflow logic for that action.
- You can add up to three additional action buttons to a form. When more than one additional action is defined, the buttons are grouped into an Actions drop-down on the form.
In the Cancel section, you can configure the Cancel button for the form.
- You can enter text to rename the Cancel button.
- To remove the Cancel button from the form, set the toggle switch to off.
Hover over the Add field or the Add icon , then select Collect from user or Present to user to add fields (user interaction types) to the form.

You can add fields to collect information from users, present information to users in a chat, and define dynamic rules to control how fields behave based on user input. For more information, see Collect from user, Present to user and Dynamic forms.

Collect from user

To collect information from users in a form, you can add any of the following fields:

Boolean

Boolean options allow a user to specify a boolean option in a chat. You can add boolean fields to a form to pass user-specified data to downstream nodes, which are then used by the agentic workflow. To add a boolean field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Boolean.
In General > Label, enter the text for this field that is displayed to a user in a chat.
In Appearance > Display as, select how the boolean fields are displayed in a chat either as a single checkbox or as radio buttons.
In the True label and False label options for radio buttons, you can modify the text that is displayed to a user in a chat for the boolean options.
In Behavior, you can specify an initial value for the boolean field by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

If you want to specify an initial value for true or false, close auto-mapping and specify a value.

A boolean field is now added to your form. The following example shows how it is displayed in the chat.

Boolean toggle

Date/Time

You can add a date and time field to a form to collect a date, time, or both. This field supports workflow scenarios such as selecting start dates, end dates, due dates, or reminder times. The value that the user selects in the chat is captured and used by the agentic workflow.

To add a date and time field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Date/Time.
In General > Label, enter the text that is displayed to the user in the chat.

Set the Multiple dates switch to on to allow users to select more than one date. Otherwise, set the switch off. The Multiple dates option is available only when the input type is Date.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.
In Input type, select the type of input you want to collect. You can choose Date, Time, or Date and Time, depending on the value that the user must provide.
In Behavior, set the Initial value switch to on to define a default value for the date or time field. You can set the initial value by using a variable or an expression for all input types. If the input type is Date, you can also use auto mapping. Users can accept or modify the initial value in the chat.
In Behavior, set the Input range switch to on to define the valid range for the date, time or date and time field. The start and end fields change based on the selected input type. You can define the start and end values by using a variable or an expression for all input types. If the input type is Date, you can also use auto mapping.

Date

Date/time range

You can add a date and time range field to a form so that a user can specify a start value and an end value in a chat. The range type can be either a date or a time. These user‑provided values can be used by the agentic workflow for scenarios such as time‑off requests, scheduling, or any workflow that requires a defined range.

To add a date and time range field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Date/Time range.
In General > Label, enter the text that is displayed to the user in the chat.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.
In Range type, select the range that the user must provide. You can choose Date or Time, based on the value the user needs to provide.
In Appearance, enter labels for the start and end fields that are displayed to the user in the chat. The available label fields depend on the selected range type.
In Behavior, set the Initial value switch to on to define the default start and end values for the date or time field.You can set the start and end values by using a variable or an expression for all range types. If the range type is Date, you can also use auto‑mapping. Users can accept or modify the initial values in the chat.
Set the Date range limits or Time range limits switch to on to define the valid range for the date or time field. The start and end fields change based on the selected range type. You can define the start and end values by using a variable or an expression for both range types. If the range type is Date, you can also use auto‑mapping.

A date and time range field is now added to your form. The following example shows how the date range field is displayed in the chat.

Date range

File upload

You can add a file upload field to a form. This field is useful for agentic workflows where users can upload files in a chat such as for document processing, collaboration, generating summaries, and others.

To add a file upload field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select File upload.
In General > Label, enter the text for this field that is displayed to a user in a chat.

To allow multiple file uploads, set the Allow multiple files switch to on. To make this field selection mandatory in a chat, set the Required switch to on.
In Appearance > Instructions, you can either enter instructions to help user upload files or click Generate instructions to auto-generate instructions based on the file size and file type selections in Behavior.

In the Button label option, you can specify a label for the file upload field.
In Behavior, you can specify the supported file types that the user can upload and the maximum file size limit.

If the Allow multiple files switch is on, you can specify the file upload limits. To specify the file upload limits, set the File upload limits switch to on, and enter the minimum and maximum number of files.

A file upload field is now added to your form. The following example shows how it is displayed in the chat.

File upload

List

You can add a list field to a form when you need to collect a list of information from a user. List items can either be primitive data types, such as strings or dates, or object data types, such as flight details.

To add a list field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select List.
In General > Label, enter the text for this field that is displayed to a user in a chat.
In the Source variable, you can specify a source for the list by using a variable or expression.

If you specify a source variable that is a list of objects, then you can choose to display the data as a table. In the Appearance section, click Edit elements to configure how the list elements are displayed to users. When you click Edit elements, a dedicated dialog opens where you can manage the elements.

In the Edit elements, you can:
- Reorder elements: Drag the to change the display order.
- Control visibility: Click the Visibility icon to hide individual elements.
- Edit labels: Modify the text in the Element label column to customize how each element appears to users.
- Tidy labels: Click Tidy labels to automatically format all labels.
- Reset labels: Click Reset labels to restore all labels to their original values from the source variable.
In the Behavior section, you can configure how users can interact with list.

Set the Allow addition switch to on if you want users to add items to the list. Set the Allow deletion switch to on if you want users to remove items from the list.

Multi choice

You can add a multi-choice field to a form for collecting more than one option from a list in a chat. The user-specified options are then used by the agentic workflow. This field is useful for agentic workflows where users can select multiple options in a chat such as several departments for a report, multiple categories for a task, and others.

To add a multi-choice field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Multi choice.
In General > Label, enter the text for this field that is displayed to a user in a chat.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.
In Source variable, you can specify a source for the list by using a variable or expression.

If you specify a source variable that is a list of objects, which defines data, then you can choose to display the data as a drop-down list or as a table. To choose a display type, in Appearance > Display as, select Dropdown or Table.

If you select the Dropdown option, Set the display name for each list item in the list by using a variable or an expression.

If you select the Table option, click Edit columns to configure how the columns are displayed to users. When you click Edit columns, a dedicated dialog opens where you can manage the elements.

In the Edit elements, you can:
- Reorder elements: Drag the to change the display order.
- Control visibility: Click the Visibility icon to hide individual elements.
- Edit labels: Modify the text in the Element label column to customize how each element appears to users.
- Tidy labels: Click Tidy labels to automatically format all labels.
- Reset labels: Click Reset labels to restore all labels to their original values from the source variable.
  
  In the Placeholder text option, you can also specify the text that is displayed to the user when the drop-down list is empty.
In Behavior, you can specify an initial value for the list by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value. You can also specify

If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

To limit how many items a user can select in the list, specify the minimum and maximum number of choices by using the Choice limit option. For example, specify the choice limits when a user must select a minimum of 2 items and a maximum of 5 items.

A multi choice field is now added to your form. The following example shows how it is displayed in the chat.

Multi choice

Number

You can add a number field to a form for collecting numeric input from users in a chat. The numeric input is then used by the agentic workflow. For example, users can specify ticket IDs, item quantity, number of days, and others in a chat.

To add a number field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Number.
In General > Label, enter the text for this field that is displayed to a user in a chat.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.
In Input type, specify either the integer or decimal type for the number.
In Appearance, you can add the helper text for the number field. Set the Helper text switch to on to add helper text. Otherwise, set the switch to off.
In Behavior, you can specify an initial value for the number by using a variable, expression, or auto-mapping options. Set the Initial value switch to on to add an initial value. Otherwise, set the switch to off. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

You can also specify a range for the number field, for example, a user can pick a number between 10 and 20. To add a range, set the Input range switch to on. Otherwise, set the switch to off. You can specify the minimum value and maximum value for a range by using a variable, expression, or auto-mapping options. To specify a particular value to use as the minimum or maximum value, close auto-mapping and enter the value.

A number field is now added to your form. The following example shows how it is displayed in the chat.

Number

Single choice

You can add a single-choice field to a form for collecting an option from a list in a chat. The user-specified option is then used by the agentic workflow. This field is useful for agentic workflows where users can select a single option in a chat such as a department, organization, and others.

To add a single-choice field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Single choice.
In General > Label, enter the text for this field that is displayed to a user in a chat.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.
In Source variable, you can specify a source for the list by using a variable or expression.

If you specify a source variable that is a list of objects, which defines data, then you can choose to display the data as a drop-down list or as a table. To choose a display type, in Appearance > Display as, select Dropdown or Table.

If you select the Dropdown option, specify the name for each list item in Set the display name for each list item by using a variable or an expression.

If you select the Table option, click Edit columns to configure how the columns are displayed to users. When you click Edit columns, a dedicated dialog opens where you can manage the elements.

In the Edit elements, you can:
- Reorder elements: Drag the to change the display order.
- Control visibility: Click the Visibility icon to hide individual elements.
- Edit labels: Modify the text in the Element label column to customize how each element appears to users.
- Tidy labels: Click Tidy labels to automatically format all labels.
- Reset labels: Click Reset labels to restore all labels to their original values from the source variable.
In the Placeholder text option, you can also specify the text that is displayed to the user when the drop-down list is empty.
In Appearance, you can add a placeholder text that is displayed to a user in a chat when the list is empty.
In Behavior, you can specify an initial value for the list by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

A single choice field is now added to your form. The following example shows how it is displayed in the chat.

Single choice

Text

You can add a text field to a form to collect textual data from a user in a chat. The user-specified text is then used by the agentic workflow. For example, users can enter responses for comments or feedback, descriptions of issues or tasks, and others in a chat.

To add a text field to a form:

In the form dialog, click Add field or click the Add icon .
Select Collect from user.
Select Text.
In General > Label, enter the text for this field that is displayed to a user in a chat.

Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

In Input type, you can specify either the Single line or Multi line type for the text.
In Appearance, you can add a placeholder text and helper text for the text field. Set the Placeholder text switch to on to add placeholder text, and set the Helper text switch to on to add helper text. Otherwise, set the switch to off.
In Behavior, you can specify an initial value for the text field by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

If you want to specify a particular initial value, close auto-mapping and enter the value.

You can specify a regular expression (regex) to define the allowed format. To specify a regular expression, set the Regex validation switch to on, and specify the regular expression. The field in the form accepts only text that matches your defined pattern. In Regex error message, you can specify the error message for validation.

For more information about mapping data in agentic workflows, see Mapping data.

A text field is now added to your form. The following example shows how it is displayed in the chat.

Text

Present to user

To display information to the user in a form, you can use any of the following data types:

Field

You can add a field to a form to display data to users in a chat.

To add a field to a form:

In the form dialog, click Add field or click the Add icon .
Select Present to user.
Select Field.
In General > Label, enter the text for the field that is displayed to a user in a chat.
In General > Source, you can specify the source for the data by using a variable or expression.

List

You can add a list to a form to display multiple information in an agentic workflow. For example, you can display priorities, statuses, and other information in a chat in an organized manner to the user.

To add a list to a form:

In the form dialog, click Add field or click the Add icon .
Select Present to user.
Select List.
In General > Select the source for your choice list, specify a source for the list by using a variable or expression.

If you specify a source variable as an array object, which defines data, then you can choose to display the data as a table. You can customize the columns to display in the Columns list.

To edit the selected column labels, click Edit column labels and specify the labels for each item. You can also click Tidy labels to format the labels automatically.

Message

You can add a message to a form to display information in an agentic workflow. For example, you can display the outcome of an agentic workflow in a chat to help users understand the result.

If you want braces to appear as plain text in a message to be displayed, escape them with double braces. For example, {{customer_id}} is displayed as {customer_id} in the output message, and the text inside the double braces is treated as plain text, not as a variable.

To add a message to a form:

In the form dialog, click Add field or click the Add icon .
Select Present to user.
Select Message.
In General > Output message, enter the message. You can also use a variable in the message.

File

You can add a file field to a form to allow users to download the file that is generated in an agentic workflow. For example, users can download reports or any other file in a chat.

To add a file download field to a form:

In the form dialog, click Add field or click the Add icon .
Select Present to user.
Select File download.
In General > Label, enter the text for this field that is displayed to a user in a chat.
In General > Source file, you can specify the source file by using a variable or expression.
- Creating agentic workflows

An agentic workflow defines a set of linked activities and controls that are designed to achieve a specific business purpose or goal. Learn more about agentic workflow.

Dynamic forms

Dynamic forms allow a single form to support multiple use cases without duplicating fields or creating separate forms. Fields respond dynamically as users interact with the form and change behavior based on user input. Instead of presenting all fields together, the form updates as users make selections so that only relevant fields, labels, and values are displayed.

Dynamic behavior is defined by using dynamic rules. Dynamic rules are configured visually in the workflow builder and do not require scripting or custom logic. Rules apply within a form and determine how one field affects the behavior of other fields. Dynamic forms adapt data collection based on user input, such as location, category, role, or previous answers.

A form can contain multiple dynamic rules. A single field can be controlled by more than one rule, and each rule is evaluated independently. Dynamic rules apply only to downstream fields. The controlled field must appear after the trigger field. This ordering supports predictable behavior and avoids circular dependencies.

Dynamic rules can be inserted between fields in the form definition and configured to control different rule types, including dynamic label, visibility, and progressive select. Rule behavior is configured through the rule properties.

Dynamic forms support the following rule types:

Dynamic label

Dynamic label rules control the label text that is displayed for a conditional field. These rules allow the same field to present different label text based on user input, supporting context‑specific terminology within a single form.

Dynamic label rules support multiple rules for the same field, and each rule can include multiple conditions. When conditions are met, the label that is defined in the rule is applied. An alternative label can also be defined for cases where conditions are not met.

Visibility

Visibility rules control whether a conditional field is shown or hidden based on the value of a trigger field. These rules are used to reduce form complexity by displaying fields only when they are relevant.

A visibility rule evaluates one or more conditions and determines the visibility state of the conditional field. Conditions can be combined within a single rule, allowing visibility behavior to be defined for multiple input scenarios. Visibility rules affect only whether a field is displayed and do not change field labels or values.

Progressive select

Progressive select rules control how dropdown values are populated for a conditional field. These rules retrieve values dynamically by running a tool when the trigger field value changes.

Instead of using conditions, progressive select rules rely on the output of a selected tool. The tool is configured in the workflow builder and provides the values that populate the dropdown field. When the trigger field changes, the tool runs again and the available options are updated.

Adding dynamic rules to a form

To add dynamic rules to a form:

In the form dialog, click Add field or click the Add icon .
Select Dynamic rules.
Select a rule type:
- Dynamic label
- Visibility
- Progressive select
In the rule properties:
- Enter a Name.
- Select an Event trigger field.
- Select one or more Conditional fields.

A dynamic rule is added to the form. The rule is created but does not yet define behavior.

Each dynamic rule is composed of the following properties:

Event trigger

Event trigger specifies the field whose value change causes the rule to be evaluated. When the value of the selected event trigger field changes, the rule runs and applies its behavior to the selected conditional fields.

After a rule is added and configured, the relationship is reflected on the trigger field. The trigger field properties include an Event triggers section that lists all rules that are triggered by that field.

For each listed entry under Event triggers, you can see which conditional field is affected, and select Edit rule to open the rule configuration directly.

This capability allows you to review and modify rule behavior from the trigger field without opening the dynamic rule in the form.

Conditional fields

Conditional fields are downstream fields whose behavior is controlled by a dynamic rule. These fields are selected from the list of fields that appear after the event trigger in the form. Selecting a field under conditional fields identifies which fields can be controlled by the rule. Selecting a conditional field does not define behavior by itself; it establishes only the field’s participation in the rule.

Selected conditional fields

The selected conditional fields list displays the fields that are currently associated with the rule. Each field in this list represents a conditional field that the rule can act on. For each selected conditional field, an Add rule option is available. Selecting add rule opens the rule‑specific configuration window, where the behavior for that field is defined, such as label changes, visibility behavior, or value‑source configuration.

Configuring dynamic label and visibility rules

Dynamic label and visibility rules are configured by using the same process. Both rule types use conditions to determine how a conditional field behaves when the trigger field value changes.

To configure a dynamic label or visibility rule to a form:

Select the dynamic rule for the Dynamic label or Visibility rule.
In the rule properties, under Selected conditional fields, select Add rule.
In the Conditional field setup:
- Configure the default condition in the If section.
- To add more conditions, select Add condition.
Configure the rule outcome:
- For a dynamic label rule, specify the label text in the Then section.
- For a visibility rule, specify whether the field is shown or hidden in the Then section.
Specify alternate behavior in the Else section.
Click Save.
- For dynamic label rules, select Add rule again to define another rule for the same field.
- For visibility rules, continue adding conditions within the same rule by selecting Add condition.

Configuring progressive select rule

To configure progressive select rule to a form:

Select the dynamic rule for the progressive select rule.
In the progressive select rule, under Selected conditional fields, select Add rule.
In the Conditional field setup, click Select tool and choose a tool from the available list.
Configure the tool inputs, if required.
Click Save.