Visual Flow Designer

You use the Visual Flow Designer to create the dialog flow definition, which is the model of the interaction between a skill and its users.

The Visual Flow Designer enables you to design conversations visually. And, unlike the legacy YAML-based designer, the Visual Flow Designer enables you to create conversations modularly with separate and reusable flows.

Basic Concepts

The Visual Flow Designer is a visual tool for designing interactions between a skill and its users. The following topics contain the first things that you need to know.

Visual Designer

With the Visual Flow Designer, dialog flows are designed visually instead of through a code editor. The connections between states are represented in visual diagrams. Variables, parameters, and component properties are defined in specialized editors and dialogs.

Multiple Flows

In the Visual Flow Designer, you create flows to handle the various parts of the conversations you are designing your skill for. Typically you would have:

  • The Main Flow, which is the main entry point for the skill and which is more of a configuration than a flow. The main flow contains:
    • Global variables.
    • Events that map to flows.
  • A flow for each regular intent.
  • A single flow to handle all answer intents (though it is also possible to have separate flows for individual answer intents if you want to include behavior that is specific to those answer intents).
  • Sub-flows and reusable utility flows (e.g. for authentication) that can be called by other flows.

Events

In skills created with the Visual Flow Designer, a flow is triggered when an event that is mapped to that flow occurs. There are events for each of the skill's intents and built-in events for standard cases (such as unexpected user input and errors). In addition, you can define custom events, which enable you to trigger flows based on actions emitted when another flow ends.

