Esta página se ha traducido con Cloud Translation API.

Integración con Salesforce (SFDC)

En esta página se describen los pasos para integrar la carga de trabajo operativa de Salesforce (SFDC) en Data Foundation de Cortex Framework. Cortex Framework integra datos de Salesforce con las canalizaciones de Dataflow en BigQuery, mientras que Cloud Composer programa y monitoriza estas canalizaciones de Dataflow para obtener estadísticas a partir de tus datos.

Archivo de configuración

El archivo config.json del repositorio de la infraestructura de datos de Cortex Framework configura los ajustes necesarios para transferir datos desde cualquier fuente de datos, incluida 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`	Implementar CDC	`true`	Genera secuencias de comandos de procesamiento de CDC para ejecutarlas como DAGs en Cloud Composer. Consulta la documentación sobre las diferentes opciones de ingesta de datos de Salesforce Sales Cloud.
`SFDC.createMappingViews`	Crear vistas de asignación	`true`	Los DAGs proporcionados para obtener nuevos registros de las APIs de Salesforce actualizan los registros en la página de destino. Si este valor es true, se generan vistas en el conjunto de datos procesado de CDC para exponer tablas con la "versión más reciente de la verdad" del conjunto de datos sin procesar. Si es false y `SFDC.deployCDC` es `true`, se generan DAGs con procesamiento de captura de datos de cambios (CDC) basado en SystemModstamp. Consulta los detalles sobre el procesamiento de CDC para Salesforce.
`SFDC.createPlaceholders`	Crear marcadores de posición	`true`	Crea tablas de marcador de posición vacías por si el proceso de ingestión no las genera para que la implementación de informes posteriores se ejecute sin errores.
`SFDC.datasets.raw`	Conjunto de datos de landing sin procesar	-	El proceso de CDC usa este espacio para que la herramienta de replicación coloque los datos de Salesforce. Si usas datos de prueba, crea un conjunto de datos vacío.
`SFDC.datasets.cdc`	Conjunto de datos procesados por el CDC	-	Conjunto de datos que funciona como fuente de las vistas de informes y como destino de los DAGs procesados. Si usas datos de prueba, crea un conjunto de datos vacío.
`SFDC.datasets.reporting`	Conjunto de datos de informes de Salesforce	`"REPORTING_SFDC"`	Nombre del conjunto de datos al que pueden acceder los usuarios finales para generar informes, donde se implementan las vistas y las tablas visibles para los usuarios.
`SFDC.currencies`	Filtrar monedas	`[ "USD" ]`	Si no utiliza datos de prueba, introduzca una sola moneda (por ejemplo, `[ "USD" ]`) o varias (por ejemplo,`[ "USD", "CAD" ]`) según corresponda a su empresa. Estos valores se usan para sustituir marcadores de posición en SQL en los modelos de analíticas cuando están disponibles.

Modelo de datos

En esta sección se describe el modelo de datos de Salesforce (SFDC) mediante el diagrama de relaciones entre entidades (DER).

Imagen 2. Salesforce (SFDC): diagrama de relaciones entre entidades.

Vistas básicas

Son los objetos azules del diagrama ER y son vistas de tablas de CDC sin transformaciones, salvo algunos alias de nombres de columna. Consulta las secuencias de comandos en src/SFDC/src/reporting/ddls.

Vistas de informes

Son los objetos verdes del diagrama ER y contienen los atributos de dimensión relevantes que usan las tablas de informes. Consulta las secuencias de comandos en src/SFDC/src/reporting/ddls.

Requisitos de los datos de Salesforce

En esta sección se explica cómo deben estructurarse los 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 conservan los mismos tipos de datos que se representan en Salesforce.
- Legibilidad: es posible que se modifiquen ligeramente algunos nombres de campos para que sean más claros en la capa de informes.
Tablas vacías e implementación: las tablas obligatorias que falten en el conjunto de datos sin procesar se crearán automáticamente como tablas vacías durante el proceso de implementación. De esta forma, se asegura que el paso de implementación de CDC se ejecute correctamente.
Requisitos de la CDC: los campos Id y SystemModstamp son fundamentales para que las secuencias de comandos de la CDC monitoricen los cambios en tus datos. Pueden tener estos nombres exactos u otros diferentes. Las secuencias de comandos de procesamiento sin formato proporcionadas obtienen estos campos automáticamente de las APIs y actualizan la tabla de replicación de destino.
- Id: actúa como identificador único de 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 formato: las secuencias de comandos de procesamiento sin formato proporcionadas no requieren procesamiento adicional (CDC). Este comportamiento se define de forma predeterminada durante la implementación.

Tablas de origen de la conversión de moneda

Salesforce te permite gestionar las monedas de dos formas:

Básico: es el valor predeterminado, en el que todos los datos usan una sola moneda.
Avanzado: convierte entre varias monedas en función de los tipos de cambio (para ello, debes habilitar Gestión avanzada de monedas).

Si usas Gestión de divisas avanzada, Salesforce utiliza dos tablas especiales:

CurrencyTypes esta tabla almacena información sobre las diferentes monedas que utiliza (por ejemplo, USD, EUR, etc.).
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 gestión avanzada de monedas. Si no usas la gestión avanzada de monedas, puedes eliminar las entradas relacionadas con estas tablas de un archivo de configuración (src/SFDC/config/ingestion_settings.yaml). Este paso evita que se intente extraer datos de tablas que no existen.

Cargar 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 Salesforce Bulk API 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 artículo sobre el módulo de extracción de SFDC.

Cortex Framework también ofrece tres métodos diferentes para integrar tus datos, en función de su procedencia y de cómo se gestionen:

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, obtener los datos y almacenarlos en un conjunto de datos "Raw" en BigQuery. Si hay registros en el conjunto de datos, Cortex Framework puede actualizarlos con los nuevos datos.
Vistas de asignación de estructura: este método es útil si ya has cargado tus datos en BigQuery a través de otra herramienta, pero la estructura de los datos no coincide con lo que necesita Cortex Framework. Cortex Framework usa "vistas" (como tablas virtuales) para traducir la estructura de datos actual al formato que esperan las funciones de informes de Cortex Framework.
Scripts de procesamiento de CDC (captura de datos de cambios): esta opción se ha diseñado específicamente para datos que cambian constantemente. Las secuencias de comandos de CDC monitorizan estos cambios y actualizan los datos de BigQuery en consecuencia. Estas secuencias de comandos se basan en dos campos especiales de tus datos:
- Id: identificador único de cada registro.
- SystemModstamp: una marca de tiempo que indica cuándo se modificó un registro.
Si sus datos no tienen estos nombres exactos, las secuencias de comandos se pueden ajustar para reconocerlos con nombres diferentes. También puede añadir campos personalizados a su 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 debe actualizarse con el nombre del campo Id asignado a AccountId y el 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 has cargado datos a través de otra herramienta (y se actualizan constantemente), Cortex puede seguir usándolos. Los scripts de CDC incluyen archivos de asignación que pueden traducir tu estructura de datos actual al formato que necesita Cortex Framework. Incluso puedes añadir campos personalizados a tus datos durante este proceso.

Configurar la integración de APIs y CDC

Para incorporar tus datos de Salesforce a BigQuery, puedes usar los siguientes métodos:

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.Lo importante es que los datos que importes tengan el mismo aspecto que si procedieran de las APIs de Salesforce.
Herramienta de replicación y añadir siempre : si utilizas una herramienta de replicación, esta opción es para una herramienta que puede añadir registros de datos nuevos (_appendalways_pattern) o actualizar registros.
Herramienta de replicación y adición de registros nuevos: si la herramienta no actualiza los registros y replica los cambios como registros nuevos en una tabla de destino (sin procesar), Cortex Data Foundation ofrece 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

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

Para asegurarse de que sus datos coincidan con lo que espera Cortex Framework, puede ajustar la configuración de la asignación para asignar su herramienta de replicación o sus esquemas. De esta forma, se generan 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 que llamen a las APIs de Salesforce y repliquen los datos en el conjunto de datos sin procesar (sección salesforce_to_raw_tables) y la generación de secuencias de comandos que procesen los cambios que se produzcan en el conjunto de datos sin procesar y en el conjunto de datos procesado de CDC (sección raw_to_cdc_tables).

De forma predeterminada, las secuencias de comandos proporcionadas para leer datos de las APIs actualizan los cambios en el conjunto de datos sin procesar, por lo que no se necesitan secuencias de comandos de procesamiento de CDC. 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 en config.json (comportamiento predeterminado). Si se necesitan secuencias de comandos de CDC, define SFDC.createMappingViews=false. Este segundo paso también permite asignar los esquemas de origen a los esquemas necesarios, tal como requiere la infraestructura de datos de Cortex Framework.

En el siguiente ejemplo de un archivo de configuración setting.yaml se muestra la generación de vistas de asignación cuando una herramienta de replicación actualiza los datos directamente en el conjunto de datos replicado, tal como se ilustra en option 3 (es decir, no se requiere CDC, solo se deben reasignar las tablas y los nombres de los campos). Como no se requiere ningún CDC, esta opción se ejecuta siempre que el parámetro SFDC.createMappingViews del archivo config.json siga siendo 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, si se elimina la configuración de una tabla base o de todas ellas de las secciones, se omite la generación de DAGs de esa tabla base o de toda la sección, como se muestra en salesforce_to_raw_tables. En este caso, definir 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 usado en el sistema de origen)
Campo de Cortex: AccountId (nombre esperado por Cortex)
Tipo de datos: String (tipo de datos que espera Cortex)

Asignar campos polimórficos

La base de datos de Cortex Framework admite la asignación de campos polimórficos, que son campos cuyo nombre puede variar, pero su estructura sigue siendo coherente. Los nombres de los tipos de campos polimórficos (por ejemplo, Who.Type) se pueden replicar añadiendo un elemento [Field Name]_Type en los archivos CSV de asignación correspondientes: src/SFDC/src/table_schema/tasks.csv. Por ejemplo, si necesita que se replique el campo Who.Type del objeto Task, añada la línea Who_Type,Who_Type,STRING. De esta forma, se define un nuevo campo llamado Who.Type que se asigna a sí mismo (conserva el mismo nombre) y tiene el tipo de datos de cadena.

Modificar plantillas de DAG

Es posible que tengas que 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 Recoger la configuración de Cloud Composer.

Si no necesitas CDC ni generar datos sin procesar a partir de llamadas a la API, define deployCDC=false. También puedes eliminar 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, puede omitir la generación de vistas de asignación configurando SFDC.createMappingViews=false.

Configurar el módulo de extracción

En esta sección se describen los pasos para usar el módulo de extracción de Salesforce a BigQuery proporcionado por Data Foundation. Los requisitos y el flujo pueden variar en función de tu sistema y de la configuración que tengas. También puedes usar otras herramientas disponibles.

Configurar credenciales y aplicaciones conectadas

Inicia sesión como administrador en tu instancia de Salesforce para completar lo siguiente:

Crea o identifica un perfil en Salesforce que cumpla los siguientes requisitos:
1. Permission for Apex REST Services and API Enabled se concede en Permisos del sistema.
2. Se concede el permiso View All para todos los objetos que quieras replicar. Por ejemplo, Cuenta y Casos. Consulta si hay restricciones o problemas con tu administrador de seguridad.
3. No se han concedido permisos relacionados con el inicio de sesión en la interfaz de usuario, como Salesforce Anywhere en Lightning Experience, Salesforce Anywhere en móviles, Usuario de Lightning Experience y Usuario de inicio de sesión de Lightning. Comprueba si hay restricciones o problemas con tu administrador de seguridad.
Crea o identifica un usuario en Salesforce. Necesitas saber el nombre de usuario, la contraseña y el token de seguridad del usuario. Ten en cuenta lo siguiente:
- Lo ideal es que sea un usuario dedicado a ejecutar esta replicación.
- El usuario debe asignarse al perfil que has creado o identificado en el paso 1.
- Aquí puedes ver el Nombre de usuario y cambiar la Contraseña.
- Puedes restablecer el token de seguridad si no lo tienes y no lo usa otro proceso.
Crea una aplicación conectada. Es el único canal de comunicación para establecer una conexión con Salesforce desde el mundo externo con la ayuda de un perfil, la API de Salesforce, las credenciales de usuario estándar y su token de seguridad.
1. Sigue las instrucciones para habilitar los ajustes de OAuth para la integración de APIs.
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 sobre cómo obtener tu clave de consumidor (que se usará más adelante como tu ID de cliente). Ponte en contacto con el administrador de seguridad para comprobar si hay problemas o restricciones.
Asigna tu aplicación conectada al perfil creado.
1. Selecciona Configuración en la parte superior derecha de la pantalla de inicio de Salesforce.
2. En el cuadro Búsqueda rápida, introduce profile y, a continuación, selecciona Perfil. Busca el perfil que has creado en el paso 1.
3. Abre el perfil.
4. Haz clic en el enlace Aplicaciones conectadas asignadas.
5. Haz clic en Editar.
6. Añade la aplicación conectada que acabas de crear.
7. Haz clic en el botón Save (Guardar).

Configurar Secret Manager

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

Crea un secreto con las siguientes especificaciones. Para obtener más información, consulta el artículo Crear un secreto.

Nombre del secreto: airflow-connections-salesforce-conn
Valor del secreto:
```
http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`
```
Haz los cambios siguientes:
- USERNAME con tu nombre de usuario.
- PASSWORD con tu contraseña.
- INSTANCE_NAME con el nombre de la instancia.
- CLIENT_ID con tu ID de cliente.
- SECRET_TOKEN con 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 DAGs proporcionados por la infraestructura de datos de Cortex Framework, debes instalar algunas dependencias. En Airflow 1.10, sigue las instrucciones de la documentación sobre cómo instalar dependencias de Python en Cloud Composer 1 para instalar los siguientes paquetes en este orden:

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

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

