Die Konfiguration von System.CommonResponse-Komponenten beinhaltet das Festlegen von Eigenschaften, die Dialog-Engine zusammen mit Metadateneigenschaften leiten, die nicht nur beschreiben, wie die Komponente Nachrichten zustellt (als Texteingabeaufforderungen, Karten oder Anhänge), sondern auch den Inhalt und das Verhalten für die Nachrichten selbst festlegen.

Im Folgenden finden Sie die YAML für einen Beispielstatus basierend auf der Komponente 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"
...
      

Im Folgenden finden Sie ein einfaches Beispiel für den Zugriff auf die Attributwerte eines Interviews:

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
  ...

Das folgende Diagramm veranschaulicht, wie Sie die Single State-Methode implementieren, wenn Ihr Dialogablauf im YAML-Modus erstellt wird. 1) Sie verwenden eine Map-Kontextvariable, um die Knowledge Intents mit Suchbegriffen zu verknüpfen. 2) Sie legen die Aktion im Status Intent, um zu einem Datenfluss zu wechseln, der die Zuordnung verwendet, um die Kontextvariable searchTerm auf den Suchbegriff des Intents festzulegen. 3) Sie wechseln dann zu einem Status, der die Wissensdatenbank nach dem Wert searchTerm durchsucht.

Beschreibung der Abbildung kf-assoc-intent-term.png

Im Folgenden finden Sie ein Beispiel für einen Dialogablauf, in dem für jede Knowledge-Base-Antwort individuelle Intents vorhanden sind.

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"

Das folgende Beispiel zeigt, wie Sie die searchTerm auf die Äußerung des Benutzers in einem YAML-Dialogskill festlegen. Bei einem visuellen Dialogskill verwenden Sie stattdessen ${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"

Nachfolgend finden Sie ein Beispiel für einen Dialogablauf, bei dem der Chat an einen Agent übertragen wird, wenn der Kunde mit einem Agent sprechen möchte:

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"

Wenn Sie eine Unterhaltung von einem digitalen Assistenten an einen Live-Agent übertragen, können Sie diese Informationen mit benutzerdefinierten Eigenschaften in der Komponente System.AgentTransfer übergeben.

Struktur für Oracle B2C Service:

      customProperties:
        - name: 
          value: 
          type:

Die Eigenschaft type ist für benutzerdefinierte Felder erforderlich. Andernfalls ist sie optional.

Die Struktur von Oracle Fusion Service lautet wie folgt:

      customProperties:
        - name: 
          value:

Beispiel für die Einstellung customProperties für 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"

Im Folgenden finden Sie ein Beispiel für einen Dialogablauf, der die Komponente aufruft, die Wartezeit anzeigt und dem Benutzer die Möglichkeit gibt, seine Transferanforderung abzubrechen.

  ############################
  # 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"

Der Status askIfWillWait verwendet einen Resource Bundle-Eintrag, um die Wartezeitnachricht zu bilden, sodass die Nachricht sinnvoll ist, ob die Zeit mehr oder weniger als eine Minute beträgt und ob eine Zahl 0, eine oder mehrere ist.

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?

Beachten Sie, dass in diesem Beispiel System.SetCustomMetrics verwendet wird, um zu verfolgen, ob Agents verfügbar waren, und wenn ja, wie viele Benutzer gewartet haben und wie viele die Transferanforderung abgebrochen haben.

Wenn Sie die Unterhaltung eines Skills an einen Oracle B2C Service-Agent übertragen möchten, fügen Sie diese Komponente dem Dialogablauf hinzu, um den Handshake mit dem Agent-Integrationskanal zu starten, der mit der Eigenschaft agentChannel angegeben wird. Sie müssen diese Komponente aufrufen, bevor Sie die Komponente System.AgentConversation aufrufen können.

Diese Komponente ist für Unterhaltungen bestimmt, die aus dem Skill stammen. Verwenden Sie diese Komponente nicht für Unterhaltungen, die aus einem Oracle B2C Service-Chat stammen, wie in Digital Assistant-Agent-Framework in Aktion beschrieben.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente, um den Handshake mit der Oracle B2C Service-Instanz zu initiieren, die vom Agent-Integrationskanal mit dem Namen ServiceCloudIntegration definiert wird.

  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"

Tipp:

In Skills mit Plattformversion 21.04 und höher werden die Standardwerte für die Eigenschaften agentActionsMessage, errorMessage, rejectedMessage, resumedMessage und waitingMessage im Resource Bundle des Skills gespeichert. Um einen Standardwert zu ändern, öffnen Sie die Seite Resource Bundle des Skills, klicken Sie auf , wählen Sie die Registerkarte Konfiguration aus, und ändern Sie die Nachricht für den Schlüssel AgentInitiation - <Eigenschaftsname>. Wenn Sie das Resource Bundle des Skills verwenden, um die Standardnachricht zu ändern, müssen Sie die Nachrichteneigenschaft nur in die Komponente aufnehmen, wenn Sie den Standardwert außer Kraft setzen möchten.

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"
  }
}

