D Référence Apache FreeMarker

Opérations de chaîne FreeMarker intégrées

Le tableau suivant vous montre comment utiliser certaines opérations de chaîne intégrées à l'aide d'une variable de chaîne appelée tester, dont la valeur est envoyée à "hello world " (avec trois espaces de fin).
Remarque

L'expression suivante permet au bot d'afficher la valeur tester ou no string found si aucune valeur n'a été définie pour la variable.
${tester.value!'no string found'}
Opération intégrée Utilisation Sortie
capitalize ${tester.value?capitalize} Hello World
last_index_of ${tester.value?last_index_of('orld')} 7
left_pad ${tester.value?left_pad(3,'_')} ___hello world
length ${tester.value?length} 14
lower_case ${tester.value?lower_case} hello world
upper_case ${tester.value?upper_case} HELLO WORLD
replace ${tester.value?replace('world', 'friends')} hello friends
remove_beginning ${tester.value?remove_beginning('hello')} world
trim ${tester.value?trim} hello world (les trois espaces de fin sont enlevés)
ensure_starts_with ${tester.value?ensure_starts_with('brave new ')} brave new hello world
ensure_ends_with ${tester.value?ensure_ends_with(' my friend')}$ hello world my friend
contains ${tester.value?contains('world')?string ('You said world', 'You did not say world')} You said world

Les expressions contains('world') renvoient true ou false. Ces valeurs booléennes sont remplacées par une chaîne à l'aide de la fonction string ('string1','string2').

