Extending Digital Assistants and Skills

You can extend any digital assistant or skill that you have pulled from the Skill Store to customize it for cases specific to your business. When a new version appears in the Skill Store, you can transfer your customizations to the new version by rebasing.

Note

Extension of digital assistants is not supported for versions earlier than 20.6.

What is Extension and What's it For?

When you install bots (digital assistants and skills) from the Skill Store, they may not satisfy all your requirements or you may want to modify them to align with your business processes. You can't modify an installed bot directly, but you can can create an extension of it and then modify that extension.

When you create an extension, you are creating a new bot that has a tight relationship to the original (base) bot. Through this relationship, you can later take advantage of updates to the base bot without having to manually reapply your customizations. You do this by using the Rebase feature. When a new version of the base bot becomes available in the Skill Store, you can install that version into your instance and then rebase your extended bot to the updated base version.

Note

When you extend a bot, you can add to or modify existing properties of the bot. However, you can't delete any properties that were defined in the base bot.

Cloning vs. Extending

Though cloning and extending are similar on a surface level, they have key differences and purposes:

When you create a clone of a bot:
- You create a totally independent copy of the bot.
- You can make unlimited changes to the clone.
- The clone loses all association with the original bot (the tracking IDs for the cloned bot do not match those of the original), so you can't later rebase to an updated version of the original bot.
Use cloning when you want to use an existing bot as a starting point for your development.
When you extend a bot (a skill or a digital assistant):
- You can make a wide range of additions and changes to the extended bot but you cannot delete anything that was defined in the base bot.
- You can later rebase, which means applying updates from the base bot into your extended bot.
  Rebasing is possible for extended bots because the internal tracking IDs that are generated for the extended bots match those of the base bots.
Use extension when you want to customize a bot and then later be able to incorporate any improvements or new features from the base bot into your customized version. You can only extend skills and digital assistants that you have pulled from the Skill Store.

Note

A third approach is to extend a bot, make customizations, and then create a clone of the extended bot. When you do this, the clone of the extended bot is also treated as an extension of the original bot (the internal tracking IDs that are generated for the clone of the extension match those of the original bot).

What Happens When You Extend a Skill or a Digital Assistant

When you extend a bot (either a skill or digital assistant), each of the parts of the bot (such as intents, entities, and properties) have one of the following statuses:

Inherited (): artifacts that are defined in the base bot. After you create an extension, all the artifacts in the bot have this status.
Local: artifacts that have been created in the the extension (e.g. new intents).
Customized (): artifacts inherited from the base bot whose values have been changed in the extension.

When you extend a skill, filters for these statuses appear on the Intents tab above the list of intents and above the list of examples.

When you extend a digital assistant, filters for these statuses appear above the list of skills (on the Skills tab) and above the list of examples (on the Intents tab).

Note

It is not possible to delete artifacts (such as skills in digital assistants, and intents and entities in skills), but you can disable them.

Important Note for Developers of Base Bots

If you are a developer of a skill or digital assistant that has been uploaded to the Skill Store and you need to update that bot in the Skill Store, you must create the updated version via the New Version option in order for users to be able to rebase their extended versions to the updated base version. If you clone the existing bot or simply create a new bot with the same name, the internal tracking IDs that are generated for the new bot will differ from those of the existing bot, so there will be no correlation between the bots.

Skills

Here's what you need to know about extending skills that you have pulled from the Skill Store.

Extend a Skill

Click to open the side menu, and select Development > Skills.
In the tile for the skill that you want to extend, click the Options icon (), and select Extend.

This skill must be a skill that you have pulled from the Skill Store.

What You Can Add and Customize in an Extended Skill

Intents. You can add utterances, change existing utterances, and add new intents. You can't delete utterances or intents, but you can disable intents.
Entities. You can add entity values, add synomyms to entity values, and add new entities. In addition, you can edit these fields:
- Enumeration Range Size
- Error Message
- Multiple Values
- Fuzzy Match
However, you can't delete entities or delete or change entity values.
Dialog flow. You can make changes throughout the dialog flow. There are no specific limitations. However, no deltas are tracked by the system. When you rebase the skill extension, you are presented with a diff tool to compare your dialog flow side-by-side with that of the new base skill. It's then up to you determine what to keep from your skill and what to bring forward from the new base skill.
Resource bundles. You can:
- Add new message keys in any of the supported languages.
- Modify any of the existing messages.
Custom component service. You can:
- Replace the package file.
- Add components to the service.
You can't:
- Remove components.
You can change the implementation of custom components in your extended skill. However, if the custom component is later updated in the base skill, those updates will not be merged with any changes you have made to the component in the extended skill when you rebase your skill. In this case, you would need to manually merge the custom component changes from the updated base skill into your extended skill.
Settings. You can adjust most of the settings for the skill, including:
- General properties, like skill description.
- Training model.
- Whether insights and conversation logging are enabled.
- Values of system parameters, such as confidence threshold and standard prompts.
- Custom parameters. (You can create new custom parameters and modify values of existing ones.)
- Values of digital assistant properties, such Invocation, Example Utterances, Start State, Welcome State, and Help State.

