La configurazione dei componenti System.CommonResponse comporta l'impostazione delle proprietà che indirizzano il motore delle finestre di dialogo insieme alle proprietà dei metadati che descrivono non solo il modo in cui il componente invia i messaggi (come prompt di testo, schede o allegati), ma imposta anche il contenuto e il comportamento dei messaggi stessi.

Di seguito è riportata la YAML per uno stato di esempio basato sul componente System.CommonResponse.

  AskPizzaSize:
    component: "System.CommonResponse"
    properties:
      variable: "pizzaSize"
      nlpResultVariable: "iresult"
      maxPrompts: 2
      metadata:
        responseItems:
        - type: "text"
          text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
            \ </#if>What size do you want?"
          name: "What size"
          separateBubbles: true
          actions:
          - label: "${enumValue}"
            type: "postback"
            payload:
              action: ""
              variables:
                pizzaSize: "${enumValue}"
            name: "size"
            iteratorVariable: "pizzaSize.type.enumValues"
      processUserMessage: true
    transitions:
      actions:
        cancel: "Intent"
      next: "AskLocation" 

  ####################    
  # Loan Advisor
  ####################

  loanAdvisorStart:
    component: "System.Output"
    properties:
      keepTurn: true
      text: |
        OK, I can initiate a loan request for you.
        But first I'll transfer you to an 
        automated advisor that will ask some
        questions about the loan that you want, 
        your assets, your liabilities, and your 
        financial history. It shouldn't take 
        more than 5 minutes.
        <#if (user.notFirstTime)??><#else>
        At any time, you can say 
        /back to go to the previous question, 
        /reset to start over or 
        /exit to stop the questions.</#if>
    transitions:
      next: "setNotFirstTime"
      
  setNotFirstTime:
    component: "System.SetVariable"
    properties:
      variable: "user.notFirstTime"
      value: true
    transitions:
      next: "loanAdvisorIA"  
      
  loanAdvisorIA:
    component: "System.IntelligentAdvisor"
    properties:
      intelligentAdvisorService: "myService"
      deployment: "Loan Qualifier"
      # default yesLabel: "yes"
      # default noLabel: "no"
      uncertainLabel: "not sure"
      endLabel: " "
      # default doneLabel: "/done"
      # default undoLabel: "/back"
      # default resetLabel: "/reset"
      # default exitLabel: "/exit"
      showExplanation: "ask"
      # default explanationAskLabel: "Do you want to see the explanation?"
      interviewAttributes: "interviewDetails"      
    transitions:
      error: "handleIAError"
      next: "handleEligibility"

  handleEligibility:
    component: "System.Switch"
    properties:
      source: <#list interviewDetails.value as i><#if i.key = 'eligibility'>${i.val}</#if></#list>
      # The values that are matched against the value of the variable or source property. The value that matches is set as transition action
      values:
      - "eligible"
      - "noteligible"
    transitions:
      actions:
        eligible: "initiateLoan"
        noteligible: "suggestNextSteps"
        NONE: "handleUnexpectedAttributeValue" # the attribute value was other than eligible or noteligible or the user exited interview
      error: "handleAttributeNotSet" # the attribute wasn't set during the interview or the key is incorrect

  handleIAError:
    component: "System.Output"
    properties:
      text: |
        We are having a problem with a connection.
        Can you please send email to 
        contact@example.com to let them know that
        the loan advisor isn't working? Thank you.
    transitions:
      next: "endOfFlow"
...
      

Di seguito è riportato un semplice esempio di accesso ai valori degli attributi di un'intervista.

context:
  variables:
    iResult: "nlpresult"
    interviewDetails: "string"

states:
  ...
  loanAdvisorIA:
    component: "System.IntelligentAdvisor"
    properties:
      intelligentAdvisorService: "myService"
      deployment: "Loan Qualifier"
      # default yesLabel: "yes"
      # default noLabel: "no"
      uncertainLabel: "not sure"
      endLabel: " "
      # default doneLabel: "/done"
      # default undoLabel: "/back"
      # default resetLabel: "/reset"
      # default exitLabel: "/exit"
      showExplanation: "ask"
      # default explanationAskLabel: "Do you want to see the explanation?"
      interviewAttributes: "interviewDetails"      
    transitions:
      error: "handleIAError"
      next: "handleEligibility"

  handleEligibility:
    component: "System.Switch"
    properties:
      source: <#list interviewDetails.value as i><#if i.key = 'eligibility'>${i.val}</#if></#list>
      # the values that are matched against the value of the variable or source property. The value that matches is set as transition action
      values:
      - "eligible"
      - "noteligible"
    transitions:
      actions:
        eligible: "initiateLoan"
        noteligible: "suggestNextSteps"
        NONE: "handleUnexpectedAttributeValue" # the attribute value was other than eligible or noteligible or the user exited interview
      error: "handleAttributeNotSet" # the attribute wasn't set during the interview or the key is incorrect
  ...

Il diagramma seguente illustra come implementare il metodo a stato singolo se il flusso della finestra di dialogo viene creato in modalità YAML. 1) Utilizzare una variabile di contesto mappa per associare gli intenti knowledge ai termini di ricerca. 2) Impostare gli intenti knowledge base azione nello stato Intent per eseguire la transizione a un flusso di dati che utilizza la mappa per impostare la variabile di contesto searchTerm sul termine di ricerca dell'intento. 3) Si passa quindi a uno stato che cerca il valore searchTerm nella knowledge base.

Descrizione dell'illustrazione kf-assoc-intent-term.png

Di seguito è riportato un esempio di flusso di una finestra di dialogo in cui sono presenti singoli intenti per ogni risposta della knowledge base.

context:
  variables:
    iResult: "nlpresult"
    intentName: "string"
    searchTerm: "string"
    searchTerms: "map"
    someVariable: "string" # For the reset state

states:

  #
  # Set search term for each knowledge intent
  #

  setSearchTerms:
    component: "System.SetVariable"
    properties:
      variable: "searchTerms"
      value:
        knowledge.Shipping Return Costs: "Shipping Return Costs"
        knowledge.Locate Service Tag or Serial: "Locating Your Service Tag or Asset Serial Number"
        knowledge.Support Account: "My Support Account"
        knowledge.Product Registration: "How do I register my product?" # (1)
        knowledge.Noncontiguous Delivery Time: "What is the delivery time to Alaska, Hawaii and the U.S. Territories?"
        knowledge.Return Policy: "What is your return policy?"
    transitions:
      next: "intent"
  
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        system.Greeting: "welcome"
        system.Unsatisfactory Response: "transferToAgent"
        system.Request Agent: "transferToAgent"
        knowledge.Shipping Return Costs: "startIntentKnowledgeSearch"
        knowledge.Locate Service Tag or Serial: "startIntentKnowledgeSearch"
        knowledge.Support Account: "startIntentKnowledgeSearch"
        knowledge.Product Registration: "startIntentKnowledgeSearch" # (2)
        knowledge.Noncontiguous Delivery Time: "startIntentKnowledgeSearch"
        knowledge.Return Policy: "startIntentKnowledgeSearch"
        unresolvedIntent: "genericKnowledgeSearch"

  #
  # Start knowledge search for a knowledge intent's search term
  # based on searchTerms context variable
  # 
  # First, reset variables
  #
  
  startIntentKnowledgeSearch: # (2)
    component: "System.ResetVariables"
    properties:
      variableList: "searchTerm, intentName"
    transitions:
      next: "setIntentName"
      
  # 
  # Set the intentName context variable
  #
  
  setIntentName:     
    component: "System.SetVariable"
    properties:
      variable: "intentName"
      value: "${iResult.value.intentMatches.summary[0].intent}"
    transitions:
      next: "setSearchTerm"      
    
  # 
  # Get the search term to use for the intent
  #
  
  setSearchTerm:
    component: "System.SetVariable"
    properties:
      variable: "searchTerm"
      value: "${searchTerms.value[intentName.value]}"
    transitions:
      next: "knowledgeSearchForGivenSearchTerm" # (3)            
      
  # 
  # This state searches for the searchTerm variable's value
  #
  
  knowledgeSearchForGivenSearchTerm:   
    component: "System.KnowledgeSearch"
    properties:
      # Set to the name of the search service that is configured in Settings
      searchServiceName: "KnowledgeSearch"
      searchTerm: "${searchTerm.value}" # put the search term here (3)
      # searchPrelude: Optional property. If missing, there's no search prelude.      
      resultSizeLimit: 1 # Change to how many articles to show. 
      # resultVersion: Optional property. Defaults to "Answer".
      # resultVersionExclusive: Optional property. Defaults to false.
      resultLinkLabel: "Show More"
      # defaultAttachmentLabel: Optional property. Defaults to "Download"
      searchLinkLabel: "Search for Similar Answers"
      noResultText: >
        I don't have an answer for that. Try rephrasing your question 
        (or you can ask to speak to a live agent).
      # cardLayout: Optional property. Defaults to "horizontal"
    transitions:
      actions:
        resultSent: "offerMoreHelp"
        noResult: "reset"
        serverError: "handleSearchServerProblem"
      error: "handleSearchError"
      next: "reset"    

  #
  # This state is called after knowledge search returns its results.
  #
  
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"

  #
  # This state is called when there's a problem accessing the knowledge base such
  # as a server error fault or an unexpected error fault. When this error occurs,
  # the error message is stored in system.state.<state-name>.serverError.message. 
  # 
  
  handleSearchServerProblem:
    component: "System.Output"
    properties:
      text: >
        I'm not able to get an answer for that question. Let me know 
        if there's anything else I can help you with.
    transitions:
      return: "handleSearchServerProblem"      
  
  #
  # This state is called when there's a problem using the knowledge search component
  # such as when there's a problem with the knowledge search integration configuration
  # 
  
  handleSearchError:
    component: "System.Output"
    properties:
      text: >
        Oops, my answer mechanism for that isn't working properly.
        You can ask a different question or ask to speak to an agent?
    transitions:
      return: "handleSearchError"      

  #
  # This state ends the conversation
  #
  
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

