> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User activity node

Use a user activity node to define interactive steps in your agentic workflow where users provide or receive information in one of two ways:

* In a multi-turn conversation, where the user provides or receives one piece of data at a time
* Through a form, which prompts the user for several pieces of data in a single conversational turn

To add a user activity node to your agentic workflow, start by creating a `userflow()` object.

#### Multi-turn conversations

To collect or deliver one piece of data at a time, call `field()` on the `userflow()` object. This method accepts the following input parameters:

| Parameter     | Type            | Required | Description                                                                                                                  |
| ------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| name          | string          | Yes      | Unique identifier for the node.                                                                                              |
| kind          | UserFieldKind   | Yes      | Type of user activity. Supported types: `Text`, `Date`, `DateTime`, `Time`, `Number`, `File`, `Boolean`, `Object`, `Choice`. |
| display\_name | string          | No       | Display name for the node.                                                                                                   |
| description   | string          | No       | Description of the node.                                                                                                     |
| direction     | string          | Yes      | Indicates whether the node is for input or output.                                                                           |
| default       | Any             | No       | Default value for the node.                                                                                                  |
| text          | string          | No       | Text used to ask a question. For example: "What is your name?"                                                               |
| option        | UserFieldOption | No       | List of predefined options with it `labels` and `values`.                                                                    |
| is\_list      | bool            | No       | Indicates whether the node accepts multiple values.                                                                          |
| min           | Any             | No       | Minimum value or constraint.                                                                                                 |
| max           | Any             | No       | Maximum value or constraint.                                                                                                 |
| input\_map    | DataMap         | No       | Define input mappings using a structured collection of Assignment objects.                                                   |
| custom        | dictionary      | No       | Dictionary for additional metadata or configuration.                                                                         |

Here is an example that shows how to use `field()`:

```py Python [expandable] theme={null}
from typing import List
from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, UserNode, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKind
from ibm_watsonx_orchestrate.flow_builder.data_map import DataMap

class Name(BaseModel):
    """
    This class represents a person's name.

    Attributes:
        name (str): The person's first name.
    """
    first_name: str = Field(default="John Doe", description="First name")

@flow(
    name ="user_flow_example",
    display_name="user_flow_example",
    description="Example user flow.",
    input_schema=Name,
)
def build_user_flow(aflow: Flow = None) -> Flow:
    # user_flow which is a subflow to be added to the aflow
    user_flow = aflow.userflow()

    # add file upload
    user_node1 = user_flow.field(direction="input",name="upload", display_name="File upload 1",  kind=UserFieldKind.File)

    # add file download
    data_map = DataMap()
    data_map.add(Assignment(target_variable="self.input.value",value_expression="flow[\"userflow_1\"][\"File upload 1\"].output.value"))
    user_node2 = user_flow.field(direction="output",name="download", display_name="Download file",  kind=UserFieldKind.File, input_map=data_map)

    # add a Display user text field
    user_node3 = user_flow.field(direction="output",name="display_first_name", display_name="Display first name", kind=UserFieldKind.Text, text="Display of first name is {flow.input.first_name}")

    # add a text input field
    user_node4 = user_flow.field(direction="input",name="last_name", display_name="Last name",  kind=UserFieldKind.Text, text="Enter last name")
    
    # add a Number input field
    user_node5 = user_flow.field(direction="input",name="age", display_name="Age",  kind=UserFieldKind.Number, text="Enter Age")

    # create a data map to build an array to be assigned to a user field of kind List
    data_map = DataMap()
    data_map.add(Assignment(target_variable="self.input.value",value_expression="[\"Alice\", \"Bob\", \"Charlie\", \"Diana\", \"Ethan\", \"Fiona\", \"George\"]"))
    user_node6 = user_flow.field(direction="output",name="Friends", display_name="List of friends", kind=UserFieldKind.List, input_map=data_map)

    # A user flow edges
    user_flow.edge(START, user_node1)
    user_flow.edge(user_node1, user_node2)
    user_flow.edge(user_node2, user_node3)
    user_flow.edge(user_node3, user_node4)
    user_flow.edge(user_node4, user_node5)
    user_flow.edge(user_node5, user_node6)
    user_flow.edge(user_node5, END)
    
    # add the user flow to the flow sequence to create the flow edges
    aflow.sequence(START, user_flow, END)

    return aflow
```

