Macros de velocidad para acciones de datos

Nota: Este artículo se aplica a las integraciones de acciones de datos de Adobe, AWS Lambda, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, servicios web y Zendesk.

Las integraciones de acciones de datos le permiten crear acciones personalizadas. Estas acciones personalizadas incluyen configuraciones de solicitud y configuraciones de respuesta con plantillas que utilizan Velocity Template Language. Estas plantillas admiten una variedad de macros Velocity.

Advertencia: Escapa de cualquier uso de variables de entrada o salida dentro de requestTemplate, SuccessTemplate, o requestUrlTemplate. Si no escapa correctamente las variables con caracteres especiales, sus acciones de datos fallarán en la ejecución.
  • Usar esc.jsonString para escapar de las cadenas dentro de los cuerpos JSON. Ver esc.jsonString.
  • Usar esc.url () o urlTool.optionalQueryParam () para escapar correctamente de la ruta o los parámetros de consulta para un requestUrlTemplate o requestTemplate si usa x-www.form-urlencoded valores. Ver Biblioteca de escape de cadenas.

Las plantillas de velocidad son válidas para los siguientes campos:

  • requestUrlTemplate
  • encabezados
  • requestTemplate
  • SuccessTemplate

Para más información, ver Crea una acción personalizada, Solicitar configuración, y Configuración de respuesta.

Nota: Notación formal formal versus silenciosa

  • Notación formal: $ {variable}

    Si la variable es nula, la notación formal genera el nombre de la variable.

  • Notación formal silenciosa: $!{variable}

    Si la variable es nula, la notación silenciosa genera una cadena vacía.

Biblioteca de matemáticas

Prefijo: Matemáticas

Utilice estas macros matemáticas para realizar operaciones matemáticas básicas. Para más información, ver Clase MathTool en la documentación de Velocity.

Biblioteca de escape de cadenas

Prefijo: Esc

Utilice EscapeTool para escapar de las cadenas en las plantillas de Velocity. EscapeTool proporciona métodos para escapar de las salidas de Java, JavaScript, HTML, XML y SQL. EscapeTool también proporciona métodos para escapar de los caracteres de Velocity Template Language. Para más información, ver Clase EscapeTool en la documentación de Velocity.

Dos métodos en particular son útiles.

  • $ esc.url (): Utilice este método para escapar de los valores de los argumentos en urlTemplate. De lo contrario, las URL con espacios u otros caracteres que no sean URL no son válidas. 
  • $ esc.d (): Utilice este método para incluir un signo de dólar ($) en una URL.

La siguiente tabla muestra ejemplos de entradas y salidas de varias macros. 

Advertencia: No utilice codificación JavaScript. $ esc.javascript ($ entrada) puede crear JSON no válido que interrumpe una acción.

Macros Entradas Salidas
$ esc.java ($ entrada) El no't decir, "¡Parada!" El no't decir, \"¡Parada!\"
$ esc.html ($ entrada) "pan de molde" Y "manteca" "pan con mantequilla"
$ esc.xml ($ entrada) "pan de molde" Y "manteca" "pan con mantequilla"
$ esc.sql ($ entrada) McHale's Marina McHale''s Marina
$ esc.url ($ entrada) hola aquí y allá hola + aquí +% 26 + allí
$ esc.dollar $
$ esc.hash #
$ esc.backslash \
$ esc.quote "
$ esc.singleQuote '
$ esc.exclamación !

encoding.base64

Base64 codifica las cadenas que proporcionas. 

Ejemplo de plantilla

