La configuration des composants System.CommonResponse implique la définition de propriétés qui dirigent le moteur de dialogue avec des propriétés de métadonnées qui décrivent non seulement la façon dont le composant livre les messages (comme les invites de texte, les cartes ou les pièces jointes), mais également la définition du contenu et du comportement pour les messages eux-mêmes.

Voici le YAML pour un exemple d'état basé sur le composant 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"
...
      

Voici un exemple simple d'accès aux valeurs d'attribut d'une enquête :

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

Le diagramme suivant illustre l'implémentation de la méthode à un seul état si votre flux de dialogue est créé en mode YAML. 1) Vous utilisez une variable de contexte de correspondance pour associer les intentions de connaissances aux termes de recherche. 2) Vous définissez chaque intention de connaissances action dans l'état Intent pour passer à un flux de données qui utilise la correspondance afin de définir la variable de contexte searchTerm sur le terme de recherche de l'intention. 3) Vous passez ensuite à un état qui recherche la valeur searchTerm dans la base de connaissances.

description de l'illustration kf-assoc-intent-term.png,

Voici un exemple de flux de dialogue dans lequel il existe des intentions individuelles pour chaque réponse de la base de connaissances.

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

states:

  #
  # Set search term for each knowledge intent
  #

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

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

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

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

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

L'exemple suivant montre comment définir searchTerm sur la variation de l'utilisateur dans une brique de boîte de dialogue YAML. Pour une brique de dialogue visuelle, utilisez plutôt ${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"

Voici un exemple de flux de dialogue qui effectue un transfert vers un agent lorsque le client demande à parler à un agent:

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"

Lorsque vous transférez une conversation d'un assistant numérique vers un agent physique, vous pouvez utiliser des propriétés personnalisées dans le composant System.AgentTransfer pour transmettre ces informations.

Voici la structure pour Oracle B2C Service :

      customProperties:
        - name: 
          value: 
          type:

La propriété type est requise pour les champs personnalisés. Sinon, elle est facultative.

Voici la structure d'Oracle Fusion Service :

      customProperties:
        - name: 
          value:

Voici un exemple de paramètre customProperties pour 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"

Voici un exemple de flux de dialogue qui appelle le composant, affiche le temps d'attente et donne à l'utilisateur la possibilité d'annuler sa demande de transfert.

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

L'état askIfWillWait utilise une entrée de groupe de ressources pour former le message de temps d'attente de sorte que le message indique si le temps est supérieur ou inférieur à une minute et si un nombre est égal à 0, un ou plusieurs.

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?

Notez que cet exemple utilise System.SetCustomMetrics pour suivre si des agents étaient disponibles et, le cas échéant, combien d'utilisateurs ont choisi d'attendre et combien ont annulé la demande de transfert.

Si vous souhaitez transférer une conversation de la brique à un agent Oracle B2C Service, ajoutez ce composant au flux de dialogue afin de lancer l'établissement de liaison avec le canal d'intégration d'agent indiqué par la propriété agentChannel. Vous devez appeler ce composant avant d'appeler le composant System.AgentConversation.

Ce composant est destiné aux conversations qui proviennent de la brique. N'utilisez pas ce composant pour les conversations qui proviennent de la discussion Oracle B2C Service, comme décrit dans La structure d'assistant numérique en tant qu'agent en action.

Voici un exemple d'utilisation de ce composant pour lancer l'établissement de liaison avec l'instance Oracle B2C Service définie par le canal d'intégration d'agent nommé ServiceCloudIntegration.

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

Conseil :

Dans les briques avec les versions 21.04 et ultérieures de la plate-forme, les valeurs par défaut des propriétés agentActionsMessage, errorMessage, rejectedMessage, resumedMessage et waitingMessage sont stockées dans le groupe de ressources de la brique. Pour modifier une valeur par défaut, ouvrez la page Groupe de ressources de la brique, cliquez sur , sélectionnez l'onglet Configuration et modifiez le message de la clé AgentInitiation - <nom de propriété>. Si vous utilisez le groupe de ressources de la brique pour modifier le message par défaut, vous n'avez pas besoin d'inclure la propriété de message dans le composant, sauf si vous voulez remplacer le message par défaut.

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

Voici un exemple de gestion des erreurs système et des actions error et 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}"