L'esempio seguente mostra come impostare searchTerm sull'espressione dell'utente in una competenza della finestra di dialogo YAML. Per una finestra di dialogo visiva, utilizzare invece ${skill.system.nlpresult.value.query}.

context:
  variables:
    iResult: "nlpresult"
    someVariable: "string" # For the reset state

states:

  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        system.Greeting: "welcome"
        system.Unsatisfactory Response: "transferToAgent"
        ...
        unresolvedIntent: "genericKnowledgeSearch"
  
  #
  # This state searches the knowledge base with the user input as the search term.
  #

  genericKnowledgeSearch: 
    component: "System.KnowledgeSearch"
    properties:
      # Set to the name of the search service that is configured in Settings
      searchServiceName: "KnowledgeSearch"
      searchTerm: "${iResult.value.query}"
      searchPrelude: "I don't know the answer offhand. Let's see what articles we have..."      
      resultSizeLimit: 3 # Change to how many articles to show. Defaults to 10.
      # resultVersion: Optional property. Defaults to "Answer".
      # resultVersionExclusive: Optional property. Defaults to false.
      resultLinkLabel: "Show More"
      # defaultAttachmentLabel: Optional property. Defaults to "Download"
      searchLinkLabel: "Open Page with All Answers"
      noResultText: >
        I couldn't find any articles about that. Try rephrasing your 
        question (or you can ask to speak to a live agent).
      # cardLayout: Optional property. Defaults to "horizontal"
    transitions:
      actions:
        resultSent: "offerMoreHelp"
        noResult: "reset"
        serverError: "handleSearchServerProblem"
      error: "handleSearchError"
      next: "reset"

  #
  # This state is called after knowledge search returns its results.
  #
  
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"

  #
  # This state is called when there's a problem accessing the knowledge base such
  # as a server error fault or an unexpected error fault. When this error occurs,
  # the error message is stored in system.state.<state-name>.serverError.message. 
  # 
  
  handleSearchServerProblem:
    component: "System.Output"
    properties:
      text: >
        I'm not able to get an answer for that question. Let me know 
        if there's anything else I can help you with.
    transitions:
      return: "handleSearchServerProblem"      
  
  #
  # This state is called when there's a problem using the knowledge search component
  # such as when there's a problem with the knowledge search integration configuration
  # 
  
  handleSearchError:
    component: "System.Output"
    properties:
      text: >
        Oops, my answer mechanism for that isn't working properly.
        You can ask a different question or ask to speak to an agent?
    transitions:
      return: "handleSearchError"      

  #
  # This state ends the conversation
  #
  
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

Di seguito è riportato un esempio di flusso di dialogo che viene trasferito a un agente quando il cliente chiede di parlare con un agente.

metadata:
  platformVersion: "1.1"
main: true
name: "AutomatedAgentConversation"
context:
  variables:
    iResult: "nlpresult"
    someVariable: "string"
states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        ...
        system.Unsatisfactory Response: "transferToAgent"
        system.Request Agent: "transferToAgent"
        ...
  
  #
  # This state tries to transfer the user to another agent when the user explicitly requests for it.
  #
  transferToAgent:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: "300"
      waitingMessage: "I'm transferring you to a human agent. Hold tight."
      rejectedMessage: "I wasn't able to transfer you to a human agent. Please try again later."
      errorMessage: "We're unable to transfer you to a human agent because there was a system error."
    transitions:
      actions:
        accepted: "reset"
        rejected: "handleRejected"
        error: "offerMoreHelp"
      next: "reset"
  #
  # This state is called when an agent transfer is rejected. 
  # It lets the customer know they can ask for something else.
  # 
  handleRejected:
    component: "System.Output"
    properties:
      text: "Meanwhile, let me know if there's anything else I can help you with."
    transitions:
      return: "handleRejected"
  
  #
  # This state is called when an agent transfer encounters a system error. 
  # It lets the customer know they can ask for something else.
  #
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"
      
  #
  # This state ends the conversation with a return transition for insights purposes, 
  # after the user has been transferred to another agent.
  #
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

Quando si trasferisce una conversazione da un assistente digitale a un agente reale, è possibile utilizzare le proprietà personalizzate nel componente System.AgentTransfer per passare queste informazioni.

Di seguito è riportata la struttura per Oracle B2C Service.

      customProperties:
        - name: 
          value: 
          type:

La proprietà type è obbligatoria per i campi personalizzati, altrimenti è facoltativa.

Di seguito è riportata la struttura per Oracle Fusion Service.

      customProperties:
        - name: 
          value:

Di seguito è riportata un'impostazione customProperties di esempio per Oracle Fusion Service.

  doTransfer:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: "300"
      allowTransferIf: "agentSessionsAreAvailable"
      # Example of passing a custom property to Oracle Fusion
                                Service      
      customProperties:
        # This is a checkbox custom field in the Universal Work Object.
        # Checkboxes take the value of Y (selected) or N (unselected).
        - name: "TriagedByODA_c"
          value: "Y"
      acceptedMessage: "The conversation has been transferred to a live agent."
      waitingMessage: "I'm transferring you to a human. Hold tight"
      rejectedMessage: "Looks like no one is available. Please try later"
      errorMessage: "We're unable to transfer you to a live agent because there was a system error."
    transitions:
      actions:
        accepted: "reset"
        rejected: "handleRejected"
        error: "offerMoreHelp"
      next: "reset"

Di seguito è riportato un esempio di flusso di una finestra di dialogo che richiama il componente, visualizza il tempo di attesa e offre all'utente la possibilità di annullare la richiesta di trasferimento.

  ############################
  # Agent Transfer
  ############################  

  # See if there are any agents available 
  
  evaluateAgentTransferCondition:
    component: "System.AgentTransferCondition"
    properties:
      maxWaitSeconds: 300
      maxEngagementsInQueue: 20
      allowTransferIf: "agentsAreAvailable"
      agentStatusVariable: "agentStatus"
    transitions:
      actions:
        conditionsMet: "askIfWillWait"
        conditionsNotMet: "setInsightsCustomMetricsConditionsNotMet"
        error: "handleTransferError"
      next: "done"
      
  # Measure when agents aren't available

  setInsightsCustomMetricsConditionsNotMet:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "No agents available for new chats"
    transitions:
      next: "handleRejected"      
                  
  askIfWillWait:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text:  "${rb('promptTextForTransferDecision','minutes,seconds',agentStatus.value.expectedWaitMinutes,agentStatus.value.expectedWaitSeconds)}"
            separateBubbles: true
            actions:
              - label: "Yes, I'll wait"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No, nevermind"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      actions:
        yes: "setInsightsCustomMetricsAgentTransferInitiated"
        no: "setInsightsCustomMetricsAgentTransferCancelled"
        textReceived: "intent"
      next: "handleCancelled"
      
  # Measure when user chooses to wait for transfer

  setInsightsCustomMetricsAgentTransferInitiated:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "User chose to wait"
    transitions:
      next: "transferToAgent"        
      
  # Measure when user chooses to not wait for transfer

  setInsightsCustomMetricsAgentTransferCancelled:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "User didn't want to wait"
    transitions:
      next: "handleCancelled"
      
  # Perform the actual transfer
  #
  # The maxWaitSeconds, maxEngagementsInQueue, allowTransferIf,
  # and customProperties, if any, should match those used for 
  # System.AgentTransferCondition 
  
  transferToAgent:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: 300
      maxEngagementsInQueue: 20
      allowTransferIf: "agentsAreAvailable"
    transitions:
      actions:
        accepted: "done"
        rejected: "handleRejected"
        error: "handleTransferError"
      next: "handleTransferError"
     
  ############################
  # All done
  ############################
                  
  done:
    component: "System.Output"
    properties:
      text: "Let me know if you need help on anything else."
    transitions:
      return: "done"  
      
  handleRejected:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text"
          text: > 
            Unfortunately, none of my colleagues are currently available to assist with this.
            Still, we’d love to see this through for you. 
            Please feel free to reach us through email@example.com.
    transitions:
      next: "done"
      
  handleCancelled:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "OK. Maybe some other time. Please feel free to reach us through email@example.com."
    transitions:
      next: "done"
      
  handleTransferError:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "Unfortunately, we can't transfer you at this time. Please try again later."
    transitions:
      next: "done"
      
  ############################
  # Global error handler
  ############################
  
  globalErrorHandler:
    component: "System.Output"
    properties:
     text: "Sorry, we were unable to do the action that you requested." 
    transitions:
      next: "done"

Lo stato askIfWillWait utilizza una voce di bundle di risorse per formare il messaggio del tempo di attesa in modo che il messaggio abbia senso se l'ora è più o meno di un minuto e se un numero è 0, uno o più.

