Integración con Salesforce (SFDC)

En esta página, se describen los pasos de integración de la carga de trabajo operativa de Salesforce (SFDC) en la Base de datos de Cortex Framework. Cortex Framework integra datos de Salesforce con canalizaciones de Dataflow a través de BigQuery, mientras que Cloud Composer programa y supervisa estas canalizaciones de Dataflow para obtener estadísticas a partir de tus datos.

Archivo de configuración

El archivo config.json del repositorio de Data Foundation de Cortex Framework configura la configuración necesaria para transferir datos desde cualquier fuente de datos, incluido Salesforce. Este archivo contiene los siguientes parámetros para las cargas de trabajo operativas de Salesforce:

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

En la siguiente tabla, se describe el valor de cada parámetro operativo de SFDC:

Parámetro Significado Valor predeterminado Descripción
SFDC.deployCDC Implementa la CDC true Genera secuencias de comandos de procesamiento de CDC para que se ejecuten como DAG en Cloud Composer. Consulta la documentación para ver las diferentes opciones de transferencia de datos de Salesforce Sales Cloud.
SFDC.createMappingViews Crea vistas de asignación true Los DAG proporcionados para recuperar registros nuevos de las APIs de Salesforce actualizan los registros en la página de destino. Si este valor se establece en verdadero, se generan vistas en el conjunto de datos procesado por la CDC para exponer tablas con la "versión más reciente de la verdad" del conjunto de datos sin procesar. Si es falso y SFDC.deployCDC es true, se generan DAG con el procesamiento de captura de datos modificados (CDC) basado en SystemModstamp. Consulta los detalles sobre el procesamiento de CDC para Salesforce.
SFDC.createPlaceholders Crea marcadores de posición true Crea tablas de marcadores de posición vacías en caso de que el proceso de transferencia no las genere para permitir que la implementación de informes descendentes se ejecute sin errores.
SFDC.datasets.raw Conjunto de datos de página de destino sin procesar - Es el lugar donde la herramienta de replicación coloca los datos de Salesforce, y es utilizado por el proceso de CDC. Si usas datos de prueba, crea un conjunto de datos vacío.
SFDC.datasets.cdc Conjunto de datos procesado por CDC - Es un conjunto de datos que funciona como fuente para las vistas de informes y como destino para los DAG de registros procesados. Si usas datos de prueba, crea un conjunto de datos vacío.
SFDC.datasets.reporting Conjunto de datos de informes de SFDC "REPORTING_SFDC" Es el nombre del conjunto de datos al que los usuarios finales pueden acceder para generar informes, en el que se implementan las vistas y las tablas para los usuarios.
SFDC.currencies Cómo filtrar monedas [ "USD" ] Si no usas datos de prueba, ingresa una sola moneda (por ejemplo, [ "USD" ]) o varias monedas (por ejemplo,[ "USD", "CAD" ]) según corresponda a tu empresa. Estos valores se usan para reemplazar los marcadores de posición en SQL en los modelos de análsis cuando están disponibles.

Modelo de datos

En esta sección, se describe el modelo de datos de Salesforce (SFDC) con el diagrama de relaciones de entidades (ERD).

Diagrama de relaciones de entidades para SFDC

Figura 2: Salesforce (SFDC): Diagrama de relaciones de entidades.

Vistas básicas

Estos son los objetos azules del ERE y son vistas en tablas de CDC sin transformaciones, excepto algunos alias de nombres de columnas. Consulta las secuencias de comandos en src/SFDC/src/reporting/ddls.

Vistas de informes

Estos son los objetos verdes del ERE y contienen los atributos dimensionales relevantes que usan las tablas de informes. Consulta las secuencias de comandos en src/SFDC/src/reporting/ddls.

Requisitos de datos de Salesforce