Events that are triggered at the skill level are mapped to flows. Events that are triggered in a flow are mapped to states in the flow. (In the case of Dialog Error events, if you haven't mapped the event to a state in the current flow, the event propagates to the Main Flow, from where it is mapped to a flow.)

Note

Events in the Visual Flow Designer roughly correspond with default transition actions in YAML dialog flows.

Variables, Scope, and Parameters

With the Visual Flow Designer, you can define variables at two levels:

  • In individual flows. Variables defined in a flow can't be directly accessed from outside of that flow.

    The lifespan of a flow variable is limited to that flow. Its value is cleared after the dialog has traversed to the end of the flow. If a user returns to that flow later in the session, the variable is re-initialized.

  • In the Main Flow. Variables defined here have a skill-wide (global) scope, meaning that they can be accessed by all flows in the skill.

    Values for these global variables persist througout the user's session with the skill. The variables are cleared when the user session with the skill ends, which happens when one of the following things occurs:

    • The user closes the chat window.
    • The session times out after a period of inactivity (the value of which is defined at the channel level and which is typically 24 hours).
    • In the context of a digital assistant, the user exits the skill or reaches a state that directly invokes another skill.
      Note

      When the user interrupts a conversation with a non sequitur input and is temporarily routed to a different skill, the digital assistanta remains in the context of the original skill and its variables are not automatically cleared. In this case, if the user returns to the original skill after the interruption, the variables hold their values. If the user selects not to return to the original skill, the original skill is exited and the variables are cleared.

Values of variables can be passed in and out of flows by using input and output parameters. By using parameters instead of direct references to variables across flows, you make flows that are self-contained, which enables reusability, fosters predictable behavior, and reduces the likelihood of bugs.

Note

The names of input parameters for a flow need to be distinct from the names of that flow's variables.

New, Modified, and Removed Components

The Visual Flow Designer's set of components is largely the same as in the YAML-based editor, but there are some additions, removals, and modifications. Here's a quick rundown of the biggest differences.

The following components are exclusive to the Visual Flow Designer:

  • Invoke Flow: Used to call a flow from an existing flow.
  • End Flow: Used to end a given flow. You can also use this component's action property to specify an event that triggers another flow. Typically, such an action would be used by an action transition specified in an Invoke Flow component in the parent flow. For top-level flows, the action in the End Flow state triggers the custom event in the Main Flow.
  • Send Message: A simplified Common Response (System.CommonResponse) component for displaying a message.
  • Ask a Question: A simplified Common Response (System.CommonResponse) component for prompting a user for a response.
  • Resolve Composite Bag: A simplified Resolve Entities (System.ResolveEntities) component that is designed specifically to work with composite bag entities.
  • Display Tables and Forms components.

The following components are not available in the Visual Flow Designer:

  • System.Intent: This functionality has been replaced by automatic intent resolution, which occurs when there is no active flow. See Intent Detection and Resolution.
  • System.ConditionEquals: Use the Switch component instead.
  • System.ConditionExists: Use the Switch component instead.
  • System.Text: Use one of the Common Response Component Templates, the Resolve Entity component, or the new Ask Question component instead.
  • System.List: Use a Common Response component template or the Resolve Entity component instead.
  • System.Output: Use a Common Response component template, the Resolve Entity component, or the Send Message component instead.
  • System.Qna: If you are using Q&A modules, you should migrate to the use of answer intents.

For a complete rundown of the components in the Visual Flow Designer, see Component Templates.

Get Started with the Visual Flow Designer

Here's a quick set of steps to get started with the Visual Flow Designer.

Create the Visual Designer Flow Skill

To create a visual flow skill:
  1. Click + New Skill in the skills landing page.
  2. Choose Visual as the dialog mode.
    Note

    The platform version must be set to 22.04 or later for this option to be available.
  3. Create intents and entities. You will need to have these in place before you create variables and intent flows.
  4. Click Flows This is an image of the dialog flows icon in the left navbar. in the left navbar. The editor opens to the Main Flow, where you set and manage the configuration for the entire skill. Among other things, you use its Skill Variables page to add the variables that are shared across flows and its Events page to create and manage the mappings of transactional flows to intents and the mapping of utility flows to built-in events that handle unresolved intents, dialog errors, and presenting answer intents.
Map Events

You can add, edit, or delete mappings from the Main Flow's Event's page. You can various types of events to existing flows using the mapping dialog.
Description of df_2_0_event_mapping_dialog.png follows

You access this dialog by clicking This is an image of the Add icon..
Description of df_2_0_event_mappings_page.png follows

Build an Intent Event Flow

Here you create flows to map to specific intents in your skill. Intent flows are typically mapped to regular intents, though you can also create them for answer intents.

To create an intent event flow:

  1. Create the corresponding intent and any entities that will be referenced within the flow.

    For example, if you're creating a pizza skill, you might create the following artifacts:

    • An orderPizza intent.
    • A value list PizzaTopping entity.
  2. Train the skill.
  3. Get started with the flow:
    • Click Flows in the left navbar, then click + Add Flow.
    • Enter a flow name, then select the name of the intent that's mapped to this flow. Then click Create.
      Note

      You can only choose from the available flow.

      Description of df_2_0_create_intent_flow_dialog.png follows

  4. Create any variables that are used within the flow:
    1. Open the Configuration tab. Then click + Add Variable.
    2. Select the variable type. If the variable references an entity, complete the dialog by naming the variable for the selected entity. Then click Apply.
      Description of df_2_0_create_flow_variable_dialog.png follows

      Note

      Within a flow, a variable and an output parameter can share the same name. However, variables and output parameters cannot have the same names as input parameters.
  5. Build the flow:
    1. Open the Flow tab.
    2. Click the menu The Add State menu icon. in the flow start, then click Add Start State to open Add State dialog.
      The Add Start State option.

    3. Select a state from the component picker, then click Insert.
    4. Open the state's property inspector to configure the component.
Using the pizza skill as an example, you'd begin the flow as follows:
  1. Select Ask Question then click Insert.
  2. Open the Component tab in the question state's property window.
  3. Add a question ("What pizza do you want?", for example). Then select the flow variable.

    Tip:

    Use resource bundles for all user-facing text in your skill.

    Description of df_2_0_update_ask_question_properties.png follows

  4. Add another state after the question by clicking the menu.This is an image of the menu icon.
  5. Choose Send Message and then click Insert.
  6. In the property window for the send message state, enter a confirmation message with a FreeMarker expression that accesses the flow variable using the ${varName.value.value} syntax. For example:
    Your ${PizzaType.value.value} pizza is on the way.
    If you're referencing a a flow-level composite bag entity, use the ${cbVarName.value.itemName.<attribute>} syntax.
    Description of df_2_0_freemarker_expression.png follows

    After you've added states to the flow, you can reassign the start state by clicking the menu This is an image of the menu icon., then choosing Make start state.
    Description of df_2_0_make_start_state.png follows

  7. Open the Transitions tab of the output component's property inspector. Note that End flow (implicit) is selected as the transition. Because this flow has no required output parameters, the transition to the implicit End flow will suffice. However, if this flow had one more required output parameters, then the output state would have to transition to an actual End flow state (inserted by clicking Flow Control > End Flow in the Add State dialog) that specifies the flow's output parameter(s).
    Description of df_2_0_implicit_transition.png follows

Reference Variable Values in FreeMarker Expressions

Use ${varName.value.value} to reference a value list entity. Because entities are resolved as JSON objects, the first .value returns the JSON object and the second .value returns the value of a property in that JSON object. To return the value of the entity in the primary language of the skill, use ${varName.value.primaryLanguageValue}.

For composite bag entities, use ${cbVarName.value.itemName.value} for value list items and {cbVarName.value.itemName} for non-value list items.
  • When an item is a value list, use a value property: ${cbVarName.value.itemName.value} or ${cbVarName.value.itemName.primaryLanguageValue}.
  • For non-value list items, you do not access the item with a value property (no .value or .primaryLanguageValue). For example, if you're referencing a DATE entity whose item name is date in the composite bag, you'd use ${cbVarName.value.date}. For a NUMBER entity item (number), you'd use ${cbVarName.value.number}.
The reference syntax depends on context. To allow the different flows within your skill to reference a skill-level variable, prepend the variable name in the expression with skill. For example, the following expression references an item (Type) in a composite bag entity (Order) that's shared across flows:
${skill.Order.value.Type.value}
skill is not required in expressions for flow-scoped variables:
${Order.value.Type.value}

Tip:

Autocompletion makes writing Apache FreeMarker expressions less error-prone.
Description of autocomplete_variables.png follows

Build a Flow for Built-In Events

You'll likely want to have utility flows for built-in events like handling unresolved intents, dialog errors, and presenting answer intents. You map these flows to built-in events in the main flow. In general, the flows mapped to built-in events get invoked when there is no active intent-level flow, such as when the skill starts, or when an intent flow terminates with an end flow state.

For example, to create a generic flow that handles all answer intents:

  1. Create or import an answer intent and then train the skill.
  2. Click Flows, then click + Add Flow.
  3. Enter a flow name for the answer intent flow, then click Create.
  4. Click the menu The Add State menu icon. in the flow start, then click Add Start State to open the Add State dialog.
    The Add Start State option.

  5. Add a display intent answer state by selecting User Messaging > Display text and multimedia messages > Display intent answer, or by entering intent answer in the Search field. Then click Insert.

    Tip:

    You use the search field to locate a state template.

    Description of df_2_0_insertdisplayanswer_state_dialog.png follows

  6. Click the display intent answer state to open the Component tab of the property inspector, then click Edit Response Items.
  7. Update the text message, incorporating the template FreeMarker expression that accesses the answer intent message ("${skill.system.event.value.intent.answer}"). For example:
    "Hello, ${profile.firstName?capitalize} ${profile.lastName?capitalize}. You were asking about ${skill.system.event.value.intent.intentName?lower_case}. Here's your answer: ${skill.system.event.value.intent.answer}."

    Description of df_2_0_add_answer_intent_reference.png follows

    Note

  8. Click Apply.
  9. Click Main Flow.
  10. Click This is an image of the Add icon. next to the Built-In Events.
  11. Complete the Create Built-In Event Handler dialog:
    • Select Answer Intent (located under Intent Events) from the Unhandled Event Type dropdown.
      Description of df_2_0_create_standard_event_mapping_answer_intent_dialog.png follows

    • Select the answer intent flow from the Mapped Flow dropdown.
  12. Click Create.
Note

The dialog error event flow can exist at both the skill and flow levels. The skill-level dialog error flow, which is mapped to the Dialog Error built-in event, acts as a fallback in the absence of an error-handling flow mapped to the flow-level Dialog Error event. If your skill does not have any dialog error flows at all, then the skill outputs the default error message (Oops! I’m encountering a spot of trouble).
Sample Messages for Built-In Event Flows
Use FreeMarker expressions to access the errors and answer intents. For more ideas, see Handy Expressions.
Built-in Event Expression Syntax and Examples
Answer Intent Use the following syntax for a generic flows that handle all answer intents for the skill:
${skill.system.event.value.intent.answer}

For example:

Hello, ${profile.firstName?capitalize} ${profile.lastName?capitalize}, you were asking about ${skill.system.event.value.intent.intentName?lower_case}. Here's your answer: ${skill.system.event.value.intent.answer}.

Dialog Error Use the following syntax for dialog error messages:
${skill.system.event.value.dialogError.errorMessage}
For example:

An error occurred while processing your order: ${skill.system.event.value.dialogError.errorMessage}

Flows

A flow is a piece of the skill dialog flow that defines the interaction with the user to complete a task or a part of a task that the user wants to perform. Typical examples of flows include:

  • Intent-driven flows, where each intent defined in the skill has an associated flow, for example 'Order Pizza', 'Send Money' or 'Create Expense'.
  • Supporting or utility flows for tasks like user authorization, new user onboarding, logging, or providing user assistance. Such flows can be invoked from multiple flows.

    For example, you could have a Create Account sub-flow that you invoke from flows like Order Pizza or Send Money.

Flow Types

Generally speaking, flows break down into the following types:

  • Main Flow.
  • Intent flows.
  • Flows for built-in events and system transitions.
  • Sub-flows that can be used by top-level flows.
Main Flow

With dialog flows created in the Visual Flow Designer, each dialog flow has a single main flow that is used to configure:

  • The mappings between events and flows.
  • Global context variables that can be used in all of the skill's flows.

    When accessing such a variable with a Freemarker expression, you prefix the variable name with skill. in the expression.

    These skill-level variables are cleared after the user session expires. Session expiry is configured at the channel level and is typically 24 hours by default.

The main flow isn't really a flow as such. Rather, it is the control center for the skill, from where users are directed to specialized flows that are mapped to the resolved intents. The main flow configuration includes the pre-defined skill.system.nlpresult variable that is populated with intent and entity matching results whenever an intent is resolved, which enables control to be passed to individual flows.

Intent Flows

When you design dialog flows with the Visual Flow Designer, you create flows that you then map to your intents. All regular intents (meaning intents that are not answer intents) must be linked to a flow.

For answer intents, you can use either (or a combination) of the following approaches:

  • Create a single flow and map it to the Answer Intent built-in event.
  • Create individual flows for specific answer intents.

    This approach enables you to have specific prompts or questions to precede and/or follow each answer.

Note

You also have the option to not provide any flow at all for answer intents, in which case the answer is given to the user without the dialog flow being directly involved.
Utility Flows for Built-In Events and System Transitions

You can create flows that are triggered by the skill's built-in events (such as Answer Intent and Dialog Error), custom events, and system transitions (such as Authorize User and Dialog Error).

Custom Sub-Flows

You can also create flows that are not mapped to a specific intent or based on built-in events (or system transitions) but which can invoked by other flows.

For example, in a skill for a restaurant, you may want to have a Show Menu flow that can be called in the middle of an order flow if a user so requests.

Variables and Scope

In the Visual Flow Designer, variables for can be defined at two levels:

  • In an individual flow. Variables defined at this level can only be accessed from inside the flow where they are defined.

    A flow-scope variable can't be directly accessed outside of the flow where it is defined, even from sub-flows or calling flows. However, you can define input and output parameters for a flow to pass values to and from variables defined in the flow.

    When the flow ends, the variable values are reset.

    Most of your variables should be defined at this level. By making regular use of flow variables, you make your flows more self-contained, which makes them easier to reuse, easier to test in isolation, and less likely to be adversely affected by bugs in other flows.

  • In the Main Flow. Variables defined here have a skill-wide (global) scope, meaning that they can be accessed by all flows in the skill.

    Values for these global variables persist througout the user's session with the skill. The variables are cleared when the user session with the skill ends, which happens when one of the following things occurs:

    • The user closes the chat window.
    • The session times out after a period of inactivity (the value of which is defined at the channel level and which is typically 24 hours).
    • In the context of a digital assistant, the user exits the skill or reaches a state that directly invokes another skill.
      Note

      When the user interrupts a conversation with a non sequitur input and is temporarily routed to a different skill, the digital assistanta remains in the context of the original skill and its variables are not automatically cleared. In this case, if the user returns to the original skill after the interruption, the variables hold their values. If the user selects not to return to the original skill, the original skill is exited and the variables are cleared.

    You should limit your use of these skill-scope variables to variables that require a shared context. For example, in a food delivery skill, you might need a skill-level variable for the list of all orders that a user has made in a session.

Variable values must match the type that was declared for the variable. If a variable is assigned a value that doesn't match its declared type, a runtime error occurs.

Note

In the Visual Flow Designer, variables can be assigned an initial value when they are declared. (This is different in YAML-based dialog flows, where you need to use a System.SetVariable component to set the initial value.)

Notes for Developers Used to YAML-Based Dialog Flows

If you are used to designing dialog flows using the OBotML code editor, you need to know the following about flows that you create with the Visual Flow Designer:

  • There is no return transition available in the Visual Flow Designer.

    When the last state of a flow is reached the flow's variables are cleared automatically (though any skill-level variables remain active until the end of the session).

  • State transitions can only be defined through the next transition or transition actions.

    When you use the designer to insert a state into a flow, the appropriate next transitions are inserted into that state and the preceding state.

    Implicit transitions based on the sequence of the states are not allowed. If no matching transition can be found, a runtime error will be thrown.

  • It is not possible to directly use FreeMarker expressions to conditionally define the target states for transitions in a component. To conditionally specify the target state, insert a Switch component into the flow to hold the expression and define the action transitions based on the result of the expression.

Designing Flows

Create a Flow

Before you can map any type of event, whether it's an intent event for a transactional flow, or a built-in event for a utility flow, you need to first create the flow itself. The mapping that you eventually assign to a flow determines whether its scope extends to the entire skill, or only to a flow.

To create a flow, click + Add Flow.

The editor is populated with a Flow start node The Dialog Start icon.. You build out the flow from here. The editor also includes Events node where you define the subflows for the system transition events that handle dialog errors, out-of-order user messages, unexpected user input, and authentication.
Description of df_2_0_initial_flow.png follows

Your flow can end without an actual end flow state (implicitly), but if you've defined output parameters that pass required values to another flow, then you need to add an end flow state The End Flow icon., one that specifies these output parameters.

Tip:

Click Validate and then review the findings as you create a flow.

.

Create the Skill-Level Variables
If you need to create a variable that's accessed by all of the flows, then your first stop before building any of the actual flows is to create a skill variable in the Main Flow's Skill Variables page:
  1. Select Main Flow > Skill Variable.
  2. Click + Add Variable and then complete the dialog.
  3. Select the variable type as an entity, a primitive type, or as a list (JSON array) or map (JSON object). If the variable references an entity (custom or built-in), complete the dialog by naming the variable for the selected entity.
    Note

    You need to create variables for any variables that are set or created in entity event handlers or custom components.
  4. If needed, enter an initial (default) value. This can be a single value (e.g., false, for a boolean or 4 for an integer), an expression (e.g., list.ManageAccounts.addAccount for a string ) or a JSON object, one that encloses the keys and values in double quotes (") as illustrated by the following list object:
    [
     {
      "pizzaType":"Veggie",
      "price":"10 USD"
      } 
    ]
    This snippet illustrates the default value for a list type variable in an array.

    Tip:

    If you set an initial value for a variable, you won't need to add a Set Variable state in the flow to give it an initial value.
Designate a Start State
You can use the menu to continue to add or delete states, or to reassign the start state, or starting node This is an image of the start node icon., of the flow. For example, if you're adding a preceding state to the starting node, you can assign it as the starting state.
Note

The start state is the first state to execute within a flow. If any other states precede the start state, the flow will skip those states, leaving them unexecuted.

Description of df_2_0_make_start_state.png follows

Add a State


Description of df_2_0_initial_flow.png follows

From the Flow start node, you can build out your state by first clicking the menu the Add State menu icon and then by inserting a state selected from the Add State dialog, opened by clicking Add start state.
Description of df_2_0_add_state_dialog.png follows

Insert a State Between States
To insert a state between two existing states:
  • Click the transition line that connects the two states and then open the Add State menu by clicking The add a state to this transition icon. . Note that the transition line notes the type of transition between the states (next, for example).
    Description of df_2_0_add_state.png follows

  • Create a state on the fly by choosing Add State from the Next Transition menu or Transition to menu for actions.
    Description of df_2_0_add_state_from_transition.png follows

Edit a State's Properties

Clicking a state opens its property editor, where you set the component configuration and transitions.
Description of df_2_0_start_state_properties.png follows

The property editor for the output state, for example, is a send message component for outputting a string.
Description of df_2_0_start_state_component_page.png follows

Deleting States

You can delete a state by hovering its tile, clicking menu icon and then selecting Delete.

WARNING:

Deleting a state can have unintended consequences. If you delete a state, the state is removed entirely from every place that it appears in the flow. If you delete the wrong state, you can restore it.
If you want to delete a sequence of states:
  1. Choose Delete states from the menu.
    Description of df_20_delete_states_option.png follows

  2. Click Delete in the confirmation dialog.
    Description of df_20_delete_states_confirmation_dialog.png follows

    If you've deleted the states in error, click Undo.
    This is an image of the Undo dialog.

Tip:

If you want to just remove one occurrence of a state in a flow, you can disconnect it from that part of the flow by changing the value of the transition to it from the preceding state.
Restore a Deleted State

If you accidentally delete a state and then realize that you want it back, you can restore it as long as you remain in the Visual Flow Designer and you haven't made any other changes. To do so:

  1. Locate the dialog confirming that the state was deleted. This should appear in the lower left of your screen and look something like the following screenshot:
    Description of undo-delete-state.png follows

  2. Click Undo.
Reconnect a Disconnected State

In the course of development, you might cause a break between states by changing a transition. At this point, the part of the flow that is broken off from the flow is parked within a tile named Disconnected, which appears below the Events tile.


Description of df_2_0_disconnected-states.png follows

You can reconnect a part of a disconnected flow to a working flow by specifying the name of a disconnected state as a transition in the working flow. To do so:

  1. If you are unsure of which states have been disconnected, double-click the Disconnected tile to display the states that have been disconnected from the flow.
  2. Select the tile of the state from which you want to transition to the currently disconnected state to open its property inspector.
  3. In the property inspector, select the Transitions tab.
  4. If you are using the Next transition, select the disconnected state from the Next Transition dropdown.
  5. If you are using an action transition, click Edit (Edit icon) for the transition that you want to use for the state and change the Transition to value to the state that you want to connect to.
Insert a New First State
You may need to insert a state before the start node.This is an image of the starting node icon.. For example, after building your flow, you might find out that you need to revise it because it's starting at the wrong point. For example, your flow starts abruptly: its start node is a state that calls a REST service that requires user input, but there is no preceding state to collect this user input. And because it's a start node, there's no transition line that enables you to insert a state. To add a state before the start node, you need to use the Add preceding state option. To add a state with this option:
  1. Hover over the start node state to invoke the menu the menu icon.
  2. Choose Add preceding state.
    Description of df_20_add_preceding_state_option.png follows

  3. Select a template from the Add State dialog. You can choose the default Next transition, or create a transition action, which you can later configure in the property editor.
    Description of df_20_add_preceding_state_add_state_dialog.png follows

  4. After you've inserted the preceding state, you can assign it as the start node by choosing Make start state from the menu.
    Description of df_20_make_preceding_state_start_state.png follows

Copy States
You can copy and paste a state (or states) to another part of the flow or to a separate flow within the skill.
  1. Click the menu the Add State menu icon on the state that you want to copy, then choose Copy states. Your selection might include a single state, or an entire branch, depending on the state's position and relation to other states.
    The Copy states option

  2. Select the target flow (either the current flow or another flow within the skill). Then click Copy. If you're selecting a separate flow, then any variables associated with the selection will be copied to that flow.
    Description of copy_states_dialog.png follows

  3. Open the Disconnected node, then set a transition that connects the state or states to the flow. If you're creating an new flow based on the copied states, choose Make start state for the selected state.
    Description of copy_disconnected_states.png follows

    Note

    States copied to the current flow are differentiated from the originals with a 1. For example, the copy of cancelOrder is cancelOrder1.

Intent Detection and Resolution

For dialog flows designed with the Visual Flow Designer, intents are detected (and resolved) automatically when there is no active flow.

This means the dialog engine performs intent resolution on the user message when:

  • The session is started with a user message.
  • A previous top-level task flow has just been ended, and the action specified by the End Flow component does not match another event (default transition).
Note

This differs from YAML-based dialog flows, where you have to explicitly add a System.Intent component to the dialog flow. In the Visual Flow Designer, there isn't a System.Intent component.

When the dialog engine performs intent resolution, it stores the result in the pre-defined variable named system.nlpresult (which you can access with the expression ${skill.system.nlpresult.value}). In addition it raises an event named system.intent.<IntentName> for the intent match that is found or system.intent.unresolvedIntent when no intent match is found. In the Main Flow, you create the mappings between the intents and the flows that need to be invoked for those intents.

Note

The automatic detection of intents in the Visual Flow Designer is similar to how digital assistants already work, with the main difference being that digital assistants support non sequiturs within an active skill when the user input is unresolved.

Answer Intent Resolution

If an answer intent is matched and you have mapped a flow to that that answer intent, then that flow is invoked.

If an answer intent is matched and you have not mapped a flow to that answer intent, but you have mapped the Answer Intents built-in event to a flow, then the flow mapped to the Answer Intents built-in event is invoked.

You can use the following expression to access the resolved answer intent answer from the event payload:

  • ${skill.system.event.value.intent.answer}
Note

It's not strictly necessary to create a flow for answer intents. If user input resolves to an answer intent that doesn't have a specific or standard flow mapped, the main flow handles the display of the answer.

Flow Mapping

Map an Intent to a Flow

You can map an intent to a flow when you create the flow:

  1. On the Events page, click + Add Flow.
  2. In the Create Flow dialog, fill in the required fields, including Intent Name.

If you have already defined a flow and now need to map an intent to it, here's how you map the intent:

  1. On the Flows page, in the list of flows, select Main Flow.
  2. Click This is an image of the Add icon. in the Intent Events section.
    This is an image of the Intent Events section header.

  3. In the Create Intent Event Handler dialog, select the intent name and mapped flow, and then click Create
    Description of df_create_intent_event_handler_dialog.png follows

    .

Map a Built-In Event to a Flow

  1. Select Main Flow.
  2. Click This is an image of the Add icon. in the Built-In Events section.
    This is an image of the Built-In Events header.

  3. In the Create Built-In Event Handler dialog, select the event type from the and mapped flow, and click Create.
    Description of df_2_0_built-in_events_mapping_dialog.png follows

Map a Transition Event to a Flow

  1. Select the flow to which you want to map the event.
  2. Select the Configuration tab.
  3. Expand the Event Mappings section.
  4. In the field for the transition that you want to map, select a state.

Invoke One Flow from Another Flow

If you want to call a flow from another flow, you do so by using Invoke Flow and End Flow components. Here's how it works:

  • The parent flow calls the child flow from an invoke flow state. It uses this state to pass values to and receive values from the child flow.
  • The child flow's end flow state passes its output parameters back to the parent flow and can also trigger an action that the parent flow executes after the child flow has ended.

    If the child flow branches and has multiple end flow states, each can pass its own action back to the parent flow, and the parent flow can use these actions to determine which branch to follow.

    (Action transitions enable you to branch the parent flow based on the results of the child flow. For example, if you have a child flow that is supposed to look up an account, it could pass an action for success and an action for failure.)

  • After the child flow has ended, the parent flow resumes.

For example, an Update Account flow in a finance skill would be the parent flow that can only complete the user's update request by calling a child flow, Get Account. The result, or output parameter that the parent flow expects after the child flow executes, is the user account. In this case, the account is the output parameter sent to the invoke flow state by the child flow's end flow state.

To link flows:
  1. Create the input and output parameters for the child flow.
  2. In the parent, or calling flow, click the Add State icon at the point where you want to call the child flow and select the Flow Control > Invoke Flow component. Then click Insert.
  3. Open the property inspector for the invoke flow state that you just added.
  4. On the General page, enter a name and a description.
  5. On the Component page, select the child flow from the Flow dropdown.
  6. If the parent flow needs to pass parameters to the child flow, click Add, then select the input parameter belonging to the child flow and enter a default value. Then click Save. Repeat this step for each input parameter.
  7. If the parent flow expects a result from the child flow, click Add to select the output parameter belonging to the child flow and then name the variable of the current (parent) flow that gets set to the value of the output parameter.
  8. Open the Transitions page to set the next state and, if needed, add action transitions such as cancel or error.
  9. If you have configured action transitions in the parent flow, configure end flow states in the child flow to trigger those actions. You do those on the Component page of each end flow's property inspector.
  10. If you need to pass a parameter back to the parent flow, click Add and then enter the name that matches the parameter name in the parent flow's invoke flow state. Then enter a parameter output value and click Save.

Invoke Another Skill from a Flow

If you want to call another skill from a flow, you do so by using Invoke Skill and End Flow components. Here's how it works:

  • The skill that you are calling must be in the same digital assistant as the skill you are calling from.
  • The skill that you are calling must have a flow that's designated as public.
  • The calling flow uses an Invoke Skill state to specify a version of a skill and a target flow in that skill. It uses this state to pass values to and receive values from the called skill.
  • The target flow's end flow state passes its output parameters back to the calling flow and can also trigger an action that the calling flow executes after the target flow has ended.

    If the target flow branches and has multiple end flow states, each can pass its own action back to the calling flow, and the calling flow can use these actions to determine which branch to follow.

    (Action transitions enable you to branch the calling flow based on the results of the target flow. For example, if you have a target flow that is supposed to look up an account, it could pass an action for success and an action for failure.)

  • After the target flow has ended, the calling flow from the calling skill resumes.

For example, an Update Account flow in a finance skill would be the calling flow that can only complete the user's update request by calling a target flow, Get Account. The result, or output parameter that the calling flow expects after the target flow executes, is the user account. In this case, the account is the output parameter sent to the invoke skill state by the target flow's end flow state.

To link flows:
  1. Create the input and output parameters for the target flow.
  2. In the target flow, select the Configuration tab, expand the General section, and turn the Public switch on.
    This is a screenshot of part of the Configuration page that shows the Require Authorization field and the Public switch.

  3. In the calling flow, click the Add State icon at the point where you want to call the target flow and select the Flow Control > Invoke Skill component. Then click Insert.
  4. Open the property inspector for the invoke skill state that you just added.
  5. On the General page, enter a name and a description.
  6. On the Component page, select skill from the Skill dropdown.
  7. Select a version from the Skill Version dropdown.
    Note

    This value only applies if the referenced skill is a standalone skill. If the target skill is in the same digital assistant as the calling skill, at runtime the version of that skill that is in the digital assistant is used and the value of this field is ignored.
  8. From the Flow Name dropdown, select one of the public flows that belong to the selected skill.
  9. If the calling flow needs to pass parameters to the target flow, click Add, then select the input parameter belonging to the target flow and enter a default value. Then click Save. Repeat this step for each input parameter.
  10. If the calling flow expects a result from the target flow, click Add to select the output parameter belonging to the target flow and then name the variable of the calling flow that gets set to the value of the output parameter.
    Note

    If the target flow isn't yet available, you can specify that the flow use mock data for the output parameters so that you can continue developing and testing the flow while waiting for the target flow to become available. To do so, set the Use Mock property to True and enter output parameters and values in the Mock Output Parameters field. Enter each parameter on a separate line in the form
    ParamName: ParamValue
  11. Open the Transitions page to set the next state and, if needed, add action transitions such as cancel or error.
  12. If you have configured action transitions in the calling flow, configure end flow states in the target flow to trigger those actions. You do those on the Component page of each end flow's property inspector.
  13. If you need to pass a parameter back to the calling flow, click Add and then enter the name that matches the parameter name in the calling flow's invoke skill state. Then enter a parameter output value and click Save.

Events and Transitions

In dialog flows developed with the Visual Flow Designer, events are used to route a conversation to flows or states within flows.

At the skill level, events are broken down into the following types:

  • Intent. These events correspond to the skill's intents. Such an event occurs when user input resolves to a given intent.
  • Built-In. These are standard events for typical use cases like unresolved intent, answer intent, and dialog error.
  • End Flow Action. These are events that you define yourself and which can be triggered by actions in end flow states (both states that use the End Flow component and states which implicitly end the flow).

At the flow level, events are broken down into the following types:

  • System Transitions. These are built-in events for typical use cases like unresolved user input, required authorization, and errors.
  • Custom Transitions. These are events that you can specify yourself and which are typically assigned to component transitions actions. When the flow reaches such a transition, the corresponding event is fired, and the state mapped to the event is invoked.

Built-In Events for the Main Flow

Event When Fired How to Use
Start Skill When a skill starts for the first time. Map to a custom flow to do such things as initalize backend systems or display a Help menu.
Dialog Error When an error is thrown by a component during a conversation. This event can also be fired when there is an error in another flow and that flow's Dialog Error system transition isn't mapped. Map to a custom error-handling flow. If this event is fired but there is no mapping, the current flow is terminated and the skill outputs the default error message ("Oops! I’m encountering a spot of trouble)".
Answer Intent When an answer intent is resolved. Map to a custom flow dedicated to answer intents.
Unresolved Intent When the user intent is unresolved. Map to a custom help flow.
Digital Assistant Help When the user expresses a request for help. This only applies when the user has accessed the skill through a digital assistant and the skill is in the digital assistant's current context. Map to a custom help flow.
Digital Assistant Welcome When the user initiates contact with the digital assistant. This only applies when the user has used explicit invocation to access the skill through a digital assistant but has not expressed an intent. Map to a custom welcome or help flow.
Note

By specifying flows for the Digital Assistant Help and Digital Assistant Welcome events, you are not completely overwriting the behavior for the digital assistant's help and unresolvedIntent system intents. If you want to universally change that behavior, you do so in the digital assistant's settings. See Specify States for a Digital Assistant's System Intents.

System Transitions for Flows

For each flow, you can take advantage of system transitions to define where you handle events such as dialog errors and out of order messages.

To define the state that is used to handle a given event:

  1. On the flow's Configuration tab, scroll down to and expand the Events Mappings section.

    You'll see the System Transitions sub-section.

  2. For the event that you want to map, select the state that you want to map it to.

    This state would typically be an Invoke Flow component that points to the utility flow for handling the event. See Invoke One Flow from Another Flow.

Here are the events that you can map as system transitions in a flow.

Event When Fired How to Use
Authorize User When a state is reached where its Requires Authorization state resolves to true. Map to an Invoke Flow component that calls an authorization flow.
Dialog Error An unexpected error occurs in the conversation.

Map to an Invoke Flow component that calls a flow for error handling.

If this event isn't mapped and an error occurs in the flow, the error handling flow that's mapped to the Dialog Error built-in event for the main flow gets invoked. When Dialog Error is mapped neither for the flow nor for the main flow, the skill outputs the default error message (Oops! I’m encountering a spot of trouble) when an error occurs.

Out-of-Order Message The user selects an option from a previous message in the conversation instead of from the current message. Map to an Invoke Flow component that calls a flow you have provided for handling out-of-order messages.
Unexpected User Input The user provides textual input instead of selecting one of the options provided in the message. Map to an Invoke Flow component that calls a flow you have provided for handling unexpected input.

Event Listening and Triggering

When you have nested flows (flows with sub-flows):

  • The current flow both listens for and triggers built-in and end flow action events.
  • The calling flow only listens for end flow action events that are triggered by the current flow. Then, when the sub-flow that has triggered an end flow action event has finished, the parent flow acts on the triggered event.

    The primary example of this is when a sub-flow's Action property specifies an end flow action event.

System Variables

Variable Type Description
system.nlpresult NLP Result Used to store the NLP result for the user utterance. To get the full NLP result, you can use the expression ${skill.system.nlpresult.value}.
system.intent.utterance String When this variable has a value, it will be used for intent matching instead of the last user message. To access this variable, you can use the expression ${skill.system.intent.utterance}.
system.event Map When one of the built-in events is mapped in the main flow or a sub flow, this variable holds event properties you can use to handle the event. For example, to get an event payload, you'd use an expression in the form ${skill.system.event.value.EVENT_NAME}.
system.rb resource bundle Used to access language resource bundle entries. To access a resource bundle entry, you can use an expression in the form ${skill.system.rb.RB_ENTRY_NAME}.

Save User-Specific Values for Return Visits

In general, when a user conversation with a skill or digital assistant ends, the variable values that were set from the user input are destroyed. However, you can also define user-scope variables to retain user input from previous sessions to enhance new conversations. You create user-scope variables directly in the components themselves.

To create a user-scope variable:

  1. In the Variable field of the property inspector of the component where you want to create it, select User Scope Variable from the dropdown.
  2. In the Scoped Variable Name field that appears, enter the variable name.

    Enter the name without the user. prefix. (Though you use that prefix when referencing a user-scope variable, you don't use it when defining it.)

To reference a user-scope variable, you use an expression like ${user.VAR_NAME}.

For example in the Pizza Skill - Visual Flow Designer sample skill, the lastOrderNumber user-scope variable is set after the user places the order in the service.reg.placeOrder flow. This variable is referenced by the expression ${((user.lastOrderNumber)?has_content)} in the first state of the flow that is called whenever the skill starts (handler.startSkill) to determine if the user has made any previous orders.

Note

The values of user-scope variables are channel specific. For example, if a user access a skill on a web channel and then later access the skill via a Microsoft Teams channel, the Teams channel will have its own instances of the user variables and won't recognize the values from the previous conversation in the web channel.

Profile-Scope Variables for User Context

You can access values for a user’s name, locale, and local time using profile-scope variables, which access the profile settings from the chat client. See User Context.

User Input Form Messages

Sometimes an input form is the quickest and least error-prone way of collecting user information. Rather than a subjecting users to a volley of questions, your skill can guide users to providing valid input by sending them forms that contain input elements like text input fields, time and date pickers and toggle switches.
Description of editable_form_example.png follows

Wherever the conversation flow calls for a message containing an input form, you can insert one by adding an inputForm state:
  1. From the Add State dialog, choose User Messaging > Create Tables and Forms. Then choose Create Input Form.
  2. To create the form's layout, actions and editable and read only fields, first click Edit Response Items and then edit the ResponseItems metadata template. In this case, the template is for the editForm response item.
    responseItems:
      - type: editForm
        title: Input Form
        formColumns: 2
        items:
          - autoSubmit: false
            displayType: textInput
            defaultValue: "${(submittedFields.value.myText)!''}"
            multiLine: false
            minLength: 5
            name: myText
            label: Text
            placeholder: Enter free text
            clientErrorMessage: Field is required and must be between 5 and 50 characters
            required: true
            maxLength: 50
          - validationRegularExpression: "^[a-zA-Z\\s]*$"
            autoSubmit: false
            displayType: textInput
            defaultValue: "${(submittedFields.value.myTextArea)!''}"
            multiLine: true
            name: myTextArea
            label: Text Area
            placeholder: Enter free text
            clientErrorMessage: Numbers are not allowed
          - autoSubmit: false
            displayType: datePicker
            minDate: "1970-01-01"
            defaultValue: "${(submittedFields.value.myDate)!''}"
            name: myDate
            maxDate: "${.now?iso_utc[0..9]}"
            label: Date
            placeholder: Pick a date in the past
            clientErrorMessage: Date is required and must be in the past.
            required: true
          - autoSubmit: false
            maxTime: "12:00"
            displayType: timePicker
            minTime: "00:00"
            defaultValue: "${(submittedFields.value.myTime)!''}"
            name: myTime
            label: Time
            placeholder: Pick a time in the morning
            clientErrorMessage: Time must be in the morning.
            required: false
          - autoSubmit: false
            displayType: numberInput
            minValue: 5
            maxValue: 500
            defaultValue: "${(submittedFields.value.myNumber)!''}"
            name: myNumber
            label: Number
            placeholder: Enter a number between 5 and 500
            clientErrorMessage: Number is required and must be between 5 and 500.
            required: true
          - autoSubmit: false
            displayType: singleSelect
            defaultValue: "${(submittedFields.value.mySingleSelect)!''}"
            name: mySingleSelect
            options:
              - label: Label 1
                value: Value 1
              - label: Label 2
                value: Value 2
              - label: Label 3
                value: Value 3
            layoutStyle: list
            label: Single Select
            clientErrorMessage: Field is required
            required: true
          - autoSubmit: false
            displayType: multiSelect
            defaultValue: "${(submittedFields.value.myMultiSelect?join(','))!''}"
            name: myMultiSelect
            options:
              - label: Label 1
                value: Value 1
              - label: Label 2
                value: Value 2
              - label: Label 3
                value: Value 3
            layoutStyle: list
            label: Multi Select
            clientErrorMessage: Field is required
            required: true
          - displayType: toggle
            defaultValue: "${(submittedFields.value.myToggle)!'true'}"
            name: myToggle
            labelOn: "Yes"
            label: Toggle
            valueOff: "false"
            labelOff: "No"
            valueOn: "true"
        actions:
          - label: Submit
            type: submitForm
        channelCustomProperties:
          - channel: "${system.channelType}"
            properties:
              replaceMessage: "${system.message.messagePayload.type == 'formSubmission'}"

The Edit Forms Metadata Template

Here are some things to note about template for the editForm response type:
  • The properties provided for the items, actions and channelCustomProperties are all specific to the editFormMessagePayload objects. Among other things, this payload contains descriptions of the overall layout of the input form message that's received by the user, the form fields (both read only and editable), and channel-specific customizations for platform-specific UI rendering and form submission behavior.
  • For each item and within the actions node, the template references a flow-level variable called submittedFields that holds the user input. This is a map variable that's generated when you add an inputForm state to the dialog flow.
    Note

    Depending on your needs, you can reference individual variables or a composite bag variable in place of the submittedFields variable.
  • items:
    • While the template provides properties for the editable fields (single and multiselect fields, date and time pickers, the number input field and the toggle switch), you can also add items for the text and link read only elements.
    • The editable fields share a set of common properties, including the autoSubmit property. This is an optional property, but enabling it (autoSubmit: true) allows the form to submit a field value before the user has actually submitted the entire form. You can use this property for interdependent fields within your form. For example, you can set this property when the display of one field depends on a value entered in another field, or when a value set for one field restricts the input allowed in another field.
      Note

      Microsoft Teams does not support autoSubmit.
    • The optional clientErrorMessage property sets the field-specific error message that displays when there is limited client-side validation or when client-side validation fails. For example, for messages sent through the Slack channel, this property is only supported when the form is within the conversation page. It does not display when the form message is in a modal dialog.
      Note

      This property is mainly intended for Microsoft Teams adaptive cards, which limits you to use a single message for all different field-level errors.
  • actions - Within this node, the template describes the form submission actions that submit the user input through the FormSubmissionMessagePayload.
  • channelCustomProperties - To support a multi-mode experience, where the user might use combinations of text and voice to fill in the form fields before submitting the form, the template includes the replaceMessage property configuration that instructs the client channel to update the current input form message instead of adding a new input form to the conversation.

Input Form Fields

Element Example Sample Code: Map Variable (submittedFields) Editable?
Single-select List Allows users to search for, and select, an item from a predefined list. You can style this component as a list of options which users can query for, and select.
Description of single_select.png follows

 - displayType: singleSelect
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true
Yes
Multiselect List A list that supports multiple selections. You can style this component as a pick list that users can filter and select from, or as a set of checkboxes.
Description of multi_select_edit_form.png follows

 - displayType: multiSelect
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select attendees
Yes
Time Picker Allows the user to enter a time value within a specified range. The component's maxTime and minTime properties validate the user input.
Description of time_picker.png follows

      - displayType: timePicker
        defaultValue: "${(submittedFields.value.Time.value?time.xs?string['hh:mm a'])!''}"
        maxTime: "23:00"
        minTime: "13:00"
        name: Time
        label: Expense Time
        placeholder: What time was the expense?
        clientErrorMessage: This time is outside the limits.
        required: true
Yes
Date Picker A field with a drop down calender that allows users to select a day, month, and year. The component's maxDate and minDate properties validate the user input.
Description of date_picker.png follows

 - displayType: datePicker
        defaultValue: "${(submittedFields.value.Date)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Yes
Number Input Allows the user to enter a number value. The minValue and maxValue properties validate the user input.
Description of number_input.png follows

     - displayType: numberInput
        minValue: 5
        serverErrorMessage: "${(amountError.value)!''}"
        maxValue: 500
        defaultValue: "${(submittedFields.value.Amount)!''}"
        name: Amount
        label: Amount
        placeholder: Enter expense amount
        clientErrorMessage: Amount is required and must be between 5 and 500.
        required: true
Yes
Text Input Allows the user to enter a text value.
Description of text_input.png follows

      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Description)!''}"
        minLength: 10
        name: Description
        label: Description
        placeholder: What is the expense justification?
        clientErrorMessage: "Description must be 10 characters minimum, 50 characters maximum."
        maxLength: 50
        required: true
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Notes)!''}"
        minLength: 10
        name: Notes
        inputStyle: email
        label: Notes
        placeholder: Expense notes (optional)
        maxLength: 50
        required: false
