User Interface Components
These are the components that are available in the User Interface category of YAML-based dialog flow editor.
-
System.CommonResponse—Outputs content-rich messages.
-
System.Webview—Integrates your bot with a web app.
-
System.IncidentCreation—Creates an incident for Oracle B2C Service or Oracle Fusion Service.
-
System.IntelligentAdvisor—Integrates your skill with an Oracle Intelligent Advisor interview.
-
System.KnowledgeSearch—Searches a knowledge service for information about a subject.
-
System.AgentTransfer—Enables a DA-as-agent skill to transfer a conversation back to Oracle B2C Service or Oracle Fusion Service.
-
System.AgentTransferCondition—Lets you check if agents are available and get the expected wait time.
-
System.AgentInitiation and System.AgentConversation—Enables you to transfer a conversation to an Oracle B2C Service live agent.
-
System.ResolveEntities—Resolves the values for the member entities of a composite bag entity.
- System.Feedback—Outputs a feedback rating component.
System.CommonResponse
The System.CommonResponse
component enables you to build
messages with rich UI features like card carrousels with images and action buttons, or forms
with tables and input fields.
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Common Response Component Templates.
Templates for the System.CommonResponse
are available in the
User Messaging section of the Add
Component dialog.
System.CommonResponse
component in the CrcPizzaBot, one of the
sample bots. In this spin on the PizzaBot, you can display an image-rich menu with quick
action Order Now buttons.
System.CommonResponse
component, the
different types of messages are known as response types and the CrcPizzaBot shows you
how, among other things, they allow the bot users to respond to prompts using action
buttons and view the pizza menu as a cascade of card items.
From the Add Component menu, you can select different
System.CommonResponse
templates for cards, text, attachment
responses, and for composite bag entities (demonstrated by the CbPizzaBot). These
templates include both properties that are common to all of these response type
properties that are specific to the individual response types. While the Add
Component menu adds separate states for each response type, you can
combine one or more response types into a single state. The CrcPizzaBot shows you
examples of both in its ShowMenu
(text response) and
OrderPizza
(text and card responses) states.
You should test each skill in your target channels early in the development cycle to make sure that your components render as desired.
The Component Properties
Configuring System.CommonResponse
components entails setting
properties that direct the Dialog Engine along with metadata properties that describe not only
how the component delivers messages (as text prompts, cards, or attachments), but also sets
the content and behavior for the messages themselves.
Name | Description | Required? |
---|---|---|
metadata |
The chat response created by this component is driven by the
contents of the metadata property. See The Metadata Property in Common Response Components.
|
Yes |
processUserMessage |
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 |
Yes |
autoNumberPostbackActions |
This property is used for composite bags, text responses, card responses. When set to true , this option prefixes numbers to options. Even when you haven’t set this option to true , auto-numbering can be enforced on card items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true . As demonstrated by its default configuration, channel-specific auto-numbering can be applied to any skill bot that registered to a digital assistant (${(system.channelType=='twilio')?then('true','false')} ):
|
No |
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. |
No |
nlpResultVariable |
Sets the variable property with an entity value
(when that entity value hasn’t already been set for the referenced variable). You can
enable nlpResultVariable to return value when you define it using a
variable that holds the NLP results (such as iResult: "nlpresult"
that’s used in our sample bots). By doing this, the nlpResultVariable
property can still populate the value when it’s null if it finds a resolved entity
that matches the one referenced by the variable. The dialog transitions to the next
state when the nlpResultVariable sets the value. You can use this
property in place of the System.SetVariable component.
|
No |
useFullEntityMatches |
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.
|
No |
maxPrompts |
Before the System.CommonResponse 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 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. |
No |
keepTurn |
The keepTurn property only applies when you set the
processUserMessage property to false . See System.Output to find out how to
set this property.
|
No |
translate |
Use this property to override the boolean value that you’ve set for
the autotranslate context variable. If you haven’t set this variable,
or if you set it to false , then you can set this property to
true to enable autotranslation for this component only. If you set
the autotranslation variable is set to true , you can
set this property to false to exclude this component from
autotranslation. See Translation Services in Skills.
|
No |
footerText |
Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. | No |
transitionAfterMatch (deprecated)
|
A boolean that, when you set it to
true , enables a temporary transition from the entity matching
performed by this component to another state. This property is no longer
supported. To get this functionality, use an entity event handler |
No |
cancelPolicy |
Determines the timing of the
cancel transition:
maxPromptsReached handler. |
No |
Here's the YAML for an example state based on the System.CommonResponse
component.
AskPizzaSize:
component: "System.CommonResponse"
properties:
variable: "pizzaSize"
nlpResultVariable: "iresult"
maxPrompts: 2
metadata:
responseItems:
- type: "text"
text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
\ </#if>What size do you want?"
name: "What size"
separateBubbles: true
actions:
- label: "${enumValue}"
type: "postback"
payload:
action: ""
variables:
pizzaSize: "${enumValue}"
name: "size"
iteratorVariable: "pizzaSize.type.enumValues"
processUserMessage: true
transitions:
actions:
cancel: "Intent"
next: "AskLocation"
Tip:
Thetext
property in this snippet is defined using Apache FreeMarker Template Language (FTL). To find
out how to add FTL expressions and use FreeMarker built-in operations to transform variable
values, see Apache FreeMarker Template Language Syntax.
Transitions for the System.CommonResponse Component
Transition | Description |
---|---|
cancel |
Triggered when a user exceeds the allotted attempts
set by the maxAttempts property, or redirect the
flow .
|
textReceived |
Triggered when a user sends text or emojis instead of tapping an action button or link. |
attachmentReceived |
Triggered when a user sends an image, audio, video, or file attachment. |
locationReceived |
Triggered when the user sends a location. |
system.outOfOrderMessage |
Set this to circumvent unexpected user behavior. Specifically, when a user doesn’t tap an action item in the current message, but instead taps an action belonging to an older message in the chat session. |
Composite Bag Transitions in the System.CommonResponse Component
System.CommonResponse
components triggers the
match
and cancel
actions based the values matched
from the user input and on your configuration of the cancelPolicy
property.
Action | Description | Required? |
---|---|---|
match |
The component triggers this action to navigate to the specified state when at least one entity in the bag has matched the user input. | No |
cancel |
The component triggers this action to navigate to
the specified state based on the setting for the
cancelPolicy property.
|
No |
System.Webview
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Webview Component.
The System.Webview
component opens a webview within your skill, or
for skills that run in a web channel, in an browser tab.
System.WebView Component Properties
Property | Description | Required? |
---|---|---|
sourceVariableList |
A comma-separated list of context or user variable
names. These variable names are the parameters that are sent to the
webview; they’re the input parameters from your bot. You can set each
variable by adding a series of System.SetVariable
states before the System.Webview state.
|
Yes |
variable |
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. |
Yes |
prompt |
A text string like “Tap to continue.” | No |
service |
The name of the webview component service. | No |
imageUrl |
The URL to the image that accompanies a prompt. | No |
linkLabel |
The label for the button that invokes the web app. | No |
cancelLabel |
The label for the Cancel button that lets users leave the state without invoking the web app. | No |
autoNumberPostbackActions |
Enables user input in SMS channels, which don’t support
buttons, by adding number equivalents to the UI elements.
|
No |
translate |
Use this property to override the boolean value that
you’ve set for the autotranslate context variable. If
you haven’t set this variable, or if you set it to
false , then you can set this property to
true to enable autotranslation for this component
only. If you set the autotranslation variable is set to
true , you can set this property to
false to exclude this component from
autotranslation. See Translation Services in Skills.
|
No |
Transitions for the System.Webview Component
Transitions | Description |
---|---|
next |
Names the next state in the dialog flow after the successful callback from the web app. |
return |
Exits the conversation after the successful callback from the web app. |
error |
Names the state that handles errors. |
actions |
|
System.IncidentCreation
You can use the System.IncidentCreation
component to create
an incident 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.
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Incident Creation.
Here's an example of using this component to transfer the conversation back to a Oracle B2C Service site.
component: "System.IncidentCreation"
properties:
serviceName: "IncidentService"
subject: "${incident.value.subject}"
attachmentUrl: <#if (incident.value.Attachment.url)??>${incident.value.Attachment.url}<#else></#if>
customFields:
description: "${incident.value.description}"
contactInfo: "<#if (profile.contactInfo)??>${profile.contactInfo}<#else></#if>"
contactProperties:
firstName: "${profile.firstName}"
lastName: "${profile.lastName}"
email: "${incident.value.email}"
incidentNumberVariable: "incidentNumber"
transitions:
error: "incidentError"
next: "exitIncident"
And here's an example for Oracle Fusion Service:
component: "System.IncidentCreation"
properties:
serviceName: "IncidentServiceB2BEndUserAuth"
subject: "${service.value.subject}"
attachmentUrl: <#if (service.value.Attachment.url)??>${service.value.Attachment.url}<#else></#if>
agentReportFilter: "ODAQueue"
addChatTranscript: "true"
customFields:
description: "${service.value.description}"
contactInfo: "<#if (profile.contactInfo)??>${profile.contactInfo}<#else></#if>"
contactProperties:
firstName: "${profile.firstName}"
lastName: "${profile.lastName}"
email: "<#if (profile.email)??>${profile.email}<#else></#if>"
incidentNumberVariable: "incidentNumber"
transitions:
error: "incidentError"
next: "exitIncident"
Property | Description | Required? | |
---|---|---|---|
serviceName |
The name of the integration as configured in Settings > Additional Services > Customer Service Integration. | Yes | |
subject |
The text for the subject of the incident. | Yes | |
attachmentUrl |
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. | No | |
agentReportFilter |
(For Oracle Fusion
Service incidents), text to filter the incidents. The default value is
ODA .
|
No | |
addChatTranscript |
(For Oracle Fusion
Service incidents only.) When set to true, chat transcript is added to the incident.
Defaults to false.
Insights must be enabled for the skill in order for the chat transcript to be made available. A transcript can only be added to the incident when using a DA as an Agent integration in combination with Web Chat for Service or Oracle Inlay Toolkit inlays. |
No | |
customFields |
A map that contains the description and, optionally, contactInfo , which can contain additional details about the incident.
The map is passed unvalidated as a text version of the object and inserted into the incident message as a private note. |
No | |
contactProperties |
A map of name/value pairs that contains 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
|
Only for Oracle B2C Service | |
incidentNumberVariable |
The name of the string context variable in which to store the incident number. | No |
System.IntelligentAdvisor
Use this component to access an Oracle Intelligent Advisor interview from a skill.
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Intelligent Advisor.
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
Here's an example:
loanAdvisorIA:
component: "System.IntelligentAdvisor"
properties:
intelligentAdvisorService: "myService"
deployment: "Loan Advisor"
# default yesLabel: "yes"
# default noLabel: "no"
uncertainLabel: "not sure"
endLabel: "You can ask me another question if there's something else that I can help
you with."
# default doneLabel: "/done"
# default undoLabel: "/back"
# default resetLabel: "/reset"
# default exitLabel: "/exit"
showExplanation: "ask"
# default explanationAskLabel: "Do you want to see the explanation?"
# default removeHtml: false
transitions:
error: "handleIAError"
next: "endOfFlow"
handleIAError:
component: "System.Output"
properties:
text: |
We are having a problem with a connection.
Can you please send email to
contact@example.com to let them know that
the loan advisor isn't working? Thank you.
transitions:
next: "endOfFlow"
See Use the Intelligent Advisor Component in Your Skill for an example that uses the component in a dialog flow.
Tip:
The default values for all the label properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the IntelligentAdvisor - <property name> key. If you use the skill's resource bundle to change the default, then you don't need to include the label property in the component unless you want to override the default.The configuration resource bundle also allows you to change the IntelligentAdvisor - defaultValue, IntelligentAdvisor - doneHelp, IntelligentAdvisor - maskLabel, IntelligentAdvisor - outOfOrderMessage, IntelligentAdvisor - resumeSessionPrompt, IntelligentAdvisor - numberMinMax, IntelligentAdvisor - outOfOrderMessage, IntelligentAdvisor - resumeSessionPrompt, and IntelligentAdvisor - yesNoMessage messages. For example, the IntelligentAdvisor - doneHelp message is output for attachment fields, and it defaults to When you are done with the upload, say {0}.
You might want to change it to something like Say {0} to let me know that you are done uploading.
Property | Description | Required? |
---|---|---|
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 exclude it if the interview doesn't prompt for currency amounts or is not expecting any certain currency. | No |
deployment |
The name of the active deployment project on the Intelligent Advisor Hub. | Yes |
doneLabel |
The text that the users type to indicate that they are done uploading a file.
The default is |
No |
endLabel |
Text to display in the chat at the end of the interview.
The default is |
No |
exitLabel |
The text that users type to indicate that they want to exit the interview.
The default is |
No |
explanationAskLabel |
The question to ask when showExplanation is set to ask .
The default is |
No |
hideScreenTitle |
Indicates whether to hide all the screen titles in the interview.
The default is |
No |
intelligentAdvisorService |
The name of the Intelligent Advisor service as configured in Settings > Additional Services. | Yes |
interviewAttributes |
The name of a context variable of type string in which to store the interview's attribute values. The attribute values are stored as an array of key/value pairs. | No |
locale |
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 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 |
No |
noLabel |
The label to use to represent Boolean FALSE values.
The default is |
No |
params |
A map of key-value connection parameters to pass upon the start of interview. This is typically needed for interviews with external data integration. | No |
removeHtml |
Indicates whether to remove the HTML markup from the text. The default is false .
|
No |
resetLabel |
The text that users type to indicate that they want to go back to the first question.
The default is |
No |
seedData |
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. |
No |
showExplanation |
Specifies whether to show the Intelligent Advisor explanation. The allowed values are never , always and ask .
If you set to The default is |
No |
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 |
No |
undoLabel |
The text that the users type to indicate that they want to go back to the previous question.
The default is |
No |
yesLabel |
The label to use to represent Boolean TRUE values.
The default is |
No |
Example: Use the Intelligent Advisor Component in Your Skill
####################
# Loan Advisor
####################
loanAdvisorStart:
component: "System.Output"
properties:
keepTurn: true
text: |
OK, I can initiate a loan request for you.
But first I'll transfer you to an
automated advisor that will ask some
questions about the loan that you want,
your assets, your liabilities, and your
financial history. It shouldn't take
more than 5 minutes.
<#if (user.notFirstTime)??><#else>
At any time, you can say
/back to go to the previous question,
/reset to start over or
/exit to stop the questions.</#if>
transitions:
next: "setNotFirstTime"
setNotFirstTime:
component: "System.SetVariable"
properties:
variable: "user.notFirstTime"
value: true
transitions:
next: "loanAdvisorIA"
loanAdvisorIA:
component: "System.IntelligentAdvisor"
properties:
intelligentAdvisorService: "myService"
deployment: "Loan Qualifier"
# default yesLabel: "yes"
# default noLabel: "no"
uncertainLabel: "not sure"
endLabel: " "
# default doneLabel: "/done"
# default undoLabel: "/back"
# default resetLabel: "/reset"
# default exitLabel: "/exit"
showExplanation: "ask"
# default explanationAskLabel: "Do you want to see the explanation?"
interviewAttributes: "interviewDetails"
transitions:
error: "handleIAError"
next: "handleEligibility"
handleEligibility:
component: "System.Switch"
properties:
source: <#list interviewDetails.value as i><#if i.key = 'eligibility'>${i.val}</#if></#list>
# The values that are matched against the value of the variable or source property. The value that matches is set as transition action
values:
- "eligible"
- "noteligible"
transitions:
actions:
eligible: "initiateLoan"
noteligible: "suggestNextSteps"
NONE: "handleUnexpectedAttributeValue" # the attribute value was other than eligible or noteligible or the user exited interview
error: "handleAttributeNotSet" # the attribute wasn't set during the interview or the key is incorrect
handleIAError:
component: "System.Output"
properties:
text: |
We are having a problem with a connection.
Can you please send email to
contact@example.com to let them know that
the loan advisor isn't working? Thank you.
transitions:
next: "endOfFlow"
...
Example: Access Interview Attributes
Here's a simple example of accessing an interview's attribute values:
context:
variables:
iResult: "nlpresult"
interviewDetails: "string"
states:
...
loanAdvisorIA:
component: "System.IntelligentAdvisor"
properties:
intelligentAdvisorService: "myService"
deployment: "Loan Qualifier"
# default yesLabel: "yes"
# default noLabel: "no"
uncertainLabel: "not sure"
endLabel: " "
# default doneLabel: "/done"
# default undoLabel: "/back"
# default resetLabel: "/reset"
# default exitLabel: "/exit"
showExplanation: "ask"
# default explanationAskLabel: "Do you want to see the explanation?"
interviewAttributes: "interviewDetails"
transitions:
error: "handleIAError"
next: "handleEligibility"
handleEligibility:
component: "System.Switch"
properties:
source: <#list interviewDetails.value as i><#if i.key = 'eligibility'>${i.val}</#if></#list>
# the values that are matched against the value of the variable or source property. The value that matches is set as transition action
values:
- "eligible"
- "noteligible"
transitions:
actions:
eligible: "initiateLoan"
noteligible: "suggestNextSteps"
NONE: "handleUnexpectedAttributeValue" # the attribute value was other than eligible or noteligible or the user exited interview
error: "handleAttributeNotSet" # the attribute wasn't set during the interview or the key is incorrect
...
System.KnowledgeSearch
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see 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 results that the service returns 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's an example of using this component. It searches a Knowledge Management service for all information that's related to the user's last utterance. For additional examples, see Use the Knowledge Search Component.
searchFor: knowledgeSearch:
component: "System.KnowledgeSearch"
properties:
searchServiceName: "myKnowledgeSearch"
searchTerm: "${iResult.value.query}"
searchPrelude: "I don't know the answer for that. Let me search for an answer."
resultSizeLimit: 5
resultVersion: "Special Response"
resultVersionExclusive: true
resultLinkLabel: "Show More"
searchLinkLabel: "Open Page with All Answers" # For B2B set to "Go to search home page"
noResultText: "I don't have an answer for that. Try rephrasing your question."
transitions:
actions:
resultSent: "reset"
noResult: "reset"
serverError: "handleSearchServerProblem"
error: "handleSearchError"
next: "reset"
Tip:
The default values for thedefaultAttachmentLabel
, noResultText
, and resultLinkLabel
properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the KnowledgeSearch - <property name> key. If you use the skill's resource bundle to change the default, then you don't need to include the property in the component unless you want to override the default.
Property | Description | Required? |
---|---|---|
cardLayout |
Specifies whether to display the result cards vertically or horizontally. Defaults to horizontal .
|
No |
customFilters |
A list of search result filters presented as name-value pairs. The allowable filter names are product and category . Each of them allows only one filter declaration. See Filter Results by Product and Category.
|
No |
customProperties |
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 + .
|
No |
defaultAttachmentLabel |
The default label to use for the result card's URL action that's linked with an attachment whenever the attachment doesn't have a configured display name. 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 Defaults to |
No |
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 (example: 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
|
No |
noResultText |
The text to output when no search result is available. Defaults to the text from the KnowledgeSearch - noResultText resource bundle entry |
No |
resultLinkLabel |
The label to use for the result card's URL action (button) that links to the web version of the information. Defaults to the text from the KnowledgeSearch - resultLinkLabel resource bundle entry If you set this property to |
No |
resultSizeLimit |
The maximum number of results to display. The default is |
No |
resultVersion |
Oracle B2C Service only: The preferred version to return when there are multiple versions for a result. You can set this property to either You can leverage special responses to display output that's specifically tailored for chat conversations as opposed to web pages. The default version is |
No |
resultVersionExclusive |
Oracle B2C Service only: Specifies whether only results that are available in the preferred version should be displayed. When The default is |
No |
searchLinkLabel |
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 the home search page. If this property isn't set, then the card message payload doesn't display the action. |
No |
searchPrelude |
The text to output before the search result is displayed. If this property isn't set, then the text from the KnowledgeSearch - searchPrelude resource bundle entry is output. If you don't want the search prelude to be displayed, then set this property to |
No |
searchServiceName |
The name of the knowledge search integration as configured in Settings. | Yes |
searchTerm |
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 Knowledge Search Component. |
Yes |
System.KnowledgeSearch Transitions
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 |
Example: Associate Related Questions with a Search Term in a YAML Dialog Flow
The following diagram illustrates how to implement the single-state method if
your dialog flow is created in YAML mode. 1) You use a map context variable to associate the
knowledge intents with search terms. 2) You set each knowledge intent's action in the
Intent
state to transition to a data flow that uses the map to set the
searchTerm
context variable to the intent's search term. 3) You then
transition to a state that searches the knowledge base for the searchTerm
value.
Here's an example of a dialog flow in which there are individual intents for each knowledge base answer.
context:
variables:
iResult: "nlpresult"
intentName: "string"
searchTerm: "string"
searchTerms: "map"
someVariable: "string" # For the reset state
states:
#
# Set search term for each knowledge intent
#
setSearchTerms:
component: "System.SetVariable"
properties:
variable: "searchTerms"
value:
knowledge.Shipping Return Costs: "Shipping Return Costs"
knowledge.Locate Service Tag or Serial: "Locating Your Service Tag or Asset Serial Number"
knowledge.Support Account: "My Support Account"
knowledge.Product Registration: "How do I register my product?" # (1)
knowledge.Noncontiguous Delivery Time: "What is the delivery time to Alaska, Hawaii and the U.S. Territories?"
knowledge.Return Policy: "What is your return policy?"
transitions:
next: "intent"
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
system.Greeting: "welcome"
system.Unsatisfactory Response: "transferToAgent"
system.Request Agent: "transferToAgent"
knowledge.Shipping Return Costs: "startIntentKnowledgeSearch"
knowledge.Locate Service Tag or Serial: "startIntentKnowledgeSearch"
knowledge.Support Account: "startIntentKnowledgeSearch"
knowledge.Product Registration: "startIntentKnowledgeSearch" # (2)
knowledge.Noncontiguous Delivery Time: "startIntentKnowledgeSearch"
knowledge.Return Policy: "startIntentKnowledgeSearch"
unresolvedIntent: "genericKnowledgeSearch"
#
# Start knowledge search for a knowledge intent's search term
# based on searchTerms context variable
#
# First, reset variables
#
startIntentKnowledgeSearch: # (2)
component: "System.ResetVariables"
properties:
variableList: "searchTerm, intentName"
transitions:
next: "setIntentName"
#
# Set the intentName context variable
#
setIntentName:
component: "System.SetVariable"
properties:
variable: "intentName"
value: "${iResult.value.intentMatches.summary[0].intent}"
transitions:
next: "setSearchTerm"
#
# Get the search term to use for the intent
#
setSearchTerm:
component: "System.SetVariable"
properties:
variable: "searchTerm"
value: "${searchTerms.value[intentName.value]}"
transitions:
next: "knowledgeSearchForGivenSearchTerm" # (3)
#
# This state searches for the searchTerm variable's value
#
knowledgeSearchForGivenSearchTerm:
component: "System.KnowledgeSearch"
properties:
# Set to the name of the search service that is configured in Settings
searchServiceName: "KnowledgeSearch"
searchTerm: "${searchTerm.value}" # put the search term here (3)
# searchPrelude: Optional property. If missing, there's no search prelude.
resultSizeLimit: 1 # Change to how many articles to show.
# resultVersion: Optional property. Defaults to "Answer".
# resultVersionExclusive: Optional property. Defaults to false.
resultLinkLabel: "Show More"
# defaultAttachmentLabel: Optional property. Defaults to "Download"
searchLinkLabel: "Search for Similar Answers"
noResultText: >
I don't have an answer for that. Try rephrasing your question
(or you can ask to speak to a live agent).
# cardLayout: Optional property. Defaults to "horizontal"
transitions:
actions:
resultSent: "offerMoreHelp"
noResult: "reset"
serverError: "handleSearchServerProblem"
error: "handleSearchError"
next: "reset"
#
# This state is called after knowledge search returns its results.
#
offerMoreHelp:
component: "System.Output"
properties:
text: >
You can ask me another question if there's something
else that I can help you with.
transitions:
return: "offerMoreHelp"
#
# This state is called when there's a problem accessing the knowledge base 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.
#
handleSearchServerProblem:
component: "System.Output"
properties:
text: >
I'm not able to get an answer for that question. Let me know
if there's anything else I can help you with.
transitions:
return: "handleSearchServerProblem"
#
# This state is called when there's a problem using the knowledge search component
# such as when there's a problem with the knowledge search integration configuration
#
handleSearchError:
component: "System.Output"
properties:
text: >
Oops, my answer mechanism for that isn't working properly.
You can ask a different question or ask to speak to an agent?
transitions:
return: "handleSearchError"
#
# This state ends the conversation
#
reset:
component: "System.SetVariable"
properties:
variable: "someVariable"
value: "x"
transitions:
return: "reset"
Example: Employ User Utterance as Search Term
The following example shows how to set the searchTerm
to
the user's utterance in a YAML dialog skill. For a visual dialog skill, you use
${skill.system.nlpresult.value.query}
instead.
context:
variables:
iResult: "nlpresult"
someVariable: "string" # For the reset state
states:
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
system.Greeting: "welcome"
system.Unsatisfactory Response: "transferToAgent"
...
unresolvedIntent: "genericKnowledgeSearch"
#
# This state searches the knowledge base with the user input as the search term.
#
genericKnowledgeSearch:
component: "System.KnowledgeSearch"
properties:
# Set to the name of the search service that is configured in Settings
searchServiceName: "KnowledgeSearch"
searchTerm: "${iResult.value.query}"
searchPrelude: "I don't know the answer offhand. Let's see what articles we have..."
resultSizeLimit: 3 # Change to how many articles to show. Defaults to 10.
# resultVersion: Optional property. Defaults to "Answer".
# resultVersionExclusive: Optional property. Defaults to false.
resultLinkLabel: "Show More"
# defaultAttachmentLabel: Optional property. Defaults to "Download"
searchLinkLabel: "Open Page with All Answers"
noResultText: >
I couldn't find any articles about that. Try rephrasing your
question (or you can ask to speak to a live agent).
# cardLayout: Optional property. Defaults to "horizontal"
transitions:
actions:
resultSent: "offerMoreHelp"
noResult: "reset"
serverError: "handleSearchServerProblem"
error: "handleSearchError"
next: "reset"
#
# This state is called after knowledge search returns its results.
#
offerMoreHelp:
component: "System.Output"
properties:
text: >
You can ask me another question if there's something
else that I can help you with.
transitions:
return: "offerMoreHelp"
#
# This state is called when there's a problem accessing the knowledge base 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.
#
handleSearchServerProblem:
component: "System.Output"
properties:
text: >
I'm not able to get an answer for that question. Let me know
if there's anything else I can help you with.
transitions:
return: "handleSearchServerProblem"
#
# This state is called when there's a problem using the knowledge search component
# such as when there's a problem with the knowledge search integration configuration
#
handleSearchError:
component: "System.Output"
properties:
text: >
Oops, my answer mechanism for that isn't working properly.
You can ask a different question or ask to speak to an agent?
transitions:
return: "handleSearchError"
#
# This state ends the conversation
#
reset:
component: "System.SetVariable"
properties:
variable: "someVariable"
value: "x"
transitions:
return: "reset"
System.AgentTransfer
You use the System.AgentTransfer
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 topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Agent Transfer.
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 System.AgentConversation instead.
Here's an example of using this component to transfer the conversation back to the chat service.
transferToAgent:
component: "System.AgentTransfer"
properties:
maxEngagementsInQueue: "8"
maxWaitSeconds: "300"
waitingMessage: "Let me see if a human agent is available to help you. Hold tight."
rejectedMessage: "No agents are available at this time. Please try again later."
errorMessage: "We're unable to transfer you to a human agent because there was a system error."
transitions:
actions:
accepted: "reset"
rejected: "handleRejected"
error: "offerMoreHelp"
next:
"reset"
Tip:
In skills with platform version 21.04 and later, the default values for theacceptedMessage
, errorMessage
, rejectedMessage
, and waitingMessage
properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the AgentTransfer - <property name> key. If you use the skill's resource bundle to change the default message, then you don't need to include the message property in the component unless you want to override the default.
Property | Description | Required? | |
---|---|---|---|
agentStatusVariable |
The name of the context 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 System.AgentTransferCondition. |
No | |
allowTransferIf |
Specifies the conditions under which the skill should transfer the chat session.
If the specified conditions aren't met, then the |
No | |
customProperties |
A map that holds information to pass to the service. See Pass Information to the Service. | No | |
errorMessage |
The message that's shown to the user when a system error occurs while transferring the chat session to an agent. Defaults to We were unable to transfer you because there was a system error . You can set the property to a blank or empty string to suppress message output.
|
No | |
maxEngagementsInQueue |
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 maxEngagementsInQueue , then the rejected
action occurs. Defaults to -1 , which means that there's no engagement
limit.
Note that for Oracle Fusion Service Chat, the response is always 0, so this property is of no value for Oracle Fusion Service. |
No | |
maxWaitSeconds |
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 maxWaitSeconds , 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 |
No | |
rejectedMessage |
The message that's shown to the users whenever one of the following occurs:
Agent rejected . You can set the property to a blank or empty string to suppress message output.
|
No | |
waitingMessage |
The message that's shown to users when they're transferred to a queue. Defaults to Agent chat session established. Waiting for agent to join . You can set the property to a blank or empty string to suppress message output.
|
No |
This component can return the following actions:
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 conversation must end with a
|
rejected |
The rejected transition is set when one of the following occurs:
|
error |
The error transition is set when there's a system error that prevents the transfer to a human agent.
|
Example: Transfer to a Human Agent
Here's an example of a dialog flow that transfers to an agent when the customer asks to speak to an agent:
metadata:
platformVersion: "1.1"
main: true
name: "AutomatedAgentConversation"
context:
variables:
iResult: "nlpresult"
someVariable: "string"
states:
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
...
system.Unsatisfactory Response: "transferToAgent"
system.Request Agent: "transferToAgent"
...
#
# This state tries to transfer the user to another agent when the user explicitly requests for it.
#
transferToAgent:
component: "System.AgentTransfer"
properties:
maxWaitSeconds: "300"
waitingMessage: "I'm transferring you to a human agent. Hold tight."
rejectedMessage: "I wasn't able to transfer you to a human agent. Please try again later."
errorMessage: "We're unable to transfer you to a human agent because there was a system error."
transitions:
actions:
accepted: "reset"
rejected: "handleRejected"
error: "offerMoreHelp"
next: "reset"
#
# This state is called when an agent transfer is rejected.
# It lets the customer know they can ask for something else.
#
handleRejected:
component: "System.Output"
properties:
text: "Meanwhile, let me know if there's anything else I can help you with."
transitions:
return: "handleRejected"
#
# This state is called when an agent transfer encounters a system error.
# It lets the customer know they can ask for something else.
#
offerMoreHelp:
component: "System.Output"
properties:
text: >
You can ask me another question if there's something
else that I can help you with.
transitions:
return: "offerMoreHelp"
#
# This state ends the conversation with a return transition for insights purposes,
# after the user has been transferred to another agent.
#
reset:
component: "System.SetVariable"
properties:
variable: "someVariable"
value: "x"
transitions:
return: "reset"
Example: Pass Information to the Service
When you transfer a conversation from a digital assistant to a live agent, you can
use custom properties in the System.AgentTransfer
component to pass
this information.
Here's the structure for Oracle B2C Service:
customProperties:
- name:
value:
type:
The type
property is required for custom fields, otherwise,
it's optional.
Here's the structure for Oracle Fusion Service:
customProperties:
- name:
value:
Here's an example customProperties
setting for Oracle Fusion
Service:
doTransfer:
component: "System.AgentTransfer"
properties:
maxWaitSeconds: "300"
allowTransferIf: "agentSessionsAreAvailable"
# Example of passing a custom property to Oracle Fusion
Service
customProperties:
# This is a checkbox custom field in the Universal Work Object.
# Checkboxes take the value of Y (selected) or N (unselected).
- name: "TriagedByODA_c"
value: "Y"
acceptedMessage: "The conversation has been transferred to a live agent."
waitingMessage: "I'm transferring you to a human. Hold tight"
rejectedMessage: "Looks like no one is available. Please try later"
errorMessage: "We're unable to transfer you to a live agent because there was a system error."
transitions:
actions:
accepted: "reset"
rejected: "handleRejected"
error: "offerMoreHelp"
next: "reset"
Tip:
For Oracle Fusion Service, the rules evaluation stops at the first rule where all conditions are met. When you configure your rules, ensure that the transferred conversation isn't routed back to the digital assistant agent. In thedoTransfer
example, the custom property
TriagedByODA_c
is set to Y
, and the rules can use
this custom property to ensure that when it is set to Y
, the
conversation isn't routed to the digital assistant agent. (For Oracle B2C
Service, the Transition State and stop configuration determines the
routing.)
System.AgentTransferCondition
You can use the System.AgentTransferCondition
component in DA-as-agent digital assistants to determine whether agents are available and, if so, the expected wait time.
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Agent Transfer Condition.
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 as follows:
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.
Here's an example of using this component to find out if agents are available, report the wait time, and allow the users to cancel the transfer request if they don't want to wait that long.
handleAgentRequest:
component: "System.CommonResponse"
properties:
keepTurn: true
metadata:
responseItems:
- type: "text"
text: "I understand. Give me a moment while I see who might be available to help you."
transitions:
next: "evaluateAgentTransferCondition"
############################
# Agent Transfer
############################
# See if there are any agents available
evaluateAgentTransferCondition:
component: "System.AgentTransferCondition"
properties:
maxWaitSeconds: 300
maxEngagementsInQueue: 20
allowTransferIf: "agentsAreAvailable"
agentStatusVariable: "agentStatus"
transitions:
actions:
conditionsMet: "askIfWillWait"
conditionsNotMet: "handleRejected"
error: "handleTransferError"
next: "done"
askIfWillWait:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "${rb('promptTextForTransferDecision','minutes,seconds',agentStatus.value.expectedWaitMinutes,agentStatus.value.expectedWaitSeconds)}"
separateBubbles: true
actions:
- label: "Yes, I'll wait"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No, nevermind"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
actions:
yes: "transferToAgent"
no: "handleCancelled"
textReceived: "intent"
next: "handleCancelled"
# Perform the actual transfer
#
# The maxWaitSeconds, maxEngagementsInQueue, allowTransferIf,
# and customProperties, if any, should match those used for
# System.AgentTransferCondition
transferToAgent:
component: "System.AgentTransfer"
properties:
maxWaitSeconds: 300
maxEngagementsInQueue: 20
allowTransferIf: "agentsAreAvailable"
transitions:
actions:
accepted: "done"
rejected: "handleRejected"
error: "handleTransferError"
next: "handleTransferError"
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?
Property | Description | Required? | |
---|---|---|---|
agentStatusVariable |
The name of the context 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 .
|
No | |
allowTransferIf |
Specifies the base set of conditions that must be met.
If the specified conditions aren't met, then the |
No | |
customProperties |
A map that holds information to pass to the service. See Pass Information to the Service. This property is supported in version 21.04 and later. | No | |
errorMessage |
The message shown to the user when Digital Assistant experiences trouble with the agent chat service. Defaults to We were unable to check the agent transfer conditions because there was a system error. This default string is stored in the configuration resource bundle under the systemComponent_AgentTransferCondition_errorMessage key. You can set the property to a blank or empty string to suppress message output.
|
No | |
maxEngagementsInQueue |
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.
|
No | |
maxWaitSeconds |
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 maxWaitSeconds , then the conditionsNotMet action occurs. This property defaults to -1 , which means that there's no maximum wait time.
Note that the |
No |
This component can return the following actions:
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:
|
error |
The error transition is set when there's an issue with the connection to the agent chat service during the agent conditions check.
|
Example: Get Agent Availability and Wait Time
Here's an example of a dialog flow that invokes the component, displays the wait time, and gives the user the opportunity to cancel their transfer request.
############################
# Agent Transfer
############################
# See if there are any agents available
evaluateAgentTransferCondition:
component: "System.AgentTransferCondition"
properties:
maxWaitSeconds: 300
maxEngagementsInQueue: 20
allowTransferIf: "agentsAreAvailable"
agentStatusVariable: "agentStatus"
transitions:
actions:
conditionsMet: "askIfWillWait"
conditionsNotMet: "setInsightsCustomMetricsConditionsNotMet"
error: "handleTransferError"
next: "done"
# Measure when agents aren't available
setInsightsCustomMetricsConditionsNotMet:
component: "System.SetCustomMetrics"
properties:
dimensions:
- name: "Agent Transfer Choice"
value: "No agents available for new chats"
transitions:
next: "handleRejected"
askIfWillWait:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "${rb('promptTextForTransferDecision','minutes,seconds',agentStatus.value.expectedWaitMinutes,agentStatus.value.expectedWaitSeconds)}"
separateBubbles: true
actions:
- label: "Yes, I'll wait"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No, nevermind"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
actions:
yes: "setInsightsCustomMetricsAgentTransferInitiated"
no: "setInsightsCustomMetricsAgentTransferCancelled"
textReceived: "intent"
next: "handleCancelled"
# Measure when user chooses to wait for transfer
setInsightsCustomMetricsAgentTransferInitiated:
component: "System.SetCustomMetrics"
properties:
dimensions:
- name: "Agent Transfer Choice"
value: "User chose to wait"
transitions:
next: "transferToAgent"
# Measure when user chooses to not wait for transfer
setInsightsCustomMetricsAgentTransferCancelled:
component: "System.SetCustomMetrics"
properties:
dimensions:
- name: "Agent Transfer Choice"
value: "User didn't want to wait"
transitions:
next: "handleCancelled"
# Perform the actual transfer
#
# The maxWaitSeconds, maxEngagementsInQueue, allowTransferIf,
# and customProperties, if any, should match those used for
# System.AgentTransferCondition
transferToAgent:
component: "System.AgentTransfer"
properties:
maxWaitSeconds: 300
maxEngagementsInQueue: 20
allowTransferIf: "agentsAreAvailable"
transitions:
actions:
accepted: "done"
rejected: "handleRejected"
error: "handleTransferError"
next: "handleTransferError"
############################
# All done
############################
done:
component: "System.Output"
properties:
text: "Let me know if you need help on anything else."
transitions:
return: "done"
handleRejected:
component: "System.CommonResponse"
properties:
keepTurn: true
metadata:
responseItems:
- type: "text"
text: >
Unfortunately, none of my colleagues are currently available to assist with this.
Still, we’d love to see this through for you.
Please feel free to reach us through email@example.com.
transitions:
next: "done"
handleCancelled:
component: "System.CommonResponse"
properties:
keepTurn: true
metadata:
responseItems:
- type: "text"
text: "OK. Maybe some other time. Please feel free to reach us through email@example.com."
transitions:
next: "done"
handleTransferError:
component: "System.CommonResponse"
properties:
keepTurn: true
metadata:
responseItems:
- type: "text"
text: "Unfortunately, we can't transfer you at this time. Please try again later."
transitions:
next: "done"
############################
# Global error handler
############################
globalErrorHandler:
component: "System.Output"
properties:
text: "Sorry, we were unable to do the action that you requested."
transitions:
next: "done"
The askIfWillWait
state uses a resource bundle entry to form the
wait time message so that the message makes sense whether the time is more or less than a
minute and whether a number is 0, one or more.
There are some experts online. But it might take {minutes, plural,
=-1 {}
=0 {}
=1 {1 minute and }
other {# minutes and }
}{seconds, plural,
=-1 {a while}
=0 {{minutes, plural,
=0 {a very short wait time}
other {0 seconds}
}}
=1 {1 second}
other {# seconds}
} for one to join. Are you willing to wait?
Note that this example uses System.SetCustomMetrics to track if agents were available, and, if so, how many users chose to wait and how many canceled the transfer request.
Live-Agent-Transfer Components
System.AgentInitiation
If you want to transfer a skill's conversation to an Oracle B2C
Service agent, add this component to the dialog flow to initiate the handshake with the
agent-integration channel that's specified by the agentChannel
property. You
must call this component before you call the System.AgentConversation
component.
This component is for conversations that originate in the skill. Do not use this component for conversations that originate in Oracle B2C Service chat, as described in The Digital Assistant as Agent Framework in Action.
Here's an example of using this component to initiate the handshake with the Oracle B2C
Service instance that's defined by the agent integration channel named
ServiceCloudIntegration
.
agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "ServiceCloudIntegration"
nlpResultVariable: "iResult"
waitingMessage: "Waiting for an agent..."
rejectedMessage: "Agents are not available right now."
resumedMessage: "We're connecting you to an agent..."
errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now."
transitions:
actions:
accepted: "agentConversation"
rejected: "tryAgain"
error: "tryAgain"
agentConversation:
component: "System.AgentConversation"
properties:
agentChannel: "ServiceCloudIntegration"
nlpResultVariable: "iResult"
exitKeywords: "bye, exit, take care, goodbye, quit"
expiryMessage: "Your chat with the agent timed out."
conclusionMessage: "Your chat with the agent has ended."
waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
transitions:
next: "endPrompt"
actions:
agentLeft: "endPrompt"
expired: "sessionExpired"
error" "agentConversationError"
Tip:
In skills with platform version 21.04 and later, the default values for theagentActionsMessage
, errorMessage
, rejectedMessage
, resumedMessage
, and waitingMessage
properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the AgentInitiation - <property name> key. If you use the skill's resource bundle to change the default message, then you don't need to include the message property in the component unless you want to override the default.
Property | Description | Required? | |
---|---|---|---|
agentActions |
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:
The action names must correspond to the
You can define the
|
No | |
agentActionsMessage |
If the agentActions property is set, then the agent console displays this value instead of the default message. For example:
|
No | |
agentChannel |
Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the agentChannel property defined for the System.AgentConversation component must all match.
|
Yes | |
allowTransferIf |
Specifies the conditions under which the skill should transfer the chat session. The component uses the queueId 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.
If the specified condition is not met, the component returns When you include this property, you must also include the This property is only available in instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). |
No | |
chatResponseVariable |
Names the map variable that holds the agent response information. After the System.AgentInitiation component connects successfully, the map contains the following properties:
|
No | |
customProperties |
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.
|
No | |
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 server. | No | |
nlpResultVariable |
The variable that stores the customer’s query message. | No | |
rejectedMessage |
A message that displays if the AgentInitiation handshake was rejected, such as if it's outside of the configured operating hours. For example:
|
No | |
resumedMessage |
A message (such as, Just a minute...we're connecting you to an agent.) that displays when the customer's chat with the customer service representative resumes. Adding this property prevents customers whose requests have already been queued from receiving a misleading Resuming chat with agent message when they repeatedly request a live chat. | No | |
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 nlpResultVariable property, but you can also define this using a variable that you set earlier in the dialog flow definition. For example, you can define a string type context variable whose value gets set prior to the System.AgentInitiation component:
|
No | |
queueId |
The ID of the queue that the component must use
to determine whether the specified allowTransferIf 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 |
Required when the allowTransferIf property is present.
|
|
transcriptDateTimeFormat |
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 .
|
No | |
transcriptTimezoneName |
The Internet Assigned Numbers Authority (IANA) name of the time zone to use to format the conversation transcript using transcriptDateTimeFormat property. Example: America/Sao_Paulo . Defaults to Europe/London . If you don't include the transcriptDateTimeFormat property, then this property is ignored.
|
No | |
waitingMessage |
A message that displays while customers wait to connect to an agent. For example:
|
No |
System.AgentInitiation Transitions
System.AgentInitiation
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 System.AgentConversation
component: agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "ServiceCloudIntegration"
...
transitions:
actions:
accepted: "agentConversation"
rejected: "noAgentsAvailable"
error: "handshakeError"
Action | Description |
---|---|
accepted |
The handshake completed successfully and the state can transition to the state with the System.AgentConversation 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:
Note that if you don't set |
Example: Handle Agent Initiation Rejection and System Errors
Here's an example of handling system errors and the error
and rejected
actions.
agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
waitingMessage: "Let me connect you with someone who can further assist you."
resumedMessage: "Someone will be with you shortly."
errorMessage: "Oops! We're having system issues and we can't connect you with an agent right now."
rejectedMessage: "Unfortunately, no one's available right now."
transitions:
actions:
accepted: "agentConversation"
rejected: "initiationRejected"
error: "tryAgain"
error: "agentInitiationSystemError"
initiationRejected:
component: "System.Output"
properties:
text: "Perhaps it's outside their working hours or it's a holiday."
transitions:
return: "initiationRejected"
tryAgain:
component: "System.Output"
properties:
text: "Please try again later."
transitions:
return: "tryAgain"
agentInitiationSystemError:
component: "System.Output"
properties:
text: "I seem to be having a connection problem. Can you please email email@example.com to let them know?"
transitions:
return: "done"
Example: The incidentID Property
context:
variables:
liveChatInfo: "map"
customerTicketId: "int"
...
setCustomFields:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
incidentID: "${customerTicketId}" # long value
...
agentInitiation:
component: "System.AgentInitiation"
properties:
...
customProperties: "${liveChatInfo.value}"
Example: The Standard customerInformation Object
This example sets the contactID
.
context:
variables:
liveChatInfo: "map"
contactId: "int"
...
setCustomFields:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
customerInformation:
contactID:
id: "${customerId}"
...
agentInitiation:
component: "System.AgentInitiation"
properties:
...
customProperties: "${liveChatInfo.value}"
Example: The Legacy customerInformation Object
This example sets the interfaceID
and
contactID
.
Tip:
Because the WSDL specifies thatinterfaceID
is of type NamedID
, we could've used
name: "myInterfaceName"
instead of id: id:
"${interfaceId}"
.
context:
variables:
liveChatInfo: "map"
interfaceId: "int"
contactId: "int"
...
setCustomFields:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
customerInformation:
interfaceID:
id:
id: "${interfaceId}"
contactID:
id: "${customerId}"
...
agentInitiation:
component: "System.AgentInitiation"
properties:
...
customProperties: "${liveChatInfo.value}"
Example: The Standard customFields Object
context:
variables:
liveChatInfo: "map"
...
setupCustomFields:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
customFields:
- name: "c$text_field" # text field
type: "STRING"
value: "SILVER"
- name: "c$text_area" # text area
type: "STRING"
value: "My package arrived but there were no contents in the box. Just bubble wrap."
- name: "c$integer" # integer
type: "INTEGER"
value: 21
- name: "c$yes_no" # yes/no (1=yes and 0=no)
type: "BOOLEAN"
value: 1
- name: "c$date_field" # date (yyyy-MM-dd'T'00:00:00. Use 0 for time)
type: "DATE"
value: "2020-02-04T00:00:00+00:00"
- name: "c$date_time" # datetime (yyyy-MM-dd'T'HH:mm:ssXXX)
type: "DATETIME"
value: "2020-02-04T21:24:18+00:00"
- name: "c$menu" # menu (no type property, you can pass the string or the ID for the value property)
value: "12"
transitions:
...
...
agentInitiation:
component: "System.AgentInitiation"
properties:
...
customProperties: "${liveChatInfo.value}"
Example: The Legacy customFields Object
context:
variables:
liveChatInfo: "map"
skillType: "string"
...
setupCustomFields:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
customerInformation:
interfaceID:
id:
id: 1
customFields:
# Text Field
- name: "c$da_text_field"
dataType: "STRING"
dataValue:
stringValue: "SILVER"
# Text Area
- name: "c$da_text_area"
dataType: "STRING"
dataValue:
stringValue: "This is a very long string that is more than 32 characters."
# Integer
- name: "c$da_integer"
dataType: "INTEGER"
dataValue:
integerValue: 21
# Menu
- name: "c$da_menu"
dataType: "NAMED_ID"
dataValue:
namedIDValue:
name: "Item 1"
# Instead of name, you can use
# id:
# id: 1
#
# Yes/No
- name: "c$da_is_from_skill"
dataType: "BOOLEAN"
dataValue:
booleanValue: true
# Date (XML Schema Date)
- name: "c$da_date"
dataType: "DATE"
dataValue:
dateValue: "2019-10-26"
# DateTime (XML Schema DateTime)
- name: "c$da_datetime"
dataType: "DATETIME"
dataValue:
dateTimeValue: "2019-10-26T21:32:52"
transitions:
...
...
agentInitiation:
component: "System.AgentInitiation"
properties:
...
customProperties: "${liveChatInfo.value}"
Example: Assemble the Custom Properties Object
These steps describe how you can declare the customProperties
object and setting its various values.
Step 1: Declare the Custom Properties Variable
customProperties
property in the System.AgentInitiation
component. It’s a JSON object that can hold the chat customer information and custom field
values. In the following example, this variable is declared as
liveChatInfo
:context:
variables:
size: "PizzaSize"
type: "PizzaType"
crust: "PizzaCrust"
iResult: "nlpresult"
interfaceId: "string"
categoryId: "string"
skillType: "string"
liveChatInfo: "map"
Step 2: Set the Values for the customProperties Map Variable
customProperties
property in the System.AgentInitiation
component. It’s a JSON object that can hold the chat customer information and custom field
values. In the following example, this variable is declared as
liveChatInfo
:context:
variables:
size: "PizzaSize"
type: "PizzaType"
crust: "PizzaCrust"
iResult: "nlpresult"
interfaceId: "string"
categoryId: "string"
skillType: "string"
liveChatInfo: "map"
Step 3: Define the Fields for the customProperties Map Variable
setLiveChatInfo:
component: "System.SetVariable"
properties:
variable: "liveChatInfo"
value:
customerInformation:
categoryID:
id: "${categoryId}"
customFields:
- name: "c$skilltype"
type: "STRING"
value: "${skillType}"
transitions:
next: "agentInitiation"
Step 4: Add the customProperties to the System.AgentInitiation Component
customProperties
property to the
System.AgentInitiation
component and define it using an expression that accesses
the map variable
value. agentInitiation:
component: "System.AgentInitiation"
properties:
subject: "A customer needs help regarding ${skillType}."
agentChannel: "ServiceCloudIntegration"
waitingMessage: "Let me connect you with someone who can further assist you."
resumedMessage: "Please wait, someone will be with you shortly."
rejectedMessage: "Sorry no one is available now."
errorMessage: "We're sorry! We're having system issues and we can't connect you with an agent."
customProperties: "${liveChatInfo.value}"
transitions:
actions:
accepted: "agentConversation"
rejected: "initiationRejected"
error: "tryAgain"
initiationRejected:
component: "System.Output"
properties:
text: "Perhaps it's outside their working hours or it's a holiday."
transitions:
return: "tryAgain"
tryAgain:
component: "System.Output"
properties:
text: "Please try again later."
transitions:
return: "tryAgain"
System.AgentConversation
Use this component to transfer a skill's conversation to an Oracle B2C
Service live agent and to manage the skill-live agent interchange. Note that you must call the
System.AgentInitiation
component before you can use this component.
System.AgentConversation
is for conversations that originate in the
skill. Do not use this component for conversations that originate in Oracle B2C
Service chat, as described in The Digital Assistant as Agent Framework in Action.
Here's an example of using this component to transfer the conversation to the Oracle B2C
Service instance that's defined by the agent integration channel named
ServiceCloudIntegration
.
agentConversation:
component: "System.AgentConversation"
properties:
agentChannel: "ServiceCloudIntegration"
nlpResultVariable: "iResult"
errorMessage: "Oops, we lost connection with the agent. If you need further help, please call customer support."
exitKeywords: "bye, exit, take care, goodbye, quit"
expiryMessage: "Your chat with the agent timed out"
waitExpiryMessage: "The chat expired while waiting for an agent"
conclusionMessage: "Your chat with the agent has ended."
waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
transitions:
next: "endPrompt"
actions:
agentLeft: "endPrompt"
expired: "sessionExpired"
waitExpired: "expiredWhileWaiting"
error: "handleConnectionError"
Property | Description | Required? |
---|---|---|
agentChannel |
Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the agentChannel property defined for the System.AgentInitiation component must all match.
|
Yes |
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 agentActions . For example, Your chat with the agent has ended .
|
No |
errorMessage |
The message that the chat displays if there is a problem with the connection to
Oracle B2C
Service.
The default message is This property only works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). |
No |
exitKeywords |
A comma-delimited list of typical exit words used by a customer to end the conversation with the live agent. For example:
The property value defaults to |
No |
expiryMessage |
A message that displays when the expired action is triggered. The default message is Chat session expired. Thanks for chatting with us .
Note that the The expiry message isn't output when the conversation concludes because the Service Cloud |
No |
nlpResultVariable |
The nlpResultVariable variable that holds the customer's query message.
|
No |
waitExpiryMessage |
The message that's shown to the user when the chat expires while waiting for an
agent. The default message is The request for live chat expired while
waiting for an agent. |
No |
waitMessage |
By default, after the conversation transfer is initiated, the skill displays the wait message that the live chat service sends to the skill, such as the queue position and wait time. Use this property to customize the message. For example:
|
No |
System.AgentConversation Transitions
The System.AgentConversation
can trigger the
expired
, agentLeft
, error
, or
waitExpired
action. In addition, it can trigger any action from the
System.AgentInitiation
component's agentActions
property.
You need to add a next
transition as well, because a customer might enter one
of the exitKeywords
to leave the chat before any of these actions can get
triggered.
agentConversation:
component: "System.AgentConversation"
properties:
agentChannel: "ServiceCloudIntegration"
nlpResultVariable: "iResult"
exitKeywords: "bye, adios, take care, goodbye"
...
transitions:
next: "endPrompt"
actions:
agentLeft: "endPrompt"
expired: "endPrompt"
waitExpired: "endPrompt"
error: "agentConversationError"
...
endPrompt:
component: "System.List"
properties:
prompt: "Your session has ended. What would you like to do?"
options:
- label: "Order a Pizza"
value: "OrderPizza"
- label: "Nothing. I'm done here."
value: "Finished"
autoNumberPostbackActions: true
transitions:
actions:
OrderPizza: "resolvePizzaSize"
Finished: "done"
...
Action | Description |
---|---|
agentActions |
If the System.AgentInitiation component has an agentActions property, then this component should have a transition action for every supported action that's specified by agentActions .
|
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
|
error |
There is a problem connecting to the live agent service. This action only works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). |
expired |
If the Oracle B2C
Service
By default, The 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.
|
Example: Configure the Agent Transfer Dialog Flow
In this example, the GetAgent
intent is trained to
understand distress calls like help me please!
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
OrderPizza: "resolvesize"
CancelPizza: "cancelorder"
GetAgent: "agentInitiation"
unresolvedIntent: "agentInitiation"
Here are the basic steps for configuring the dialog flow:
-
Initiate the live-agent transfer.
-
Add a state for the
System.AgentInitiation
component. -
Set the state's
agentChannel
property to the name of the Agent Integration channel that you configured for the live-agent system.
After the Agent Integration channel establishes a connection and Oracle B2C Service sends the chat request to its queue (that is, after it creates a help ticket), theSystem.AgentInitiation
component allows the transition to the next state, which is typically defined for theSystem.AgentConversation
component (agentConversation
in the following example).agentInitiation: component: "System.AgentInitiation" properties: agentChannel: "ServiceCloudIntegration" nlpResultVariable: "iResult" waitingMessage: "Waiting for an agent..." rejectedMessage: "Agents are not available right now." resumedMessage: "We're connecting you to an agent..." errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now." transitions: actions: accepted: "agentConversation" rejected: "tryAgain" error: "tryAgain" tryAgain: component: "System.Output" properties: text: "Please try again later." transitions: return: "tryAgain"
Tip:
Customers may repeatedly request a live chat even though their requests have already been queued in the agent's chat console. Add aresumedMessage
property to theSystem.AgentInitiation
state to prevent such customers from receiving a misleading Resuming chat with agent message. -
-
Add and configure the
System.AgentConversation
component. While the dialog engine is in the state defined for this component, the skill passes messages back and forth between the customer and the agent. The skill listens for exit keywords in the customer input, likebye
. When the skill detects one of these keywords, theSystem.AgentConversation
component ends the live-chat session and triggers itsnext
transition.Here's an example:
agentConversation: component: "System.AgentConversation" properties: agentChannel: "ServiceCloudIntegration" nlpResultVariable: "iResult" errorMessage: "Oops, we lost connection with the agent. If you need further help, please call customer support." exitKeywords: "bye, exit, take care, goodbye, quit" expiryMessage: "Your chat with the agent timed out." conclusionMessage: "Your chat with the agent has ended." waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}." transitions: next: "endPrompt" actions: agentLeft: "endPrompt" expired: "endPrompt" error: "endPrompt" endPrompt: component: "System.Output" properties: text: "Returning you to your bot." transitions: return: "endPrompt"
Example: Get Survey Information
In the following example that uses the standard format, the
AgentConversation
component outputs a survey link after the agent
conversation ends. The link includes the session and engagement ID from the map that was
named by the chatResponseVariable
property.
context:
variables:
agentSystemResponse: "map" # chat request response is stored in this variable.
...
states:
...
agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
chatResponseVariable: "agentSystemResponse"
transitions:
actions:
accepted: "agentConversation"
rejected: "tryAgain"
error: "tryAgain"
agentConversation:
component: "System.AgentConversation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
exitKeywords: "bye, exit, take care, goodbye, quit"
expiryMessage: "Your chat with the agent timed out."
conclusionMessage: "Can you please fill out this survey: <PUT SURVEY URL HERE>?session=${agentSystemResponse.value.sessionId}&surveyid=${agentSystemResponse.value.engagementId}"
transitions:
next: "endPrompt"
actions:
agentLeft: "endPrompt"
expired: "sessionExpired"
error: "agentConversationError"
Example: Transfer the Chat to a Specific Oracle B2C Service Queue
-
If you haven't already, in the context node, define a map variable to use with the
System.AgentInitiation
component'scustomProperties
property. For example:context: variables: greeting: "string" name: "string" liveChatInfo: "map"
-
Define the fields for the map variable.
Here's an example of the standard format for agent-integration channels that were created in version 20.01 or later and that connect to Oracle B2C Service version 19A or later.
setLiveChatInfo: component: "System.SetVariable" properties: variable: "liveChatInfo" value: customFields: - name: "c$frombot" type: "BOOLEAN" value: 1 transitions: next: "agentInitiation"
Here's an example of the legacy format for agent-integration channels that were created prior to version 20.01 or that connect to a version that is earlier than Oracle B2C Service version 19A.
setLiveChatInfo: component: "System.SetVariable" properties: variable: "liveChatInfo" value: customFields: - name: "c$frombot" dataType: "BOOLEAN" dataValue: booleanValue: true transitions: next: "agentInitiation"
-
Add the
customProperties
property to theSystem.AgentInitiation
component, and set it to the value of your map variable. For example:agentInitiation: component: "System.AgentInitiation" properties: agentChannel: "B2CServiceIntegration" nlpResultVariable: "iResult" customProperties: "${liveChatInfo.value}" waitingMessage: "Waiting for an agent..." rejectedMessage: "Agents are not available right now." resumedMessage: "We're connecting you to an agent..." errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now." transitions: actions: accepted: "agentConversation" rejected: "tryAgain" error: "tryAgain" tryAgain: component: "System.Output" properties: text: "Please try again later." transitions: return: "tryAgain"
System.ResolveEntities
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Resolve Entity.
Iterates through all the entity fields in the composite bag, converses with the user and resolves all the fields. The component randomly chooses the prompts that you provide for each entity while resolving that entity.
Property | Description | Required | |
---|---|---|---|
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. | Yes | |
nlpResultVariable |
Populates the variable property (which references the composite bag entity variable) using the values stored in the nlpresult context variable. You can define this property by naming the nlpresult variable (typically, iResult ). When the framework resolves a single child entity, then the variable property gets populated with just that entity value. When the nlpresult variable holds values for all of the child entities, then the dialog flow transitions to the next state. You can use this property in place of the SetVariable states that populate the child entity values.
|
No | |
maxPrompts |
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. | No | |
autoNumberPostbackActions |
When you set to true , this option prefixes numbers to options. Even when you haven’t set this option to true , auto-numbering can be enforced on list items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true . Channel-specific auto-numbering can be applied to any skill bot that's registered to a digital assistant:
|
No | |
useFullEntityMatches |
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.
|
||
footerText |
Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. | No | |
headerText |
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).
|
No | |
transitionAfterMatch |
A boolean that, when you set it to
true , enables a temporary transition from the
entity matching performed by this component to a custom component. By
default, this is false . This property is ignored (and
the match transition is not triggered) if you've
registered an entity event handler.
|
No | |
cancelPolicy |
Determines the timing of the
cancel transition:
maxPromptsReached handler. |
No |
Calendar Components
Use these calendar components to interact with Outlook and Google calendars:
-
System.CreateCalendarEvent: Create an event
-
System.DeleteCalendarEvent: Cancel an event
-
System.GetCalendarEventDetails: Get details about an event
-
System.ListCalendarEvents: Get data for a filtered set of events
-
System.SelectCalendarEvent: Select an event from a filtered list
-
System.SendInviteResponse: Change an event's response status
-
System.UpdateCalendarEvent: Change an event
Calendar Authorization
To enable interaction between a skill and a calendar provider, you need to set up a service and modify the skill and dialog flow to enable the user to sign into their calendar through that service.
Before you use any calendar component, you must register an application with the calendar provider and create an authorization code service. See these topics to learn how:
In your dialog flow, you use the System.OAuth2AccountLink
component to prompt the user to sign into their calendar through the authorization code service that you created. Note that you can't set the component's enableSingleSignOn
property to true
when you use the component for calendar component authorization.
You can leverage the "requires authorization" feature to automatically ensure that the user has signed in (obtained an access token) before invoking any calendar components. This feature only asks the user to sign in if they don't have an access token yet or it has expired and can't be refreshed. You can use the skill's Requires Authorization configuration to set the default for the whole skill, and then use the state-level requiresAuthorization
setting to override the default. That is, you use the skill setting to set the default, and then only include the component requiresAuthorization
setting in the states for which the default doesn't apply.
To use the requires authorization feature, you must you add a system.authorizeUser
action to the defaultTransitions
node to name the state that starts the authorization flow. For example:
defaultTransitions:
error: "globalErrorHandler"
actions:
system.authorizeUser: "userAuthN.performOAuth"
Before a skill transitions to a state that requires authorization, it checks to see if there's a valid access token for the calendar service. If not, it does the following actions:
-
Invokes the state that you've defined for the
system.authorizedUser
action in thedefaultTransitions
node. -
Asks the user to sign in.
-
Transitions to the state that required authorization (that is, the state defined by
${system.requestedState}
).
Here's an authorization dialog flow example:
defaultTransitions:
error: "globalErrorHandler"
actions:
system.authorizeUser: "userAuthN.performOAuth"
...
############################
# Authenticate
############################
userAuthN.performOAuth:
component: "System.OAuth2AccountLink"
properties:
prompt: "User Authentication"
variable: "code"
linkLabel: "Sign into ${system.config.calendarProvider}"
authenticationService: "${system.config.authService}"
accessTokenVariableName: "user.accessToken"
authenticatedUserVariableName: "user.authenticatedUser"
enableSingleSignOn: false # SSO not supported for calendar components
transitions:
actions:
pass : "${system.requestedState}"
fail : "handleFailedLogin"
textReceived: "intent"
handleFailedLogin:
component: "System.Output"
requiresAuthorization: false
properties:
text: "Sorry, you aren't authorized to do that"
transitions:
return: "doneHandleFailedLogin"
For a skill that's mostly focused on calendar components, consider setting the skill's Requires Authorization configuration to true
, and then set the value to false only for those states that don't require authorization. In this example, any user can execute the initTimezoneOffset
and intent
states. Therefore, requiresAuthorization
is set to false
for those states. The states that work with the calendar components don't need to include requiresAuthorization
because the default is true
.
initTimezoneOffset:
requiresAuthorization: false
component: "System.SetVariable"
properties:
variable: "timezoneOffset"
value: <#attempt>${profile.timezoneOffset}<#recover>0</#attempt>
transitions:
next: "intent"
intent:
component: "System.Intent"
requiresAuthorization: false
properties:
variable: "iResult"
transitions:
actions:
SetupMeeting: "setUpMeeting"
CancelMeeting: "cancelMeeting"
ListMeetings: "listMeetings"
UpdateMeeting: "updateMeeting"
ListInvites: "listInvites"
RespondInvites: "respondInvites"
LogoutUser: "logoutUser"
unresolvedIntent: "greeting"
...
cancelMeeting.performDelete:
component: "System.DeleteCalendarEvent"
properties:
eventId: "${eventId}"
provider: "${system.config.calendarProvider}"
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "cancelMeeting.printSuccessMessage"
cancelMeeting.printSuccessMessage:
component: "System.Output"
properties:
text: "I've cancelled the meeting"
transitions:
return: "doneCancel"
Working with Calendar Dates and Times
When working with the calendar components, it's important to understand the relationship between calendar start and end times, DATE and TIME entities, and the local timezone.
When you create, update, or retrieve events, you use the local datetime for the start
and end
values, and you use either the timezoneOffset
or the timezone
property to tell the component how to calculate the universal time (UTC).
The calendar components' timezoneOffset
is different from the profile.timezoneOffset
. For calendar components, timezoneOffset
is the value that the component must add to the start
and end
values to obtain the UTC. You can derive a calendar component's' timezoneOffset
property value by multiplying profile.timezoneOffset
by -1.
The profile.timezoneOffset
might not always be available. This depends on whether the client provided the offset. For example, someone might build an Oracle Web app that doesn't set profile.timezoneOffset
. Therefore, it's a good idea to create a default timezone for cases where the profile.timezoneOffset
hasn't been set. For example:
initTimezoneOffset:
requiresAuthorization: false
component: "System.SetVariable"
properties:
variable: "timezoneOffset"
value: <#attempt>${profile.timezoneOffset}<#recover>${system.config.defaultTimezoneOffset}</#attempt>
transitions:
next: "intent
When you retrieve an event, the component returns the datetime values in UTC format. For example: 2021-04-15T22:00:00.000Z
. Your skill needs to convert the value to the local time.
updateMeeting.printEventDetails:
component: "System.Output"
properties:
keepTurn: true
text: |
You selected:
${eventDetails.value.subject}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
Location: ${eventDetails.value.location}
Attendees: ${eventDetails.value.attendees?join(', ')}
transitions:
next: "updateMeeting.selectItemToChange"
When you use the DATE and TIME entities, here are some things to consider:
-
If you use a composite bag that has both a DATE entity and one or more TIME entities, then you must disable Out of Order Extraction. Otherwise, when the entities are resolved, you don't have control over which values resolve to the DATE entity and which values resolve to the TIME entity (or both). For example, when the TIME is resolved, it might change the value of the DATE entity.
-
When an utterance contains text such as "yesterday", "today", or "tomorrow", the parser doesn't take the local time zone into consideration. Therefore, it's possible that, in the early morning and late afternoon, the wrong date might be used. For that reason, it's a good idea to echo back the resolved date so that the user can verify it before the skill adds an event or updates an event's start or end time.
-
To set a calendar's
start
andend
property values, you must use the date from the DATE entity and the time from the TIME entity. For example:start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}" end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"
Handling Calendar Errors
The calendar provider may reject an event request. For example, it might return an error if the user tries to create an event that has an end time earlier than the start time. In most cases, the calendar provider returns a 400 error, which, in turn, transitions the skill to the global error handler.
Consider validating the values to prevent these errors from occurring. Here are examples of composite bag entity validations:
-
DATE entity: For new and updated meetings, validate that the date is on or after the current date.
${(meetingSlot.value.date.date?number?long gte ((.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']+'T00:00:00')?datetime.iso?long)?then('true','false')}
-
TIME entity: For new and updated meetings, verify that the date and start time are on or after the current datetime.
${(((meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']+'T'+meetingSlot.value.startTime.date?number_to_date?string['HH:mm:ss'])?datetime.iso?long) gte (.now?date?long - timezoneOffset?number))?then('true','false')}
For all end times, verify that the end time is after the start time.
${(newEvent.value.startTime.date?number_to_time < newEvent.value.endTime.date?number_to_time)?then('true','false')}
To handle calendar-provider rejections gracefully, add your own global error handler. For example:
defaultTransitions:
error: "globalErrorHandler"
actions:
system.authorizeUser: "userAuthN.performOAuth"
...
globalErrorHandler:
requiresAuthorization: false
component: "System.Output"
properties:
text: "Sorry, we were unable to do the action that you requested."
transitions:
return: "done"
Alternatively, you can use the error transition to create error handlers that are appropriate for each case:
setUpMeeting.performSchedule:
component: "System.CreateCalendarEvent"
properties:
start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}"
end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"
subject: "${newEvent.value.subject}"
location: "${newEvent.value.location}"
attendees: "${newEvent.value.attendees}"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "setUpMeeting.printResults"
error: "handleCreateEventError"
...
handleCreateEventError:
requiresAuthorization: false
component: "System.Output"
properties:
text: "Sorry, there's a problem with the event that you wanted to create."
transitions:
return: "done"
System.CreateCalendarEvent
Use this component to add an event to an Outlook or Google calendar. Note that you can't create recurring or all-day events.
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
To learn how to set the start
and end
values, see Working with Calendar Dates and Times.
Here's an example of how to use this component. In this example, a composite bag entity is used to get the date, start and end times, subject, location, and attendees.
####################
# Create Meeting
####################
setUpMeeting:
component: "System.CommonResponse"
properties:
keepTurn: true
processUserMessage: true
variable: "newEvent"
nlpResultVariable: "iResult"
cancelPolicy: "immediate"
transitionAfterMatch: "false"
metadata:
responseItems:
- type: "text"
text: "${system.entityToResolve.value.prompt}"
actions:
- label: "${enumValue}"
type: "postback"
iteratorVariable: "system.entityToResolve.value.enumValues"
payload:
variables:
newEvent: "${enumValue}"
globalActions:
- label: "Cancel"
type: "postback"
visible:
onInvalidUserInput: false
payload:
action: "cancel"
transitions:
actions:
cancel: "allDone"
next: "setUpMeeting.askConfirm"
setUpMeeting.askConfirm:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: |
Create ${newEvent.value.subject} meeting on ${newEvent.value.date.date?number_to_date?string['MMM d']}
from ${newEvent.value.startTime.date?number_to_date?string['hh:mm a']} to ${newEvent.value.endTime.date?number_to_date?string['hh:mm a']}
at ${newEvent.value.location} with ${newEvent.value.attendees}?
name: "confirmCreate"
separateBubbles: true
actions:
- label: "Yes"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
next: "intent"
actions:
yes: "setUpMeeting.performSchedule"
no: "allDone"
textReceived: "intent"
setUpMeeting.performSchedule:
component: "System.CreateCalendarEvent"
properties:
start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}"
end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"
subject: "${newEvent.value.subject}"
location: "${newEvent.value.location}"
attendees: "${newEvent.value.attendees}"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "setUpMeeting.printResults"
error: "handleCreateCalendarError"
setUpMeeting.printResults:
component: "System.Output"
properties:
text: "The ${newEvent.value.date.date?number_to_date?string['MMM d']} meeting is now on your calendar."
keepTurn: true
transitions:
next: "setUpMeeting.getMeetings"
...
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
start |
The meeting's start date and time in the format yyyy-MM-dd'T'HH:mm:ss For example, 2021-02-26T09:55:00 .
|
Yes |
end |
The meeting's end date and time in the format yyyy-MM-dd'T'HH:mm:ss . For example, 2021-02-26T09:55:00 .
|
Yes |
subject |
The subject of the meeting. | Yes |
attendees |
A comma separated list of attendees. Note that the calendar provider can't send a notification to an attendee if the ID isn't a valid account ID for that provider. | Yes |
timezoneOffset |
The amount of time in milliseconds to add to universal time (UTC) to get standard time in the user's time zone. For example, if the local time zone is UTC-2, then the timezoneOffset is -7200000 . The default value is 0.
Note
You can derive the timezoneOffset property for the current user based on the value of the user context variable profile.timezoneOffset . However, if you do so, you must multiply profile.timezoneOffset by -1.
You can specify |
No |
timezone |
The local time zone's ID as identified by https://www.iana.org/time-zones. Also referred to as the TZ database name. For example: |
No |
System.DeleteCalendarEvent
Use this component to delete an event from an Outlook or Google calendar. Note that you can't delete recurring or all-day events.
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
Here's an example of how to use this component.
####################
# Cancel Meeting
####################
# Want to select from deletable meetings
cancelMeeting:
component: "System.SetVariable"
properties:
variable: "stateAfterList"
value: "cancelMeeting.confirmCancel"
transitions:
next: "cancelMeeting.setListType"
cancelMeeting.setListType:
component: "System.SetVariable"
properties:
variable: "listType"
# Only show deletable meetings
value: "DELETE"
transitions:
next: "cancelMeeting.setListPrompt"
cancelMeeting.setListPrompt:
component: "System.SetVariable"
properties:
variable: "listPrompt"
value: "to cancel"
transitions:
next: "listMeetings.commonEntryPoint"
# List meetings common code returns to this state
cancelMeeting.confirmCancel:
component: "System.ResetVariables"
properties:
variableList: "confirmAction"
transitions:
next: "cancelMeeting.askConfirm"
cancelMeeting.askConfirm:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "Are you sure you want to cancel this meeting?"
name: "confirmCcancel"
separateBubbles: true
actions:
- label: "Yes"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
next: "intent"
actions:
yes: "cancelMeeting.performDelete"
no: "allDone"
textReceived: "intent"
cancelMeeting.performDelete:
component: "System.DeleteCalendarEvent"
properties:
eventId: "${eventId}"
provider: "${system.config.calendarProvider}"
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "cancelMeeting.printSuccessMessage"
cancelMeeting.printSuccessMessage:
component: "System.Output"
properties:
text: "I've cancelled the meeting"
transitions:
return: "doneCancel"
...
############################
# List Meetings Shared Code
############################
listMeetings.commonEntryPoint:
component: "System.SetVariable"
properties:
variable: "inputDate"
value: "${iResult.value.entityMatches['DATE'][0]}"
transitions:
next: "listMeetings.setDate"
listMeetings.setDate:
component: "System.SetVariable"
properties:
variable: "start"
value: "${inputDate.value?has_content?then(inputDate.value.date?number_to_date?string['yyyy-MM-dd'], (.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd'])}T00:00:00"
transitions:
next: "listMeetings.clearInputDate"
listMeetings.clearInputDate:
component: "System.ResetVariables"
properties:
variableList: "inputDate"
transitions:
next: "listMeetings.filterByAttendees"
listMeetings.filterByAttendees:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "Do you want to list only meetings with a particular attendee?"
name: "confirmFilter"
separateBubbles: true
actions:
- label: "Yes"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
next: "intent"
actions:
yes: "listMeetings.resolveAttendeesFilter"
no: "listMeetings.clearAttendeesFilter"
textReceived: "intent"
# clear filter
listMeetings.clearAttendeesFilter:
component: "System.ResetVariables"
properties:
variableList: "attendees"
transitions:
next: "listMeetings.performList"
# resolve filter
listMeetings.resolveAttendeesFilter:
component: "System.CommonResponse"
properties:
keepTurn: true
processUserMessage: true
variable: "attendees"
nlpResultVariable: "iResult"
metadata:
responseItems:
- type: "text"
text: "Who is the attendee?"
transitions:
next: "listMeetings.performAttendeesList"
actions:
textReceived: "listMeetings.performAttendeesList"
# perform attendees list
listMeetings.performAttendeesList:
component: "System.SelectCalendarEvent"
properties:
listType: "${listType}"
start: "${start}"
attendees: "${attendees}"
prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
actions:
found: "${stateAfterList}"
notfound: "listMeetings.printNotFoundMessage"
next: "globalErrorHandler"
# perform list
listMeetings.performList:
component: "System.SelectCalendarEvent"
properties:
listType: "${listType}"
start: "${start}"
prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
actions:
found: "${stateAfterList}"
notfound: "listMeetings.printNotFoundMessage"
next: "globalErrorHandler"
listMeetings.printNotFoundMessage:
component: "System.Output"
properties:
text: "There are no meetings on ${start?datetime.iso?long?number_to_date?string['MMM d']}"
transitions:
return: "doneListMeetings"
...
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
eventId |
The ID of the event to delete. You can use System.ListCalendarEvents or System.SelectCalendarEvent to get an eventId .
|
Yes |
System.GetCalendarEventDetails
Use this component to get an event's details from an Outlook or Google calendar.
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
The details are returned in the variable that's specified by the eventDetailsVariableName
property in the following JSON format:
{
"isAllDay": boolean,
"subject": string,
"inviteResponse": string,
"attendees": [
"string",
...
],
"start": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
"end": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
"location": string,
"isRecurring": boolean,
"id": string
}
The start
and end
properties are UTC values. To learn how to convert the start
and end
values to local time, see Working with Calendar Dates and Times.
Here's an example of how to use this component.
listMeetings.performGetDetails:
component: "System.GetCalendarEventDetails"
properties:
eventId: "${eventId}"
eventDetailsVariableName: "eventDetails"
provider: "${system.config.calendarProvider}"
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "listMeetings.checkIfResults"
# In case the eventId is no longer valid
listMeetings.checkIfResults:
component: "System.ConditionExists"
properties:
variable: "eventDetails"
transitions:
actions:
exists: "listMeetings.printEventDetails"
notexists: "globalErrorHandler"
listMeetings.printEventDetails:
component: "System.Output"
properties:
text: |
${eventDetails.value.subject}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
Location: ${eventDetails.value.location}
Attendees: ${eventDetails.value.attendees?join(', ')}
transitions:
return: "doneGetDetails"
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
eventId |
The ID of the event to retrieve. You can use System.ListCalendarEvents or System.SelectCalendarEvent to get an eventId .
|
Yes |
eventDetailsVariableName |
The name of the context variable in which to store the details. | Yes |
System.ListCalendarEvents
Use this component to get an array of Outlook or Google events for a named calender owner. You can filter the list by these attributes:
- The event can be deleted
- The event can be updated
- The user was invited to the event
- How the user has responded to an invitation
- The event includes one or more named attendees
- The meeting starts after a date and time
- The meeting ends before a date and time
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
The list is returned in the variable that's specified by the eventListVariableName
property in the following JSON format:
[{
"isAllDay": boolean,
"subject": string,
"inviteResponse": string,
"start": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
"end": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
"isRecurring": boolean,
"id": string
}, …]
To learn how to set the start
and end
values, see Working with Calendar Dates and Times. That topic also shows how to convert the JSON start
and end
property values to local time.
Here's an example of how to use this component.
############################
# List Invites
############################
listInvites:
component: "System.ListCalendarEvents"
properties:
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
listType: "INVITED"
response: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
eventListVariableName: "eventList"
start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
transitions:
next: "globalErrorHandler"
actions:
found: "listInvites.printMeetings"
notfound: "listInvites.notFound"
listInvites.printMeetings:
component: "System.CommonResponse"
properties:
keepTurn: true
metadata:
responseItems:
- type: "text"
# display the local time
text: |
${eventList.subject} [${eventList.inviteResponse}]
${(eventList.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d hh:mm a']} to ${(eventList.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
name: "event"
separateBubbles: true
iteratorVariable: "eventList"
processUserMessage: false
transitions:
return: "listInvitesDone"
listInvites.notFound:
component: "System.Output"
properties:
keepTurn: true
text: "You don't have any invitations for the next 14 days"
transitions:
return: "listInvitesDone"
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
listType |
Indicates the type of list. Must be one of the following:
|
Yes |
eventListVariableName |
The name of the context variable in which to store the events list. | Yes |
start |
The earliest date and time for which meetings should be included in the list (format: yyyy-MM-dd'T'HH:mm:ss ). For example, 2021-02-26T09:55:00 .
|
Yes |
end |
The latest date and time for which meetings should be included in the list (format: yyyy-MM-dd'T'HH:mm:ss ). For example, 2021-02-26T09:55:00 .
For list type |
No |
attendees |
A comma-separated, case-insensitive list of strings to use to filter the list by attendees. Only meetings where one or more attendee values contain one or more strings in the list are included in the output. | No |
response |
A comma-separated list of invitation statuses to filter the list on when the listType is INVITED . The allowable statuses are:
The default is |
No |
timezoneOffset |
The amount of time in milliseconds to add to universal time (UTC) to get standard time in the user's time zone. For example, if the local time zone is UTC-2, then the timezoneOffset is -7200000 . The default value is 0.
Note
You can derive the timezoneOffset property for the current user based on the value of the user context variable profile.timezoneOffset . However, if you do so, you must multiply profile.timezoneOffset by -1.
You can specify |
No |
timezone |
The local time zone's ID as identified by https://www.iana.org/time-zones. Also referred to as the TZ database name. For example: America/Los_Angeles . The default is UTC . You can specify timezoneOffset or timezone but not both.
|
No |
This component can return the following actions:
Action | Description |
---|---|
found |
One or more events were returned. |
notfound |
There are no matching events. |
System.SelectCalendarEvent
Use this component to display a list of Outlook or Google events that the user can select from. The component saves the ID of the selected event in the variable that's specified by the eventIdVariableName
property.
You can filter the list to select from by these attributes:
- The event can be deleted
- The event can be updated
- The user was invited to the event
- How the user has responded to an invitation
- The event includes one or more named attendees
- The meeting starts after a date and time
- The meeting ends before a date and time
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
To learn how to set the start
and end
values, see Working with Calendar Dates and Times.
Here's an example of how to use this component.
############################
# Respond Invites
############################
respondInvites.performList:
component: "System.SelectCalendarEvent"
properties:
listType: "INVITED"
response: "${inviteFilter}"
# Note: For list type INVITED the default end date is 14 days after the start date and time.
start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
prompt: "Select the invitation to send the response to:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "globalErrorHandler"
actions:
found: "respondInvites.resolveInviteResponse"
notfound: "respondInvites.printNotFoundMessage"
respondInvites.printNotFoundMessage:
component: "System.Output"
properties:
text: "There are no meeting invites."
transitions:
return: "allDone"
...
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
listType |
Indicates the type of list. Must be one of the following:
|
Yes |
eventIdVariableName |
The name of the context variable in which to store the event's ID. | Yes |
start |
The earliest date and time for which meetings should be included in the list (format: yyyy-MM-dd'T'HH:mm:ss ). For example, 2021-02-26T09:55:00 .
|
Yes |
end |
The latest date and time for which meetings should be included in the list (format: yyyy-MM-dd'T'HH:mm:ss ). For example, 2021-02-26T09:55:00 .
For list type |
No |
attendees |
A comma-separated, case-insensitive list of strings to use to filter the list by attendees. Only meetings where one or more attendee values contain one or more strings in the list are included in the output. | No |
response |
A comma-separated list of invitation statuses to filter the list on when the listType is INVITED . The allowable statuses are:
The default is |
No |
prompt |
The text that appears before the list. The default is You have the following meeting(s): You don't need to include this property unless you want to override the default.
Tip: In skills with platform version 21.04 and later, the default value is stored in the skill's resource bundle. To change the default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the SelectCalendarEvent - prompt key. |
No |
allDayLabel |
The text to indicate all-day events. The default is All day .
|
No |
recurringLabel |
The text to indicate a recurring event. The default is Recurring .
|
No |
acceptedLabel |
The text to indicate that the calendar owner accepted the invitation. The default is Accepted .
|
No |
tentativeLabel |
The text to indicate that the calendar owner tentatively accepted the invitation. The default is Tentative .
|
No |
declinedLabel |
The text to indicate that the calendar owner declined the invitation. The default is Declined .
|
No |
pendingLabel |
The text to indicate that the calendar owner hasn't responded to the invitation. The default is Pending .
|
No |
timezoneOffset |
The amount of time in milliseconds to add to universal time (UTC) to get standard time in the user's time zone. For example, if the local time zone is UTC-2, then the timezoneOffset is -7200000 . The default value is 0.
Note
You can derive the timezoneOffset property for the current user based on the value of the user context variable profile.timezoneOffset . However, if you do so, you must multiply profile.timezoneOffset by -1.
You can specify |
No |
timezone |
The local time zone's ID as identified by https://www.iana.org/time-zones. Also referred to as the TZ database name. For example: America/Los_Angeles . The default is UTC . You can specify timezoneOffset or timezone but not both.
|
No |
This component can return the following actions:
Action | Description |
---|---|
found |
One or more events were returned. |
notfound |
There are no matching events. |
System.SendInviteResponse
Use this component to accept, tentatively accept, or decline an invitation for an Outlook or Google calendar event.
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
Here's an example of how to use this component.
############################
# Respond Invites
############################
respondInvites:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "Which types of meeting invitations do you want to respond to?"
name: "getInviteFilter"
separateBubbles: true
actions:
- label: "Pending and tentatively accepted invitations"
type: "postback"
keyword: "PENDING,TENTATIVE"
payload:
variables:
inviteFilter: "PENDING,TENTATIVE"
- label: "All invitations"
keyword: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
type: "postback"
payload:
variables:
inviteFilter: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
- label: "Cancel"
keyword: "cancel"
type: "postback"
payload:
action: "allDone"
transitions:
actions:
allDone: "allDone"
textReceived: "intent"
next: "respondInvites.performList"
respondInvites.performList:
component: "System.SelectCalendarEvent"
properties:
listType: "INVITED"
response: "${inviteFilter}"
# Note: For list type INVITED the default end date is 14 days after the start date and time.
start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
prompt: "Select the invitation to send the response to:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "globalErrorHandler"
actions:
found: "respondInvites.resolveInviteResponse"
notfound: "respondInvites.printNotFoundMessage"
respondInvites.printNotFoundMessage:
component: "System.Output"
properties:
text: "There are no meeting invites."
transitions:
return: "allDone"
############################
# Invite Response
############################
respondInvites.resolveInviteResponse:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "Choose a response:"
name: "getInviteResponse"
separateBubbles: true
actions:
- label: "Accept"
type: "postback"
keyword: "ACCEPTED"
payload:
variables:
inviteResponse: "ACCEPTED"
- label: "Tentatively accept"
keyword: "TENTATIVE"
type: "postback"
payload:
variables:
inviteResponse: "TENTATIVE"
- label: "Decline"
keyword: "DECLINED"
type: "postback"
payload:
variables:
inviteResponse: "DECLINED"
- label: "Don't send a response"
keyword: "CANCEL"
type: "postback"
payload:
action: "allDone"
transitions:
actions:
allDone: "allDone"
textReceived: "intent"
next: "respondInvites.performRespond"
respondInvites.performRespond:
component: "System.SendInviteResponse"
properties:
eventId: "${eventId}"
response: "${inviteResponse}"
provider: "${system.config.calendarProvider}"
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "respondInvites.printSuccessMessage"
respondInvites.printSuccessMessage:
component: "System.Output"
properties:
text: "I've sent the meeting invitation response"
transitions:
return: "doneSendInviteResponse"
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
eventId |
The ID of the event to send the response to. You can use System.ListCalendarEvents or System.SelectCalendarEvent to get the ID of calender events to which the calendar owner was invited.
|
Yes |
response |
The response to send. The allowable responses are:
|
Yes |
System.UpdateCalendarEvent
Use this component to make changes to an Outlook or Google calendar event. Note that you can't update recurring or all-day events.
The user must be signed in to the calendar provider to access this component. You can use the "requires authorization" feature to manage user sign in, as described in Calendar Authorization.
To learn how to set the start
and end
values, see Working with Calendar Dates and Times.
Here's an example of how to use this component. In this example, a composite bag entity is used to get the date, the start time, and the end time.
####################
# Update Meeting
####################
updateMeeting:
component: "System.SetVariable"
properties:
variable: "stateAfterList"
value: "updateMeeting.performGetDetails"
transitions:
next: "updateMeeting.setListType"
updateMeeting.setListType:
component: "System.SetVariable"
properties:
variable: "listType"
# Only show updateable meetings
value: "UPDATE"
transitions:
next: "updateMeeting.setListPrompt"
updateMeeting.setListPrompt:
component: "System.SetVariable"
properties:
variable: "listPrompt"
value: "to update"
transitions:
next: "listMeetings.commonEntryPoint"
# List meetings common code returns to this state
updateMeeting.performGetDetails:
component: "System.GetCalendarEventDetails"
properties:
eventId: "${eventId}"
eventDetailsVariableName: "eventDetails"
provider: "${system.config.calendarProvider}"
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "updateMeeting.checkIfResults"
updateMeeting.checkIfResults:
component: "System.ConditionExists"
properties:
variable: "eventDetails"
transitions:
actions:
exists: "updateMeeting.printEventDetails"
notexists: "globalErrorHandler"
updateMeeting.printEventDetails:
component: "System.Output"
properties:
keepTurn: true
text: |
You selected:
${eventDetails.value.subject}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
Location: ${eventDetails.value.location}
Attendees: ${eventDetails.value.attendees?join(', ')}
transitions:
next: "updateMeeting.updateTime"
# Change meeting time
updateMeeting.updateTime:
component: "System.ResolveEntities"
properties:
variable: "meetingSlot"
nlpResultVariable: "iResult"
maxPrompts: 5
cancelPolicy: "immediate"
transitions:
actions:
cancel: "allDone"
next: "updateMeeting.setStart"
updateMeeting.setStart:
component: "System.SetVariable"
properties:
variable: "start"
value: "${meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']}T${meetingSlot.value.startTime.date?number_to_date?string['HH:mm:ss']}"
transitions:
next: "updateMeeting.setEnd"
updateMeeting.setEnd:
component: "System.SetVariable"
properties:
variable: "end"
value: "${meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']}T${meetingSlot.value.endTime.date?number_to_date?string['HH:mm:ss']}"
transitions:
next: "updateMeeting.updateTime.performUpdate"
updateMeeting.updateTime.performUpdate:
component: "System.UpdateCalendarEvent"
properties:
eventId: "${eventId}"
start: "${start}"
end: "${end}"
provider: "${system.config.calendarProvider}"
#timezone: "${system.config.timezoneID}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
next: "updateMeeting.printSuccessMessage"
error: "handleUpdateCalendarError"
...
############################
# List Meetings Shared Code
############################
listMeetings.commonEntryPoint:
component: "System.SetVariable"
properties:
variable: "inputDate"
value: "${iResult.value.entityMatches['DATE'][0]}"
transitions:
next: "listMeetings.setDate"
listMeetings.setDate:
component: "System.SetVariable"
properties:
variable: "start"
value: "${inputDate.value?has_content?then(inputDate.value.date?number_to_date?string['yyyy-MM-dd'], (.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd'])}T00:00:00"
transitions:
next: "listMeetings.clearInputDate"
listMeetings.clearInputDate:
component: "System.ResetVariables"
properties:
variableList: "inputDate"
transitions:
next: "listMeetings.filterByAttendees"
listMeetings.filterByAttendees:
component: "System.CommonResponse"
properties:
processUserMessage: true
metadata:
responseItems:
- type: "text"
text: "Do you want to list only meetings with a particular attendee?"
name: "confirmFilter"
separateBubbles: true
actions:
- label: "Yes"
type: "postback"
keyword: "yes"
payload:
action: "yes"
name: "Yes"
- label: "No"
keyword: "no"
type: "postback"
payload:
action: "no"
name: "No"
transitions:
next: "intent"
actions:
yes: "listMeetings.resolveAttendeesFilter"
no: "listMeetings.clearAttendeesFilter"
textReceived: "intent"
# clear filter
listMeetings.clearAttendeesFilter:
component: "System.ResetVariables"
properties:
variableList: "attendees"
transitions:
next: "listMeetings.performList"
# resolve filter
listMeetings.resolveAttendeesFilter:
component: "System.CommonResponse"
properties:
keepTurn: true
processUserMessage: true
variable: "attendees"
nlpResultVariable: "iResult"
metadata:
responseItems:
- type: "text"
text: "Who is the attendee?"
transitions:
next: "listMeetings.performAttendeesList"
actions:
textReceived: "listMeetings.performAttendeesList"
# perform attendees list
listMeetings.performAttendeesList:
component: "System.SelectCalendarEvent"
properties:
listType: "${listType}"
start: "${start}"
attendees: "${attendees}"
prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
actions:
found: "${stateAfterList}"
notfound: "listMeetings.printNotFoundMessage"
next: "globalErrorHandler"
# perform list
listMeetings.performList:
component: "System.SelectCalendarEvent"
properties:
listType: "${listType}"
start: "${start}"
prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
eventIdVariableName: "eventId"
provider: "${system.config.calendarProvider}"
timezoneOffset: ${timezoneOffset?number * -1}
calendarOwner: "${user.authenticatedUser}"
calendarId: "${user.authenticatedUser}"
credential: "${user.accessToken}"
transitions:
actions:
found: "${stateAfterList}"
notfound: "listMeetings.printNotFoundMessage"
next: "globalErrorHandler"
listMeetings.printNotFoundMessage:
component: "System.Output"
properties:
text: "There are no meetings on ${start?datetime.iso?long?number_to_date?string['MMM d']}"
transitions:
return: "doneListMeetings"
...
This component is supported in Oracle Digital Assistant Version 21.02 and later.
Property | Description | Required? |
---|---|---|
provider |
The calendar provider. The allowed values are Google and Outlook .
|
Yes |
calendarOwner |
The user ID of the calendar owner. It must be a valid account ID for the calendar provider, such as the value of the variable that's identified by the System.OAuth2AccountLink component's authenticatedUserVariable property, which is set when the user authenticates.
|
Yes |
calendarId |
The name of the calendar. For the user's default calendar, set to the same value as the calendarOwner property.
|
Yes |
credential |
The provider's access token. This is the value of the variable that's identified by the System.OAuth2AccountLink component's accessTokenVariableName property, which is set when the user authenticates.
|
Yes |
eventId |
The ID of the event to update. You can use System.ListCalendarEvents or System.SelectCalendarEvent to get an eventId .
|
Yes |
start |
The new start date and time in the format yyyy-MM-dd'T'HH:mm:ss For example, 2021-02-26T09:55:00 .
|
No |
end |
The new end date and time in the format yyyy-MM-dd'T'HH:mm:ss For example, 2021-02-26T09:55:00 .
|
No |
subject |
The new subject of the meeting. | Yes |
attendees |
A comma separated list of attendees. This list replaces the previous list. Note that the calendar provider can't send a notification to an attendee if the ID isn't a valid account ID for that provider. | Yes |
timezoneOffset |
The amount of time in milliseconds to add to universal time (UTC) to get standard time in the user's time zone. For example, if the local time zone is UTC-2, then the timezoneOffset is -7200000 . The default value is 0.
Note
You can derive the timezoneOffset property for the current user based on the value of the user context variable profile.timezoneOffset . However, if you do so, you must multiply profile.timezoneOffset by -1.
You can specify |
No |
timezone |
The local time zone's ID as identified by https://www.iana.org/time-zones. Also referred to as the TZ database name. For example: America/Los_Angeles . The default is UTC . You can specify timezoneOffset or timezone but not both.
|
No |
Footers
This footer displays on all channels, even ones that support buttons like Facebook. However, you can configure channel-specific rendering for the footer. To do this:
-
Define the
autoNumberPostbackActions
variable using thesystem.message
expression.setAutoNumbering: component: "System.SetVariable" properties: variable: "autoNumberPostbackActions" value: "${(system.channelType=='facebook')?then('true','false')}"
-
Define the
footerText
definition with an Apache FreeMarkerif
directive to display or hide the footer based on the channel type.footerText: <#if autoNumberPostbackActions.value>"Make your choice by entering the menu option number."</#if>
On Facebook, the System.CommonResponse renders the footer text in its own text bubble that appears just before the global actions (the quick replies). The footer can’t display after these actions, because that requires a second footer text bubble that causes the actions to disappear.
The translate Property
translate
property that overrides the global autoTranslate
variable setting:
-
If you set the
autoTranslate
variable tofalse
(the default), then no autotranslation occurs on the component unless you set thetranslate
property totrue
. -
If you set the
autoTranslate
variable totrue
, then thetranslate
property is implicitly set totrue
as well, which means that the label, title, description, prompt and text strings will be translated.
autotranslate
by setting it to
true
, then setting a component’s translate
property to false
excludes its prompt, title, description, label and
text strings from translation. Conversely, if you don’t enable
autotranslate
, but a component's translate
property is set to true
, then the component’s prompt, title,
description, label, and text string is translated into the detected user language using
the configured translation service. (Input components translate the user input into
English.)
autoTranslate is set to... | ...and the component’s translate property is set to... | ...then the user input, prompt, label, text, title, and description get translated |
---|---|---|
true |
not set | yes |
true |
true |
yes |
true |
false |
no |
false |
not set | no |
false |
false |
no |
false |
true |
yes |
Flows designed with the Visual Flow Designer don't have the
translate
property or autoTranslate
context variable. To configure translation for
those skills you use the Translate User Input Message and
Translate Bot Response Message properties.
System.Feedback
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see User Feedback.
The System.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.
System.Feedback Component Properties
Property | Description |
---|---|
maxRating |
The maximum rating that a user can submit. By
default, the maximum value is 5 . You can adjust
this value downward.
|
enableTextFeedback |
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).
|
threshold |
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 .
|
footerText |
The text that displays at the bottom of the feedback dialog. |
System.Feedback Component Transitions
return: "done"
transition.
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. |
system.userFeedbackRating
– Returns the user's rating.system.userFeedbackText
– WhenenableTextFeedback
is set totrue
, your skill can prompt for feedback when the ratings fall below thethreshold
value.system.userFeedbackText
returns the user's input (${system.userFeedbackText.value}
).
...
getUserFeedback:
component: "System.Feedback"
properties:
threshold: 2
maxRating: 5
enableTextFeedback: true
transitions:
actions:
above: "positiveFeedback"
below: "negativeFeedback"
cancel: "cancelFeedback"
positiveFeedback:
component: "System.Output"
properties:
text: "Thank you for your rating of ${system.userFeedbackRating.value}."
transitions:
return: "done"
negativeFeedback:
component: "System.Output"
properties:
text: "You gave us a score of ${system.userFeedbackRating.value} and entered ${system.userFeedbackText.value}. We appreciate your feedback."
transitions:
return: "done"
cancelFeedback:
component: "System.Output"
properties:
text: "Feedback canceled."
transitions:
return: "done"
...
System.Text
This component is deprecated, and there is no longer a template available for it. Instead you can use one of the many templates based on the Common Response component that are offered in the User Messaging section of the Add Component dialog.
The System.Text
component enables your bot to set a context or
user variable by asking the user to enter some text.
System.Text
state for the first time, it prompts the user to enter some text. When the user enters a value, the Dialog Engine returns to this state. The component processes the user response and if it can convert the user input to the variable type, it stores the value in the variable. The Dialog Engine moves on to another state when this variable has a value.
The Dialog Engine skips over the
System.Text
state of the variable already has a value.
Property | Description | Required? |
---|---|---|
prompt |
A text string that describes the input required from the user. You can dynamically add values to it using a value expression. For example: Hello ${profile.firstName}, how many pizzas do you want? |
Yes |
variable |
The name of the variable, which can be either a user variable or one of the variables declared in the context node.
|
Yes |
nlpResultVariable |
Sets the variable property with an entity value (when that entity value hasn’t already been set for the referenced variable). You can enable nlpResultVariable to return a value when you define it using a variable that holds the NLP results (such as iresult: "nlpresult" that’s used in our sample bots). By doing this, the nlpResultVariable property can still populate the value when it’s null if it finds a resolved entity that matches the one referenced by the variable. The dialog transitions to the next state when the nlpResultVariable sets the value. You can use this property in place of the System.SetVariable component.
|
No |
maxPrompts |
The number of times that component prompts the user for valid input. See Limiting the Number of User Prompts. | No |
translate |
Use this property to override the boolean value that you’ve set for the autotranslate context variable. If you haven’t set this variable, or if you set it to false , then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable is set to true , you can set this property to false to exclude this component from autotranslation. See Translation Services in Skills.
|
No |
See Transitions for Common Response Components for the predefined action types that you can use with this component.
How Do I Use the System.Text Component?
In this example, the type
variable holds the values expected by the PizzaType
entity, like cheese
, Veggie Lover
, and Hawaiian
. When this information is missing from the user input, the bot can still get it because its dialog flow transitions to the type
state, whose System.Text
component prompts them to explicitly state what they want. Keep in mind that even at this point, the user input still needs to resolve to the PizzaType
entity to transition to the next state.
main: true
name: "PizzaBot"
parameters:
age: 18
context:
variables:
size: "PizzaSize"
type: "PizzaType"
crust: "PizzaCrust"
iResult: "nlpresult"
...
type:
component: "System.Text"
properties:
prompt: "What Type of Pizza do you want?"
variable: "type"
transitions:
...
System.List
This component is deprecated, and there is no longer a template available for it. Instead you can use one of the many templates based on the Common Response component that are offered in the User Messaging section of the Add Component dialog.
The System.List
component is designed to output a list of options.
Depending on whether a variable value has been set (or even defined for this component),
the navigation from the component can be triggered by the user's choice, or by the value
set for the user or context variable.
Property | Description | Required? |
---|---|---|
options |
You can specify the options using
comma-separated text strings, Apache FreeMarker expressions, and as
a list of maps. The options Property and Action Lists both provide examples of the latter
approach.
|
Yes |
prompt |
The text string that prompts the user. | Yes |
variable |
The name of the variable whose value is populated by the user input. The Dialog Engine skips this state if the variable value has already been set and doesn’t output the list options for the user. | No |
nlpResultVariable |
Sets the variable property with an
entity value (when that entity value hasn’t already been set for the
referenced variable). You can enable
nlpResultVariable to return a value when you
define it with the variable that holds the NLP results (such as
iResult: "nlpresult" that’s used in our sample
skills). By doing this, the nlpResultVariable
property can still populate the value when it’s null if it finds a
resolved entity that matches the one referenced by the variable. The
dialog transitions to the next state when the
nlpResultVariable sets the value. You can use
this property in place of the System.SetVariable component.
Action Lists describes how you can use the
variable and nlpResultVariable
properties to change the list display behavior.
|
No—Use this property when the variable property names an entity-type variable. |
maxPrompts |
The number of times that component prompts the user for valid input. See Limiting the Number of User Prompts. | No |
translate |
Use this property to override the boolean value that
you’ve set for the autotranslate context variable.
If you haven’t set this variable, or if you set it to
false , then you can set this property to
true to enable autotranslation for this
component only. If you set the autotranslation
variable is set to true , you can set this property
to false to exclude this component from
autotranslation. See Translation Services in Skills.
|
No |
autoNumberPostbackActions |
When set to true , this option prefixes numbers to options. Even when you haven’t set this option to true , auto-numbering can be enforced on list items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true . Channel-specific auto-numbering can be applied to any skill that's registered to a digital assistant:${(system.channelType=='twilio')?then('true','false')} |
No |
footerText |
Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. | No |
Value Lists
You can use the System.List
component to return a value that satisfies a context variable that’s defined as a primitive (like greeting: "string"
in the dialog flow template) or as an entity, as shown in the following snippet. In this dialog flow, the options: "Thick,Thin,Stuffed,Pan"
definition returns a value that matches crust
variable. The options
property defined for size is a value expression (${size.type.enumValues}
) that returns the Large, Medium, Small, and Personal list values as options. See Apache FreeMarker Template Language Syntax.
nlpResultVariable
property’s
iResult
definition allows the component to set the entity values for the
variable
properties for the crust
and
size
states when these values haven’t been previously set. Like the
Text
component, the System.List
component doesn’t require
any transitions.
main: true
name: "PizzaBot"
...
context:
variables:
size: "PizzaSize"
crust: "PizzaCrust"
iResult: "nlpresult"
...
states:
...
crust:
component: "System.List"
properties:
options: "Thick,Thin,Stuffed,Pan"
prompt: "What crust do you want for your pizza?"
variable: "crust"
main: true
name: "PizzaBot"
...
context:
variables:
size: "PizzaSize"
crust: "PizzaCrust"
iResult: "nlpresult"
...
states:
...
crust:
component: "System.List"
properties:
options: "Thick,Thin,Stuffed,Pan"
prompt: "What crust do you want for your pizza?"
variable: "crust"
nlpResultVariable: "iresult"
transitions:
next: "size"
size:
component: "System.List"
properties:
options: "${size.type.enumValues}"
prompt: "What size Pizza do you want?"
variable: "size"
nlpResultVariable: "iresult"
transitions:
...
Users aren’t limited to the options displayed in the list. They can resolve the entity by entering a word that the entity recognizes, like a synonym. Instead of choosing from among the pizza size options in the list, for example, users can instead enter big, a synonym defined for the
PizzaSize
entity’s Large option. See Custom Entities.The options Property
options
property using any of the following:
-
A list of maps—While you can set the options property as a text string or value expression, you can also configure the
options
property as list of maps. Each one has alabel
property, avalue
property, and an optionalkeyword
property. You can localize your list options when you follow this approach because, as noted by the following example, you can reference a resource bundle. See Resource Bundles for Skills to find out more about using the dot notation. When users enter a value that matches one of the values specified in thekeyword
property, the bot reacts in the same way that it would if the user tapped the list option itself.askPizzaSize: component: "System.List" properties: prompt: What size do you want?" options: - value: "small" label: "${rb.pizza_size_small}" keyword: "1" - value: "medium" label: "${rb.pizza_size_medium}" keyword: "2" - value: "large" label: "${rb.pizza_size_large}" keyword: "3" variable: "pizzaSize"
-
A text string of comma-separated options, like
"small, medium, large"
in the following snippet. You can’t addlabel
andvalue
properties when you defineoptions
as a string.askPizzaSize: component: "System.List" properties: prompt: "What size do you want?" options: "small, medium, large" variable: "pizzaSize"
-
An Apache FreeMarker value expression that loops over either a list of strings, or a list of maps, where each map must contain both the
label
andvalue
properties and optionally, akeyword
property.askPizzaSize: component: "System.List" properties: prompt: "What size do you want?" options: "${pizzaSize.value.enumValues}" variable: "pizzaSize"
Action Lists
System.Switch
component for conditional navigation, you
can use action lists. The System.List
's optional variable
and nlpResultVariable
properties set the list display behavior and subsequent
transition based on user input.
- When you don't configure these properties, the transition action is based on the option
selected by the skill
user:
showMenu: component: "System.List" properties: prompt: "Hello, this is our menu today" options: - value: "pasta" label: "Pasta" - value: "pizza" label: "Pizza" transitions: actions: pasta: "orderPasta" pizza: "orderPizza"
- When you add the
variable
andnlpResultVariable
properties, the list display gets bypassed when the user's input is matched. In the following snippet, the list of options gets bypassed when thenlpResultVariable
, sets thesize
variable from user input like I want to order a large pizza. The transition appropriate to the value is then triggered.getPizzaSize: component: "System.List" properties: prompt: "What size of pizza" variable: "size" nlpResultVariable: "iResult" options: - label: "Small" value: "Small" - label: "Large" value: "Large" transitions: actions: Large: "Large" Small: "Small"
System.Output
System.Output
component to output a message that
doesn't require a user response, or doesn't require your skill to process the user's
response.
This component is deprecated, and there is no longer a template available for it. Instead you can use one of the many templates based on the
System.CommonResponse
that are offered in the User
Messaging section of the Add Component
dialog.
Property | Description | Required? |
---|---|---|
text |
A text string | Yes – This field requires a value. |
keepTurn |
A boolean value for relinquishing (false ) or
retaining the skill’s control of the dialog flow (true ). Use
keepTurn: true when you want to output an unbroken sequence of
skill messages wherein no interjections from the user are accepted.
|
No |
translate |
Use this property to override the boolean value that you’ve set
for the autotranslate context variable. If you haven’t set that
variable, or if you set it to false , then you can set this property
to true to enable autotranslation for this component only. If you
set the autotranslation variable to true , you can
set this property to false to exclude this component from
autotranslation. See Translation Services in Skills.
|
No |
How Do I Use the System.Output Component
System.Output
component requires the string definition
for the text
property. As illustrated in the following example of a
confirmation message, you can add value expressions to this
string.done:
component: "System.Output"
properties:
text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."
By
default, the Dialog Engine waits for user input after it outputs a statement from your skill.
If you override this behavior, add the optional keepTurn
property and set it
to true
to direct the Dialog Engine to the next state defined by the
transitions
property. When no transition as been defined, the Dialog Engine
moves to the next state in the sequence.
wait:
component: "System.Output"
properties:
text: "Please wait, we're reviewing your order"
keepTurn: true
transitions:
next: "ready"
waitmore:
component: "System.Output"
properties:
text: "Almost done..."
keepTurn: true
transitions:
next: "done"
done:
component: "System.Output"
properties:
text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."
transitions:
return: "done"
Defining Value Expressions for the System.Output Component
text
property.
For example, the following snippet uses different expressions for outputting the text for an
order confirmation (pizza size and
type).confirmation:
component: "System.Output"
properties:
text: "Your ${size.value} ${type.value} pizza is on its way."
transitions:
return: "done"
Each
expression must always return a value. If even one expression returns a null value, then the
skill outputs raw text for each expression in the string, leaving your users with ouput like
this: Your ${size.value} ${type.value} is on its way.
${size.value!\”piping\”} ${type.value!\”hot\”}
. The
double quotes indicate that the default value is a not a variable reference, but is instead
the constant value that the operator expects. For
example:text: "Your ${size.value!\"piping\"} ${type.value!\"hot\"} pizza is on its way."
Always escape the quotation marks (
\"...\"
) that enclose the default value when you use the
Freemarker operator. Your dialog flow’s OBotML syntax won’t be valid unless you use this
escape sequence each time that you define a default value operation, or set off output text
with double quotes. For example, the following System.Output
component
definition allows users to read the message as You said, “Cancel this
order.”confirmCancel:
component: "System.Output"
properties:
text: "You said, \"Cancel this order.\""
transitions:
return: "cancelOrder"
Translating the Output Text
System.Output
component’s
autotranslated text on a per-component basis using the translate
property. By
setting it to false
, as in the following snippet, the components outputs the
text as is, with no translation. By setting this property to true
, you can
enable autotranslation when the autoTranslate
variable is either set to
false
or not defined. See Translation Services in Skills.
Typically, you would not set the
autoTranslate
variable to true
if you’re translating
text with resource bundles. We do not recommend this
approach.
setAutoTranslate:
component: "System.SetVariable"
properties:
variable: "autoTranslate"
value: "true"
transitions:
...
...
pizzaType:
component: "System.Output"
properties:
text: "What type of pizza do you want?"
translate: false
transitions:
...