En esta sección, se describen los detalles de cómo deben estructurarse tus datos de Salesforce para usarlos con Cortex Framework.

  • Estructura de la tabla:
    • Nombres: Los nombres de las tablas usan snake_case (palabras en minúsculas separadas por guiones bajos) y están en plural. Por ejemplo, some_objects.
    • Tipos de datos: Las columnas mantienen los mismos tipos de datos que se representan en Salesforce.
    • Legibilidad: Es posible que algunos nombres de campos se ajusten ligeramente para mejorar la claridad en la capa de informes.
  • Tablas vacías y la implementación: Todas las tablas requeridas que no estén en el conjunto de datos sin procesar se crean automáticamente como tablas vacías durante el proceso de implementación. Esto garantiza la ejecución fluida del paso de implementación de CDC.
  • Requisitos de la CDC: Los campos Id y SystemModstamp son fundamentales para que las secuencias de comandos de la CDC hagan un seguimiento de los cambios en tus datos. Pueden tener estos nombres exactos o diferentes. Las secuencias de comandos de procesamiento sin procesar proporcionadas recuperan estos campos automáticamente de las APIs y actualizan la tabla de replicación de destino.
    • Id: Actúa como un identificador único para cada registro.
    • SystemModstamp: Este campo almacena una marca de tiempo que indica la última vez que se modificó un registro.
  • Secuencias de comandos de procesamiento sin procesar:Las secuencias de comandos de procesamiento sin procesar proporcionadas no requieren procesamiento adicional (CDC). Este comportamiento se establece de forma predeterminada durante la implementación.

Tablas de origen para la conversión de monedas

Salesforce te permite administrar las monedas de dos maneras:

  • Básico: Es la opción predeterminada, en la que todos los datos usan una sola moneda.
  • Avanzada: Convierte entre varias monedas según los tipos de cambio (requiere habilitar la Administración avanzada de monedas).

Si usas la Administración avanzada de monedas, Salesforce usa dos tablas especiales:

  • CurrencyTypes: Esta tabla almacena información sobre las diferentes monedas que usas (por ejemplo, USD, EUR, etcétera).
  • DatedConversionRates: Esta tabla contiene los tipos de cambio entre monedas a lo largo del tiempo.

Cortex Framework espera que estas tablas estén presentes si usas la administración de monedas avanzada. Si no usas la administración avanzada de monedas, puedes quitar las entradas relacionadas con estas tablas de un archivo de configuración (src/SFDC/config/ingestion_settings.yaml). Este paso evita intentos innecesarios de extraer datos de tablas inexistentes.

Carga datos de SFDC en BigQuery

Cortex Framework proporciona una solución de replicación basada en secuencias de comandos de Python programadas en Apache Airflow y API de Bulk de Salesforce 2.0. Estas secuencias de comandos de Python se pueden adaptar y programar en la herramienta que elijas. Para obtener más información, consulta el módulo de extracción de SFDC.

Cortex Framework también ofrece tres métodos diferentes para integrar tus datos, según de dónde provengan y cómo se administren:

  1. Llamadas a la API: Esta opción es para los datos a los que se puede acceder directamente a través de una API. Cortex Framework puede llamar a la API, tomar los datos y almacenarlos en un conjunto de datos "sin procesar" en BigQuery. Si hay registros existentes en el conjunto de datos, Cortex Framework puede actualizarlos con los datos nuevos.
  2. Vistas de asignación de estructuras: Este método es útil si ya tienes tus datos cargados en BigQuery a través de otra herramienta, pero la estructura de datos no coincide con lo que necesita Cortex Framework. Cortex Framework usa "vistas" (como tablas virtuales) para traducir la estructura de datos existente al formato que esperan las funciones de informes de Cortex Framework.

  3. Secuencias de comandos de procesamiento de CDC (captura de datos modificados): Esta opción está diseñada específicamente para datos que cambian constantemente. Las secuencias de comandos de CDC hacen un seguimiento de estos cambios y actualizan los datos en BigQuery según corresponda. Estas secuencias de comandos dependen de dos campos especiales en tus datos:

    • Id: Es el identificador único de cada registro.
    • SystemModstamp: Una marca de tiempo que indica cuándo se cambió un registro.

    Si tus datos no tienen estos nombres exactos, las secuencias de comandos se pueden ajustar para reconocerlos con nombres diferentes. También puedes agregar campos personalizados a tu esquema de datos durante este proceso. Por ejemplo, la tabla de origen con datos del objeto Account debe tener los campos Id y SystemModstamp originales. Si estos campos tienen nombres diferentes, el archivo src/SFDC/src/table_schema/accounts.csv se debe actualizar con el nombre del campo Id asignado a AccountId y cualquier campo de marca de tiempo de modificación del sistema asignado a SystemModstamp. Para obtener más información, consulta la documentación de SystemModStamp.