Yes
Toggle Presents a toggle switch (or a radio button grouping, depending on the channel) for two options.
Description of edit_form_toggle.png follows

      - displayType: toggle
        defaultValue: "false"
        name: TipIncluded
        labelOn: Tip
        label: Tip Included?
        valueOff: "false"
        labelOff: No Tip
        valueOn: "true"
Yes
Text Read only inline text
Description of text_read_only.png follows

      - displayType: text
        alignment: left
        value: Read our expenses policy.
No – Read only
Link An inline link
Description of link_read_only.png follows

      - displayType: link
        alignment: left
        value: "http:www.oracle.com"
No – Read only

Handy Expressions

In your flows you can use FreeMarker expressions for a variety of purposes. Here are some commonly-used expressions.

Tip:

Autocompletion guides you through writing these (and other) Apache FreeMarker expressions.
Operation Freemarker Expression Result Type
Get name of parent flow ${system.parentFlow} String
Get event payload ${skill.system.event.value.EVENT_NAME} JSON object
Access NLP result ${skill.system.nlpresult.value} JSON object
Access skill-scope variable ${skill.VAR_NAME}  
Access flow-scope variable ${VAR_NAME}  
Access flow input param ${INPUT_PARAM_NAME}  
Access user-scope variable ${user.VAR_NAME}  
Access profile-scope variable ${profile.VAR_NAME}  
Get Answer Intent answer ${skill.system.event.value.intent.answer}

