Referencia de Apache FreeMarker

Operaciones de cadena de FreeMarker incorporadas

La tabla siguiente muestra cómo utilizar algunas de las operaciones de cadena incorporadas mediante el uso de una variable de cadena denominada tester, cuyo valor se envía a "hello world " (con tres espacios en blanco finales).

Nota

La siguiente expresión permite al bot generar el valor tester o no string found si no se ha definido ningún valor para la variable.

${tester.value!'no string found'}

Operación incorporada	Uso	Salida
`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`
`reemplazar`	`${tester.value?replace('world', 'friends')}`	`hello friends`
`remove_beginning`	`${tester.value?remove_beginning('hello')}`	`world`
`trim`	`${tester.value?trim}`	`hello world` (los tres espacios finales se eliminan)
`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` Las expresiones `contains('world')` devuelven `true` o `false`. Estos valores booleanos se sustituyen por una cadena mediante la función `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` (la expresión regular devuelve true o false)	`${tester.value?matches('^([^0-9]*)$')}`	La expresión regular devuelve `true` o `false`, en función de si el valor contiene un número (en cuyo caso el valor booleano se devuelve como `false`). El valor `tester` devuelve `true`.
`matches` (la expresión regular devuelve una cadena)	`${tester.value?matches('^([^0-9]*)$')?}`	Igual que antes, pero esta vez `true` se devuelve como cadena. La función `matches('regular expression')` devuelve `true` o `false` como tipos booleanos. Para imprimir `true` o `false` en un componente `System.Output`, use `?string` para realizar una conversión a cadena. Nota: no puede utilizar una expresión regular para devolver un grupo de valores; utilícela para devolver un único valor coincidente (o sin coincidencia).

Ejemplo: transformación de casos con el componente Switch

Imagine un caso en el que se llaman a diferentes estados según la entrada del usuario (wine o beer), que se almacena en la variable choice.

Las mayúsculas o minúsculas de la entrada del usuario pueden ser inconsistentes, incluso dentro de una sola palabra (WiNE). En lugar de agregar todas las variaciones posibles a la definición del componente, utilice una operación FTL, como upper_case para uniformar las mayúsculas y minúsculas:

${choice.value?upper_case}

Ejemplo: concatenación de expresiones FTL

También puede concatenar operaciones FTL en una sola expresión.

En el siguiente ejemplo, los números de vuelo de la aerolínea (representados por la variable flight.value) de UA1234 y UA 1234 se transformarían en 1234.

${flight.value?trim?lower_case?remove_beginning('ua ')?remove_beginning('ua')}"

Operaciones numéricas de FreeMarker incorporadas

La siguiente tabla muestra las operaciones numéricas incorporadas y la forma en la que se muestra el juego de valores para las variables negativeValue (-2,5) y positiveValue (0,5175):

Operación	Ejemplo	Salida
`abs`	`${negativeValue.value?abs}`	2,5 El operador convierte el valor numérico negativo en un valor positivo.
`string` (se utiliza con un valor numérico)	`${negativeValue.value?abs?string.percent}`	250% El operador cambia, en primer lugar, el valor negativo por uno positivo. A continuación, lo convierte en un porcentaje multiplicando implícitamente el valor por 100.
`string` (con el valor de formato decimal y varias monedas) Consejo: Busque en Charbase los símbolos de otras monedas.	`${positiveValue.value?string['###.##']}`	0,51
	`${positiveValue.value?string['###.##%']}`	51% El operador agrega un carácter de porcentaje después de multiplicar el valor por 100.
	`${positiveValue.value?string['##.###\u00A4']}`	0,51 $
	`${positiveValue.value?string['##.###\u20AC']}`	0,51 €
	`${positiveValue.value?string['##.###\u00A3']}`	0,51 £
`round`	`${negativeValue.value?round}`	-2 El operador redondea al número entero más cercano. Si el número termina en ,5, redondea hacia arriba.
`round`	`${positiveValue.value?round}`	1 El operador redondea al número entero más cercano. Si el número termina en ,5, redondea hacia arriba.
`floor`	`${positiveValue.value?floor}`	0 El operador redondea hacia abajo.
`ceiling`	`${positiveValue.value?ceiling}`	1 El operador redondea hacia arriba.
`lower_abc`	`${negativeValue.value?abs?round?lower_abc}`	c El operador convierte el valor negativo en positivo y, a continuación, lo redondea a 3. Devuelve c, la tercera letra del alfabeto.
`upper_abc`	`${negativeValue.value?abs?round?upper_abc}`	C El operador convierte el valor negativo en positivo y, a continuación, lo redondea a 3. Devuelve C, la tercera letra del alfabeto.
`is_infinite`	`${positiveValue.value?is_infinite?string}`	false El operador devuelve false, ya que un valor flotante no es infinito según IEEE 754 (estándar para aritmética en coma flotante). Nota: el valor devuelto será un booleano sin `?string`.

