Saltar a contenido

Proveedores de Almacenamiento

Clarive soporta proveedores de almacenamiento conectables para documentos adjuntos a tópicos y otros activos binarios. Esto le permite almacenar archivos fuera de la base de datos MongoDB manteniendo compatibilidad con instalaciones existentes.

Descripción General

Por defecto, Clarive almacena todos los adjuntos en MongoDB GridFS. Con proveedores de almacenamiento, puede:

  • Almacenar archivos en sistemas de almacenamiento externos (S3, sistema de archivos, etc.)
  • Reducir el tamaño de la base de datos y mejorar el rendimiento de los respaldos
  • Implementar estrategias de almacenamiento personalizadas para diferentes tipos de archivos
  • Mantener compatibilidad completa con archivos existentes

Comportamiento por Defecto

Todas las instalaciones de Clarive utilizan GridFS como proveedor de almacenamiento predeterminado. Esto mantiene 100% de compatibilidad con versiones anteriores.

Los archivos se almacenan en las colecciones MongoDB: - grid.files - Metadatos de archivos - grid.chunks - Contenido de archivos (en bloques de 255KB)

Arquitectura

El sistema de proveedores de almacenamiento consta de tres componentes principales:

  1. Baseliner::StorageProvider - Rol que define la interfaz del proveedor
  2. Baseliner::Storage - Fábrica y gestor para proveedores
  3. Implementaciones de Proveedores - Backends de almacenamiento concretos (GridFS, etc.)

Interfaz del Proveedor

Todos los proveedores de almacenamiento deben implementar el rol Baseliner::StorageProvider, que requiere estos métodos:

  • put(filehandle => $fh, ...) - Almacenar un archivo, devuelve storage_id
  • get(storage_id => $id) - Recuperar un objeto de archivo
  • remove(storage_id => $id) - Eliminar un archivo
  • info(storage_id => $id) - Obtener metadatos del archivo
  • exists(storage_id => $id) - Verificar si el archivo existe

Uso de Proveedores de Almacenamiento

Obtener un Proveedor

use Baseliner::Storage;

# Obtener el proveedor predeterminado (GridFS)
my $provider = Baseliner::Storage->provider();

# Obtener un proveedor específico
my $provider = Baseliner::Storage->provider('GridFS');

Almacenar Archivos

# Almacenar un archivo
my $storage_id = $provider->put(
    filehandle => $fh,
    filename   => 'documento.pdf',
    metadata   => { campo_personalizado => 'valor' }
);

Recuperar Archivos

# Obtener un objeto de archivo
my $file = $provider->get( storage_id => $storage_id );

# Leer contenido
my $content = $file->slurp();

# Escribir a filehandle
$file->print($output_fh);

# Obtener metadatos
my $info = $file->info();  # { length, md5, uploadDate, filename, metadata }

Eliminar Archivos

# Eliminar un archivo
$provider->remove( storage_id => $storage_id );

# Verificar si el archivo existe
if ($provider->exists( storage_id => $storage_id )) {
    # El archivo existe
}

Proveedor de Microsoft SharePoint

Clarive incluye un proveedor de almacenamiento SharePoint que almacena archivos en Microsoft SharePoint Online utilizando la API de Microsoft Graph.

Configuración

Para usar SharePoint como proveedor de almacenamiento:

  1. Crear un Recurso CI de Sitio SharePoint (MSSharePointSite)
  2. Configurar la conexión de SharePoint:
  3. Tenant ID: ID del inquilino de Microsoft 365
  4. Client ID: ID de aplicación (cliente) del registro de aplicación Azure AD
  5. Client Secret: Secreto de cliente del registro de aplicación Azure AD
  6. Site ID: Identificador del sitio SharePoint
  7. Drive ID: ID de unidad de biblioteca de documentos (predeterminado: "root")

  8. Active: Habilitar el proveedor de almacenamiento

  9. En la configuración del campo "Adjuntar Archivos", seleccionar:

  10. Storage Provider: Su CI de Sitio SharePoint
  11. Storage Folder: Ruta de carpeta en SharePoint (ej., /FromClarive)

Registro de Aplicación Azure AD

Antes de usar el proveedor SharePoint, debe registrar una aplicación en Azure AD:

  1. Ir a Portal Azure → Azure Active Directory → Registros de aplicaciones
  2. Crear un nuevo registro
  3. En "Certificados y secretos", crear un nuevo secreto de cliente
  4. En "Permisos de API", agregar:
  5. Microsoft Graph → Permisos de aplicación
  6. Sites.ReadWrite.All
  7. Files.ReadWrite.All
  8. Otorgar consentimiento de administrador para los permisos
  9. Copiar el Tenant ID, Client ID y Client Secret

Obtener IDs de Sitio y Unidad

Para encontrar su Site ID y Drive ID de SharePoint:

# Obtener site ID
curl -H "Authorization: Bearer <token>" \
  "https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<nombre-sitio>"

# Obtener drive ID
curl -H "Authorization: Bearer <token>" \
  "https://graph.microsoft.com/v1.0/sites/<site-id>/drives"

Características

El proveedor de almacenamiento SharePoint:

  • Almacena archivos en SharePoint Online con nombres de archivo originales
  • Utiliza IDs de archivo de SharePoint para recuperación confiable de archivos
  • Soporta carpetas de almacenamiento configurables por campo
  • Maneja automáticamente la autenticación OAuth2
  • Soporta cargas fragmentadas para archivos grandes (fragmentos de 3.2 MB)
  • Reemplaza archivos existentes en actualización (comportamiento de conflicto: reemplazar)

Organización de Archivos

Los archivos se almacenan en SharePoint exactamente como se especifica en la configuración del campo:

  • Storage Folder: Configurado a nivel de campo (ej., /FromClarive)
  • Filename: El nombre de archivo original se preserva (ej., documento.pdf)
  • Ruta Completa: /FromClarive/documento.pdf

El proveedor de almacenamiento guarda el ID único de archivo de SharePoint en la base de datos de Clarive, que se utiliza para todas las operaciones de archivo (descarga, eliminación, información).

Configuración a Nivel de Campo

Cada campo "Adjuntar Archivos" puede especificar su propia carpeta de almacenamiento:

{
    xtype: 'textfield',
    name: 'storage_folder',
    fieldLabel: 'Carpeta de Almacenamiento',
    value: '/FromClarive'  // Los archivos se almacenarán aquí
}

Esto permite usar el mismo CI de Sitio SharePoint para múltiples campos, cada uno almacenando archivos en carpetas diferentes.

Sustitución de Variables en Carpetas de Almacenamiento

La ruta de la carpeta de almacenamiento soporta sustitución de variables usando la sintaxis ${variable}. Las variables se reemplazan con datos del tópico al momento de la carga.

Ejemplos:

// Usar título del tópico
storage_folder: '/Documentos/${title}'

// Usar categoría del tópico
storage_folder: '/Proyectos/${category}'

// Usar nombres de CIs relacionados (se resuelven automáticamente)
storage_folder: '/Ambientes/${environment}/Proyectos/${project}'

Resolución de Variables:

  • Los campos del tópico están disponibles directamente (ej., ${title}, ${status})
  • Los campos CI relacionados (MIDs) se reemplazan automáticamente con nombres de CI
  • Los campos de array con un solo valor se convierten a escalares
  • Los valores múltiples permanecen como arrays (se usa el primer valor)

Ejemplo:

Si un tópico tiene: - Título: "Implementación de Funcionalidad" - CI de Proyecto: "MiProyecto" (MID: cla-default-project-123) - CI de Ambiente: "Producción" (MID: cla-default-environment-456)

Y storage_folder está configurado como: /Proyectos/${project}/${environment}

La ruta final será: /Proyectos/MiProyecto/Producción

Limitaciones

  • Los archivos se almacenan con sus nombres originales; el versionado lo maneja el versionado de activos de Clarive
  • Los caracteres inválidos de SharePoint (" * : < > ? / \ |) en rutas de carpetas y nombres de archivos se reemplazan automáticamente con guiones bajos
  • Los caracteres especiales como #, %, &, etc. están permitidos y se codifican automáticamente en URL
  • Requiere conectividad de red a la API de Microsoft Graph
  • Requiere credenciales y permisos válidos de Azure AD
  • El rendimiento de descarga depende de los tiempos de respuesta de SharePoint/Microsoft Graph API

Creación de un Recurso de Proveedor de Almacenamiento

Los proveedores de almacenamiento se crean como Recursos CI en Clarive. Para crear un nuevo proveedor de almacenamiento SharePoint:

Nota: La funcionalidad mssharepoint debe estar instalada para que el tipo de proveedor MSSharePointSite esté disponible.

  1. Navegar a Recursos en la interfaz de Clarive
  2. Hacer clic en Crear Nuevo Recurso
  3. Seleccionar Proveedor de Almacenamiento de los tipos de recursos
  4. Elegir MSSharePointSite como el tipo de proveedor
  5. Completar los campos requeridos:
  6. Nombre: Un nombre descriptivo para el proveedor
  7. Moniker: Identificador único
  8. Activo: Marcar para habilitar el proveedor
  9. Tenant ID, Client ID, Client Secret: Credenciales de Azure AD
  10. Site ID, Drive ID: Identificadores de SharePoint
  11. Hacer clic en Guardar

Una vez creado, el proveedor SharePoint estará disponible para selección en las configuraciones de campos "Adjuntar Archivos" en toda la aplicación Clarive.

Ver También