Flujos y comandos

Esta página reúne flujos operativos de acs2md para clientes que necesitan operaciones repetibles a escala de espacio, no solo ejemplos aislados de comandos.

Copia de continuidad de un espacio vivo

Usa este flujo cuando el cliente quiere mantener una copia actualizada del espacio fuera de la plataforma de origen.

acs2md space convert by-key DOCS \
  --output-dir ./continuity/docs \
  --sync

Por qué es útil:

• --sync mantiene la salida alineada con el espacio vivo
• el árbol resultante ya es útil fuera de Confluence
• el cliente obtiene una copia de continuidad que puede revisar, respaldar o republicar

Exportación orientada a archivo que conserva borrados

Usa este flujo cuando el objetivo es preservación más que un espejo exacto.

acs2md space convert by-key DOCS \
  --output-dir ./archive/docs \
  --incremental

Por qué es útil:

• las páginas eliminadas en Confluence se conservan localmente
• en ejecuciones posteriores solo se reprocesa lo que cambia
• la salida se comporta más como un archivo histórico que como un espejo vivo

Preparar una migración de plataforma

Usa este flujo cuando el equipo necesita un árbol documental portable antes de mover contenido a un sitio estático o a un repositorio.

acs2md space pages by-key DOCS --tree
acs2md space convert by-key DOCS \
  --include-metadata \
  --output-dir ./migration/docs

Por qué es útil:

• space pages --tree permite validar el alcance antes de convertir
• los metadatos ayudan a conservar referencias durante la migración
• la estructura de directorios es mucho más sencilla de mapear al sistema destino

Exportación nativa para ingeniería de migración

Usa este flujo cuando el equipo necesita cargas nativas de Confluence para transformación personalizada, depuración de migración o análisis de ingeniería antes de decidir cómo gestionar la conversión a Markdown.

acs2md space get by-key DOCS \
  --format atlas_doc_format \
  --output-dir ./native/docs

Por qué es útil:

• la exportación nativa preserva la representación de origen sin convertirla primero
• los equipos de ingeniería pueden inspeccionar salida ADF o Storage antes de definir reglas personalizadas de migración
• el mismo binario sigue sirviendo para la conversión masiva a Markdown cuando el flujo esté listo para avanzar

Generar un corpus amplio para RAG o búsqueda empresarial

Usa este flujo cuando el cliente necesita contenido repetible a escala para IA o indexación.

acs2md space convert by-key KB \
  --exclude-marks \
  --embed-images=false \
  --output-dir ./rag/kb

Por qué es útil:

• todo el espacio se convierte en un corpus Markdown coherente
• la salida orientada a texto es más fácil de fragmentar e indexar
• las ejecuciones recurrentes actualizan el corpus sin reprocesar todo

Revisión de gobernanza y accesos

Usa este flujo cuando permisos y metadatos son tan importantes como el contenido.

acs2md space list --format json > governance/spaces.json
acs2md space properties by-key DOCS --format json > governance/docs-properties.json
acs2md space permissions by-key DOCS --resolve-users --format json > governance/docs-permissions.json

Por qué es útil:

• inventario, metadatos y permisos quedan recogidos juntos
• --resolve-users hace la salida más legible para revisión con negocio
• es un flujo válido para auditoría, limpieza o preparación de migración

Exportación programada para operaciones

Usa este flujo cuando la exportación debe ejecutarse de forma periódica con muy poca intervención manual.

export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACS2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN
 
acs2md space convert by-key DOCS \
  --output-dir ./scheduled/docs \
  --sync \
  --log-file acs2md.log

Por qué es útil:

• las variables de entorno evitan exponer secretos en el historial
• el comportamiento de sincronización es explícito y predecible
• el log deja una pista operativa de las ejecuciones recurrentes

Copia de seguridad y recuperación ante desastres dentro de Confluence

Usa esto cuando el contenido perdido tenga que volver al propio Confluence, no solo a archivos. Disponible desde v1.0.12.

# Cada noche: una copia de seguridad restaurable; las páginas sin cambios se omiten
acs2md space get by-key DOCS --output-dir /backups --log-file backup.log
 