Cet exemple définit 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}"

L'exemple suivant définit interfaceID et 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}"

Ces étapes décrivent comment déclarer l'objet customProperties et définir ses différentes valeurs.

Ce composant permet de transférer la conversation d'une brique à un agent physique Oracle B2C Service et de gérer l'échange entre la brique et l'agent. Vous devez appeler le composant System.AgentInitiation pour pouvoir utiliser ce composant.

System.AgentConversation est destiné aux conversations qui proviennent de la brique. N'utilisez pas ce composant pour les conversations qui proviennent de la discussion Oracle B2C Service, comme décrit dans La structure d'assistant numérique en tant qu'agent en action.

Voici un exemple d'utilisation de ce composant pour transférer la conversation à l'instance Oracle B2C Service définie par le canal d'intégration d'agent nommé ServiceCloudIntegration.

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

System.AgentConversation peut déclencher l'action expired, agentLeft, error ou waitExpired. En outre, il peut déclencher une action à partir de la propriété agentActions du composant System.AgentInitiation. Vous devez également ajouter une transition next car un client peut saisir l'un des exitKeywords pour quitter la discussion afin que l'une de ces actions puisse être déclenchée.

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

Dans cet exemple, l'intention GetAgent est entraînée à comprendre les appels de détresse comme aidez-moi s'il vous plait !

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

Voici les étapes de base pour configurer le flux de dialogue :

