If you want to host the custom component package from Oracle Digital Assistant as an embedded component service, you must first pack the custom components into a TGZ file. Then, when you create the embedded component service, you upload this file.

This TGZ file, which you package using bots-node-sdk pack, must contain the assets and structure described in Implement Custom Components. It also must contain all the node modules that it depends on (the bots-node-sdk pack does that for you).

To prepare a package for uploading to the embedded container service:

1. Ensure that you have the latest version of the Bots Node.js command line tools.

   The embedded container requires that the TGZ file includes all dependencies. Earlier versions did not bundle the dependencies into the file. Now, the command that you'll use to create the TGZ file ensures that your package.json file contains a bundledDependencies node that lists all the dependent modules that need to be included in the TGZ file.

2. In the directory that contains the main.js file, run the following command for each of the modules that your package depends on. You don't need to do this for devDependencies, such as the Bots Node SDK.

   This command adds the module to the node_modules folder and adds it as a dependency in package.json.

   npm install <module>

   If your package.json already names all the dependencies, then you can run npm install instead.

3. Ensure that the top-level folder contains an .npmignore file that has a *.tgz entry. For example:

   *.tgz
   spec
   service-*

   Otherwise, when you pack the files into a TGZ file, you include the TGZ file that already exists in the top-level folder, and your TGZ file will double in size. After you pack the files a few times, the TGZ file will be to large to upload into the container.

4. Run this command:

   bots-node-sdk pack

   This command validates the component package, updates it to include devDependencies if necessary, and then creates a TGZ file, which you'll upload when you create an embedded component service from the skill’s Components tab. Note that the files you've listed as dependencies are included as bundledDependencies, with the exception of the Bots Node SDK and Express, which are devDependencies.

Your package should be compatible with Node 14.17.0.

For more information about the pack command, see https://github.com/oracle/bots-node-sdk/blob/master/bin/CLI.md.

After you pack a custom component package into a TGZ file, you can upload it to create an embedded component service from the skill's Components tab.

To learn how to create the TGZ file, see Prepare the Package for an Embedded Container Service.

To create the embedded component service:

1. From the skill, click Components .

2. Click .

3. Select Embedded Container.

4. Click Upload a component package file and point to the TGZ file to upload, or drag the file to the Package File box.

5. (Optional) If you want to send custom component context.logger() statements to the service's log, then switch Enable Component Logging to On. This switch is available only in instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).

   You can see the log from the Components tab by clicking Diagnostics > View Logs.

   Note
   
   The skill keeps a log entry for two days. When you delete an embedded custom component service, the skill's log entries for that service are deleted.

6. Click Create.

   Digital Assistant uploads the TGZ file and creates the embedded component service. During the upload, Digital Assistant verifies that the package is valid, and can reject the package for the reasons that are described later in this section.

   After you upload the TGZ file, the custom component service is built and its components are deployed. If the Components page displays an awaiting deployment message after you upload the TGZ file, it means that the service has been created, but is not yet available. When the service becomes available, the deployment metadata displays in place of the awaiting deployment message.

7. Ensure that Service Enabled is switched to On.

During the upload, Digital Assistant might reject the package. Here are reasons for rejection and ways to resolve the issues.

• JavaScript contains syntax errors: If a component's JavaScript has syntax errors, then that component is not added to the container, which results in this error message:

  Error Message: failed to start service built: Invalid component
        path:

  View the component files in an editor that detects syntax errors. Also, try hosting the package on a local server that sends error messages to a console log.

  Another reason for this message might be that the package doesn't contain all the node module dependencies. See the next item in this list.

• Missing node modules: If the package doesn't contain all the node module dependencies, then you'll get the same error message as above:

  Error Message: failed to start service built: Invalid component
        path:

  To learn how to include node module dependencies, see Prepare the Package for an Embedded Container Service.

• Component name is too long: If a component name has more than 100 characters, begins with System., or contains other than alphanumeric characters and underscores, then the service creation fails.

  Change the name in the component's JavaScript, repackage, and upload again.

• Exceeded component service limit: If your instance already has the maximum number of embedded custom component services, then the service creation fails. Ask your service administrator for the embedded-custom-component-service-count limit as described in View Service Limits in the Infrastructure Console.

  If you need to raise the limit, you can request an increase. See Requesting a Service Limit Increase.

• TGZ file is too large: This typically happens when the .npmignore file doesn't contain a *.tgz entry and therefore, every time you pack the files, a nested copy of the existing TGZ is added.

  When the top-level folder contains an .npmignore file with *.tgz, the previous version of the TGZ file isn't included when you update the package.

If you want to send custom component context.logger() statements to the service's log, then switch Enable Component Logging to On. This switch is available only in instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).

When Enable Component Logging is switched to On, you can click the Diagnostics button for the service to access view logs and crash reports to diagnose the problem.

• Select View Logs to view messages that the custom component sends to context.logger(). This feature is available only in instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). The Enable Component Logging switch must be On for the log to contain these messages.
• Select View Crash Report to view details about what may have caused the container to crash.

After you create the service, you can invoke the custom components from your dialog flow as described in Custom Components.