Si ya cargaste datos a través de otra herramienta (y se actualizan constantemente), Cortex puede usarlos. Las secuencias de comandos de CDC incluyen archivos de asignación que pueden traducir tu estructura de datos existente al formato que necesita Cortex Framework. Incluso puedes agregar campos personalizados a tus datos durante este proceso.

Configura la integración de la API y el CDC

Para transferir tus datos de Salesforce a BigQuery, puedes usar las siguientes formas:

  1. Secuencias de comandos de Cortex para llamadas a la API: Proporciona secuencias de comandos de replicación para Salesforce o una herramienta de replicación de datos de tu elección.La clave es que los datos que ingreses deben verse igual que si provinieran de las APIs de Salesforce.
  2. Herramienta de replicación y adición siempre : Si usas una herramienta para la replicación, esta opción es para una herramienta que puede agregar registros de datos nuevos (_appendalways_pattern) o actualizar registros existentes.
  3. Herramienta de replicación y agregar registros nuevos: Si la herramienta no actualiza los registros y replica los cambios como registros nuevos en una tabla objetivo (sin procesar), Cortex Data Foundation proporciona la opción de crear secuencias de comandos de procesamiento de CDC. Para obtener más información, consulta el proceso de los CDC.

Carga de trabajo de Salesforce: Opciones de integración de datos

Figura 1. Carga de trabajo de Salesforce: opciones de integración de datos.

Para asegurarte de que tus datos coincidan con lo que espera Cortex Framework, puedes ajustar la configuración de asignación para asignar tu herramienta de replicación o los esquemas existentes. Esto genera vistas de asignación compatibles con la estructura que espera Cortex Framework Data Foundation.

Usa el archivo ingestion_settings.yaml para configurar la generación de secuencias de comandos para llamar a las APIs de Salesforce y replicar los datos en el conjunto de datos sin procesar (sección salesforce_to_raw_tables) y la generación de secuencias de comandos para procesar los cambios entrantes en el conjunto de datos sin procesar y en el conjunto de datos procesado por la CDC (sección raw_to_cdc_tables).

De forma predeterminada, las secuencias de comandos proporcionadas para leer desde las APIs actualizan los cambios en el conjunto de datos sin procesar, por lo que no se requieren secuencias de comandos de procesamiento de CDC y, en su lugar, se crean vistas de asignación para alinear el esquema de origen con el esquema esperado.

La generación de secuencias de comandos de procesamiento de CDC no se ejecuta si SFDC.createMappingViews=true está en config.json (comportamiento predeterminado). Si se requieren secuencias de comandos de CDC, configura SFDC.createMappingViews=false. Este segundo paso también permite asignar los esquemas de origen a los esquemas requeridos según lo exija la base de datos de Cortex Framework.

En el siguiente ejemplo de un archivo de configuración setting.yaml, se ilustra la generación de vistas de asignación cuando una herramienta de replicación actualiza los datos directamente en el conjunto de datos replicado, como se ilustra en option 3 (es decir, no se requiere CDC, solo la reasignación de tablas y nombres de campos). Como no se requiere ningún CDC, esta opción se ejecuta siempre que el parámetro SFDC.createMappingViews en el archivo config.json permanezca como true.

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

En este ejemplo, quitar la configuración de una tabla base o de todas ellas de las secciones omite la generación de DAG de esa tabla base o de la sección completa, como se ilustra para salesforce_to_raw_tables. En esta situación, configurar el parámetro deployCDC : False tiene el mismo efecto, ya que no es necesario generar secuencias de comandos de procesamiento de CDC.

