Instalar el complemento

Instalar ConnXL significa dos cosas: ejecutar el agent en un host que tus usuarios de Excel puedan alcanzar, y llevar el manifiesto generado a Excel. El agent sirve el complemento; el manifiesto solo le dice a Excel dónde vive el agent.

¿Vas a ejecutar el agent en producción?

Esta página cubre lo mínimo para levantar el agent y llevar el manifiesto a Excel. Para archivos de servicio, contenedores, actualizaciones, reglas de firewall y retirada, consulta Desplegar y ejecutar el agent.

Ejecuta el agent

El agent es un único binario, connxl-agent, que ejecutas en tu propia VM, contenedor o hardware físico — en tu propia nube o on-prem, dentro de tu red. Lee su configuración en vivo (funciones, conexiones, secretos por referencia) solo del backend — no hay archivo de configuración YAML. Un pequeño conjunto de archivos sí vive en disco junto a él: el par TLS cert.pem/key.pem y el directorio static/ de la descarga (el shell del panel de tareas y los logos neutros que sirve el agent).

Descarga el agent configurado desde la página del Agente del entorno, en el panel, pestaña Despliegue (es toda la página la primera vez que este entorno se despliega). Haz clic en Descargar agent configurado, elige la plataforma de tu host (Windows x64, Linux x64 o Linux arm64) y obtienes un binario con la identidad de este entorno ya incrustada — la URL del backend, el complemento y el entorno, y un token de inscripción de un solo uso nuevo, todo grabado en la descarga. No hay nada que configurar: colócalo en tu host con el directorio static/ al lado, añade el certificado TLS de más abajo y ejecútalo. En el primer arranque lee su propia identidad incrustada, se inscribe para obtener su certificado de cliente mTLS y empieza a servir — sin ninguna variable de entorno.

Una descarga configurada es única — y revocable

Cada Descargar agent configurado graba su propio token de inscripción nuevo, así que cada descarga es única byte a byte (el SHA256SUMS de una versión cubre los binarios simples, nunca uno grabado). Si un binario configurado se filtra o retiras un host, haz clic en Regenerar en el mismo panel: revoca todos los tokens de inscripción de este entorno de una vez — cada binario configurado descargado previamente y cada token copiado a mano — de modo que ninguno pueda volver a inscribirse. Los agents que ya se inscribieron no se ven afectados: se autentican con su certificado mTLS, y solo una inscripción nueva necesita un token vivo. Vuelve a descargar para repartir un reemplazo.

Sirve el complemento por HTTPS

Los complementos de Office deben servirse por HTTPS. Elige cómo llega el agent con CONNXL_TLS_TERMINATION:

edge (el valor por defecto) — el agent sirve HTTP plano en :3000 y espera un balanceador de carga que termine el TLS delante (un AWS ALB con un certificado ACM, nginx, Caddy o un túnel) sobre un nombre DNS que controles. El agent no guarda ningún certificado, así que autoescala sin fricción — la configuración recomendada para producción.
agent — el agent termina el TLS él mismo. Define CONNXL_TLS_TERMINATION=agent y coloca cert.pem y key.pem junto al binario. Úsalo para una sola VM sin balanceador, o para pruebas locales (mkcert emite uno de confianza).

En ambos casos el agent escucha en :3000. Office no cargará un complemento por HTTP no confiable directamente, así que un agent edge expuesto sin un terminador delante falla de forma visible en vez de servir de forma insegura.

terminalsh

# working directory holds: connxl-agent, static/  (cert.pem + key.pem only in agent mode)

./connxl-agent                                # default (edge): HTTP on :3000 behind your TLS-terminating load balancer
CONNXL_TLS_TERMINATION=agent ./connxl-agent   # agent terminates TLS with cert.pem/key.pem → https://<host>:3000

Alcanzabilidad

Cualquiera que sea el host que elijas, debe ser alcanzable por HTTPS por cada cliente de Excel que vaya a usar el complemento — Excel obtiene el panel de tareas y ejecuta funciones contra el agent directamente. El agent solo hace conexiones salientes hacia este backend, así que se sitúa cómodamente detrás de NAT o de un firewall.

El token incrustado solo arranca la inscripción

