Utilizzare il comando init component dell'interfaccia CLI dell'SDK per creare un file JavaScript o TypeScript con la struttura per utilizzare l'SDK Node.js di Oracle Digital Assistant per scrivere un componente personalizzato. La lingua specificata al momento dell'esecuzione del comando init per creare il pacchetto del componente determina se viene creato un file JavaScript o TypeScript.

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

Il componente personalizzato deve esportare due oggetti:

• metadata: fornisce allo skill le informazioni sui componenti riportate di seguito.
  • Nome componente
  • Proprietà supportate
  • Azioni di transizione supportate

  Per i flussi di dialogo basati su YAML, il componente personalizzato supporta per impostazione predefinita le seguenti proprietà. Queste proprietà non sono disponibili per gli skill progettati in modalità finestra di dialogo Visual.

  • autoNumberPostbackActions: booleano. Non necessaria. Quando si utilizza true, i pulsanti e le opzioni di elenco vengono numerati automaticamente. L'impostazione predefinita è false. Vedere Numerazione automatica per i canali di solo testo nei flussi di finestre di dialogo YAML.
  • insightsEndConversation: booleano. Non necessaria. Quando true, la sessione interrompe la registrazione della conversazione per la generazione di report degli approfondimenti. L'impostazione predefinita è false. Vedere Modellare il flusso di finestre di dialogo.
  • insightsInclude: booleano. Non necessaria. Quando si utilizza true, lo stato viene incluso nel report degli approfondimenti. L'impostazione predefinita è true. Vedere Modellare il flusso di finestre di dialogo.
  • translate: booleano. Non necessaria. Quando si utilizza true, la traduzione automatica è abilitata per questo componente. L'impostazione predefinita è il valore della variabile di contesto autotranslation. Vedere Translation Services in Skills.
• invoke: contiene la logica da eseguire. In questo metodo è possibile leggere e scrivere variabili di contesto delle competenze, creare messaggi di conversazione, impostare transizioni di stato, effettuare chiamate REST e altro ancora. In genere, questa funzione consente di utilizzare la parola chiave async per gestire le promesse. La funzione invoke accetta il seguente argomento:
  • context, che assegna un nome al riferimento all'oggetto CustomComponentContext nell'SDK Node.js di Digital Assistant. Questa classe è descritta nella documentazione dell'SDK all'indirizzo https://oracle.github.io/bots-node-sdk/. Nelle versioni precedenti dell'SDK, il nome era conversation. È possibile utilizzare uno dei due nomi.
  Nota
  
  Se si utilizza una libreria JavaScript che non supporta le promesse, quindi non si utilizza la parola chiave async, è anche possibile aggiungere un argomento done come callback richiamato dal componente al termine dell'elaborazione.

Esempio:

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

Per ulteriori informazioni ed esplorare alcuni esempi di codice, consulta la sezione relativa alla scrittura di componenti personalizzati nella documentazione relativa all'SDK del nodo bot.

È possibile utilizzare diverse combinazioni delle funzioni keepTurn e transition del kit SDK nodo bot per definire il modo in cui il componente personalizzato interagisce con un utente e il modo in cui la conversazione continua dopo che il componente restituisce il controllo del flusso alla competenza.

• keepTurn(boolean) specifica se la conversazione deve passare a un altro stato senza prima richiedere l'input dell'utente.

  Tenere presente che se si desidera impostare keepTurn su true, è necessario chiamare keepTurn dopo aver chiamato reply perché reply imposta in modo implicito keepTurn su false.

• transition(action) fa sì che la finestra di dialogo passi allo stato successivo dopo l'invio di tutte le eventuali risposte. L'argomento facoltativo action indica l'azione (risultato) restituita dal componente.

  Se non si chiama transition(), la risposta viene inviata, ma la finestra di dialogo rimane nello stato e il successivo input utente torna a questo componente. Cioè, invoke() viene chiamato di nuovo.

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

Di seguito sono riportati alcuni casi d'uso comuni in cui utilizzare keepTurn e transition per controllare il flusso della finestra di dialogo.

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

I metodi di istanza CustomComponentContext consentono di ottenere il contesto per le variabili di richiamo, accesso e modifica e di inviare nuovamente i risultati al motore della finestra di dialogo.

È possibile trovare diversi esempi di codice per l'uso di questi metodi in Scrittura di componenti personalizzati e Messaggistica di conversazione nella documentazione dell'SDK del nodo bot.

La documentazione di riferimento sull'SDK è disponibile all'indirizzo https://github.com/oracle/bots-node-sdk.

Quando si progetta un componente personalizzato, è necessario valutare se il componente verrà utilizzato da uno skill che supporta più lingue.

