Use the SDK's CLI init component command to create a JavaScript or TypeScript file with the framework for working with the Oracle Digital Assistant Node.js SDK to write a custom component. The language that you specified when you ran the init command to create the component package determines whether a JavaScript or a TypeScript file is created.

bots-node-sdk init component <component name> c components

Your custom component must export two objects:

• metadata: This provides the following component information to the skill.

  • Component name

  • Supported properties

  • Supported transition actions

  For YAML-based dialog flows, the custom component supports the following properties by default. These properties aren't available for skills designed in Visual dialog mode.

  • autoNumberPostbackActions: Boolean. Not required. When true, buttons and list options are numbered automatically. The default is false. See Auto-Numbering for Text-Only Channels.

  • insightsEndConversation: Boolean. Not required. When true, the session stops recording the conversation for insights reporting. The default is false. See Model the Dialog Flow.

  • insightsInclude: Boolean. Not required. When true, the state is included in insights reporting. The default is true. See Model the Dialog Flow.

  • translate: Boolean. Not required. When true, autotranslation is enabled for this component. The default is the value of the autotranslation context variable. See Translation Services in Skills.

• invoke: This contains the logic to execute. In this method, you can read and write skill context variables, create conversation messages, set state transitions, make REST calls, and more. Typically, you would use the async keyword with this function to handle promises. The invoke function takes the following argument:

  • context, which names the reference to the CustomComponentContext object in the Digital Assistant Node.js SDK. This class is described in the SDK documentation at https://oracle.github.io/bots-node-sdk/. In earlier versions of the SDK, the name was conversation. You can use either name.
  Note
  
  If you are using a JavaScript library that doesn't support promises (and thus aren't using async keyword), it is also possible to add a done argument as a callback that the component invokes when it has finished processing.

Here’s an example:

'use strict';

module.exports = {

  metadata: {
    name: 'helloWorld',
    properties: {
      human: { required: true, type: 'string' }
    },
    supportedActions: ['weekday', 'weekend']
  },

  invoke: async(context) => {
    // Retrieve the value of the 'human' component property.
    const { human } = context.properties();
    // determine date
    const now = new Date();
    const dayOfWeek = now.toLocaleDateString('en-US', { weekday: 'long' });
    const isWeekend = [0, 6].indexOf(now.getDay()) > -1;
    // Send two messages, and transition based on the day of the week
    context.reply(`Greetings ${human}`)
      .reply(`Today is ${now.toLocaleDateString()}, a ${dayOfWeek}`)
      .transition(isWeekend ? 'weekend' : 'weekday');   
  }
}

To learn more and explore some code examples, see Writing Custom Components in the Bots Node SDK documentation.

You use different combinations of the Bots Node SDK keepTurn and transition functions to define how the custom component interacts with a user and how the conversation continues after the component returns flow control to the skill.

• keepTurn(boolean) specifies whether the conversation should transition to another state without first prompting for user input.

  Note that if you want to set keepTurn to true, you should call keepTurn after you call reply because reply implicitly sets keepTurn to false.

• transition(action) causes the dialog to transition to the next state after all replies, if any, are sent. The optional action argument names that action (outcome) that the component returns.

  If you don't call transition(), the response is sent but the dialog stays in the state and subsequent user input comes back to this component. That is, invoke() is called again.

invoke: async (context) ==> {
   ...
   context.reply(payload);
   context.keepTurn(true);
   context.transition ("success"); 
}

Here are some common use cases where you would use keepTurn and transition to control the dialog flow:

invoke: async (context) => {
    const listVariableName = context.properties().variableName;
    ...
    // Write list of options to a context variable
    context.variable(listVariableName, list);
   // Navigate to next state without 
   // first prompting for user interaction.
   context.keepTurn(true);
   context.transition();
 }

