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 True to direct the Dialog Engine to return to the state after the user enters text or taps a button. Set this property to False if no user input is required (or expected).

Set this property to True when setting a location.

Keep Turn

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

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

Variable

This variable holds the name of 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 cancel action. See Limiting the Number of User Prompts

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

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

    This is the default value.

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

This property is ignored if you've registered an entity event handler with an item- or event-level maxPromptsReached handler.
Use Full Entity Matches When set to True, custom entity values are stored as JSON objects (similar to built-in entity values). This enables you to create expressions to access properties such as value, primaryLanguageValue, and originalString, which are particularly important for skills that are currently or eventually might become multi-lingual.
Transitions for Common Response Components
Common Response components use the transitions listed in the following table. Message Handling for User Message Components describes how these transitions get triggered.
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
Common Response components trigger 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

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:
<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>
Footer Text Enhances the output on text-only channels. For example, you can use FreeMarker expressions to conditionalize the footer text for text-only channels.
Cancel Policy Determines the timing of the cancel transition:
  • Immediate—Immediately after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide Maximum Number of Prompts value has been met.

    This is the default value.

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

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

User Feedback

The User Feedback component enables you to collect feedback data for Insights by presenting users with a rating scale after they've completed a transactional flow. 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 – When enableTextFeedback is set to true, your skill can prompt for feedback when the ratings fall below the threshold value. system.userFeedbackText returns the user's input (${system.userFeedbackText.value}).

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

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

Variables Templates

Copy Variables

Copies values from one variable to another.

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

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

Reset Variables

This component resets the values of specified variables to null.

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

Set Variable

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

Property Description
Variable The name of the variable.
Value The target value, which you can define as a literal or as a FreeMarker expression that references another variable. The value must match type of the declared variable.

Set Custom Metrics

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

Language Templates

Detect Language

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

Note

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

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

Note

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

Translate Input

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

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

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

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

Translate Output

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

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

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

Match Entity

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

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

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

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

The Match Entity component resolves only a single value.

Security Templates

OAuth Account Link

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

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

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

Property Description
Variable Specifies the 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:
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

This component can return the following actions:

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

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

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

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

Tip:

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

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


Description of fb_oauth.png follows

There are several ways to transition from this component:

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

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

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


Description of webview_login.png follows

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

OAuth 2.0 Account Link

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

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

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

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

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

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

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

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

This component can return the following actions:

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

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

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

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

Tip:

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

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


Description of oauth2accountlinksignin1.png follows

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


Description of oauth2accountlinksignin2.png follows

As mentioned earlier, you can set requiresAuthorization for a state to ensure that the user is authorized before invoking the state's component. If the user hasn't authorized yet, the dialog invokes the 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:

  1. If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
  2. Add a client-credentials authentication service for the identity provider, as described in Authentication Services.
Property Description
Authentication Service The name of the client-credentials service that you created in the Authentication Services UI for the OAuth2 identity provider.
Access Token Variable Name Specifies the variable to store the access token in. You can declare it 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:
ParamName: ParamValue

End Flow

This component is used to explicitly end a flow.

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

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

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

Service Integration Templates

Agent Communication Template

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

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

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

Agent Initiation

Here are the Agent Initiation component properties:

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

A customer needs help regarding ${flow_variable.value}

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

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

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

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

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

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

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

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

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

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

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

Here are the descriptions of the actions:

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

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

Resource Bundle Entries for Agent Initiation

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

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

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

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

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

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

Agent rejected.

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

Resuming chat with agent

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

Agent chat session established, Waiting for agent to join.

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

Agent Conversation

Here are the Agent Conversation component properties:

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

The Agent Conversation component can trigger the following actions:

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

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

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

Note

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

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

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

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

error

There is a problem connecting to the live agent service.

expired

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

By default, CS_IDLE_TIMEOUT is 10 minutes.

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

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

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

The Agent Conversation component uses the following resource bundle entries:

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

Chat session ended. Thanks for chatting with us.

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

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

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

bye, take care, see you, goodbye

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

Chat session expired. Thanks for chatting with us.

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

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

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

User left the chat.

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

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

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