#### Forms (Public Preview)

To prompt for multiple pieces of data in a single turn, instantiate the `form()` object to create a form node. This method accepts the following input parameters:

| Parameter             | Type   | Required | Description                                                        |
| --------------------- | ------ | -------- | ------------------------------------------------------------------ |
| name                  | string | Yes      | The internal name of the form.                                     |
| display\_name         | string | No       | The display name shown on the form.                                |
| instructions          | string | No       | Instructions text for the form.                                    |
| submit\_button\_label | string | No       | The label for the submit button. Defaults to `Submit` if not set.  |
| cancel\_button\_label | string | No       | The label for the cancel button. If set to None, hides the button. |

After instantiating the form object, add fields to it. Each field type requires its own configuration. Supported field types include:

<AccordionGroup>
  <Accordion title="text_input_field">
    Creates a text input field. Configure it as a single-line input or a multi-line text area.

    | Parameter         | Type   | Required | Description                                                                                           |
    | ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
    | name              | string | Yes      | The internal name of the field.                                                                       |
    | label             | string | No       | Display label for the field.                                                                          |
    | required          | bool   | No       | Whether the field is required. Defaults to `False`.                                                   |
    | single\_line      | bool   | No       | Whether the field uses a single line. If `False`, creates a multi-line text area. Defaults to `True`. |
    | placeholder\_text | string | No       | Placeholder text for the field.                                                                       |
    | help\_text        | string | No       | Help text for the field.                                                                              |
    | default           | any    | No       | Default value for the field, passed as DataMap.                                                       |
  </Accordion>

  <Accordion title="boolean_input_field">
    Creates a boolean input field. Render it as a checkbox or radio buttons.

    | Parameter        | Type   | Required | Description                                                                                         |
    | ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
    | name             | string | Yes      | The internal name of the field.                                                                     |
    | label            | string | No       | Display label for the field.                                                                        |
    | single\_checkbox | bool   | No       | Whether to display as a single checkbox. If `False`, displays as radio buttons. Defaults to `True`. |
    | default          | any    | No       | Default value for the field, passed as `input_map`.                                                 |
    | true\_label      | string | No       | Label for the true option. Defaults to `True`.                                                      |
    | false\_label     | string | No       | Label for the false option. Defaults to `False`.                                                    |
  </Accordion>

  <Accordion title="date_range_input_field">
    Creates a date range input field with start and end date pickers.

    | Parameter          | Type   | Required | Description                                          |
    | ------------------ | ------ | -------- | ---------------------------------------------------- |
    | name               | string | Yes      | The internal name of the field.                      |
    | label              | string | No       | Display label for the field.                         |
    | required           | bool   | No       | Whether the field is required. Defaults to `False`.  |
    | start\_date\_label | string | No       | Label for the start date field.                      |
    | end\_date\_label   | string | No       | Label for the end date field.                        |
    | default\_start     | any    | No       | Default value for the start date, passed as DataMap. |
    | default\_end       | any    | No       | Default value for the end date, passed as DataMap.   |
  </Accordion>

  <Accordion title="date_input_field">
    Creates a date input field.

    | Parameter | Type   | Required | Description                                         |
    | --------- | ------ | -------- | --------------------------------------------------- |
    | name      | string | Yes      | The internal name of the field.                     |
    | label     | string | No       | Display label for the field.                        |
    | required  | bool   | No       | Whether the field is required. Defaults to `False`. |
    | default   | any    | No       | Default value for the field, passed as DataMap.     |
  </Accordion>

  <Accordion title="number_input_field">
    Creates a number input field.

    | Parameter   | Type   | Required | Description                                                                                       |
    | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
    | name        | string | Yes      | The internal name of the field.                                                                   |
    | label       | string | No       | Display label for the field.                                                                      |
    | required    | bool   | No       | Whether the field is required. Defaults to `False`.                                               |
    | is\_integer | bool   | No       | Whether the field accepts only integers. If `False`, accepts decimal numbers. Defaults to `True`. |
    | help\_text  | string | No       | Help text for the field.                                                                          |
    | default     | any    | No       | Default value for the field, passed as DataMap.                                                   |
    | minimum     | any    | No       | Minimum allowed value, passed as DataMap.                                                         |
    | maximum     | any    | No       | Maximum allowed value, passed as DataMap.                                                         |
  </Accordion>

  <Accordion title="file_upload_field">
    Creates a file upload field.

    | Parameter              | Type   | Required | Description                                                  |
    | ---------------------- | ------ | -------- | ------------------------------------------------------------ |
    | name                   | string | Yes      | The internal name of the field.                              |
    | label                  | string | No       | Display label for the field.                                 |
    | instructions           | string | No       | Instructions for the file upload.                            |
    | required               | bool   | No       | Whether the field is required. Defaults to `False`.          |
    | allow\_multiple\_files | bool   | No       | Whether multiple files can be uploaded. Defaults to `False`. |
    | file\_max\_size        | int    | No       | Maximum file size in MB. Defaults to `10`.                   |
  </Accordion>

  <Accordion title="message_output_field">
    Creates a message output field to display static text.

    | Parameter | Type   | Required | Description                     |
    | --------- | ------ | -------- | ------------------------------- |
    | name      | string | Yes      | The internal name of the field. |
    | label     | string | No       | Display label for the field.    |
    | message   | string | No       | The message text to display.    |
  </Accordion>

  <Accordion title="field_output_field">
    Creates a field output to display dynamic values.

    | Parameter | Type   | Required | Description                              |
    | --------- | ------ | -------- | ---------------------------------------- |
    | name      | string | Yes      | The internal name of the field.          |
    | label     | string | No       | Display label for the field.             |
    | value     | any    | No       | The value to display, passed as DataMap. |
  </Accordion>

  <Accordion title="list_output_field">
    Creates a list output field to display tabular data.

    | Parameter | Type               | Required | Description                                                                                    |
    | --------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------- |
    | name      | string             | Yes      | The internal name of the field.                                                                |
    | label     | string             | No       | Display label for the field.                                                                   |
    | choices   | any                | No       | The list of items to display, passed in a DataMap.                                             |
    | columns   | dict\[string, str] | No       | Mapping of source property names to table column labels. Only those columns appear if present. |
  </Accordion>

  <Accordion title="file_download_field">
    Creates a file download field.

    | Parameter | Type   | Required | Description                              |
    | --------- | ------ | -------- | ---------------------------------------- |
    | name      | string | Yes      | The internal name of the field.          |
    | label     | string | No       | Display label for the field.             |
    | value     | any    | No       | The file to download, passed as DataMap. |
  </Accordion>

  <Accordion title="single_choice_input_field">
    Creates a single-choice input field. Display options as a dropdown or as radio buttons.

    | Parameter              | Type               | Required | Description                                                                                       |
    | ---------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------- |
    | name                   | string             | Yes      | The internal name of the field.                                                                   |
    | label                  | string             | No       | Display label for the field.                                                                      |
    | required               | bool               | No       | Whether the field is required. Defaults to `False`.                                               |
    | choices                | any                | No       | The list of available choices, passed as DataMap.                                                 |
    | show\_as\_dropdown     | bool               | No       | Whether to display options as a dropdown. If False, display as radio buttons. Defaults to `True`. |
    | dropdown\_item\_column | string             | No       | Column name used for display text in dropdown.                                                    |
    | placeholder\_text      | string             | No       | Placeholder text for the dropdown.                                                                |
    | default                | any                | No       | Default selected value, passed as DataMap.                                                        |
    | columns                | dict\[string, str] | No       | Mapping of source property names to display labels for complex choice objects.                    |
  </Accordion>

  <Accordion title="multi_choice_input_field">
    Creates a multi-choice input field. Display options as a multi-select dropdown or as checkboxes.

    | Parameter              | Type   | Required | Description                                                                                      |
    | ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
    | name                   | string | Yes      | The internal name of the field.                                                                  |
    | label                  | string | No       | Display label for the field.                                                                     |
    | required               | bool   | No       | Whether the field is required. Defaults to `False`.                                              |
    | choices                | any    | No       | The list of available choices, passed as DataMap.                                                |
    | show\_as\_dropdown     | bool   | No       | Whether to display options as a dropdown. If `False`, display as checkboxes. Defaults to `True`. |
    | dropdown\_item\_column | string | No       | Column name used for display text in dropdown.                                                   |
    | placeholder\_text      | string | No       | Placeholder text for the dropdown.                                                               |
  </Accordion>