context.keepTurn(false);
context.transition("success");

  invoke: async (context) => {
    // Perform conversation tasks.
    const tracking_token = "a2VlcHR1cm4gZXhhbXBsZQ==";    
    const quotes = require("./json/Quotes.json");
    const quote = quotes[Math.floor(Math.random() * quotes.length)];
    
    // Check if postback action is issued. If postback action is issued, 
    // check if postback is from this component rendering. This ensures
    // that the component only responds to its own postback actions.     
    if (context.postback() && context.postback().token == tracking_token && context.postback().isNo) {
      context.keepTurn(true);
      context.transition();
    } else {
      // Show the quote of the day.
      context.reply("'" + quote.quote + "'");
      context.reply(" Quote by: " + quote.origin);
      // Create a single message with two buttons to 
      // request another quote or not.
      const mf = context.getMessageFactory();
      const message = mf.createTextMessage('Do you want another quote?')
        .addAction(mf.createPostbackAction('Yes', { isNo: false, token: tracking_token }))
        .addAction(mf.createPostbackAction('No', { isNo: true, token: tracking_token })); 
      context.reply(message);
      // Although reply() automatically sets keepTurn to false, 
      // it's good practice to explicitly set it so that it's
      // easier to see how you intend the component to behave.
      context.keepTurn(false);
    };
  }

invoke: async (context) => {

  const quotes = require("./json/Quotes.json");
  const quote = quotes[Math.floor(Math.random() * quotes.length)];
  
  // Check if postback action is issued and postback is from this component rendering. 
  // This ensures that the component only responds to its own postback actions.     
  const um = context.getUserMessage()
  if (um instanceof PostbackMessage && um.getPostback() && um.getPostback()['system.state'] === context.getRequest().state && um.getPostback().isNo) {
    context.keepTurn(true);
    context.transition();
  } else {
    // Show the quote of the day.
    context.reply(`'${quote.quote}'`);
    context.reply(`Quote by: ${quote.origin}`);
    // Create a single message with two buttons to request another quote or not.
    let actions = [];

    const mf = context.getMessageFactory();
    const message = mf.createTextMessage('Do you want another quote?')
      .addAction(mf.createPostbackAction('Yes', { isNo: false }))
      .addAction(mf.createPostbackAction('No', { isNo: true }));
    context.reply(message);
    // Although reply() automatically sets keepTurn to false, it's good practice to explicitly set it so that it's
    // easier to see how you intend the component to behave.
    context.keepTurn(false);
  }
}

You use CustomComponentContext instance methods to get the context for the invocation, access and change variables, and send results back to the dialog engine.

You can find several code examples for using these methods in Writing Custom Components and Conversation Messaging in the Bots Node SDK documentation

The SDK reference documentation is at https://github.com/oracle/bots-node-sdk.

When you design a custom component, you should consider whether the component will be used by a skill that supports more than one language.

If the custom component must support multi-language skills, then you need to know if the skills are configured for native language support or translation service.

When you use a translation service, you can translate the text from the skill. You have these options:

• Set the translate property in the custom component's state to true to translate the component's reply, as described in Send Responses Directly to the Translation Service.

• Send raw data back to the skill in context variables and use the variables' values in a system component that composes the output. Set that component's translate property to true. See Use a System Component to Pass the Message to the Translation Service.

• Send raw data back to the skill in context variables and use the variables' values in a system component that uses the resource bundle key for the language. See Use a System Component to Reference a Resource Bundle.

For native language skills, you have these options:

• Pass the data back to the skill in context variables and then output the text from a system component by passing the variables' values to a resource bundle key, as described in Use a System Component to Reference a Resource Bundle. With this option, the custom component must have metadata properties for the skill to pass the names of the context variables to store the data in.

• Use the resource bundle from the custom component to compose the custom component's reply, as described in Reference Resource Bundles from the Custom Component. You use the conversation.translate() method to get the resource bundle string to use for your call to context.reply(). This option is only valid for resource bundle definitions that use positional (numbered) parameters. It doesn't work for named parameters. With this option, the custom component must have a metadata property for name of the resource bundle key, and the named resource bundle key's parameters must match those used in the call to context.reply().

Here's an example of using the resource bundle from the custom component. In this example, fmTemplate would be set to something like ${rb('date.dayOfWeekMessage', 'lundi', '19 juillet 2021')}.

'use strict';

var IntlPolyfill    = require('intl');
Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;

