Script de Migración de Assets

Este script migra assets (documentos/archivos) de proveedores de almacenamiento antiguos a nuevos proveedores de almacenamiento basándose en la configuración de categoría del topic.

Propósito¶

Cuando actualizas la configuración del campo de documento de una categoría de topic para usar un nuevo proveedor de almacenamiento (por ejemplo, migrar de GridFS a SharePoint), los assets existentes en los topics de esa categoría seguirán almacenados en el proveedor antiguo. Este script migra esos assets existentes al nuevo proveedor de almacenamiento.

Uso¶

Ejecución en Seco (Recomendado Primero)¶

Antes de realizar la migración real, ejecuta el script de ejecución en seco para ver qué se migraría:

./bin/cla repl --script repl-scripts/migrate_assets_dryrun.pl <nombre_categoria>

Migración Real¶

Después de revisar la salida de la ejecución en seco, realiza la migración real:

./bin/cla repl -c <config> --script repl-scripts/migrate_assets.pl <nombre_categoria> [límite]

Parámetros¶

<nombre_categoria>: El nombre de la categoría del topic cuyos assets deseas migrar
[límite]: Opcional. Número de topics a procesar. Úsalo para probar con un número pequeño de topics primero.

Ejemplo¶

# Primero, verifica qué se migraría
./bin/cla repl -c clarive --script repl-scripts/migrate_assets_dryrun.pl "Change Request"

# Prueba con solo 1 topic primero
./bin/cla repl -c clarive --script repl-scripts/migrate_assets.pl "Change Request" 1

# Si tiene éxito, migra todos los topics
./bin/cla repl -c clarive --script repl-scripts/migrate_assets.pl "Change Request"

Qué Hacen los Scripts¶

Script de Ejecución en Seco (`migrate_assets_dryrun.pl`)¶

Analiza Sin Cambios: Examina todos los assets sin modificar nada
Muestra Plan de Migración: Lista qué assets se migrarían
Identifica Problemas: Resalta assets sin proveedor de destino configurado
Seguro de Ejecutar: Se puede ejecutar múltiples veces sin efectos secundarios

Script de Migración (`migrate_assets.pl`)¶

Encuentra Topics: Localiza todos los topics en la categoría especificada
Encuentra Assets: Para cada topic, encuentra todos los documentos/assets adjuntos
Verifica Configuración: Determina el proveedor de almacenamiento de destino a partir de la configuración del campo de documento de la categoría
Omite si Ya Está Migrado: Si un asset ya está en el proveedor de destino, lo omite
Migra Archivos: Para assets que necesitan migración:
Descarga el archivo del proveedor de almacenamiento antiguo
Sube al nuevo proveedor de almacenamiento
Actualiza el CI del asset con la nueva ubicación de almacenamiento y proveedor
Elimina el archivo del proveedor de almacenamiento antiguo
Reporta Resultados: Proporciona un resumen de:
Total de assets encontrados
Assets ya migrados
Assets migrados exitosamente
Migraciones fallidas con detalles de errores

Requisitos¶

La categoría debe tener al menos un campo de documento configurado con un storage_provider
El proveedor de almacenamiento de destino debe estar correctamente configurado y accesible
El script requiere acceso a la base de datos de Clarive y a los proveedores de almacenamiento

Ejemplo de Salida¶

======================================================================
Asset Migration Script
Category: Change Request
======================================================================
Found category: Change Request (ID: category-12345)
Found 10 topics in category 'Change Request'

----------------------------------------------------------------------
Processing topic: CR-001: Update Authentication (topic-98765)
  Found 3 asset(s)
    Asset: design_doc.pdf (MID: asset-11111)
      Current provider: GridFS (default)
      Field: documents
      Target provider MID: mssharepoint-site-1
      Target folder: ChangeRequests/{title}
      Status: Needs migration
      Starting migration...
        Downloading from old provider...
        Uploading to new provider...
        New storage ID: 01ABCDEFGHIJKLMNOPQRSTUVWXYZ
        Updated asset CI
        Removing from old provider...
        Migration completed ✓
    Asset: screenshot.png (MID: asset-22222)
      Current provider MID: mssharepoint-site-1
      Field: documents
      Target provider MID: mssharepoint-site-1
      Status: Already migrated ✓
    ...

======================================================================
Migration Summary
======================================================================
Total assets found:        30
Already migrated:          5
Successfully migrated:     23
Failed migrations:         2

Errors encountered:
  - Asset old_file.doc (asset-99999): Could not retrieve file data from old provider

Done!

Características de Seguridad¶

El script verifica si los assets ya están en el proveedor de destino antes de migrarlos
Proporciona salida de progreso detallada para cada asset
Las migraciones fallidas se reportan pero no detienen el script
Solo elimina archivos del proveedor antiguo después de una carga exitosa al nuevo proveedor
El parámetro de límite opcional permite probar con un número pequeño de topics (por ejemplo, 1) antes de procesar todos los topics
El script se puede ejecutar de forma segura múltiples veces - los assets ya migrados se omitirán

Solución de Problemas¶

Error: "Category 'X' not found"¶

Verifica que el nombre de la categoría esté escrito correctamente
Los nombres de categorías distinguen entre mayúsculas y minúsculas

Error: "Could not instantiate new provider"¶

Verifica que el CI del proveedor de almacenamiento esté correctamente configurado
Verifica que el MID del proveedor exista en la base de datos

Error: "Could not retrieve file data from old provider"¶

El archivo puede haber sido eliminado manualmente del proveedor antiguo
El proveedor antiguo puede estar mal configurado o inaccesible

Error: "Could not upload file to new provider"¶

Verifica la configuración y credenciales del proveedor de almacenamiento de destino
Verifica la conectividad de red al proveedor de almacenamiento (por ejemplo, SharePoint)
Verifica los permisos y cuotas del proveedor de almacenamiento

Notas¶

El script empareja cada asset con su configuración de campo específica, asegurando que se use el proveedor de almacenamiento y carpeta correctos
Si un topic tiene múltiples campos de documento con diferentes proveedores, cada asset se migrará al proveedor de su campo correspondiente
GridFS se considera el proveedor "predeterminado" cuando storage_provider_mid no está configurado en un asset
Usa el parámetro de límite opcional para probar con un número pequeño de topics antes de ejecutar en todos los topics