Referencia de Funciones CEL

Referencia completa de todas las funciones integradas disponibles en las expresiones CEL de AutoTalk. Las funciones estan organizadas por categoria.

---

Core

get(obj, path, default?)

Accede de forma segura a una propiedad anidada a traves de una ruta con puntos.

get(client, "address.city")                  // "São Paulo"
get(client, "address.zip", "00000-000")      // retorna el predeterminado si falta
get(null, "name")                            // null
get(step(0), "data.results.0.title")         // ruta profunda con indice de array

Param	Tipo	Descripcion
obj	any	Objeto a acceder (seguro para null)
path	string	Ruta con puntos (ej: "a.b.c")
default	any	Valor retornado si la ruta no existe (predeterminado: null)

has(obj, path?)

Verifica si un valor o ruta anidada existe y no es null/undefined.

has(client, "email")        // true si client.email esta definido
has(myVar)                  // true si myVar no es null/undefined
has(obj, "a.b.c")           // true si la ruta completa resuelve a no-null

coalesce(...vals)

Retorna el primer valor no-null y no-undefined. Variadica (acepta 2+ argumentos).

coalesce(client.nickname, client.name, "Guest")   // el primer no-null gana
coalesce(0, 42)                                    // 0 (no es null!)
coalesce(false, true)                              // false (no es null!)
coalesce("", "fallback")                           // "" (no es null!)

Semantica de verificacion de null

coalesce() solo omite null y undefined. Valores como 0, false y "" son validos y se retornan.

now()

Retorna la fecha/hora actual.

now()                                    // fecha/hora actual
format_datetime(now(), "YYYY-MM-DD")     // "2024-01-15"

present(val)

Verifica si un valor esta significativamente presente. Retorna false para null, undefined, strings vacias/solo espacios y arrays vacios. Numeros y booleanos siempre se consideran presentes.

present(client.email)         // true si es string no vacia
present("")                   // false
present("   ")                // false (solo espacios)
present(0)                    // true
present([])                   // false
present([1, 2])               // true

Reemplaza patrones verbosos

present(x) reemplaza el patron comun size(trim(coalesce(x, ""))) > 0.

blank(val)

Inverso de present(). Retorna true para null, undefined, strings vacias/solo espacios y arrays vacios.

blank(client.email)           // true si es null o vacio
blank("hello")                // false
blank(0)                      // false

---

Utilidades

pluck(arr, path)

Extrae una propiedad de cada objeto en un array.

pluck(clients, "name")                     // ["Alice", "Bob", "Carol"]
pluck(tools, "tool.function.name")         // ruta profunda soportada

slice(arr, start, end?)

Corta un array de forma segura. Retorna [] para entradas que no son arrays. Soporta indices negativos.

slice(results, 0, 5)         // primeros 5 elementos
slice(results, -3)            // ultimos 3 elementos
slice(results, 1, -1)         // todos excepto el primero y el ultimo
slice(null, 0, 2)             // [] (seguro para no-arrays)

defaults(obj, fallbacks)

Fusiona valores de respaldo en un objeto para claves que son null/undefined. Fusion superficial.

defaults(response, {"status": "unknown", "retryable": false})
// Completa status y retryable solo si son null/undefined en response

Semantica de verificacion de null

Como coalesce(), solo los valores null/undefined son reemplazados. 0, false y "" se mantienen.

url_params(base, params)

Construye una URL con parametros de query. Omite valores null y vacios. Codifica automaticamente.

url_params("https://api.example.com/search", {"q": query, "page": 1, "lang": null})
// "https://api.example.com/search?q=hello&page=1" (lang omitido)

truncate(str, maxLen, suffix?)

Trunca una string a una longitud maxima con un sufijo opcional.

truncate("Hello World", 5)              // "Hello"
truncate("Hello World", 8, "...")        // "Hello..."
truncate(null, 10)                       // "" (seguro para null)
truncate("Hi", 100)                      // "Hi" (sin necesidad de truncar)

