article by Frank Nimphius, October 2019
As of Oracle Digital Assistant 19.4.1, the local deployment of custom components has changed to the point that custom component tar balls (".tgz" files) must now contain all node module dependencies. This change addresses the new Acceptable Use of the Public Registry announcement by NPM , Inc.
The blog article referenced in this post explains everything you need to know about this deployment change and provides guidance on what to do or not to do.
What Has Changed
In previous versions of Oracle Digital Assistant, deployment packages contained only the custom component service sources and the package.json file that lists the node module dependencies. During deployment, the Oracle Digital Assistant skill then called 'npm install' on the package to install dependent Node modules from the Internet. With the new deployment model in Oracle Digital Assistant 19.4.1 and later, the dependent Node modules must be deployed with the custom components.
What You Need to Know: Creating New Custom Component Packages
In version 2.2.2 of its Oracle Bots Node SDK ( https://github.com/oracle/bots-node-sdk), Oracle has changed the deployment to include dependent Node modules in the deployable package. The Oracle Bots Node SDK is the recommended option for you to build and deploy custom components, as well as webhook clients.
To create and deploy custom components, you
- (One time) Install the Bots Oracle Node SDK using NPM:
npm install -g @oracle/bots-node-sdk (Windows)
sudo npm install -g @oracle/bots-node-sdk (MAC)
- Create new custom component projects
cd into the component folder
bots-node-sdk init
- Package the custom component service for local container deployment (if it should be deployed to local container)
bots-node-sdk pack
What exactly has changed:
The Oracle Bots Node SDK version 2.2 .2 has a changed behavior for the "bots-node-sdk" pack command that adds the following entry to the package.json file before deployment
"bundledDependencies": [
"dependent module 1","dependent module 2","dependent module 3", " … "
]
It then calls npm pack to create the ".tgz" file. Because of the change in the package.json file, the "tgz" file now will contain all dependent node modules you configured through calling "npm install <node module name> when building the custom component.
Backward Compatibility
The change in the custom component deployment is not backward compatible, which means that for exiting custom component packages, you need to apply the changes before re-deploying your custom components. Custom components that are already deployed to Oracle Digital Assistant continue working after the bot platform is upgraded to 19.4.1.
How to update existing custom component packages
- To update existing custom component services, ensure you have the latest version of Oracle Bots Node SDK installed. The version you need is at least "2.2". To check the version of your Oracle Bots Node SDK, type
bots-node-sdk -v
on a command line or in a terminal window. This command assumes you have Oracle Bots Node SDK installed with the global flag (-g) applied.
- To update the tgz deployment file, "cd" into the custom component services folder and type
bots-node-sdk pack
Note: Use bots-node-sdk pack from here on and never use npm pack directly
What About Deployed Custom Components?
Custom components that are deployed to skills when your Cloud instance gets updated to 19.4.1 should be okay as Oracle Digital Assistant will take care of the dependencies.
IMPORTANT NOTICE: When the custom component package is updated during the 19.4.1 upgrade, the corresponding skill version will get a new timestamp. This does not affect the active channel or DA routing, but you should pay extra attention when selecting the skill version you want to edit as it may not be the latest. Digital Assistant also may display an alert that there exists a newer version of a skill after the upgrade.
If you have deployed custom components to a skill that then you exported, importing this skill back into Oracle Digital Assistant 19.4.1 or later will cause a deployment failure for the custom component. In that case, just create a new deployment package for your custom component service and upload it to the skill. So only skill at rest that you reactivate by deploying it to Oracle Digital Assistant requires a second import step, which is to replace the custom component .tgz file.
What If I No Longer Have the Custom Component Sources?
If you no longer have the custom component sources, or never owned them, then still you can upgrade the custom component package to include all dependent node modules.
All you need to do is to download the existing package ('.tgz' file) from the link you see in the skill's custom component service configuration. Then unzip the ".tgz" file on your local computer. Ensure you have NPM (Node Package manager) and the Oracle Bots Node SDK installed globally and navigate into the extracted "package" folder.
Ensure you have access to the Internet and then, on a command line or in a terminal window, issue
- npm install
- bots-node-sdk pack
The first command downloads the dependent node modules listed in the package.json file to your local machine. The second then creates the new deployment package with all the dependent modules. In a final step, you upload the newly created .tgz file to the skill's custom component configuration using the "change" link.
Trouble Shooting
If you missed this tip, then the problem sown in the sample image below may occur when deploying your custom component services to Oracle Digital Assistant 19.4.1 or later. The change not only affects the redeployment of custom component services, but existing skills as well that uses locally deployed custom component services (using the old package format) if you clone or create a new version in Oracle Digital Assistant 19.1.4.
The exception …
Error Message: failed to start service built: Invalid component path: /runner_custom_components/DF2A59A1-8EC5-4B3C-BCA8-0C351EF43E3A_24/cc_package/banking/balance_retrieval.js
RUNNER_FAIL_SERVICE_START: failed to start service built: Invalid component path: /runner_custom_components/DF2A59A1-8EC5-4B3C-BCA8-0C351EF43E3A_24/cc_package/banking/balance_retrieval.js
usually happens when a custom component service contains an invalid JavaScript (Node) file or if required Node module dependencies are missing. Because existing custom components don't have Node modules as part of the ".tgz" file, this error will show.
Related Content
TechExchange Quick-Tip: Customizing the Oracle Bots Node.js SDK Component Template