El token de un solo uso grabado en un binario configurado hace exactamente una cosa: permite que el agent obtenga su certificado de cliente mTLS en el primer arranque. A partir de ahí es el certificado —no el token— el que autentica cada petición, para siempre. Por eso Regenerar nunca perturba a un agent que ya se inscribió, y por eso regenerar contiene un binario configurado filtrado: el token gastado ya no puede ganar un certificado. Consulta Mutual TLS para el ciclo de vida del certificado y la alternativa de atestación en la nube.

Despliega en un host Linux (AWS o donde sea)

En un servidor real, ejecuta el agent como un servicio para que se reinicie al arrancar y tras un fallo. Un binario configurado lleva su propia identidad, así que la unidad no necesita ninguna variable CONNXL_* — solo el directorio de trabajo:

/etc/systemd/system/connxl-agent.serviceini

[Unit]
Description=connxl-agent
After=network-online.target

[Service]
WorkingDirectory=/opt/connxl-agent
ExecStart=/opt/connxl-agent/connxl-agent
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

connxl-agent y static/ viven en /opt/connxl-agent (añade también cert.pem/key.pem, y Environment=CONNXL_TLS_TERMINATION=agent, solo si quieres que el agent termine el TLS él mismo en vez de correr detrás de un balanceador). Luego systemctl enable --now connxl-agent.

El agent solo hace conexiones salientes hacia este backend y hacia tus fuentes de datos, así que un host cerrado no necesita ningún puerto de entrada abierto para el enlace con el backend. Lo que sí tiene que ser alcanzable es el endpoint HTTPS :3000 del agent — Excel obtiene el panel de tareas y ejecuta funciones contra él directamente, desde donde estén tus usuarios. Dale un certificado de confianza pública para el host exacto del manifiesto; en la web y en máquinas que no gestionas, un certificado autofirmado será rechazado. Patrones habituales:

Proxy inverso / balanceador de carga (nginx, Caddy, un AWS ALB con un certificado de ACM) que termina TLS en un nombre DNS que posees y reenvía al :3000 del agent.
Un túnel (p. ej. Cloudflare Tunnel) que publica el agent en un nombre de host HTTPS de confianza sin abrir ningún puerto de entrada — útil para una prueba rápida o para un agent sin IP pública.

Elijas lo que elijas, define esa URL HTTPS pública como el host del agent del entorno (abajo) para que el manifiesto generado apunte Excel a ella.

Avanzado: configurar la identidad con variables de entorno

La descarga configurada es la vía fácil, pero el agent sigue leyendo su identidad de las variables de entorno CONNXL_* cuando las defines — la opción correcta para contenedores, Kubernetes o cualquier flujo de IaC/automatización donde una descarga grabada no encaja. Las variables de entorno siempre ganan: cualquier valor CONNXL_* que definas anula el campo correspondiente incrustado en el binario, así que puedes partir de un binario sin configurar (crudo) —consigue uno en Configuración avanzada / manual en el panel de Despliegue— o anular campos concretos en uno configurado.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	El host público de este backend — de donde el agent extrae su configuración y hacia donde envía telemetría.
`CONNXL_ENROLL_TOKEN`Required	`string`	Un token de inscripción de un solo uso, revelado una vez cuando haces clic en Regenerar para este entorno. El agent lo intercambia por su propio certificado de cliente mTLS en el primer arranque, y a partir de ahí se autentica con ese certificado.
`CONNXL_MTLS_CERT`Required	`path`	Ruta donde el agent guarda el certificado de cliente que inscribe — tú eliges la ubicación, el agent crea el archivo. No es el mismo par que cert.pem/key.pem, más arriba.
`CONNXL_MTLS_KEY`Required	`path`	Ruta de la clave privada correspondiente. Ver TLS mutuo para el ciclo completo.

¿Sin token? Inscríbete con la identidad en la nube del agent

En AWS, GCP o Azure, el agent puede inscribirse sin ningún token usando su identidad de instancia — establece CONNXL_ENROLL_ATTESTATION (más CONNXL_ADDIN_ID/CONNXL_ENV_ID) en lugar de CONNXL_ENROLL_TOKEN. Ver TLS mutuo.

Apunta Excel a tu host del agent