Modifications Which Aren't Preserved When Rebasing

Q&A. You can modify the contents of a Q&A module in an extended skill, but those modifications are discarded if you later rebase the skill.
If you have modified a Q&A module in your extended skill, be sure to export the Q&A source file before you rebase.

Note

This limitation does not apply to answer intents.

Disable Intents

When you extend a skill, you can't remove intents, but you can disable them.

When you disable an intent, you exclude it from the training model. Any user input that would otherwise match well with a disabled intent's training data will instead resolve to a different intent (likely unresolvedIntent).

If you later rebase the skill, any intents that you have disabled will remain disabled. If you re-enable an intent after rebasing, you will pick up any changes that were made to that intent in the base skill.

To disable an intent:

In the left navbar of the extended skill, click .
Select the intent you want to disable.
Turn the intent's Enabled switch to the OFF position.
Click the Train button in the upper right corner of the page and then click Submit.

Note

If you want to exclude the functionality of an intent from a skill but want to let the user know that the intent's functionality is not available, keep the intent enabled, but enter a static response in the intent's Answer field. When you do this, this text is displayed when the user's input resolves to that intent. See Answer Intents for more on how this works.

Digital Assistants

Here's what you need to know about extending digital assistants that you have pulled from the Skill Store.

Extend a Digital Assistant

Click to open the side menu, and select Development > Digital Assistants.
In the tile for the digital assistant that you want to extend, click the Options icon (), and select Extend.

This digital assistant must be one that you have pulled from the Skill Store.

What You Can Add and Customize in an Extended Digital Assistant

Skills. You can add other skills. You can't delete skills that are inherited from the base digital assistant but you can disable them.
System Intents. For the exit, help, and unresolvedIntents intents, you can add utterances and change existing utterances.
Settings. You can adjust most of the settings for the digital assistant, including:
- General properties, like the digital assistant description.
- Training model.
- Whether insights are enabled.
- Routing parameters, such as the various confidence thresholds and standard prompts.
- Custom parameters. You can create new custom parameters and modify values of existing ones.

Disable Skills

When you extend a digital assistant, you can't remove skills, but you can disable them.

When you disable a skill, you exclude it from the training model. Any user input that would otherwise match well with the skill's training data will instead resolve elsewhere (likely the digital assistant's unresolvedIntent).

If you later rebase the digital assistant, any skills that you have disabled will remain disabled. If you re-enable a skill after rebasing, you will pick up any changes that were made to that skill in the base digital assistant.

To disable a skill:

In the left navigation for the digital assistant, click .
Select the skill you want to disable.
Turn the skill's Enabled switch to the OFF position.

Update a Skill in an Extended Digital Assistant

If you have an extended digital assistant that contains a skill that has a newer version that is installed in your instance, you can update the digital assistant to use that newer version.

Click to open the side menu, and select Development > Digital Assistants.
Click the tile for the digital assistant to open it.
On the Skills tab of the digital assistant, select the skill that you want to replace with a newer version.

The skill should have the badge.
Click Update Skill.
From the New Skill Version dropdown, select the version of the skill that you want to include and click Update Skill.
Set the Overwrite Interaction Model switch.

If you want any changes that have been made to the Invocation and Example Utterances properties that are defined on the Digital Assistant tab of the skill's Settings page to be propagated to the digital assistant, leave this switch in the ON position.

These values are used in the help card for the skill in the digital assistant.
Click Update Skill.

Extend a Skill in an Extended Digital Assistant

If you have extended a digital assistant want to replace one of its base skills with an extended version of that skill, you need to follow these general steps:

Extend the skill and make the desired customizations to it.
Train the skill.
(A skill needs to be trained before it can be published.)
In the digital assistant, update the version of the skill that it uses by doing the following:
1. Click to open the side menu, and select Development > Digital Assistants.
2. Click the tile for the digital assistant to open it.
3. On the Skills tab of the digital assistant, select the skill that you have extended. This skill should have the badge.
4. Click Update Skill.
5. From the New Skill Version dropdown, select the extended version of the skill and click Update Skill.
Once you have tested the digital assistant with the new version of the skill and are satisified with its behavior, publish the skill.

Make, Review, and Revert Customizations

You can add to or customize an extended bot (skill or digital assistant) by using any of its enabled controls and editable fields.

