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:
- Log into Oracle Digital Assistant.
- Click in the top left corner to open the side menu.
- Expand Development and then click Skills.
- Hide the menu by clicking it again.
- Click Import Skill (located at the upper right). You will see a warning (Imported Ok, but note...). You can ignore this warning.
- 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:
- On the Skills page, within the tile for
Visual_Flow_Designer_Starter_Skill
, click the Options menu icon, and select Clone. - In the Display Name field, enter
<YourInitials>Visual_Flow_Designer_Starter_Skill
. - Select Open cloned skill afterwards. Then click Clone.
Review the Artifacts
- Intents -- 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.
- Entities -- 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.
- Resource Bundles -- 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
- 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 . You can ignore them.
If it's not already open, open Visual_Flow_Designer_Skill by clicking the tile. Then take a look at the following artifacts.
Tip:
You can use these flow as a quick reference. If you need a fully functioning skill, take a look atCompleted_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.
- Click Flows in the left navbar.
- Click Main Flow.
- Click Skill Variables.
- Click Add Variable (located under Custom Variables).
- For the name, enter
pizza
. - For the description, enter
Resolves the pizza menu
. - Select Entity as the variable type, then select cbe.pizza as the entity name.
- Click Apply.
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.
- Click Add Flow.
- In the Create Flow dialog, enter
pizza.ans.genericHandler
as the name. - For the description, enter
Generic answer intent flow
. Then click Create. - In the dialog flow editor, hover over the Start node, click the menu , then click Add start state.
- Select User messaging, then Display Multimedia Messages.
- Choose Display Intent answer.
- Accept the default name (displayIntentAnswer).
- For the description, enter General answer. Then click Insert.
- Click the displayIntentAnswer state to open its property inspector.
- Click Component in the property inspector. Then click Edit Response Items.
- 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}"
- 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:
When you're done, the flow should include the displayIntentAnswer state:
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.
- Click Main Flow.
- If it's not already open, click Events.
- Click next to Built-In Events.
- Select Answer Intent from the Unhandled Event Type list.
- Select pizza.ans.genericHandler as the mapped flow. Then click Create.
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.
- Before you can chat with the skill, be sure that it's been trained with Trainer Tm:
- Click Train.
- Choose Trainer Tm, then click Submit.
- Click Preview to open the Skill Tester.
- Enter How many calories?
- Click Reset, then enter Can I get a vegetarian pizza?
- 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.
- When you're done, click Reset and then close the Skill Tester.
Tip:
If you run into problems, take a look at theReference_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.
- Click Flows in the left navbar (if it's not already open), then click Add Flow.
- Enter
intent.reg.order
as the flow name. - Enter
Order pizza
flow as the description. - Select pizza.reg.orderPizza as the Intent Name. Then click Create.
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.
- Click intent.reg.order.
- Click Configuration.
- Click Add Variable.
- Complete the dialog by adding the following values before clicking Apply.
- Name -
confirmation
- Description -
Flow branching variable
- Variable Type - Entity
- Variable Name - cbe.confirmation
- Name -
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.
- Click Flow.
- Hover over the menu in the Start node, then click Add start state.
- Select Send Message.
- Name the state
startPizzaOrder
. - For the description, enter
Greeting message
and then click Insert. - Click the startPizzaOrder state to open its property inspector. Click Component if the Component page is not already open.
- Instead of entering a text string for the greeting message, reference the resource bundle:
${rb('pizza.messages.orderPizzaStart')}
- Hover over the startPizzaOrder state to display its menu icon . Click the menu icon, then click Add state.
- Choose Resolve Composite Bag.
- Name the state
resolvePizza
. - Enter
Pizza menu
as then description. Then click Insert. - In the Component page, select pizza as the composite bag entity variable.
- Click the menu in the resolvePizza state, then click Add state.
- Select Send Message.
- Name the state
confirmMessage
. - Enter
Confirmation message
as the description. Then click Insert. - 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:
Note the next transition line that's inserted automatically as you add states.
Test Out the Flow
Now we're going to test out the flow so far.
- Open the Skill Tester.
- Enter Order pizza. Then complete the order by selecting the pizza type and size.
- 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.
- 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.
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.
- Hover over the next transition line between the resolvePizza and the confirmMessage states. Then click to add a state to the next transition.
- 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.
- Name the state
confirmSelection
. - For the description, enter
Resolves Confirmation entity
. Then click Insert. - In the Component page of the property inspector for the confirmSelection state, choose confirmation as the flow-scope variable.
- Hover over the next transition line that's between the confirmSelection state and the confirmMessage state, then click .
- Choose Flow Control. Then choose Invoke Flow.
- Name the state
cancelCurrentOrder
. - For the description, enter
Calls intent.reg.cancelOrder
and then click Insert. - 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.
- Hover over the next transition line between the confirmSelection and cancelCurrentOrder states and click once again.
- Choose Flow Control, then Switch.
- Name the state
routeSelection
. - Enter
Branches conversation
as the description. Then click Insert. - In the Component page of the property inspector for the routeSelection state, select Expression.
- 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}
. - Open the Transitions page of the property inspector for the routeSelection state.
- Select End flow (implicit) as the Next Transition.
- Click to (located next to Action) to create the Yes transition:
- For Action Name, enter Yes.
- For Transition to, select ConfirmMessage.
- Click Save .
- Click to to create the No transition:
- For Action Name, enter No
- For Transition to, select cancelCurrentOrder
- Click Save . 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.
- 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.
Test out the Flow
Repeat the prior conversation in the Skill Tester for both the Yes and No options.
- Open the Skill Tester.
- Enter Order pizza. Select the pizza type and size.
- When you reach the confirmSelection state, choose Yes.
The conversation routes from the Main Flow to the intent.reg.OrderPizza flow and culminates in the confirmMessage state.
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.
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
- Tutorial: Tour of the Visual Flow Designer Sample Skill
- Visual Flow Designer in Using Oracle Digital Assistant
Create a Dialog Flow with the Oracle Visual Flow Designer
F54570-03
August 2022
Copyright © 2022, Oracle and/or its affiliates.
Shows you how to create dialog flow with Oracle Cloud Visual Flow Designer
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or "commercial computer software documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government's use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.