System.CommonResponseコンポーネントの構成には、ダイアログ・エンジンに指示するプロパティと、コンポーネントによるメッセージの配信方法(テキスト・プロンプト、カードまたは添付として)のみでなく、メッセージ自体の内容および動作も設定するメタデータ・プロパティの設定が必要です。

System.CommonResponseコンポーネントに基づく状態の例のYAMLを次に示します。

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

インタビューの属性値にアクセスする簡単な例を次に示します。

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

次の図に、ダイアログ・フローがYAMLモードで作成されている場合の単一状態メソッドの実装方法を示します。1)マップ・コンテキスト変数を使用して、ナレッジ・インテントを検索語に関連付けます。2)各ナレッジ・インテントを設定しますIntent状態のアクション。マップを使用してsearchTermコンテキスト変数をインテントの検索語に設定するデータ・フローに遷移します。3)次に、searchTerm値をナレッジ・ベースで検索する状態に遷移します。

図kf-assoc-intent-with-term.pngの説明

ナレッジ・ベース・アンサーごとに個別のインテントがあるダイアログ・フローの例を次に示します。

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"

次の例は、YAMLダイアログ・スキルでsearchTermをユーザーの発話に設定する方法を示しています。ビジュアル・ダイアログ・スキルの場合は、かわりに${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"

顧客がエージェントとの会話を要求したときにエージェントに転送するダイアログ・フローの例を次に示します:

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"

デジタル・アシスタントからライブ・エージェントに会話を転送する場合、System.AgentTransferコンポーネントのカスタム・プロパティを使用してこの情報を渡すことができます。

Oracle B2C Serviceの構造を次に示します:

      customProperties:
        - name: 
          value: 
          type:

カスタム・フィールドにはtypeプロパティが必要です。それ以外の場合はオプションです。

Oracle Fusion Serviceの構造は次のとおりです。

      customProperties:
        - name: 
          value:

Oracle Fusion ServiceのcustomProperties設定の例:

  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"

コンポーネントを起動し、待機時間を表示し、ユーザーに転送リクエストを取り消す機会を与えるダイアログ・フローの例を次に示します。

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

askIfWillWait状態では、リソース・バンドル・エントリを使用して待機時間メッセージを形成し、時間が1分以上か1分未満か、および数が0か1以上かがわかるようにします。

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?

この例では、System.SetCustomMetricsを使用して、エージェントが使用可能かどうか、および使用可能である場合は待機することを選択したユーザー数と、転送リクエストを取り消した数を追跡します。

スキルの会話をOracle B2C Serviceエージェントに転送する場合は、このコンポーネントをダイアログ・フローに追加し、agentChannelプロパティで指定されたエージェント統合チャネルとのハンドシェイクを開始します。System.AgentConversationコンポーネントをコールする前に、このコンポーネントをコールする必要があります。

このコンポーネントは、スキルで発生した会話用です。デジタル・アシスタント(エージェント)のフレームワークの動作で説明されているように、このコンポーネントをOracle B2C Serviceチャットで発生した会話に使用しないでください。

このコンポーネントを使用して、ServiceCloudIntegrationというエージェント統合チャネルによって定義されるOracle B2C Serviceインスタンスとのハンドシェイクを開始する例を次に示します。

  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"

ヒント:

プラットフォーム・バージョンが21.04以降のスキルでは、agentActionsMessage、errorMessage、rejectedMessage、resumedMessageおよびwaitingMessageプロパティのデフォルト値はスキルのリソース・バンドルに格納されます。デフォルトを変更するには、スキルの「リソース・バンドル」ページを開き、をクリックして「構成」タブを選択し、AgentInitiation - <property name>キーのメッセージを変更します。スキルのリソース・バンドルを使用してデフォルト・メッセージを変更する場合は、コンポーネントにメッセージ・プロパティを含める必要はありません(デフォルトをオーバーライドする場合を除きます)。

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

システム・エラーとerrorおよびrejectedアクションの処理の例を次に示します。

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

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

この例では、contactIDを設定します。

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

次の例では、interfaceIDとcontactIDを設定します。

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

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

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

これらのステップでは、customPropertiesオブジェクトを宣言し、その様々な値を設定する方法について説明します。

このコンポーネントを使用して、スキルの会話をOracle B2C Serviceライブ・エージェントに転送し、スキルとライブ・エージェントのやり取りを管理します。このコンポーネントを使用する前に、System.AgentInitiationコンポーネントをコールする必要があることに注意してください。

System.AgentConversationは、スキルで発生した会話用です。デジタル・アシスタント(エージェント)のフレームワークの動作で説明されているように、このコンポーネントをOracle B2C Serviceチャットで発生した会話に使用しないでください。

次に、このコンポーネントを使用して、ServiceCloudIntegrationというエージェント統合チャネルによって定義されるOracle B2C Serviceインスタンスに会話を転送する例を示します。

  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"

System.AgentConversationは、expired、agentLeft、errorまたはwaitExpiredアクションをトリガーできます。また、System.AgentInitiationコンポーネントのagentActionsプロパティからアクションをトリガーできます。これらのアクションがトリガーされる前に、顧客がexitKeywordsのいずれかを入力してチャットを終了する場合があるため、next遷移も追加する必要があります。

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

次の例では、GetAgentインテントは、助けてくださいのような助けを求める発言を理解するようにトレーニングされています。

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

次に、ダイアログ・フローを構成するための基本ステップを示します:

1. ライブ・エージェント転送を開始します。

   1. System.AgentInitiationコンポーネントの状態を追加します。

   2. 状態のagentChannelプロパティを、ライブ・エージェント・システム用に構成したエージェント統合チャネルの名前に設定します。

   エージェント統合チャネルが接続を確立し、Oracle B2C Serviceがチャット・リクエストをそのキューに送信した後(つまり、ヘルプ・チケットを作成した後)、System.AgentInitiationコンポーネントによって次の状態への遷移が可能になります。これは通常、System.AgentConversationコンポーネントに定義されます(次の例ではagentConversation)。

   
     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"

   ヒント:

   顧客のリクエストがエージェントのチャット・コンソールのキューにすでに入っていても、顧客はライブ・チャットを繰り返し要求できます。System.AgentInitiation状態にresumedMessageプロパティを追加して、このような顧客が誤解を招く「エージェントとのチャットを再開しています」メッセージを受信しないようにします。

2. System.AgentConversationコンポーネントを追加して構成します。ダイアログ・エンジンがこのコンポーネントに定義された状態になっている間、スキルは顧客とエージェントの間でメッセージを受け渡します。スキルは、顧客入力の終了キーワード(byeなど)をリスニングします。スキルがこれらのキーワードのいずれかを検出すると、System.AgentConversationコンポーネントはライブ・チャット・セッションを終了し、そのnext遷移をトリガーします。

   次の例は、次のとおりです:

     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"

標準フォーマットを使用する次の例では、エージェントの会話が終了すると、AgentConversationコンポーネントがサーベイ・リンクを出力します。リンクには、chatResponseVariableプロパティによって指定されたマップからのセッションおよびエンゲージメントIDが含まれます。

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. まだ定義していない場合は、コンテキスト・ノードで、System.AgentInitiationコンポーネントのcustomPropertiesプロパティで使用するマップ変数を定義します。例:

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

2. マップ変数のフィールドを定義します。

   次に、バージョン20.01以上で作成され、Oracle B2C Serviceバージョン19A以上に接続するエージェント統合チャネルの標準フォーマットの例を示します。

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

   次に、バージョン20.01より前に作成されたか、Oracle B2C Serviceバージョン19Aより前のバージョンに接続するエージェント統合チャネルのレガシー・フォーマットの例を示します。

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

3. customPropertiesプロパティをSystem.AgentInitiationコンポーネントに追加し、これをマップ変数の値に設定します。例:

     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"

スキルとカレンダ・プロバイダ間の対話を有効にするには、サービスを設定し、スキルおよびダイアログ・フローを変更して、ユーザーがそのサービスを介してカレンダにサインインできるようにする必要があります。

カレンダ・コンポーネントを使用する前に、アプリケーションをカレンダ・プロバイダに登録し、認可コード・サービスを作成する必要があります。方法は、次の項目を参照してください:

• Google OAuth2 Authorizationへのアプリケーションの登録

• Microsoft IDプラットフォームへのアプリケーションの登録

• 認可コード・サービスの追加

ダイアログ・フローで、System.OAuth2AccountLinkコンポーネントを使用して、作成した認可コード・サービスを介してカレンダにサインインするようユーザーに求めます。このコンポーネントをカレンダ・コンポーネントの認可に使用する場合は、コンポーネントのenableSingleSignOnプロパティをtrueに設定できないことに注意してください。

「認可が必要」機能を利用すると、ユーザーがカレンダ・コンポーネントを起動する前に、サインインしていること(アクセス・トークンを取得していること)を自動的に確認できます。この機能によって、ユーザーがまだアクセス・トークンを持っていない場合、または期限が切れてリフレッシュできない場合のみ、ユーザーがサインインを求められます。スキルの「認可が必要」構成を使用してスキル全体のデフォルトを設定し、状態レベルのrequiresAuthorization設定を使用してデフォルトをオーバーライドできます。つまり、スキルの設定を使用してデフォルトを設定し、デフォルトが適用されない状態にのみコンポーネントのrequiresAuthorization設定を含めます。

「認可が必要」機能を使用するには、defaultTransitionsノードにsystem.authorizeUserアクションを追加して、認可フローを開始する状態を指定する必要があります。例:

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

スキルは、認可が必要な状態に遷移する前に、カレンダ・サービスにとって有効なアクセス・トークンがあるかどうかを確認します。ない場合は、次の処理を実行します:

1. defaultTransitionsノードのsystem.authorizedUserアクションに定義した状態を起動します。

2. ユーザーにサインインを求めます。

3. 認可が必要な状態(${system.requestedState}によって定義された状態)に遷移します。

認可ダイアログ・フローの例を次に示します:

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" 

主にカレンダ・コンポーネントに特化したスキルでは、スキルの「認可が必要」構成をtrueに設定し、認可が必要でない状態に対してのみ値をfalseに設定することを検討してください。この例では、どのユーザーもinitTimezoneOffset状態およびintent状態を実行できます。したがって、それらの状態では、requiresAuthorizationがfalseに設定されます。カレンダ・コンポーネントで作動する状態には、requiresAuthorizationを含める必要はありません。デフォルトがtrueであるためです。

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

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

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

カレンダ・コンポーネントを使用するときは、カレンダの開始時間と終了時間、DATEとTIMEエンティティ、およびローカル・タイムゾーンの関係を理解することが重要です。

イベントを作成、更新または取得する場合は、startとendの値にローカル日時を使用し、timezoneOffsetまたはtimezoneプロパティを使用して、協定世界時(UTC)の計算方法をコンポーネントに指示します。

カレンダ・コンポーネントのtimezoneOffsetはprofile.timezoneOffsetとは異なります。カレンダ・コンポーネントの場合、timezoneOffsetは、UTCを得るためにコンポーネントがstartとendの値に追加する必要がある値です。profile.timezoneOffsetに-1を掛けると、カレンダ・コンポーネントのtimezoneOffsetプロパティ値を導出できます。

profile.timezoneOffsetは常に使用できるとはかぎりません。クライアントがオフセットを指定したかどうかによって異なります。たとえば、profile.timezoneOffsetを設定せずにOracle Webアプリケーションが構築されることがあります。したがって、profile.timezoneOffsetが設定されない場合に備えて、デフォルトのタイムゾーンを作成することをお薦めします。例:

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

イベントを取得すると、コンポーネントがUTCフォーマットで日時値を返します。例: 2021-04-15T22:00:00.000Z。スキルによって値をローカル時間に変換する必要があります。

  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"

DATEおよびTIMEエンティティを使用する場合、次のことを考慮する必要があります:

• DATEエンティティと1つ以上のTIMEエンティティの両方を含むコンポジット・バッグを使用する場合は、「順不同の抽出」を無効にする必要があります。そうしないと、エンティティが解決されるときに、どの値がDATEエンティティに解決され、どの値がTIMEエンティティに解決されるか(あるいは両方)を制御できません。たとえば、TIMEが解決されるときに、DATEエンティティの値が変更される可能性があります。

• 発話に「昨日」、「今日」、「明日」のようなテキストが含まれているとき、パーサーはローカル・タイムゾーンを考慮しません。したがって、早朝や夕方に、間違った日付が使用される可能性があります。そのため、解決された日付をエコーバックすることをお薦めします。これにより、スキルによってイベントが追加されたり、イベントの開始時刻または終了時刻が更新される前にユーザーが解決された日付を確認できます。

• カレンダのstartおよびendプロパティ値を設定するには、DATEエンティティの日付とTIMEエンティティの時刻を使用する必要があります。例:

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

カレンダ・プロバイダによってイベント・リクエストが拒否される場合があります。たとえば、終了時間が開始時間よりも前になるイベントをユーザーが作成しようとすると、エラーが返される場合があります。ほとんどの場合、カレンダ・プロバイダは400エラーを返し、これによってスキルがグローバル・エラー・ハンドラに遷移します。

このようなエラーが発生しないように、値を検証することを検討してください。コンポジット・バッグ・エンティティ検証の例を次に示します:

• DATEエンティティ: 新規の会議や更新された会議について、日付が現在の日付以降であることを確認します。

  ${(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エンティティ: 新規の会議や更新された会議について、日付と開始時刻が現在の日時以降であることを確認します。

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

  すべての終了時刻について、終了時刻が開始時刻より後であることを確認します。

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

カレンダ・プロバイダの拒否を正常に処理するには、独自のグローバル・エラー・ハンドラを追加します。例:

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"

または、エラー遷移を使用して、各ケースに適したエラー・ハンドラを作成できます:

  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"

このコンポーネントを使用して、OutlookまたはGoogleのカレンダにイベントを追加します。繰返しイベントまたは終日イベントは作成できないことに注意してください。

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

startとendの値の設定方法の詳細は、カレンダの日付と時刻の操作を参照してください。

このコンポーネントの使用例を次に示します:この例では、コンポジット・バッグ・エンティティを使用して、日付、開始時刻と終了時刻、件名、場所および参加者を取得します。

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

このコンポーネントを使用して、OutlookまたはGoogleのカレンダからイベントを削除します。繰返しイベントまたは終日イベントは削除できないことに注意してください。

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

このコンポーネントの使用例を次に示します:

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

このコンポーネントを使用して、OutlookまたはGoogleのカレンダからイベントの詳細を取得します。

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

詳細は、次のようなJSONフォーマットで、eventDetailsVariableNameプロパティで指定された変数に返されます:

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

startおよびendプロパティはUTC値です。startとendの値の変換方法の詳細は、カレンダの日付と時刻の操作を参照してください。

このコンポーネントの使用例を次に示します:

  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"

このコンポーネントを使用して、指定したカレンダ所有者についてOutlookまたはGoogleイベントの配列を取得します。リストは次の属性でフィルタ処理できます:

• 削除できるイベント
• 更新できるイベント
• イベントに招待されたユーザー
• ユーザーが招待に応答した方法
• 指定した参加者1人以上が含まれるイベント
• 特定の日時より後に開始する会議
• 特定の日時より前に終了する会議

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

リストは、次のようなJSONフォーマットで、eventListVariableNameプロパティで指定された変数に返されます。

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

startとendの値の設定方法の詳細は、カレンダの日付と時刻の操作を参照してください。このトピックでは、JSONのstartおよびendプロパティ値をローカル時間に変換する方法も示します。

このコンポーネントの使用例を次に示します:

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

このコンポーネントは、次のアクションを返すことができます:

このコンポーネントを使用して、ユーザーが選択できるOutlookまたはGoogleイベントのリストを表示します。このコンポーネントは、選択されたイベントのIDをeventIdVariableNameプロパティで指定された変数に保存します。

選択するためのリストは次の属性でフィルタ処理できます:

• 削除できるイベント
• 更新できるイベント
• イベントに招待されたユーザー
• ユーザーが招待に応答した方法
• 指定した参加者1人以上が含まれるイベント
• 特定の日時より後に開始する会議
• 特定の日時より前に終了する会議

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

startとendの値の設定方法の詳細は、カレンダの日付と時刻の操作を参照してください。

このコンポーネントの使用例を次に示します:

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

プロパティ	説明	必須?
provider	カレンダ・プロバイダ。指定できる値はGoogleおよびOutlookです。	はい
calendarOwner	カレンダ所有者のユーザーID。これは、カレンダ・プロバイダの有効なアカウントIDである必要があります。たとえば、ユーザー認証時に設定される、System.OAuth2AccountLinkコンポーネントのauthenticatedUserVariableプロパティで識別される変数の値などです。	はい
calendarId	カレンダの名前。ユーザーのデフォルト・カレンダの場合は、calendarOwnerプロパティと同じ値に設定します。	はい
credential	プロバイダのアクセス・トークン。これは、ユーザー認証時に設定される、System.OAuth2AccountLinkコンポーネントのaccessTokenVariableNameプロパティで識別される変数の値です。	はい
listType	リストのタイプを示します。次のいずれかである必要があります: ALL: カレンダ所有者のすべてのタイプの会議 DELETE:カレンダ所有者が削除できる会議すべて UPDATE:カレンダ所有者が更新できる会議すべて INVITED: カレンダ所有者が開催するものではないが、カレンダ所有者が招待されている会議すべて	はい
eventIdVariableName	イベントのIDを格納するコンテキスト変数の名前。	はい
start	リストに含める会議の最も早い日時(フォーマット: yyyy-MM-dd'T'HH:mm:ss)。例、 2021-02-26T09:55:00	はい
end	リストに含める会議の最も遅い日時(フォーマット: yyyy-MM-dd'T'HH:mm:ss)。例、 2021-02-26T09:55:00 リスト・タイプINVITEDの場合、デフォルトは開始日時の14日後です。他のすべてのタイプの場合、デフォルトは開始日時の24時間後です。	いいえ
attendees	大/小文字が区別されない文字列のカンマ区切りリスト。参加者によってリストをフィルタ処理するために使用されます。1つ以上のattendee値にリストの1つ以上の文字列が含まれている会議のみが出力されます。	いいえ
response	招待の状態のカンマ区切りリスト。listTypeがINVITEDのときにリストをフィルタ処理するために使用されます。指定できる状態は次のとおりです: ACCEPTED TENTATIVE DECLINED PENDING デフォルトはPENDING,TENTATIVEです。レスポンスを待機している招待、または仮受付けされた招待のみが出力されます。	いいえ
prompt	リストの前に表示されるテキスト。デフォルトはYou have the following meeting(s):です。デフォルトをオーバーライドする場合を除き、このプロパティを含める必要はありません。 ヒント: プラットフォーム・バージョンが21.04以降のスキルでは、デフォルト値はスキルのリソース・バンドルに格納されます。デフォルトを変更するには、スキルの「リソース・バンドル」ページを開き、をクリックして「構成」タブを選択し、SelectCalendarEvent - promptキーのメッセージを変更します。	いいえ
allDayLabel	終日イベントを示すテキスト。デフォルトはAll dayです。	いいえ
recurringLabel	繰返しイベントを示すテキスト。デフォルトはRecurringです。	いいえ
acceptedLabel	カレンダ所有者が招待を受け入れたことを示すテキスト。デフォルトはAcceptedです。	いいえ
tentativeLabel	カレンダ所有者が招待を仮に受け入れたことを示すテキスト。デフォルトはTentativeです。	いいえ
declinedLabel	カレンダ所有者が招待を辞退したことを示すテキスト。デフォルトはDeclinedです。	いいえ
pendingLabel	カレンダ所有者が招待に応答しなかったことを示すテキスト。デフォルトはPendingです。	いいえ
timezoneOffset	ユーザーのタイムゾーンの標準時刻を取得するために、世界標準時(UTC)に追加する時間(ミリ秒単位)。たとえば、ローカル・タイムゾーンがUTC-2の場合、timezoneOffsetは-7200000です。デフォルト値は0です。 ノート ユーザー・コンテキスト変数profile.timezoneOffsetの値に基づいて、現在のユーザーのtimezoneOffsetプロパティを導出できます。ただし、そのためには、profile.timezoneOffsetに-1を掛ける必要があります。 timezoneOffsetまたはtimezoneを指定できますが、両方は指定できません。	いいえ
timezone	https://www.iana.org/time-zonesによって指定されるローカル・タイムゾーンのID。TZデータベース名とも呼ばれます。例: America/Los_Angeles。デフォルトはUTCです。timezoneOffsetまたはtimezoneを指定できますが、両方は指定できません。	いいえ

このコンポーネントは、次のアクションを返すことができます:

このコンポーネントを使用して、OutlookまたはGoogleのカレンダ・イベントについて、招待の受入れ、仮受入れまたは辞退を行います。

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

このコンポーネントの使用例を次に示します:

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

このコンポーネントを使用して、OutlookまたはGoogleのカレンダ・イベントを変更します。繰返しイベントまたは終日イベントは更新できないことに注意してください。

ユーザーがこのコンポーネントにアクセスするには、カレンダ・プロバイダにサインインする必要があります。カレンダの認可で説明されているように、「認可が必要」機能を使用してユーザーのサインインを管理できます。

startとendの値の設定方法の詳細は、カレンダの日付と時刻の操作を参照してください。

このコンポーネントの使用例を次に示します:この例では、コンポジット・バッグ・エンティティを使用して、日付、開始時刻および終了時刻を取得します。

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

この例では、type変数が、PizzaTypeエンティティによって予期されている値(cheese、Veggie Lover、Hawaiianなど)を保持します。この情報がユーザー入力にない場合でも、ボットのダイアログ・フローはtype状態に遷移し、そのSystem.Textコンポーネントが要望を明示的に示すようユーザーに求めるため、ボットは情報を取得できます。この時点でも、次の状態に遷移するには、ユーザー入力がPizzaTypeエンティティに解決される必要があることに注意してください。

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

次のスニペットに示すように、System.Listコンポーネントを使用して、プリミティブとして(ダイアログ・フロー・テンプレートのgreeting: "string"など)またはエンティティとして定義されているコンテキスト変数を満たす値を返すことができます。このダイアログ・フローでは、options: "Thick,Thin,Stuffed,Pan"定義により、crust変数と一致する値が返されます。sizeに対して定義されたoptionsプロパティは、オプションとしてLarge、Medium、SmallおよびPersonalリスト値を返す値式(${size.type.enumValues})です。Apache FreeMarker Template Languageの構文を参照してください。

この例は、nlpResultVariableプロパティのiResult定義により、コンポーネントでcrust状態およびsize状態のvariableプロパティのエンティティ値を設定する方法も示しています(これらの値が以前に設定されていない場合)。Textコンポーネントと同様に、System.Listコンポーネントには遷移は必要ありません。

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

ノート

ユーザーは、リストに表示されているオプションに制限されません。エンティティで認識される単語(シノニムなど)を入力することで、エンティティを解決できます。たとえば、ユーザーはリスト内のピザ・サイズのオプションの中から選択するかわりに、big (PizzaSizeエンティティのLargeオプションに対して定義されているシノニム)を入力できます。カスタム・エンティティを参照してください。

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"