Note: You can also use ${skill.system.event.value.answerIntent.answer}.

 
Get intent name

${skill.system.event.value.intent.intentName}

String
Get error message ${skill.system.event.value.dialogError.errorMessage} String
Access Resource bundle entry ${skill.system.rb.RB_ENTRY_NAME} Resource Bundle
Access the value of a custom parameter ${skill.system.config.CUSTOM_PARAMETER_NAME} String

For more on FreeMarker in your components, see Apache FreeMarker Template Language Syntax.

User Authorization

At certain points in a flow, you may wish to enforce user authorization. You accomplish this by doing the following:

  1. On the states where you want to enforce authorization, set the Requires Authorization property to True. This property is on the General tab of the state's property inspector.

    If a user that reaches such a state hasn't authorized yet, the Authorize using OAuth state is invoked, and then the flow invokes the state that required authorization.

  2. Create an authorization component and map it to the flow's Authorize User standard transition event:
    1. Select the flow and then select the flow's Flow tab.
    2. Double-click the Events tile for the flow to expand it.
    3. Mouse over the Authorize User tile, click the ellipsis (…) button that appears, and select Add State.
    4. From the Security category of the template picker, select a component, provide a name for the state, and click Insert.

      See Security Templates for details of each of the available templates.

    5. In the component's property inspector, configure the component's properties, including its transition actions.

Auto Numbering Response Items

You can use the auto-numbering feature to prefix buttons and list options with numbers in your responses. When users can’t use tap gestures, they can still trigger the button’s postback actions by entering a number. This feature is particularly helpful for text channels.

You configure auto numbering at the skill level.

To configure auto numbering:

  1. In the left navigation of the skill, select Settings icon.
  2. Select the Configuration tab.
  3. Set the value of Enable Auto Numbering on Postback Actions in Task Flows.

    If you want to turn on auto numbering for all channels, set the value to true.

    If you want to turn auto numbering on only for certain channels, provide an expression to determine which channels will get auto numbering. For example, to turn on auto numbering only for Twilio channels, you would enter:

    ${(system.channelType=='twilio')?then('true','false')}

Resource Bundles and the Visual Flow Designer

Any user-visible strings that you add to your dialog flow are best handled through resource bundles.

You reference resource bundle message keys through the variable rb. A reference to a simple resource bundle message takes either of the following two forms:

  • ${rb.RB_ENTRY_NAME}
  • ${skill.system.rb.RB_ENTRY_NAME}
For more on resource bundles, including information on creating the resource bundle entries themselves and using complex message formats, see Resource Bundles for Skills.

Tip:

Autocompletion helps you select the resource bundles referenced in Apache FreeMarker expressions.
Description of autocomplete_resource_bundle_expression.png follows

Insights for Flows Created in the Visual Flow Designer

A conversation is included in the Total Conversations tally in Insights in the following cases:
  • The conversation ends at an End Flow state.
  • The conversation ends at state where End flow (implicit) is selected a the transition.

Modify a Resource Bundle Entry

  1. In the skill, click Resource Bundles icon to open the Resources Bundle.
  2. Select the Configuration tab.
  3. Using the Filter field, navigate to the entry that you want to update.
  4. Mouse over the value for the key and select the Editicon that appears.
  5. In the Text field, enter the updated message.
  6. Click Update Entry.

Component Templates

Here are descriptions of the templates that are provided for the various dialog flow components.

Send Message

This is a very simple component that is designed to display one or more messages to the user. It does not wait for or respond to user input.

The Send Message component has the following property:

Property Description
Messages Messages that are displayed to the user when the component is called.

Ask Question

This component is designed to ask for user input and then store that input so that it can be used or processed by other components.

The Ask Question component has the following properties:

Name Description
Question Text that is displayed to the user.
Variable The variable that holds the user's answer to the question.

This component can return the following actions:

Action Description
cancel The user has reached the maximum number of attempts to provide a valid value.
system.textReceived The user has entered text (as opposed to, for example, selecting an action button).

Resolve Composite Bag

This component is a simplified version of the Resolve Entities component that you can use to resolve a composite bag entity.

To use this component, you need a composite bag entity and a skill variable for that composite bag.

The Resolve Composite Bag component has the following property:

Name Description
Composite Bag Entity Variable Text that is displayed to the user.

This component can return the following actions:

Action Description
cancel The user has reached the maximum number of attempts to provide a valid value.
disambiguate The user input needs to be clarified to determine which entity value it matches, if any.
match The user input matches a valid entity value.

User Messaging Templates

The templates in the User Messaging category are designed for displaying messages and prompts and accepting user input.

With the exception of the Resolve Entity and User Feedback templates, all of these templates are based on the Common Response component and are tailored to specific purposes.

Common Response Component Templates

The vast majority of the templates in the User Messaging category are based on the Common Response component, which enables you to use component properties and metadata to build a specialized user interface that can include text, action buttons, images, and cards.

In many of the cases, such as the templates in the Display Multimedia Messages sub-category, the main differences are in the Metadata property for the Common Response component.

In other cases, such as in the Display Tables and Forms sub-category, the template consists of a Common Response component preceded by a Set Variable component.

In the Channel-Specific Features sub-category, there are examples of using extensions available for Slack and Microsoft Teams channels.

Properties for Common Response Component Templates

Except for the Resolve Entities and User Feedback components, the templates in the User Messaging category are based on the Common Response component. As such, they each use the properties in the following table (or a subset of them).

Name Description
Metadata The chat response created by this component is driven by the message-specific ResponseItems metadata. See The Metadata Property.
Process User Message

Set this property to True to direct the Dialog Engine to return to the state after the user enters text or taps a button. Set this property to False if no user input is required (or expected).

Set this property to True when setting a location.

Keep Turn

A boolean value for relinquishing (False) or retaining (True) the skill’s control of the dialog flow. Set to True when you want to output an unbroken sequence of skill messages wherein no interjections from the user are accepted.

This property only applies when you set the Process User Message property to False.

Variable

This variable holds the name of the context or user variable that gets populated when a user responds by entering free text instead of tapping a button. This property is ignored when a user taps a button, because the button’s payload determines which variables values get set. If the variable property has already been set when the Dialog Engine enters this state, then the state is skipped.

For composite bag entities, reference the composite bag entity variable. Users get prompted for the individual entity values in the bag. When all the entity values are set, the component transitions to the next state.

Maximum Number of Prompts

Before the component can populate the variable value that you’ve specified for the Variable property from the text entered by the user, it validates the value against the variable type. This can be entity-type validation, or in the case of a primitive type, it’s a value that can be coerced to the primitive type.

When the component can’t validate the value, the Dialog Engine sends the message text and options again. (You can modify this message to reflect the validation failure.) To avoid an endless loop resulting from the user’s continued inability to enter a valid value, use this property to set a limit on the number of attempts given to the user. When the user exceeds this allotment, the component transitions to the cancel action. See Limiting the Number of User Prompts

As described in Create a Composite Bag Entity, individual entities in a composite bag entity can override this setting when the Maximum User Input Attempts option is set.

Multi-Value Indicates whether an entity variable can store an array of matching values or just a single matching value.
Cancel Policy Determines the timing of the cancel transition:
  • Immediate—Immediately after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide Maximum Number of Prompts value has been met.

    This is the default value.

  • Last Entity—When the last entity in the bag has been matched with value.

This property is ignored if you've registered an entity event handler with an item- or event-level maxPromptsReached handler.
Use Full Entity Matches When set to True, custom entity values are stored as JSON objects (similar to built-in entity values). This enables you to create expressions to access properties such as value, primaryLanguageValue, and originalString, which are particularly important for skills that are currently or eventually might become multi-lingual.
Resolve Entity
Property Description
Variable Refers to the composite bag entity context variable that’s populated by this component. If all child entities of the composite entity variable already have a value, then the dialog flow transitions to the next state without sending the user a message.
Maximum Number of Prompts Specifies the number of attempts allotted to the user to enter a valid value that matches the child entity type. If the maximum number of attempts is exceeded for the first child entity, this property resets to 0 and the bot outputs the prompt for the next child entity. As described in Create a Composite Bag Entity, individual entities in the composite bag can override this setting when the Maximum User Input Attempts option is set.
Multi-Value Indicates whether an entity variable can store an array of matching values or just a single matching value.
Use Full Entity Matches When set to True, custom entity values are stored as JSON objects (similar to built-in entity values). This enables you to create expressions to access properties such as value, primaryLanguageValue, and originalString, which are particularly important for skills that are currently or eventually might become multi-lingual.
Prompt The text used to prompt the user for built-in entities.
Disambiguation Prompt The text used to prompt the user for disambiguation when the prior user input matched multiple values of the built-in entity. This property is ignored if the Multi-Value property resolves to true.
Header Text A message that displays before the component prompts the user for the next item in the bag. You can use this header to provide feedback on the previous entities in the bag that have been matched (or updated). For example:
<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>
Footer Text Enhances the output on text-only channels. For example, you can use FreeMarker expressions to conditionalize the footer text for text-only channels.
Cancel Policy Determines the timing of the cancel transition:
  • Immediate—Immediately after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide Maximum Number of Prompts value has been met.

    This is the default value.

  • Last Entity—When the last entity in the bag has been matched with value.

This property is ignored if you've registered an entity event handler with an item- or event-level maxPromptsReached handler.
User Feedback

The User Feedback component enables you to collect feedback data for Insights by presenting users with a rating scale after they've completed a transactional flow. If you're using the 21.10 SDK or later, this component outputs a horizontal star rating system. If you're using an earlier SDK, the component outputs this rating scale as a simple list that allows users to tap the button that corresponds with their rating.

While you can change the behavior of this component using the component properties, you can change its look and feel when you use the SDK (version 21.10 or later). For example, you can replace the default star icons used for the feedback buttons with another icon.

Name Description
Max Rating The maximum rating that a user can submit. By default, the maximum value is 5. You can adjust this value downward.
Threshold A boolean, which if set to true, enables the user to submit text feedback if the rating is less than, or equal to, the threshold value. By default, this property is set to false (no feedback enabled).
Enable Text Feedback The value for evaluating the transition between the above and below actions. By default, the threshold between positive and negative feedback is set as 2 for the default maxRating value, which is 5.
Footer Text The text that displays at the bottom of the feedback dialog.

This component can return the following actions:

Action Description
above Set when the user input is a valid value that's above the Threshold value.
below Set when user input is a valid value that's equal to, or below, the Threshold value. ).
cancel Set when users decline the rating by clicking Skip.

You can use the following system variables for the messages output by the transition states:

  • system.userFeedbackRating – Returns the user's rating.
  • system.userFeedbackText – When enableTextFeedback is set to true, your skill can prompt for feedback when the ratings fall below the threshold value. system.userFeedbackText returns the user's input (${system.userFeedbackText.value}).

The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:

Resource Bundle Key Description
Feedback - feedbackPrompt The prompt shown to the user to select the rating for the conversation.
Feedback - invalidValuePrompt The prompt shown to the user to select the rating for the conversation after the user has input an invalid value for the rating.
Feedback - ratingButtonLabels Comma-separated list of labels displayed on the rating buttons.
Feedback - skipLabel The label of the button for skipping feedback.
Feedback - textFeedbackPrompt Prompt shown to the user asking them to provide text feedback when they give a rating below the Threshold property value.
Feedback - thankYouPrompt The prompt shown to the user when the transition selected by the user is not defined in dialog flow.

Variables Templates

Copy Variables

Copies values from one variable to another.

Property Description
Source Variables The name of the variables that will have their value copied.
Destination Variables The variables that the values from the source variables will be copied to.

The definitions of these properties don’t have to mirror one another. While you can define both destination and source variables as lists of variables, you can also define the source variable with a single variable and the destination as a list. If you set an additional destination variable, it inherits the variable value of the proceeding source value specified.

Reset Variables

This component resets the values of specified variables to null.

Property Description
Variables to Reset The variables that need to be reset.
Set Variable

The Set Variable component sets the value of a pre-defined variable.

Property Description
Variable The name of the variable.
Value The target value, which you can define as a literal or as a FreeMarker expression that references another variable. The value must match type of the declared variable.
Set Custom Metrics
Click Dimensions to add the name-value pairs for the dimensions and dimension values.
Attribute Description
name The name of the dimension (in 50 characters or less) as it appears in the Custom Metrics report. Use only letters, numbers, and spaces. Do not use special characters.
value You can define the dimension value as either a FreeMarker expression or a text string.
  • Use FreeMarker expressions to reference a variable declared for an entity.
  • Use a string to track a value that's not set by variables in the dialog flow definition, but is instead tracks other aspects of skill usage.

Language Templates

Detect Language

The Detect Language component uses the translation service to detect the user’s language from the user input.

Note

This component is only available if you have created your skill to use a translation service (i.e., not in natively-supported language mode).

This component sets a variable named profile.languageTag with the locale string. You can set variables with the current language when you use this variable in a value expression (${profile.languageTag}).

Note

The profile.languageTag takes precedence over the profile.locale variable that’s set by the messenger client.
Property Description
Existing Profile Language Tag When set to True, the skill uses the language that is detected by the digital assistant immediately. (Otherwise, the skill might provide a message or prompt in English before the language is (re-)detected.) This property only applies to skills that are in digital assistants that use a translation service.
Translate Input