Nachfolgend finden Sie ein Beispiel für die Verarbeitung von Systemfehlern und der error- und rejected-Aktionen.

  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 diesem Beispiel wird contactID festgelegt.

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 diesem Beispiel werden interfaceID und contactID festgelegt.

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 diesen Schritten wird beschrieben, wie Sie das Objekt customProperties deklarieren und die verschiedenen Werte festlegen können.

Mit dieser Komponente können Sie die Unterhaltung eines Skills an einen Oracle B2C Service-Live-Agent übertragen und den Austausch zwischen Skill und Live-Agent verwalten. Beachten Sie, dass Sie die Komponente System.AgentInitiation aufrufen müssen, bevor Sie diese Komponente verwenden können.

System.AgentConversation ist für Unterhaltungen bestimmt, die aus dem Skill stammen. Verwenden Sie diese Komponente nicht für Unterhaltungen, die aus einem Oracle B2C Service-Chat stammen, wie in Digital Assistant-Agent-Framework in Aktion beschrieben.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente zur Übertragung der Unterhaltung an die Oracle B2C Service-Instanz, die vom Agent-Integrationskanal mit dem Namen ServiceCloudIntegration definiert wird.

  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"

Die Aktion System.AgentConversation kann die Aktion expired, agentLeft, error oder waitExpired auslösen. Außerdem kann sie jede Aktion aus der Eigenschaft agentActions der Komponente System.AgentInitiation auslösen. Sie müssen auch einen next-Übergang hinzufügen, da ein Kunde möglicherweise eines der exitKeywords eingeben kann, um den Chat zu verlassen, bevor diese Aktionen ausgelöst werden können.

  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 diesem Beispiel wird das Intent GetAgent darauf trainiert, Hilferufe wie Helfen Sie mir bitte! zu verstehen.

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

Grundlegende Schritte beim Konfigurieren des Dialogablaufs:

1. Starten Sie die Live-Agent-Übertragung:

   1. Fügen Sie einen Status für die Komponente System.AgentInitiation hinzu.

   2. Setzen Sie die Eigenschaft agentChannel des Status auf den Namen des Agent-Integrationskanals, den Sie für das Live-Agent-System konfiguriert haben.

   Nachdem der Agent-Integrationskanal eine Verbindung aufgebaut und Oracle B2C Service die Chatanfrage an seine Queue gesendet hat (d.h. nachdem ein Hilfeticket erstellt wurde), lässt die Komponente System.AgentInitiation den Übergang zum nächsten Status zu. Dieser ist typischerweise für die Komponente System.AgentConversation definiert (AgentConversation im folgenden Beispiel).

   
     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"

   Tipp:

   Kunden können wiederholt einen Livechat anfordern, auch wenn ihre Anforderungen bereits in der Agent-Chatkonsole in die Queue gestellt wurden. Fügen Sie dem Status System.AgentInitiation eine Eigenschaft resumedMessage hinzu, um zu verhindern, dass Kunden die irreführende Nachricht Wiederaufnahme des Chats mit dem Agent erhalten.

2. Fügen Sie die Komponente System.AgentConversation hinzu, und konfigurieren Sie sie. Während sich die Dialog-Engine in dem für diese Komponente definierten Status befindet, übergibt der Skill Nachrichten zwischen Kunden und Agent. Der Skill überwacht die Kundeneingabe auf Beendigungsschlüsselwörter wie Tschüss. Wenn der Skill eines dieser Schlüsselwörter erkennt, beendet die Komponente System.AgentConversation die Livechatsession und löst den Übergang next aus.

   Beispiel:

     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"

