Controlador Salesforce

Esta documentación explica la implementación del controlador Salesforce y cómo los parámetros de conexión se corresponden con los campos de la interfaz de usuario en la aplicación Gigantic.

Parámetros de Conexión

Autenticación: JWT OAuth 2.0

El controlador Salesforce utiliza JWT OAuth 2.0 Bearer Flow para autenticación servidor-a-servidor. Este método es seguro y no requiere interacción del usuario.

Configuración de Autenticación JWT

Paso 1: Crear una Aplicación Conectada en Salesforce

1. Inicie sesión en su organización de Salesforce
2. Navegue a: Configuración → Aplicaciones → Administrador de Aplicaciones
3. Haga clic en Nueva Aplicación Conectada
4. Complete la información básica:
   • Nombre de Aplicación Conectada: Gigantic Data Migration
   • Correo de Contacto: Su correo electrónico
5. Habilite Configuración de OAuth:
   • Marque "Habilitar Configuración de OAuth"
   • URL de Callback: https://login.salesforce.com (no se usa para JWT pero es requerido)
   • Marque "Usar firmas digitales"
   • Cargue su certificado (clave pública del par de claves que generará)
   • Seleccione Alcances de OAuth:
     • Acceso completo (full)
     • Realizar solicitudes en cualquier momento (refresh_token, offline_access)
6. Guarde y anote el Consumer Key

Paso 2: Generar Par de Claves RSA

Genere una clave privada y certificado:

# Generar clave privada
openssl genrsa -out server.key 2048

# Generar certificado (clave pública)
openssl req -new -x509 -key server.key -out server.crt -days 365

Cargue server.crt a la Aplicación Conectada (Paso 1). Use server.key en la configuración de Gigantic.

Paso 3: Pre-Autorizar Usuario

1. Vaya a: Configuración → Aplicaciones → Aplicaciones Conectadas → Administrar Aplicaciones Conectadas
2. Haga clic en el nombre de su aplicación
3. Haga clic en Editar Políticas
4. Bajo Políticas de OAuth:
   • Usuarios Permitidos: Los usuarios aprobados por el administrador están pre-autorizados
5. Haga clic en Guardar
6. Haga clic en Administrar Perfiles o Administrar Conjuntos de Permisos
7. Agregue el perfil o conjunto de permisos de su usuario

Detalles Técnicos

El controlador Salesforce utiliza Bulk API 2.0 para operaciones de datos de alto rendimiento:

• Consultas: Utiliza automáticamente Bulk API 2.0 para conjuntos de datos de más de 10,000 registros, REST API para consultas más pequeñas
• Escrituras: Utiliza Bulk API 2.0 para todas las operaciones de inserción, actualización y upsert
• Tamaños de Lote: Soporta hasta 150,000 registros por lote
• Procesamiento Concurrente: Soporta hasta 100 trabajos paralelos
• Ordenamiento Automático: Los objetos padre se procesan antes que los hijos

Modos de Carga

El controlador Salesforce soporta tres modos de carga:

ID Externa para Operaciones Merge

Al usar modo merge, el controlador crea automáticamente un campo de ID externa llamado GIGExternalId__c en cada objeto:

• Tipo de Campo: Texto (255 caracteres)
• Propósito: Mapea IDs de registros de origen a org destino
• Único: Marcado como ID externa para coincidencia de upsert
• Automático: Creado durante la fase start si no existe

Cómo funciona:

1. El ID del registro de origen se almacena en GIGExternalId__c
2. En upsert, Salesforce busca coincidencias por GIGExternalId__c
3. Si encuentra coincidencia → Actualiza; Si no encuentra → Inserta

Ejemplo:

rules:
  migration:
    loadMode: merge  # Habilita uso de ID externa
    include:
      - Account
      - Contact

Mejores Prácticas

✅ Recomendado: Migraciones de Sandbox

Utilice siempre Gigantic con sandboxes de Salesforce, no producción:

• Por qué: Las migraciones de datos pueden afectar automatizaciones, reglas de validación y lógica de negocio
• Tipos de Sandbox: Full Copy, Partial Copy o Developer sandboxes
• Pruebas: Valide la migración en sandbox antes de considerar producción
• Inicio de Sesión en Sandbox: Use https://test.salesforce.com como host

✅ Recomendado: Modo Update en la Misma Org

Para el mejor rendimiento y configuración más simple, use modo update dentro de la misma org:

Beneficios:

• ⚡ Rápido: No requiere mapeo de ID, procesamiento verdaderamente concurrente
• 🎯 Simple: Sin mapeo de usuarios, sin creación de ID externa
• ✅ Confiable: Referencias directas de ID, sin complejidad entre orgs

Ejemplo de Caso de Uso:

# Anonimizando datos en el mismo sandbox
source:
  driver: salesforce
  host: https://test.salesforce.com
  # ... detalles de autenticación

sink:
  driver: salesforce
  host: https://test.salesforce.com  # ¡Misma org!
  # ... mismos detalles de autenticación

