Variables

Las variables guardan valores de configuración e información sensible (como contraseñas o claves de API) para que no tengas que escribirlos en tus reglas y en tu código personalizado. Defines el valor una vez y lo referencias por su nombre.

Variables del proyecto y variables globales

Hay dos ámbitos de variables:

Cualquier usuario que pueda abrir la página puede ver la lista. Los usuarios sin permiso para gestionar variables no ven el botón Crear ni la columna Acciones.

Cuando un job o una prueba se ejecuta en un proyecto, Gigantics combina los dos ámbitos: primero las variables globales y después las del proyecto. Una variable del proyecto sustituye a la variable global con el mismo nombre.

Variables globales       Variables del proyecto   Valores usados en el proyecto
------------------       ----------------------   -----------------------------
api_url = https://a      api_url = https://b  ->  api_url = https://b
api_key = ••••••                              ->  api_key = (secreto global)
                         region  = eu         ->  region  = eu

Los nombres deben ser únicos dentro de su ámbito: dos variables del mismo proyecto, o dos variables globales, no pueden tener el mismo nombre. El mismo nombre puede existir como variable global y como variable del proyecto (así es como se sustituye un valor global).

Tipos de variables

Hay dos tipos de variables:

• Plain: variables de texto normales, que se guardan tal cual.
• Secret: para datos sensibles como contraseñas o claves de API. El valor se cifra antes de guardarlo en la base de datos y se muestra como ••••••• en la interfaz.

Creación y gestión de variables

Interfaz de usuario

La página Variables muestra una tabla con estas columnas:

Usa Buscar para filtrar la tabla por nombre, tipo o valor.

Añadir una nueva variable

1. Pulsa Crear en la esquina superior derecha.
2. Se abre un panel lateral con el formulario Nueva variable:
   • Nombre: el identificador de la variable (obligatorio).
   • Tipo: Plain o Secret.
   • Valor: un área de texto para las variables Plain, o un campo de contraseña para las variables Secret (obligatorio).
3. Pulsa Guardar.

Editar una variable

1. Abre el menú de acciones de la variable.
2. Selecciona Editar. El título del panel es Editar variable - <nombre>.
3. Cambia el nombre, el tipo o el valor.
4. Pulsa Guardar.

En las variables Secret, el campo del valor muestra •••••••. Si no lo cambias, se conserva el secreto guardado.

Eliminar una variable

1. Abre el menú de acciones de la variable.
2. Selecciona Eliminar.
3. Confirma con Sí, borrar en el diálogo "¿Está seguro de que quiere eliminar esta variable?".

Uso de variables

Insertar una variable desde el editor

El editor de funciones personalizadas, el editor de código personalizado de las operaciones de anonimización y los editores YAML (por ejemplo los Parámetros personalizados de un origen de datos) tienen un botón de variables (Mostrar variables). Abre una lista con dos grupos:

• Variables del proyecto: se muestra cuando estás dentro de un proyecto y el proyecto tiene variables.
• Variables globales.

Cada entrada muestra la referencia $(nombre) y su valor (•••••• en los secretos). Pulsa una entrada para insertar esa referencia en la posición del cursor. Nunca se inserta el valor, así que los secretos no se copian en el texto y un cambio posterior de la variable se aplica en todas partes.

Cómo referenciar variables

En las reglas y en el código personalizado, referencia una variable con:

$(nombre_variable)

Por ejemplo, para una variable llamada api_key:

$(api_key)

Dentro del código personalizado, todas las variables están también en el objeto $vars, por ejemplo $vars.api_key.

Variables en los orígenes de datos

Los campos de conexión de un origen de datos (host, puerto, base de datos, usuario, contraseña, esquema, los ajustes del túnel, los Parámetros personalizados y los ajustes de su gestor de contraseñas) pueden referenciar variables con $(nombre) o con la forma corta $nombre:

Host:          $(db_host)
Base de datos: ventas_$(entorno)

Gigantics las resuelve al conectar, con las variables del proyecto del origen de datos y las variables globales. Como en el resto de sitios, una variable del proyecto sustituye a una variable global con el mismo nombre. Un campo que es solo una referencia toma el valor de la variable tal cual; una referencia dentro de un texto más largo se sustituye por el valor como texto. Una referencia a una variable que no existe se deja como está escrita.

La forma corta $nombre solo admite letras, números y _ en el nombre, así que termina en el primer carácter distinto: en $db_host.example.com el nombre es db_host. Usa $(nombre) cuando la referencia va seguida de más texto.

Cómo se leen los valores

Los valores Secret se descifran al usarse. Después, Gigantics lee el valor como una expresión JavaScript si puede y, si no, como texto:

Si necesitas que un valor que parece un número, una fecha o una lista se quede como texto, ponlo entre comillas: "123", "2026-10-21".

Beneficios de usar variables

• Seguridad: la información sensible, como contraseñas y claves de API, se cifra y se oculta
• Flexibilidad: cambia valores de configuración sin modificar tu código
• Reutilización: usa la misma variable en varias funciones y reglas
• Valores por proyecto: sustituye un valor global en un proyecto sin afectar a los demás

Buenas prácticas

1. Usa variables Secret para datos sensibles: usa siempre el tipo "Secret" para contraseñas, claves de API y otra información sensible
2. Nombres descriptivos: usa nombres claros que expliquen para qué sirve la variable
3. Valores globales, sustituciones por proyecto: guarda los valores compartidos como variables globales y crea una variable del proyecto con el mismo nombre solo donde un proyecto necesite otro valor
4. Limpieza periódica: borra las variables que no uses para mantener el proyecto ordenado
5. Control de acceso: concede el permiso Edit project settings solo a los usuarios que necesiten crear o modificar variables del proyecto

Ejemplos de uso

• Guardar cadenas de conexión o endpoints que usan las funciones personalizadas
• Gestionar claves de API de servicios externos
• Mantener valores de configuración como umbrales o límites
• Usar un valor distinto por proyecto para la misma función