There are some experts online. But it might take {minutes, plural,
     =-1 {}
     =0 {}
     =1 {1 minute and }
     other {# minutes and }
}{seconds, plural,
     =-1 {a while}
     =0 {{minutes, plural,
          =0 {a very short wait time}
          other {0 seconds}
        }}
     =1 {1 second}
     other {# seconds}
} for one to join. Are you willing to wait?

In questo esempio viene utilizzato System.SetCustomMetrics per tenere traccia della disponibilità degli agenti e, in tal caso, del numero di utenti che hanno scelto di attendere e del numero di utenti che hanno annullato la richiesta di trasferimento.

Se si desidera trasferire la conversazione di una skill a un agente di Oracle B2C Service, aggiungere questo componente al flusso della finestra di dialogo per avviare l'handshake con il canale di integrazione agente specificato dalla proprietà agentChannel. È necessario chiamare questo componente prima di chiamare il componente System.AgentConversation.

Questo componente si riferisce alle conversazioni che hanno origine nello skill. Non utilizzare questo componente per le conversazioni che hanno origine nella chat di Oracle B2C Service, come descritto in L'assistente digitale come struttura agente in azione.

Di seguito è riportato un esempio di utilizzo di questo componente per avviare l'handshake con l'istanza di Oracle B2C Service definita dal canale di integrazione dell'agente denominato ServiceCloudIntegration.

  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      agentChannel: "ServiceCloudIntegration"
      nlpResultVariable: "iResult"
      waitingMessage: "Waiting for an agent..."
      rejectedMessage: "Agents are not available right now."
      resumedMessage: "We're connecting you to an agent..."
      errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now."
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "tryAgain"
        error: "tryAgain"
   agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "ServiceCloudIntegration"
      nlpResultVariable: "iResult"
      exitKeywords: "bye, exit, take care, goodbye, quit"
      expiryMessage: "Your chat with the agent timed out."
      conclusionMessage: "Your chat with the agent has ended."
      waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
    transitions:
      next: "endPrompt"
      actions:
        agentLeft: "endPrompt"
        expired: "sessionExpired"
        error" "agentConversationError"

Suggerimento

Nelle competenze con versione piattaforma 21.04 e successive, i valori predefiniti per le proprietà agentActionsMessage, errorMessage, rejectedMessage, resumedMessage e waitingMessage vengono memorizzati nel bundle di risorse dello skill. Per modificare un'impostazione predefinita, aprire la pagina Bundle delle risorse della competenza, fare clic su , selezionare la scheda Configurazione e modificare il messaggio per la chiave AgentInitiation - <property name>. Se si utilizza il bundle di risorse dello skill per modificare il messaggio predefinito, non è necessario includere la proprietà del messaggio nel componente a meno che non si desideri eseguire l'override dell'impostazione predefinita.

Here are the available actions that you can send to transfer the conversation
back to the bot. Prepend the action with a forward slash (for example, /actionName).
/OrderPizza : Order Pizza : Order a pizza.
/ShowMenu : Show Menu : Show order options.

  agentInitiation:
    component: "System.AgentInitiation"
    ...
    properties:
      agentChannel: "ServiceCloudIntegration"
      agentActions:
      - action: "OrderPizza"
        label: "Order Pizza"
        description: "Order a pizza."
      - action: "ShowMenu"
        label: "Show Menu"
        description: "Show order options. "
      …
  agentConversation:
    component: "System.AgentConversation"
    ...
    transitions:
      next: "terminatedWithoutAction"
      actions:
        ShowMenu: "ShowMenu"
        OrderPizza: "OrderPizza"

{
  "sessionID": "string", // agent session id

  "completedSurveyID": {
    "id": "int"
  },

  "engagementID": { // survey id
    "id": "int"
  },

  "cancelledSurveyID": {
    "id": "int"
  }
}

Di seguito è riportato un esempio di gestione degli errori di sistema e delle azioni error e rejected.

  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      agentChannel: "B2CServiceIntegration"
      nlpResultVariable: "iResult"
      waitingMessage: "Let me connect you with someone who can further assist you."
      resumedMessage: "Someone will be with you shortly."
      errorMessage: "Oops! We're having system issues and we can't connect you with an agent right now."
      rejectedMessage: "Unfortunately, no one's available right now."     
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "initiationRejected"
        error: "tryAgain"
      error: "agentInitiationSystemError"
  initiationRejected:
    component: "System.Output"
    properties:
      text: "Perhaps it's outside their working hours or it's a holiday."
    transitions:
      return: "initiationRejected"
  tryAgain:
    component: "System.Output"
    properties:
      text: "Please try again later."
    transitions:
      return: "tryAgain"
  agentInitiationSystemError:
    component: "System.Output"
    properties:
      text: "I seem to be having a connection problem. Can you please email email@example.com to let them know?"
    transitions:
      return: "done"

context:
  variables:
    liveChatInfo: "map"
    customerTicketId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        incidentID: "${customerTicketId}" # long value
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

In questo esempio viene impostato il valore contactID.

context:
  variables:
    liveChatInfo: "map"
    contactId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation:
          contactID:
            id: "${customerId}"
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

In questo esempio vengono impostati interfaceID e contactID.

context:
  variables:
    liveChatInfo: "map"
    interfaceId: "int"
    contactId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation:
          interfaceID:
            id:
              id: "${interfaceId}"
          contactID:
            id: "${customerId}"
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

context:
  variables:
    liveChatInfo: "map"
...
  setupCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customFields:
          - name: "c$text_field"        # text field
            type: "STRING"
            value: "SILVER"
          - name: "c$text_area"         # text area
            type: "STRING"
            value: "My package arrived but there were no contents in the box. Just bubble wrap."
          - name: "c$integer"           # integer
            type: "INTEGER"
            value: 21
          - name: "c$yes_no"  # yes/no (1=yes and 0=no)
            type: "BOOLEAN"
            value: 1
          - name: "c$date_field"        # date (yyyy-MM-dd'T'00:00:00. Use 0 for time)
            type: "DATE"
            value: "2020-02-04T00:00:00+00:00" 
          - name: "c$date_time"         # datetime (yyyy-MM-dd'T'HH:mm:ssXXX)
            type: "DATETIME"
            value: "2020-02-04T21:24:18+00:00" 
          - name: "c$menu"              # menu (no type property, you can pass the string or the ID for the value property)
            value: "12"
    transitions:
      ...
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

context:
  variables:
    liveChatInfo: "map"
    skillType: "string"
...
  setupCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation: 
          interfaceID:
            id:
              id: 1     
        customFields:
# Text Field
          - name: "c$da_text_field"
            dataType: "STRING"
            dataValue:
              stringValue: "SILVER"
# Text Area
          - name: "c$da_text_area"
            dataType: "STRING"
            dataValue:
              stringValue: "This is a very long string that is more than 32 characters."
# Integer
          - name: "c$da_integer"
            dataType: "INTEGER"
            dataValue:
              integerValue: 21
# Menu
          - name: "c$da_menu"
            dataType: "NAMED_ID"
            dataValue: 
              namedIDValue:
                name: "Item 1"
# Instead of name, you can use
#                id:
#                  id: 1
#
# Yes/No
          - name: "c$da_is_from_skill"
            dataType: "BOOLEAN"
            dataValue:
              booleanValue: true
# Date (XML Schema Date)
          - name: "c$da_date"
            dataType: "DATE"
            dataValue:
              dateValue: "2019-10-26" 
# DateTime (XML Schema DateTime)
          - name: "c$da_datetime"
            dataType: "DATETIME"
            dataValue:
              dateTimeValue: "2019-10-26T21:32:52"               
    transitions:
      ...
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

In questi passaggi viene descritto come dichiarare l'oggetto customProperties e impostarne i vari valori.

Utilizzare questo componente per trasferire la conversazione di uno skill a un agente reale di Oracle B2C Service e per gestire l'interscambio agente live delle competenze. Prima di poter utilizzare questo componente, è necessario chiamare il componente System.AgentInitiation.

System.AgentConversation si riferisce alle conversazioni che hanno origine nella competenza. Non utilizzare questo componente per le conversazioni che hanno origine nella chat di Oracle B2C Service, come descritto in L'assistente digitale come struttura agente in azione.

Di seguito è riportato un esempio di utilizzo di questo componente per trasferire la conversazione all'istanza di Oracle B2C Service definita dal canale di integrazione dell'agente denominato ServiceCloudIntegration.

  agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "ServiceCloudIntegration"
      nlpResultVariable: "iResult"
      errorMessage: "Oops, we lost connection with the agent. If you need further help, please call customer support."
      exitKeywords: "bye, exit, take care, goodbye, quit"
      expiryMessage: "Your chat with the agent timed out"
      waitExpiryMessage: "The chat expired while waiting for an agent"
      conclusionMessage: "Your chat with the agent has ended."
      waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
    transitions:
      next: "endPrompt"
      actions:
        agentLeft: "endPrompt"
        expired: "sessionExpired"
        waitExpired: "expiredWhileWaiting"
        error: "handleConnectionError"

L'azione System.AgentConversation può attivare l'azione expired, agentLeft, error o waitExpired. Inoltre, può attivare qualsiasi azione dalla proprietà agentActions del componente System.AgentInitiation. È necessario aggiungere anche una transizione next, poiché un cliente potrebbe immettere una delle opzioni exitKeywords per uscire dalla chat prima che una di queste azioni possa essere attivata.

  agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "ServiceCloudIntegration"
      nlpResultVariable: "iResult"
      exitKeywords: "bye, adios, take care, goodbye"
      ...
    transitions:
      next: "endPrompt"
      actions:
        agentLeft: "endPrompt"
        expired: "endPrompt"
        waitExpired: "endPrompt"
        error: "agentConversationError"
  ...
  endPrompt:
    component: "System.List"
    properties: 
      prompt: "Your session has ended. What would you like to do?"
      options: 
      - label: "Order a Pizza"
        value: "OrderPizza" 
      - label: "Nothing. I'm done here."
        value: "Finished" 
      autoNumberPostbackActions: true
    transitions:
      actions:
        OrderPizza: "resolvePizzaSize"
        Finished: "done"
...
      
    

In questo esempio, l'intento GetAgent viene addestrato per comprendere le chiamate di soccorso come help me please!

intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        OrderPizza: "resolvesize"
        CancelPizza: "cancelorder"
        GetAgent: "agentInitiation"
        unresolvedIntent: "agentInitiation"

Di seguito sono riportati i passi di base per la configurazione del flusso della finestra di dialogo.

1. Avviare il trasferimento dell'agente attivo.

   1. Aggiungere uno stato per il componente System.AgentInitiation.

   2. Impostare la proprietà agentChannel dello stato sul nome del canale di integrazione agente configurato per il sistema live-agent.

   Dopo che il canale di integrazione dell'agente ha stabilito una connessione e Oracle B2C Service ha inviato la richiesta di chat alla relativa coda (ovvero dopo la creazione di un ticket di assistenza), il componente System.AgentInitiation consente la transizione allo stato successivo, in genere definito per il componente System.AgentConversation (agentConversation nell'esempio seguente).

   
     agentInitiation:
       component: "System.AgentInitiation"
       properties:
         agentChannel: "ServiceCloudIntegration"
         nlpResultVariable: "iResult"
         waitingMessage: "Waiting for an agent..."
         rejectedMessage: "Agents are not available right now."
         resumedMessage: "We're connecting you to an agent..."
         errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now."
       transitions:
         actions:
           accepted: "agentConversation"
           rejected: "tryAgain"
           error: "tryAgain"
     tryAgain:
       component: "System.Output"
       properties:
         text: "Please try again later."
       transitions:
         return: "tryAgain"

   Suggerimento

   I clienti possono richiedere ripetutamente una chat live anche se le loro richieste sono già state accodate nella console di chat dell'agente. Aggiungere una proprietà resumedMessage allo stato System.AgentInitiation per impedire a tali clienti di ricevere un messaggio ripresa della chat con l'agente fuorviante.

2. Aggiungere e configurare il componente System.AgentConversation. Mentre il motore della finestra di dialogo si trova nello stato definito per questo componente, lo skill passa i messaggi avanti e indietro tra il cliente e l'agente. La competenza ascolta le parole chiave di uscita nell'input del cliente, ad esempio bye. Quando lo skill rileva una di queste parole chiave, il componente System.AgentConversation termina la sessione di live chat e attiva la transizione next.

   Esempio:

     agentConversation:
       component: "System.AgentConversation"
       properties:
         agentChannel: "ServiceCloudIntegration"
         nlpResultVariable: "iResult"
         errorMessage: "Oops, we lost connection with the agent. If you need further help, please call customer support."
         exitKeywords: "bye, exit, take care, goodbye, quit"
         expiryMessage: "Your chat with the agent timed out."
         conclusionMessage: "Your chat with the agent has ended."
         waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
       transitions:
         next: "endPrompt"
         actions:
           agentLeft: "endPrompt"
           expired: "endPrompt"
           error: "endPrompt"
     endPrompt:
       component: "System.Output"
       properties:
         text: "Returning you to your bot."
       transitions:
         return: "endPrompt"

Nell'esempio seguente che utilizza il formato standard, il componente AgentConversation restituisce un collegamento al sondaggio al termine della conversazione con l'agente. Il collegamento include la sessione e l'ID coinvolgimento dalla mappa denominata dalla proprietà chatResponseVariable.

context:
  variables:
    agentSystemResponse: "map" # chat request response is stored in this variable.
    ...
states:
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      agentChannel: "B2CServiceIntegration"
      nlpResultVariable: "iResult"
      chatResponseVariable: "agentSystemResponse"  
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "tryAgain"
        error: "tryAgain"
  agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "B2CServiceIntegration"
      nlpResultVariable: "iResult"
      exitKeywords: "bye, exit, take care, goodbye, quit"
      expiryMessage: "Your chat with the agent timed out."
      conclusionMessage: "Can you please fill out this survey: <PUT SURVEY URL HERE>?session=${agentSystemResponse.value.sessionId}&surveyid=${agentSystemResponse.value.engagementId}"
    transitions:
      next: "endPrompt"
      actions:
        agentLeft: "endPrompt"
        expired: "sessionExpired"
        error: "agentConversationError"

1. Se non è già stata definita nel nodo di contesto una variabile di mappa da utilizzare con la proprietà customProperties del componente System.AgentInitiation. Ad esempio:

   context:
     variables:
       greeting: "string"
       name: "string"
       liveChatInfo: "map"
   

2. Definire i campi per la variabile mappa.

   Di seguito è riportato un esempio del formato standard per i canali di integrazione degli agenti creati nella versione 20.01 o successiva e che si connettono a Oracle B2C Service versione 19A o successiva.

     setLiveChatInfo:
       component: "System.SetVariable"
       properties:
         variable: "liveChatInfo"
         value:
           customFields: 
             - name: "c$frombot"
               type: "BOOLEAN"
               value: 1
       transitions:
         next: "agentInitiation"

   Di seguito è riportato un esempio del formato legacy per i canali di integrazione degli agenti creati prima della versione 20.01 o che si connettono a una versione precedente a Oracle B2C Service versione 19A.

     setLiveChatInfo:
       component: "System.SetVariable"
       properties:
         variable: "liveChatInfo"
         value:
           customFields: 
             - name: "c$frombot"
               dataType: "BOOLEAN"
               dataValue:
                 booleanValue: true
       transitions:
         next: "agentInitiation"

3. Aggiungere la proprietà customProperties al componente System.AgentInitiation e impostarla sul valore della variabile mappa. Ad esempio:

     agentInitiation:
       component: "System.AgentInitiation"
       properties:
         agentChannel: "B2CServiceIntegration"
         nlpResultVariable: "iResult"
         customProperties: "${liveChatInfo.value}"
         waitingMessage: "Waiting for an agent..."
         rejectedMessage: "Agents are not available right now."
         resumedMessage: "We're connecting you to an agent..."
         errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now."
       transitions:
         actions:
           accepted: "agentConversation"
           rejected: "tryAgain"
           error: "tryAgain"
     tryAgain:
       component: "System.Output"
       properties:
         text: "Please try again later."
       transitions:
         return: "tryAgain"

Per abilitare l'interazione tra uno skill e un provider di calendario, è necessario impostare un servizio e modificare lo skill e il flusso di finestre di dialogo per consentire all'utente di accedere al proprio calendario tramite tale servizio.

Prima di utilizzare qualsiasi componente di calendario, è necessario registrare un'applicazione presso il fornitore del calendario e creare un servizio di codici di autorizzazione. Per ulteriori informazioni, vedere questi argomenti:

• Registra un'applicazione con Google OAuth2 Autorizzazione

• Registrare un'applicazione con Microsoft Identity Platform

• Aggiungi un servizio codice autorizzazione

Nel flusso della finestra di dialogo, utilizzare il componente System.OAuth2AccountLink per richiedere all'utente di accedere al proprio calendario tramite il servizio di codici di autorizzazione creato. Tenere presente che non è possibile impostare la proprietà enableSingleSignOn del componente su true quando si utilizza il componente per l'autorizzazione del componente calendario.

È possibile utilizzare la funzione "richiede autorizzazione" per assicurarsi automaticamente che l'utente abbia eseguito l'accesso (ottenuto un token di accesso) prima di richiamare qualsiasi componente del calendario. Questa funzione richiede all'utente di accedere solo se non dispone ancora di un token di accesso o se è scaduto e non può essere aggiornato. È possibile utilizzare la configurazione Richiede autorizzazione dello skill per impostare l'impostazione predefinita per l'intera skill, quindi utilizzare l'impostazione requiresAuthorization a livello di stato per sostituire l'impostazione predefinita. In altre parole, si utilizza l'impostazione della competenza per impostare l'impostazione predefinita e quindi includere solo l'impostazione del componente requiresAuthorization negli stati per i quali l'impostazione predefinita non si applica.

Per utilizzare la funzione di autorizzazione obbligatoria, è necessario aggiungere un'azione system.authorizeUser al nodo defaultTransitions per assegnare un nome allo stato che avvia il flusso di autorizzazione. Ad esempio:

defaultTransitions:
  error: "globalErrorHandler"
  actions:
    system.authorizeUser: "userAuthN.performOAuth"

Prima che uno skill passi a uno stato che richiede l'autorizzazione, verifica se esiste un token di accesso valido per il servizio Calendar. In caso contrario, vengono eseguite le seguenti azioni:

1. Richiama lo stato definito per l'azione system.authorizedUser nel nodo defaultTransitions.

2. Chiede all'utente di accedere.

3. Esegue la transizione allo stato che richiede l'autorizzazione, ovvero lo stato definito da ${system.requestedState}.

Di seguito è riportato un esempio di flusso della finestra di dialogo di autorizzazione.

defaultTransitions:
  error: "globalErrorHandler"
  actions:
    system.authorizeUser: "userAuthN.performOAuth"

...

  ############################
  # Authenticate
  ############################
     
  userAuthN.performOAuth:
    component: "System.OAuth2AccountLink"
    properties:
      prompt: "User Authentication"
      variable: "code"
      linkLabel: "Sign into ${system.config.calendarProvider}"
      authenticationService: "${system.config.authService}"
      accessTokenVariableName: "user.accessToken"
      authenticatedUserVariableName: "user.authenticatedUser"
      enableSingleSignOn: false # SSO not supported for calendar components
    transitions:
      actions:
        pass : "${system.requestedState}"
        fail : "handleFailedLogin"
        textReceived: "intent"
  handleFailedLogin:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "Sorry, you aren't authorized to do that"
    transitions:
      return: "doneHandleFailedLogin" 

Per uno skill incentrato principalmente sui componenti del calendario, considerare di impostare la configurazione Richiede autorizzazione dello skill su true, quindi impostare il valore su falso solo per gli stati che non richiedono autorizzazione. In questo esempio, qualsiasi utente può eseguire gli stati initTimezoneOffset e intent. Pertanto, requiresAuthorization è impostato su false per tali stati. Gli stati che funzionano con i componenti del calendario non devono includere requiresAuthorization perché l'impostazione predefinita è true.

  initTimezoneOffset:
    requiresAuthorization: false
    component: "System.SetVariable"
    properties:
      variable: "timezoneOffset"
      value: <#attempt>${profile.timezoneOffset}<#recover>0</#attempt>      
    transitions:
      next: "intent"

  intent:
    component: "System.Intent"
    requiresAuthorization: false
    properties:
      variable: "iResult"
    transitions:
      actions:
        SetupMeeting: "setUpMeeting"
        CancelMeeting: "cancelMeeting"
        ListMeetings: "listMeetings"
        UpdateMeeting: "updateMeeting"
        ListInvites: "listInvites"
        RespondInvites: "respondInvites"
        LogoutUser: "logoutUser"
        unresolvedIntent: "greeting"

...
  cancelMeeting.performDelete:
    component: "System.DeleteCalendarEvent"
    properties:
      eventId: "${eventId}"
      provider: "${system.config.calendarProvider}"
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "cancelMeeting.printSuccessMessage"
  cancelMeeting.printSuccessMessage:
    component: "System.Output"
    properties:
      text: "I've cancelled the meeting"
    transitions:
      return: "doneCancel"

Quando si utilizzano i componenti del calendario, è importante comprendere la relazione tra le ore di inizio e di fine del calendario, le entità DATA e ORA e il fuso orario locale.

Quando si creano, si aggiornano o si recuperano eventi, si utilizza la data/ora locale per i valori start e end e si utilizza la proprietà timezoneOffset o timezone per indicare al componente come calcolare l'ora universale (UTC).

Il valore timezoneOffset dei componenti del calendario è diverso dal valore profile.timezoneOffset. Per i componenti calendario, timezoneOffset è il valore che il componente deve aggiungere ai valori start e end per ottenere il valore UTC. È possibile derivare il valore della proprietà timezoneOffset di un componente calendario moltiplicando profile.timezoneOffset per -1.

È possibile che profile.timezoneOffset non sia sempre disponibile. Ciò dipende dal fatto che il client abbia fornito l'offset. Ad esempio, qualcuno potrebbe creare un'applicazione Web Oracle che non imposta profile.timezoneOffset. Pertanto, è consigliabile creare un fuso orario predefinito per i casi in cui l' profile.timezoneOffset non è stato impostato. Ad esempio:

  initTimezoneOffset:
    requiresAuthorization: false
    component: "System.SetVariable"
    properties:
      variable: "timezoneOffset"
      value: <#attempt>${profile.timezoneOffset}<#recover>${system.config.defaultTimezoneOffset}</#attempt>      
    transitions:
      next: "intent

Quando si recupera un evento, il componente restituisce i valori di data e ora in formato UTC. Ad esempio, 2021-04-15T22:00:00.000Z. Lo skill deve convertire il valore nell'ora locale.

  updateMeeting.printEventDetails:
    component: "System.Output"
    properties:
      keepTurn: true
      text: |
        You selected:
        ${eventDetails.value.subject}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
        Location: ${eventDetails.value.location}        
        Attendees: ${eventDetails.value.attendees?join(', ')}     
    transitions:
      next: "updateMeeting.selectItemToChange"

Quando si utilizzano le entità DATA e ORA, ecco alcune cose da considerare:

• Se si utilizza un sacchetto composto con un'entità DATE e una o più entità TIME, è necessario disabilitare Estrazione fuori ordine. In caso contrario, quando le entità vengono risolte, non si dispone del controllo su quali valori vengono risolti nell'entità DATE e quali valori vengono risolti nell'entità TIME (o in entrambi). Ad esempio, quando l'ora viene risolta, potrebbe cambiare il valore dell'entità DATA.

• Quando un enunciato contiene testo come "ieri", "oggi" o "domani", il parser non prende in considerazione il fuso orario locale. Pertanto, è possibile che, al mattino presto e nel tardo pomeriggio, venga utilizzata la data sbagliata. Per questo motivo, è consigliabile riecheggiare la data risolta in modo che l'utente possa verificarla prima che l'abilità aggiunga un evento o aggiorni l'ora di inizio o di fine di un evento.

• Per impostare i valori delle proprietà start e end di un calendario, è necessario utilizzare la data dell'entità DATE e l'ora dell'entità TIME. Ad esempio:

        start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}"
        end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"

