{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "description":"Pizza Order Schema",
   "title":"Pizza Order Schema",
   "type":"object",
   "properties":{
      "size":{
         "description":"The pizza size",
         "type":"string"
      },
      "orderid":{
         "description":"The pizza orderid",
         "type":"string"
      },
      "type":{
         "description":"The pizza type",
         "type":"string"
      },
      "topping":{
         "description":"The pizza topping",
         "type":"string"
      }
   }
}

Per la capacità di rispondere all'evento, aggiungere un flusso per l'evento e utilizzare lo stato Notifica utente per visualizzare un messaggio quando si verifica l'evento:

1. Nella competenza che si desidera utilizzare l'evento, fare clic su , quindi su + Aggiungi flusso.
2. Inserire un nome di flusso e fare clic su Crea.
3. Fare clic sul menu nell'avvio del flusso, quindi fare clic su Aggiungi stato di inizio per aprire la finestra di dialogo Aggiungi stato.
   
   
   
   
4. Selezionare Service Integration > Notifica utente, immettere un nome per lo stato e fare clic su Inserisci.
5. Nella finestra di ispezione delle proprietà per lo stato Notifica utente inserito, selezionare la scheda Componente e compilare il campo Messaggio di notifica con un messaggio che si desidera venga visualizzato dall'utente quando si verifica l'evento.

   Nel messaggio è possibile utilizzare le espressioni nel seguente formato per accedere ai dati dell'evento:

   ${skill.system.event.value.application.data.<propertyName>}

   Nota
   
   È inoltre possibile accedere alle informazioni di contesto dall'evento utilizzando il seguente tipo di espressione:

   ${skill.system.event.value.application.context.<attributeName>}

   Per informazioni sugli attributi di contesto disponibili, vedere Attributi di contesto evento.
6. Facoltativamente, immettere nella proprietà ID utente un ID per un utente specifico che è possibile determinare in modo dinamico dall'interno del flusso, ad esempio tramite un componente personalizzato. Questa proprietà è utile soprattutto se l'ID utente non viene inviato nel payload dell'evento e l'utente è un utente unificato autenticato tramite un'autorizzazione che utilizza il componente OAuth 2.0 in cui la proprietà Associa a utente unificato è stata impostata su true. Per ulteriori informazioni sugli utenti unificati, vedere Configurazione dell'identità utente unificata.

Se l'evento deve essere indirizzato a un utente specifico ma tale utente non è specificato nell'evento stesso, potrebbe essere possibile determinare l'utente nel flusso che gestisce l'evento. Ecco i passaggi generali per farlo funzionare:

1. All'inizio del flusso che gestisce l'evento, aggiungere un componente personalizzato che determina l'ID utente (in base al payload dell'evento e/o a una logica personalizzata) e assegna tale ID a una variabile.
2. Dopo lo stato del componente personalizzato, inserire un componente Notifica utente e impostare la proprietà ID utente del componente sulla variabile restituita dal componente personalizzato.

Affinché una competenza riceva un evento, è necessario creare un gestore di eventi per tale evento nel flusso principale. Nel gestore di eventi è possibile mappare l'evento al flusso contenente lo stato Notifica utente creato per ricevere l'evento:

1. Nell'elenco dei flussi selezionare Flusso principale.
2. Nella scheda Eventi di tale flusso, accanto alla sezione Eventi applicazione, fare clic su .
3. Nella finestra di dialogo Crea handler eventi applicazione, selezionare il tipo di evento, la versione del tipo di evento e il flusso a cui si desidera mappare l'evento, quindi fare clic su Chiudi.
   Nota
   
   Nel campo Tipo di evento non risolto sono disponibili solo i tipi di evento finalizzati.

Per utilizzare un evento esterno, una competenza deve far parte di un assistente digitale. Per aggiungere uno skill configurato per utilizzare un evento in un assistente digitale, procedere come segue.

1. Fare clic su per aprire il menu laterale, selezionare Sviluppo > Assistenti digitali e fare doppio clic sull'assistente digitale che si desidera utilizzare.

2. Fare clic su Aggiungi skill.