Operaciones de matriz de FreeMarker Incorporadas

Las operaciones de matriz (o sequence ) permiten al bot, entre otras cosas, determinar el tamaño de una matriz, ordenar las matrices o buscar contenido en una matriz.

Puede utilizar matrices para crear datos ficticios para pruebas o para definir estructuras de datos que se mantengan más allá de las sesiones del usuario. Puede guardar una matriz en un componente personalizado, en un flujo o en una variable global. Aquí hay matrices para las variables person y colors, respectivamente.

[
  {
    "firstName" : "Frank",
    "lastName" : "Normal"
  },
  {
    "firstName" : "Grant",
    "lastName" : "Right"
  },
  {
    "firstName" : "Geoff",
    "lastName" : "Power"
  },
  {
    "firstName" : "Marcelo",
    "lastName" : "Jump"
  }
]

[
    "yellow", "blue", "red", "black", "white", "green"
  ]

Estas matrices se utilizan para ilustrar las operaciones de matriz en la siguiente tabla y en Ejemplo: iteración de matrices.

Operador	Ejemplo	Salida
`size`	`${person.value?size?number}`	`4`: tamaño (cuatro miembros) de la matriz `person`
índice de matriz	`${person.value[1].firstName}`	`Grant`: indica el valor de la segunda propiedad `firstName` de la matriz `person`.
índice de matriz	`${person.value[1].firstName !'unknown'}`	Igual que el anterior, pero, en este caso, el bot genera una salida desconocida si la segunda propiedad `firstName` no tiene ningún valor.
`first`	`${person.value?first.firstName}`	`Frank`: primera entrada de la matriz de personas. Esta operación no utiliza el índice de matriz.
`last`	`${person.value?last.firstName}`	`Marcelo`: último valor `lastName` en la matriz de personas.
`sort_by`	`${person.value?sort_by('lastName') [0].firstName}`	`Marcelo` Este operador ordena la matriz `person` en orden ascendente según la propiedad `lastName`. A continuación, imprime el valor de la propiedad `firstName` correspondiente para la entrada final en la matriz de personas: Jump, Marcelo Normal, Frank Power, Geoff Right, Grant Nota: salvo en el caso de que guarde la matriz ordenada en una variable mediante `System.SetVariable`, los datos se mantienen ordenados en una única solicitud.
`sort_by`	`${person.value?sort_by('lastName')?reverse[0].firstName}`	`Grant`: los valores se ordenan en orden descendente: Right, Grant Power, Geoff Normal, Frank Jump, Marcelo
`seq_index_of`	`${colors.value?seq_index_of('red')}`	`2`: valor de índice para el rojo en la matriz de colores.
`seq_last_index_of`	`${colors.value?seq_last_index_of('red')}`	`2`: el último valor de índice para el rojo en
`join`	`${colors.value?join(',')}`	Devuelve la matriz `colors` como una cadena separada por comas: `yellow, blue, red, black, white, green`
`seq_contains`	`${colors.value?seq_contains('red')?string('Yes', 'No')`	Devuelve `Yes` porque la matriz contiene el rojo. Nota: `?seq_contains` devuelve un valor booleano. Este valor se sustituye por una cadena con la expresión `?string('…','…')`.
`sort`	`${colors.value?sort?join(',')}`	Devuelve la matriz de colores como una cadena separada por comas en orden ascendente: `black, blue, green, red, white, yellow`
`reverse`	`${colors.value?sort?reverse?join(',')}`	Devuelve la matriz `colors` como una cadena separada por comas en orden descendente: `yellow, blue, red, black, white, green`

Devolución de intenciones y puntuaciones

Puede utilizar operaciones de matriz para devolver los resultados del procesamiento de la intención y la entidad. Por ejemplo:

${skill.system.nlpresult.value.entityMatches[‘name of entity’]} devuelve una matriz de las entidades encontradas en una cadena de usuario que se transfiere al motor de intenciones almacenado en la variable nlpresult.
${skill.system.nlpresult.value.intentMatches.summary[n].intent} devuelve el nombre de la intención que tiene una clasificación de confianza de n, donde 0 representa la intención con la clasificación superior, 1 representa la segunda intención con la clasificación, etc.
${skill.system.nlpresult.value.intentMatches.summary[n].score} devuelve la puntuación de confianza de la intención especificada.

