There isn’t a field for providing descriptions for custom components that explain what they do and what information must be passed to them. So the best ways to help skill developers with use of your component are to use good names for the component and input parameters and to carefully choose the action strings that your component returns.

• Built-in YAML components use System.<name> as their name. So, especially for YAML-based dialog flows, you may want to use Custom.<name> for skill reviewers to understand it’s a custom component that the dialog flow references. Or, you can use a name space to provide context. For our sample custom components we often use oracle.sample.<name> to indicate that those components are not meant to be production quality.

• Input parameters provide data to the custom component to process. Often the data passed to a custom component is not the actual value to work with, but rather the name of a variable that either holds the data values to process or to which data queried from a remote service should be written to. Looking at the built-in components, they use variable as the property name to hold the name of the variable that the component result will be written to, or <name>Var (e.g. nlpResultVar) to indicate properties that refer to a variable reference name. You can further improve this by using the _in and _out postfixes to indicate whether a variable refers to a variable that contains data or is expecting data from the component.

• Action strings are optional and can be used by the skill developer to determine the next dialog flow state to navigate to. Using success or failure as an action string does not provide much context, so we suggest using something like orderSubmitted, orderRejected, or userUnauthorized instead.

The reality is that often the developer of a custom component is also the skill developer who uses it. For this reason, many developers simplify their work with custom components by making assumptions about variables that are present in the skill. So instead of passing the name of a variable to the component, they refer directly to the name in the custom component logic. We do not recommend this because such assumptions can easily break a custom component. We recommend defining a clear and complete contract between the custom component and the skills using it.

A common question is about how many custom components should be added to a custom component service package. In general it is always a good idea to think of custom component services, and the components it contains, as libraries. So, all components that relate to a task could be saved in a single custom component service. However, recommendations need to be able to face reality. Therefore, the question about how to package custom components needs to be answered based on the intended use of the custom components.

• Reuse is not an option for many custom component developers. When custom components are developed for and used in a specific skill, it makes sense to group all those components into a single custom component service deployment. The exception to this is for components that are actually reused in other skills.

• Embedded component container deployments are restricted by the number of custom component services per Oracle Digital Assistant instance. Therefore, you’ll want to use a single custom component service per skill or look for a remote deployment of your custom components.

• Use remote custom component service deployment to Kubernetes in Oracle Cloud Infrastructure, for the following reasons:

  • To not disclose sensitive information contained in your custom component code. Custom component services deployed to the embedded container can be downloaded by anyone who has full access to your Oracle Digital Assistant instance.

  • To implement better segmentation of your code. Custom components should only contain code that is necessary to interact with the bot and to invoke REST services. All other code should be stored in external JavaScript files (if using an embedded container) or in integration layers (REST services). Custom components include code that does the following things:

    • read input parameters

    • read/set variable values

    • handle messages received by a component

    • render the custom component user interface

    • determine transition to a next state

    • manage component state

    • access REST services

  • To improve performance. The embedded container for deploying custom components to skills uses OCI functions, which have a cold start delay. To avoid this delay, as well as the limit in the number of services that can be deployed, a remote deployment of custom component provides you with a worry-free alternative.

  • To share common components. Though our experience is that reuse isn’t highly ranked among custom component developers, it makes sense to create and deploy commonly used custom components to a remote server. You might have common components for things like error handling and escalation, 2-legged OAuth2 authorization handling, and more.

The default logger implemented for custom components is the console logger. You access the logger through a call to context.logger(). You can the call logging functions available for the console logger like ".info('…') or ".warn('…')".

Note: Using context.logger() makes the most sense when deploying to the embedded container, as the embedded container knows how to properly display these logs. For custom components that you deploy externally, it is best to use a different logging library, like log4js.

Custom dialog flow components may have a longer interaction with a user before navigation transitions to a next dialog flow state. For this interaction you need to make sure the component handles its internal state so it can distinguish between an initial call and subsequent calls. There are two options for doing so:

• Add a token to the postback message payload. When the custom component renders a user interface where users can press an action item, a postback message is sent back to the custom component. The custom component must evaluate the postback messages it receives to determine whether that postback is from the user interface it is rendering or from another component. For this it can check the postback message as to whether it contains a token that the custom component added when rendering the action item.

• Use a context variable. If you need to manage a more complex state between custom component invocations, e.g. to keep track of values extracted from user messages, you can use a dialog flow variable for this. Custom components can create dialog flow variables at runtime in a call to context.variable('variable name', value). If a variable of the specified name does not exist, then it will be created. The "value" object can be anything you need to keep track of.

