Component Templates
Here are descriptions of the templates that are provided for the various dialog flow components.
Send Message
This is a very simple component that is designed to display one or more messages to the user. It does not wait for or respond to user input.
The Send Message component has the following property:
Property | Description |
---|---|
Messages | Messages that are displayed to the user when the component is called. |
Ask Question
This component is designed to ask for user input and then store that input so that it can be used or processed by other components.
The Ask Question component has the following properties:
Name | Description |
---|---|
Question | Text that is displayed to the user. |
Variable | The variable that holds the user's answer to the question. |
This component can return the following actions:
Action | Description |
---|---|
cancel |
The user has reached the maximum number of attempts to provide a valid value. |
system.textReceived |
The user has entered text (as opposed to, for example, selecting an action button). |
Resolve Composite Bag
This component is a simplified version of the Resolve Entities component that you can use to resolve a composite bag entity.
To use this component, you need a composite bag entity and a skill variable for that composite bag.
The Resolve Composite Bag component has the following property:
Name | Description |
---|---|
Composite Bag Entity Variable | Text that is displayed to the user. |
This component can return the following actions:
Action | Description |
---|---|
cancel |
The user has reached the maximum number of attempts to provide a valid value. |
disambiguate |
The user input needs to be clarified to determine which entity value it matches, if any. |
match |
The user input matches a valid entity value. |
User Messaging Templates
The templates in the User Messaging category are designed for displaying messages and prompts and accepting user input.
With the exception of the Resolve Entity and User Feedback templates, all of these templates are based on the Common Response component and are tailored to specific purposes.
Common Response Component Templates
The vast majority of the templates in the User Messaging category are based on the Common Response component, which enables you to use component properties and metadata to build a specialized user interface that can include text, action buttons, images, and cards.
In many of the cases, such as the templates in the Display Multimedia Messages sub-category, the main differences are in the Metadata property for the Common Response component.
In other cases, such as in the Display Tables and Forms sub-category, the template consists of a Common Response component preceded by a Set Variable component.
In the Channel-Specific Features sub-category, there are examples of using extensions available for Slack and Microsoft Teams channels.
Properties for Common Response Component Templates
Except for the Resolve Entities and User Feedback components, the templates in the User Messaging category are based on the Common Response component. As such, they each use the properties in the following table (or a subset of them).
Name | Description |
---|---|
Metadata | The chat response created by this component is driven by
the message-specific ResponseItems metadata. See The Metadata Property in Common Response Components.
|
Process User Message |
Set this property to Set this property to |
Keep Turn |
A boolean value for relinquishing ( This property only applies when you set the Process User
Message property to |
Variable |
This variable holds the name of a variable that gets populated when a user responds by entering free text instead of tapping a button. This property is ignored when a user taps a button, because the button’s payload determines which variables values get set. If the variable property has already been set when the Dialog Engine enters this state, then the state is skipped. For composite bag entities, reference the composite bag entity variable. Users get prompted for the individual entity values in the bag. When all the entity values are set, the component transitions to the next state. |
Maximum Number of Prompts |
Before the component can populate the variable value that you’ve specified for the Variable property from the text entered by the user, it validates the value against the variable type. This can be entity-type validation, or in the case of a primitive type, it’s a value that can be coerced to the primitive type. When the component can’t validate the value, the Dialog
Engine sends the message text and options again. (You can modify
this message to reflect the validation failure.) To avoid an endless
loop resulting from the user’s continued inability to enter a valid
value, use this property to set a limit on the number of attempts
given to the user. When the user exceeds this allotment, the
component transitions to the As described in Create a Composite Bag Entity, individual entities in a composite bag entity can override this setting when the Maximum User Input Attempts option is set. |
Multi-Value | Indicates whether an entity variable can store an array of matching values or just a single matching value. |
Cancel Policy | Determines the timing
of the cancel transition:
maxPromptsReached handler. |
Use Full Entity Matches | When set to True , custom entity values
are stored as JSON objects (similar to built-in entity values). This
enables you to create expressions to access properties such as
value , primaryLanguageValue , and
originalString , which are particularly important
for skills that are currently or eventually might become
multi-lingual.
|
Transitions for Common Response Components
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. |
system.nonSequitur.onResume |
Use this transition action to provide alternate navigation for a state when the conversation returns to that state after having handled a non sequitur. This can be used to refresh the component state, bypass the state, or to re-query information displayed by the state. In particular, this transition is useful for cases when the state depends on fresh data (in other words, it needs to be re-queried whenever a user returns to it). |
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
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 |
Resolve Entity
Property | Description |
---|---|
Variable | Refers to the composite bag entity dialog flow variable that’s populated by this component. If all child entities of the composite entity variable already have a value, then the dialog flow transitions to the next state without sending the user a message. |
Maximum Number of Prompts | Specifies the number of attempts allotted to the user to enter a valid value that matches the child entity type. If the maximum number of attempts is exceeded for the first child entity, this property resets to 0 and the bot outputs the prompt for the next child entity. As described in Create a Composite Bag Entity, individual entities in the composite bag can override this setting when the Maximum User Input Attempts option is set. |
Multi-Value | Indicates whether an entity variable can store an array of matching values or just a single matching value. |
Use Full Entity Matches | When set to
True , custom entity values are stored as JSON
objects (similar to built-in entity values). This enables you to create
expressions to access properties such as value ,
primaryLanguageValue , and
originalString , which are particularly important
for skills that are currently or eventually might become
multi-lingual.
|
Prompt | The text used to prompt the user for built-in entities. |
Disambiguation Prompt | The text used to prompt the user for disambiguation when the prior user input matched multiple values of the built-in entity. This property is ignored if the Multi-Value property resolves to true. |
Header Text | A message that displays
before the component prompts the user for the next item in the bag. You
can use this header to provide feedback on the previous entities in the
bag that have been matched (or updated). For
example:
|
Footer Text | Enhances the output on text-only channels. For example, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. |
Cancel Policy | Determines the timing
of the cancel transition:
maxPromptsReached handler. |
User Feedback
The User Feedback component enables you to collect feedback data for Insights by presenting users with a rating scale after they've completed a transactional flow. Users can't change their rating because the User Feedback component does not allow out-of-order input. If you're using the 21.10 SDK or later, this component outputs a horizontal star rating system.
While you can change the behavior of this component using the component properties, you can change its look and feel when you use the SDK (version 21.10 or later). For example, you can replace the default star icons used for the feedback buttons with another icon.
Name | Description |
---|---|
Max Rating | The maximum rating that a user can submit. By default,
the maximum value is 5 . You can adjust this value
downward.
|
Threshold | A boolean, which if set to true ,
enables the user to submit text feedback if the rating is less than, or
equal to, the threshold value. By default, this
property is set to false (no feedback enabled).
|
Enable Text Feedback | The value for evaluating the transition between the
above and below actions. By
default, the threshold between positive and negative feedback is set as
2 for the default maxRating value,
which is 5 .
|
Footer Text | The text that displays at the bottom of the feedback dialog. |
This component can return the following actions:
Action | Description |
---|---|
above |
Set when the user input is a valid value that's above the Threshold value. |
below |
Set when user input is a valid value that's equal to, or below, the Threshold value. ). |
cancel |
Set when users decline the rating by clicking Skip. |
You can use the following system variables for the messages output by the transition states:
system.userFeedbackRating
– Returns the user's rating.system.userFeedbackText
– 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}
).
The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:
Resource Bundle Key | Description |
---|---|
Feedback - feedbackPrompt | The prompt shown to the user to select the rating for the conversation. |
Feedback - invalidValuePrompt | The prompt shown to the user to select the rating for the conversation after the user has input an invalid value for the rating. |
Feedback - ratingButtonLabels | Comma-separated list of labels displayed on the rating buttons. |
Feedback - skipLabel | The label of the button for skipping feedback. |
Feedback - textFeedbackPrompt | Prompt shown to the user asking them to provide text feedback when they give a rating below the Threshold property value. |
Feedback - thankYouPrompt | The prompt shown to the user when the transition selected by the user is not defined in dialog flow. |
Variables Templates
Copy Variables
Copies values from one variable to another.
Property | Description |
---|---|
Source Variables | The name of the variables that will have their value copied. |
Destination Variables | The variables that the values from the source variables will be copied to. |
The definitions of these properties don’t have to mirror one another. While you can define both destination and source variables as lists of variables, you can also define the source variable with a single variable and the destination as a list. If you set an additional destination variable, it inherits the variable value of the proceeding source value specified.
Reset Variables
This component resets the values of specified variables to null.
Property | Description |
---|---|
Variables to Reset | The variables that need to be reset. |
Set Variable
The Set Variable component sets the value of a pre-defined variable.
Property | Description |
---|---|
Variable | The name of the variable. |
Value | The target value, which you can define as a literal or as a FreeMarker expression that references another variable. The value must match type of the declared variable. |
Set Custom Metrics
Attribute | Description |
---|---|
name |
The name of the dimension (in 50 characters or less) as it appears in the Custom Metrics report. Use only letters, numbers, and spaces. Do not use special characters. |
value |
You can define the dimension value as either a
FreeMarker expression or a text string.
|
Language Templates
Detect Language
The Detect Language component uses the translation service to detect the user’s language from the user input.
Note:
This component is only available if you have created your skill to use a translation service (i.e., not in natively-supported language mode).This component sets a variable named profile.languageTag
with the
locale string. You can set variables with the current language when you use this
variable in a value expression (${profile.languageTag}
).
Note:
Theprofile.languageTag
takes precedence over the
profile.locale
variable that’s set by the messenger client.
Property | Description |
---|---|
Existing Profile Language Tag | When set to True, the skill uses the language that is detected by the digital assistant immediately. (Otherwise, the skill might provide a message or prompt in English before the language is (re-)detected.) This property only applies to skills that are in digital assistants that use a translation service. |
Translate Input
This component sends specified text to the skill's translation service and then stores the English translation. It relies on the skill being configured with a translation service, which recognizes the language from the user's input and translates it into in English. This component doesn't work with skills that use the Natively Supported language mode.
Use this component when you need to process the raw input text before having it translated. For example, you might want to remove some personal data from the user input before sending it to the translation service.
Because this component leverages the translation service, which already detects the user’s language, this component doesn’t need to follow states that detect or set the language.
Property | Description |
---|---|
Expression | FreeMarker expression that specifies the text values to be translated into English. |
Variable | The variable that holds the English translation of the text. If this value isn't set, the component uses the user's previous input. |
Translate Output
The Translate Output component allows you to translate specified text to the
user’s language. The component takes the value defined for the
Expression property. It uses the skill's translation service
to translate the text into the language detected by the Detect Language component or by
the profile.locale
variable and then stores it in the variable
specified by the Variable property.
This component doesn't work with skills that use the Natively Supported language mode.
Properties | Description |
---|---|
Expression | A FreeMarker expression that references a variable whose value needs to be translated. |
Variable | Variable that holds the translated text. |
Match Entity
The Match Entity component calls the Intent Engine to extract entity information from the text held by the Source Variable property. If a match exists for the variable's entity type, the variable specified by the Variable property is set with this entity value.
Property | Description |
---|---|
Source Variable | The variable that holds the input value. |
Variable | The name of the variable that is set with the value of
the extracted entity. The value of this variable can be used in a
subsequent Set Variable component to extract a specific entity using a
FreeMarker expression. For example, to extract an EMAIL
entity value:
${userInputEntities.value.entityMatches['EMAIL'][0]} |
This component also has two predefined transitions: match
and nomatch
.
Transition | Description |
---|---|
match |
Directs the Dialog Engine to go a state when the entities match. |
nomatch |
Defines the Dialog Engine to go to a state when the entities don’t match. |
Note:
The Match Entity component resolves only a single value.Security Templates
OAuth Account Link
Use this component to obtain the authorization code for services that are secured by the authorization code grant flow, such as LinkedIn, Twitter, Google, or Microsoft. The skill’s custom components can exchange the authorization code for an access token, which they then use to invoke the end service.
The component first directs the user to the identity provider’s login page. After a successful login, the component returns the authorization code in a variable, which you use to pass the authorization code to the custom component. The custom component API must exchange the authorization code, client ID, and client secret for an OAuth user access token.
For each state that requires authorization before it can be invoked, you set
its Requires Authorization setting to True
. See
User Authorization for the steps to set this up.
Property | Description |
---|---|
Variable | Specifies the dialog flow variable to store the authorization code in. You can declare it as a string or another supported variable type. It can also be a user variable. |
Authorize URL | The login URL. The authorizeURL Property describes how to configure this URL. |
Footer Text | Enhances the login dialog by adding text beneath the login and cancel options. You can use FreeMarker expressions to conditionalize the footer text for text-only channels. |
Show Cancel Label | (Optional) Enables you to specify whether or not to
display the Cancel button. By default, this
property is set to True , meaning that the
Cancel button is displayed. In some cases,
such as for SMS channels, you might not want to display this button. You
can configure such behavior with an expression
like:
|
This component can return the following actions:
Action | Description |
---|---|
fail |
The user clicked the cancel button. |
pass |
The authorization code was retrieved successfully. |
textReceived |
The user entered text instead of clicking the cancel button or authenticating successfully. |
The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:
Resource Bundle Key | Description |
---|---|
OAuthAccountLink - cancelLabel | Use to override the label for the button that the users
can click to leave state without invoking the authentication dialog. The
default label is Cancel .
|
OAuthAccountLink - linkLabel | Use to override the label for the button that the users
can click to invoke the authentication dialog. The default label is
Log In .
|
OAuthAccountLink - prompt | The string to use to prompt the user to sign in. |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Tip:
You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.When the dialog engine encounters this component, the skill bot prompts the user with two links — Login and Cancel.
There are several ways to transition from this component:
-
The user clicks the cancel button and the component transitions to the state that's named by the
fail
action. -
The user doesn't click any buttons but enters text instead. The component transitions to the state that's named by the
textReceived
action. -
The user clicks the login link and the channel renders the identity provider’s login page or its authentication dialog as a webview, as shown in the example below. After successful authorization, the component transitions to the state that's named by the
pass
action (or to the next state if there isn't apass
action), which would typically call a custom component that exchanges the authorization code for an access token.
If the test window doesn’t render the webview, cut and paste the link text into your browser.
OAuth 2.0 Account Link
Use this component to obtain an OAuth2 user access token (grant type Authorization Code) for resources that are secured by Oracle Identity Cloud Service (IDCS), Oracle Access Manager (OAM), Microsoft identity platform, or Google OAuth 2.0 authorization. This component completes all the steps for the 3-legged OAuth2 flow and returns the OAuth2 access token.
For each state that requires authorization before it can be invoked, you set
its Requires Authorization setting to True
. See
User Authorization for the steps to set this up.
If you need to obtain an access token of grant type Client Credentials to access client resources, see OAuth 2.0 Client.
Before you can use this component in a skill, you must do the following tasks:
- If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
- Add an authentication service for the identity provider, as described in Authentication Services.
Some identity providers issue refresh tokens. When you use this component, Digital Assistant stores the refresh token for the retention period that's specified for the authentication service. The Digital Assistant backend can use the refresh token, if available, to get a new access token without the user having to sign in again.
Property | Description |
---|---|
Authentication Service | The name of the authorization-code service that you created in the Authentication Services UI for the OAuth2 identity provider. |
Authenticated User Variable Name | Specifies the variable in which to store the authenticated user name (the name that’s known by the identity provider). If the variable is user-scoped, then it can be shared across skills. |
Access Token Variable Name | Specifies the variable to store the access token in. If the variable is user-scoped, then it can be shared across skills. |
Multi-Scope Access Token Variable Name | Field reserved for future multi-scope access token support. |
Footer Text | Enhances the login dialog by adding text beneath the login and cancel options. You can use FreeMarker expressions to conditionalize the footer text for text-only channels. |
Show Cancel Option | (Optional) Enables you to specify whether or not to
display the Cancel button. By default, this
option is set to True , meaning that the
Cancel button is displayed. In some cases,
such as for SMS channels, you might not want to display this button. You
can configure such behavior with an expression
like:
|
Requires Association Consent | Set this to True if the skill uses the Notify User component and the event channel is either Twilio or Slack to persist user identity across sessions and channels. This property enables the linking of supported channel accounts to the OAuth authenticated IDCS account using a unified user identifier. |
Update User Profile | If the identity provider is IDCS, and you want to store
the user's profile from IDCS for the duration of the session, then set
this property to True . When a user is challenged for
authentication, if this property is set to true , the
component will try to fetch the user profile data from the identity
provider and set the results in the
userProfile.<authorization service> map. See
Store IDCS User Profile for the Duration of the Session.
|
Enable Single Sign-On | (Applies to Microsoft Teams channels only) If you have
set up Microsoft Teams single sign on, setting this to
True will enable users that have already signed in
to Teams to not have to sign in to the skill separately.
|
Redirect URL | The redirect URL that receives the authorization code. |
Note:
The Associate With Unified User property is no longer available. If you want to enable the linking of supported channel to a unified user identity, you can do so for the whole instance. See Enable Channel Account Linking.This component can return the following actions:
Action | Description |
---|---|
fail |
The user clicked the cancel button. |
pass |
The access token was retrieved successfully. |
textReceived |
The user entered text instead of clicking the cancel button or authenticating successfully. |
The component's standard display text is stored in resource bundle entries. These bundle entries have default text, but you can customize them. Here are the entries for this component:
Resource Bundle Key | Description |
---|---|
OAuth2AccountLink - cancelLabel | Use to override the label for the button that the users
can click to leave a state without invoking the authentication dialog.
The default label is Cancel .
|
OAuth2AccountLink - linkLabel | Use to override the label for the button that the users
can click to invoke the authentication dialog. The default label is
Log In .
|
OAuthAccount2Link - prompt | The string to use to prompt the user to sign in. |
OAuthAccount2Link - consentNeverFinalConfirmationNoLabel | The label for the "No" button that appears after the
prompt to confirm that the user wants to opt out of having their channel
account permanently associated with a unified identity. The default is
Cancel .
|
OAuthAccount2Link - consentNeverFinalConfirmationPrompt | The prompt that asks users to confirm that they want to opt out of having their channel account associated with a unified identity. |
OAuthAccount2Link - consentNeverFinalConfirmationYesLabe | The label for the "Yes" button that appears after the
prompt to confirm that the user wants to opt out of having their account
permanently associated with a unified identity. The default is
Confirm .
|
OAuthAccount2Link - consentNeverFinalPrompt | The message that confirms to users that they have permanently opted out of having their account associated with a unified identity. |
OAuthAccount2Link - consentNeverLabel | The label for the "Never" button that appears after the
prompt that asks if the user wants to associate their channel account
data to a unified identity. The default is Never link this
account .
|
OAuthAccount2Link - consentNotifyPrompt | The message that informs users that their channel account will be associated with the authenticated user identity. |
OAuthAccount2Link - consentNotNowFinalPrompt | The message that confirms to users that they have temporarily declined to associate their channel account data to a unified identity. |
OAuthAccount2Link - consentNotNowLabel | The label for the "Not Now" button that appears after
the prompt that asks if the user wants to associate their channel
account data to a unified identity. The default value is Not at
this time .
|
OAuthAccount2Link - consentPrompt | The prompt that asks users to choose if they consent to associating their channel account with the authenticated user identity. |
OAuthAccount2Link - consentYesLabel | The label for the "Yes" button that appears after the prompt that asks if the user wants to associate their channel account data to a unified identity. |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Tip:
You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.When the dialog engine encounters the component, the skill bot prompts the
user with two links: Get an Access Token and Cancel (you can use
linkLabel
and cancelLabel
to change the link
text).
![Description of oauth2accountlinksignin1.png follows Description of oauth2accountlinksignin1.png follows](img/oauth2accountlinksignin1.png)
Description of the illustration oauth2accountlinksignin1.png
If the user clicks the link to get an access token, it displays the identity
provider’s login page or authentication dialog as specified by the authentication
service. After successful login, it obtains the access token, sets the values for the
variables identified by accessTokenVariableName
and
authenticatedUserVariableName
, and then flows to the state that's
named by the pass
action (or to the next state if there isn't a
pass
action). If the user cancels, the postback action is set to
fail
. If the user enters text, it returns the
textReceived
action.
![Description of oauth2accountlinksignin2.png follows Description of oauth2accountlinksignin2.png follows](img/oauth2accountlinksignin2.png)
Description of the illustration oauth2accountlinksignin2.png
As mentioned earlier, you can set requiresAuthorization
for
a state to ensure that the user is authorized before invoking the state's component. If
the user hasn't authorized yet, the dialog invokes the Authorize User event.
OAuth 2.0 Client
Use this component to obtain an OAuth2 access token of grant type Client Credentials. That is, you use it to get an access token that's based on the client's credentials, and not the user's name and password. You can use this component to get a token that enables access to client resources that are protected by Oracle Identity Cloud Service or Oracle Access Manager (OAM).
If you need to access resources on behalf of a user, see OAuth 2.0 Account Link and OAuth Account Link.
Before you can use this component in a skill, you must do the following tasks:
- If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
- Add a client-credentials authentication service for the identity provider, as described in Authentication Services.
Property | Description |
---|---|
Authentication Service | The name of the client-credentials service that you created in the Authentication Services UI for the OAuth2 identity provider. |
Access Token Variable Name | Specifies the variable to store the access token in. You
can declare it as a string or another supported variable type. It also
can be a user-scoped variable. For example:
user.accessToken .
|
Multi-Scope Access Token Variable Name | Field reserved for future multi-scope access token support. |
This component doesn't have any actions. To handle system problems that might occur, add a next transition that goes to a state that can handle such errors.
Reset OAuth 2.0 tokens
Use this component to revoke all the logged-in user's refresh and user access tokens from the identity provider that the authentication service represents. It also removes the refresh tokens from the database. To use this component, you must provide the identity provider's revoke refresh token URL in the Authentication Service UI.
The skill must include a state that uses the OAuth 2.0 Account Link component for the same authentication service, and it must be invoked before the state that uses this component.
Property | Description |
---|---|
Authentication Service | The name of the service that you created in the Authentication Service UI for the OAuth2 identity provider. This service must have a valid revoke refresh token URL. |
This component can return the following action:
Action | Description |
---|---|
noRefreshTokenFound |
The authentication service doesn't have any refresh tokens for the user. |
Flow Control Templates
Switch
Use this component to switch states based on a variable value.
This component determines an execution path by resolving a variable or expression and then triggering a corresponding transition action that is mapped to a state in the flow.
You define and map the transition actions on the Transitions tab of the property inspector.
Property | Description |
---|---|
Variable | A variable, the value of which is used to determine which transition action to trigger. |
Expression | A FreeMarker expression used to determine which
transition action to trigger. For example, the expression
${((user.lastOrderNumber)?has_content)} could be
used to trigger the True transition action if the
user.lastOrderNumber variable has a value or
trigger the False action if the variable has a null
value.
|
Invoke Flow
With this component, you call a child flow from the current flow, optionally passing in input parameters. When the child flow completes, it returns an action and optional output parameters to its parent flow.
The transition actions that can be set depend on the actions that are set in the child flow's End Flow component.
Property | Description |
---|---|
Flow | The name of the flow to be invoked. |
Input Parameters | Parameters that are passed to the invoked flow. The values can include Freemarker expressions. |
Output Parameters | Parameters that can be returned from the invoked flow when it completes. The Value of the parameter should be the name of a variable in the current flow that is used to store the value of the parameter when it is returned from the invoked flow. |
Invoke Skill
With this component, you call a different skill's flow, optionally passing in input parameters. When the called flow completes, it returns an action and optional output parameters to the calling flow.
Before you use this component, there must a public flow available in the skill you are calling. See Invoke Another Skill from a Flow.
Property | Description |
---|---|
Skill Name | The name of the skill to be invoked. Only skills that have one or more public flows are shown. |
Skill Version | (This property appears once you have selected a value for Skill Name.) The version of the skill to use. If the target skill is in the same digital assistant as the current skill, this field will be disregarded and the version of the skill in the digital assistant will be used. |
Flow Name | (This property appears once you have selected a value for Skill Name.) The name of the flow to be invoked from the skill. Only skills that have been marked as public in the target skill are shown. |
Input Parameters | (This property appears once you have selected a value for Flow Name.) Parameters that are passed to the invoked flow. The values can include Freemarker expressions. |
Output Parameters | (This property appears once you have selected a value for Flow Name.) Parameters that can be returned from the invoked flow when it completes. The Value of the parameter should be the name of a variable in the current flow that is used to store the value of the parameter when it is returned from the invoked flow. |
Use Mock | Set to True if you need to temporarily
use mock data for the output parameters. This enables you to continue
developing and testing the flow if the target flow isn't yet
available.
|
Mock Output Parameters | If you need to temporarily use mock output parameters
while developing the flow, enter each parameter on a separate line in
the form:
|
End Flow
This component is used to explicitly end a flow.
When this state is reached, all of the flow's variables are cleared and control is returned to the parent flow (or, if there isn't a parent flow, the Main Flow).
You don't need an End Flow state for a flow if you don't need to return parameters or actions from the flow to a parent flow or the Main Flow.
Property | Description |
---|---|
Action | The action returned to the calling flow, which can be used for setting transitions in the Invoke Flow component. |
Action Values | Should be set when the Action property contains a Freemarker expression and must contain a list of possible values of the resolved Freemarker expression. |
Keep Turn | When true, the dialog engine
continues to execute the next state in the calling
flow based on the transitions defined in the
Invoke Flow component. This property is IGNORED
when:
|
Output Parameters | Parameters that can be returned to a parent flow when the current flow is completed. |
Service Integration Templates
Agent Communication Template
This template consists of the Agent Initiation and Agent Conversation components. You use these components together to transfer a skill's conversation to an Oracle B2C Service agent.
- The Agent Initiation component initiates the handshake with the agent-integration channel that's specified by the component's Agent Integration Channel property.
- The Agent Conversation component manages the interchange between the skill and live agent.
This template is for conversations that originate in the skill. Do not use this template for conversations that originate in Oracle B2C Service chat, as described in The Digital Assistant as Agent Framework in Action.
Agent Initiation
Here are the Agent Initiation component properties:
Property | Description | |
---|---|---|
Agent Integration Channel | Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the Agent Integration Channel property defined for the Agent Conversation component must all match. | |
Agent Actions | A
list of actions that the agent can trigger to terminate the chat and
move the flow to the state defined for the transition action. In the
customer service representative's console, these actions display as
slash commands when the agent conversation is initiated, as shown in
this
example: On
the Transitions tab of the Agent Conversation
component, you need to manually enter these actions and map them to the
appropriate states.
|
|
Subject | The subject line that
displays in the agent's console after the hand off to the agent
platform. By default, this is the last customer message stored in the
system.nlpResult variable (which you can access
with the expression
${skill.system.nlpresult.value.query} ), but you can
also define this using a variable that you set earlier in the flow. For
example, you can define a string type variable whose
value gets set prior to the Agent Initiation component:
|
|
Chat Response Variable | Names
the map variable that holds the agent response information. After the
Agent Initiation component connects successfully, the map contains the
following
properties:
|
|
Custom Properties | A map that holds the incident ID,
interface, contact, or custom fields (or a combination thereof) to pass
to the service. To reference a map variable, use a value expression like
this: ${mapVariableName.value} . See Pass Customer Information to a Live Chat.
|
|
Queue ID | The ID of the queue
that the component must use to determine whether the specified
Allow Transfer If condition is met. This must
be the ID of the queue that the Oracle B2C
Service chat rules will route that conversation to.
This property is ignored if the Allow Transfer If property isn't defined. |
|
Allow Transfer If | Specifies the
conditions under which the skill should transfer the chat session. The
component uses the Queue ID value to identify the
queue from which to obtain the statistics. You should verify that the
chat rules will actually transfer the conversation to the identified
queue, and not some other queue.
If the specified condition is not met, the
component returns the When you include this property, you must also include the Queue ID property. |
|
Transcript Date/Time Format | The format for the date
and time in the conversation transcript messages that are forwarded to
the agent. Refer to the DateTimeFormatter Java class
for valid patterns. Example: dd/MM/yyyy HH:mm . Defaults
to yyyy-mmm-ddThh:mm:ssZ .
|
|
Transcript Time Zone | The Internet Assigned Numbers Authority (IANA) name of the time zone to use to format the conversation transcript using Transcript Date/Time Format property. If you don't define the Transcript Date/Time Format property, this property is ignored. |
Transition Actions for Agent Initiation
The Agent Integration component returns the accepted
,
rejected
, and error
actions. These actions can
each point to a different state, with the accepted
action typically
naming the state for the Agent Conversation component. You can
set these transitions on the Transitions tab of the component's
property inspector.
You can map the transitions for these actions on the Transitions tab of the component's property inspector.
Here are the descriptions of the actions:
Transition Action | Description |
---|---|
accepted |
The handshake completed successfully and the state can transition to the state with the Agent Conversation component. |
error |
There's a problem establishing a connection with Oracle B2C Service. For example, the password in the Agent Integration channel is no longer valid, or there's a problem with the Service Cloud server. |
rejected |
Oracle B2C
Service has rejected the connection request. Some of the reasons for
rejecting a connection request are:
Note that if you don't set the Allow
Transfer If and Queue ID
properties, the |
Resource Bundle Entries for Agent Initiation
The Agent Integration component uses the following properties, which are stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_AgentInitiation_agentActionsMessage |
If
any actions are specified in the Agent Actions
property, the agent console displays this message before the list of
actions. The default is:
|
|
systemComponent_AgentInitiation_errorMessage |
The message to display when
there's a problem establishing a connection with Oracle B2C
Service. For example, the password in the Agent Integration channel is no
longer valid, or there's a problem with the Service Cloud server. The
default is:
|
|
systemComponent_AgentInitiation_rejectedMessage |
The message that displays if the
AgentInitiation handshake was rejected, such as if
it's outside of the configured operating hours. The default is:
|
|
systemComponent_AgentInitiation_resumedMessage |
The message that
displays when the customer's chat with the customer service
representative resumes. The default is:
|
|
systemComponent_AgentInitiation_waitingMessage |
The message that
displays while customers wait to connect to an agent. The default is:
|
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Agent Conversation
Here are the Agent Conversation component properties:
Property | Description |
---|---|
Agent Integration Channel | Names the Agent Integration channel. This value, the name of the Agent Integration channel, and the Agent Integration Channel property defined for the Agent Integration component must all match. |
B2C Wait Message Override | Text to override the B2C wait message that provides an estimate of the time a user will have to wait to speak to an agent. |
Transition Actions for Agent Conversation
The Agent Conversation component can trigger the following actions:
- The built-in
expired
,agentLeft
,error
, andwaitExpired
actions. - Any action from the Agent Initiation component's Agent Actions property.
You need to include a
next
transition as well, because a customer might enter one of the
exit keywords (defined in the
systemComponent_AgentConversation_exitKeywords
resource bundle
entry) to leave the chat before any of these actions can get triggered.
You can map the transitions for the actions on the Transitions tab of the component's property inspector.
Note:
The actions from the Agent Initiation component's Agent Actions property do not appear in the dropdown list for actions when adding them on the component's Transitions tab, so you need to enter them manually.Here are the descriptions of the built-in transition actions:
Action | Description |
---|---|
agentLeft |
The agent terminated the session without using a slash
action (for example, /Order). Alternatively, the session ended because
there was no activity within the time specified by the Oracle B2C
Service
CS_IDLE_TIMEOUT configuration and that configuration is
less than the Session Expiration setting for the
agent-integration channel. See the expired action for
more information.
Note that this action is not returned
when the user leaves the conversation by entering an exit keyword.
In that case, the flow transitions to the state that's named by the
|
error |
There is a problem connecting to the live agent service. |
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.
|
Resource Bundle Entries for Agent Conversation
The Agent Conversation component uses the following resource bundle entries:
Resource Bundle Key | Description |
---|---|
systemComponent_AgentConversation_conclusionMessage |
An automated message sent to the customer when either the
user enters an exit keyword, the agentLeft action is
triggered, or the agent terminates the conversation without sending one
of the Agent Actions. The default is:
|
systemComponent_AgentConversation_errorMessage |
The message that the chat displays if there is a problem
with the connection to Oracle B2C
Service. The default is:
|
systemComponent_AgentConversation_exitKeywords |
A comma-delimited list of typical exit words used by a
customer to end the conversation with the live agent. The default is:
|
systemComponent_AgentConversation_expiryMessage |
The message that displays when the
expired action is triggered. The default message
is:
Note that the
In addition, this message isn't output when the
conversation concludes because the Service Cloud
|
systemComponent_AgentConversation_userLeftMessage |
The message shown when the user has exited the chat. The
default message is:
|
systemComponent_AgentConversation_waitExpiryMessage |
The message that's shown to the user when the chat
expires while waiting for an agent. The default is:
|
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Agent Transfer
You use the Agent transfer component in DA-as-agent digital assistants to transfer the conversation back to the chat service. The conversation will be routed to a live agent per the chat rules that have been configured in the chat service.
This component is for conversations that originate in a service chat, as described in The Digital Assistant as Agent Framework in Action. For conversations that originate in the skill, use the Agent Communication template instead.
Property | Description | |
---|---|---|
Maximum Wait Time (Seconds) | The maximum number of
estimated wait seconds that are allowed. When the chat
service receives the transfer request, it responds with the estimated
wait time. If this value exceeds Maximum Wait Time
(Seconds), then the rejected action
occurs. This property defaults to -1 , which means that
there's no maximum wait time. When set to -1 , the
digital assistant transfers the user to a human agent regardless of what
the estimated wait time is.
Note that the
|
|
Maximum Engagements In Queue | The maximum number
allowed for engagements waiting in the destination queue. When the chat
request is sent, the chat service responds with the current number of
engagements waiting in the queue. If this value exceeds
Maximum Engagements In Queue, then the
rejected action occurs. Defaults to
-1 , which means that there's no engagement limit.
Note that for B2B Chat, the response is always 0, so this property is of
no value for B2B.
|
|
Agent Availability StatusVariable | The name of the
variable of type map to use to store the agent availability status
information. No information is stored if the property is not specified.
To reference a map variable, use a value expression like this:
${<mapVariableName>.value.<key>} . For
example, agentStatus.value.expectedWaitMinutes .
To learn about the values returned in this variable, see Agent Transfer Condition. |
|
Allow Transfer If | Specifies the
conditions under which the skill should transfer the chat session.
If the specified conditions aren't met, then the
|
|
Custom Properties | A map that holds information to pass to the service. |
Transition Actions for Agent Transfer
The Agent Transfer component has some built-in transaction actions that it can return.
You can map the transitions for these actions on the Transitions tab of the component's property inspector.
Action | Description |
---|---|
accepted |
The accepted transition is set when the
chat is successfully transferred to a queue.
Note that after a chat request is accepted, the flow must end with an End Flow state. |
rejected |
The rejected transition is set when one
of the following occurs:
|
error |
The error transition is set when
there's a system error that prevents the transfer to a human
agent.
|
Resource Bundle Entries for Agent Transfer
The Agent Transfer component also uses the following properties, which are stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_AgentTransfer_acceptedMessage |
The message that's
shown to the users whenever a human agent accepts the chat request. The
default is:
|
|
systemComponent_AgentTransfer_errorMessage |
The message that's
shown to the user when a system error occurs while transferring the chat
session to an agent. The default is:
You can set the property to a blank or empty string to suppress message output. |
|
systemComponent_AgentTransfer_rejectedMessage |
The message that's
shown to the users whenever one of the following occurs:
The default message is: You can set the property to a blank or empty string to suppress message output. |
|
systemComponent_AgentTransfer_waitingMessage |
The message that's
shown to users when they're transferred to a queue. The default message
is:
You can set the property to a blank or empty string to suppress message output. |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Agent Transfer Condition
You can use the Agent Transfer Condition component in DA-as-agent digital assistants to determine whether agents are available and, if so, the expected wait time.
You use the component's properties to specify the transfer conditions, and it returns an action that indicates whether the conditions were met. In addition, it sets the values of the named map variable.
Property | Description | |
---|---|---|
Custom Properties | A map that holds information to pass to the service. See Pass Information to the Service. | |
Maximum Wait Time (Seconds) | The maximum number of
estimated wait seconds that are allowed. When the chat
service receives the request, it responds with the estimated wait time.
If this value exceeds Maximum Wait Time
(Seconds), then the conditionsNotMet action
occurs. This property defaults to -1 , which means that
there's no maximum wait time.
Note that the
|
|
Maximum Engagements in Queue | The maximum number allowed for engagements waiting in the destination queue. When the request is sent, the chat service responds with the current number of engagements waiting in the queue. If this value exceeds maxEngagementsInQueue , then the conditionsNotMet action occurs. Defaults to -1 , which means that there's no engagement limit.
|
|
Agent Transfer If | Specifies the base set
of conditions that must be met.
If the specified conditions aren't met, then the
|
|
Agent Availability Status Variable | The name of the
variable of type map to use to store the agent
availability status information. No information is stored if the
property is not specified. To reference a map variable, use a value
expression like this:
${<mapVariableName>.value.<key>} . For
example, agentStatus.value.expectedWaitMinutes .
|
Here is the structure of the value of Agent Availability Status Variable and the information stored in it:
queueId (integer, optional): The engagement queue ID,
expectedTotalWaitSeconds (integer, optional): Expected wait time in the queue in seconds
( -1 if there's inadequate information, zero or greater otherwise ).,
expectedWaitSeconds (integer, optional): The number representing the "ss" segment of the expected wait time of format mm:ss
( -1 if there's inadequate information, zero or greater otherwise ).,
expectedWaitMinutes (integer, optional): The number representing the "mm" segment of the expected wait time of format mm:ss
( -1 if there's inadequate information, zero or greater otherwise ).,
availableAgentSessions (integer, optional): Total number of sessions available across all agents.,
totalAvailableAgents (integer, optional): Total number of agents whose status is available.,
totalUnavailableAgents (integer, optional): Total number of agents whose status is unavailable.,
totalAgentsRequestingNewEngagement (integer, optional): Total number of agents who are available and have capacity.
outsideOperatingHours (boolean, optional): True if outside operating hours. False if inside operating hours.,
engagementsInQueue (integer, optional): The number of engagements currently in the queue.
sessionId (string, optional): The session ID.,
clientId (integer, optional): The client ID.
Tip:
Here's a suggested resource bundle definition that you can use to display the expected wait time:This might take {minutes, plural,
=-1 {}
=0 {}
=1 {1 minute and }
other {# minutes and }
}{seconds, plural,
=-1 {a while}
=0 {{minutes, plural,
=0 {a short wait time}
other {0 seconds}
}}
=1 {1 second}
other {# seconds}
} to connect. Are you willing to wait?
Transition Actions for Agent Transfer Condition
The Agent Transfer Condition component has some built-in transaction actions that it can return.
You can map the transitions for these actions on the Transitions tab of the component's property inspector.
Action | Description |
---|---|
conditionsMet |
The conditionsMet transition is set
when when it's inside business hours and the
maxWaitSeconds ,
maxEngagementsInQueue and
allowTransferIf conditions are met.
|
conditionsNotMet |
The conditionsNotMet transition is set
when one of the following occurs:
|
error |
The error transition is set when
there's an issue with the connection to the agent chat service during
the agent conditions check.
|
You can set these transition actions on the Transitions tab of the component's property inspector.
Resource Bundle Entries for Agent Transfer Condition
The Agent Transfer component also uses the following property that is stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_AgentTransferCondition_errorMessage |
The message that's
shown to the user when a system error occurs while transferring the chat
session to an agent. The default is:
You can set the property to a blank or empty string to suppress message output. |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Call REST Service
Use this component to send an HTTP request to a REST endpoint that you configured in the API Services settings.
Here are the component properties:
Property | Description |
---|---|
REST Service | The name of the API Settings REST service that defines the configuration for the endpoint. See Add a REST Service for an Endpoint. |
Authentication Type | The authentication type that's defined for the REST service. You only can change this value from the REST Services tab. |
Endpoint | The URI that's defined for the REST service. You only can change this value from the REST Services tab. |
Method | Select which configured method to use for this REST call. |
Request Body | For POST, PATCH, and PUT requests, specify the request body to send with the REST request.
Tip: If the body contains FreeMarker expressions, then you can switch Expression to On to see FreeMarker syntax coloring. However, if you do so, JSON syntax validation is turned off. |
Parameters | For the path parameters that are in the endpoint, add a parameter of type Path, set the key to match the path parameter, and set the desired value. Note that if a path parameter is defined in the REST service configuration and you want to use that parameter's value, you don't need to add it to the component.
For query parameters that you want to pass in the REST request, add a parameter of type Query, set the key to match the query parameter, and set the desired value. Note that if a query parameter is defined in the REST service configuration and you want to use that parameter's value, you don't need to add it to the component. Tip: If the REST Services configuration set a query parameter that you don't want to use in this call, you can clear that parameter by setting its value to${r""} .
After you edit the parameter, click |
Response Mode |
Specify which response you want returned after the call completes:
Note that if the REST service configuration doesn't have a static response, then the only choice is Use Actual Response. |
Result Variable |
The name of the map variable for storing the response data. The map will contain a
|
Note:
The size of the response payload that can be stored in the result variable is limited to 15 KB by default. If you need a higher limit, file a service request (SR) with Oracle Support.The component returns these actions:
Action | Description |
---|---|
success | The response status code is in the 100-399 range. |
failure | The response status code outside the 100-399 range. |
To learn more, see Access Backends Using the REST Service Component.
Knowledge Search
Use this component to search Oracle B2C Service Knowledge Foundation or Oracle Fusion Service Knowledge Management for information about a given search term and to display the results.
For Oracle B2C Service, the search results depend on whether the answers are public and what the access level, product, or category settings are.
Note that you must create a knowledge search service before you can use this component. See Add a Knowledge Search Service.
Here are the Knowledge Search component properties:
Property | Description |
---|---|
Search Service Name | The name of the knowledge search integration as configured in Settings. |
Term to Search For | The text to use as the search term for the knowledge
search invocation. A search term is required for Oracle Fusion
Service Knowledge Management. For Oracle B2C
Service Knowledge Foundation, it returns the most popular articles if no
search term is provided.
For search term techniques, see Use the Knowledge Search Component. |
Text to Display Ahead of Results | The text to output before the search result is displayed.
If this property is On, the KnowledgeSearch - searchPrelude value in the configuration resource bundle is used. The default is Off, meaning no text is displayed. |
Maximum Number of Results | The maximum number of results to display.
The default is |
Preferred Version of Results | Oracle B2C
Service only: The preferred version to return when there are multiple
versions for a result. You can set this property to either
Answer or Special Response .
The default version is
|
Only Show Preferred Version |
Oracle B2C
Service only: When When The default is |
Web Article Link Label | The label to use for the result card's URL action
(button) that links to the web version of the information.
If you set this property to Off, the web article link button is not displayed and the full text is output instead. This is not recommended if you have very long articles that would be hard to read in a typically-sized skill widget. The default is On, which means the KnowledgeSearch - resultLinkLabel value in the configuration resource bundle is used. |
Web Search Page Link Label |
Oracle B2C Service: The label to use for the card message payload action that's linked to the web page with the full search result list. Oracle Fusion Service: The label to use for the card message payload action that's linked to home search page. If this property is On, the KnowledgeSearch - searchLinkLabel value in the configuration resource bundle is used. The default is Off, meaning the card message does not display the action. |
Card Layout | Specifies whether to display the result cards vertically
or horizontally. Defaults to horizontal .
|
Search Using Locale | Defaults to the value of the
profile.locale variable.
For Oracle B2C
Service multi-interface knowledge integration services, the
five-character ISO or BCP locale code that specifies which interface
to use to perform the search (e.g. 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
|
Result Filters | A list of search result filters. The allowable filter types are Product and Category . Each of them allows only one filter declaration.
|
Custom Properties | Oracle B2C
Service only: A map of key/value pairs to send to the search service.
Currently, this property supports only the
word_connector key. You use the
word_connector property set to AND
to prepend every word in the search term with
+ .
|
Transition Actions for Knowledge Search
The Knowledge Search component has some built-in transaction actions that it can return.
You can map the transitions for these actions on the Transitions tab of the component's property inspector.
Action | Description |
---|---|
resultSent |
The search returned at least one result. |
noResult |
There were no results for the search term. |
serverError |
An error occurred on the knowledge search service's
server during the invocation, such as a server error fault or an
unexpected error fault.
When this error occurs, the error
message is stored in
|
Resource Bundle Entries for Knowledge Search
The Knowledge Search component also uses the following properties, which are stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_KnowledgeSearch_defaultAttachmentLabel |
The default label to
use for the result card's URL action that is linked with an attachment
of the search result if that attachment does not have a display name
configured already. When used, it's appended by an index number. For
example, if the second attachment doesn't have a display name, then the
default attachment label is appended with 2 .
The default is |
|
systemComponent_KnowledgeSearch_noResultText |
The text to output when
no search result is available.
The default is:
|
|
systemComponent_KnowledgeSearch_resultLinkLabel |
The label to use for
the result card's URL action that's linked to the web version of the
knowledge article.
The default is |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Incident Creation
You use the Incident Creation template to create an incident report on a customer service site. Note that you must create a customer service integration from the Settings > Additional Services > Customer Service Integration page before you can use this component in your instance.
Property | Description | |
---|---|---|
Incident Service Name | The name of the integration as configured in Settings > Additional Services > Customer Service Integration. | |
Subject of Incident | The text for the subject of the incident. | |
Attachment URL | The URL of a document or image that's related to the incident. Note that adding attachments is not supported for DA as Agent skills. | |
Agent report filter | (For Oracle Fusion Service incidents), text to filter the incidents. | |
Add chat transcript to the incident | (For Oracle Fusion
Service incidents.) When set to True, the chat transcript is added to the
incident.
Insights must be enabled for the skill for this to work. 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. |
|
Custom Fields | Contains the description key/value pair and, optionally, the contactInfo key/value pair, which can contain a map of additional details about the incident.
The key/value pairs are passed unvalidated as a text version of the object and inserted into the incident message as a private note. |
|
Contact Properties | Key/value pairs that contain the information
that's required to look up or create customer service contact
information. It must contain email, and can
optionally contain firstName and
lastName.
If email isn't provided, then you must provide both firstName and lastName. |
|
String context variable to store the incident number | The name of the string variable in which to store the incident number. |
Intelligent Advisor
Use this component to access an Oracle Intelligent Advisor interview from a skill.
You must create an Intelligent Advisor service integration before you can use this component. See Add an Intelligent Advisor Service. In addition, the interview must have been deployed to the Intelligent Advisor Hub and activated on the chat service channel. The interview must be for anonymous users. You can't access interviews for portal users or agent users.
You can use the component's properties to specify the following interview settings:
- Whether to display the titles and the explanation
- The labels for the yes, no, and uncertain buttons
- The strings that the user enters to reset, go back to the previous question (undo), and exit the interview
- The text to display at the end of the interview
- How to phrase the question about whether to display the explanation
- The string the user enters to indicate they are done uploading files
- The attribute values and connector params to pass to the interview
- The project locale to use
Intelligent Advisor Properties
Here are the Intelligent Advisor component properties:
Property | Description |
---|---|
Intelligent Advisor Service Name | The name of the Intelligent Advisor service as configured in Settings > Additional Services. |
Deployment Project Name | The name of the active deployment project on the Intelligent Advisor Hub. |
Variable for Interview Results | The name of a list variable in which to store the interview's attribute values upon return from the interview to the skill. The attribute values are stored as an array of key/value pairs. |
Hide All Screen Titles | Indicates whether to hide all the screen titles in the interview. |
Show Explanation | Specifies whether to show the Intelligent Advisor
explanation. The allowed values are never ,
always and ask .
If
you set to If you don't define
this property, the behavior defaults to
|
Seed Data | A map of Intelligent Advisor attribute names and values
to pass to the interview. For date and time attributes, use the standard
Intelligent Advisor date and time formats. For example:
start_date: "2010-01-31" .
The attribute that you are passing the value to must have the Seed from URL parameter option enabled in Policy Modeling. See Pass Attribute Values and Connection Parameters for details on working with Policy Modeling. |
Connection Parameters | A map of key-value connection parameters to pass upon the start of interview. This is typically needed for interviews with external data integration. |
End Interview Text Label | The label that's shown in the chat at the end of the
interview. If set to Off, no message will be
shown in the chat at the end of the interview. The default is
On, meaning the
systemComponent_IntelligentAdvisor_endLabel value
in the configuration resource bundle is displayed at the end of the
interview.
|
Remove HTML Tags From Output | Indicates whether to remove the HTML markup from the
text. The default is false .
|
Interview Locale | The five-character ISO or BCP locale code (e.g.
en_GB ) used to specify the language that the
interview should start with.
This property affects both the target interview and date and number resolution. The component initiates the version of the named
interview (deployment) that's associated with the language specified
by the component's 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
|
Interview Expected Currency | The ISO-4217 currency code for the currency that's used in the interview. When this code is specified, the user only can input currency values in the formats that are allowed for that currency. You can set this property to blank or null if the interview doesn't prompt for currency amounts or is not expecting any certain currency. |
Resource Bundle Entries for Intelligent Advisor
The Intelligent Advisor component also uses the following properties, which are stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_IntelligentAdvisor_answerNotValid |
Message that's displayed for Intelligent Advisor interview inputs of type Masked when the user's answer doesn't conform to the specified input mask. | |
systemComponent_IntelligentAdvisor_defaultValue |
Text that's added to a question when the Intelligent Advisor interview input has a default value. | |
systemComponent_IntelligentAdvisor_doneHelp |
Help message that's displayed for Intelligent Advisor interview inputs of type Upload. | |
systemComponent_IntelligentAdvisor_doneLabel |
The text that the users
type to indicate that they are done uploading a file.
The
default is |
|
systemComponent_IntelligentAdvisor_endLabel |
Text to display in the chat at the end of the
interview.
The default is |
|
systemComponent_IntelligentAdvisor_exitLabel |
The text that users type to indicate that they want to
exit the interview.
The default is
|
|
systemComponent_IntelligentAdvisor_explanationAskLabel |
The question to ask when showExplanation
is set to ask .
The default is |
|
systemComponent_IntelligentAdvisor_maskLabel |
Text that's added to a
question to display the expected format for Intelligent Advisor
interview inputs of type Masked Text Box.
The default is
|
|
systemComponent_IntelligentAdvisor_noLabel |
The label to use to represent Boolean FALSE values.
The default is |
|
systemComponent_IntelligentAdvisor_numberMinMax |
Message that's
displayed when the user enters a value outside of the specified range
for an Intelligent Advisor interview input of type Slider.
The default is |
|
systemComponent_IntelligentAdvisor_outOfOrderMessage |
Error message that's
displayed when the user taps a button in a previous Intelligent Advisor
interview message.
The default is:
|
|
systemComponent_IntelligentAdvisor_resetLabel |
The text that users type to indicate that they want to
go back to the first question.
The default is
|
|
systemComponent_IntelligentAdvisor_resumeSessionPrompt |
Question that is asked
if the user starts an interview that they had previously left before the
interview completed.
The default is:
|
|
systemComponent_IntelligentAdvisor_uncertainLabel |
The label that the user can type if they don't know the
value. This label appears for optional Boolean radio buttons.
The default is |
|
systemComponent_IntelligentAdvisor_undoLabel |
The text that the users type to indicate that they want
to go back to the previous question.
The default is
|
|
systemComponent_IntelligentAdvisor_yesLabel |
The label to use to represent Boolean TRUE values.
The default is |
|
systemComponent_IntelligentAdvisor_yesNoMessage |
Message that's
displayed when the user enters an invalid answer for Intelligent Advisor
interview inputs of type Boolean Radio Button.
The default is:
|
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Webview Component
The Webview component opens a webview within your skill, or for skills that run in a web channel, in an browser tab.
Property | Description |
---|---|
Webview Component Service | The name of the webview component service. |
Inputs for Service | A comma-separated list of variable names. These variable names are the parameters that are sent to the webview from the skill. |
Output for Service | The name of the variable (a string value) that identifies
the webview payload that’s returned to the bot after the user completes
his or her interactions within the webview.
Because the payload is stored in this variable, which you can access at a later point in your dialog flow definition. For example, you can reference this in an output component. |
Component Service URL | The base URL to which the variable names set for the Inputs to Service property are sent as parameters. This is a base endpoint provided by a web server. This property is not supported in the current release (you configure this now in the Create Service dialog). However skills built with prior versions will still function. |
Image URL | The URL of the image that accompanies a prompt. |
Authorization Token | The authorization token that’s sent with requests to the
URL specified by the Component Service URL
property. This property is the form of Basic
<token> or Bearer <token> .
|
Query Parameters for Service | The stringified JSON object whose key-value pairs are the query parameters that are appended to the POST request. |
Transition Actions for the Webview Component
The Webview component has some built-in transaction actions that it can return.
You can map the transitions for these actions on the Transitions tab of the component's property inspector.
Transitions | Description |
---|---|
cancel |
Triggered when the user taps the Cancel button. |
system.textReceived |
Triggered when the user enters text rather than tapping one of the buttons. |
unexpectedAction |
Triggered when the user taps a button from a previous reply. |
Resource Bundle Entries for the Webview Component
The Webview component also uses the following properties, which are stored in the skill's resource bundle:
Resource Bundle Key | Description | |
---|---|---|
systemComponent_Webview_cancelLabel |
The label of the cancel
button to leave this state without invoking the webview.
The default
is |
|
systemComponent_Webview_linkLabel |
The label of the button
to invoke the webview.
The default is |
|
systemComponent_Webview_prompt |
The message for the
user to tap on the link to invoke the webview.
The
default is |
See Modify a Resource Bundle Entry for the steps to change the default message for a resource bundle entry.
Notify User
You use this component to send a notification to a user when a Cloud-based event of a type that has been registered in Oracle Digital Assistant has occurred. See External Events for information on registering event types and configuring a digital assistant to consume the event.
Property | Description |
---|---|
User ID | (Optional) If you want to dynamically determine which user to notify of the event when it is received, enter the unified user ID that is returned from the user's messenger service. If this value is set, when the event is generated, Digital Assistant will pass this ID to the messenger service to get user data, such as the channel, and the channel's ID for the user so that it can notify that particular user. This property only works for Slack and Twilio channels and for users that have already interacted with Digital Assistant. |
Notification Message | The message that is returned to the user.
In the message, you can make use of expressions in the following formats to access information from the event:
|
Publish Event
You use this component to externally publish a Cloud-based event of a type that has been registered in Oracle Digital Assistant. See External Events for information on registering event types and configuring a digital assistant to publishing and consuming events.
Property | Description |
---|---|
Name | The name of the type of the event that is to be published |
Data | The payload of the event in JSON format. |
Here's an example payload that could be used as the value for the Data property:
{
"size": "Large",
"type": "Veggie"
}
Component Changes in the Visual Flow Designer
In the Visual Flow Designer, a number of components that were part of the YAML-based dialog flow editor have changed or are no longer available. Here are the key changes:
- The
ConditionExists
andConditionEquals
components aren't supported. You can use the Switch component instead. - The
Text
,List
, andOutput
components aren't supported. Instead you can use the Send Message, Ask Question, and Resolve Composite Bag templates, as well as the templates in the User Messaging category, most of which are templates based on the Common Response component. - The Resolve Entity and Common Response components will now
always attempt to slot entities from the
system.nlpresult
variable.As such the
nlpResultVariable
property is no longer necessary and has been removed from those components. - The
autoNumberPostbackActions
variable and component property are not supported. Auto-numbering can be configured at the skill level using the skill's Enable Auto Numbering on Postback Actions in Task Flows configuration setting (or at the digital assistant level using the digital assistant's Enable Auto Numbering on Postback Actions setting). - The
autoTranslate
variable and thetranslate
component property are not available. They are replaced by the Translate User Input Message and Translate Bot Response Message properties, which are set at the skill level. - The
transitionAfterMatch
component property for the Common Response and Resolve Entity components is no longer supported. To get this functionality, you can use an entity event handler. - The value of the
useFullEntityMatches
property for the Common Response and Resolve Entity components now defaults totrue
.This means that the value of the resolved entity is returned as an object and you need to specify the appropriate object property to return a string value.
- The value of the
cancelPolicy
property for the Common Response and Resolve Entity components now defaults toimmediate
(instead oflastEntity
).This means that the cancel transition occurs after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide maxPrompts value has been met.
- The Insights component properties
insightsInclude
andinsightsEndConversation
are not supported. The modular flows already delineate the conversation, soinsightsEndConversation
is not needed. A conversation ends when the last state of a top-level flow has been reached.
Message Handling for User Message Components
Typically, a user might respond to a message in the following ways:
-
By entering free text.
-
By sending their location.
-
Using a multi-media option to send an image, audio file, video, or file attachment.
-
Tapping one of the postback buttons displayed in the most recent message output by the bot.
-
By scrolling to a previous message in the conversation and tapping one of its buttons.
Handling Free Text
variable
property. When the
text is a valid value, these components trigger the textReceived
transition. If you don’t define the textReceived
transition, the Dialog
Engine transitions to the state defined by the next
transition or the
Unexpected User Input event.
Tip:
UsetextReceived
to handle unexpected user messages when
you expect the user to tap a button, send an attachment, or a location.
Handling Multimedia Messages
{
"type": "video",
"url": "https://www.youtube.com/watch?v=CMNry4PE93Y"
}
For
example, if a video attachment is stored in a variable called myVideo
,
you can access the video using the FreeMarker expression,
${myVideo.value.url}
.
Handling Location Messages
{
"title": "Oracle Headquarters",
"url": "https://www.google.com.au/maps/place/…",
"longitude": -122.265987,
"latitude": 37.529818
}
For
example, if the location is stored in a variable called location, you can access the
latitude using the FreeMarker expression, ${location.value.latitude}
.
Postback Actions
{
"action": "order",
"state": "OrderPizza",
"variables": {
"orderedPizza": "PEPPERONI",
"orderPizzaImage": "http://pizzasteven/pepperoni.png"
}
How Out-of-Order Actions Are Detected
system.state
property in the payload, which identifies
the state for which the postback was rendered, enables the system to identify when a user
performs an action that occurs out of the current scope, such as tapping a button from a
previous
response.
"system.postbackActions": {
"small": {
"postback": {
"variables": {
"size": "Small"
},
"system.botId": "44F2405C-F317-4A3F-8250-617F54F01EA6",
"action": "Small",
"system.state": "size"
For example, a user might tap the Order Now button for a pepperoni pizza, but instead
of completing the order, he might scroll further up to a previous message and clicks Order
Now for a pasta dish.
At this point, the system compares the system.state
property in the payload of the incoming postback action against the current state. When the
two no longer match, the skill executes a transition that can, depending on how you configure
your dialog flow, either honors the user's request, or denies it.
skill.system.event.value.outOfOrderMessage.outOfOrderState
and
skill.system.event.value.outOfOrderMessage.currentState
variables, you can
customize this behavior either for the entire skill, or for a particular state in the dialog
flow.
-
skill.system.event.value.outOfOrderMessage.outOfOrderState
—Holds the value of thestate
property in the incoming postback payload, the "out-of-order" message. -
skill.system.event.value.outOfOrderMessage.currentState
—Holds the value of the current state.Note:
Only components that set the state property in the postback payload can enable the skill to respond when the user skips back in the flow. TheOAuthAccountLink
component does not set this property.