rules:
  anonymize:
    loadMode: update  # Actualizar registros en el lugar
    transform:
      Contact:
        - Email:
            action: fake
            label: tech/email

Update vs Merge: Cuándo Usar Cada Uno

Gestión de Automatizaciones

⚠️ Importante: Las automatizaciones de Salesforce pueden ralentizar o bloquear migraciones de datos.

Antes de ejecutar migraciones grandes, considere deshabilitar automatizaciones:

• Reglas de Validación: Pueden bloquear registros
• Reglas de Flujo de Trabajo: Pueden ralentizar operaciones
• Process Builder: Se ejecuta en cada registro
• Flujos: Los flujos auto-lanzados se ejecutan durante cargas
• Reglas de Duplicados: Pueden bloquear upserts (ver abajo)
• Triggers de Apex: Consumen tiempo de procesamiento

Cómo deshabilitar:

1. Navegue a: Configuración → Automatización de Procesos
2. Desactive flujos de trabajo, procesos y flujos relevantes
3. Navegue a: Configuración → Administrador de Objetos → [Objeto] → Reglas de Validación
4. Desactive reglas de validación temporalmente
5. Ejecute la migración
6. Re-habilite después de completar

Reglas de Duplicados

Las reglas de duplicados de Salesforce pueden bloquear operaciones de merge incluso al usar IDs externas:

Problema: Las reglas de duplicados verifican campos como Email, Nombre, Teléfono - no solo su ID externa. Durante upsert, si la ID externa no coincide pero otros campos sí, la inserción falla.

Solución: Deshabilite las reglas de duplicados durante la migración

Configuración → Gestión de Duplicados → Reglas de Duplicados → Desactivar

Soporte de Túnel SSH

El controlador Salesforce no requiere túneles SSH ya que se conecta directamente a servicios cloud de Salesforce vía HTTPS. Todas las conexiones están encriptadas por defecto.

Endpoints de API Utilizados

Las conexiones Salesforce se utilizan principalmente en:

• Creación de Tap (descubrimiento de esquema y extracción de datos)
• Creación de Sink (destino de carga de datos)
• Ejecución de Pipeline (anonimización y migración de datos)

Parámetros Personalizados

El controlador Salesforce soporta parámetros personalizados adicionales para configuraciones avanzadas.

Ejemplo:

bulkPollInterval: 5000        # Intervalo de sondeo en milisegundos (por defecto: 5000)
bulkPollTimeout: 1800000      # Tiempo máximo de espera en milisegundos (por defecto: 1800000 - 30 minutos)
bulkQueryThreshold: 10000     # Umbral de cantidad de registros para usar Bulk API 2.0 (por defecto: 10000)

Descripciones de Parámetros:

• bulkPollInterval: Con qué frecuencia verificar el estado del trabajo en milisegundos. Valores más bajos proporcionan actualizaciones más rápidas pero consumen más llamadas API. El valor por defecto es 5000ms (5 segundos).

• bulkPollTimeout: Tiempo máximo de espera para que un trabajo se complete en milisegundos. Los trabajos que excedan este tiempo serán cancelados. El valor por defecto es 1800000ms (30 minutos).

• bulkQueryThreshold: Número mínimo de registros para activar Bulk API 2.0 para consultas. Las consultas por debajo de este umbral usan REST API para mejor rendimiento. El valor por defecto es 10000 registros.

Solución de Problemas

Errores de Autenticación

Problema: "invalid_grant: user hasn't approved this consumer"

Solución:

1. Verifique que la Aplicación Conectada esté configurada correctamente
2. Pre-autorice el usuario (Administrar Perfiles/Conjuntos de Permisos)
3. Verifique que el certificado coincida con la clave privada
4. Asegúrese que el nombre de usuario sea correcto

Problema: "invalid_grant: invalid client credentials"

Solución:

• Verifique que el Consumer Key sea correcto
• Verifique que el archivo de clave privada exista y sea legible
• Asegúrese que el certificado fue cargado a la Aplicación Conectada

Errores de Detección de Duplicados

Problema: DUPLICATES_DETECTED: Use one of these records

Solución: Deshabilite las reglas de duplicados antes de la migración (vea sección Gestión de Automatizaciones arriba)

Problemas de Rendimiento

Problema: La migración es lenta

Soluciones:

1. Deshabilite automatizaciones (mayor impacto)
2. Use modo update en lugar de merge (si es misma org)
3. Verifique que las reglas de automatización estén desactivadas

Límites de Conexión

Problema: Errores de límite de API

Solución:

• Bulk API 2.0 solo cuenta la creación de trabajos contra límites de API (no cada lote)
• Considere la asignación de límite de API diaria

Resumen

El controlador Salesforce está optimizado para migraciones de datos de alto rendimiento usando Bulk API 2.0:

✅ Use sandboxes para pruebas y migraciones ✅ Modo update para operaciones en misma org (más rápido) ✅ Modo merge para migraciones entre orgs ✅ Deshabilite automatizaciones antes de migraciones grandes ✅ JWT OAuth para autenticación segura