Before you Begin

This 30-minute tutorial shows you how to create a dialog flow declaratively using the Visual Flow Designer.

Background

In this tutorial, you're going to add an order pizza flow to an existing skill that already has a completed cancel order flow. Your order pizza flow will branch to this existing flow. This pizza skill is a simplified version of the PizzaSkill - Visual Flow Designer that's described in Tour of the Visual Flow Designer Sample Skill.

What Do You Need?

  • The starter skill, Visual_Flow_Designer_Starter_Skill.zip, which is included with this tutorial. Download this file to your local system.
  • Access to Oracle Digital Assistant Version 22.04 or higher

Explore the Starter Skill

If this skill is not already in your instance:

  1. Log into Oracle Digital Assistant.
  2. Click This is an image of the menu icon. in the top left corner to open the side menu.
  3. Expand Development and then click Skills.
  4. Hide the menu by clicking it again.
  5. Click Import Skill (located at the upper right). You will see a warning (Imported Ok, but note...). You can ignore this warning.
  6. Browse to, then select Visual_Flow_Designer_Starter_Skill.zip.

If the skill has already been imported and/or you will be sharing the instance with others who might do this tutorial, clone the skill:

  1. On the Skills page, within the tile for Visual_Flow_Designer_Starter_Skill, click the Options menu icon, and select Clone.
  2. In the Display Name field, enter <YourInitials>Visual_Flow_Designer_Starter_Skill.
  3. Select Open cloned skill afterwards. Then click Clone.

Review the Artifacts

    If it's not already open, open Visual_Flow_Designer_Skill by clicking the tile. Then take a look at the following artifacts.

  1. Intents This is an image of the Intents icon in the left navbar. -- Take a look at the pizza.reg.orderPizza, pizza.reg.cancelPizza, pizza.ans.calories, and ans.proc.vegetarianPizza intents. Note the conversation names for the pizza.ans.calories, and ans.proc.vegetarianPizza intents. In this tutorial, you'll either create flows for these intents, or reference them when you branch the dialog flow.
  2. Entities This is an image of the Entities icon in the left navbar. -- You'll declare variables for two of the composite bag entities: cbe.pizza, which supports the pizza menu, and cbe.confirmation, which is used to branch the flow. The resolution logic for cbePizza is executed through an entity event handler.
  3. Resource Bundles This is an image of the Resource Bundles icon in the left navbar. -- Following best practices, the prompts in this tutorial are executed through resource bundles, not through text strings. You'll reference the following resource bundles in your flow:
    Resource Bundle Key String
    answerIntentIntroMessage1 Hello! You were asking about
    answerIntentIntroMessage2 Here's your answer:
    cbe.confirmation.message Your order is on the way.
    cbe.confirmation.prompt1 You ordered a {0} {1} pizza. Is that right?
    pizza.messages.orderPizzaStart Hey, there! Let's get this order started!
    systemFlowName_ans.about.calories the calorie content of our pizzas
    systemFlowName_ans.proc.vegetarianPizza vegetarian pizzas
  4. Reference flows -- This skill includes a set of reference flows to help you out if you run into problems. These flows are meant only as guides, not as functioning flows. Because they are not mapped to any events or reference any variables, the Visual Flow Designer notes these flows as having errors This is an image of the Error icon.. You can ignore them.
    5. Description of reference_flows.png follows
    Description of the illustration

    Tip:

    You can use these flow as a quick reference. If you need a fully functioning skill, take a look at Completed_VFD_Skill. You can import this skill to your instance if it's not already there.

Create Skill-Level Variables

You're going to start off by declaring a variable for the cbe.pizza entity.
This variable will set the values for the pizza size and type. Because both the parent flow and the child flows need these values, you must create a skill-level variable so that all flows can access the values.

  1. Click Flows This is an image of the Flows icon. in the left navbar.
  2. Click Main Flow.
    3. This is an image of the Main Flow link.
  3. Click Skill Variables.
    4. This is an image of the Skill Variables link.
  4. Click Add Variable (located under Custom Variables).
    5. This is an image of the Add Variable button
  5. For the name, enter pizza.
  6. For the description, enter Resolves the pizza menu.
  7. Select Entity as the variable type, then select cbe.pizza as the entity name.
  8. Click Apply.
    9. Description of create_skill_variable_pizza.png follows
    Description of the illustration

Build the Answer Intent Flow