This component sends specified text to the skill's translation service and then stores the English translation. It relies on the skill being configured with a translation service, which recognizes the language from the user's input and translates it into in English. This component doesn't work with skills that use the Natively Supported language mode.

Use this component when you need to process the raw input text before having it translated. For example, you might want to remove some personal data from the user input before sending it to the translation service.

Because this component leverages the translation service, which already detects the user’s language, this component doesn’t need to follow states that detect or set the language.

Property Description
Expression FreeMarker expression that specifies the text values to be translated into English.
Variable The variable that holds the English translation of the text. If this value isn't set, the component uses the user's previous input.
Translate Output

The Translate Output component allows you to translate specified text to the user’s language. The component takes the value defined for the Expression property. It uses the skill's translation service to translate the text into the language detected by the Detect Language component or by the profile.locale variable and then stores it in the variable specified by the Variable property.

This component doesn't work with skills that use the Natively Supported language mode.

Properties Description
Expression A FreeMarker expression that references a variable whose value needs to be translated.
Variable Variable that holds the translated text.
Match Entity

The Match Entity component calls the Intent Engine to extract entity information from the text held by the Source Variable property. If a match exists for the variable's entity type, the variable specified by the Variable property is set with this entity value.

Property Description
Source Variable The variable that holds the input value.
Variable The name of the variable that is set with the value of the extracted entity. The value of this variable can be used in a subsequent Set Variable component to extract a specific entity using a FreeMarker expression. For example, to extract an EMAIL entity value: ${userInputEntities.value.entityMatches['EMAIL'][0]}

This component also has two predefined transitions: match and nomatch.

Transition Description
match Directs the Dialog Engine to go a state when the entities match.
nomatch Defines the Dialog Engine to go to a state when the entities don’t match.
Note

The Match Entity component resolves only a single value.

Security Templates

OAuth Account Link

Use this component to obtain the authorization code for services that are secured by the authorization code grant flow, such as LinkedIn, Twitter, Google, or Microsoft. The skill’s custom components can exchange the authorization code for an access token, which they then use to invoke the end service.

The component first directs the user to the identity provider’s login page. After a successful login, the component returns the authorization code in a variable, which you use to pass the authorization code to the custom component. The custom component API must exchange the authorization code, client ID, and client secret for an OAuth user access token.

For each state that requires authorization before it can be invoked, you set its Requires Authorization setting to True. See User Authorization for the steps to set this up.

Property Description
Variable Specifies the variable to store the authorization code in. You can declare it in the context node as a variable, a string, or another supported variable type. It can also be a user variable.
Authorize URL The login URL. The authorizeURL Property describes how to configure this URL.
Footer Text Enhances the login dialog by adding text beneath the login and cancel options. You can use FreeMarker expressions to conditionalize the footer text for text-only channels.
Show Cancel Label (Optional) Enables you to specify whether or not to display the Cancel button. By default, this property is set to True, meaning that the Cancel button is displayed. In some cases, such as for SMS channels, you might not want to display this button. You can configure such behavior with an expression like:
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

This component can return the following actions:

Action Description
fail The user clicked the cancel button.
pass The authorization code was retrieved successfully.
textReceived The user entered text instead of clicking the cancel button or authenticating successfully.

The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:

Resource Bundle Key Description
OAuthAccountLink - cancelLabel Use to override the label for the button that the users can click to leave state without invoking the authentication dialog. The default label is Cancel.
OAuthAccountLink - linkLabel Use to override the label for the button that the users can click to invoke the authentication dialog. The default label is Log In.
OAuthAccountLink - prompt The string to use to prompt the user to sign in.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Tip:

You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.

When the dialog engine encounters this component, the skill bot prompts the user with two links — Login and Cancel.


Description of fb_oauth.png follows

There are several ways to transition from this component:

  • The user clicks the cancel button and the component transitions to the state that's named by the fail action.

  • The user doesn't click any buttons but enters text instead. The component transitions to the state that's named by the textReceived action.

  • The user clicks the login link and the channel renders the identity provider’s login page or its authentication dialog as a webview, as shown in the example below. After successful authorization, the component transitions to the state that's named by the pass action (or to the next state if there isn't a pass action), which would typically call a custom component that exchanges the authorization code for an access token.


Description of webview_login.png follows

If the test window doesn’t render the webview, cut and paste the link text into your browser.

OAuth 2.0 Account Link

Use this component to obtain an OAuth2 user access token (grant type Authorization Code) for resources that are secured by Oracle Identity Cloud Service (IDCS), Oracle Access Manager (OAM), Microsoft identity platform, or Google OAuth 2.0 authorization. This component completes all the steps for the 3-legged OAuth2 flow and returns the OAuth2 access token.

For each state that requires authorization before it can be invoked, you set its Requires Authorization setting to True. See User Authorization for the steps to set this up.

If you need to obtain an access token of grant type Client Credentials to access client resources, see OAuth 2.0 Client.

Before you can use this component in a skill, you must do the following tasks:

  1. If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
  2. Add an authentication service for the identity provider, as described in Authentication Services.

Some identity providers issue refresh tokens. When you use this component, Digital Assistant stores the refresh token for the retention period that's specified for the authentication service. The Digital Assistant backend can use the refresh token, if available, to get a new access token without the user having to sign in again.

Property Description
Authentication Service The name of the authorization-code service that you created in the Authentication Services UI for the OAuth2 identity provider.
Authenticated User Variable Name Specifies the variable in which to store the authenticated user name (the name that’s known by the identity provider). If the variable is user-scoped, then it can be shared across skills.
Access Token Variable Name Specifies the variable to store the access token in. If the variable is user-scoped, then it can be shared across skills.
Multi-Scope Access Token Variable Name Field reserved for future multi-scope access token support.
Footer Text Enhances the login dialog by adding text beneath the login and cancel options. You can use FreeMarker expressions to conditionalize the footer text for text-only channels.
Show Cancel Option (Optional) Enables you to specify whether or not to display the Cancel button. By default, this option is set to True, meaning that the Cancel button is displayed. In some cases, such as for SMS channels, you might not want to display this button. You can configure such behavior with an expression like:
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}
Requires Association Consent Set this to True if the skill uses the Notify User component and the event channel is either Twilio or Slack to persist user identity across sessions and channels. This property enables the linking of supported channel accounts to the OAuth authenticated IDCS account using a unified user identifier.
Update User Profile If the identity provider is IDCS, and you want to store the user's profile from IDCS for the duration of the session, then set this property to True. When a user is challenged for authentication, if this property is set to true, the component will try to fetch the user profile data from the identity provider and set the results in the userProfile.<authorization service> map. See Store IDCS User Profile for the Duration of the Session.
Enable Single Sign-On (Applies to Microsoft Teams channels only) If you have set up Microsoft Teams single sign on, setting this to True will enable users that have already signed in to Teams to not have to sign in to the skill separately.
Redirect URL The redirect URL that receives the authorization code.
Note

The Associate With Unified User property is no longer available. If you want to enable the linking of supported channel to a unified user identity, you can do so for the whole instance. See Enable Channel Account Linking.

This component can return the following actions:

Action Description
fail The user clicked the cancel button.
pass The access token was retrieved successfully.
textReceived The user entered text instead of clicking the cancel button or authenticating successfully.

The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:

Resource Bundle Key Description
OAuth2AccountLink - cancelLabel Use to override the label for the button that the users can click to leave a state without invoking the authentication dialog. The default label is Cancel.
OAuth2AccountLink - linkLabel Use to override the label for the button that the users can click to invoke the authentication dialog. The default label is Log In.
OAuthAccount2Link - prompt The string to use to prompt the user to sign in.
OAuthAccount2Link - consentNeverFinalConfirmationNoLabel The label for the "No" button that appears after the prompt to confirm that the user wants to opt out of having their channel account permanently associated with a unified identity. The default is Cancel.
OAuthAccount2Link - consentNeverFinalConfirmationPrompt The prompt that asks users to confirm that they want to opt out of having their channel account associated with a unified identity.
OAuthAccount2Link - consentNeverFinalConfirmationYesLabe The label for the "Yes" button that appears after the prompt to confirm that the user wants to opt out of having their account permanently associated with a unified identity. The default is Confirm.
OAuthAccount2Link - consentNeverFinalPrompt The message that confirms to users that they have permanently opted out of having their account associated with a unified identity.
OAuthAccount2Link - consentNeverLabel The label for the "Never" button that appears after the prompt that asks if the user wants to associate their channel account data to a unified identity. The default is Never link this account.
OAuthAccount2Link - consentNotifyPrompt The message that informs users that their channel account will be associated with the authenticated user identity.
OAuthAccount2Link - consentNotNowFinalPrompt The message that confirms to users that they have temporarily declined to associate their channel account data to a unified identity.
OAuthAccount2Link - consentNotNowLabel The label for the "Not Now" button that appears after the prompt that asks if the user wants to associate their channel account data to a unified identity. The default value is Not at this time.
OAuthAccount2Link - consentPrompt The prompt that asks users to choose if they consent to associating their channel account with the authenticated user identity.
OAuthAccount2Link - consentYesLabel The label for the "Yes" button that appears after the prompt that asks if the user wants to associate their channel account data to a unified identity.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Tip:

You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.

When the dialog engine encounters the component, the skill bot prompts the user with two links: Get an Access Token and Cancel (you can use linkLabel and cancelLabel to change the link text).


Description of oauth2accountlinksignin1.png follows

If the user clicks the link to get an access token, it displays the identity provider’s login page or authentication dialog as specified by the authentication service. After successful login, it obtains the access token, sets the values for the variables identified by accessTokenVariableName and authenticatedUserVariableName, and then flows to the state that's named by the pass action (or to the next state if there isn't a pass action). If the user cancels, the postback action is set to fail. If the user enters text, it returns the textReceived action.


Description of oauth2accountlinksignin2.png follows

As mentioned earlier, you can set requiresAuthorization for a state to ensure that the user is authorized before invoking the state's component. If the user hasn't authorized yet, the dialog invokes the system.authorizeUser action in defaultTransitions.

OAuth 2.0 Client

Use this component to obtain an OAuth2 access token of grant type Client Credentials. That is, you use it to get an access token that's based on the client's credentials, and not the user's name and password. You can use this component to get a token that enables access to client resources that are protected by Oracle Identity Cloud Service or Oracle Access Manager (OAM).

If you need to access resources on behalf of a user, see OAuth 2.0 Account Link and OAuth Account Link.

Before you can use this component in a skill, you must do the following tasks:

  1. If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
  2. Add a client-credentials authentication service for the identity provider, as described in Authentication Services.
Property Description
Authentication Service The name of the client-credentials service that you created in the Authentication Services UI for the OAuth2 identity provider.
Access Token Variable Name Specifies the variable to store the access token in. You can declare it in the context node as a variable, a string, or another supported variable type. It also can be a user-scoped variable. For example: user.accessToken.
Multi-Scope Access Token Variable Name Field reserved for future multi-scope access token support.

This component doesn't have any actions. To handle system problems that might occur, add a next transition that goes to a state that can handle such errors.

Reset OAuth 2.0 tokens

Use this component to revoke all the logged-in user's refresh and user access tokens from the identity provider that the authentication service represents. It also removes the refresh tokens from the database. To use this component, you must provide the identity provider's revoke refresh token URL in the Authentication Service UI.

The skill must include a state that uses the OAuth 2.0 Account Link component for the same authentication service, and it must be invoked before the state that uses this component.

Property Description
Authentication Service The name of the service that you created in the Authentication Service UI for the OAuth2 identity provider. This service must have a valid revoke refresh token URL.

This component can return the following action:

Action Description
noRefreshTokenFound The authentication service doesn't have any refresh tokens for the user.

Flow Control Templates

Switch

Use this component to switch states based on a variable value.

This component determines an execution path by resolving a variable or expression and then triggering a corresponding transition action that is mapped to a state in the flow.

You define and map the transition actions on the Transitions tab of the property inspector.

Property Description
Variable A variable, the value of which is used to determine which transition action to trigger.
Expression A FreeMarker expression used to determine which transition action to trigger. For example, the expression ${((user.lastOrderNumber)?has_content)} could be used to trigger the True transition action if the user.lastOrderNumber variable has a value or trigger the False action if the variable has a null value.
Invoke Flow

With this component, you call a child flow from the current flow, optionally passing in input parameters. When the child flow completes, it returns an action and optional output parameters to its parent flow.

The transition actions that can be set depend on the actions that are set in the child flow's End Flow component.

Property Description
Flow The name of the flow to be invoked.
Input Parameters Parameters that are passed to the invoked flow. The values can include Freemarker expressions.
Output Parameters Parameters that can be returned from the invoked flow when it completes. The Value of the parameter should be the name of a variable in the current flow that is used to store the value of the parameter when it is returned from the invoked flow.
Invoke Skill

With this component, you call a different skill's flow, optionally passing in input parameters. When the called flow completes, it returns an action and optional output parameters to the calling flow.

Before you use this component, there must a public flow available in the skill you are calling. See Invoke Another Skill from a Flow.

Property Description
Skill Name The name of the skill to be invoked. Only skills that have one or more public flows are shown.
Skill Version (This property appears once you have selected a value for Skill Name.) The version of the skill to use. If the target skill is in the same digital assistant as the current skill, this field will be disregarded and the version of the skill in the digital assistant will be used.
Flow Name (This property appears once you have selected a value for Skill Name.) The name of the flow to be invoked from the skill. Only skills that have been marked as public in the target skill are shown.
Input Parameters (This property appears once you have selected a value for Flow Name.) Parameters that are passed to the invoked flow. The values can include Freemarker expressions.
Output Parameters (This property appears once you have selected a value for Flow Name.) Parameters that can be returned from the invoked flow when it completes. The Value of the parameter should be the name of a variable in the current flow that is used to store the value of the parameter when it is returned from the invoked flow.
Use Mock Set to True if you need to temporarily use mock data for the output parameters. This enables you to continue developing and testing the flow if the target flow isn't yet available.
Mock Output Parameters If you need to temporarily use mock output parameters while developing the flow, enter each parameter on a separate line in the form:
ParamName: ParamValue
End Flow

This component is used to explicitly end a flow.

When this state is reached, all of the flow's variables are cleared and control is returned to the parent flow (or, if there isn't a parent flow, the Main Flow).

You don't need an End Flow state for a flow if you don't need to return parameters or actions from the flow to a parent flow or the Main Flow.