Param	Tipo	Descripcion
str	any	Valor a truncar (convertido a string, null retorna "")
maxLen	number	Longitud maxima del resultado (incluyendo el sufijo)
suffix	string	Se agrega al truncar (predeterminado: "")

tip

El sufijo se incluye dentro de maxLen: truncate("Hello World", 8, "...") retorna "Hello..." (8 caracteres).

tpl(template, vars)

Interpolacion simple de string. Reemplaza marcadores {key} con valores de un objeto.

tpl("Hello {name}!", {"name": "Alice"})                    // "Hello Alice!"
tpl("*{title}*\n{domain}\n{url}", article)                 // texto formateado del articulo
tpl("{address.city}, {address.country}", client)            // soporte de ruta con puntos
tpl("Hi {name}", {"name": null})                           // "Hi " (null → vacio)

Param	Tipo	Descripcion
template	string	String de plantilla con marcadores {key}
vars	object	Objeto con valores para interpolar

join_present(separator, ...values)

Une valores con un separador, omitiendo valores en blanco. Usa las mismas reglas que present(): null, strings vacias/solo espacios y arrays vacios se omiten. 0 y false se mantienen.

join_present(", ", "Alice", "Bob", "Carol")       // "Alice, Bob, Carol"
join_present(" - ", title, null, author)           // "Title - Author" (null omitido)
join_present(" ", "Hello", "", "World")            // "Hello World" (vacio omitido)
join_present(" | ", 0, false, "text")              // "0 | false | text" (0/false mantenidos)

Reemplaza concatenacion condicional

join_present(" - ", prefix, text) reemplaza el patron (present(prefix) ? prefix + " - " : "") + text.

encode_uri(str)

Codifica una string para URL.

encode_uri("hello world")    // "hello%20world"

format_currency(n, currency, locale?)

Formatea un numero como moneda.

format_currency(1234.5, "USD", "en-US")    // "$1,234.50"
format_currency(99.9, "BRL", "pt-BR")      // "R$ 99,90"

---

String

CEL incluye funciones de string integradas. La mayoria funciona tanto en estilo receptor como en estilo funcion:

"hello".contains("ell")      // true (estilo receptor)
contains("hello", "ell")     // true (estilo funcion)

Funcion	Descripcion	Ejemplo
contains(str, sub)	Verifica si la string contiene la substring	"hello".contains("ell")
startsWith(str, prefix)	Verifica prefijo	"hello".startsWith("he")
endsWith(str, suffix)	Verifica sufijo	"hello".endsWith("lo")
split(str, sep)	Divide en array	split("a,b,c", ",") → ["a","b","c"]
lowerAscii(str)	Minusculas	lowerAscii("HELLO") → "hello"
upperAscii(str)	Mayusculas	upperAscii("hello") → "HELLO"
trim(str)	Elimina espacios	trim(" hi ") → "hi"
substring(str, start, end?)	Extrae substring	substring("hello", 1, 4) → "ell"
replace(str, old, new)	Reemplaza ocurrencias	replace("aab", "a", "x") → "xxb"
indexOf(str, sub)	Primer indice de la substring	indexOf("hello", "l") → 2
lastIndexOf(str, sub)	Ultimo indice de la substring	lastIndexOf("hello", "l") → 3
charAt(str, index)	Caracter en el indice	charAt("hello", 0) → "h"
join(list, sep?)	Une array en string	join(["a","b"], ",") → "a,b"

---

Math

Funcion	Descripcion	Ejemplo
math_add(a, b)	Suma	math_add(5, 3) → 8
math_subtract(a, b)	Resta	math_subtract(10, 3) → 7
math_multiply(a, b)	Multiplicacion	math_multiply(4, 3) → 12
math_divide(a, b)	Division	math_divide(10, 3) → 3.333...
math_round(n, decimals?)	Redondeo	math_round(3.456, 2) → 3.46
math_floor(n)	Piso	math_floor(3.7) → 3
math_ceil(n)	Techo	math_ceil(3.1) → 4
math_abs(n)	Valor absoluto	math_abs(-5) → 5
math_pow(base, exp)	Potencia	math_pow(2, 3) → 8
math_sqrt(n)	Raiz cuadrada	math_sqrt(16) → 4
math_max(arr)	Maximo	math_max([1,5,3]) → 5
math_min(arr)	Minimo	math_min([1,5,3]) → 1
math_mean(arr)	Promedio	math_mean([1,2,3]) → 2
math_median(arr)	Mediana	math_median([1,2,10]) → 2
math_clamp(val, min, max)	Restringe al rango	math_clamp(15, 0, 10) → 10