Il fornitore del calendario può rifiutare una richiesta di evento. Ad esempio, potrebbe essere restituito un errore se l'utente tenta di creare un evento con un'ora di fine precedente all'ora di inizio. Nella maggior parte dei casi, il provider del calendario restituisce un errore 400 che, a sua volta, esegue la transizione della competenza all'handler di errori globale.

Valutare la possibilità di convalidare i valori per evitare che si verifichino questi errori. Di seguito sono riportati alcuni esempi di convalide delle entità sacchetto composito.

• Entità data: per le riunioni nuove e aggiornate, verificare che la data sia uguale o successiva alla data corrente.

  ${(meetingSlot.value.date.date?number?long gte  ((.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']+'T00:00:00')?datetime.iso?long)?then('true','false')}

• entità TEMPO: per le riunioni nuove e aggiornate, verificare che la data e l'ora di inizio corrispondano o siano successive alla data/ora corrente.

  ${(((meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']+'T'+meetingSlot.value.startTime.date?number_to_date?string['HH:mm:ss'])?datetime.iso?long) gte (.now?date?long - timezoneOffset?number))?then('true','false')}

  Per tutte le ore di fine, verificare che l'ora di fine sia successiva all'ora di inizio.

  ${(newEvent.value.startTime.date?number_to_time < newEvent.value.endTime.date?number_to_time)?then('true','false')}

Per gestire in modo corretto i rifiuti del provider di calendario, aggiungere il proprio handler di errori globale. Ad esempio:

defaultTransitions:
  error: "globalErrorHandler"
  actions:
    system.authorizeUser: "userAuthN.performOAuth"

...

  globalErrorHandler:
    requiresAuthorization: false
    component: "System.Output"
    properties:
      text: "Sorry, we were unable to do the action that you requested."
    transitions:
      return: "done"

In alternativa, è possibile utilizzare la transizione di errore per creare handler di errori appropriati per ogni caso:

  setUpMeeting.performSchedule:
    component: "System.CreateCalendarEvent"
    properties:
      start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}"
      end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"
      subject: "${newEvent.value.subject}"
      location: "${newEvent.value.location}"
      attendees: "${newEvent.value.attendees}"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "setUpMeeting.printResults"
      error: "handleCreateEventError"

...

  handleCreateEventError:
    requiresAuthorization: false
    component: "System.Output"
    properties:
      text: "Sorry, there's a problem with the event that you wanted to create."
    transitions:
      return: "done"

Utilizzare questo componente per aggiungere un evento a un calendario di Outlook o Google. Tenere presente che non è possibile creare eventi ricorrenti o di tutti i giorni.

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

Per informazioni su come impostare i valori start e end, vedere Utilizzo di date e ore del calendario.

Di seguito è riportato un esempio di utilizzo di questo componente. In questo esempio, un'entità sacchetto composito viene utilizzata per ottenere la data, l'ora di inizio e di fine, l'oggetto, la posizione e i partecipanti.

  ####################
  # Create Meeting 
  ####################

  setUpMeeting:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      processUserMessage: true
      variable: "newEvent"
      nlpResultVariable: "iResult"     
      cancelPolicy: "immediate"
      transitionAfterMatch: "false"
      metadata:
        responseItems:       
          - type: "text"
            text: "${system.entityToResolve.value.prompt}"
            actions:
              - label: "${enumValue}"
                type: "postback"
                iteratorVariable: "system.entityToResolve.value.enumValues"
                payload:
                  variables:
                    newEvent: "${enumValue}"
        globalActions:
          - label: "Cancel"
            type: "postback"
            visible:
              onInvalidUserInput: false
            payload:
             action: "cancel"
    transitions:
      actions:
        cancel: "allDone"
      next: "setUpMeeting.askConfirm"       
  setUpMeeting.askConfirm:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: |
              Create ${newEvent.value.subject} meeting on ${newEvent.value.date.date?number_to_date?string['MMM d']}
              from ${newEvent.value.startTime.date?number_to_date?string['hh:mm a']} to ${newEvent.value.endTime.date?number_to_date?string['hh:mm a']}
              at ${newEvent.value.location} with ${newEvent.value.attendees}?
            name: "confirmCreate"
            separateBubbles: true
            actions:
              - label: "Yes"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      next: "intent"
      actions:
        yes: "setUpMeeting.performSchedule"
        no: "allDone"
        textReceived: "intent"      
  setUpMeeting.performSchedule:
    component: "System.CreateCalendarEvent"
    properties:
      start: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.startTime.date?number_to_date?string['HH:mm:ss']}"
      end: "${newEvent.value.date.date?number_to_date?string['yyyy-MM-dd']}T${newEvent.value.endTime.date?number_to_date?string['HH:mm:ss']}"
      subject: "${newEvent.value.subject}"
      location: "${newEvent.value.location}"
      attendees: "${newEvent.value.attendees}"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "setUpMeeting.printResults"
      error: "handleCreateCalendarError"
  setUpMeeting.printResults:
    component: "System.Output"
    properties:
      text: "The ${newEvent.value.date.date?number_to_date?string['MMM d']} meeting is now on your calendar."
      keepTurn: true
    transitions:
      next: "setUpMeeting.getMeetings"
...

Utilizzare questo componente per eliminare un evento da un calendario di Outlook o Google. Tenere presente che non è possibile eliminare gli eventi ricorrenti o di tutti i giorni.

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

Di seguito è riportato un esempio di utilizzo di questo componente.

  ####################
  # Cancel Meeting
  ####################
  
  # Want to select from deletable meetings

  cancelMeeting:
    component: "System.SetVariable"
    properties:
      variable: "stateAfterList"
      value: "cancelMeeting.confirmCancel"
    transitions:
      next: "cancelMeeting.setListType"
  cancelMeeting.setListType:
    component: "System.SetVariable"
    properties:
      variable: "listType"
      # Only show deletable meetings
      value: "DELETE"
    transitions:
      next: "cancelMeeting.setListPrompt"
  cancelMeeting.setListPrompt:
    component: "System.SetVariable"
    properties:
      variable: "listPrompt"
      value: "to cancel"
    transitions:
      next: "listMeetings.commonEntryPoint"

  # List meetings common code returns to this state
  cancelMeeting.confirmCancel:
    component: "System.ResetVariables"
    properties:
      variableList: "confirmAction"
    transitions:
      next: "cancelMeeting.askConfirm"      
  cancelMeeting.askConfirm:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Are you sure you want to cancel this meeting?"
            name: "confirmCcancel"
            separateBubbles: true
            actions:
              - label: "Yes"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      next: "intent"
      actions:
        yes: "cancelMeeting.performDelete"
        no: "allDone"
        textReceived: "intent"
  cancelMeeting.performDelete:
    component: "System.DeleteCalendarEvent"
    properties:
      eventId: "${eventId}"
      provider: "${system.config.calendarProvider}"
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "cancelMeeting.printSuccessMessage"
  cancelMeeting.printSuccessMessage:
    component: "System.Output"
    properties:
      text: "I've cancelled the meeting"
    transitions:
      return: "doneCancel"
  ...

  ############################
  # List Meetings Shared Code
  ############################
  
  listMeetings.commonEntryPoint:
    component: "System.SetVariable"
    properties:
      variable: "inputDate"
      value: "${iResult.value.entityMatches['DATE'][0]}"
    transitions:
      next: "listMeetings.setDate"
  listMeetings.setDate:
    component: "System.SetVariable"
    properties:
      variable: "start"
      value: "${inputDate.value?has_content?then(inputDate.value.date?number_to_date?string['yyyy-MM-dd'], (.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd'])}T00:00:00"
    transitions:
      next: "listMeetings.clearInputDate"  
  listMeetings.clearInputDate:
    component: "System.ResetVariables"
    properties:
      variableList: "inputDate"
    transitions:
      next: "listMeetings.filterByAttendees"
  listMeetings.filterByAttendees:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Do you want to list only meetings with a particular attendee?"
            name: "confirmFilter"
            separateBubbles: true
            actions:
              - label: "Yes"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      next: "intent"
      actions:
        yes: "listMeetings.resolveAttendeesFilter"
        no: "listMeetings.clearAttendeesFilter"
        textReceived: "intent"

  # clear filter 
  
  listMeetings.clearAttendeesFilter:
    component: "System.ResetVariables"
    properties:
      variableList: "attendees"
    transitions:
      next: "listMeetings.performList"

  # resolve filter

  listMeetings.resolveAttendeesFilter:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      processUserMessage: true
      variable: "attendees"
      nlpResultVariable: "iResult"
      metadata:
        responseItems:
          - type: "text"
            text: "Who is the attendee?"
    transitions:
      next: "listMeetings.performAttendeesList"
      actions:
        textReceived: "listMeetings.performAttendeesList"

  # perform attendees list 

  listMeetings.performAttendeesList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "${listType}"
      start: "${start}"
      attendees: "${attendees}"
      prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      actions:
        found: "${stateAfterList}"
        notfound: "listMeetings.printNotFoundMessage"
      next: "globalErrorHandler"

  # perform list 

  listMeetings.performList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "${listType}"
      start: "${start}"
      prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      actions:
        found: "${stateAfterList}"
        notfound: "listMeetings.printNotFoundMessage"
      next: "globalErrorHandler"

  listMeetings.printNotFoundMessage:
    component: "System.Output"
    properties:
      text: "There are no meetings on ${start?datetime.iso?long?number_to_date?string['MMM d']}"
    transitions:
      return: "doneListMeetings"
...

Utilizzare questo componente per ottenere i dettagli di un evento da un calendario di Outlook o Google.

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

I dettagli vengono restituiti nella variabile specificata dalla proprietà eventDetailsVariableName nel seguente formato JSON:

{
  "isAllDay": boolean,
  "subject": string,
  "inviteResponse": string,
  "attendees": [
    "string",
      ...
  ],
  "start": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
  "end":  format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
  "location": string,
  "isRecurring": boolean,
  "id": string
}

Le proprietà start e end sono valori UTC. Per informazioni su come convertire i valori start e end in ora locale, vedere Utilizzo di date e ore del calendario.

Di seguito è riportato un esempio di utilizzo di questo componente.

  listMeetings.performGetDetails:
    component: "System.GetCalendarEventDetails"
    properties:
      eventId: "${eventId}"
      eventDetailsVariableName: "eventDetails"
      provider: "${system.config.calendarProvider}"
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "listMeetings.checkIfResults"
  # In case the eventId is no longer valid
  listMeetings.checkIfResults:
    component: "System.ConditionExists"
    properties:
      variable: "eventDetails"
    transitions:
      actions:
        exists: "listMeetings.printEventDetails"
        notexists: "globalErrorHandler" 
  listMeetings.printEventDetails:
    component: "System.Output"
    properties:
      text: |
        ${eventDetails.value.subject}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
        Location: ${eventDetails.value.location}        
        Attendees: ${eventDetails.value.attendees?join(', ')} 
    transitions:
      return: "doneGetDetails"

Utilizzare questo componente per ottenere una serie di eventi di Outlook o Google per un proprietario di calendario denominato. È possibile filtrare l'elenco in base ai seguenti attributi:

• L'evento può essere eliminato
• L'evento può essere aggiornato
• L'utente è stato invitato all'evento
• Modalità di risposta dell'utente a un invito
• L'evento include uno o più partecipanti denominati
• La riunione inizia dopo una data e un'ora
• La riunione termina prima di una data e un'ora

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

La lista viene restituita nella variabile specificata dalla proprietà eventListVariableName nel seguente formato JSON:

[{
  "isAllDay": boolean,
  "subject": string,
  "inviteResponse": string,
  "start": format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
  "end":  format yyyy-MM-dd'T'HH:mm:ss.SSSZ,
  "isRecurring": boolean,
  "id": string
}, …]

Per informazioni su come impostare i valori start e end, vedere Utilizzo di date e ore del calendario. In questo argomento viene inoltre illustrato come convertire i valori delle proprietà JSON start e end in ora locale.

Di seguito è riportato un esempio di utilizzo di questo componente.

  ############################
  # List Invites
  ############################

  listInvites:
    component: "System.ListCalendarEvents"
    properties:
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
      listType: "INVITED"
      response: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
      eventListVariableName: "eventList"
      start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
    transitions:
      next: "globalErrorHandler"
      actions:
        found: "listInvites.printMeetings"
        notfound: "listInvites.notFound"
  listInvites.printMeetings:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:
        - type: "text"
          # display the local time
          text: |
            ${eventList.subject} [${eventList.inviteResponse}]
            ${(eventList.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d hh:mm a']} to ${(eventList.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}           
          name: "event"
          separateBubbles: true
          iteratorVariable: "eventList"
      processUserMessage: false
    transitions:
      return: "listInvitesDone"
  listInvites.notFound:
    component: "System.Output"
    properties:
      keepTurn: true
      text: "You don't have any invitations for the next 14 days"
    transitions:
      return: "listInvitesDone"      

Questo componente può restituire le seguenti azioni:

Utilizzare questo componente per visualizzare un elenco di eventi di Outlook o Google tra cui l'utente può effettuare la selezione. Il componente salva l'ID dell'evento selezionato nella variabile specificata dalla proprietà eventIdVariableName.

È possibile filtrare l'elenco in base ai seguenti attributi:

• L'evento può essere eliminato
• L'evento può essere aggiornato
• L'utente è stato invitato all'evento
• Modalità di risposta dell'utente a un invito
• L'evento include uno o più partecipanti denominati
• La riunione inizia dopo una data e un'ora
• La riunione termina prima di una data e un'ora

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

Per informazioni su come impostare i valori start e end, vedere Utilizzo di date e ore del calendario.

Di seguito è riportato un esempio di utilizzo di questo componente.

  ############################
  # Respond Invites
  ############################
      
  respondInvites.performList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "INVITED"
      response: "${inviteFilter}"
      # Note: For list type INVITED the default end date is 14 days after the start date and time.
      start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
      prompt: "Select the invitation to send the response to:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "globalErrorHandler"
      actions:
        found: "respondInvites.resolveInviteResponse"
        notfound: "respondInvites.printNotFoundMessage"

  respondInvites.printNotFoundMessage:
    component: "System.Output"
    properties:
      text: "There are no meeting invites."
    transitions:
      return: "allDone"
  ...

Proprietà	descrizione;	Richiesto?
provider	Il fornitore del calendario. I valori consentiti sono Google e Outlook.	Sì
calendarOwner	L'ID utente del proprietario del calendario. Deve essere un ID account valido per il provider di calendario, ad esempio il valore della variabile identificata dalla proprietà authenticatedUserVariable del componente System.OAuth2AccountLink, impostata quando l'utente esegue l'autenticazione.	Sì
calendarId	Nome del calendario. Per il calendario predefinito dell'utente, impostare lo stesso valore della proprietà calendarOwner.	Sì
credential	Token di accesso del provider. Si tratta del valore della variabile identificata dalla proprietà accessTokenVariableName del componente System.OAuth2AccountLink, impostata quando l'utente esegue l'autenticazione.	Sì
listType	Indica il tipo di elenco. Deve essere uno dei seguenti: ALL: tutti i tipi di riunioni del proprietario del calendario DELETE: tutte le riunioni che il proprietario del calendario può eliminare UPDATE: tutte le riunioni che il proprietario del calendario può aggiornare INVITED: Tutte le riunioni che non sono organizzate dal proprietario del calendario ma il proprietario è invitato a partecipare.	Sì
eventIdVariableName	Nome della variabile di contesto in cui memorizzare l'ID dell'evento.	Sì
start	La prima data e ora in cui le riunioni devono essere incluse nell'elenco (formato: yyyy-MM-dd'T'HH:mm:ss). Ad esempio, 2021-02-26T09:55:00.	Sì
end	L'ultima data e ora per le quali le riunioni devono essere incluse nell'elenco (formato: yyyy-MM-dd'T'HH:mm:ss). Ad esempio, 2021-02-26T09:55:00. Per il tipo di elenco INVITED, l'impostazione predefinita è 14 giorni dopo la data e l'ora di inizio. Per tutti gli altri tipi, l'impostazione predefinita è 24 ore dopo la data e l'ora di inizio.	No
attendees	Elenco separato da virgole e senza distinzione tra maiuscole e minuscole delle stringhe da utilizzare per filtrare la lista in base ai partecipanti. Nell'output vengono incluse solo le riunioni in cui uno o più valori partecipante contengono una o più stringhe nell'elenco.	No
response	Una lista separata da virgole di stati di invito per filtrare la lista quando listType è INVITED. Gli stati consentiti sono descritti di seguito. ACCEPTED TENTATIVE DECLINED PENDING L'impostazione predefinita è PENDING,TENTATIVE, che restituisce solo gli inviti che sono in attesa di una risposta o che sono stati accettati provvisoriamente.	No
prompt	Il testo visualizzato prima dell'elenco. L'impostazione predefinita è You have the following meeting(s): Non è necessario includere questa proprietà a meno che non si desideri eseguire l'override dell'impostazione predefinita. Suggerimento Negli skill con versione piattaforma 21.04 e successive, il valore predefinito viene memorizzato nel bundle di risorse dello skill. Per modificare l'impostazione predefinita, aprire la pagina Bundle delle risorse dello skill, fare clic su , selezionare la scheda Configurazione e modificare il messaggio per la chiave SelectCalendarEvent - prompt.	No
allDayLabel	Testo per indicare gli eventi di tutto il giorno. Il valore predefinito è All day.	No
recurringLabel	Testo per indicare un evento ricorrente. L'impostazione predefinita è Recurring.	No
acceptedLabel	Testo che indica che il proprietario del calendario ha accettato l'invito. L'impostazione predefinita è Accepted.	No
tentativeLabel	Testo che indica che il proprietario del calendario ha accettato provvisoriamente l'invito. L'impostazione predefinita è Tentative.	No
declinedLabel	Testo che indica che il proprietario del calendario ha rifiutato l'invito. L'impostazione predefinita è Declined.	No
pendingLabel	Testo che indica che il proprietario del calendario non ha risposto all'invito. L'impostazione predefinita è Pending.	No
timezoneOffset	Il periodo di tempo in millisecondi da aggiungere al tempo universale (UTC) per ottenere l'ora standard nel fuso orario dell'utente. Ad esempio, se il fuso orario locale è UTC-2, timezoneOffset è -7200000. Il valore predefinito è zero. Nota È possibile derivare la proprietà timezoneOffset per l'utente corrente in base al valore della variabile di contesto utente profile.timezoneOffset. In tal caso, tuttavia, è necessario moltiplicare profile.timezoneOffset per -1. È possibile specificare timezoneOffset o timezone, ma non entrambi.	No
timezone	ID del fuso orario locale identificato da https://www.iana.org/time-zones. Anche denominato nome del database del fuso orario. Ad esempio: America/Los_Angeles. L'impostazione predefinita è UTC. È possibile specificare timezoneOffset o timezone, ma non entrambi.	No

Questo componente può restituire le seguenti azioni:

Utilizzare questo componente per accettare, accettare provvisoriamente o rifiutare un invito per un evento di calendario di Outlook o Google.

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

Di seguito è riportato un esempio di utilizzo di questo componente.

  ############################
  # Respond Invites
  ############################
      
  respondInvites:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Which types of meeting invitations do you want to respond to?"
            name: "getInviteFilter"
            separateBubbles: true
            actions:
              - label: "Pending and tentatively accepted invitations"
                type: "postback"
                keyword: "PENDING,TENTATIVE"
                payload:
                  variables: 
                    inviteFilter: "PENDING,TENTATIVE"
              - label: "All invitations"
                keyword: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
                type: "postback"                
                payload:
                  variables: 
                    inviteFilter: "PENDING,ACCEPTED,TENTATIVE,DECLINED"
              - label: "Cancel"
                keyword: "cancel"
                type: "postback"                
                payload:
                  action: "allDone" 
    transitions:
      actions:
        allDone: "allDone"
        textReceived: "intent" 
      next: "respondInvites.performList"
  respondInvites.performList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "INVITED"
      response: "${inviteFilter}"
      # Note: For list type INVITED the default end date is 14 days after the start date and time.
      start: "${(.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd']}T00:00:00"
      prompt: "Select the invitation to send the response to:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "globalErrorHandler"
      actions:
        found: "respondInvites.resolveInviteResponse"
        notfound: "respondInvites.printNotFoundMessage"
  respondInvites.printNotFoundMessage:
    component: "System.Output"
    properties:
      text: "There are no meeting invites."
    transitions:
      return: "allDone"

  ############################
  # Invite Response
  ############################
      
  respondInvites.resolveInviteResponse:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Choose a response:"
            name: "getInviteResponse"
            separateBubbles: true
            actions:
              - label: "Accept"
                type: "postback"
                keyword: "ACCEPTED"
                payload:
                  variables: 
                    inviteResponse: "ACCEPTED"
              - label: "Tentatively accept"
                keyword: "TENTATIVE"
                type: "postback"                
                payload:
                  variables: 
                    inviteResponse: "TENTATIVE"
              - label: "Decline"
                keyword: "DECLINED"
                type: "postback"                
                payload:
                  variables: 
                    inviteResponse: "DECLINED"
              - label: "Don't send a response"
                keyword: "CANCEL"
                type: "postback"                
                payload:
                  action: "allDone" 
    transitions:
      actions:
        allDone: "allDone"
        textReceived: "intent" 
      next: "respondInvites.performRespond"
  respondInvites.performRespond:
    component: "System.SendInviteResponse"
    properties:
      eventId: "${eventId}"
      response: "${inviteResponse}"
      provider: "${system.config.calendarProvider}"
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions: 
      next: "respondInvites.printSuccessMessage"
  respondInvites.printSuccessMessage:
    component: "System.Output"
    properties:
      text: "I've sent the meeting invitation response"
    transitions:
      return: "doneSendInviteResponse"

Utilizzare questo componente per apportare modifiche a un evento di calendario di Outlook o Google. Tenere presente che non è possibile aggiornare gli eventi ricorrenti o di tutti i giorni.

Per accedere a questo componente, è necessario che l'utente abbia effettuato l'accesso al provider del calendario. È possibile utilizzare la funzione "richiede autorizzazione" per gestire l'accesso utente, come descritto in Autorizzazione calendario.

Per informazioni su come impostare i valori start e end, vedere Utilizzo di date e ore del calendario.

Di seguito è riportato un esempio di utilizzo di questo componente. In questo esempio, un'entità sacchetto composito viene utilizzata per ottenere la data, l'ora di inizio e l'ora di fine.

  ####################
  # Update Meeting 
  ####################
 
  updateMeeting:
    component: "System.SetVariable"
    properties:
      variable: "stateAfterList"
      value: "updateMeeting.performGetDetails"
    transitions:
      next: "updateMeeting.setListType"
  updateMeeting.setListType:
    component: "System.SetVariable"
    properties:
      variable: "listType"
      # Only show updateable meetings
      value: "UPDATE"
    transitions:
      next: "updateMeeting.setListPrompt"
  updateMeeting.setListPrompt:
    component: "System.SetVariable"
    properties:
      variable: "listPrompt"
      value: "to update"
    transitions:
      next: "listMeetings.commonEntryPoint"

  # List meetings common code returns to this state
  updateMeeting.performGetDetails:
    component: "System.GetCalendarEventDetails"
    properties:
      eventId: "${eventId}"
      eventDetailsVariableName: "eventDetails"
      provider: "${system.config.calendarProvider}"
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "updateMeeting.checkIfResults"      
  updateMeeting.checkIfResults:
    component: "System.ConditionExists"
    properties:
      variable: "eventDetails"
    transitions:
      actions:
        exists: "updateMeeting.printEventDetails"
        notexists: "globalErrorHandler"  
  updateMeeting.printEventDetails:
    component: "System.Output"
    properties:
      keepTurn: true
      text: |
        You selected:
        ${eventDetails.value.subject}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['MMM d']}
        ${(eventDetails.value.start?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}-${(eventDetails.value.end?datetime.iso?long - timezoneOffset?number?long)?number_to_date?string['hh:mm a']}
        Location: ${eventDetails.value.location}        
        Attendees: ${eventDetails.value.attendees?join(', ')}     
    transitions:
      next: "updateMeeting.updateTime"

  # Change meeting time
      
  updateMeeting.updateTime:
    component: "System.ResolveEntities"
    properties:
      variable: "meetingSlot"
      nlpResultVariable: "iResult"      
      maxPrompts: 5
      cancelPolicy: "immediate" 
    transitions:
      actions:
        cancel: "allDone"
      next: "updateMeeting.setStart"      
  updateMeeting.setStart:
    component: "System.SetVariable"
    properties:
      variable: "start"
      value: "${meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']}T${meetingSlot.value.startTime.date?number_to_date?string['HH:mm:ss']}"
    transitions:
      next: "updateMeeting.setEnd"
  updateMeeting.setEnd:
    component: "System.SetVariable"
    properties:
      variable: "end"
      value: "${meetingSlot.value.date.date?number_to_date?string['yyyy-MM-dd']}T${meetingSlot.value.endTime.date?number_to_date?string['HH:mm:ss']}"
    transitions:
      next: "updateMeeting.updateTime.performUpdate"
  updateMeeting.updateTime.performUpdate:
    component: "System.UpdateCalendarEvent"
    properties:
      eventId: "${eventId}"
      start: "${start}"
      end: "${end}"
      provider: "${system.config.calendarProvider}"
      #timezone: "${system.config.timezoneID}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      next: "updateMeeting.printSuccessMessage"
      error: "handleUpdateCalendarError"
  ...

  ############################
  # List Meetings Shared Code
  ############################
  
  listMeetings.commonEntryPoint:
    component: "System.SetVariable"
    properties:
      variable: "inputDate"
      value: "${iResult.value.entityMatches['DATE'][0]}"
    transitions:
      next: "listMeetings.setDate"
  listMeetings.setDate:
    component: "System.SetVariable"
    properties:
      variable: "start"
      value: "${inputDate.value?has_content?then(inputDate.value.date?number_to_date?string['yyyy-MM-dd'], (.now?date?long - timezoneOffset?number?long)?number_to_date?string['yyyy-MM-dd'])}T00:00:00"
    transitions:
      next: "listMeetings.clearInputDate"  
  listMeetings.clearInputDate:
    component: "System.ResetVariables"
    properties:
      variableList: "inputDate"
    transitions:
      next: "listMeetings.filterByAttendees"
  listMeetings.filterByAttendees:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Do you want to list only meetings with a particular attendee?"
            name: "confirmFilter"
            separateBubbles: true
            actions:
              - label: "Yes"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      next: "intent"
      actions:
        yes: "listMeetings.resolveAttendeesFilter"
        no: "listMeetings.clearAttendeesFilter"
        textReceived: "intent"

  # clear filter 
  
  listMeetings.clearAttendeesFilter:
    component: "System.ResetVariables"
    properties:
      variableList: "attendees"
    transitions:
      next: "listMeetings.performList"

  # resolve filter

  listMeetings.resolveAttendeesFilter:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      processUserMessage: true
      variable: "attendees"
      nlpResultVariable: "iResult"
      metadata:
        responseItems:
          - type: "text"
            text: "Who is the attendee?"
    transitions:
      next: "listMeetings.performAttendeesList"
      actions:
        textReceived: "listMeetings.performAttendeesList"

  # perform attendees list 

  listMeetings.performAttendeesList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "${listType}"
      start: "${start}"
      attendees: "${attendees}"
      prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      actions:
        found: "${stateAfterList}"
        notfound: "listMeetings.printNotFoundMessage"
      next: "globalErrorHandler"

  # perform list 

  listMeetings.performList:
    component: "System.SelectCalendarEvent"
    properties:
      listType: "${listType}"
      start: "${start}"
      prompt: "Choose the ${start?datetime.iso?long?number_to_date?string['MMM d']} meeting ${listPrompt}:"
      eventIdVariableName: "eventId"
      provider: "${system.config.calendarProvider}"
      timezoneOffset: ${timezoneOffset?number * -1}
      calendarOwner: "${user.authenticatedUser}"
      calendarId: "${user.authenticatedUser}"
      credential: "${user.accessToken}"
    transitions:
      actions:
        found: "${stateAfterList}"
        notfound: "listMeetings.printNotFoundMessage"
      next: "globalErrorHandler"

  listMeetings.printNotFoundMessage:
    component: "System.Output"
    properties:
      text: "There are no meetings on ${start?datetime.iso?long?number_to_date?string['MMM d']}"
    transitions:
      return: "doneListMeetings"
...

In questo esempio, la variabile type contiene i valori previsti dall'entità PizzaType, ad esempio cheese, Veggie Lover e Hawaiian. Quando queste informazioni non sono presenti nell'input utente, il bot può comunque ottenerle perché il relativo flusso di finestre di dialogo passa allo stato type, il cui componente System.Text richiede loro di indicare in modo esplicito ciò che desiderano. Tenere presente che anche a questo punto, l'input utente deve ancora essere risolto nell'entità PizzaType per passare allo stato successivo.

main: true
name: "PizzaBot"
parameters:
  age: 18
context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    iResult: "nlpresult"

...

  type:
    component: "System.Text"
    properties:
      prompt: "What Type of Pizza do you want?"
      variable: "type"
    transitions:
      ...

È possibile utilizzare il componente System.List per restituire un valore che soddisfa una variabile di contesto definita come primitiva (ad esempio greeting: "string" nel modello di flusso della finestra di dialogo) o come entità, come mostrato nello snippet seguente. In questo flusso di dialogo, la definizione options: "Thick,Thin,Stuffed,Pan" restituisce un valore che corrisponde alla variabile crust. La proprietà options definita per la dimensione è un'espressione di valore (${size.type.enumValues}) che restituisce i valori degli elenchi Grande, Medio, Piccolo e Personale come opzioni. Vedere Apache FreeMarker Template Language Syntax.

In questo esempio viene inoltre illustrato come la definizione iResult della proprietà nlpResultVariable consenta al componente di impostare i valori di entità per le proprietà variable per gli stati crust e size quando questi valori non sono stati impostati in precedenza. Analogamente al componente Text, il componente System.List non richiede transizioni.

main: true
name: "PizzaBot"

...

context:
  variables:
    size: "PizzaSize"
    crust: "PizzaCrust"
    iResult: "nlpresult"

...

states:

...

crust:
  component: "System.List"
  properties:
    options: "Thick,Thin,Stuffed,Pan"
    prompt: "What crust do you want for your pizza?"
    variable: "crust"
main: true
name: "PizzaBot"

...

context:
  variables:
    size: "PizzaSize"
    crust: "PizzaCrust"
    iResult: "nlpresult"
...

states:

...

crust:
   component: "System.List"
   properties:
     options: "Thick,Thin,Stuffed,Pan"
     prompt: "What crust do you want for your pizza?"
     variable: "crust"
     nlpResultVariable: "iresult"
   transitions:
     next: "size"
size:
   component: "System.List"
   properties:
     options: "${size.type.enumValues}"
       prompt: "What size Pizza do you want?"
       variable: "size"
       nlpResultVariable: "iresult"
    transitions:
      ...

Nota

Gli utenti non sono limitati alle opzioni visualizzate nell'elenco. Possono risolvere l'entità inserendo una parola che l'entità riconosce, come un sinonimo. Anziché scegliere tra le opzioni relative alle dimensioni della pizza nell'elenco, ad esempio, gli utenti possono immettere grande, sinonimo definito per l'opzione grande dell'entità PizzaSize. Vedere Entità personalizzate.

done:
    component: "System.Output"
    properties:
      text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."

  wait:
    component: "System.Output"
    properties:
      text: "Please wait, we're reviewing your order"
      keepTurn: true
    transitions:
      next: "ready"
 waitmore:
    component: "System.Output"
    properties:
      text: "Almost done..."
      keepTurn: true
    transitions:
      next: "done"
  done:
    component: "System.Output"
    properties:
      text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."
    transitions:
      return: "done"