Property Description
Action The action returned to the calling flow, which can be used for setting transitions in the Invoke Flow component.
Action Values Should be set when the Action property contains a Freemarker expression and must contain a list of possible values of the resolved Freemarker expression.
Keep Turn When true, the dialog engine continues to execute the next state in the calling flow based on the transitions defined in the Invoke Flow component. This property is IGNORED when:
  • a child flow is running. When a child flow ends, Keep Turn is always true.
  • a root flow is running and no bot messages have been created yet in the turn. In this case, Keep Turn is always true. (This ensures the turn isn't released without the bot sending a message back to the user, which could give the user the impression that the bot is hanging.)
Output Parameters Parameters that can be returned to a parent flow when the current flow is completed.

Service Integration Templates

Agent Communication Template

This template consists of the Agent Initiation and Agent Conversation components. You use these components together to transfer a skill's conversation to an Oracle B2C Service agent.

  • The Agent Initiation component initiates the handshake with the agent-integration channel that's specified by the component's Agent Integration Channel property.
  • The Agent Conversation component manages the interchange between the skill and live agent.

This template is for conversations that originate in the skill. Do not use this template for conversations that originate in Oracle B2C Service chat, as described in The Digital Assistant as Agent Framework in Action.

Agent Initiation

Here are the Agent Initiation component properties:

Property Description
Agent Integration Channel Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the Agent Integration Channel property defined for the Agent Conversation component must all match.
Agent Actions A list of actions that the agent can trigger to terminate the chat and move the flow to the state defined for the transition action. In the customer service representative's console, these actions display as slash commands when the agent conversation is initiated, as shown in this example:
Here are the available actions that you can send to transfer the conversation
back to the bot. Prepend the action with a forward slash (for example, /actionName).
/OrderPizza : Order Pizza : Order a pizza.
/ShowMenu : Show Menu : Show order options.
On the Transitions tab of the Agent Conversation component, you need to manually enter these actions and map them to the appropriate states.
Subject The subject line that displays in the agent's console after the hand off to the agent platform. By default, this is the last customer message stored in the system.nlpResult variable (which you can access with the expression ${skill.system.nlpresult.value.query}), but you can also define this using a variable that you set earlier in the flow. For example, you can define a string type variable whose value gets set prior to the Agent Initiation component:

A customer needs help regarding ${flow_variable.value}

Chat Response Variable Names the map variable that holds the agent response information. After the Agent Initiation component connects successfully, the map contains the following properties:
{
  "sessionID": "string", // agent session id

  "completedSurveyID": {
    "id": "int"
  },

  "engagementID": { // survey id
    "id": "int"
  },

  "cancelledSurveyID": {
    "id": "int"
  }
}
Custom Properties A map that holds the incident ID, interface, contact, or custom fields (or a combination thereof) to pass to the service. To reference a map variable, use a value expression like this: ${mapVariableName.value}. See Pass Customer Information to a Live Chat.
Queue ID The ID of the queue that the component must use to determine whether the specified Allow Transfer If condition is met. This must be the ID of the queue that the Oracle B2C Service chat rules will route that conversation to.

This property is ignored if the Allow Transfer If property isn't defined.

Allow Transfer If Specifies the conditions under which the skill should transfer the chat session. The component uses the Queue ID value to identify the queue from which to obtain the statistics. You should verify that the chat rules will actually transfer the conversation to the identified queue, and not some other queue.
  • Agents Are Requesting New Engagements: This is the most restrictive set of conditions. The skill attempts to transfer the conversation only if there are agents who have requested new engagements (pulled chats) and are assigned to the specified queue or, if the chat server automatically pushes chats to agents, there are agents who are available to receive chats, haven't reached their maximum number of chats, and are assigned to the specified queue. With this option, the user doesn't have to wait too long before they speak to the agent.
  • Agent Sessions Are Available: The skill attempts to transfer the conversation if there are available agents who haven't reached their maximum number of chats and are assigned to the specified queue. The user may have to wait if the agents are involved in long-running conversations or are doing some post-chat follow-up.
  • Agents Are Available: The skill attempts to transfer the conversation if there are any agents online who are assigned to the specified queue regardless of whether they have reached their maximum number of chats or are requesting new engagements. With this option, the users may have long waits.

If the specified condition is not met, the component returns the rejected action.

When you include this property, you must also include the Queue ID property.

Transcript Date/Time Format The format for the date and time in the conversation transcript messages that are forwarded to the agent. Refer to the DateTimeFormatter Java class for valid patterns. Example: dd/MM/yyyy HH:mm. Defaults to yyyy-mmm-ddThh:mm:ssZ.
Transcript Time Zone The Internet Assigned Numbers Authority (IANA) name of the time zone to use to format the conversation transcript using Transcript Date/Time Format property. If you don't define the Transcript Date/Time Format property, this property is ignored.
Transition Actions for Agent Initiation

The Agent Integration component returns the accepted, rejected, and error actions. These actions can each point to a different state, with the accepted action typically naming the state for the Agent Conversation component. You can set these transitions on the Transitions tab of the component's property inspector.

You can map the transitions for these actions on the Transitions tab of the component's property inspector.

Here are the descriptions of the actions:

Transition Action Description
accepted The handshake completed successfully and the state can transition to the state with the Agent Conversation component.
error There's a problem establishing a connection with Oracle B2C Service. For example, the password in the Agent Integration channel is no longer valid, or there's a problem with the Service Cloud server.
rejected Oracle B2C Service has rejected the connection request. Some of the reasons for rejecting a connection request are:
  • No agents are available (requires Allow Transfer If and Queue ID properties)
  • It's outside of the configured operating hours
  • It's a holiday
  • There's a problem with the chat server

Note that if you don't set the Allow Transfer If and Queue ID properties, the rejected action won't occur when no agents are available. Instead the transfer will remain in a wait condition.

Resource Bundle Entries for Agent Initiation

The Agent Integration component uses the following properties, which are stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_AgentInitiation_agentActionsMessage If any actions are specified in the Agent Actions property, the agent console displays this message before the list of actions. The default is:

\n Here are the available actions that you can send to transfer the conversation back to the bot. Prepend the action with a forward slash (for example, /actionName).\n

systemComponent_AgentInitiation_errorMessage The message to display when there's a problem establishing a connection with Oracle B2C Service. For example, the password in the Agent Integration channel is no longer valid, or there's a problem with the Service Cloud server. The default is:

Error transferring to agent. The reason is: {0}.

systemComponent_AgentInitiation_rejectedMessage The message that displays if the AgentInitiation handshake was rejected, such as if it's outside of the configured operating hours. The default is:

Agent rejected.

systemComponent_AgentInitiation_resumedMessage The message that displays when the customer's chat with the customer service representative resumes. The default is:

Resuming chat with agent

systemComponent_AgentInitiation_waitingMessage The message that displays while customers wait to connect to an agent. The default is:

Agent chat session established, Waiting for agent to join.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Agent Conversation

Here are the Agent Conversation component properties:

Property Description
Agent Integration Channel Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the Agent Integration Channel property defined for the Agent Integration component must all match.
B2C Wait Message Override Text to override the B2C wait message that provides an estimate of the time a user will have to wait to speak to an agent.
Transition Actions for Agent Conversation

The Agent Conversation component can trigger the following actions:

  • The built-in expired, agentLeft, error, and waitExpired actions.
  • Any action from the Agent Initiation component's Agent Actions property.

You need to include a next transition as well, because a customer might enter one of the exit keywords (defined in the systemComponent_AgentConversation_exitKeywords resource bundle entry) to leave the chat before any of these actions can get triggered.

You can map the transitions for the actions on the Transitions tab of the component's property inspector.

Note

The actions from the Agent Initiation component's Agent Actions property do not appear in the dropdown list for actions when adding them on the component's Transitions tab, so you need to enter them manually.

Here are the descriptions of the built-in transition actions:

Action Description
agentLeft The agent terminated the session without using a slash action (for example, /Order). Alternatively, the session ended because there was no activity within the time specified by the Oracle B2C Service CS_IDLE_TIMEOUT configuration and that configuration is less than the Session Expiration setting for the agent-integration channel. See the expired action for more information.

Note that this action is not returned when the user leaves the conversation by entering an exit keyword. In that case, the flow transitions to the state that's named by the next transition, or, if there is no next transition, to the next state in the flow.

error

There is a problem connecting to the live agent service.

expired

If the Oracle B2C Service CS_IDLE_TIMEOUT is equal to or more than the Session Expiration setting for the agent-integration channel, then this action is triggered when neither the end-user nor the agent sends a message within the session expiration limit. If CS_IDLE_TIMEOUT is less than the Session Expiration setting for the agent-integration channel, and there is no activity, then Oracle B2C Service terminates the chat and the agentLeft action is triggered instead.

By default, CS_IDLE_TIMEOUT is 10 minutes.

The expired action isn't returned when the conversation concludes because the Service Cloud USER_WAIT_QUEUE_TIMEOUT was exceeded. Consider setting this configuration to a high value, such as 7200 seconds (2 hours).

To view or change your Oracle B2C Service instance's settings, open the Desktop Console, click Navigation, click the first Configuration item in the menu, and click Configuration Settings. Then search the for the setting in the Chat folder.

waitExpired The chat request expired while waiting for an agent. This happens when the wait time exceeds the value in the chat client's USER_WAIT_QUEUE_TIMEOUT setting.
Resource Bundle Entries for Agent Conversation

The Agent Conversation component uses the following resource bundle entries:

Resource Bundle Key Description
systemComponent_AgentConversation_conclusionMessage An automated message sent to the customer when either the user enters an exit keyword, the agentLeft action is triggered, or the agent terminates the conversation without sending one of the Agent Actions. The default is:

Chat session ended. Thanks for chatting with us.

systemComponent_AgentConversation_errorMessage The message that the chat displays if there is a problem with the connection to Oracle B2C Service. The default is:

Chat session error. The reason is: {0}.

systemComponent_AgentConversation_exitKeywords A comma-delimited list of typical exit words used by a customer to end the conversation with the live agent. The default is:

bye, take care, see you, goodbye

systemComponent_AgentConversation_expiryMessage The message that displays when the expired action is triggered. The default message is:

Chat session expired. Thanks for chatting with us.

Note that the conclusionMessage is not output if the expiryMessage is output.

In addition, this message isn't output when the conversation concludes because the Service Cloud USER_WAIT_QUEUE_TIMEOUT was exceeded.

systemComponent_AgentConversation_userLeftMessage The message shown when the user has exited the chat. The default message is:

User left the chat.

systemComponent_AgentConversation_waitExpiryMessage The message that's shown to the user when the chat expires while waiting for an agent. The default is:

The request for live chat expired while waiting for an agent.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Agent Transfer

You use the Agent transfer component in DA-as-agent digital assistants to transfer the conversation back to the chat service. The conversation will be routed to a live agent per the chat rules that have been configured in the chat service.

This component is for conversations that originate in a service chat, as described in The Digital Assistant as Agent Framework in Action. For conversations that originate in the skill, use the Agent Communication template instead.

Property Description
Maximum Wait Time (Seconds) The maximum number of estimated wait seconds that are allowed. When the chat service receives the transfer request, it responds with the estimated wait time. If this value exceeds Maximum Wait Time (Seconds), then the rejected action occurs. This property defaults to -1, which means that there's no maximum wait time. When set to -1, the digital assistant transfers the user to a human agent regardless of what the estimated wait time is.

Note that the rejected action is based on the estimated wait time and not the actual wait time. After the conversation is transferred, the digital assistant doesn't have control over the conversation, nor does it have access to information about it. Therefore, it's possible for the actual wait time to exceed the estimated wait time.

Maximum Engagements In Queue The maximum number allowed for engagements waiting in the destination queue. When the chat request is sent, the chat service responds with the current number of engagements waiting in the queue. If this value exceeds Maximum Engagements In Queue, then the rejected action occurs. Defaults to -1, which means that there's no engagement limit. Note that for B2B Chat, the response is always 0, so this property is of no value for B2B.
Agent Availability StatusVariable The name of the variable of type map to use to store the agent availability status information. No information is stored if the property is not specified. To reference a map variable, use a value expression like this: ${<mapVariableName>.value.<key>}. For example, agentStatus.value.expectedWaitMinutes.

To learn about the values returned in this variable, see Agent Transfer Condition.

Allow Transfer If Specifies the conditions under which the skill should transfer the chat session.
  • Agents Are Requesting New Engagements: (default) For Oracle B2C Service agents who must pull chats (request new engagements), this is the most restrictive set of conditions, and the user doesn't have to wait too long before they speak to an agent. The skill attempts to transfer the conversation only if there are agents who have requested new engagements. In all other cases, this option has the same behavior as Agent Sessions Are Available. Don't use this option for Oracle Fusion Service because, the total agents requesting new engagements for that service is always 0.
  • Agent Sessions Are Available: The skill attempts to transfer the conversation if any of the available agents have not reached the maximum number of chats that they are allowed to have at one time. The user may have to wait if the agents are involved in long-running conversations or are doing some post-chat follow-up.
  • Agents Are Available: The skill attempts to transfer the conversation if there are any agents online regardless of whether they have reached their maximum number of chats or are requesting new engagements. With this option, the users may have long waits.

If the specified conditions aren't met, then the rejected action occurs.

Custom Properties A map that holds information to pass to the service.
Transition Actions for Agent Transfer

The Agent Transfer component has some built-in transaction actions that it can return.

You can map the transitions for these actions on the Transitions tab of the component's property inspector.

Action Description
accepted The accepted transition is set when the chat is successfully transferred to a queue.

Note that after a chat request is accepted, the flow must end with an End Flow state.

rejected The rejected transition is set when one of the following occurs:
  • The allowTransferIf conditions weren't met.
  • The estimated wait time exceeds maxWaitSeconds
  • The number of engagements in the queue exceeds maxEngagementsInQueue.
error The error transition is set when there's a system error that prevents the transfer to a human agent.
Resource Bundle Entries for Agent Transfer

The Agent Transfer component also uses the following properties, which are stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_AgentTransfer_acceptedMessage The message that's shown to the users whenever a human agent accepts the chat request. The default is:

The chat has been transferred to another agent.

systemComponent_AgentTransfer_errorMessage The message that's shown to the user when a system error occurs while transferring the chat session to an agent. The default is:

We were unable to transfer you to another agent because there was a system error.

You can set the property to a blank or empty string to suppress message output.

systemComponent_AgentTransfer_rejectedMessage The message that's shown to the users whenever one of the following occurs:
  • The Allow Transfer If conditions weren't met.
  • The estimated wait time exceeds the Maximum Wait Time (Seconds) value.
  • The number of engagements in the queue exceeds the Maximum Engagements In Queue value.

The default message is: Agent rejected.

You can set the property to a blank or empty string to suppress message output.

systemComponent_AgentTransfer_waitingMessage The message that's shown to users when they're transferred to a queue. The default message is:

Agent chat session established. Waiting for agent to join.

You can set the property to a blank or empty string to suppress message output.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Agent Transfer Condition

You can use the Agent Transfer Condition component in DA-as-agent digital assistants to determine whether agents are available and, if so, the expected wait time.

You use the component's properties to specify the transfer conditions, and it returns an action that indicates whether the conditions were met. In addition, it sets the values of the named context map variable.

Property Description
Custom Properties A map that holds information to pass to the service. See Pass Information to the Service.
Maximum Wait Time (Seconds) The maximum number of estimated wait seconds that are allowed. When the chat service receives the request, it responds with the estimated wait time. If this value exceeds Maximum Wait Time (Seconds), then the conditionsNotMet action occurs. This property defaults to -1, which means that there's no maximum wait time.

Note that the conditionsNotMet action is based on the estimated wait time and not the actual wait time.

Maximum Engagements in Queue The maximum number allowed for engagements waiting in the destination queue. When the request is sent, the chat service responds with the current number of engagements waiting in the queue. If this value exceeds maxEngagementsInQueue, then the conditionsNotMet action occurs. Defaults to -1, which means that there's no engagement limit.
Agent Transfer If Specifies the base set of conditions that must be met.
  • Agents Are Requesting New Engagements: (default) For B2C agents who must pull chats (request new engagements), requires that agents have pulled chats. In all other cases, this option has the same behavior as Agent Sessions Are Available.
  • Agent Sessions Are Available: Requires that agents are requesting chats.
  • Agents Are Available: Requires that at least one agent is active regardless of whether they have reached their maximum number of chats or are requesting new engagements.

If the specified conditions aren't met, then the conditionsNotMet action occurs.

Agent Availability Status Variable The name of the variable of type map to use to store the agent availability status information. No information is stored if the property is not specified. To reference a map variable, use a value expression like this: ${<mapVariableName>.value.<key>}. For example, agentStatus.value.expectedWaitMinutes.

Here is the structure of the value of Agent Availability Status Variable and the information stored in it:

queueId (integer, optional): The engagement queue ID,
expectedTotalWaitSeconds (integer, optional): Expected wait time in the queue in seconds
        ( -1 if there's inadequate information, zero or greater otherwise ).,
expectedWaitSeconds (integer, optional): The number representing the "ss" segment of the expected wait time of format mm:ss 
        ( -1 if there's inadequate information, zero or greater otherwise ).,
expectedWaitMinutes (integer, optional): The number representing the "mm" segment of the expected wait time of format mm:ss 
        ( -1 if there's inadequate information, zero or greater otherwise ).,
availableAgentSessions (integer, optional): Total number of sessions available across all agents.,
totalAvailableAgents (integer, optional): Total number of agents whose status is available.,
totalUnavailableAgents (integer, optional): Total number of agents whose status is unavailable.,
totalAgentsRequestingNewEngagement (integer, optional): Total number of agents who are available and have capacity.
outsideOperatingHours (boolean, optional): True if outside operating hours. False if inside operating hours.,
engagementsInQueue (integer, optional): The number of engagements currently in the queue.
sessionId (string, optional): The session ID.,
clientId (integer, optional): The client ID.

Tip:

Here's a suggested resource bundle definition that you can use to display the expected wait time:
This might take {minutes, plural,
     =-1 {}
     =0 {}
     =1 {1 minute and }
     other {# minutes and }
}{seconds, plural,
     =-1 {a while}
     =0 {{minutes, plural,
          =0 {a short wait time}
          other {0 seconds}
        }}
     =1 {1 second}
     other {# seconds}
} to connect. Are you willing to wait?
Transition Actions for Agent Transfer Condition

The Agent Transfer Condition component has some built-in transaction actions that it can return.

You can map the transitions for these actions on the Transitions tab of the component's property inspector.

Action Description
conditionsMet The conditionsMet transition is set when when it's inside business hours and the maxWaitSeconds, maxEngagementsInQueue and allowTransferIf conditions are met.
conditionsNotMet The conditionsNotMet transition is set when one of the following occurs:
  • It's outside business hours.
  • The allowTransferIf conditions weren't met.
  • The estimated wait time exceeds maxWaitSeconds
  • The number of engagements in the queue exceeds maxEngagementsInQueue.
error The error transition is set when there's an issue with the connection to the agent chat service during the agent conditions check.

You can set these transition actions on the Transitions tab of the component's property inspector.

Resource Bundle Entries for Agent Transfer Condition

The Agent Transfer component also uses the following property that is stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_AgentTransferCondition_errorMessage The message that's shown to the user when a system error occurs while transferring the chat session to an agent. The default is:

We were unable to check the agent transfer conditions because there was a system error.

You can set the property to a blank or empty string to suppress message output.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Call REST Service

Use this component to send an HTTP request to a REST endpoint that you configured in the API Services settings.

Here are the component properties:

Property Description
REST Service The name of the API Settings REST service that defines the configuration for the endpoint. See Add a REST Service for an Endpoint.
Authentication Type The authentication type that's defined for the REST service. You only can change this value from the REST Services tab.
Endpoint The URI that's defined for the REST service. You only can change this value from the REST Services tab.
Method Select which configured method to use for this REST call.
Request Body For POST, PATCH, and PUT requests, specify the request body to send with the REST request.

Tip:

If the body contains FreeMarker expressions, then you can switch Expression to On to see FreeMarker syntax coloring. However, if you do so, JSON syntax validation is turned off.
Parameters For the path parameters that are in the endpoint, add a parameter of type Path, set the key to match the path parameter, and set the desired value. Note that if a path parameter is defined in the REST service configuration and you want to use that parameter's value, you don't need to add it to the component.

For query parameters that you want to pass in the REST request, add a parameter of type Query, set the key to match the query parameter, and set the desired value. Note that if a query parameter is defined in the REST service configuration and you want to use that parameter's value, you don't need to add it to the component.

Tip:

If the REST Services configuration set a query parameter that you don't want to use in this call, you can clear that parameter by setting its value to ${r""}.

After you edit the parameter, click Save button to add the parameter to the list.

Response Mode

Specify which response you want returned after the call completes:

  • Use Actual REST API Response: This returns the actual response from the REST service.

  • Always Use Static REST Response: This returns the static response that is configured on the REST Services tab. This response is helpful during development and test phases, among other uses.

  • Fallback Using Static Response: If the REST request is successful, then the REST response is returned. Otherwise, the static response that's configured on the REST Services tab is returned.

Note that if the REST service configuration doesn't have a static response, then the only choice is Use Actual Response.

Result Variable

The name of the map variable for storing the response data. The map will contain a responsePayload property for the response body and a statusCode property for the status code. How the response body is stored in the variable depends on the whether the response is a JSON object, JSON Array, or plain text (string):

  • JSON Object: The object is stored in the responsePayload property.

  • JSON Array: The array is stored in theresponsePayload.responseItems property.

  • Plain Text: The text is stored in the responsePayload.message property.

The component returns these actions:

Action Description
success The response status code is in the 100-399 range.
failure The response status code outside the 100-399 range.

To learn more, see Access Backends Using the REST Service Component.

Knowledge Search

Use this component to search Oracle B2C Service Knowledge Foundation or Oracle Fusion Service Knowledge Management for information about a given search term and to display the results.

For Oracle B2C Service, the search results depend on whether the answers are public and what the access level, product, or category settings are.

Note that you must create a knowledge search service before you can use this component. See Add a Knowledge Search Service.

Here are the Knowledge Search component properties:

Property Description
Search Service Name The name of the knowledge search integration as configured in Settings.
Term to Search For The text to use as the search term for the knowledge search invocation. A search term is required for Oracle Fusion Service Knowledge Management. For Oracle B2C Service Knowledge Foundation, it returns the most popular articles if no search term is provided.

For search term techniques, see Use the System.KnowledgeSearch Component.

Text to Display Ahead of Results The text to output before the search result is displayed.

If this property is On, the KnowledgeSearch - searchPrelude value in the configuration resource bundle is used. The default is Off, meaning no text is displayed.

Maximum Number of Results The maximum number of results to display.

The default is 10.

Preferred Version of Results Oracle B2C Service only: The preferred version to return when there are multiple versions for a result. You can set this property to either Answer or Special Response.

The default version is Answer.

Only Show Preferred Version

Oracle B2C Service only: When True, only results that are available in the preferred version (as set by the Preferred Version of Results property) should be displayed.

When False, it first includes all matching answers that are available with the version set in the property. If the number of included answers is less than the limit, then it continues to include answers in the non-preferred version until the limit is met.

The default is False.

Web Article Link Label The label to use for the result card's URL action (button) that links to the web version of the information.

If you set this property to Off, the web article link button is not displayed and the full text is output instead. This is not recommended if you have very long articles that would be hard to read in a typically-sized skill widget. The default is On, which means the KnowledgeSearch - resultLinkLabel value in the configuration resource bundle is used.

Web Search Page Link Label

Oracle B2C Service: The label to use for the card message payload action that's linked to the web page with the full search result list.

Oracle Fusion Service: The label to use for the card message payload action that's linked to home search page.

If this property is On, the KnowledgeSearch - searchLinkLabel value in the configuration resource bundle is used. The default is Off, meaning the card message does not display the action.

Card Layout Specifies whether to display the result cards vertically or horizontally. Defaults to horizontal.
Search Using Locale Defaults to the value of the profile.locale variable.

For Oracle B2C Service multi-interface knowledge integration services, the five-character ISO or BCP locale code that specifies which interface to use to perform the search (e.g. en_GB). If there isn't an interface that supports the locale, then the default interface is used. See Implement Multi-Lingual Knowledge Search.

For Oracle Fusion Service it fetches the articles that are associated with the specified locale. If matching articles don't exist for the locale, it returns noResult.

Result Filters A list of search result filters. The allowable filter types are Product and Category. Each of them allows only one filter declaration.
Custom Properties Oracle B2C Service only: A map of key/value pairs to send to the search service. Currently, this property supports only the word_connector key. You use the word_connector property set to AND to prepend every word in the search term with +.
Transition Actions for Knowledge Search

The Knowledge Search component has some built-in transaction actions that it can return.

You can map the transitions for these actions on the Transitions tab of the component's property inspector.

Action Description
resultSent The search returned at least one result.
noResult There were no results for the search term.
serverError An error occurred on the knowledge search service's server during the invocation, such as a server error fault or an unexpected error fault.

When this error occurs, the error message is stored in system.state.<state-name>.serverError.message.

Resource Bundle Entries for Knowledge Search

The Knowledge Search component also uses the following properties, which are stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_KnowledgeSearch_defaultAttachmentLabel The default label to use for the result card's URL action that is linked with an attachment of the search result if that attachment does not have a display name configured already. When used, it's appended by an index number. For example, if the second attachment doesn't have a display name, then the default attachment label is appended with 2.

The default is Download.

systemComponent_KnowledgeSearch_noResultText The text to output when no search result is available.

The default is:

Sorry, no result was found in the knowledge search.

systemComponent_KnowledgeSearch_resultLinkLabel The label to use for the result card's URL action that's linked to the web version of the knowledge article.

The default is View Results.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Incident Creation

You use the Incident Creation template to create an incident report on a customer service site. Note that you must create a customer service integration from the Settings > Additional Services > Customer Service Integration page before you can use this component in your instance.

Property Description
Incident Service Name The name of the integration as configured in Settings > Additional Services > Customer Service Integration.
Subject of Incident The text for the subject of the incident.
Attachment URL The URL of a document or image that's related to the incident. Note that adding attachments is not supported for DA as Agent skills.
Agent report filter (For Oracle Fusion Service incidents), text to filter the incidents.
Add chat transcript to the incident (For Oracle Fusion Service incidents.) When set to True, the chat transcript is added to the incident. (Insights must be enabled for the skill for this to work.)
Custom Fields Contains the description key/value pair and, optionally, the contactInfo key/value pair, which can contain a map of additional details about the incident.

The key/value pairs are passed unvalidated as a text version of the object and inserted into the incident message as a private note.

Contact Properties Key/value pairs that contain the information that's required to look up or create customer service contact information. It must contain email, and can optionally contain firstName and lastName.

If email isn't provided, then you must provide both firstName and lastName.

String context variable to store the incident number The name of the string context variable in which to store the incident number.
Intelligent Advisor

Use this component to access an Oracle Intelligent Advisor interview from a skill.

You must create an Intelligent Advisor service integration before you can use this component. See Add an Intelligent Advisor Service. In addition, the interview must have been deployed to the Intelligent Advisor Hub and activated on the chat service channel. The interview must be for anonymous users. You can't access interviews for portal users or agent users.

You can use the component's properties to specify the following interview settings:

  • Whether to display the titles and the explanation
  • The labels for the yes, no, and uncertain buttons
  • The strings that the user enters to reset, go back to the previous question (undo), and exit the interview
  • The text to display at the end of the interview
  • How to phrase the question about whether to display the explanation
  • The string the user enters to indicate they are done uploading files
  • The attribute values and connector params to pass to the interview
  • The project locale to use
Intelligent Advisor Properties

Here are the Intelligent Advisor component properties:

Property Description
Intelligent Advisor Service Name The name of the Intelligent Advisor service as configured in Settings > Additional Services.
Deployment Project Name The name of the active deployment project on the Intelligent Advisor Hub.
Variable for Interview Results The name of a list variable in which to store the interview's attribute values upon return from the interview to the skill. The attribute values are stored as an array of key/value pairs.
Hide All Screen Titles Indicates whether to hide all the screen titles in the interview.
Show Explanation Specifies whether to show the Intelligent Advisor explanation. The allowed values are never, always and ask.

If you set to ask, then use the systemComponent_IntelligentAdvisor_explanationAskLabel resource bundle entry to specify the text for asking if the user wants to see the explanation.

If you don't define this property, the behavior defaults to never.

Seed Data A map of Intelligent Advisor attribute names and values to pass to the interview. For date and time attributes, use the standard Intelligent Advisor date and time formats. For example: start_date: "2010-01-31".

The attribute that you are passing the value to must have the Seed from URL parameter option enabled in Policy Modeling. See Pass Attribute Values and Connection Parameters for details on working with Policy Modeling.

Connection Parameters A map of key-value connection parameters to pass upon the start of interview. This is typically needed for interviews with external data integration.
End Interview Text Label The label that's shown in the chat at the end of the interview. If set to Off, no message will be shown in the chat at the end of the interview. The default is On, meaning the systemComponent_IntelligentAdvisor_endLabel value in the configuration resource bundle is displayed at the end of the interview.
Remove HTML Tags From Output Indicates whether to remove the HTML markup from the text. The default is false.
Interview Locale The five-character ISO or BCP locale code (e.g. en_GB) used to specify the language that the interview should start with.

This property affects both the target interview and date and number resolution.

The component initiates the version of the named interview (deployment) that's associated with the language specified by the component's locale property. If there isn't a Hub deployment for the specified locale, then the component uses the default locale that's associated with the deployment.

For date and number input, the values are resolved per the DATE and NUMBER entity settings. When Consider End User Locale is switched to On for the entity, then the value is resolved for the locale that is specified by this property (or the default if not specified). See Locale-Based Entity Resolution.

This property defaults to the profile.locale value. If profile.locale doesn't have a value, then it uses the channel's locale.

Interview Expected Currency The ISO-4217 currency code for the currency that's used in the interview. When this code is specified, the user only can input currency values in the formats that are allowed for that currency. You can set this property to blank or null if the interview doesn't prompt for currency amounts or is not expecting any certain currency.
Resource Bundle Entries for Intelligent Advisor

The Intelligent Advisor component also uses the following properties, which are stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_IntelligentAdvisor_answerNotValid Message that's displayed for Intelligent Advisor interview inputs of type Masked when the user's answer doesn't conform to the specified input mask.
systemComponent_IntelligentAdvisor_defaultValue Text that's added to a question when the Intelligent Advisor interview input has a default value.
systemComponent_IntelligentAdvisor_doneHelp Help message that's displayed for Intelligent Advisor interview inputs of type Upload.
systemComponent_IntelligentAdvisor_doneLabel The text that the users type to indicate that they are done uploading a file.

The default is /done.

systemComponent_IntelligentAdvisor_endLabel Text to display in the chat at the end of the interview.

The default is Interview ended. You can set the property to "" to prevent text from being displayed.

systemComponent_IntelligentAdvisor_exitLabel The text that users type to indicate that they want to exit the interview.

The default is /exit.

systemComponent_IntelligentAdvisor_explanationAskLabel The question to ask when showExplanation is set to ask.

The default is Do you want to see the explanation?

systemComponent_IntelligentAdvisor_maskLabel Text that's added to a question to display the expected format for Intelligent Advisor interview inputs of type Masked Text Box.

The default is Answer format: {0}

systemComponent_IntelligentAdvisor_noLabel The label to use to represent Boolean FALSE values.

The default is No.

systemComponent_IntelligentAdvisor_numberMinMax Message that's displayed when the user enters a value outside of the specified range for an Intelligent Advisor interview input of type Slider.

The default is Enter a number between {0} and {1}.

systemComponent_IntelligentAdvisor_outOfOrderMessage Error message that's displayed when the user taps a button in a previous Intelligent Advisor interview message.

The default is:

You have already answered this question. When you want to step backwards to change a previous answer, say {0}.

systemComponent_IntelligentAdvisor_resetLabel The text that users type to indicate that they want to go back to the first question.

The default is /reset.

systemComponent_IntelligentAdvisor_resumeSessionPrompt Question that is asked if the user starts an interview that they had previously left before the interview completed.

The default is:

Do you want to restart the interview from where you previously left?

systemComponent_IntelligentAdvisor_uncertainLabel The label that the user can type if they don't know the value. This label appears for optional Boolean radio buttons.

The default is Uncertain.

systemComponent_IntelligentAdvisor_undoLabel The text that the users type to indicate that they want to go back to the previous question.

The default is /back.

systemComponent_IntelligentAdvisor_yesLabel The label to use to represent Boolean TRUE values.

The default is Yes.

systemComponent_IntelligentAdvisor_yesNoMessage Message that's displayed when the user enters an invalid answer for Intelligent Advisor interview inputs of type Boolean Radio Button.

The default is:

Enter either {0} or {1}

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Webview Component

The Webview component opens a webview within your skill, or for skills that run in a web channel, in an browser tab.

Property Description
Webview Component Service The name of the webview component service.
Inputs for Service A comma-separated list of variable names. These variable names are the parameters that are sent to the webview from the skill.
Output for Service The name of the variable (a string value) that identifies the webview payload that’s returned to the bot after the user completes his or her interactions within the webview.

Because the payload is stored in this variable, which you can access at a later point in your dialog flow definition. For example, you can reference this in an output component.

Component Service URL The base URL to which the variable names set for the Inputs to Service property are sent as parameters. This is a base endpoint provided by a web server. This property is not supported in the current release (you configure this now in the Create Service dialog). However skills built with prior versions will still function.
Image URL The URL of the image that accompanies a prompt.
Authorization Token The authorization token that’s sent with requests to the URL specified by the Component Service URL property. This property is the form of Basic <token> or Bearer <token>.
Query Parameters for Service The stringified JSON object whose key-value pairs are the query parameters that are appended to the POST request.
Transition Actions for the Webview Component

The Webview component has some built-in transaction actions that it can return.

You can map the transitions for these actions on the Transitions tab of the component's property inspector.

Transitions Description
cancel Triggered when the user taps the Cancel button.
system.textReceived Triggered when the user enters text rather than tapping one of the buttons.
unexpectedAction Triggered when the user taps a button from a previous reply.
Resource Bundle Entries for the Webview Component

The Webview component also uses the following properties, which are stored in the skill's resource bundle:

Resource Bundle Key Description
systemComponent_Webview_cancelLabel The label of the cancel button to leave this state without invoking the webview.

The default is Cancel.

systemComponent_Webview_linkLabel The label of the button to invoke the webview.

The default is Tap to continue.

systemComponent_Webview_prompt The message for the user to tap on the link to invoke the webview.

The default is Please tap on the link to proceed.

See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.

Notify User

You use this component to send a notification to a user when a Cloud-based event of a type that has been registered in Oracle Digital Assistant has occurred. See External Events for information on registering event types and configuring a digital assistant to consume the event.

Property Description
User ID (Optional) If you want to dynamically determine which user to notify of the event when it is received, enter the unified user ID that is returned from the user's messenger service. If this value is set, when the event is generated, Digital Assistant will pass this ID to the messenger service to get user data, such as the channel, and the channel's ID for the user so that it can notify that particular user. This property only works for Slack and Twilio channels and for users that have already interacted with Digital Assistant.
Notification Message The message that is returned to the user.

In the message, you can make use of expressions in the following formats to access information from the event:

  • Event data content:
    ${skill.system.event.value.application.data.<propertyName>}
  • Event context content:
    ${skill.system.event.value.application.context.<propertyName>}
Publish Event

You use this component to externally publish a Cloud-based event of a type that has been registered in Oracle Digital Assistant. See External Events for information on registering event types and configuring a digital assistant to publishing and consuming events.

Property Description
Name The name of the type of the event that is to be published
Data The payload of the event in JSON format.

Here's an example payload that could be used as the value for the Data property:

{
    "size": "Large",
    "type": "Veggie"
}

Component Changes in the Visual Flow Designer

In the Visual Flow Designer, a number of components that were part of the YAML-based dialog flow editor have changed or are no longer available. Here are the key changes:

  • The ConditionExists and ConditionEquals components aren't supported. You can use the Switch component instead.
  • The Text, List, and Output components aren't supported. Instead you can use the Send Message, Ask Question, and Resolve Composite Bag templates, as well as the templates in the User Messaging category, most of which are templates based on the Common Response component.
  • The Resolve Entity and Common Response components will now always attempt to slot entities from the system.nlpresult variable.

    As such the nlpResultVariable property is no longer necessary and has been removed from those components.

  • The autoNumberPostbackActions variable and component property are not supported. Auto-numbering can be configured at the skill level using the skill's Enable Auto Numbering on Postback Actions in Task Flows configuration setting (or at the digital assistant level using the digital assistant's Enable Auto Numbering on Postback Actions setting).
  • The autoTranslate variable and the translate component property are not available. They are replaced by the Translate User Input Message and Translate Bot Response Message properties, which are set at the skill level.
  • The transitionAfterMatch component property for the Common Response and Resolve Entity components is no longer supported. To get this functionality, you can use an entity event handler.
  • The value of the useFullEntityMatches property for the Common Response and Resolve Entity components now defaults to true.

    This means that the value of the resolved entity is returned as an object and you need to specify the appropriate object property to return a string value.

  • The value of the cancelPolicy property for the Common Response and Resolve Entity components now defaults to immediate (instead of lastEntity).

    This means that the cancel transition occurs after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide maxPrompts value has been met.

  • The Insights component properties insightsInclude and insightsEndConversation are not supported. The modular flows already delineate the conversation, so insightsEndConversation is not needed. A conversation ends when the last state of a top-level flow has been reached.

Migrate to Visual Dialog Mode

You can migrate a skill with an OBotML-authored dialog flow to a Visual Flow Designer skill by clicking Migrate to Flow Designer in the dialog flow editor.
This is an image of the Migrate to Flow Designer button

However, before you take that step, you may need to make some adjustments to the skill or the OBotML definition to ensure the following:
  • The skill is Version 21.12 or higher
  • There are no transitions that use FreeMarker to express states. For example, a transition like equal: "${system.actualState}" will prevent migration.
  • There are no System.QnA states. Replace Q&A content with answer intents.
Note

If the OBotML definition has 50 or more states, the migration will still proceed, but will not result in an intent flow populated with states. It will only contain the flow-level variables.
To locate any issues within the OBotML definition, first validate your skill, then review the Findings' Migrate window for the validation errors This is an image of the warning icon. that you must fix before migration, the warnings This is an image of the error icon. , and the informational messages This is an image of the tip icon that describe how the states with deprecated properties or components, such as System.ConditionEquals, System.ConditionExists, System.List, System.Text and System.Intent will be interpolated in the Visual Flow Designer.
Description of migration_findings.png follows

What Happens When You Migrate to a Visual Flow Designer Skill

A successful migration results in a new skill. By default, its version is noted as Version 1.0–migrated in the tile. (You can change the value of the skill version in the Migration dialog).
An image of a Visual Flow Dialog-versioned skill tile

The new version of the skill is accompanied by a migration log that documents that conversion of deprecated properties and components.
8:5 The variable 'iResult' will not be migrated. In visual dialogs, the intent resolution is done in the dialog engine and the NLP result is available through the 'skill.system.nlpresult' variable.
9:5 The variable 'rb' will not be migrated. This variable is pre-defined now.
84:5 The state 'welcome' uses the 'System.Output' component, which is obsolete in visual dialog mode. It will be replaced with a 'System.CommonResponse' component.
92:5 The state 'getIntent' uses the System.Intent component, which is obsolete in visual dialog mode. It will be replaced with a System.Switch component. Intent resolution in visual dialog mode happens automatically when starting a new session and after ending a root flow.
115:7 The property 'values' in the state 'startDetermineWineType' is obsolete in visual dialog mode and will be removed.
122:9 The 'NONE' transition action in the state 'startDetermineWineType' is obsolete in visual dialog mode and will be removed. The 'next' transition is used instead.
... 

The Visual Flow Designer skill contains both a main flow and a single intent flow. All of the intents are mapped to this flow. Within this flow, the intent routing is accomplished using a Switch state where the intent names have been transcribed as action transitions. The routing logic is executed using ${skill.system.event.value.intent.intentName}.

Testing of Visual Flow Designer iteration of the flow may reveal that the migration introduced regressions. For example, changes to the transition definitions may have disconnected segments of the flow. You may also find that the single flow created from the migration is unwieldy. In this case, you can modularize the functionality by copying states into a separate flow.

Migration Summary

OBotML Artifact(s)... ...Become the Following In Visual Flow Designer
Intents Intent events and unresolvedIntent are all mapped to the single intent flow.
Context Variables Flow-level variables. The rb variable is not migrated; the system.rb variable is used instead.
System.Intent states Transcribed as a Switch state. The intents are named as action transitions. The routing is determined using ${skill.system.event.value.intent.intentName}. The transitions that point back to a System.Intent state route to the End Flow state for intent matching.
System.List and System.Text states Common Response > Resolve Entities states
System.Output states Common Response states
System.ConditionEquals and System.ConditionExists states Switch states
Component properties:
  • nlpResultVariable property in System.CommonResponse and System.ResolveEntities
  • cancelPolicy in System.ResolveEntities
  • autoNumberPostbackActions
  • translate
  • values in System.Switch component
  • insightsIncludes
  • insightsEndConversation
These properties are removed. cancelPolicy in Resolve Entities now defaults to immediate
FreeMarker expressions used in OBotML, entity properties and bag item properties:
  • system.errorState
  • system.errorAction
  • system.actualState
  • system.expectedState
  • system.requestedState
  • system.errorState
  • rb
Equivalent expressions in Visual Flow Designer
  • skill.system.event.value.dialogError.errorState
  • skill.system.event.value.dialogError.errorMessage
  • skill.system.event.value.outOfOrderMessage.outOfOrderState
  • skill.system.event.value.outOfOrderMessage.currentState
  • skill.system.event.value.authorizeUser.requestedState
  • skill.system.event.value.outOfOrderMessage.errorState
  • skill.system.rb
error transition system.dialogError transition action
attachmentReceived and locationReceived transition actions Removed
Transitions using FreeMarker expressions (when the FreeMarker expression can be resolved to an actual state). Switch states
return transitions Migrated to End Flow state
NONE transition in System.Switch next transition.
Custom component names The custom component name is prefixed with the custom component name. The two names are separated by a colon.
iteratorExpression The iteratorExpression property is added to the metadata when an iteratorVariable is used.
agentActions property of System.AgentInitiation Comma-delimited lists of action names are converted to an arrays with action, label, and description properties.

Import and Export Flows

You can import and export Visual Mode dialog flows using the Import Flow and Export Selected Flow options from the More menu.
Description of more_flow_options.png follows

Export Flows

You can export a flow by first selecting it, and then clicking More > Export Selected Flow. The exported dialog flow is a YAML representation of the dialog. This document named for the skill and flow and appended with -Flow ( PizzaSkill-pizza.ans.proc.veggiePizza-Flow.yaml, for example). Its YAML syntax conforms to Visual Dialog Mode, not the OBotML written for skills created in the YAML mode. When you export a flow, you export this document only. It will not be accompanied by any of the following dependencies, even if they are referenced.
  • The security service referenced by security component states.
  • Services for various service integration states
  • Translation services
  • Intents, entities, resource bundles
  • Referenced task flows
When imported, the flow will run properly if the skill already has the referenced artifacts. Otherwise, the import will throw validation errors.
Note

You can export any flow except for the main flow.
An example of the YAML representation of the Visual Dialog Mode is as follows:
name: "WineryChats"
trackingId: "D6BFE43B-D774-412A-91F6-4582D04B3375"
type: "task"
version: "2.0"
interface:
  returnActions:
  - "done"
variables:
- name: "redWineCard"
  type: "map"
  system: false
defaultTransitions:
  actions:
    system.outOfOrderMessage: "outOfOrderMessageHandler"
    system.startTaskFlow: "buildRedWineMenu"
states:
  buildRedWineMenu:
    component: "System.SetVariable"
    properties:
      variable: "redWineCard"
      value: 
        Cabernet Sauvignon:
          image: "https://cdn.pixabay.com/photo/2016/05/24/16/16/wine-1412603__340.jpg"
          price: 35
          description: "Flavor of dark fruits like black cherry and blackberry along with a warm spice, vanilla and black pepper"
          title: "Cabernet Sauvignon"
...

Import Flows

You can import a flow by clicking More > Import flow and then browsing to, and selecting, a YAML document formatted for the Visual Dialog Mode. These flows can be the YAML documents generated when you export a dialog flow (the ones with names formatted as <skill name> - <flow name> -Flow.yaml ), or they can be the YAML files located in the dialogs folder of an exported ZIP file for a skill built using Visual Dialog Mode. You can't import an OBotML document directly. You must migrate the skill first.

There are some exceptions to the flows that can import.
  • You can't import a main flow (the System.MainFlow.yaml file located in the dialogs folder of an exported ZIP file for a Visual Dialog Mode skill.
  • You can't import a flow that already exists in the skill or in your instance. If the flow already exists, you can upload the YAML document by changing the value for the name node.
    name: "WineryChats"
    trackingId: "D6BFE43B-D774-412A-91F6-4582D04B3375"
    type: "task"
    ...
    However, you may instead want to duplicate the flow (Menu > Duplicate Selected Flow) rather than edit the YAML.
You can successfully import a flow even if it references artifacts like entities, intents, resources bundles, or backend services that are not present in the skill. However, these imports will result in validation errors. This is an image of the warning icon.. To get a list of the validation errors in the Findings' Flow, click View validation findings in the error messages that displays after the import.
This is an image of the import flow validation error message.

Tutorials: Visual Flow Designer

You can get hands-on practice designing a dialog flow by following the Create a Dialog Flow with the Oracle Visual Flow Designer tutorial.

You can also learn some useful design practices by reading the Tour of the Visual Flow Designer Sample Skill article.