En la página de tu complemento, define el host del agent (anúlalo por entorno en los ajustes del entorno). ConnXL incorpora ese host en cada URL del manifiesto generado — el panel de tareas, los metadatos de las funciones y cada imagen — de modo que Excel siempre habla con tu agent y nunca con ConnXL.

Introduce solo el dominio — addin.tu-empresa.com, con puerto si hace falta. El https:// es fijo y aparece como prefijo del campo: Office solo carga un complemento por HTTPS, localhost incluido, así que el esquema no se elige.

Descarga o copia el manifiesto

Desde la misma página, descarga el manifiesto generado. ConnXL emite tanto el manifiesto XML clásico como el manifiesto JSON unificado — elige el que necesite tu versión de Office. También puedes copiar la URL del manifiesto, que es la fuente autorizada para el despliegue centralizado.

Es un manifiesto, no un binario

No hay un binario de complemento de un clic ni una ficha en la Office Store. La descarga es un pequeño archivo de manifiesto que registra en Excel tu complemento alojado por el agent.

Llévalo a Excel

Hay dos formas de instalarlo, según para quién sea:

Sideload — para ti o un equipo pequeño durante la configuración. Registra el manifiesto localmente y el complemento aparece en la cinta de opciones. La guía de sideloading de Microsoft cubre cada plataforma.
Despliegue centralizado en M365 — para desplegarlo en toda tu organización. Tu administrador de Microsoft 365 despliega el complemento desde el centro de administración usando la URL del manifiesto, y llega a cada usuario asignado.

Cuándo tienes que volver a desplegar

La mayoría de los cambios se aplican en vivo — editar funciones, conexiones, el panel de tareas o las plantillas fluye al agent por su canal de configuración sin redespliegue. Solo los cambios que alteran el manifiesto en sí — el icono del complemento, añadir/quitar/reetiquetar un botón de la cinta, o el nombre de la pestaña personalizada — requieren que los usuarios reinstalen el manifiesto.

Referencia de variables de entorno