Usa el siguiente comando para instalar cada paquete necesario:

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

Haz los cambios siguientes:

ENVIRONMENT_NAME con el nombre de 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 instalación de un paquete obligatorio:

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

Habilitar Secret Manager como backend

Habilita Secret Manager de Google como backend de seguridad. En este paso se indica cómo activar Secret Manager como ubicación de almacenamiento principal de información sensible, como contraseñas y claves de API, que usa tu entorno de Cloud Composer. De esta forma, se mejora la seguridad al centralizar y gestionar las credenciales en un servicio específico. Para obtener más información, consulta Secret Manager.

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

Con este paso, te aseguras de que la cuenta de servicio asociada a 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 necesario es Secret Manager Secret Accessor. Este permiso permite que la cuenta de servicio recupere y use los secretos almacenados en Secret Manager.Para consultar una guía completa sobre cómo configurar los controles de acceso en Secret Manager, consulta la documentación sobre el control de acceso.

Conexión de BigQuery en Airflow

Asegúrate de crear la conexión sfdc_cdc_bq siguiendo las instrucciones de la sección Recopilar ajustes de Cloud Composer. Es probable que el módulo de Salesforce a BigQuery use esta conexión para establecer la comunicación con BigQuery.

Siguientes pasos

Para obtener más información sobre otras fuentes de datos y cargas de trabajo, consulta el artículo Fuentes de datos y cargas de trabajo.
Para obtener más información sobre los pasos para la implementación en entornos de producción, consulta los requisitos previos para la implementación de Data Foundation de Cortex Framework.