# Cada mañana: ¿algo ha cambiado, ha desaparecido o ha acabado en la papelera?
acs2md space check by-key DOCS --backup-dir /backups --fail-on-drift
 
# Cuando se perdió algo: revisa el plan y después restaura
acs2md space restore by-key DOCS --backup-dir /backups/DOCS --dry-run
acs2md space restore by-key DOCS --backup-dir /backups/DOCS
 
# Confirma la restauración
acs2md space check by-key DOCS --backup-dir /backups/DOCS

Por qué es útil:

• la copia de seguridad contiene todo lo que necesita una restauración: cuerpos, adjuntos, etiquetas, propiedades y el árbol de carpetas
• space check convierte “falta algo” en una lista exacta de qué falta, antes de que nadie escriba nada
• la restauración muestra su plan, nunca elimina y se reanuda si se interrumpe
• recuperar una página es un solo comando: acs2md page restore --backup-dir /backups/DOCS --page-id PAGE_ID

Consulta Restaurar un espacio para los modos, lo que se recupera y lo que no.

Evidencia para el plan de continuidad de negocio

Úsalo cuando un auditor o un plan de continuidad pida pruebas, no una descripción: que existe una copia del espacio fuera de Confluence, que está al día y que la recuperación se ha probado. Los comandos de abajo producen esa prueba como archivos; relaciónalos con los controles que cite tu plan: A.5.29, A.5.30 y A.8.13 de ISO/IEC 27001:2022, los criterios de disponibilidad de SOC 2 (A1.3 exige una recuperación probada), el artículo 21(2)(c) de NIS 2 sobre gestión de copias de seguridad y recuperación ante desastres, y la cláusula 7.5.3 de ISO 9001:2015 sobre información documentada. Climakers no está certificado bajo estos marcos; los artefactos son tuyos para presentarlos.

# 1. Cada noche: una copia nativa restaurable, conservada con su log
acs2md space get by-key DOCS --output-dir /backups --log-file /backups/DOCS.log
 
# 2. Cada noche, tras la copia: verifícala y conserva el resultado legible por máquina
acs2md space check by-key DOCS --backup-dir /backups --fail-on-drift -f json > /backups/DOCS.check.json
 
# 3. Cada trimestre: una prueba de recuperación en un espacio de pruebas, sin tocar el original
acs2md space restore by-key DOCS-DR --backup-dir /backups/DOCS --create-space --mode all --yes
acs2md space check by-key DOCS-DR --backup-dir /backups/DOCS --all -f json > /backups/DOCS-DR.test.json
 
# 4. Cada semana: una copia de continuidad legible para quien la necesite cuando Confluence esté caído
acs2md space convert by-key DOCS --output-dir /continuity --sync

Qué evidencia cada paso:

• el paso 1 es la copia en sí, con adjuntos, etiquetas, propiedades y el árbol de carpetas registrados en .backup-manifest.json
• el paso 2 es la verificación de la copia: el JSON nombra cada página que se desvió, y una salida distinta de cero es la alerta
• el paso 3 es la prueba de recuperación que piden SOC 2 y NIS 2: la copia restaurada se compara con la copia de seguridad de la que salió, y el .restore-state.json que queda en el directorio de la copia registra qué se restauró y cuándo
• el paso 4 es la copia que sigue siendo legible sin Confluence, en Git, en un archivo o en un sitio estático

Dos cuidados: la prueba de recuperación deja el archivo de progreso apuntando al espacio de pruebas, así que una restauración real en DOCS necesita --reset-state; y la restauración nunca elimina nada, así que el espacio de pruebas se retira a mano en Confluence. Mantén /backups en almacenamiento bajo tu control y conserva los archivos .check.json y .test.json durante tu periodo de retención. Consulta Restaurar un espacio para lo que una restauración puede y no puede devolver.

Secuencia recomendada para una ejecución con cliente

1. confirmar el puesto con doctor
2. descubrir el alcance con space list y space pages
3. decidir si la salida debe comportarse como espejo o como archivo
4. evaluar si la reescritura de enlaces y las imágenes embebidas ayudan o perjudican al uso posterior
5. tratar permisos y propiedades como parte del programa de exportación cuando la gobernanza importe