Todo lo que el agent lee al arrancar. Una descarga configurada aporta su propia identidad, así que en esa vía no necesitas ninguna de estas; son la vía manual / de automatización, y cualquier valor que definas aquí anula el campo correspondiente incrustado en un binario configurado. CONNXL_BACKEND_URL más una credencial de inscripción — CONNXL_ENROLL_TOKEN, o CONNXL_ENROLL_ATTESTATION con CONNXL_ADDIN_ID/CONNXL_ENV_ID — más CONNXL_MTLS_CERT/CONNXL_MTLS_KEY (donde aterriza el certificado emitido) es el mínimo para cablear la identidad a mano; el resto son opcionales. El agent escucha en el puerto 3000. Por defecto (CONNXL_TLS_TERMINATION sin definir o edge) sirve HTTP plano ahí detrás de un balanceador que termina el TLS — no hace falta cert.pem/key.pem; define CONNXL_TLS_TERMINATION=agent para que termine el TLS él mismo con el par cert.pem / key.pem junto al binario (ese par nunca es una variable de entorno).

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	El host público de este backend — de donde el agent obtiene su configuración y adonde envía la telemetría.
`CONNXL_TLS_TERMINATION`Optional	`edge \| agent`	Cómo maneja el TLS el listener de cara a Excel en :3000. Por defecto edge: el agent sirve HTTP plano y un balanceador que termina el TLS delante maneja el HTTPS (sin cert.pem/key.pem). agent: el agent termina el TLS él mismo con cert.pem/key.pem junto al binario — el caso de una sola VM / sin balanceador / local. Es independiente del mTLS agent-a-backend, que siempre está activo.
`CONNXL_MTLS_CERT`Required	`path`	Ruta donde el agent guarda el certificado de cliente que inscribe (tú eliges la ubicación — el agent crea el archivo). Ver TLS mutuo.
`CONNXL_MTLS_KEY`Required	`path`	Ruta de la clave privada correspondiente.
`CONNXL_ENROLL_TOKEN`Condicional	`string`	Token de inscripción de un solo uso que permite a un agent nuevo obtener su certificado mTLS en el primer arranque — el único mecanismo de autenticación del agent (ya no existe una clave de API estática). Requerido salvo que te inscribas con CONNXL_ENROLL_ATTESTATION. Ver TLS mutuo.
`CONNXL_ENROLL_ATTESTATION`Condicional	`aws \| gcp \| azure`	Usa el documento de identidad de instancia de la nube como credencial de inscripción en lugar de un token. Requerido salvo que se establezca CONNXL_ENROLL_TOKEN.
`CONNXL_ADDIN_ID`Condicional	`id`	El complemento al que se inscribe este agent. Requerido solo si se establece CONNXL_ENROLL_ATTESTATION — no se lee en la vía por token.
`CONNXL_ENV_ID`Condicional	`id`	El entorno al que se inscribe este agent. Requerido solo si se establece CONNXL_ENROLL_ATTESTATION — no se lee en la vía por token.
`CONNXL_ZONE`Optional	`string`	Etiqueta libre de ubicación (un rack, un datacenter, una zona de disponibilidad). Se reporta con las instantáneas de salud y se muestra en la página de salud del agent.
`CONNXL_REGION`Optional	`string`	Etiqueta libre de región, reportada junto a la zona.
`CONNXL_REPLICA_ID`Optional	`string`	Etiqueta opcional que identifica esta réplica en los heartbeats y en los logs agregados. Útil cuando ejecutas varios agentes detrás de un balanceador y el hostname de la máquina es opaco (un id de contenedor o pod). Por defecto usa el hostname de la máquina.
`CONNXL_HEARTBEAT_SECONDS`Optional	`int`	Intervalo del heartbeat en segundos. Por defecto 30, limitado a un máximo de 60 — el backend marca un agent como desconectado tras ~90 s de silencio, así que un intervalo mayor haría parpadear un agent sano.
`CONNXL_STATE_DIR`Optional	`path`	Directorio donde el agent persiste su estado de ejecución entre reinicios. Por defecto un directorio state/ junto al binario.
`CONNXL_SECRETS_TTL_SECONDS`Optional	`int`	Cuánto tiempo se cachean las referencias a secretos resueltas, en segundos. Por defecto 300; 0 o negativo desactiva la caché. Los errores de resolución nunca se cachean.
`CONNXL_SECRETS_AWS_REGION`Optional	`string`	Región por defecto para referencias a secretos respaldadas por AWS. Un ?region= en la propia referencia tiene prioridad; sin ninguno de los dos, aplica la cadena por defecto del SDK de AWS.
`CONNXL_SECRETS_AWS_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referencias a secretos respaldadas por AWS (un VPC endpoint, un endpoint FIPS o un emulador). Debe ser https o una dirección de loopback — cualquier otra cosa se ignora con un aviso, porque definir un endpoint también omite la cadena de credenciales y uno en texto plano llevaría nombres y valores de secretos en claro.
`CONNXL_SECRETS_GCP_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referencias de GCP Secret Manager (un Secret Manager privado o emulado). Debe ser https o una dirección de loopback. Si se define, se omiten las Application Default Credentials. Déjalo sin definir para usar el servicio real.
`CONNXL_SECRETS_AZURE_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referencias de Azure Key Vault (un vault privado o emulado). Debe ser https o una dirección de loopback. Si se define, se omite DefaultAzureCredential. Déjalo sin definir para usar el servicio real.
`CONNXL_LOG_LEVEL`Optional	`debug \| info \| warn \| error`	Nivel mínimo de severidad que se escribe en los logs. Por defecto info; debug añade líneas detalladas; warn conserva los fallos y los problemas reintentables; error conserva solo los fallos terminales — también oculta un heartbeat o una reinscripción fallidos, así que usa warn para bajar el ruido.
`CONNXL_LOG_FORMAT`Optional	`text \| json`	Formato de las líneas de log en disco y stdout. Por defecto text (legible); json emite un objeto JSON por línea ({ts, level, category, msg}) para colectores de logs.

Conexiones

Conecta el agent a tus fuentes de datos antes de construir funciones.

Usar funciones en Excel

El espacio de nombres, el panel de tareas, las referencias de celda, los desbordamientos y las actualizaciones en vivo.

Instalar el complemento

Conexiones

Usar funciones en Excel

En esta página