math_clamp(val, min, max)

Restringe un numero dentro de un rango.

math_clamp(page, 1, 100)     // asegura que page esta entre 1 y 100
math_clamp(-5, 0, 10)        // 0 (por debajo del minimo)
math_clamp(15, 0, 10)        // 10 (por encima del maximo)

---

DateTime

Funcion	Descripcion
now()	Fecha/hora actual
format_datetime(d, fmt, tz?)	Formatea una fecha/hora. Formatos: "DD/MM/YYYY", "YYYY-MM-DD HH:mm:ss", "HH:mm"
add_datetime(d, n, unit)	Agrega tiempo. Unidades: "years", "months", "days", "hours", "minutes", "seconds"
diff_datetime(d1, d2, unit)	Diferencia entre dos fechas/horas
zoned_datetime(d, tz)	Convierte a zona horaria
is_before(d1, d2)	d1 antes de d2?
is_after(d1, d2)	d1 despues de d2?
is_between(d, start, end)	d entre start y end?

---

JSON

Funcion	Descripcion
json_parse(str)	Convierte string JSON a objeto
json_stringify(obj)	Serializa objeto a string JSON

---

BSON / ObjectId

Funcion	Descripcion
object_id()	Genera una nueva string ObjectId
object_id_is_valid(id)	Verifica si la string es un ObjectId valido
object_id_to_string(id)	Convierte ObjectId a string

---

Especificas de Workflow

Estas funciones solo estan disponibles en expresiones de workflow y agentes (no en CEL de formularios).

step(N)

Accede a la salida del paso N del workflow (indexado desde 0).

step(0)                      // objeto completo de salida del paso
step(0).data                 // payload de datos del paso
step(0).status               // codigo de estado HTTP (para pasos HTTP)

step_ok(N)

Verifica si el paso N se completo exitosamente. Retorna true cuando executionContext.status es "completed" Y el estado HTTP es 200 (o null para pasos no-HTTP).

// Antes: verboso
get(step(0), "executionContext.status") == "completed" && (get(step(0), "status") == null || get(step(0), "status") == 200)

// Despues: una llamada a funcion
step_ok(0)

step_data(N, path?, default?)

Obtiene datos del paso N en una ruta con puntos opcional. Retorna el predeterminado (o null) si no existe.

// Antes
get(step(0), "data.title", null)

// Despues
step_data(0, "title")
step_data(0, "results.0.name", "Unknown")
step_data(1, "choices.0.message.content")

step_error(N)

Obtiene informacion de error de un paso fallido. Retorna {code, user_message, retryable} o null.

// Antes
coalesce(get(step(0), "executionContext.safeError.code"), "UNKNOWN")

// Despues
step_error(0)                          // {code: "TIMEOUT", user_message: "...", retryable: true}
get(step_error(0), "code", "UNKNOWN")  // "TIMEOUT"

step_has_content(N, path)

Verifica si el paso N se completo exitosamente Y tiene datos presentes (no-null, no-vacio) en la ruta dada. Combina step_ok(N) && present(step_data(N, path)) en una sola llamada.

// Antes: dos verificaciones
step_ok(0) && present(step_data(0, "articles"))

// Despues: una llamada a funcion
step_has_content(0, "articles")

getContext()

Obtiene el objeto de contexto de ejecucion del workflow.

getTool(name)

Obtiene el resultado de una herramienta desde el contexto.

getRoot()

Obtiene el contexto raiz del workflow.