Se il componente personalizzato deve supportare competenze multilingue, è necessario sapere se le competenze sono configurate per il supporto della lingua nativa o il servizio di traduzione.

Quando si utilizza un servizio di traduzione, è possibile tradurre il testo dalla competenza. Sono disponibili le opzioni seguenti:

• Impostare la proprietà translate nello stato del componente personalizzato su true per tradurre la risposta del componente, come descritto in Invia risposte direttamente al servizio di traduzione.

• Invia dati grezzi alla competenza nelle variabili e utilizza i valori delle variabili in un componente di sistema che compone l'output. Impostare su true la proprietà translate del componente. Vedere Utilizzare un componente di sistema per passare il messaggio al servizio di traduzione.

• Inviare i dati non elaborati allo skill nelle variabili e utilizzare i valori delle variabili in un componente di sistema che utilizza la chiave bundle di risorse per la lingua. Vedere Utilizzare un componente di sistema per fare riferimento a un bundle di risorse.

Per le competenze linguistiche native, sono disponibili le seguenti opzioni:

• Trasmettere i dati alla competenza nelle variabili e quindi eseguire l'output del testo da un componente di sistema passando i valori delle variabili a una chiave bundle di risorse, come descritto in Utilizzare un componente di sistema per fare riferimento a un bundle di risorse. Con questa opzione, il componente personalizzato deve avere proprietà di metadati per consentire allo skill di passare i nomi delle variabili in cui memorizzare i dati.

• Utilizzare il bundle di risorse del componente personalizzato per comporre la risposta del componente personalizzato, come descritto in Bundle di risorse di riferimento del componente personalizzato. Utilizzare il metodo conversation.translate() per ottenere la stringa del bundle delle risorse da utilizzare per la chiamata a context.reply(). Questa opzione è valida solo per le definizioni di bundle di risorse che utilizzano parametri posizionali (numerati). Non funziona per i parametri denominati. Con questa opzione, il componente personalizzato deve avere una proprietà di metadati per il nome della chiave del bundle di risorse e i parametri della chiave del bundle di risorse denominato devono corrispondere a quelli utilizzati nella chiamata a context.reply().

Di seguito è riportato un esempio di utilizzo del bundle di risorse dal componente personalizzato. In questo esempio, fmTemplate verrà impostato su un valore simile a ${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 una conversazione dell'assistente digitale, un utente può interrompere un flusso di conversazione modificando l'oggetto. Ad esempio, se un utente avvia un flusso per effettuare un acquisto, potrebbe interrompere tale flusso per chiedere quanto credito ha su una carta regalo. Lo chiamiamo non sequitur. Per consentire all'assistente digitale di identificare e gestire i non sequiturs, chiamare il metodo context.invalidInput(payload) quando una risposta di espressione utente non è compresa nel contesto del componente.

In una conversazione digitale, il runtime determina se un input non valido è un non sequitur mediante la ricerca di corrispondenze di risposta in tutte le competenze. Se trova corrispondenze, reindirizza il flusso. In caso contrario, viene visualizzato il messaggio, se fornito, che richiede all'utente l'input, quindi esegue di nuovo il componente. Il nuovo input viene passato al componente nella proprietà text.

In una conversazione di skill standalone, il runtime visualizza il messaggio, se fornito, che richiede all'utente l'input, quindi esegue di nuovo il componente. Il nuovo input viene passato al componente nella proprietà text.

Questo codice di esempio chiama context.invalidInput(payload) ogni volta che l'input non viene convertito in un numero.

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

Di seguito è riportato un esempio di come un assistente digitale gestisce l'input non valido in runtime. Per la prima risposta età (twentyfive), non ci sono corrispondenze in alcuna competenza registrata con l'assistente digitale in modo che la conversazione visualizzi il messaggio context.invalidUserInput specificato. Nella risposta alla seconda età (send money), l'assistente digitale trova una corrispondenza in modo da chiedere se deve reindirizzare a tale flusso.

È necessario chiamare context.invalidInput() o context.transition(). Se si richiamano entrambe le operazioni, assicurarsi che la variabile system.invalidUserInput sia ancora impostata se viene inviato un messaggio aggiuntivo. Tenere inoltre presente che i componenti di input dell'utente, ad esempio i componenti delle entità di risposta comune e di risoluzione, reimpostano system.invalidUserInput.

Si supponga, ad esempio, di modificare il componente AgeChecker come illustrato di seguito e di chiamare context.transition() dopo 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 questo caso, il flusso di dati deve tornare a askage in modo che l'utente riceva due messaggi di output: "Input età non compreso. Si prega di riprovare" seguito da "Quanti anni hai?". Ecco come potrebbe essere gestito in un flusso di dialogo in modalità 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"