1. Lancez le transfert à l'agent physique.

   1. Ajoutez un état pour le composant System.AgentInitiation.

   2. Définissez la propriété agentChannel de l'état sur le nom du canal d'intégration d'agent que vous avez configuré pour le système d'agent physique.

   Une fois que le canal d'intégration d'agent a établi une connexion et qu'Oracle B2C Service a envoyé la demande de discussion à la file d'attente (c'est-à-dire, une fois qu'il a créé un ticket d'aide), le composant System.AgentInitiation permet la transition vers l'état suivant, qui est généralement défini pour le composant System.AgentConversation (agentConversation dans l'exemple suivant).

   
     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"

   Conseil :

   Les clients peuvent demander plusieurs fois à discuter avec un agent physique même lorsque leurs demandes ont déjà été mises dans la file d'attente de la console de discussion de l'agent. Ajoutez une propriété resumedMessage à l'état System.AgentInitiation pour empêcher ces clients de recevoir un message Reprise de la discussion avec un agent qui pourrait les induire en erreur.

2. Ajoutez et configurez le composant System.AgentConversation. Tant que le moteur de dialogue se trouve dans l'état défini pour ce composant, la brique transmet les messages entre le client et l'agent. La brique écoute les mots-clés de sortie dans l'entrée client, comme au revoir. Lorsque la brique détecte l'un de ces mots-clés, le composant System.AgentConversation met fin à la session en cours et déclenche la transition next.

   Voici un exemple :

     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"

Dans l'exemple suivant utilisant le format standard, le composant AgentConversation génère un lien d'enquête après la fin de la conversation avec l'agent. Le lien inclut les ID de session et d'interaction de la correspondance nommée par la propriété chatResponseVariable.

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

1. Si vous ne l'avez pas encore fait, dans le noeud de contexte, définissez une variable de correspondance à utiliser avec la propriété customProperties du composant System.AgentInitiation. Par exemple :

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

2. Définissez les champs de la variable de correspondance.

   Voici un exemple de format standard pour les canaux d'intégration d'agent créés dans la version 20.01 ou version ultérieure et connectés à Oracle B2C Service version 19A ou ultérieure.

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

   Voici un exemple de format hérité pour les canaux d'intégration d'agent créés avant la version 20.01 ou qui se connectent à une version antérieure à Oracle B2C Service version 19A.

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

3. Ajoutez la propriété customProperties au composant System.AgentInitiation et définissez-la sur la valeur de votre variable de correspondance. Par exemple :

     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"

Pour activer l'interaction entre une brique et un fournisseur de calendrier, vous devez configurer un service, et modifier la brique et le flux de dialogue afin de permettre à l'utilisateur de se connecter à son calendrier via ce service.

Avant d'utiliser un composant de calendrier, vous devez inscrire une application auprès du fournisseur de calendrier et créer un service de code d'autorisation. Pour obtenir les procédures, reportez-vous aux rubriques suivantes :

• Inscription d'une application pour autorisation auprès de Google OAuth2

• Inscription d'une application auprès de la plate-forme d'identité Microsoft

• Ajout d'un service de code d'autorisation

Dans votre flux de dialogue, vous utilisez le composant System.OAuth2AccountLink pour inviter l'utilisateur à se connecter à son calendrier via le service de code d'autorisation que vous avez créé. Vous ne pouvez pas définir la propriété enableSingleSignOn du composant sur true lorsque vous utilisez le composant pour l'autorisation de composant de calendrier.

Vous pouvez utiliser la fonctionnalité Autorisation requise pour vérifier automatiquement que l'utilisateur s'est connecté (a obtenu un jeton d'accès) avant d'appeler des composants de calendrier. Cette fonctionnalité demande uniquement à l'utilisateur de se connecter s'il ne dispose pas encore d'un jeton d'accès, ou si celui-ci a expiré et ne peut pas être actualisé. Vous pouvez utiliser la configuration Autorisation requise de la brique afin de définir la valeur par défaut pour l'ensemble de la brique, puis appliquer le paramètre requiresAuthorization au niveau de l'état pour remplacer la valeur par défaut. Autrement dit, vous utilisez le paramètre de la brique pour définir la valeur par défaut, puis incluez uniquement le paramètre requiresAuthorization du composant dans les états pour lesquels la valeur par défaut ne s'applique pas.

Pour utiliser la fonctionnalité Autorisation requise, vous devez ajouter une action system.authorizeUser au noeud defaultTransitions afin de nommer l'état qui démarre le flux d'autorisation. Par exemple :

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

Avant qu'une brique passe à un état avec autorisation requise, elle vérifie s'il existe un jeton d'accès valide pour le service de calendrier. Si le jeton est absent, elle effectue les actions suivantes :

1. Elle appelle l'état que vous avez défini pour l'action system.authorizedUser dans le noeud defaultTransitions.

2. Elle demande à l'utilisateur de se connecter.

3. Elle passe à l'état nécessitant une autorisation (c'est-à-dire l'état défini par ${system.requestedState}).

Voici un exemple de flux de dialogue d'autorisation :

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" 

Pour une brique principalement axée sur les composants de calendrier, envisagez de définir la configuration Autorisation requise de la brique sur true, puis définissez la valeur sur False uniquement pour les états qui ne nécessitent pas d'autorisation. Dans cet exemple, n'importe quel utilisateur peut exécuter les états initTimezoneOffset et intent. Par conséquent, le paramètre requiresAuthorization est défini sur false pour ces états. Les états qui utilisent les composants de calendrier n'ont pas besoin d'inclure requiresAuthorization car la valeur par défaut est 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"

Lorsque vous utilisez les composants de calendrier, il est important de comprendre la relation entre les heures de début et de fin du calendrier, les entités DATE et TIME, et le fuseau horaire local.

Lorsque vous créez, mettez à jour ou extrayez des événements, vous utilisez la date et l'heure locales pour les valeurs start et end, et soit timezoneOffset, soit timezone pour indiquer au composant comment calculer le temps universel (UTC).

La valeur timezoneOffset des composants de calendrier est différente de profile.timezoneOffset. Pour les composants de calendrier, timezoneOffset est la valeur que le composant doit ajouter aux valeurs start et end pour obtenir l'heure UTC. Vous pouvez déduire la valeur de propriété timezoneOffset d'un composant de calendrier en multipliant profile.timezoneOffset par -1.

Il est possible que profile.timezoneOffset ne soit pas toujours disponible. Tout dépend de la fourniture ou non du décalage par le client. Par exemple, quelqu'un peut créer une application Web Oracle qui ne définit pas profile.timezoneOffset. Par conséquent, il est recommandé de créer un fuseau horaire par défaut pour les cas où le paramètre profile.timezoneOffset n'a pas été défini. Par exemple :

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

Lorsque vous récupérez un événement, le composant renvoie les valeurs de date/d'heure au format UTC. Par exemple : 2021-04-15T22:00:00.000Z. Votre brique doit convertir la valeur à l'heure locale.

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

Lorsque vous utilisez les entités DATE et TIME, voici quelques points à prendre en compte :

• Si vous utilisez un conteneur composite comportant à la fois une entité DATE et des entités TIME, vous devez désactiver l'option Extraction dans le désordre. Sinon, lorsque les entités sont résolues, vous n'avez pas le contrôle sur les valeurs résolues en entité DATE et les valeurs résolues en entité TIME (ou les deux). Par exemple, lorsque l'entité TIME est résolue, elle peut modifier la valeur de l'entité DATE.

• Lorsqu'une variation contient du texte tel que "hier", "aujourd'hui" ou "demain", l'analyseur ne prend pas en compte le fuseau horaire local. Il est donc possible que, tôt le matin et tard l'après-midi, la mauvaise date soit utilisée. C'est pourquoi il est recommandé de renvoyer la date résolue afin que l'utilisateur puisse la vérifier avant que la brique n'ajoute un événement, ou ne mette à jour l'heure de début ou de fin d'un événement.

• Pour définir les valeurs des propriétés start et end d'un calendrier, vous devez utiliser la date de l'entité DATE et l'heure de l'entité TIME. Par exemple :

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

Le fournisseur de calendrier peut rejeter une demande d'événement. Par exemple, il peut renvoyer une erreur si l'utilisateur tente de créer un événement dont l'heure de fin est antérieure à l'heure de début. Dans la plupart des cas, le fournisseur de calendrier renvoie une erreur 400 qui, à son tour, transmet la brique au gestionnaire d'erreurs global.

Envisagez de valider les valeurs afin d'éviter que ces erreurs ne se produisent. Voici des exemples de validation d'entité de conteneur composite :

• Entité DATE : pour les réunions nouvelles et mises à jour, vérifiez que la date est identique ou postérieure à la date du jour.

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

• Entité TIME : pour les réunions nouvelles et mises à jour, vérifiez que la date et l'heure de début sont identiques ou postérieures à la date et à l'heure en cours.

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

  Pour toutes les heures de fin, vérifiez que l'heure de fin est postérieure à l'heure de début.

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

Pour gérer sans erreur les rejets de fournisseur de calendrier, ajoutez votre propre gestionnaire d'erreurs global. Par exemple :

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"

Vous pouvez également utiliser la transition des erreurs pour créer des gestionnaires d'erreurs adaptés à chaque cas :

  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"

Utilisez ce composant pour ajouter un événement à un calendrier Outlook ou Google. Vous ne pouvez pas créer d'événements récurrents ou d'une journée entière.

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Pour découvrir comment définir les valeurs start et end, reportez-vous à Utilisation des dates et heures du calendrier.

Voici un exemple d'utilisation de ce composant. Dans cet exemple, une entité de conteneur composite est utilisée pour obtenir la date, les heures de début et de fin, l'objet, le lieu et les participants.

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

Utilisez ce composant pour supprimer un événement d'un calendrier Outlook ou Google. Vous ne pouvez pas supprimer des événements récurrents ou d'une journée entière.

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Voici un exemple d'utilisation de ce composant.

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

Utilisez ce composant pour obtenir les détails d'un événement à partir d'un calendrier Outlook ou Google.

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Les détails sont renvoyés dans la variable spécifiée par la propriété eventDetailsVariableName au format JSON suivant :

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

Les propriétés start et end sont des valeurs UTC. Pour découvrir comment convertir les valeurs start et end à l'heure locale, reportez-vous à Utilisation des dates et heures du calendrier.

Voici un exemple d'utilisation de ce composant.

  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"

Utilisez ce composant afin d'obtenir un tableau des événements Outlook ou Google pour un propriétaire de calendrier nommé. Vous pouvez filtrer la liste sur les attributs suivants :

• L'événement peut être supprimé
• L'événement peut être mis à jour
• L'utilisateur a été invité à l'événement
• Réponse de l'utilisateur à une invitation
• L'événement inclut des participants nommés
• La réunion commence après une date et une heure données
• La réunion se termine avant une date et une heure données

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

La liste est renvoyée dans la variable spécifiée par la propriété eventListVariableName au format JSON suivant :

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

Pour découvrir comment définir les valeurs start et end, reportez-vous à Utilisation des dates et heures du calendrier. Cette rubrique explique également comment convertir les valeurs des propriétés JSON start et end à l'heure locale.

Voici un exemple d'utilisation de ce composant.

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

Ce composant peut renvoyer les actions suivantes :

Utilisez ce composant pour afficher la liste des événements Outlook ou Google que l'utilisateur peut sélectionner. Le composant enregistre l'ID de l'événement sélectionné dans la variable spécifiée par la propriété eventIdVariableName.

Vous pouvez filtrer la liste de sélection sur les attributs suivants :

• L'événement peut être supprimé
• L'événement peut être mis à jour
• L'utilisateur a été invité à l'événement
• Réponse de l'utilisateur à une invitation
• L'événement inclut des participants nommés
• La réunion commence après une date et une heure données
• La réunion se termine avant une date et une heure données

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Pour découvrir comment définir les valeurs start et end, reportez-vous à Utilisation des dates et heures du calendrier.

Voici un exemple d'utilisation de ce composant.

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

Propriété	Description	Requis ?
provider	Fournisseur de calendrier. Valeurs autorisées : Google et Outlook.	Oui
calendarOwner	ID utilisateur du propriétaire du calendrier. Il doit s'agir d'un ID de compte valide pour le fournisseur de calendrier, tel que la valeur de la variable identifiée par la propriété authenticatedUserVariable du composant System.OAuth2AccountLink, définie lors de l'authentification de l'utilisateur.	Oui
calendarId	Nom du calendrier. Pour le calendrier par défaut de l'utilisateur, définissez la même valeur que pour la propriété calendarOwner.	Oui
credential	Jeton d'accès du fournisseur. Il s'agit de la valeur de la variable identifiée par la propriété accessTokenVariableName du composant System.OAuth2AccountLink, définie lors de l'authentification de l'utilisateur.	Oui
listType	Indique le type de liste. Il doit s'agir de l'un des suivants : ALL : tous les types de réunion du propriétaire du calendrier DELETE : toutes les réunions que le propriétaire du calendrier peut supprimer UPDATE : toutes les réunions que le propriétaire du calendrier peut mettre à jour INVITED : toutes les réunions qui ne sont pas organisées par le propriétaire du calendrier, mais auxquelles il est invité à participer	Oui
eventIdVariableName	Nom de la variable de contexte dans laquelle stocker l'ID de l'événement.	Oui
start	Date et heure les plus anciennes pour lesquelles les réunions doivent être incluses dans la liste (format : yyyy-MM-dd'T'HH:mm:ss). Par exemple, 2021-02-26T09:55:00.	Oui
end	Date et heure les plus récentes pour lesquelles les réunions doivent être incluses dans la liste (format : yyyy-MM-dd'T'HH:mm:ss). Par exemple, 2021-02-26T09:55:00. Pour le type de liste INVITED, la valeur par défaut est 14 jours après la date et l'heure de début. Pour tous les autres types, la valeur par défaut est 24 heures après la date et l'heure de début.	Non
attendees	Liste des chaînes, séparées par des virgules et sans distinction entre les majuscules et les minuscules, à utiliser pour filtrer la liste sur les participants. Seules les réunions pour lesquelles des valeurs de participant contiennent des chaînes de la liste sont incluses dans la sortie.	Non
response	Liste des statuts d'invitation, séparés par des virgules, sur lesquels filtrer la liste lorsque listType a la valeur INVITED. Les statuts possibles sont les suivants : ACCEPTED TENTATIVE DECLINED PENDING La valeur par défaut est PENDING,TENTATIVE, qui affiche uniquement les invitations en attente de réponse ou acceptées provisoirement.	Non
prompt	Texte qui apparaît avant la liste. La valeur par défaut est You have the following meeting(s):. Vous n'avez pas besoin d'inclure cette propriété, sauf si vous voulez remplacer la valeur par défaut. Conseil : Dans les briques avec les versions 21.04 et ultérieures de la plate-forme, la valeur par défaut est stockée dans le groupe de ressources de la brique. Pour modifier la valeur par défaut, ouvrez la page Groupe de ressources de la brique, cliquez sur , sélectionnez l'onglet Configuration et modifiez le message de la clé SelectCalendarEvent - prompt.	Non
allDayLabel	Texte indiquant les événements d'une journée entière. La valeur par défaut est All day.	Non
recurringLabel	Texte indiquant un événement récurrent. La valeur par défaut est Recurring.	Non
acceptedLabel	Texte indiquant que le propriétaire du calendrier a accepté l'invitation. La valeur par défaut est Accepted.	Non
tentativeLabel	Texte indiquant que le propriétaire du calendrier a accepté l'invitation provisoirement. La valeur par défaut est Tentative.	Non
declinedLabel	Texte indiquant que le propriétaire du calendrier a refusé l'invitation. La valeur par défaut est Declined.	Non
pendingLabel	Texte indiquant que le propriétaire du calendrier n'a pas encore répondu à l'invitation. La valeur par défaut est Pending.	Non
timezoneOffset	Durée en millisecondes à ajouter au temps universel (UTC) pour obtenir l'heure standard dans le fuseau horaire de l'utilisateur. Par exemple, si le fuseau horaire local est UTC-2, timezoneOffset est -7200000. La valeur par défaut est 0. Remarque Vous pouvez déduire la propriété timezoneOffset pour l'utilisateur en cours en fonction de la valeur de la variable de contexte utilisateur profile.timezoneOffset. Toutefois, dans ce cas, vous devez multiplier profile.timezoneOffset par -1. Vous pouvez indiquer timezoneOffset ou timezone, mais pas les deux.	Non
timezone	ID du fuseau horaire local identifié par https://www.iana.org/time-zones. Egalement appelé nom tz database. Par exemple : America/Los_Angeles. La valeur par défaut est UTC. Vous pouvez indiquer timezoneOffset ou timezone, mais pas les deux.	Non

Ce composant peut renvoyer les actions suivantes :

Utilisez ce composant pour accepter, accepter provisoirement ou refuser une invitation à un événement de calendrier Outlook ou Google.

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Voici un exemple d'utilisation de ce composant.

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

Utilisez ce composant pour apporter des modifications à un événement de calendrier Outlook ou Google. Vous ne pouvez pas mettre à jour des événements récurrents ou d'une journée entière.

L'utilisateur doit être connecté au fournisseur de calendrier pour accéder à ce composant. Vous pouvez utiliser la fonctionnalitéAutorisation requise pour gérer la connexion utilisateur, comme décrit dans Autorisation de calendrier.

Pour découvrir comment définir les valeurs start et end, reportez-vous à Utilisation des dates et heures du calendrier.

Voici un exemple d'utilisation de ce composant. Dans cet exemple, une entité de conteneur composite est utilisée pour obtenir la date, l'heure de début et l'heure de fin.

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

Dans cet exemple, la variable type contient les valeurs attendues par l'entité PizzaType, comme cheese, Veggie Lover et Hawaiian. Lorsque cette information est manquante dans la saisie utilisateur, le bot peut tout de même l'obtenir, car son flux de dialogue passe à l'état type, dont le composant System.Text invite l'utilisateur à indiquer explicitement ce qu'il veut. Gardez à l'esprit que même à ce stade, la saisie utilisateur doit quand même être résolue en entité PizzaType pour passer à l'état suivant.

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

Vous pouvez utiliser le composant System.List pour renvoyer une valeur qui remplit une variable de contexte définie comme primitive (comme greeting: "string" dans le modèle de flux de dialogue) ou comme entité, comme indiqué dans le fragment de code suivant. Dans ce flux de dialogue, la définition options: "Thick,Thin,Stuffed,Pan" renvoie une valeur qui correspond à la variable crust. La propriété options définie pour size est une expression de valeur (${size.type.enumValues}) qui renvoie les valeurs de liste Large, Medium, Small et Personal en tant qu'options. Reportez-vous à Syntaxe de langage de modèle Apache FreeMarker.

Cet exemple montre également comment la définition iResult de la propriété nlpResultVariable permet au composant de définir les valeurs d'entité des propriétés variable pour les états crust et size lorsque ces valeurs n'ont pas été définies. Comme pour le composant Text, le composant System.List ne requiert aucune transition.

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

Remarque

Les utilisateurs ne sont pas limités aux options affichées dans la liste. Ils peuvent résoudre l'entité en saisissant un mot que l'entité reconnaît, comme un synonyme. Au lieu de choisir parmi les options de taille de pizza dans la liste, par exemple, les utilisateurs peuvent entrer big, un synonyme défini pour l'option Large de l'entité PizzaSize. Reportez-vous à Entités personnalisées.

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"