Uso en automatizaciones

Una vez creada la credencial en el ambiente, la usas en el playbook por su nombre, mediante la función de expresión credential(...). Nunca escribes el valor real.

La función credential()

En cualquier campo que acepte una expresión, escribe:

credential("nombre-de-la-credencial")

Según el formato de la credencial, la usas de dos maneras:

Formato	Cómo se lee	Devuelve
Valor único	credential("api-token")["value"]	El secreto como texto
Varios campos	credential("db")["password"]	El valor de ese campo

// Credencial de valor único
credential("openai")["value"]

// Credencial con varios campos
credential("db")["host"]
credential("db")["user"]
credential("db")["password"]
credential("smtp")["password"]

Parámetros de tipo credencial

Algunas actividades (por ejemplo, conexión a base de datos o envío de correo) tienen un parámetro de tipo credencial. En esos campos pasa directamente credential("nombre") y la actividad extrae los datos que necesita. En campos de texto normales (un encabezado de API, por ejemplo), usa ["campo"] (o ["value"] en una credencial de valor único) para obtener el valor concreto. .ToPlainText() no está permitido en expresiones: el motor lo rechaza para que el secreto no termine en un texto cualquiera.

Cómo se resuelve, paso a paso

1. En el playbook escribes credential("erp").
2. Al ejecutar, el agente detecta esa referencia y le pide a Zoan Cloud el valor de la credencial erp del ambiente donde se ejecuta, según la carpeta del proceso (ver abajo).
3. Zoan Cloud devuelve el valor cifrado; el agente lo descifra en memoria, solo para esa ejecución.
4. La actividad usa el valor. Nunca se escribe en el archivo del proyecto ni en los logs (al imprimirse, una credencial aparece como [credential]).

sequenceDiagram
  participant P as Playbook
  participant A as Agent
  participant N as Zoan Cloud
  P->>A: = credential("erp")
  A->>N: pide "erp" del ambiente
  N-->>A: valor cifrado
  A->>A: descifra en memoria → usa → descarta

Qué credencial usa cada robot

Si usas carpetas, cada robot usa las credenciales de su área sin cambiar el playbook. Para un proceso de la carpeta Compras, credential("sap-prod") se busca en este orden:

1. En la carpeta del proceso (Compras).
2. En las carpetas vinculadas a ella (ver Vincular desde otra carpeta) y en la raíz del ambiente.
3. Si el ambiente no tiene ninguna con ese nombre, en las credenciales globales de la organización.

• La carpeta se toma del proceso en cada ejecución: si mueves el proceso a otra carpeta, la siguiente ejecución usa las credenciales de la nueva.
• Un proceso de una subcarpeta usa lo de su carpeta, lo vinculado a ella y lo de la raíz; para usar una credencial de la carpeta padre, vincúlala a la subcarpeta.
• Si el ambiente tiene esa credencial en una carpeta que el robot no alcanza, la ejecución falla con un error claro en lugar de usar la global del mismo nombre.

La misma regla aplica a las integraciones que usan los robots, los asistentes (según la carpeta del asistente) y los proyectos de extracción (según la carpeta del proyecto). Los pasos de los flujos usan las credenciales e integraciones de la raíz del ambiente y las globales.

Requisitos

• El agente debe estar conectado a Zoan Cloud. Si ejecutas un playbook que usa credential(...) sin sesión activa con Zoan Cloud, falla con un error claro pidiéndote conectarte. Por eso, los playbooks con credenciales se prueban con el Agent conectado.
• La credencial debe existir en el ambiente donde se ejecuta y estar al alcance de la carpeta del proceso. Si no, la ejecución falla indicando qué credencial no se pudo resolver.

Errores comunes

Error	Causa	Solución
no hay proveedor de credenciales configurado	Ejecutaste sin conexión a Zoan Cloud	Conecta el Agent a Zoan Cloud antes de ejecutar
La credencial 'x' no pudo resolverse	No existe en ese ambiente, o el nombre no coincide	Créala en el ambiente o corrige el nombre
La credencial «x» no existe o no está disponible desde la carpeta «y»	La credencial está en otra carpeta, se desvinculó o se movió	Créala en esa carpeta, vincúlala a ella o déjala en la raíz del ambiente
El parámetro espera credencial pero recibió texto	Pasaste un literal en vez de la expresión	Escribe credential("nombre") sin comillas alrededor: es una expresión, no un texto

Buenas prácticas

• Nombres consistentes entre ambientes (erp, no erp-prod): el mismo playbook se ejecuta en producción y pruebas sin cambios. Ver Ambientes.
• Rota sin tocar el playbook: cambia el valor en el portal y la próxima ejecución usa el nuevo secreto.
• No copies el valor a una variable y la imprimas: extrae el secreto lo más tarde posible y solo donde se necesita.

Siguientes pasos

• Gestión de credenciales — crear y administrar credenciales.
• Expresiones — la sintaxis de credential() y demás funciones.