Input parameters that you define for a custom component need to be validated to have content. This is also true for parameters that you set as required. The following cases need to be checked:

• The input parameter has a value set.

• The value does not start with '$ {', as this indicates an expression for reading the input parameter value from a variable or that an object is not correctly resolved in the dialog flow.

All bot responses you send from a custom component should use the MessageFactory class. The MessageFactory class can be used to create the same type of rich user messages as the Common Response component, which includes list of values, attachments, card layouts and text messages.

In addition, messages that are defined with the MessageFactory class are channel independent. This means that you create a single component message, which is then converted by the channel-specific connectors into the format required by the respective client channel.

To access the MessageFactory class from a custom component, you use the following reference:

let MessageFactory = context.MessageFactory();

• ☑ Ensure backend services are optimized or abstracted for use with skills.
• ☑ Custom components should only contain bot-related code. All other code should be moved into utility classes or libraries, or be deployed as individual REST services to a remote server or cloud service.
• ☑ Create a clear and complete contract between custom components and the skills they are used in.
• ☑ Use custom components for complex evaluations. Avoid Apache FreeMarker in those cases.
• ☑ Manage component state for multi-request user interactions.
• ☑ Validate all custom component input parameters.
• ☑ Handle errors by returning an action string for the skill developer to handle problems.

• Tutorial: Custom component development for backend integration
• Tutorial: Custom component debugging
• Embedded Container Limits for Custom Component Services
• Bots Node SDK Documentation: MessageFactory sample code for various UI responses

A lot of the functionality that can be set for the Common Response component, like global buttons for help and cancel, is not available to the Resolve Entities component through configuration.

However, you can add missing functionality using entity event handlers. This enables you to take advantage of the simplicity of the Resolve Entities component in the dialog flow without sacrificing advanced functionality.

Entity event handler functions are invoked by the Resolve Entities and Common Response components when resolving a composite bag entity. There is no need for you to track which bag item needs to be resolved next as it is all done for you.

Still, you may want to save some information for later use. For this you have two options:

• Context resolution properties are variables you create on the context object. The variables and their values exist until the composite bag entity is resolved or you leave the dialog flow state that resolves a composite bag entity. The benefit of using the context resolution properties is that there is no housekeeping you need to do.

  • For write, use: context.setCustomProperty(name, value);
  • For read, use: context.getCustomProperty(name);

• Dialog flow variables created at runtime or at design time can be used to store values you want to persist beyond the resolving of the composite bag entity. Content stored in dialog flow variables can be accessed from dialog flow states (for variables defined at design time only) and from other entity event handlers.

  • For write, use: context.variable(name,value);
  • For read, use: context.variable(name);

The default logger implemented for entity event handlers is the console logger.

You access the logger through a call to context.logger().

You can the call logging functions available for the console logger like .info('…') or .warn('…').

Custom user messages are displayed through the context.addMessage() function. As with custom dialog flow components, our recommendation is to use the MessageFactory class for creating channel-agnostic messages instead of outputting channel-specific payloads. Entity event handlers also support messages of type value-list, card layout, and attachment.

• ☑ Store temporary values in the resolution context unless needed in a later dialog flow state.
• ☑ Use a single custom component service for all entity event handlers used in a skill.
• ☑ Use the MessageFactory class for messages to display to users.

• Oracle Digital Assistant Design Camp video: Understanding Entity Event Handlers

• Tutorial: Developing Entity Event Handler in browser

• Tutorial: Developing Entity Event Handler in external IDE
• Example: Model driven conversations using EEH by example of an expense report
• Bots Node SDK Documentation: MessageFactory sample code for various UI responses
• Documentation: Entity event handler functions (exposed on the context object)

Here's how you can access named parameters in a resource bundle:

//Entity event handler sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.addMessage(message,true);

//Custom dialog flow component sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.reply(message);

Using resource bundles everywhere is a common theme throughout this guide. However, the use of resource bundles stored in a skill creates a tight coupling between the custom dialog flow component or event handler and the skill. If you're okay with this dependency and value the benefit of having resource strings managed in a single place more than avoiding the problem of tight coupling, you should do it. For event handlers, the chance of reuse is minimal anyway, which is why there should be no doubt about the use of resource bundle strings in entity event handlers at all.

For custom dialog flow components that are reused in different skills, the translation function will also work if the skills have the resource bundle key names required by the custom component added to their resource bundle.

Using an alternative solution, you can avoid tight coupling of custom components to a skill by passing the messages read from a resource bundle as input parameters to a custom dialog flow component.