In this step, you're going to create an answer intent that handles user questions about calories and vegetarian options. In Visual Flow Designer, you don't need to create generic answer intent flow like this because the Main Flow presents answer intents automatically. But through the simple answer intent flow that you'll create in this step, you learn about creating and customizing a flow for a standard event, the group of Main Flow-level events for handling standard use cases like unresolved intent, answer intent, and dialog error.

  1. Click Add Flow.
    2. This is an image of the Add Flow button.
  2. In the Create Flow dialog, enter pizza.ans.genericHandler as the name.
  3. For the description, enter Generic answer intent flow. Then click Create.
    4. Description of create_generic_answer_flow.png follows
    Description of the illustration
  4. In the dialog flow editor, hover over the Start node, click the menu Description of sample-arch-image.png follows, then click Add start state.
    5. Description of add_start_state.png follows
    Description of the illustration
  5. Select User messaging, then Display Multimedia Messages.
    6. Description of display_multi_media_messages.png follows
    Description of the illustration
  6. Choose Display Intent answer.
  7. Accept the default name (displayIntentAnswer).
  8. For the description, enter General answer. Then click Insert.
    9. Description of display_intent_answer.png follows
    Description of the illustration

    When you're done, the flow should include the displayIntentAnswer state:

    This is an image of the displayIntentAnswer node.
  9. Click the displayIntentAnswer state to open its property inspector.
  10. Click Component in the property inspector. Then click Edit Response Items.
    11. Description of edit_response_item_display_intent_answer.png follows
    Description of the illustration
  11. Take a look at the default message at the Apache FreeMarker expression for the text property that references an answer intent: 
    "${skill.system.event.value.intent.answer}"
  12. The default expression returns only the answer. To create a friendlier message that includes a greeting, and the conversation name, update the text property with the following expression. Then click Apply. 
    "${rb('answerIntentIntroMessage1')} ${rb('systemFlowName_'+skill.system.event.value.intent.intentName)}. ${rb('answerIntentIntroMessage2')} ${skill.system.event.value.intent.answer}"

    This expression references the following resource bundles to enable the skill to output "Hello! You were asking about <conversation name>. Here is your answer: <answer text>.

    • answerIntentIntroMessage1 -- Hello! You were asking about
    • systemFlowName_ -- Resource bundle for conversation name strings.
    • answerIntentIntroMessage2" -- Here's your answer:

    Description of edit_response_item_intent_answer.png follows
    Description of the illustration

Map the Answer Intent Flow to an Event

You've completed the answer intent flow, but it can't yet display any answers. To trigger this flow when users ask about calories or vegetarian options, you need to return to the Main Flow to map it to an event that's dedicated to handling answer intents.

  1. Click Main Flow.
  2. If it's not already open, click Events.
  3. Click This is an image of the Add Built-in Event icon. next to Built-In Events.
    4. This is an image of the Add Built-in Event icon.
  4. Select Answer Intent from the Unhandled Event Type list.
  5. Select pizza.ans.genericHandler as the mapped flow. Then click Create.
    6. Description of answer_intent_mapping.png follows
    Description of the illustration

Test the Answer Intent

Now we'll use the Skill Tester to make sure that the intent is resolved correctly and also see how the flow works.

  1. Before you can chat with the skill, be sure that it's been trained with Trainer Tm:
    • Click Train.
      • This is an image of the Train icon.
    • Choose Trainer Tm, then click Submit.
  2. Click Preview to open the Skill Tester.
    3. Preview icon
  3. Enter How many calories?
    4. Description of test_answer_flow.png follows
    Description of the illustration
  4. Click Reset, then enter Can I get a vegetarian pizza?
  5. For both of these responses, take a look at the traversal from the Main Flow to the displayIntentAnswer state of the pizza.ans.genericHandler flow.
    6. Description of answer_intent_routing.png follows
    Description of the illustration
  6. When you're done, click Reset and then close the Skill Tester.
    7. This is an image of the Reset button.

Tip:

If you run into problems, take a look at the Reference_pizza.ans.genericHandler flow. This flow does not function because it is not mapped to the Answer Intent event.

In this step, you've created a flow that handles all answer intents. If you want to add actions related to the answer, then you can create a flow dedicated to just one answer intent. The pizza.ans.proc.veggiePizza flow in the sample skill, PizzaSkill - Visual Flow Designer, is an example of using an answer intent as an entry point to a transactional flow: users asking for vegetarian options get routed to the order pizza flow, where the pizza menu is filtered for its vegetarian options.

Create the Order Pizza Flow

