Utilice el comandoinit component de la CLI del SDK para crear un archivo JavaScript o TypeScript con el marco para trabajar con el SDK de Node.js de Oracle Digital Assistant para escribir un componente personalizado. El idioma especificado al ejecutar el comando init para crear el paquete de componentes determina si se ha creado un archivo JavaScript o TypeScript.

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

Su componente personalizado debe exportar dos objetos:

• metadata: proporciona la siguiente información del componente a la aptitud.
  • Nombre del Componente
  • Propiedades soportadas
  • Acciones de transición soportadas

  Para los flujos de diálogo basados en YAML, el componente personalizado soporta las siguientes propiedades por defecto. Estas propiedades no están disponibles para las aptitudes diseñadas en el modo de diálogo Visual.

  • autoNumberPostbackActions: booleano. No necesario. Cuando el valor es true, los botones y las opciones de lista se enumeran automáticamente. El valor por defecto es false. Consulte Numeración automática para canales de solo texto en flujos de diálogo de YAML.
  • insightsEndConversation: booleano. No necesario. Cuando el valor es true, la sesión deja de grabar la conversación para la generación de informes de estadísticas. El valor por defecto es false. Consulte Modelo del flujo de diálogo.
  • insightsInclude: booleano. No necesario. Cuando el valor es true, el estado se incluye en los informes de estadísticas. El valor por defecto es true. Consulte Modelo del flujo de diálogo.
  • translate: booleano. No necesario. Cuando el valor es true, se activa la traducción automática para este componente. El valor por defecto es el valor de la variable de contexto autotranslation. Consulte Servicios de traducción en aptitudes.
• invoke: contiene la lógica que se va a ejecutar. En este método, puede leer y escribir variables de contexto de aptitud, crear mensajes de conversación, definir transiciones de estado, realizar llamadas de REST, entre otras acciones. Normalmente, se utiliza la palabra clave async con esta función para gestionar promesas. La función invoke toma el siguiente argumento:
  • context, que asigna un nombre a la referencia al objeto CustomComponentContext del SDK de Node.js de Digital Assistant. Esta clase se describe en la documentación del SDK, en https://oracle.github.io/bots-node-sdk/. En las versiones anteriores del SDK, el nombre era conversation. Puede utilizar cualquiera de los nombres.
  Nota
  
  Si utiliza una biblioteca JavaScript que no soporta promesas (y, por lo tanto, no utiliza la palabra clave async), también es posible agregar un argumento done como devolución de llamada que llama el componente cuando ha terminado el procesamiento.

Ejemplo:

'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');   
  }
}

Para obtener más información y conocer algunos ejemplos de código, consulte Escritura de componentes personalizados en la documentación del SDK de Bots Node.

Puede utilizar diferentes combinaciones de las funciones keepTurn y transition del SDK del nodo de bot para definir cómo interactúa el componente personalizado con un usuario y cómo continúa la conversación después de que el componente haya devuelto el control de flujo a la aptitud.

• keepTurn(boolean) especifica si la conversación debe pasar a otro estado sin solicitar primero la entrada del usuario.

  Tenga en cuenta que si desea definir keepTurn en true, debe llamar a keepTurn después de llamar a reply porque reply define implícitamente keepTurn en false.

• transition(action) hace que el cuadro de diálogo pase al siguiente estado después de enviar todas las respuestas, si las hay. El argumento action opcional nombra esa acción (resultado) que devuelve el componente.

  Si no llama a transition(), la respuesta se envía, pero el cuadro de diálogo permanece en el estado y la siguiente entrada de usuario vuelve a este componente. Es decir, se vuelve a llamar a invoke().

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

A continuación se muestran algunos casos de uso comunes en los que utilizaría keepTurn y transition para controlar el flujo de diálogo:

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);
  }
}

Utilice los métodos de la instancia CustomComponentContext para obtener el contexto para la llamada, acceder a las variables y cambiarlas y devolver los resultados al motor de diálogo.

Puede encontrar varios ejemplos de código para utilizar estos métodos en Escritura de componentes personalizados y Mensajes de conversación en la documentación del SDK de Bots Node

La documentación de referencia del SDK se encuentra en https://github.com/oracle/bots-node-sdk.

Al diseñar un componente personalizado, debe considerar si el componente lo utilizará una aptitud que soporte más de un idioma.

Si el componente personalizado debe soportar aptitudes en varios idiomas, debe saber si las aptitudes están configuradas para el soporte de idioma nativo o el servicio de traducción.

Al utilizar un servicio de traducción, puede traducir el texto de la aptitud. Tiene estas opciones:

• Defina la propiedad translate en el estado del componente personalizado en true para traducir la respuesta del componente, como se describe en Enviar respuestas directamente al servicio de traducción.

• Devolver los datos raw a la aptitud en variables y utilizar los valores de las variables en un componente del sistema que compone la salida. Defina la propiedad translate de ese componente en true. Consulte Uso de un Componente del Sistema para Pasar el Mensaje al Servicio de Traducción.

• Vuelva a enviar los datos raw a la aptitud en variables y utilice los valores de las variables en un componente del sistema que utilice la clave de grupo de recursos para el idioma. Consulte Use a System Component to Reference a Resource Bundle.

Para las aptitudes de idioma nativo, tiene estas opciones:

• Transfiera los datos a la aptitud en variables y, a continuación, genere el texto de un componente del sistema transfiriendo los valores de las variables a una clave de grupo de recursos, como se describe en Uso de un componente del sistema para hacer referencia a un grupo de recursos. Con esta opción, el componente personalizado debe tener propiedades de metadatos para que la aptitud transfiera los nombres de las variables en las que almacenar los datos.

• Utilice el grupo de recursos del componente personalizado para redactar la respuesta del componente personalizado, como se describe en Paquetes de recursos de referencia del componente personalizado. Utilice el método conversation.translate() para obtener la cadena de grupo de recursos que se utilizará para la llamada a context.reply(). Esta opción solo es válida para las definiciones de grupos de recursos que usan parámetros posicionales (numerados). No funciona para parámetros con nombre. Con esta opción, el componente personalizado debe tener una propiedad de metadatos para el nombre de la clave del grupo de recursos, y los parámetros de la clave del grupo de recursos con nombre deben coincidir con los utilizados en la llamada a context.reply().

A continuación, se muestra un ejemplo del uso del grupo de recursos del componente personalizado. En este ejemplo, fmTemplate se definiría como ${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();  
  }
};

En una conversación de asistente digital, un usuario puede interrumpir un flujo de conversación cambiando el asunto. Por ejemplo, si un usuario inicia un flujo para realizar una compra, es posible que interrumpa ese flujo para preguntar cuánto crédito tiene en una tarjeta regalo. Es lo que denominamos incongruencia. Para permitir que el asistente digital identifique y gestione las incongruencias, llame al método context.invalidInput(payload) cuando la respuesta a la expresión del usuario no se entienda en el contexto del componente.

En una conversación digital, el tiempo de ejecución determina si una entrada no válida es una incongruencia buscando coincidencias de respuestas en todas las aptitudes. Si encuentra alguna coincidencia, vuelve a encaminar el flujo. Si no, muestra el mensaje, si se ha proporcionado, solicita al usuario una entrada y, a continuación, vuelve a ejecutar el componente. La nueva entrada se transfiere al componente en la propiedad text.

En una conversación de aptitud independiente, el tiempo de ejecución muestra el mensaje, si se ha proporcionado, solicita al usuario una entrada y, a continuación, ejecuta el componente de nuevo. La nueva entrada se transfiere al componente en la propiedad text.

Este código de ejemplo llama a context.invalidInput(payload) siempre que los datos introducidos no se convierten en un número.

"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();
    }
};

A continuación, se muestra un ejemplo de cómo maneja un asistente digital una entrada no válida en el tiempo de ejecución. Con respecto a la primera respuesta a la edad (twentyfive), no hay coincidencias en ninguna aptitud registrada con el asistente digital, por lo que la conversación muestra el mensaje context.invalidUserInput especificado. En la segunda respuesta a la edad (send money), el asistente digital encuentra una coincidencia y pregunta si se debe ejecutar el redireccionamiento hacia este flujo.

Debe llamar a context.invalidInput() o a context.transition(). Si llama a ambas operaciones, asegúrese de que la variable system.invalidUserInput siga definida si se envía algún mensaje adicional. Tenga en cuenta también que los componentes de entrada de usuario (como los componentes Respuesta común y Entidades de resolución) restablecen system.invalidUserInput.

Supongamos, por ejemplo, que modificamos el componente AgeChecker como se muestra a continuación y que llamamos a context.transition() después de 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;
}

En este caso, el flujo de datos debe volver a realizar la transición a askage para que el usuario obtenga dos mensajes de salida: "No se ha entendido la entrada de edad. Vuelva a intentarlo", seguido de "¿Cuántos años tiene?". A continuación, se muestra cómo se puede manejar esto en un flujo de diálogo en modo YAML.

  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"