Im folgenden Beispiel für das Standardformat gibt die Komponente AgentConversation einen Umfragelink aus, nachdem die Agent-Unterhaltung beendet wurde. Der Link umfasst die Session- und Engagement-ID aus der Zuordnung, die mit der Eigenschaft chatResponseVariable benannt wurde.

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. Falls noch nicht geschehen, definieren Sie im Kontextknoten eine Zuordnungsvariable, die mit der Eigenschaft customProperties der Komponente System.AgentInitiation verwendet werden soll. Beispiel:

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

2. Definieren Sie die Felder für die Zuordnungsvariable.

   Im Folgenden finden Sie ein Beispiel für das Standardformat für Agent-Integrationskanäle, die in Version 20.01 oder höher erstellt wurden und eine Verbindung zu Oracle B2C Service Version 19A oder höher herstellen.

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

   Im Folgenden finden Sie ein Beispiel für das Legacy-Format für Agent-Integrationskanäle, die vor Version 20.01 erstellt wurden oder die eine Verbindung zu einer Version vor Oracle B2C Service Version 19A herstellen.

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

3. Fügen Sie die Eigenschaft customProperties der Komponente System.AgentInitiation hinzu, und setzen Sie sie auf den Wert der Zuordnungsvariablen. Beispiel:

     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"

Um die Interaktion zwischen einem Skill und einem Kalenderprovider zu ermöglichen, müssen Sie einen Service einrichten und den Skill und Dialogablauf ändern, damit der Benutzer sich über diesen Service bei seinem Kalender anmelden kann.

Bevor Sie eine Kalenderkomponente verwenden, müssen Sie eine Anwendung beim Kalenderprovider registrieren und einen Autorisierungscodeservice erstellen. In diesen Themen werden die jeweiligen Schritte beschrieben:

• Anwendungen mit Google OAuth2-Autorisierung registrieren

• Anwendungen bei Microsoft Identity Platform registrieren

• Autorisierungscodeservice hinzufügen

Verwenden Sie im Dialogablauf die Komponente System.OAuth2AccountLink, um den Benutzer zur Anmeldung bei seinem Kalender über den von Ihnen erstellten Autorisierungscodeservice aufzufordern. Beachten Sie, dass Sie die Eigenschaft enableSingleSignOn der Komponente nicht auf true setzen können, wenn Sie die Komponente zur Kalenderkomponentenautorisierung verwenden.

Sie können das Feature "Autorisierung erforderlich" nutzen, um vor dem Aufrufen von Kalenderkomponenten automatisch sicherzustellen, dass sich der Benutzer angemeldet (einen Zugriffstoken erhalten) hat. Dieses Feature fordert den Benutzer nur dann zur Anmeldung auf, wenn er noch kein Zugriffstoken hat oder dieses abgelaufen ist und nicht aktualisiert werden kann. Sie können die Einstellung Autorisierung erforderlich des Skills verwenden, um den Standardwert für den gesamten Skill festzulegen. Verwenden Sie dann die Einstellung requiresAuthorization auf Statusebene, um den Standardwert außer Kraft zu setzen. Das heißt, Sie verwenden die Skilleinstellung, um den Standardwert festzulegen, und nehmen dann die Einstellung requiresAuthorization der Komponente nur in die Statusangaben auf, für die der Standardwert nicht gilt.

Um das Feature "Autorisierung erforderlich" zu verwenden, müssen Sie dem Knoten defaultTransitions eine system.authorizeUser-Aktion hinzufügen, um den Status zu benennen, der den Autorisierungsablauf startet. Beispiel:

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

Bevor ein Skill in einen Status übergeht, für den eine Autorisierung erforderlich ist, wird geprüft, ob ein gültiges Zugriffstoken für den Kalenderservice vorhanden ist. Wenn nicht, werden folgende Aktionen ausgeführt:

1. Der Skill ruft den Status auf, den Sie für die system.authorizedUser-Aktion im Knoten defaultTransitions definiert haben.

2. Der Benutzer wird aufgefordert, sich anzumelden.

3. Der Skill wechselt zum Status, für den die Autorisierung erforderlich war (also der durch ${system.requestedState} definierte Status).

Beispiel für einen Autorisierungsdialogablauf:

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" 

