Components

Components give your skill its actual functionality. The state nodes in your dialog flow definition are built around them. These reusable units of work perform all manner of tasks and functions, from the basic management of the dialog flow to case-specific actions.

Every state in your dialog flow names a component that performs an action, such as accepting user input, verifying that input, or responding with text. Each component has a specified set of properties that you can use to pass and receive values as well as control the component's behavior. For example, the following state uses the System.List component to display a list of values that the user can choose from. The state uses the options property to provide the values for the list, and it uses the maxPrompts property to tell the state to transition to the next state whenever the user enters 2 invalid values. The variable property names the variable to store the choice in.

  size:
    component: "System.List"
    properties:
      prompt: "What size pizza do you want?"
      options: "${size.type.enumValues}"
      variable: "size"
      maxPrompts: 2
    transitions:
      actions:
        cancel: "setDefaultSize"

There are two types of components that you can use in a dialog flow – built-in components and custom components. When the Dialog Engine enters a state in the dialog flow, it assesses the component. When it encounters one of the built-in components (noted by System.), it executes one of the generic tasks, such as display a message or prompt the user to enter text. When the Dialog Engine discovers a custom component, however, it calls the component's service, which hosts one or more custom components.

Built-In Components

We provide a set of components that support a range of generic actions, which you can use in any skill: security, parsing the user input, routing the dialog flow based on that user input, and outputting the skill’s responses in various ways. Unless you need to integrate with backends or perform extremely complex logic, these components will provide the actions that your states need.

To add a state for a built-in component to your dialog flow, click + Components on the Flows tab, select the component type, and then select the component. The component's template is displayed, which lists the component's properties with descriptions that explain the purpose of each one. When you apply the component, you can choose whether to include the descriptions in the state that's added for the component.

When you validate your dialog flow, Oracle Digital Assistant verifies the component's properties. For example, it will report if you forgot to include a required property.

For details, see Built-In Components: Properties, Transitions, and Usage.

Custom Components

Most skills need to integrate with data from remote systems or do some backend processing. For example, your skill might need to get a list of products or save order information. Another example is that your skill might need to perform complex logic that you can't accomplish using FreeMarker. Custom components enable you to integrate with backends as well as perform tasks that aren't covered by the built-in components.

To learn how to build a custom component, see Task 1: Implement Custom Components. To learn how to add custom components for use in your skill, see Task 3: Add Component Package to a Skill. To learn about a custom component that's been added to the skill, go to the skill's Components Components icon page, expand the component service and select the component. The component's name, properties and supported actions are displayed. Use this information to build the component's state in your dialog flow.

Tip:

Because it's possible for components from different services to have the same name, you can prepend the component name with the service name followed by a colon (:) to ensure that you uniquely reference each custom component that you use.

In addition to the component's defined properties, you can include these properties in the custom component's state:

Name Description Required?
autoNumberPostbackActions When set to true, this option prefixes numbers to buttons and list options. Even when you haven’t set this option to true, auto-numbering can be enforced on card items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. The default is false. No
insightsEndConversation Set to true to stop recording the conversation for insights reporting. The default is false. No
insightsInclude Specifies whether to include the state in insights reporting. The default is true. No
translate Use this property to override the Boolean value that you’ve set for the autotranslate context variable. If you haven’t set the autotranslate variable, or if you set it to false, then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable to true, then you can set this property to false to exclude this component from autotranslation. See Translation Services in Skills. The default is the autotranslate context variable value. No

Here's an example of a custom component state in the dialog flow. The hello.world component is from the custom service.

  start:
    component: "custom:helloWorld"
    properties:
      human: "${human.value}"
    transitions:
      next: "askAge"

When you use the embedded component service to host your custom components, you can access view logs and crash reports for the components from the Components Components icon page. Select the service, and then click Diagnostics.