3. Nella casella relativa allo skill configurato per l'utilizzo dell'evento, selezionare .

   Se non trovi l'abilità che stai cercando, potrebbe avere una modalità lingua non compatibile con la modalità lingua del tuo assistente digitale. Vedere Condizioni per l'aggiunta di una competenza a un assistente digitale.

4. Fare clic sul pulsante Fine per chiudere il catalogo delle competenze e visualizzare la pagina relativa allo skill nell'assistente digitale.

5. Scorrere fino alla sezione Modello di interazione della pagina e assicurarsi che il valore Richiama sia il nome che si desidera venga utilizzato dagli utenti per richiamare lo skill.

   Questo nome deve rispettare le seguenti Linee guida per i nomi delle chiamate.

6. Fornire alcune espressioni di esempio tipiche di come un utente invocherebbe lo skill.

   Queste espressioni verranno utilizzate come opzioni selezionabili negli stati di benvenuto e di aiuto predefiniti dell'assistente digitale.

L'esempio riportato di seguito mostra l'uso di un modulo strutturato per l'invio di eventi.

curl --location --request POST 'https://<server>/events/v2/listeners/appevent/channels/<id>' \
--header 'Content-Type: application/cloudevents+json' \
--header 'X-Hub-Signature: sha256=<SHA256 encoded request body using the channel's secret key>' \
--data-raw \

'{
    "specversion": "1.0",           //Version # of Digital Assistant's Events support
    "type": "<event_name>",         //The event type that the skill is listening for
    "source": "< event source>",    //URI-reference - identifies the context in which an event happened
    "id": "<event id>",             //Unique id for the event
    "version":"<event version>",    //An extension attribute(not part of CloudEvent spec) for the version # of the event type
    "data": {                       //The business data that matches with the schema defined for the event  
           
          }
}'

async pushEvent(eventName, eventVersion, userId, channelName, eventData){
  try {

    // Build event data
    const event = {
      specversion: "1.0",           //Version # of Digital Assistant's Events support
      type: eventName, // Name of Event you created in ODA
	  source: "< event source>",    //URI-reference - identifies the context in which an event happened
      id: "<event id>",             //Unique id for the event
      time: "2022-09-07T21:19:24Z", // Any Date value will do now
      channelname: <channelName>,   // Can be set to System_Global_Test if you want to test in tester
      version: <eventVersion>, // version of the event that you defined in Digital Assistant
      userid: <userId>,
      datacontenttype: "application/json",
      data: <eventData> // JSON object represting your payload which should confirm to the event's JSON schema
    };

    // Build Required headers
    const headers = {
      "X-Hub-Signature" : this._buildSignatureHeader(event, <EVENTS_CHANNEL_SECRET_KEY> , "utf8"),
      "Content-Type" : "application/cloudevents+json"
    };

    // POST to EVENT_LISTENER_CHANNEL_URL
    ....
    
  } catch (error) {
    logger.error(error.message);
    const errorMessage = `Error pushing event [ ${eventData} ] to Digital Assistant`;
    logger.debug(errorMessage);

    throw new Error(error.message);	
  }
}



_buildSignatureHeader(body, secret, encoding) {
  const buf = Buffer.from(JSON.stringify(body), "utf8");
  return "sha256=" + this._buildSignature(buf, secret, encoding);
}

_buildSignature(buf, secret, encoding) {
  const hmac = crypto.createHmac("sha256", Buffer.from(secret || "", encoding || "utf8"));
  if (buf) {
    hmac.update(buf);
  }
  return hmac.digest("hex");
}

Di seguito sono riportati gli attributi comuni che è possibile utilizzare in un payload evento.

• specversion: (Obbligatorio) Numero di versione del supporto Eventi di Digital Assistant. Attualmente, l'unico valore valido è 1.0.
• type: (Obbligatorio) il tipo di evento di ascolto della capacità. Deve corrispondere al nome del tipo di evento specificato nel task Definisci un tipo di evento.
• source: (Obbligatorio) identifica il contesto in cui si è verificato un evento. Può essere una stringa in formato libero.
• id: (Obbligatorio) ID univoco generato per l'evento dall'applicazione.
• version: (Obbligatorio) Il nome della versione del tipo di evento inviato. È necessario includere un valore per questo attributo nel payload evento e deve corrispondere al valore fornito per la versione del tipo di evento fornita nel task Crea un handler per l'evento esterno.
  Nota
  
  Questo attributo è uno degli attributi di estensione, ovvero non fa parte della specifica CloudEvent.