Asignación de datos

Debes asignar los campos de datos entrantes al formato que espera Cortex Data Foundation. Por ejemplo, un campo llamado unicornId de tu sistema de datos de origen debe cambiar de nombre y reconocerse como AccountId (con un tipo de datos de cadena) en Cortex Data Foundation:

  • Campo de origen: unicornId (nombre que se usa en el sistema de origen)
  • Campo de Cortex: AccountId (nombre que espera Cortex)
  • Tipo de datos: String (tipo de datos que espera Cortex)

Asignación de campos polimórficos

Data Foundation de Cortex Framework admite la asignación de campos polimórficos, que son campos cuyo nombre puede variar, pero su estructura sigue siendo coherente. Para replicar los nombres de tipos de campo polimórficos (por ejemplo, Who.Type), agrega un elemento [Field Name]_Type en los archivos CSV de asignación respectivos: src/SFDC/src/table_schema/tasks.csv. Por ejemplo, si necesitas que se replique el campo Who.Type del objeto Task, agrega la línea Who_Type,Who_Type,STRING. Esto define un campo nuevo llamado Who.Type que se asigna a sí mismo (mantiene el mismo nombre) y tiene un tipo de datos de cadena.

Cómo modificar plantillas de DAG

Es posible que debas ajustar las plantillas de DAG para CDC o para el procesamiento de datos sin procesar según lo requiera tu instancia de Airflow o Cloud Composer. Para obtener más información, consulta Cómo recopilar la configuración de Cloud Composer.

Si no necesitas la CDC ni la generación de datos sin procesar a partir de llamadas a la API, configura deployCDC=false. Como alternativa, puedes quitar el contenido de las secciones en ingestion_settings.yaml. Si se sabe que las estructuras de datos son coherentes con las que espera Cortex Framework Data Foundation, puedes omitir la generación de vistas de asignación configurando SFDC.createMappingViews=false.

Cómo configurar el módulo de extracción

En esta sección, se presentan los pasos para usar el módulo de extracción de Salesforce a BigQuery que proporciona Data Foundation. Es posible que tus requisitos y flujos varíen según el sistema y la configuración existentes. Como alternativa, puedes usar otras herramientas disponibles.

Configura las credenciales y la app conectada

Accede a tu instancia de Salesforce como administrador para completar lo siguiente:

  1. Crea o identifica un perfil en Salesforce que cumpla con los siguientes requisitos:
    1. Permission for Apex REST Services and API Enabled se otorga en Permisos del sistema.
    2. Se otorga permiso View All para todos los objetos que deseas replicar. Por ejemplo, Cuenta y Casos. Verifica si hay restricciones o problemas con tu administrador de seguridad.
    3. No se otorgaron permisos relacionados con el acceso a la interfaz de usuario, como Salesforce Anywhere en la experiencia de Lightning, Salesforce Anywhere en dispositivos móviles, usuario de la experiencia de Lightning y usuario de acceso de Lightning. Verifica si hay restricciones o problemas con tu administrador de seguridad.
  2. Crea o identifica un usuario existente en Salesforce. Debes conocer el nombre de usuario, la contraseña y el token de seguridad del usuario. Ten en cuenta lo siguiente:
    • Idealmente, debe ser un usuario dedicado a ejecutar esta replicación.
    • El usuario debe estar asignado al perfil que creaste o identificaste en el paso 1.
    • Puedes ver el Nombre de usuario y restablecer la Contraseña aquí.
    • Puedes restablecer el token de seguridad si no lo tienes y otro proceso no lo usa.
  3. Crea una app conectada. Es el único canal de comunicación para establecer una conexión con Salesforce desde el mundo externo con la ayuda del perfil, la API de Salesforce, las credenciales de usuario estándar y su token de seguridad.
    1. Sigue las instrucciones para habilitar la configuración de OAuth para la integración de la API.
    2. Asegúrate de que Require Secret for Web Server Flow y Require Secretfor Refresh Token Flow estén habilitados en la sección API (Enabled OAuth Settings).
    3. Consulta la documentación para obtener tu clave de consumidor (que más adelante se usará como tu ID de cliente). Consulta a tu administrador de seguridad si hay problemas o restricciones.
  4. Asigna tu app conectada al perfil creado.
    1. Selecciona Configuración en la parte superior derecha de la pantalla principal de Salesforce.
    2. En el cuadro Búsqueda rápida, ingresa profile y, luego, selecciona Perfil. Busca el perfil que creaste en el paso 1.
    3. Abre el perfil.
    4. Haz clic en el vínculo Apps conectadas asignadas.
    5. Haz clic en Editar.
    6. Agrega la app conectada recién creada.
    7. Haz clic en el botón Save.