</AccordionGroup>

Here is an example that shows how to use `form()`:

```py Python [expandable] theme={null}
from typing import List
from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, UserNode, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKind
from ibm_watsonx_orchestrate.flow_builder.data_map import DataMap

class Name(BaseModel):
    """
    This class represents a person's name.

    Attributes:
        name (str): The person's first name.
    """
    first_name: str = Field(default="John", description="First name")
    last_name: str = Field(default="Doe", description="Last name")

class StringListNames(BaseModel):
    listOfNames: List[Name] = Field(
        default=[{"John", "Doe"}, {"Jane", "Doe"}, {"Jean", "Doe"}],
        description="A list of string values."
    )

class FlowInput(BaseModel):
    salutations: List[str] = Field(
        default=["Mr", "Mrs"],
        description="A list of string salutations."
    )
    listOfLanguages: List[str] = Field(
        default=["java", "python", "typescript"],
        description="A list of languages."
    )
    salary_expectation: int = Field(
        default=200000,
        description="Expected salary as an integer number."
    )


@flow(
    name ="user_flow_application_form",
    display_name="Application form",
    description="Creates an application form.",
    input_schema=FlowInput,
)

def build_user_form(aflow: Flow = None) -> Flow:

    user_flow = aflow.userflow()
    user_flow.spec.display_name= "Application"
    

    user_node_with_form = user_flow.form(name="ApplicationForm", display_name="Application")
    
    data_map = DataMap()
    data_map.add(Assignment(target_variable="self.input.choices", value_expression="flow.input.salutations"))
 
    #Salutatiom
    user_node_with_form.single_choice_input_field(name="Salutation", label="Salutation", required=True, choices=data_map, 
                                                  show_as_dropdown=True, placeholder_text="Please enter your title")
   
    #Boolean married
    user_node_with_form.boolean_input_field(name="Married", label="Married", single_checkbox = True, true_label="Married", false_label="Not married")

    #Text fiels "lastName"
    user_node_with_form.text_input_field(name="LastName", label="Last name", required=True, placeholder_text="Enter your last name", help_text="Enter last name")

    #Number widget Age"
    user_node_with_form.number_input_field(name="Age", label="Age", required=True, help_text="Enter your age")

    data_map_salary = DataMap()
    data_map_salary.add(Assignment(target_variable="self.input.default", value_expression="flow.input.salary_expectation"))
    
    #Number widget salary"
    user_node_with_form.number_input_field(name="Salary", label="Desired salary", is_integer=False, help_text="Your dream salary is here", default=data_map_salary)
  
    data_map_desired_salary = DataMap()
    data_map_desired_salary.add(Assignment(target_variable="self.input.value", value_expression="flow.input.salary_expectation"))
    
     #Field widget salary"
    user_node_with_form.field_output_field(name="acknowledge", label="Desired salary", value = data_map_desired_salary)

    data_map_list_source = DataMap()
    data_map_list_source.add(Assignment(target_variable="self.input.choices", value_expression="flow.input.listOfLanguages"))
    
    #  #List output widget"
    user_node_with_form.list_output_field(name="strength", label="Qualification", choices=data_map_list_source)

    #List output widget"
    user_node_with_form.message_output_field(name="success", label="Successful submision", message="Application successfully completed.")
 

    # A user flow edges
    user_flow.edge(START, user_node_with_form)
    user_flow.edge(user_node_with_form, END)
    
    # add the user flow to the flow sequence to create the flow edges
    aflow.sequence(START, user_flow, END)

  
    return aflow

```