You can review customizations made in a bot by clicking the icon that appears next to the field that has been customized. (For an intent's example utterances, you need to mouse over the icon next to the utterance to display the icon.

When you click this icon, the Review Customization dialog appears, which enables you to compare the current value of the field with the base value. If you want to revert to the value in the base bot, click Revert to Original.

Testing Customizations

You can use the Test Cases feature to ensure that any modifications that you have made in your extensions have not broken any of the bot's basic functions.

You can create the tests by recording conversations in the tester. In addition, some skills and digital assistants in the Skill Store come with test cases, which you can run on your extensions to make sure that you haven't broken any of the functionality.

See Test Suites and Test Cases for details on creating and using test cases.

Rebasing

If a new base version of a bot that you have extended is made available, you can rebase the extended bot so that it picks up the changes to the base bot and keeps the customizations that you made in the extended bot. Rebasing is available for both skills and digital assistants.

You can also rebase to any version of the bot that descends from the original bot, whether it is a version of the original bot or an extended version of the bot. (This does not apply to clones or bots that are created separately but with the same name.)

How Rebasing Works

When you rebase, the following things happen in the extended bot:

A new version of the extension is created.
Any new artifacts (such as new intents) in the new version of the base bot (i.e. those that were added after the extension was created or last rebased) are added to the extension.
Any local artifacts (those that were created in the extension) are retained in the extension.
Any customizations of artifacts (such as changes of property values) are retained.
Note

Customized property values always take precedence over changes in the base bot. If you want to use the values from the new base, you can revert changes once the rebase process is complete.
Any inherited artifacts that are included in the current version of the base bot that have not been customized and that have been removed from the new version of the base bot are deleted.
Customized artifacts that no longer exist in the new base bot are included in the rebased extension. In the extension, they are treated as local artifacts, so you can delete them if they are no-longer needed.

Caution:

If both the new version of the base bot and the extension have a new artifact with the same key (usually the name), the rebasing will not be able to resolve the two and thus will fail. In this case, you would need to delete the local version of the artifact before being able to successfully rebase.

Rebase a Skill Extension

If you haven't already done so, install the updated skill:
1. Click to open the side menu and select Development > Store.
2. In the tile for the updated base skill, click and select Pull.
Click to open the side menu, select Development > Skills, and click the tile for the extended version of the skill to open it.
In the left navigation for the skill, click .
Click the Rebase button.
In the Base Skill dropdown, select the skill version you are rebasing to and click Next.
Complete the wizard.

If the rebase is successful, the new rebased version of the skill is created and opened in Draft mode.

If the rebase isn't successful, an error message appears indicating what has blocked the successful rebase and a new version of the extended skill is not created.

Rebase a Digital Assistant Extension

If you haven't already done so, install the updated digital assistant:
1. Click to open the side menu and select Development > Store.
2. In the tile for the updated base digital assistant, click and select Pull.
Click to open the side menu, select Development > Digital Assistants, and click the tile for the extended version of the digital assistant to open it.
In the left navigation for the digital assistant, click .
Click the Rebase button.
In the Base Digital Assistant dropdown, select the skill version you are rebasing to and click Next.
Complete the wizard.

If the rebase is successful, the new rebased version of the digital assistant is created and opened in Draft mode.

If the rebase isn't successful, an error message appears indicating what has blocked the successful rebase and a new version of the extended digital assistant is not created.

How Do I Respond to a Failed Rebase?

If a rebase of a skill or digital assistant fails, here are the steps to re-attempt the rebase:

Create a new version of the bot extension.
Make changes to the extension to address errors in the rebase attempt. This may simply mean reverting any customizations that have conflicted with changes in the base bot.
Attempt to rebase the version of the extension.

Branching an Extension

It is also possible to create a clone of an extension so that you can work on different branches in parallel. For example, you might do this when you have an extended bot in production but you want to have a differently named extension where you are working on significant changes.

When you clone an extension, the extended bot is also treated as an extension of the original bot, meaning that:

At design time, the various artifacts are marked as inherited, local, and customized, just like they are in other extended bots.
You can rebase to new versions of the original bot.
The internal tracking IDs that are generated for the clone of the extension match those of the original bot.

Note

Cloning works with bot extension only if you first create an extended bot.

Post-Deployment Lifecycle of an Extended Skill

Once you have deployed an extended version of a skill, it's important to establish a routine for incorporating improvements and then redeploying.

Here's an example of what such a routine might look like, based on the following assumptions:

You are using Insights on an ongoing basis to improve intent resolution in the skill.
You periodically add new features to the skill.
You have two instances of Digital Assistant (one for production and one for testing and staging).

In your production instance, create a new version of the deployed skill.
You create a new version of the skill in your production instance so that you can capture Insights data from actual customer usage and then use the Retrainer to supplement your training model with utterances that the skill did not correctly understand before.

To make this procedure easier to read, let's assume the the published skill is version v1 and the new draft version is v1.1.
Evaluate the Insights reports on the skill and supplement the training data for your intents with additional utterances to handle valid user phrasing that was not taken into account in your previous training data.
As part of this process, you can use the Insights Retrainer to add unresolved utterances to the appropriate intents.
Export the skill (v1.1 in the example above).
In your test or staging instance, import the skill you just exported from the production instance (v1.1).
In the test or staging instance, create a new version of the imported skill. This new version will be for incorporating any new features that you are adding to the skill. (Let's refer to this version as v2.)
In v2, incorporate any feature additions or changes that you want to include.
If you have been developing those changes elsewhere, manually merge them into v2.
Train and test v2 until you are satisfied with the results.
Export the skill (v2) from your test instance.
In your production instance, import the skill that you have just trained and tested (v2).
Train the skill.
Publish the skill.
If you are deploying the skill as part of a digital assistant, create a new version of the digital assistant.
Update the new version of the digital assistant to use the new version of the skill (v2).
Update the channel to use the new version of the digital assistant.
Publish the new version of the digital assistant.

Oracle Cloud Infrastructure Documentation