In this step, you're going to create the skill's primary flow.

  1. Click Flows in the left navbar (if it's not already open), then click Add Flow.
  2. Enter intent.reg.order as the flow name.
  3. Enter Order pizza flow as the description.
  4. Select pizza.reg.orderPizza as the Intent Name. Then click Create.
    5. Description of create_flow_order_pizza.png follows
    Description of the illustration

Create the Flow-Level Variable

In this step, you're going to declare a variable for the cbe.confirmation entity, whose yes and no values support the branching action that you'll add to the flow later on. Because the branching action is unique to this flow, the value set for this variable needs to be confined to this flow only. Not only is its usefulness limited to the flow, but its lifespan is also. Unlike the skill-scoped pizza variable you created earlier, you're going to create this flow-scoped variable within the intent.reg.order flow, not within the main flow.

  1. Click intent.reg.order.
  2. Click Configuration.
    3. Description of order_pizza_flow_flow_variables.png follows
    Description of the illustration
  3. Click Add Variable.
  4. Complete the dialog by adding the following values before clicking Apply.

Build the Order Pizza Flow

For this short flow, you'll create a state for the skill-scoped composite bag pizza entity along with two other states that output text messages for greeting the user and confirming the order.

  1. Click Flow.
  2. Hover over the menu in the Start node, then click Add start state.
  3. Select Send Message.
    4. Description of order_pizza_flow_add_send_message_state.png follows
    Description of the illustration
  4. Name the state startPizzaOrder.
  5. For the description, enter Greeting message and then click Insert.
  6. Click the startPizzaOrder state to open its property inspector. Click Component if the Component page is not already open.
  7. Instead of entering a text string for the greeting message, reference the resource bundle: 
    ${rb('pizza.messages.orderPizzaStart')}
    8. Description of order_pizza_flow_startPizzaOrder_rb.png follows
    Description of the illustration
  8. Hover over the startPizzaOrder state to display its menu icon Description of sample-arch-image.png follows. Click the menu icon, then click Add state.
    9. Description of sample-arch-image.png follows
    Description of the illustration
  9. Choose Resolve Composite Bag.
  10. Name the state resolvePizza.
  11. Enter Pizza menu as then description. Then click Insert.
    12. Description of order_pizza_flow_resolve_pizza.png follows
    Description of the illustration

    Note the next transition line that's inserted automatically as you add states.

    Description of next_transition.png follows
    Description of the illustration
  12. In the Component page, select pizza as the composite bag entity variable.
    13. Description of order_pizza_flow_resolve_bag_properties.png follows
    Description of the illustration
  13. Click the menu in the resolvePizza state, then click Add state.
  14. Select Send Message.
  15. Name the state confirmMessage.
  16. Enter Confirmation message as the description. Then click Insert.
  17. In the Component page of the property inspector, reference the confirmation message resource bundle: 
    ${rb('cbe.confirmation.message')}

    When you're done, the flow should look like this:

    Description of first_completed_flow.png follows
    Description of the illustration

Test Out the Flow

Now we're going to test out the flow so far.

  1. Open the Skill Tester.
    2. This is an image of the Skill Tester icon
  2. Enter Order pizza. Then complete the order by selecting the pizza type and size.
    3. Description of partial_flow_skill_tester.png follows
    Description of the illustration
  3. Note the routing from the Main Flow to the intent.reg.order flow and the subsequent traversal from the startPizzaOrder state to the confirmMessage state.
    4. Description of order_pizza_flow.png follows
    Description of the illustration
  4. Click Reset and then close the Skill Tester.

In this step, you learned how to create an intent event flow that references a skill-level variable and resource bundles.

If you're having trouble completing this flow, take a look at the Reference_intent.reg.orderPizza_1 flow. This flow does not function because it is not mapped to an intent and does not reference the pizza variable.

Call Another Flow

To handle the situation where a user decides to cancel their order before it is sent, you're going to branch the conversation to the pre-existing cancel order flow, intent.reg.cancelOrder (accessed by clicking Flows > intent.reg.cancelOrder in the left navbar). This simple flow outputs "All right, you can peacefully forget about your pizza." using a Send Message state that references the pizza.messages.cancelOrder resource bundle.

Description of cancel_order_flow.png follows
Description of the illustration
If you were writing the dialog definition in YAML instead of the Visual Flow Designer, the order pizza and cancel pizza flows would be part of a monolithic block of code. Because of the modular approach afforded by the Visual Flow Designer, you create separate flows which you link together.

  1. Hover over the next transition line between the resolvePizza and the confirmMessage states. Then click Description of sample-arch-image.png follows to add a state to the next transition.
    2. Description of order_pizza_flow_insert_state.png follows
    Description of the illustration
  2. From the Add State dialog, select the Resolve Entity template by selecting User Messaging > Resolve Entities > Resolve Entity, or by entering resolve entity in the Search field.
    3. This is an image of the Search field.
  3. Name the state confirmSelection.
  4. For the description, enter Resolves Confirmation entity. Then click Insert.
    5. Description of order_pizza_flow_confirm_selection.png follows
    Description of the illustration
  5. In the Component page of the property inspector for the confirmSelection state, choose confirmation as the flow-scope variable.
    6. Description of order_pizza_flow_confirmation_properties.png follows
    Description of the illustration
  6. Hover over the next transition line that's between the confirmSelection state and the confirmMessage state, then click This is an image of the add state icon..
  7. Choose Flow Control. Then choose Invoke Flow.
  8. Name the state cancelCurrentOrder.
  9. For the description, enter Calls intent.reg.cancelOrder and then click Insert.
    10. Description of order_pizza_flow_invoke_flow.png follows
    Description of the illustration
  10. In Component page, select intent.reg.cancelOrder, the cancel order flow, as the flow that will be called when the dialog transitions to this state. If you were passing values like pizza size and pizza toppings to the cancel order flow, then you'd also define input parameters for this component.
    11. Description of order_pizza_flow_cancel_current_flow_flow.png follows
    Description of the illustration
  11. Hover over the next transition line between the confirmSelection and cancelCurrentOrder states and click This is an image of the add state icon. once again.
  12. Choose Flow Control, then Switch.
  13. Name the state routeSelection.
  14. Enter Branches conversation as the description. Then click Insert.
    15. Description of order_pizza_flow_add_switch.png follows
    Description of the illustration
  15. In the Component page of the property inspector for the routeSelection state, select Expression.
  16. You need to reference the Yes and No values from the confirmation variable that you created for this flow. To do this, paste the following expression into the field: 
    ${confirmation.value.confirmation.primaryLanguageValue}

    This expression uses the format for referencing an item in a composite bag entity: ${cbeVariableName.value.itemName.primaryLanguageValue}.

    17. Description of order_pizza_flow_confirmation_fm.png follows
    Description of the illustration
  17. Open the Transitions page of the property inspector for the routeSelection state.
  18. Select End flow (implicit) as the Next Transition.
    19. Description of order_pizza_dialog_flow_add_routing_action.png follows
    Description of the illustration
  19. Click to This is an image of the add action icon. (located next to Action) to create the Yes transition:
    • For Action Name, enter Yes.
    • For Transition to, select ConfirmMessage.
    • Click Save This is an image of the save icon..
  20. Click to This is an image of the add action icon. to create the No transition:
    • For Action Name, enter No
    • For Transition to, select cancelCurrentOrder
    • Click Save This is an image of the save icon..
      • Description of order_pizza_flow_route_selection_transitions.png follows
      Description of the illustration
      At this point, the flow should look like this. Note the No and Yes transitions branching from the routeSelection state. Note also that there's a next transition wired to the cancelCurrentOrder state.
      Description of flow_after_switch.png follows
      Description of the illustration
  21. To prevent a transition from the cancelCurrentOrder state to the confirmMessage state:
    • Open the property inspector for the cancelCurrentOrder state.
    • Select the Transitions page.
    • Select End flow (implicit) as the next transition.
    When you're done, the flow should look like this:
    22. Description of completed_flow.png follows
    Description of the illustration

Test out the Flow

Repeat the prior conversation in the Skill Tester for both the Yes and No options.

  1. Open the Skill Tester.
    2. This is an image of the Skill Tester icon
  2. Enter Order pizza. Select the pizza type and size.
  3. When you reach the confirmSelection state, choose Yes.
    Description of confirmSelection_state_in_skill_tester.png follows
    Description of the illustration

    The conversation routes from the Main Flow to the intent.reg.OrderPizza flow and culminates in the confirmMessage state.

    Description of order_pizza_flow_diagram.png follows
    Description of the illustration

  • Click Reset.
  • Enter Order pizza again. Select the pizza type and size.
  • When you reach the confirmSelection state, choose No.

    The conversation gets routed from the Main Flow, through the intent_reg.orderPizza flow, and then finally to the intent.reg.cancelOrderflow because of the No answer given for the confirmSelection state.

    Description of cancel_order_flow_diagram.png follows
    Description of the illustration

    • In this step, you learned how to add states to an existing flow. Specifically, you added flow control states to a flow comprised exclusively made up of user interface states. Using the flow control states, you learned how to link a parent flow to a child flow and how to set the branching logic to call that child flow. You also learned how to navigate the flow by changing the transition properties.

    Tip:

    If you run into problem check out Reference_intent.reg.orderPizza_2. This flow does not function because it is not mapped to an intent event.

    By completing this tutorial, you have learned the basics of creating and mapping flows in the Visual Flow Designer.

    Learn More