• data: (Obbligatorio) i dati business corrispondenti allo schema definito per l'evento.

Per ogni evento generato, Digital Assistant aggiunge attributi di estensione che descrivono il contesto in cui viene generato l'evento. Gli strumenti e i codici applicazione possono quindi utilizzare queste informazioni per identificare elementi quali l'origine degli eventi generati e la loro relazione con altri eventi. È inoltre possibile specificare i valori per questi attributi nel payload degli eventi.

Di seguito è riportato un elenco degli attributi di estensione (tutti di tipo String):

• version: il nome della versione del tipo di evento inviato. È necessario includere un valore per questo attributo nel payload evento e deve corrispondere al valore fornito per la versione del tipo di evento fornita nel task Crea un handler per l'evento esterno.
• userid: l'ID dell'utente a cui viene indirizzato il messaggio. Può assumere una delle due forme seguenti:
  • Un ID utente IAM OCI. In questo caso, è necessario includere anche l'attributo usertenancy nel payload.
  • ID utente fornito dal canale. In questo caso, è necessario includere anche l'attributo channelname nel payload.
    Nota
    
    Per Twilio, questo valore corrisponde al numero di telefono cellulare dell'utente.
• usertenancy: il nome della tenancy IAM OIC del provider di identità dell'utente.
• channelname: il nome del canale attraverso il quale viene esposto l'assistente digitale.
• tenancy: il nome della tenancy Oracle Cloud Infrastructure per l'istanza di Digital Assistant. In genere, non è necessario includere in modo esplicito questo attributo poiché le informazioni sulla tenancy vengono passate nelle intestazioni delle richieste.

{
    "specversion": "1.0",
    "type": "com.pizzastore.pizza.ordercreated",
    "source": "pizzastore/orders",
    "id": "12345678-90ab-cdef-1234-567890abcdef",
    "time": "2022-08-10T12:31:00Z",
    "contenttype": "application/json",
    "tenancy": "mydigitalassistantinstance",
    "version": "1.0",
    "data": {"size": "Large",
            "type": "Veg"
          }
}

Se è necessario passare l'ID utente IAM OCI per l'utente nel payload, specificare anche gli attributi userid e usertenancy:

{
    "specversion": "1.0",           //Version # of Digital Assistant's Events support
    "type": "<event_name>",         //The event type that the skill is listening for
    "source": "< event source>",    //URI-reference - identifies the context in which an event happened
    "id": "<event id>",             //Unique id for the event
    "version":"<event version>",    //An extension attribute(not part of CloudEvent spec) for the version # of the event type
    "userid":"<IAM user id>",      //An extension attribute(not part of CloudEvent spec) for the user ID  
    "usertenancy":<IAM tenancy>",  //Extension attribute, IAM
    "data": {                       //The business data that matches with the schema defined for the event  
           
          }
}

Per gli assistenti digitali esposti attraverso i canali Twilio e Web, l'applicazione esterna può anche avvisare gli utenti specificando il nome del canale e l'ID utente fornito dal canale.

{
    "specversion": "1.0",            //Version # of Digital Assistant's Events support
    "type": "<name_of_event_type>",  //The event type that the skill is listening for
    "source": "< event source>",     //URI-reference - identifies the context in which an event happened
    "id": "<event id>",              //Unique id for the event
    "version":"<event version>",     //An extension attribute(not part of CloudEvent spec) for the version # of the event type
    "userid":"<channel user id>",    //An extension attribute(not part of CloudEvent spec) for the user ID
    "channelname":"<channel name>",  //Name of the channel through which the digital assistant is exposed
    "data": {                        //The business data that matches with the schema defined for the event  
           
          }
}