module.exports = {
  metadata: () => ({
    name: 'Date.DayOfWeek',
    properties: {
      rbKey:   { required: true,  type: 'string'    }
    },
    supportedActions: []
  }),
  invoke: (context, done) => {
    const { rbKey } = context.properties();
    if (!rbKey || rbKey.startsWith('${')){
      context.transition();
            done(new Error('The state is missing the rbKey property or it uses an invalid expression to pass the value.'));
    }
    //detect user locale. If not set, define a default
    const locale  = context.getVariable('profile.locale') ? 
      context.getVariable('profile.locale') : 'en-AU';  
    const jsLocale     = locale.replace('_','-');
    //when profile languageTag is set, use it. If not, use profile.locale
    const languageTag = context.getVariable('profile.languageTag')?
                      context.getVariable('profile.languageTag') : jslocale;
   /* =============================================================
      Determine the current date in local format and 
      the day name for the locale
      ============================================================= */
    var now          = new Date();
    var dayTemplate  = new Intl.DateTimeFormat(languageTag,
      { weekday: 'long' });
    var dayOfWeek    = dayTemplate.format(now);
    var dateTemplate = new Intl.DateTimeFormat(languageTag, 
      { year: 'numeric', month: 'long', day: 'numeric'});
    var dateToday    = dateTemplate.format(now);

   /* =============================================================
      Use the context.translate() method to create the ${Freemarker} 
      template that's evaluated when the reply() is flushed to the 
      client.
      ============================================================= */
    const fmTemplate = context.translate(rbKey, dateToday, dayOfWeek );

    context.reply(fmTemplate)
                .transition()
                .logger().info('INFO : Generated FreeMarker => ' 
                + fmTemplate);
    done();  
  }
};

In a digital assistant conversation, a user can break a conversation flow by changing the subject. For example, if a user starts a flow to make a purchase, they might interrupt that flow to ask how much credit they have on a gift card. We call this a non sequitur. To enable the digital assistant to identify and handle non sequiturs, call the context.invalidInput(payload) method when a user utterance response is not understood in the context of the component.

In a digital conversation, the runtime determines if an invalid input is a non sequitur by searching for response matches in all skills. If it finds matches, it reroutes the flow. If not, it displays the message, if provided, prompts the user for input, and then executes the component again. The new input is passed to the component in the text property.

In a standalone skill conversation, the runtime displays the message, if provided, prompts the user for input, and then executes the component again. The new input is passed to the component in the text property.

This example code calls context.invalidInput(payload) whenever the input doesn’t convert to a number.

"use strict"
 