Para estas dos expresiones, n es el índice del elemento que desea buscar. Por ejemplo, la expresión para devolver el nombre de intención resuelta principal sería:

${skill.system.nlpresult.value.intentMatches.summary[0].intent}

Para la puntuación de la intención principal, la expresión sería:

${skill.system.nlpresult.value.intentMatches.summary[0].score}

Puede utilizar estas expresiones para las intenciones que se puntúen por encima del umbral de confianza, pero también puede utilizarlas para devolver intenciones cuya puntuación esté por debajo del umbral de confianza. Estas expresiones no dependen del valor de umbral de confianza configurado en la página Configuración de la aptitud, por lo que puede utilizarlas para devolver las intenciones del candidato y sus puntuaciones incluso cuando no se haya resuelto ninguna intención y se haya activado una acción unresolvedIntent. En este caso, puede, por ejemplo, utilizar estas expresiones para devolver las tres intenciones principales y sus puntuaciones de umbral de subconfianza.

Nota

Si necesita hacer referencia a la intención que un usuario ha seleccionado después de que se le pida que desambigue, puede utilizar ${system.intent.name}. (${skill.system.nlpresult.value.intentMatches.summary[0].intent} siempre devuelve la intención con la puntuación superior, que puede que no sea la intención que el usuario seleccione al desambiguar.

Ejemplo: iteración de matrices

Las matrices determinan el número de entidades en la entrada de usuario.

Descripción de arrayoutput.png a continuación

Descripción de la ilustración arrayoutput.png

El siguiente fragmento de la propiedad Metadatos de un componente de respuesta común muestra cómo determinar el tamaño de la matriz retenida en la variable person y, a continuación, iterar sobre sus elementos para que la aptitud genere algo parecido a lo siguiente:


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

Nota

La salida descrita en este código no se ordena (es decir, no se utiliza ninguna operación sort_by).

Operaciones de fecha de FreeMarker incorporadas

La siguiente expresión deriva la fecha actual mediante la referencia de variable especial FreeMarker, .now, y el operador date incorporado.

${.now?date}

En la siguiente tabla, se muestran algunas de las operaciones de fecha incorporadas que se pueden utilizar para definir propiedades y manipular valores de entidad.

Operaciones	Ejemplo	Salida
`date`	`${.now?date}`	Fecha actual
`time`	`${.now?time}`	Hora del día, por ejemplo, 5:46:09 PM
`datetime`	`${.now?datetime}`	Imprime la fecha y la hora actuales, por ejemplo, 17 de enero de 2018 5:36:13 PM.
`long` y `number_to_date`	`${(.now?long + 86400000)?number_to_date }`	Añade 24 horas a la fecha actual. Si la llamada se realiza el 17 de enero de 2018, FreeMarker genera la fecha 18 de enero de 2018.
`string` (con estilos de formato)	`${.now?string.full}`	Convierte la fecha actual en una cadena con el formato miércoles, 17 de enero de 2018 6:35:12 PM UTC.
	`${.now?string.long}`	Convierte la fecha en una cadena con la salida con este formato: 17 de enero de 2018 6:36:47 PM UTC.
	`${.now?string.short}`	Convierte la fecha en una cadena con la salida con este formato: 1/17/18 6:37 PM
	`${.now?string.medium}`	Convierte la fecha en una cadena con la salida con este formato: 17 de enero de 2018 6:38:35.
	`${.now?string.iso}`	Imprime la fecha según la norma ISO 8601, como 2018-01-17T18:54:01.129Z.
`string` (con los formatos de salida especificados)	`${.now?string['dd.MM.yyyy, HH:mm']}`	Imprime la fecha actual en un formato personalizado, por ejemplo, 17.01.2018, 18:58.
`string` (con los formatos de salida especificados)	`${.now?string['yyyy']}`	2018
`datetime` (con `string` y estilo de formato)	`${date_variable?datetime?string.short}`	Convierte la fecha en una cadena con el formato 1/17/18 6:37 PM. El operador `datetime` permite a FreeMarker saber si la variable incluye una fecha que contiene información de fecha y hora. De forma parecida, puede utilizar los operadores `date` o `time` para indicar si el valor de fecha contiene solo la fecha o solo la hora, pero el uso de `datetime?string` permite evitar errores.
Conversión del valor de entidad en una cadena utilizando `date` `long` `number_to_date` estilos de formato formatos de fecha personalizados	`${dateVar.value.date?long?number_to_date?date?string.short}`	Convierte la fecha de la extracción de la entidad en una cadena con el formato 11/17/18. El operador date indica a FreeMarker que la variable contiene una fecha, pero no una hora. El uso de este formato evita errores.
	`${dateVar.value.date?long?number_to_date?string.medium}`	Convierte la fecha derivada de la extracción de la entidad en una cadena con el formato 17 de enero de 2018. Nota: todos los demás formatos, como `full`, `short`, `long` e `iso`, funcionan de la misma forma con las fechas derivadas de la extracción de la entidad.
	`${dateVar.value.date?long?number_to_date?string['dd.MM.yyyy']}`	Imprime la fecha en formato personalizado. Por ejemplo: 17.01.2018, 18:58.
	`${dateVar.value.date?long?number_to_date?string['yyyy']}`	Imprime la fecha derivada de la entidad en un formato personalizado.

Ejemplo: extracción de fechas desde la entrada del usuario

Los siguientes ejemplos son de una aptitud que gestiona citas. Cuando un usuario le pregunta ¿puede organizar una reunión con el señor Higgs pasado mañana?, el bot utiliza una entidad compleja, DATE, para extraer mañana de la solicitud. Muestra la fecha solicitada mediante ${(theDate.value.date?long + 86400000)?number_to_date} para agregar 24 horas (o 86.400.000 milisegundos) a "mañana".

Texto con Expresión	Salida
`"Today is: ${.now}"`	Hoy es: 18/1/18 8:31 AM
`"Date found is: ${theDate.value.date}"`	La fecha encontrada es: 19 de enero de 2018
`"A day later is ${(theDate.value.date?long + 86400000)?number_to_date}"`	El día siguiente es el 20 de enero de 2018

Ejemplo: configuración de una fecha predeterminada (si no se establece ningún valor de fecha)

Si el mensaje del usuario no incluye información de fecha, la aptitud puede preguntar a los usuarios la fecha o proporcionar una fecha por defecto. Para proporcionar la fecha actual, puede utilizar la siguiente expresión:

${.now?datetime?string.long}

Variables del sistema a las que puede acceder FreeMarker

Oracle Digital Assistant tiene un juego de variables del sistema mediante el que se puede recuperar información útil en los flujos de diálogo mediante expresiones de FreeMarker.

En sus formas más sencillas, estas expresiones toman el siguiente formato:

${system.variableName}

Algunas variables pueden contener objetos con propiedades anidadas a las que se puede acceder utilizando la notación de puntos después del nombre de la variable en el formato siguiente.

${system.variableName.propertyName}

Además, los valores de propiedad anidada también pueden ser objetos con propiedades anidadas.

Estas son las variables del sistema que están disponibles mediante expresiones FreeMarker.

Variable	Descripción
`system.actualState`	Nombre del estado al que ha navegado el usuario al pulsar un botón "en secuencia incorrecta" más antiguo. Si la carga útil de devolución contiene una propiedad `system.state`, el motor de diálogo navega a este estado y define esta variable en el nombre de dicho estado. Consulte también Configuración del flujo de diálogo para acciones inesperadas.
`system.authorizedUsers`	Lista de todos los usuarios autorizados para un chat de grupo determinado.
`system.channelType`	Tipo de canal de la sesión de usuario actual. Valores permitidos: `facebook`, `androidsdk`, `iossdk`, `websdk`, `slack`, `twilio`, `msteams`, `cortana`, `webhook` y `test`. Si la sesión se está ejecutando en el comprobador, el valor corresponde al tipo de canal que se está simulando.
`system.entityToResolve`	El objeto que representa el elemento de bolsa compuesta actual que resolver en el componente de respuesta común cuando la propiedad de variable del componente hace referencia a un objeto entity.The de bolsa compuesta tiene las siguientes propiedades: `nextRangeStart`: número de índice de la lista de valores permitidos de la entidad a la que se navegará al pulsar el botón Mostrar más. `updatedEntities`: lista de elementos de bolsa compuesta actualizados en función del último mensaje de usuario. `needShowMoreButton`: propiedad booleana que se puede utilizar como `expression` para la propiedad `visible`, a fin de representar condicionalmente el botón Mostrar más para ir al siguiente juego de valores de entidad. `outOfOrderMatches`: lista de elementos de bolsa que se rellenaron con un valor basado en el último mensaje de usuario cuando se solicitó al usuario otro artículo de bolsa. `rangeStartVar`: nombre de la variable que contiene el inicio del rango actual de los valores de entidad. `validationErrors`: para el elemento de bolsa actual, lista de mensajes de error provocados por un valor no válido proporcionado en el último mensaje de usuario. `allMatches`: lista de elementos de bolsa que han obtenido valores nuevos o actualizados en función del último mensaje de usuario. `resolvingField`: nombre del elemento de bolsa actual que se solicita al usuario. `userInput`: último mensaje de usuario. `skippedItems`: lista de elementos de bolsa en los que se ha excedido el número máximo de peticiones de datos para un valor. `disambiguationValues`: lista de valores de entidad permitidos que tienen coincidencias en el último mensaje de usuario. `enumValues`: lista de valores de entidad permitidos para el elemento de bolsa actual. Consulte Variable system.entityToResolve para obtener ejemplos sobre cómo utilizar `system.entityToResolve`.
`system.errorAction`	Texto de mensaje de error generado por un error inesperado devuelto durante la ejecución del estado.
`system.errorState`	Nombre del estado que ha devuelto un error inesperado durante la ejecución.
`system.expectedState`	Cuando el usuario se desplaza al historial de mensajes y pulsa un botón"en secuencia incorrecta" más antiguo, esta variable se rellena con el nombre del estado que se esperaba ejecutar, pero que nunca se ejecutó porque el usuario decidió pulsar este botón "en secuencia incorrecta". Consulte también Configuración del flujo de diálogo para acciones inesperadas.
`system.intent.name`	Se utiliza para hacer referencia a la intención que ha seleccionado un usuario después de que se le pida que desambigue. ( `${iResult.value.intentMatches.summary[0].intent}` siempre devuelve la intención con la puntuación superior, que puede que no sea la intención que el usuario seleccione al desambiguar).
`system.invalidUserInput`	Valor booleano establecido en `true` cuando la entrada de usuario no coincide con el tipo de variable solicitado.
`system.message`	Último mensaje recibido por Oracle Digital Assistant. Esta variable incluye las propiedades siguientes: `channelConversation`: objeto de conversación del canal que tiene las siguientes propiedades: `botId` `channelType`: si la ejecución se realiza en el comprobador, devolverá `test`. Si desea obtener el nombre del canal que se está simulando en el comprobador, utilice `system.channelType` en su lugar. `channelName` `channelCategory`: devuelve el tipo de canal. Para canales de DA como agente, devuelve `botAsAgent`. `groupConversation`: devuelve `true` si la conversación es un chat de grupo. `userId`: devuelve el ID de usuario. Para los canales de DA como agente, se devolverá el ID de interacción. `sessionId`: devuelve el ID de sesión. Para los canales de DA como agente, se devolverá el ID de interacción. `sessionExpiryDuration` `messagePayload`: mensaje real enviado por el usuario. Las propiedades a las que puede acceder dependen del tipo de mensaje: Mensaje de texto: la propiedad `text` que devuelve el mensaje real introducido por el usuario Mensaje de devolución: propiedades del objeto de devolución, normalmente `action` y `variables`, cuando se utiliza el componente de respuesta común. Por ejemplo, si el usuario pulsa un botón que define la variable `pizzaSize`, este valor se puede recuperar utilizando la siguiente expresión: `${system.message.messagePayload.variables.pizzaSize}` Mensaje de ubicación: propiedad `location`, que contiene un objeto de ubicación con las siguientes propiedades: `title` `url` `latitude` `longitude` `stateCount`: número de estados ejecutados para procesar el último mensaje de usuario. `platformVersion`: versión de la plataforma de ejecución actual.
`system.requestedState`	Si un usuario accede a una conversación que se encuentra en un estado que requiere autorización y el usuario no está en la lista de usuarios almacenados en `system.authorizedUsers`, el motor de diálogo almacena el estado que tenía previsto ejecutar en esta variable.
`system.selectedCardIndex`	Esta variable mantiene el índice de la tarjeta seleccionada al utilizar la función para optimizar la representación de tarjetas para canales de solo texto, como Twilio. Esta optimización permite al usuario seleccionar una tarjeta en un proceso de dos pasos: en primer lugar, se presenta una lista de tarjetas; a continuación, el usuario puede introducir el número de tarjetas que quiera seleccionar. El número de índice correspondiente de esta tarjeta se almacena en esta variable.

Nota

Las variables del sistema de la tabla anterior son las únicas que puede utilizar en expresiones FreeMarker. Otras variables del sistema no son públicas y su uso está sujeto a cambios, lo que significa que sus habilidades no pueden confiar en ellas.

Por ejemplo, las variables system.routingFromSkill, system.routingToSkill, system.routingFromIntent y system.routingToIntent solo están disponibles para una configuración de asistente digital específica. Consulte Variables del sistema para asistentes digitales.

Documentación de Oracle Cloud Infrastructure

D Referencia de Apache FreeMarker