Configura Secret Manager

Configura Secret Manager para almacenar los detalles de la conexión. El módulo de Salesforce a BigQuery se basa en Secret Manager para almacenar de forma segura las credenciales que necesita para conectarse a Salesforce y BigQuery. Este enfoque evita exponer información sensible, como contraseñas, directamente en el código o los archivos de configuración, lo que mejora la seguridad.

Crea un secreto con las siguientes especificaciones. Para obtener instrucciones más detalladas, consulta Crea un secreto.

  • Nombre del secreto: airflow-connections-salesforce-conn

  • Valor secreto:

    http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`

    Reemplaza lo siguiente:

    • USERNAME por tu nombre de usuario.
    • PASSWORD con tu contraseña.
    • INSTANCE_NAME por el nombre de la instancia.
    • CLIENT_ID por tu ID de cliente.
    • SECRET_TOKEN por tu token secreto.

Para obtener más información, consulta cómo encontrar el nombre de tu instancia.

Bibliotecas de Cloud Composer para la replicación

Para ejecutar las secuencias de comandos de Python en los DAG que proporciona la Fundación de datos de Cortex Framework, debes instalar algunas dependencias. Para la versión 1.10 de Airflow, sigue la documentación para instalar dependencias de Python para Cloud Composer 1 y, luego, instala los siguientes paquetes en el orden indicado:

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

Para la versión 2.x de Airflow, consulta la documentación Instalar dependencias de Python para la documentación de Cloud Composer 2 para instalar apache-airflow-providers-salesforce~=5.2.0.

Usa el siguiente comando para instalar cada paquete requerido:

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

Reemplaza lo siguiente:

  • ENVIRONMENT_NAME por el nombre del entorno asignado.
  • LOCATION con la ubicación
  • PACKAGE_NAME con el nombre del paquete elegido.
  • EXTRAS_AND_VERSION con las especificaciones de los extras y la versión.

El siguiente comando es un ejemplo de una instalación de paquete obligatoria:

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

Habilita Secret Manager como backend

Habilita Google Secret Manager como el backend de seguridad. En este paso, se te indica que actives Secret Manager como la ubicación de almacenamiento principal para la información sensible, como las contraseñas y las claves de API que usa tu entorno de Cloud Composer. Esto mejora la seguridad, ya que centraliza y administra las credenciales en un servicio dedicado. Para obtener más información, consulta Secret Manager.

Permite que la cuenta de servicio de Composer acceda a los secretos

Este paso garantiza que la cuenta de servicio asociada con Cloud Composer tenga los permisos necesarios para acceder a los secretos almacenados en Secret Manager. De forma predeterminada, Cloud Composer usa la cuenta de servicio de Compute Engine. El permiso requerido es Secret Manager Secret Accessor. Este permiso permite que la cuenta de servicio recupere y use los secretos almacenados en Secret Manager.Para obtener una guía completa sobre la configuración de controles de acceso en Secret Manager, consulta la documentación de control de acceso.

Conexión de BigQuery en Airflow

Asegúrate de crear la conexión sfdc_cdc_bq según Cómo recopilar la configuración de Cloud Composer. Es probable que el módulo de Salesforce a BigQuery use esta conexión para establecer la comunicación con BigQuery.

Próximos pasos