Agent Transfer

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The chat has been transferred to another agent.

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

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

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

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

The default message is: Agent rejected.

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

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

Agent chat session established. Waiting for agent to join.

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

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

Agent Transfer Condition

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

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

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

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

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

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

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

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

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

Tip:

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

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

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

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

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

Resource Bundle Entries for Agent Transfer Condition

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

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

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

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

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

Call REST Service

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

Here are the component properties:

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

Tip:

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

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

Tip:

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

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

Response Mode

Specify which response you want returned after the call completes:

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

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

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

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

Result Variable

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

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

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

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

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 10.

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

The default version is Answer.

Only Show Preferred Version

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

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

The default is False.

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

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

Web Search Page Link Label

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

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

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

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

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

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

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

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

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

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

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

Resource Bundle Entries for Knowledge Search

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

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

The default is Download.

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

The default is:

Sorry, no result was found in the knowledge search.

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

The default is View Results.

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

Incident Creation

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

Property Description
Incident Service Name The name of the integration as configured in Settings > Additional Services > Customer Service Integration.
Subject of Incident The text for the subject of the incident.
Attachment URL The URL of a document or image that's related to the incident. Note that adding attachments is not supported for DA as Agent skills.
Agent report filter (For Oracle Fusion Service incidents), text to filter the incidents.
Add chat transcript to the incident (For Oracle Fusion Service incidents.) When set to True, the chat transcript is added to the incident.

Insights must be enabled for the skill for this to work.

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 ask, then use the systemComponent_IntelligentAdvisor_explanationAskLabel resource bundle entry to specify the text for asking if the user wants to see the explanation.

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

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

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

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

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

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

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

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

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

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

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

The default is /done.

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

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

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

The default is /exit.

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

The default is Do you want to see the explanation?

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

The default is Answer format: {0}

systemComponent_IntelligentAdvisor_noLabel The label to use to represent Boolean FALSE values.

The default is No.

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

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

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

The default is:

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

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

The default is /reset.

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

The default is:

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

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

The default is Uncertain.

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

The default is /back.

systemComponent_IntelligentAdvisor_yesLabel The label to use to represent Boolean TRUE values.

The default is Yes.

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

The default is:

Enter either {0} or {1}

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

Webview Component

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

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

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

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

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

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

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

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

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

The default is Cancel.

systemComponent_Webview_linkLabel The label of the button to invoke the webview.

The default is Tap to continue.

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

The default is Please tap on the link to proceed.

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

Notify User

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

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

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

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

Publish Event

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

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

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

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

Component Changes in the Visual Flow Designer

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

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

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

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

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

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

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

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

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

When a user enters free text, Common Response components first validate this input as the variable value that's specified by the 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:

Use textReceived to handle unexpected user messages when you expect the user to tap a button, send an attachment, or a location.

Handling Multimedia Messages

When a users sends a file, image, video, or audio file, Common Response components store the attachment information as a JSON object in the variable property that’s specified for the component. This object has the following structure:
{
  "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

When a user sends his or her current location, Common Response components store the location information as a JSON object in the variable property specified for the component. This object has the following structure:
{
  "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

The actions in the response message, such as buttons, links, and list items, are implemented as postback actions. For example, when a user taps a button, its postback gets rendered. Its payload is a JSON object that holds the name of the state, the values set for the dialog flow variables, and the transition actions. For example, the following payload is rendered when a user taps the Order Now button for a pepperoni pizza:
{
	"action": "order",
	"state": "OrderPizza",
	"variables": {
		"orderedPizza": "PEPPERONI",
		"orderPizzaImage": "http://pizzasteven/pepperoni.png"
	}

How Out-of-Order Actions Are Detected

The 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.

By default, Digital Assistant allows out-of-order actions. This means that the variable values get reset. Using the flow's Out of Order Message action and the 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 the state 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. The OAuthAccountLink component does not set this property.

Override Out-of-Order Message Handling with a Message Handling State

You can change the default behavior out-of-order message handling by mapping the Out-of-Order Message system transition event to an Invoke Flow component that calls a flow you have provided for handling out-of-order messages.