ends_with ${tester.value?ends_with('world')?string ('Ends with world', 'Doesn't end with world')} Ends with world
starts_with ${tester.value?starts_with('world')?string ('Starts with world', 'Doesn't start with world')} Doesn't start with world
matches (l'expression régulière renvoie la valeur True ou False) ${tester.value?matches('^([^0-9]*)$')} L'expression régulière renvoie true ou false selon que la valeur contient un nombre (auquel cas la valeur booléenne est renvoyée comme false). La valeur tester renvoie true.
matches (l'expression régulière renvoie une chaîne) ${tester.value?matches('^([^0-9]*)$')?} Identique à la ligne ci-dessus, mais cette fois, true est renvoyé en tant que chaîne. La fonction matches('regular expression') renvoie true ou false sous forme de type booléen. Pour imprimer true ou false dans un composant System.Output, utilisez ?string pour effectuer une conversion vers une chaîne.

Remarque : vous ne pouvez pas utiliser d'expression régulière pour renvoyer un groupe de valeurs. Utilisez-les pour renvoyer une valeur correspondante unique (ou aucune correspondance).

Exemple : transformation de la casse avec le composant Switch

Imaginez un cas où différents états sont appelés en fonction de la saisie utilisateur (wine ou beer), stockée dans la variable choice.

La casse des entrées utilisateur peut être incohérente, même dans un mot (WiNE). Au lieu d'ajouter toutes les variations possibles à la définition du composant, utilisez une opération FTL telle que upper_case pour rendre la casse uniforme :
${choice.value?upper_case}

Exemple : concaténation d'expressions FTL

Vous pouvez également concaténer des opérations FTL en une seule expression.

Dans l'exemple suivant, les numéros de vol de la compagnie aérienne (représentés par la variable flight.value) de UA1234 et UA 1234 seraient tous deux transformés en 1234.
${flight.value?trim?lower_case?remove_beginning('ua ')?remove_beginning('ua')}"

Opérations de nombre FreeMarker intégrées

Le tableau suivant présente les opérations de nombre intégrées et montre comment elles fournissent la valeur définie pour les variables negativeValue (-2.5) et positiveValue (0.5175) :
Opération Exemple Sortie
abs ${negativeValue.value?abs} 2,5

L'opérateur convertit la valeur numérique négative en valeur positive.

string (utilisé avec une valeur numérique) ${negativeValue.value?abs?string.percent} 250%

L'opérateur commence par remplacer la valeur négative par un nombre positif. Il le convertit ensuite en pourcentage, en multipliant implicitement la valeur par 100.

string (avec la valeur de format décimal et différentes devises)

Conseil : reportez-vous à Charbase pour obtenir d'autres symboles de devise.

${positiveValue.value?string['###.##']} 0.51
${positiveValue.value?string['###.##%']} 51%

L'opérateur ajoute un caractère de pourcentage après avoir multiplié la valeur par 100.

${positiveValue.value?string['##.###\u00A4']} 0.51 $
${positiveValue.value?string['##.###\u20AC']} 0.51 €
${positiveValue.value?string['##.###\u00A3']} 0.51 £
round ${negativeValue.value?round} -2

L'opérateur arrondit la valeur au nombre entier le plus proche. Si le nombre se termine par .5, il est arrondi au chiffre supérieur.

${positiveValue.value?round} 1

L'opérateur arrondit la valeur au nombre entier le plus proche. Si le nombre se termine par .5, il est arrondi au chiffre supérieur.

floor ${positiveValue.value?floor} 0

L'opérateur arrondit le nombre à la valeur inférieure.

ceiling ${positiveValue.value?ceiling} 1

L'opérateur arrondit le nombre à la valeur supérieure.

lower_abc ${negativeValue.value?abs?round?lower_abc} c

L'opérateur convertit la valeur négative en un nombre positif, puis l'arrondit à 3. Il renvoie la lettre c, la troisième lettre de l'alphabet.

upper_abc ${negativeValue.value?abs?round?upper_abc} C

L'opérateur convertit la valeur négative en un nombre positif, puis l'arrondit à 3. Il renvoie la lettre C, la troisième lettre de l'alphabet.

is_infinite ${positiveValue.value?is_infinite?string} false

L'opérateur renvoie False, car une valeur float n'est pas infinie selon l'IEEE 754 (norme sur l'arithmétique à virgule flottante).

Remarque : la valeur renvoyée est une valeur booléenne sans ?string.

Opérations de tableau FreeMarker intégrées

Les opérations de tableau (ou de séquence ) permettent à votre bot, entre autres, de déterminer la taille d'un tableau, de trier des tableaux ou de rechercher du contenu dans un tableau.

Vous pouvez utiliser des tableaux pour créer des données de simulation à des fins de test ou pour définir des structures de données persistantes au-delà des sessions utilisateur. Vous pouvez enregistrer un tableau dans un composant personnalisé, dans un flux ou une variable globale. Voici les tableaux pour les variables person et colors, respectivement.
[
  {
    "firstName" : "Frank",
    "lastName" : "Normal"
  },
  {
    "firstName" : "Grant",
    "lastName" : "Right"
  },
  {
    "firstName" : "Geoff",
    "lastName" : "Power"
  },
  {
    "firstName" : "Marcelo",
    "lastName" : "Jump"
  }
]
[
    "yellow", "blue", "red", "black", "white", "green"
  ]
Ces tableaux permettent d'illustrer les opérations de tableau dans le tableau suivant et dans Exemple : itération de tableaux.
Opérateur Exemple Sortie
size ${person.value?size?number} 4 : taille (quatre membres) du tableau person.
index de tableau ${person.value[1].firstName} Grant : correspond à la valeur de la deuxième propriété firstName dans le tableau person.
${person.value[1].firstName !'unknown'} Identique à la ligne ci-dessus, mais dans ce cas, la sortie du bot est "unknown" si la deuxième propriété firstName n'a pas de valeur.
first ${person.value?first.firstName} Frank : première entrée du tableau person. Cette opération n'utilise pas l'index de tableau.
last ${person.value?last.firstName} Marcelo : dernière valeur lastName dans le tableau person.
sort_by ${person.value?sort_by('lastName') [0].firstName} Marcelo
Cet opérateur trie le tableau person en fonction de la propriété lastName dans l'ordre croissant. Il imprime ensuite la valeur de la propriété firstName correspondante pour l'entrée finale dans le tableau person :
  • Jump, Marcelo

  • Normal, Frank

  • Power, Geoff

  • Right, Grant

Remarque : à moins d'enregistrer le tableau trié dans une variable à l'aide de System.SetVariable, les données restent triées pour une seule demande uniquement.

${person.value?sort_by('lastName')?reverse[0].firstName} Grant : les valeurs sont triées par ordre décroissant.
  • Right, Grant

  • Power, Geoff

  • Normal, Frank

  • Jump, Marcelo

seq_index_of ${colors.value?seq_index_of('red')} 2 : valeur d'index pour le rouge dans le tableau colors.
seq_last_index_of ${colors.value?seq_last_index_of('red')} 2 : dernière valeur d'index pour le rouge dans
join ${colors.value?join(',')} Renvoie le tableau colors sous la forme d'une chaîne séparée par des virgules : yellow, blue, red, black, white, green
seq_contains ${colors.value?seq_contains('red')?string('Yes', 'No') Renvoie Yes car le tableau contient la valeur red.

Remarque : ?seq_contains renvoie une valeur booléenne. Cette valeur est ensuite remplacée par une chaîne utilisant l'expression ?string('…','…').

sort ${colors.value?sort?join(',')} Renvoie le tableau colors sous la forme d'une chaîne séparée par des virgules dans l'ordre croissant : black, blue, green, red, white, yellow
reverse ${colors.value?sort?reverse?join(',')} Renvoie le tableau colors sous la forme d'une chaîne séparée par des virgules dans l'ordre décroissant : yellow, blue, red, black, white, green

Renvoyer des intentions et des scores

Vous pouvez utiliser les opérations de tableau pour renvoyer les résultats du traitement de l'intention et de l'entité. Par exemple :
  • ${skill.system.nlpresult.value.entityMatches[‘name of entity’]} renvoie un tableau d'entités trouvées dans une chaîne utilisateur transmise au moteur d'intentions stocké dans la variable nlpresult.

  • ${skill.system.nlpresult.value.intentMatches.summary[n].intent} renvoie le nom de l'intention dont le classement de confiance est n, où 0 représente l'intention la mieux classée, 1 représente l'intention la moins classée, etc.

  • ${skill.system.nlpresult.value.intentMatches.summary[n].score} renvoie le score de confiance pour l'intention donnée.
Pour ces deux expressions, n est l'index de l'élément à rechercher. Par exemple, l'expression pour renvoyer le nom de l'intention résolue en tant qu'intention principale se présenterait comme suit :
${skill.system.nlpresult.value.intentMatches.summary[0].intent}
Pour le score de l'intention principale, l'expression se présenterait comme suit :
${skill.system.nlpresult.value.intentMatches.summary[0].score}

Vous pouvez utiliser ces expressions pour les intentions dont le score dépasse le seuil de confiance, mais également pour renvoyer les intentions dont le score est en dessous du seuil de confiance. Ces expressions ne dépendent pas de la valeur de seuil de confiance configurée sur la page Paramètres de la brique. Vous pouvez donc les utiliser pour renvoyer les intentions candidates et leurs scores même si aucune intention n'a pu être résolue et qu'une action unresolvedIntent a été déclenchée. Dans ce cas, vous pouvez, par exemple, utiliser ces expressions pour renvoyer les trois principales intentions et leurs scores de seuil de confiance respectifs.

Remarque

Si vous devez faire référence à l'intention qu'un utilisateur a sélectionnée après avoir été invité à lever l'ambiguïté, vous pouvez utiliser ${system.intent.name}. (${skill.system.nlpresult.value.intentMatches.summary[0].intent} renvoie toujours l'intention avec le score le plus élevé, ce qui peut ne pas être l'intention que l'utilisateur sélectionne lorsqu'il désambiguise.

Exemple : itération de tableaux

Les tableaux déterminent le nombre d'entités dans la saisie utilisateur.

Le snippet suivant de la propriété de métadonnées d'un composant de réponse commune montre comment déterminer la taille du tableau contenu dans la variable person, puis itérer ses éléments afin que la sortie de la brique ressemble à ce qui suit :


responseItems:
- type: "text"
  text: "${person?index+1}. ${person.firstName} ${person.lastName}"
  name: "Sorry"
  separateBubbles: true
  iteratorVariable: "person"
Remarque

La sortie décrite dans ce code n'est pas triée (autrement dit, aucune opération sort_by n'est utilisée).

Opérations de date FreeMarker intégrées

L'expression suivante déduit la date actuelle à l'aide de la référence de variable spéciale FreeMarker, .now et de l'opérateur date intégré.
${.now?date}
Le tableau suivant présente certaines des opérations de date intégrées qui permettent de définir des propriétés et de manipuler les valeurs d'entité.
Opération(s) Exemple Sortie
date ${.now?date} Date du jour
time ${.now?time} Heure de la journée, par exemple 17:46:09
datetime ${.now?datetime} Imprime la date et l'heure en cours, par exemple, 17 jan 2018 17:36:13.
long et number_to_date ${(.now?long + 86400000)?number_to_date } Ajoute 24 heures à la date actuelle. Si l'appel est effectué le 17 janvier 2018, la sortie de FreeMarker indiquera le 18 janvier 2018.
string (avec styles de formatage) ${.now?string.full} Convertit la date du jour en chaîne au format suivant : mercredi 17 janvier 2018 18:35:12 UTC.
${.now?string.long} Convertit une date en chaîne avec la sortie formatée de la manière suivante : 17 janvier 2018 18:36:47 UTC.
${.now?string.short} Convertit une date en chaîne avec la sortie formatée de la manière suivante : 1/17/18 18:37
${.now?string.medium} Convertit une date en chaîne avec la sortie formatée de la manière suivante : 17 jan 2018 18:38:35.
${.now?string.iso}

Imprime la date au format de la norme ISO 8601 : 2018-01-17T18:54:01.129Z.

string (avec les formats de sortie spécifiés) ${.now?string['dd.MM.yyyy, HH:mm']}

Imprime la date actuelle dans un format personnalisé, comme 17.01.2018, 18:58.

${.now?string['yyyy']}

2018

datetime (avec string et style de formatage) ${date_variable?datetime?string.short} Convertit la date en chaîne au format 1/17/18 18:37.

L'opérateur datetime permet à FreeMarker de déterminer si la variable contient une date qui contient à la fois les informations de date et d'heure. De même, vous pouvez utiliser les opérateurs date ou time pour indiquer si la valeur de date contient uniquement la date ou l'heure, mais l'utilisation de datetime?string permet d'éviter les erreurs.

Conversion de la valeur d'entité en chaîne à l'aide des éléments suivants :
  • date

  • long

  • number_to_date,

  • styles de formatage,

  • formats de date personnalisés.

${dateVar.value.date?long?number_to_date?date?string.short} Convertit la date de l'extraction de l'entité en une chaîne au format 11/17/18.

L'opérateur de date indique à FreeMarker que la variable contient uniquement une date, pas des informations d'heure. L'utilisation de ce format permet d'éviter les erreurs.

${dateVar.value.date?long?number_to_date?string.medium} Convertit la date déduite de l'extraction de l'entité en une chaîne formatée de la manière suivante : 17 jan 2018.

Remarque : tous les autres formats, tels que full, short, long et iso, fonctionnent de la même manière avec les dates déduites de l'extraction d'entité.

${dateVar.value.date?long?number_to_date?string['dd.MM.yyyy']} Imprime la date au format personnalisé. Par exemple : 17.01.2018, 18:58.
${dateVar.value.date?long?number_to_date?string['yyyy']} Imprime la date déduite de l'entité dans un format personnalisé.

Exemple : extraction de dates à partir de la saisie utilisateur

Les exemples suivants proviennent d'une brique qui gère les rendez-vous. Lorsqu'un utilisateur demande Can you arrange a meeting with Mr. Higgs a day later than tomorrow?, le bot utilise une entité complexe, DATE, pour extraire tomorrow de la demande. Il génère la date demandée à l'aide de ${(theDate.value.date?long + 86400000)?number_to_date} pour ajouter 24 heures (ou 86 400 000 millisecondes) à "demain".
Texte avec expression Sortie
"Today is: ${.now}"
  • Today is: 1/18/18 8:31 AM
"Date found is: ${theDate.value.date}"
  • Date found is: Jan 19, 2018

"A day later is ${(theDate.value.date?long + 86400000)?number_to_date}"
  • A day later is Jan 20, 2018

Exemple : définition d'une date par défaut (quand aucune valeur de date n'est définie)

Si le message utilisateur ne contient pas d'informations de date, votre brique peut inviter les utilisateurs à indiquer la date, ou fournir une date par défaut. Pour indiquer la date du jour, vous pouvez utiliser l'expression suivante :

${.now?datetime?string.long}

Variables système compatibles avec FreeMarker

Oracle Digital Assistant dispose d'un ensemble de variables système qui permettent d'extraire des informations utiles de vos flux de dialogue via des expressions FreeMarker.

Dans leur forme la plus simple, ces expressions ont le format suivant :

${system.variableName}

Certaines variables peuvent contenir des objets ayant des propriétés imbriquées accessibles à l'aide de la syntaxe par points après le nom de la variable au format suivant.

${system.variableName.propertyName}

En outre, les valeurs de propriété imbriquée peuvent également être des objets avec des propriétés imbriquées.

Voici les variables système disponibles via les expressions FreeMarker.

Variable Description
system.actualState Nom de l'état auquel l'utilisateur a accédé en touchant un ancien bouton "hors séquence". Si la charge utile de postback contient une propriété system.state, le moteur de dialogue accède à cet état et définit cette variable sur le nom de cet état. Reportez-vous également à Configuration du flux de dialogue pour les actions inattendues.
system.authorizedUsers Liste de tous les utilisateurs autorisés pour une discussion de groupe donnée.
system.channelType Type de canal de la session utilisateur en cours. Valeurs autorisées : facebook, androidsdk, iossdk, websdk, slack, twilio, msteams, cortana, webhook et test.

Si la session est exécutée dans le testeur, la valeur correspond au type de canal simulé.

system.entityToResolve Objet représentant l'élément de conteneur composite en cours à résoudre dans le composant de réponse commune lorsque la propriété de variable du composant fait référence à un objet de conteneur composite entity.The possède les propriétés suivantes :
  • nextRangeStart : numéro d'index de la liste des valeurs autorisées de l'entité à laquelle il sera possible d'accéder lorsque vous appuyez sur le bouton Afficher plus.
  • updatedEntities : liste des éléments de conteneur composite qui ont été mis à jour en fonction du dernier message utilisateur.
  • needShowMoreButton : propriété booléenne qui peut être utilisée en tant qu'expression pour la propriété visible afin d'afficher conditionnellement le bouton Afficher plus pour accéder à l'ensemble de valeurs d'entité suivant.
  • outOfOrderMatches : liste des éléments de conteneur remplis avec une valeur basée sur le dernier message utilisateur lorsque l'utilisateur a été invité à indiquer un autre élément de conteneur.
  • rangeStartVar : nom de la variable qui contient le début de la plage en cours des valeurs d'entité.
  • validationErrors : liste des messages d'erreur liés à une valeur non valide fournie dans le dernier message utilisateur pour l'élément de conteneur en cours.
  • allMatches : liste des éléments de conteneur ayant obtenu de nouvelles valeurs ou des valeurs mises à jour en fonction du dernier message utilisateur.
  • resolvingField : nom de l'élément de conteneur en cours que l'utilisateur est invité à entrer.
  • userInput : dernier message utilisateur.
  • skippedItems : liste des éléments de conteneur pour lesquels le nombre maximal d'invites pour une valeur est dépassé.
  • disambiguationValues : liste des valeurs d'entité autorisées qui ont des correspondances dans le dernier message utilisateur.
  • enumValues : liste des valeurs d'entité autorisées pour l'élément de conteneur actuel.

Reportez-vous à Variable system.entityToResolve pour obtenir des exemples d'utilisation de system.entityToResolve.

system.errorAction Texte du message d'erreur d'une erreur inattendue générée lors de l'exécution de l'état.
system.errorState Nom de l'état ayant généré une erreur inattendue au cours de l'exécution.
system.expectedState Lorsque l'utilisateur fait défiler l'historique des messages vers le haut, et qu'il touche un ancien bouton "hors séquence", cette variable est remplie avec le nom de l'état qui devait être exécuté, mais n'a jamais été exécuté car l'utilisateur a décidé de toucher ce bouton "hors séquence". Reportez-vous également à Configuration du flux de dialogue pour les actions inattendues.
system.intent.name Utilisez cette option pour faire référence à l'intention qu'un utilisateur a sélectionnée après avoir été invité à lever l'ambiguïté. (
${iResult.value.intentMatches.summary[0].intent}
renvoie toujours l'intention avec le score le plus élevé, qui n'est peut-être pas l'intention que l'utilisateur sélectionne lorsqu'il désambiguise.)
system.invalidUserInput Une valeur booléenne est définie sur true lorsque la saisie utilisateur ne correspond pas au type de variable demandé.
system.message Dernier message reçu par Oracle Digital Assistant. La variable possède les propriétés suivantes :
  • channelConversation : objet de conversation de canal, qui possède les propriétés suivantes :
    • botId
    • channelType : lors de l'exécution dans le testeur, cette fonction renvoie test. Pour obtenir le nom du canal simulé dans le testeur, utilisez system.channelType à la place.
    • channelName
    • channelCategory : renvoie le type de canal. Pour les canaux DA en tant qu'agent, cette commande renvoie botAsAgent.
    • groupConversation : renvoie true si la conversation est une discussion de groupe.
    • userId : renvoie l'ID utilisateur. Pour les canaux DA en tant qu'agent, l'ID d'engagement est renvoyé.
    • sessionId : renvoie l'ID de session. Pour les canaux DA en tant qu'agent, l'ID d'engagement est renvoyé.
    • sessionExpiryDuration
  • messagePayload : message réel envoyé par l'utilisateur. Les propriétés auxquelles vous pouvez accéder dépendent du type de message :
    • Message texte : la propriété text renvoie le message réel entré par l'utilisateur.
    • Message de retour : propriétés de l'objet de retour, généralement action et variables, lors de l'utilisation du composant Réponse commune. Par exemple, lorsque l'utilisateur touche un bouton qui définit la variable pizzaSize, cette valeur peut être récupérée à l'aide de l'expression suivante : ${system.message.messagePayload.variables.pizzaSize}
    • Message d'emplacement : la propriété location, qui contient un objet d'emplacement avec les propriétés suivantes :
      • title
      • url
      • latitude
      • longitude
  • stateCount : nombre d'états exécutés pour traiter le dernier message utilisateur.
  • platformVersion : version actuelle de la plate-forme d'exécution.
system.requestedState Si un utilisateur arrive dans une conversation avec un état nécessitant une autorisation et qu'il ne figure pas dans la liste des utilisateurs stockés dans system.authorizedUsers, le moteur de dialogue stocke l'état qu'il a prévu d'exécuter dans cette variable.
system.selectedCardIndex Cette variable contient l'index de la carte sélectionnée lors de l'utilisation du site afin d'optimiser l'affichage des cartes pour les canaux de type texte uniquement, comme Twilio. Cette optimisation permet à l'utilisateur de sélectionner une carte dans un processus en deux étapes : la première liste des cartes est présentée, puis l'utilisateur peut saisir le nombre de cartes qu'il souhaite sélectionner. Le numéro d'index correspondant de cette carte est stocké dans cette variable.
Remarque

Les variables système du tableau ci-dessus sont les seules que vous pouvez utiliser dans les expressions FreeMarker. Les autres variables système ne sont pas publiques et leur utilisation est sujette à changement, ce qui signifie que vos compétences ne peuvent pas compter sur elles.

Par exemple, les variables system.routingFromSkill, system.routingToSkill, system.routingFromIntent et system.routingToIntent ne sont disponibles que pour des paramètres d'assistant numérique spécifiques. Reportez-vous à Variables système pour les assistants numériques.