El campo codificado es $ encoding.base64 (\"$ {primero} y $ {segundo} \")

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

primero == gato

segundo == perro

El campo codificado es Y2F0IGFuZCBkb2c =

esc.jsonString

Cuando crea cuerpos JSON para solicitudes POST, PUT y PATH, debe escapar de las cadenas. Esta macro escapa de las comillas y otros caracteres según las reglas de codificación JSON.

Nota: esc.jsonString trata los caracteres Unicode de forma diferente a EscapeTool.javascript () lo hace. 

Ejemplo de plantilla

$ esc.jsonString ($ {input.json})

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
Esta es una cadena con {una pestaña incrustada}, ", y {una nueva línea incrustada}, y una letra cirílica Ԃ "Esta es una cadena con \\ t, \\\", y \\ n, y una letra cirílica Ԃ"
Nota: Debido a que los caracteres Unicode en cadenas son estándar en las especificaciones de codificación JSON, los caracteres Unicode no se escapan al formato \ u0000.

successTemplateUtils.firstFromArray

Esta macro extrae el primer elemento de la cadena de matriz JSON proporcionada y tiene dos parámetros. Se requiere el primer parámetro, que es la matriz de entrada para el valor extraído. El segundo parámetro, que especifica la respuesta que se devuelve cuando la matriz está vacía, es opcional y, por defecto, no devuelve nada. Si la matriz no está vacía, se ignora el segundo parámetro. 

Si la entrada para firstFromArray Si los datos se extraen a través de translationMap JSONPath, no es necesario ningún escape de cadena. En los siguientes ejemplos de plantillas, identificadores podría provenir de una entrada de translationMap, como "identificadores": "$ .idArray".

Ejemplos de plantillas y resultados

Ejemplos de plantillas Entradas Plantillas resueltas
$ {successTemplateUtils.firstFromArray ("$ {ids}")} ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]"
ids == "" Esta entrada da como resultado un error.
$ {successTemplateUtils.firstFromArray (\"$ {ids} \", \"{}\")} ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]" {}
ids == "" Esta entrada da como resultado un error.
$ {successTemplateUtils.firstFromArray (\"$ {ids} \", \"$ esc.quote $ esc.quote \")} * ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]" ""
ids == "" Esta entrada da como resultado un error.

* Este ejemplo de plantilla usa EscapeTool para escapar caracteres. Para más información, ver Biblioteca de escape de cadenas.

successTemplateUtils.moveKeysIntoArrayOfObjects

Esta macro convierte los datos a un formato compatible con Architect y tiene dos parámetros obligatorios. El primer parámetro es la entrada de la respuesta original. El segundo parámetro es el nombre de la clave que la macro agrega a un objeto y el valor es el campo dinámico de la respuesta original.

Nota: Si la macro no puede convertir datos, la acción de datos devuelve un error o una matriz vacía.

Para devolver los datos convertidos, configure el traducciónMapa y SuccessTemplate en su acción de datos basada en el siguiente ejemplo.

Ejemplo de acción de datos

"config": {
 "solicitud": {
 "requestUrlTemplate": "https://some.website.com/with/normalized/data",
 "tipo de solicitud": "OBTENER",
 "encabezados": {
 },
 "requestTemplateDefault": cierto
  },
 "respuesta": {
 "translationMap": {
 "entitySegmentMembershipUps": "$. *. ruta.a.la.clave.dinámica"
 },
 "translationMapDefaults": {},
 "SuccessTemplate": "{\" segmentos \ ": $ {successTemplateUtils.moveKeysIntoArrayOfObjects ($ {entitySegmentMembershipUps})}, \ "segmentoId \")}} "
 }
 }

En la respuesta original, no puede acceder al GUID porque es una clave dinámica y no se puede aplanar correctamente.

Respuesta original devuelta

"segmentoMembresía": {
 "UPS": {
 "a959c128-d6d9-4a42-a307-c5d278cfcbe2": {
 "lastQualificationTime": "2020-11-16T03: 23: 31Z",
 "estado": "comprendió"
 }
 }
 }

La macro mueve el ID a un objeto y lo devuelve como segmentoId

Macro devolvió la respuesta

"segmentos": [
 {
 "lastQualificationTime": "2020-11-16T03: 23: 31Z",
 "estado": "comprendió",
 "segmentoId": "a959c128-d6d9-4a42-a307-c5d278cfcbe2"
 }
 ]

urlTool.optionalQueryParam

Esta macro formatea un par clave-valor como parámetro de consulta, a menos que el valor esté vacío. De lo contrario, la macro devuelve una cadena vacía. No incluya el ampersand (&) en su plantilla; la macro agrega automáticamente el ampersand. Consulte los resultados del ejemplo de plantilla.  Utilice la macro solo después de al menos un parámetro de consulta obligatorio. En el siguiente ejemplo de plantilla, el parámetro de consulta requerido es $ {input.AMOUNT}.

Nota: Utilice notación formal silenciosa: $!{variable}.
Ejemplo de plantilla

cantidad = $ {input.AMOUNT} $ urlTool.optionalQueryParam (\"descripción\"PS{input.DESCRIPTION})

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

input.AMOUNT == 30

input.DESCRIPTION == patatas

cantidad = 30 & descripción = patatas

input.AMOUNT == 30

input.DESCRIPTION == ""

cantidad = 30

Macros del método de cadena de Java

Utilice métodos de cadena de Java en las plantillas de Velocity para manipular variables de cadena, como cambiar el caso de un valor o extraer un valor de una cadena. Para más información, ver Cadena de clase en la documentación de Java 11.

En el siguiente ejemplo, el toUpperCase () El método convierte el valor de cadena de la variable $ a en mayúsculas. los separar() El método divide la variable $ b en una matriz de cadenas. La variable $ d concatena valores de la variable $ a, la variable $ b y el primer elemento de la matriz para la variable $ c.

Ejemplo de plantilla

#set ($ a = $ {input1.string1})
 #set ($ a = $ a.toUpperCase ())
 #set ($ b = $ {input1.string2})
 #set ($ c = $ b.split ("\ +"))
 #set ($ d = "Estamos usando ""$ {a}"" ""$ {b}"" ""$ c [1]"" para hacer esto ". )
 $ d

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

input.string1 = value1

input.string2 = value1 + value2

Estamos usando "VALUE1" "valor1 + valor2" "valor2" para hacer esto.

Macros de Microsoft Dynamics

msdynamics.fieldSearchFilter

Esta macro crea un filtro de búsqueda dado un valor y una lista de campos que desea buscar. La macro compara el valor con cada uno de los campos de la lista.

Ejemplo de plantilla

$ msdynamics.fieldSearchFilter (\"$ input.EMAIL_ADDRESS \", [\"emailaddress1 \", \"emailadress2 \"]

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.EMAIL_ADDRESS = TestMail@example.com emailaddress1 eq 'TestMail@example.com' o emailaddress2 eq 'TestMail@example.com'

msdynamics.phoneNumberFilter

Esta macro crea un filtro de búsqueda dado un número de teléfono y una lista de campos que desea buscar. La macro elimina los caracteres no admitidos y cualquier valor que no sea un dígito, como + y paréntesis, del número de teléfono y agrega "o" entre cada campo. Este filtro de búsqueda es útil para comparar un número de teléfono con varios números de teléfono en un registro de cuenta.

Ejemplo de plantilla

$ msdynamics.phoneNumberFilter (\"$ input.PHONE_NUMBER \", [\"teléfono1 \", \"teléfono2 \"])

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.PHONE_NUMBER = +1 (555) 555-0123 teléfono1 eq '+1 (555) 555-0123' o teléfono2 eq '+1 (555) 555-0123' o teléfono1 eq '15555550123' o teléfono2 eq '15555550123'

Macros de Salesforce

salesforce.escReservado

Esta macro escapa los caracteres reservados de las consultas de Salesforce SOQL / SOSL realizadas en una URL. Salesforce se reserva los siguientes caracteres: ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. Esta macro asegura que los personajes se escapen correctamente. Para más información, ver ENCONTRAR {SearchQuery} en la documentación de Salesforce.

Ejemplo de plantilla

ENCONTRAR {$ salesforce.escReserved ($ {input.PHONE_NUMBER})} EN CAMPOS DE TELÉFONO

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.PHONE_NUMBER == (555) 555-5555 ENCONTRAR {\ (555 \) 555 \ -5555} EN CAMPOS DE TELÉFONO

Para más información, ver Acerca de las acciones personalizadas para integraciones.

Para obtener más información sobre las integraciones, consulte Acerca de las integraciones de acciones de datos.