module.exports = {
 
    metadata: () => ({
        "name": "AgeChecker",
        "properties": {
            "minAge": { "type": "integer", "required": true }
        },
        "supportedActions": [
            "allow",
            "block",
            "unsupportedPayload"
        ]
    }),
 
    invoke: (context, done) => {
        // Parse a number out of the incoming message
        const text = context.text();
        var age = 0;
        if (text){
          const matches = text.match(/\d+/);
          if (matches) {
              age = matches[0];
          } else {
              context.invalidUserInput("Age input not understood. Please try again");
              done();
              return;
          }
        } else {
          context.transition('unsupportedPayload");
          done();
          return;
        }
 
        context.logger().info('AgeChecker: using age=' + age);
 
        // Set action based on age check
        let minAge = context.properties().minAge || 18;
        context.transition( age >= minAge ? 'allow' : 'block' );
 
        done();
    }
};

Here’s an example of how a digital assistant handles invalid input at runtime. For the first age response (twentyfive), there are no matches in any skills registered with the digital assistant so the conversation displays the specified context.invalidUserInput message. In the second age response (send money), the digital assistant finds a match so it asks if it should reroute to that flow.

You should call either context.invalidInput() or context.transition(). If you call both operations, ensure that the system.invalidUserInput variable is still set if any additional message is sent. Also note that user input components such as System.CommonResponse, System.Text, System.List, and System.ResolveEntities reset system.invalidUserInput.

Say, for example, that we modify the AgeChecker component as shown below, and call context.transition() after context.invalidInput().

if (matches) {  age = matches[0]; } else { 
      context.invalidUserInput("Age input not understood. Please try again"); 
      context.transition("invalid"); 
      context.keepTurn(true);
      done();
      return;
}

In this case, the data flow needs to transition back to askage so that the user gets two output messages – "Age input not understood. Please try again" followed by "How old are you?".

  askage:
    component: "System.Output"
    properties:
      text: "How old are you?"
    transitions:
      next: "checkage"
  checkage:
    component: "AgeChecker"
    properties:
      minAge: 18
    transitions:
      actions:
        allow: "crust"
        block: "underage"
        invalid: "askage"

Before you can deploy custom components to Oracle Cloud Infrastructure Functions, you need to obtain the names of the artifacts that are used for deployment, and you need to verify that you have permission to use them.

To set up your instance for Oracle Cloud Infrastructure Functions deployment, your tenancy administrator completed the steps in Setup and Policies for Oracle Functions. As part of the process, they created the following artifacts. Ask your administrator for their names, which you'll need when you complete the steps in Set Up Your User Account for Oracle Functions:

• The names of the region and compartment to use for your functions.

• The name of the compartment for the function application's virtual network (VCN). Typically, this is the same compartment as the one used for functions.

• The name of the VCN to use for the function application.

Also, ask your administrator to verify that you belong to a group that has the necessary permissions for function developers, which includes access to these artifacts.

Before you can deploy custom component packages to Oracle Cloud Infrastructure Functions, you must complete these steps in the Oracle Cloud Infrastructure Console:

1. Sign into the Console and, in the top bar, select the region that the function-development compartment is in.

2. You'll deploy to Oracle Cloud Infrastructure Functions through the Oracle Cloud Infrastructure Registry. If you don't already have a registry repository that you can use, then do the following to create one.

   1. Click on the top left to open the navigation menu, click Developer Services, click Container Registry, and then, in the List Scope section, select the compartment that's been set up for function development.

   2. Click Create Repository.

   3. Give the repository a name, and then click Create Repository.

3. If you don't have a functions application for your custom component packages, you'll need to create one. From the Developer Services page, click Functions, and then click Create Application. Provide a name, select a VCN, select at least one subnet, and click Create.

   If you don't see any VCNs to choose from, you might not be in the correct region.

   There are limits to the number of applications and functions. For the default limits, see Functions Limits in Oracle Cloud Infrastructure Documentation .

4. On the Applications page, click the application that you use for function deployment, click Getting Started in the Resources section, and then click Local Setup.

   As shown in the following screenshot, the page displays several commands that you'll need to use to set up your local computer and to deploy your custom component package. Copy and save the commands for steps 3 through 7.

   You'll use these later after you've installed the required software on your local machine and are ready to deploy your custom components. Alternatively, bookmark this page so that you can return to it when you need to use the commands.

   Don't run these commands now. Just copy them.

   
   
   
   

5. In your copied command that looks similar to the following, change [OCIR-REPO] to the name of your registry repository.

   fn update context registry phx.ocir.io/devdigital/[OCIR-REPO]

6. Click the Profile icon in the top-right corner, and then click User Settings to go to the User Details page.

7. In the next step you'll create a PEM file that you need to store in a .oci folder on your local machine. If your home folder on your local machine doesn't have this directory, create one from a terminal window.

   • Linux and Mac:

     cd ~
     mkdir .oci

   • Windows:

     cd C:\Users\<your-user-name>
     mkdir .oci

8. You need a public and private PEM file for secure access. If you haven't set one up for your user account yet, then, from User Details in the Console, click API Keys from the Resources section, and then click Add API Key.

   Save the private key file (the PEM file) to the .oci directory in your home folder.

9. Make a note of the Fingerprint that's associated with the API key. When you have multiple API keys, you must know which fingerprint to use for each private PEM file.

10. If you haven't already set up a config file for the fingerprint on your local machine, then, from the API Keys section, do these steps:

    1. Click in the row for your API key's fingerprint and then click View Configuration file.

    2. Copy the Configuration File Preview content.

    3. In the .oci folder on your local machine (the same folder that you saved your private key file in), create a file named config and paste the copied contents into the file.

11. In the config file, change the key_file property to point to the location of your private PEM file. For example: key_file=/home/joe/.oci/my-private.pem

12. If you don't have an auth token, click Auth Tokens in the Resources menu, and then click Generate Token. Copy the auth token immediately to a secure location from where you can retrieve it later because you won't see the auth token again in the console. You use the auth token as a password when you sign in to push your custom component package to the Oracle Infrastructure registry for deployment.

You'll need to install cURL, the OCI command line interface (CLI), Fn, and Docker on your local machine to enable deployment to Oracle Cloud Infrastructure Functions. If your machine runs on Windows, then you must do one of the following options to use Fn:

• Install Fn and Docker on Linux in an Oracle VM VirtualBox by following the steps in this topic.

• Install Docker and Fn on Windows, and then install the Linux subsystem for Windows as described in How-to: Run Fn client on Windows and connect to a remote Fn server.

• Deploy your custom components from Cloud Shell. See Cloud Shell in Oracle Cloud Infrastructure Documentation.

To set up your local machine:

1. (Windows on VM only) If you want to use a Linux guest on Oracle VM VirtualBox to deploy your custom component package to Oracle Cloud Infrastructure Functions, follow these steps:

   1. Install VirtualBox from https://www.virtualbox.org/.

   2. Download a Linux ISO. For example, to get the ISO for Ubuntu-Mate, go to https://ubuntu-mate.org/download/ and click 64-bit PCs/Macs.

   3. In VirtualBox, create a virtual machine from the ISO. You can find instructions for creating a Ubunto-Mate virtual machine at https://itsfoss.com/install-linux-in-virtualbox/. This will be your Linux guest.

   4. Start the Linux guest.

   5. From a terminal window, run this command:

      sudo apt-get update

      This updates the package lists for new packages and packages that need upgrading.

      Tip:

      To open a terminal window in Ubuntu, press Ctrl-Alt-T.

   6. To be able to do things like copy and paste in a terminal window, you'll need the guest additions. Download http://download.virtualbox.org/virtualbox/<release>/VBoxGuestAdditions_<release>.iso and install and configure the additions using the instructions at https://itsfoss.com/virtualbox-guest-additions-ubuntu/

      Be sure to configure configured Devices > Drag and Drop to bidirectional.

   7. Enter this command in a terminal window to install node.js and npm on the guest.

      sudo apt install npm

   8. Drag the .oci folder in your home directory on your local machine into the home folder on the Linux guest.

      Because it's a hidden file, you must press Ctrl-H or select View > Show Hidden Files in the home folder to see it.

   9. From the .oci folder on the Linux guest, open the config file and change key_file to point to the location of the file in your Linux guest. For example: key_file=/home/joe/.oci/my-private.pem

   10. Complete the remaining steps in this topic from the Linux guest.

2. (Mac only) If you haven't already, install Homebrew to enable you to install cURL, OCI CLI, and Fn. See https://docs.brew.sh/Installation. Alternatively, you can use the equivalent MacPorts commands.

3. If your Internet access is through a VPN, then you might need to set up proxies. For example:

   export http-proxy = http://<external_ip>:80
   export https-proxy = http://<external_ip>:80
   export no_proxy = localhost,127.0.0.1,<list>
   export noproxy = localhost,127.0.0.1,<list>
   export no_proxy = localhost,127.0.0.1,<list>
   # Example for apt
   nano /etc/apt/apt.conf
   Acquire::http::Proxy "http://<external_ip>:80";
   Acquire::https::Proxy "http://<external_ip>:80";

4. Run the appropriate command to bring the packages up to date.

   • Linux:

     sudo apt update && sudo apt upgrade

   • Mac:

     brew update && brew upgrade

5. (Linux only) You'll use cURL to install OCI and Fn. Enter this commeand in a terminal window. The last statement is to verify that it installed successfully.

   sudo apt install curl
   curl --version

6. Fn uses the OCI CLI to deploy the custom components to Oracle Cloud Infrastructure Functions. Run the appropriate command to install the CLI, and accept all defaults.

   • Linux:

     bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

   • Mac:

     brew update && brew install oci-cli

   • Windows (if using Linux subsystem on Windows): Follow the Windows steps in Quickstart in Oracle Cloud Infrastructure Documentation.

7. In Set Up Your User Account for Oracle Functions, you created a config file. You now need to configure the CLI to use that file. Open a new terminal window, run this command, provide the location of your config file, and then enter n for the remaining questions (your config file already has the necessary settings).

   oci setup config

   For example:

   $ oci setup config
       This command provides a walkthrough of creating a valid CLI config file.
       ...
   
   Enter a location for your config [/home/joe/.oci/config]:
   Config file: /home/joe/.oci/config already exists. Do you want add a profile here? (If no, you will be prompted to overwrite the file) [Y/n]: n
   File: /home/joe/.oci/config already exists. Do you want to overwrite (Removes existing profiles!!!)? [y/N]: n

8. You need Docker 17.10.0-ce or later to push the custom component package to the registry.

   • For Ubuntu, the installation instructions are at https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

   • For Mac, the installation instructions are at https://docs.docker.com/docker-for-mac/install/

   See https://docs.docker.com/engine/install/linux-postinstall/ if you don’t want to preface the docker command with sudo.

9. If you are using VPN, then follow the instructions at https://docs.docker.com/network/proxy/

   If you are using Linux subsystem on Windows, you can set the proxies from Resources page in the Docker Desktop Settings.

10. Ensure that Docker is running. You can't start Fn, which you install next, if Docker isn't running.

11. You'll use Fn, which is a lightweight Docker-based serverless-functions platform, to configure the context and deploy the package. If you haven't installed it already, follow the instructions for installing Fn, starting the Fn server, and testing the installation at https://fnproject.io/tutorials/install/

    You don't need to configure the context or set the registry at this time. You'll do this when you complete the steps in Deploy the Custom Components to Oracle Cloud Infrastructure Functions.

Before you can deploy a custom component package to Oracle Cloud Infrastructure Functions, you'll need to add func.js and func.yaml files, add a developer dependency for the fnproject FDK, and install the FDK.

1. If you used the bots-node-sdk init command to create your custom component package, it may have created a file named Dockerfile in the top folder. If so, you must delete it. Otherwise, your deployment will fail.

2. In the top folder for your custom component package (the folder that contains main.js), create a file named func.js, and then add the following code. This is the file that Oracle Cloud Infrastructure Functions will invoke.

   /***
    
     This function handles an invocation that sets the "Oracle-Bots-Fn-Path" header to determine which component to invoke or if metadata should be returned.
    
   ***/
    
   const fdk = require('@fnproject/fdk');
   const OracleBotLib = require('@oracle/bots-node-sdk/lib');
   const path = require("path");
    
   const BOTS_FN_PATH_HEADER = "Oracle-Bots-Fn-Path";
   const METADATA_PATH = "metadata";
   const COMPONENT_PREFIX = "components/";
    
   let shell;
   let componentsRegistry;
    
   const getComponentsRegistry = function (packagePath) {
       let registry = require(packagePath);
       if (registry.components) {
           return OracleBotLib.ComponentRegistry.create(registry.components, path.join(process.cwd(), packagePath));
       }
       return null;
   }
    
   componentsRegistry = getComponentsRegistry('.');
   if (componentsRegistry && componentsRegistry.getComponents().size > 0) {
       shell = OracleBotLib.ComponentShell({logger: console}, componentsRegistry);
       if (!shell) {
           throw new Error("Failed to initialize Bots Node SDK");
       }
   } else {
       throw new Error("Unable to process component registry because no components were found in package: " + packagePath);
   }
    
   const _handle = function (input, ctx) {
       let botsFnPath = ctx.getHeader(BOTS_FN_PATH_HEADER);
       if (!botsFnPath) {
           throw new Error("Missing required header " +  BOTS_FN_PATH_HEADER);
       } else if (botsFnPath === METADATA_PATH) {
           return shell.getAllComponentMetadata();
       } else if (botsFnPath.startsWith(COMPONENT_PREFIX)) {
           let componentName = botsFnPath.substring(COMPONENT_PREFIX.length);
           if (!componentName) {
               throw new Error("The component name is missing from the header " + BOTS_FN_PATH_HEADER + ": " + botsFnPath);
           }
           return new Promise((resolve) => {
               let callback = (err, data) => {
                   if (!err) {
                       resolve(data);
                   } else {
                       console.log("Component invocation failed", err.stack);
                       throw err;
                   }
               };
               shell.invokeComponentByName(componentName, input, {logger: () => console}, callback);
               });
       }
   };
    
   fdk.handle(function (input, ctx) {
       try {
           return _handle(input, ctx);
       } catch (err) {
           console.log("Function failed", err.stack);
           throw err;
       }
   });

3. In the same folder, create a file named func.yaml and then add the following content:

   schema_version: 20180708
   name: <custom component package name>
   version: 0.0.1
   runtime: [node11|node14]
   build_image: [fnproject/node:11-dev|fnproject/node:14-dev]
   run_image: [fnproject/node:11|fnproject/node:14]
   entrypoint: node func.js

4. In the name property, change <custom component package name> to the name of your custom component package, and then save your changes. The name is typically the same as the name that you specify in the package.json file.

   The name should be no more than 255 characters and contain only letters, numbers, _, and -.

5. Set these properties:

   • runtime: The Node language and version. Specify node11 or node14.

   • build_image: The build-time base image that contains the language-specific libraries and tools to build executable functions. Specify fnproject/node:11-dev or fnproject/node:14-dev.

   • run_image: The runtime base image that provides the language-specific runtime environment in which to run executable functions. Specify fnproject/node:11 or fnproject/node:14.

6. In a terminal window, change to the package's top folder and enter this command to install the FDK and to add it as a package dependency in the package.json file:

   npm install --save-dev @fnproject/fdk

7. (Optional – Linux, Mac, and Linux subsystem on Windows only) Run this command to install package dependencies:

   npm install

   Note that if the node_modules folder doesn't exist, then the fn deploy command that you do later will invoke npm install for you.

8. (Windows VM only) Complete these steps to copy your custom component code to your Linux guest for deployment:

   1. Drag-and-drop the top level folder to the Linux guest.

   2. In a terminal window, change to the top-level folder (the one that contains main.js) and type this command to add execute permissions for the folder.

      chmod 755 components

   3. Delete the node_modules folder to ensure that you don't have any platform-dependent node modules.

   4. (Optional) Run this command to reinstall the node module dependencies.

      npm install

      Note that if the node_modules folder doesn't exist, then the fn deploy command that you run later will invoke npm install for you.

You are now ready to complete the steps in Deploy the Custom Components to Oracle Cloud Infrastructure Functions.

After you create the func.js file, add fnproject to the development dependencies, and install the dependencies as described in Modify the Custom Component Package for Oracle Functions, you are ready to deploy a Docker image of the component package to Oracle Cloud Infrastructure Functions.

When you completed the steps in Set Up Your User Account for Oracle Functions, you copied commands from the Local Setup on the Getting Started page for steps 3 through 7. You'll use these copied commands to deploy your custom components.

If you're using Cloud Shell, then use the similar commands shown in Cloud Shell Setup instead.

To deploy the custom components:

1. Ensure that Docker and the Fn server are running.

2. In a terminal window, change to the top directory for your custom component package and enter your equivalent copied commands to configure the context.

   fn create context <context> --provider oracle
   fn use context <context>
   fn update context oracle.compartment-id <compartment-ocid>
   fn update context api-url https://functions.<region-identifier>.oci.oraclecloud.com

   You don't have to run these commands again until you need to change the context configurations.

   If you get the error "Fn: error replacing file with tempfile" when you change the context, then manually edit ~/.fn/config.yaml and change the context in that file.

3. If your config file has multiple profiles, enter this command to point to the profile that you created in Set Up Your User Account for Oracle Functions.

   fn update context oracle.profile <profile-name>

4. To point the registry repository that you created in Set Up Your User Account for Oracle Functions, enter your copied command that's equivalent to the following. If you haven't already, change [OCIR-REPO] to the name of your repository.

   fn update context registry <region-key>.ocir.io/<tenancy-namespace>/[OCIR-REPO]

   You don't have to run this command again until you need to change the repository configuration.

5. If you haven't signed into Docker in your current session, run the copied command that's equivalent to the one shown here.

   When it prompts you for a password, enter your auth token, which is the token that you obtained while completing the steps in Set Up Your User Account for Oracle Functions.

   docker login -u '<tenancy-namespace>/<user-name>' <region-key>.ocir.io

6. To deploy the custom components, run this command:

   fn deploy --app <application>

   If you see the following message, open the .oci/config file and verify that fingerprint shows the correct fingerprint for the specified key_file. If not, go to your user settings in the Console, click API Keys, view the configuration file for the correct fingerprint, and then replace the content of your config file with the displayed content.

   Fn: Service error:NotAuthenticated. The required information to complete
   authentication was not provided or was incorrect.. 
   http status code: 401.

Your custom components are ready to use in a skill as described in Add Oracle Function Service.

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 Task 1: 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.