Bei einem Skill, der sich hauptsächlich auf Kalenderkomponenten bezieht, sollten Sie die Konfiguration Autorisierung erforderlich des Skills auf true setzen und dann den Wert nur für die Statusangaben auf "false" setzen, die keine Autorisierung erfordern. In diesem Beispiel kann jeder Benutzer die Status initTimezoneOffset und intent ausführen. Daher ist requiresAuthorization für diese Status auf false gesetzt. Die Status, die mit den Kalenderkomponenten verwendet werden, müssen nicht requiresAuthorization enthalten, da der Standardwert true ist.

  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"

Bei der Arbeit mit den Kalenderkomponenten müssen Sie sich mit dem Zusammenhang zwischen den Start- und Endzeiten des Kalenders, DATE- und TIME-Entitys und der lokalen Zeitzone vertraut machen.

Wenn Sie Ereignisse erstellen, aktualisieren oder abrufen, verwenden Sie den lokalen Datums-/Uhrzeitwert für die Werte start und end. Mit der Eigenschaft timezoneOffset oder timezone teilen Sie der Komponente mit, wie die Universalzeit (UTC) berechnet werden soll.

timezoneOffset der Kalenderkomponenten unterscheidet sich von profile.timezoneOffset. Bei Kalenderkomponenten ist timezoneOffset der Wert, den die Komponente den Werten start und end hinzufügen muss, um die UTC abzurufen. Sie können den Eigenschaftswert timezoneOffset einer Kalenderkomponente ableiten, indem Sie profile.timezoneOffset mit -1 multiplizieren.

profile.timezoneOffset ist möglicherweise nicht immer verfügbar. Das hängt davon ab, ob der Client den Offset bereitgestellt hat. Beispiel: Ein Benutzer kann eine Oracle-Web-App erstellen, die profile.timezoneOffset nicht festlegt. Daher ist es empfehlenswert, eine Standardzeitzone für Fälle zu erstellen, in denen profile.timezoneOffset nicht festgelegt wurde. Beispiel:

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

Wenn Sie ein Ereignis abrufen, gibt die Komponente die Datums-/Uhrzeitwerte im UTC-Format zurück. Beispiel: 2021-04-15T22:00:00.000Z. Der Skill muss den Wert in die Ortszeit konvertieren.

  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"

Berücksichtigen Sie folgende Punkte bei Verwendung der Entitys DATE und TIME:

• Wenn Sie eine Mischentity verwenden, die sowohl eine DATE- Entity als auch eine oder mehrere TIME-Entitys enthält, müssen Sie Out-of-Order-Extraktion deaktivieren. Wenn die Entitys aufgelöst werden, haben Sie andernfalls keine Kontrolle darüber, welche Werte als DATE-Entity und welche Werte als TIME-Entity (oder beides) aufgelöst werden. Beispiel: Wenn TIME aufgelöst wird, kann der Wert der DATE-Entity dadurch geändert werden.

• Wenn eine Äußerung Text wie "gestern", "heute" oder "morgen" enthält, berücksichtigt der Parser die lokale Zeitzone nicht. Daher ist es möglich, dass am frühen Morgen und am späten Nachmittag das falsche Datum verwendet wird. Aus diesem Grund empfiehlt es sich, das aufgelöste Datum erneut anzuzeigen, damit der Benutzer es prüfen kann, bevor der Skill ein Ereignis hinzufügt oder die Start- oder Endzeit eines Ereignisses aktualisiert.

• Um die Eigenschaftswerte start und end eines Kalenders festzulegen, müssen Sie das Datum aus der DATE-Entity und die Uhrzeit aus der TIME-Entity verwenden. Beispiel:

        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']}"

Der Kalenderprovider kann eine Ereignisanforderung ablehnen. Beispiel: Es kann ein Fehler zurückgegeben werden, wenn der Benutzer versucht, ein Ereignis zu erstellen, dessen Endzeit vor der Startzeit liegt. In den meisten Fällen gibt der Kalenderprovider einen 400-Fehler zurück, der wiederum den Skill an den globalen Error Handler überträgt.

Validieren Sie die Werte, um zu verhindern, dass diese Fehler auftreten. Beispiele für Validierungen von Mischentitys:

• DATE-Entity: Validieren Sie bei neuen und aktualisierten Besprechungen, ob das Datum am oder nach dem aktuellen Datum liegt.

  ${(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')}

• TIME-Entity: Prüfen Sie bei neuen und aktualisierten Besprechungen, ob Datum und Startzeit am oder nach dem aktuellen Datums-/Uhrzeitwert liegen.

  ${(((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')}

  Prüfen Sie für alle Endzeiten, ob die Endzeit nach der Startzeit liegt.

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

Um die Ablehnungen von Kalenderprovidern ordnungsgemäß zu verarbeiten, fügen Sie Ihren eigenen globalen Error Handler hinzu. Beispiel:

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"

Alternativ dazu können Sie den Fehlerübergang verwenden, um Error Handler zu erstellen, die für jeden Fall geeignet sind:

  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"

Verwenden Sie diese Komponente, um ein Ereignis zu einem Outlook- oder Google-Kalender hinzuzufügen. Beachten Sie, dass Sie keine wiederkehrenden oder ganztägigen Ereignisse erstellen können.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Informationen zum Festlegen der Werte start und end finden Sie unter Mit Kalenderdaten und -zeiten arbeiten.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente. In diesem Beispiel wird eine Mischentity zum Abrufen von Datum, Start- und Endzeit, Betreff, Standort und Teilnehmern verwendet.

  ####################
  # 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"
...

Mit dieser Komponente können Sie ein Ereignis aus einem Outlook- oder Google-Kalender löschen. Beachten Sie, dass Sie keine wiederkehrenden oder ganztägigen Ereignisse löschen können.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente.

  ####################
  # 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"
...

Mit dieser Komponente können Sie die Details eines Ereignisses aus einem Outlook- oder Google-Kalender abrufen.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Die Details werden in der Variable zurückgegeben, die von der Eigenschaft eventDetailsVariableName im folgenden JSON-Format angegeben wird:

{
  "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
}

Die Eigenschaften start und end sind UTC-Werte. Informationen zum Konvertieren der Werte start und end in Ortszeit finden Sie unter Mit Kalenderdaten und -zeiten arbeiten.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente.

  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"

Mit dieser Komponente können Sie ein Array von Outlook- oder Google-Ereignissen für einen benannten Kalendereigentümer abrufen. Sie können die Liste nach folgenden Attributen filtern:

• Das Ereignis kann gelöscht werden.
• Das Ereignis kann aktualisiert werden.
• Der Benutzer wurde zum Ereignis eingeladen.
• Wie der Benutzer auf eine Einladung reagiert hat.
• Das Ereignis enthält mindestens einen benannten Teilnehmer.
• Die Besprechung beginnt nach einem Datum und einer Uhrzeit.
• Die Besprechung endet vor einem Datum und einer Uhrzeit.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Die Liste wird in der Variable zurückgegeben, die von der Eigenschaft eventListVariableName im folgenden JSON-Format angegeben wird:

[{
  "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
}, …]

Informationen zum Festlegen der Werte start und end finden Sie unter Mit Kalenderdaten und -zeiten arbeiten. In diesem Thema wird auch beschrieben, wie die Eigenschaftswerte JSON start und end in Ortszeit konvertiert werden.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente.

  ############################
  # 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"      

Diese Komponente kann folgende Aktionen zurückgeben:

Mit dieser Komponente können Sie eine Liste von Outlook- oder Google-Ereignissen anzeigen, zwischen denen der Benutzer wählen kann. Die Komponente speichert die ID des ausgewählten Ereignisses in der Variable, die mit der Eigenschaft eventIdVariableName angegeben wird.

Sie können die Liste für die Auswahl nach folgenden Attributen filtern:

• Das Ereignis kann gelöscht werden.
• Das Ereignis kann aktualisiert werden.
• Der Benutzer wurde zum Ereignis eingeladen.
• Wie der Benutzer auf eine Einladung reagiert hat.
• Das Ereignis enthält mindestens einen benannten Teilnehmer.
• Die Besprechung beginnt nach einem Datum und einer Uhrzeit.
• Die Besprechung endet vor einem Datum und einer Uhrzeit.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Informationen zum Festlegen der Werte start und end finden Sie unter Mit Kalenderdaten und -zeiten arbeiten.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente.

  ############################
  # 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"
  ...

Eigenschaft	Beschreibung	Erforderlich?
provider	Der Kalenderprovider. Die zulässigen Werte sind Google und Outlook.	Ja
calendarOwner	Die Benutzer-ID des Kalendereigentümers. Das muss eine gültige Account-ID für den Kalenderprovider sein, wie z.B. der Wert der Variable, die mit der Eigenschaft authenticatedUserVariable der Komponente System.OAuth2AccountLink identifiziert wird. Diese wird bei der Authentifizierung des Benutzers festgelegt.	Ja
calendarId	Der Name des Kalenders. Legen Sie diese Eigenschaft für den Standardkalender des Benutzers auf denselben Wert wie die Eigenschaft calendarOwner.	Ja
credential	Das Zugriffstoken des Providers. Das ist der Wert der Variable, die mit der Eigenschaft accessTokenVariableName der Komponente System.OAuth2AccountLink identifiziert wird. Diese wird bei der Authentifizierung des Benutzers festgelegt.	Ja
listType	Gibt den Typ der Liste an. Dieser muss einer der Folgenden sein: ALL: Alle Typen der Besprechungen des Kalendereigentümers DELETE: Alle Besprechungen, die der Kalendereigentümer löschen kann UPDATE: Alle Besprechungen, die der Kalendereigentümer aktualisieren kann INVITED: Alle Besprechungen, die nicht vom Kalendereigentümer organisiert werden, aber zu denen der Eigentümer eingeladen wurde.	Ja
eventIdVariableName	Der Name der Kontextvariable, in der die Ereignis-ID gespeichert werden soll.	Ja
start	Die früheste Datums-/Uhrzeitangabe, zu der Besprechungen in die Liste aufgenommen werden sollen (Format: yyyy-MM-dd'T'HH:mm:ss). Beispiel: 2021-02-26T09:55:00.	Ja
end	Die späteste Datums-/Uhrzeitangabe, zu der Besprechungen in die Liste aufgenommen werden sollen (Format: yyyy-MM-dd'T'HH:mm:ss). Beispiel: 2021-02-26T09:55:00. Für den Listentyp INVITED lautet der Standardwert 14 Tage nach Startdatum und -zeit. Bei allen anderen Typen ist der Standardwert 24 Stunden nach Startdatum und -zeit.	Nein
attendees	Eine durch Komma getrennte Liste mit Zeichenfolgen (ohne Beachtung der Groß-/Kleinschreibung), mit denen die Liste nach Teilnehmern gefiltert werden soll. Nur Besprechungen, bei denen mindestens ein Teilnehmerwert mindestens eine Zeichenfolge in der Liste enthält, werden in die Ausgabe aufgenommen.	Nein
response	Eine durch Komma getrennte Liste mit Einladungsstatuswerten, nach denen die Liste gefiltert wird, wenn listType INVITED ist. Zulässige Statuswerte: ACCEPTED TENTATIVE DECLINED PENDING Der Standardwert ist PENDING,TENTATIVE. Damit werden nur Einladungen ausgegeben, die auf eine Antwort warten oder vorläufig angenommen wurden.	Nein
prompt	Der Text, der vor der Liste angezeigt wird. Der Standardwert ist You have the following meeting(s): Sie müssen diese Eigenschaft nur dann aufnehmen, wenn Sie den Standardwert außer Kraft setzen möchten. Tipp: In Skills mit Plattformversion 21.04 und höher wird der Standardwert im Resource Bundle des Skills gespeichert. Um den Standardwert zu ändern, öffnen Sie die Seite Resource Bundle des Skills, klicken Sie auf , wählen Sie die Registerkarte Konfiguration aus, und ändern Sie die Nachricht für den Schlüssel SelectCalendarEvent - prompt.	Nein
allDayLabel	Der Text zur Angabe ganztägiger Ereignisse. Der Standardwert ist All day.	Nein
recurringLabel	Der Text zur Angabe eines wiederkehrenden Ereignisses. Der Standardwert ist Recurring.	Nein
acceptedLabel	Der Text, der angibt, dass der Kalendereigentümer die Einladung angenommen hat. Der Standardwert ist Accepted.	Nein
tentativeLabel	Der Text, der angibt, dass der Kalendereigentümer die Einladung vorläufig angenommen hat. Der Standardwert ist Tentative.	Nein
declinedLabel	Der Text, der angibt, dass der Kalendereigentümer die Einladung abgelehnt hat. Der Standardwert ist Declined.	Nein
pendingLabel	Der Text, der angibt, dass der Kalendereigentümer nicht auf die Einladung reagiert hat. Der Standardwert ist Pending.	Nein
timezoneOffset	Die Zeit in Millisekunden, die der koordinierten Weltzeit (UTC) hinzugefügt werden muss, um die Normalzeit in der Zeitzone des Benutzers abzurufen. Beispiel: Wenn die lokale Zeitzone UTC-2 ist, lautet timezoneOffset -7200000. Der Standardwert ist 0. Hinweis Sie können die Eigenschaft timezoneOffset für den aktuellen Benutzer basierend auf dem Wert der Benutzerkontextvariable profile.timezoneOffset ableiten. In diesem Fall müssen Sie jedoch profile.timezoneOffset mit -1 multiplizieren. Sie können timezoneOffset oder timezone angeben, aber nicht beides.	Nein
timezone	Die ID der lokalen Zeitzone gemäß https://www.iana.org/time-zones. Wird auch als TZ-Datenbankname bezeichnet. Beispiel: America/Los_Angeles. Der Standardwert lautet UTC. Sie können timezoneOffset oder timezone angeben, aber nicht beides.	Nein

Diese Komponente kann folgende Aktionen zurückgeben:

Mit dieser Komponente können Sie eine Einladung für ein Outlook- oder Google-Kalenderereignis annehmen, vorläufig annehmen oder ablehnen.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente.

  ############################
  # 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"

Verwenden Sie diese Komponente, um Änderungen an einem Outlook- oder Google-Kalenderereignis vorzunehmen. Beachten Sie, dass Sie keine wiederkehrenden oder ganztägigen Ereignisse aktualisieren können.

Der Benutzer muss beim Kalenderprovider angemeldet sein, um auf diese Komponente zugreifen zu können. Sie können die Funktion "Autorisierung erforderlich" verwenden, um die Benutzeranmeldung zu verwalten, wie unter Kalenderautorisierung beschrieben.

Informationen zum Festlegen der Werte start und end finden Sie unter Mit Kalenderdaten und -zeiten arbeiten.

Nachfolgend finden Sie ein Beispiel für die Verwendung dieser Komponente. In diesem Beispiel wird eine Mischentity zum Abrufen des Datums, der Startzeit und der Endzeit verwendet.

  ####################
  # 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 diesem Beispiel enthält die Variable type die Werte, die von der Entity PizzaType erwartet werden, wie Käse, Veggie Lover und Hawaii. Wenn diese Informationen in der Benutzereingabe fehlen, kann der Bot sie dennoch abrufen, weil der Dialogablauf in den Status type übergeht, dessen Komponente System.Text den Benutzer dazu auffordert, den gewünschten Status explizit anzugeben. Beachten Sie, dass die Benutzereingabe dennoch als PizzaType-Entity aufgelöst werden muss, um in den nächsten Status zu wechseln.

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

Mit der Komponente System.List können Sie einen Wert zurückgeben, der einer Kontextvariablen entspricht, die als Primitive (wie greeting: "string" in der Dialogablaufvorlage) oder als Entity definiert ist, wie im folgenden Snippet dargestellt. In diesem Dialogablauf gibt die Definition options: "Dick,Dünn,Gefüllt,Pan" einen Wert zurück, der mit der Variablen crust übereinstimmt. Die für die Größe definierte Eigenschaft options ist ein Wertausdruck (${size.type.enumValues}), der die Listenwerte "Groß", "Mittel", "Klein" und "Persönlich" als Optionen zurückgibt. Siehe Apache FreeMarker Template Language-Syntax.

Dieses Beispiel zeigt außerdem, wie mit der Definition iResult der Eigenschaft nlpResultVariable die Komponente die Entitywerte für die Eigenschaften variable für die Status crust und size festlegen kann, wenn diese Werte zuvor nicht festgelegt wurden. Wie die Komponente Text erfordert auch die Komponente System.List keine Übergänge.

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

Hinweis

Benutzer sind nicht auf die in der Liste angezeigten Optionen eingeschränkt. Sie können die Entity auflösen, indem sie ein Wort eingeben, das die Entity erkennt, wie ein Synonym. Anstatt eine Option für die Pizzagrößen in der Liste auszuwählen, können Benutzer z.B. stattdessen jumbo eingeben, ein Synonym, das für die Option Groß der Entity PizzaSize definiert ist. Siehe Benutzerdefinierte Entitys.

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"