Activador de Salesforce

Anuncio: Ahora la integración de aplicaciones está disponible para tu proyecto de Google Cloud. Ahora puedes usar la integración de Apigee y la integración de aplicaciones dentro del mismo proyecto de Google Cloud. Más información

El activador de Salesforce te permite escuchar eventos de captura de datos modificados (CDC) o de plataforma de mensajería empresarial. Mediante este activador, puedes iniciar la integración en función de cualquiera de los eventos de CDC (Crear, Actualizar, Borrar o Recuperar) o los eventos de plataforma en tu instancia de Salesforce.

Antes de comenzar

En esta sección, se describen los pasos necesarios para conectar y configurar una instancia de Salesforce a fin de usar los eventos de Captura de datos modificados (CDC) o Platform para transmitir los cambios a tu Integración de Apigee en forma de Pub/Sub. Los siguientes pasos deben completarse antes de configurar cualquier tarea o activador relacionado con Salesforce en Apigee:

• Configura un usuario de integración
• Configura un conjunto de permisos
• Configura un token de seguridad
• Crea una app conectada

Nota: Para completar estos pasos, se requiere acceso de administrador del sistema a tu instancia de Salesforce. Si no tienes acceso de administración, comparte estas instrucciones con tu administrador de Salesforce.

En este instructivo, se proporcionan instrucciones detalladas, pero te recomendamos que conozcas las opciones de configuración de Salesforce. Salesforce proporciona documentación detallada para desarrolladores que te ayudará a comenzar.

Configura un usuario de integración

Nota: Si ya tienes un usuario de integración y conoces la contraseña, puedes pasar al siguiente paso. Si necesitas restablecer la contraseña, consulta el Paso 6 que figura a continuación.

Para configurar un usuario de integración, sigue estos pasos:

1. Accede a la instancia de Salesforce con tus credenciales de sysadmin.
2. Haz clic en el ícono de ajustes y selecciona Setup, como se muestra en la siguiente imagen:
3. Haz clic en Users > Users en el menú de administración.
4. En el panel Users, selecciona el botón New User.
5. En el cuadro de diálogo User Edit, completa los siguientes detalles:
   1. First Name: el nombre del usuario de integración.
   2. Last Name: el apellido del usuario de integración.
   3. Email Address: el correo electrónico del usuario de integración. Lo ideal es que debería ser un correo electrónico de grupo.
   4. Username: el nombre de usuario que cumple con las convenciones de nombres a nivel de la organización.

      Si creas un usuario de integración nuevo, usa el siguiente formato: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Si tienes un usuario de integración existente, confirma que el nombre de usuario se ingrese aquí.

   5. Role: selecciona una de las opciones del menú desplegable.
   6. User License: ingresa Salesforce o, si usas una organización de prueba, ingresa Salesforce Platform.
   7. Profile: selecciona el perfil de permisos para los usuarios de integración en el menú desplegable.

      Recomendamos asignar un perfil sin permisos para proteger el acceso de Salesforce del usuario de integración contra el uso no autorizado.

   8. Haz clic en Guardar.
6. Para actualizar la contraseña del usuario de integración nuevo, sigue estos pasos:
   1. Haz clic en el botón Reset password(s) en el panel Users. Se envía un correo electrónico de restablecimiento de contraseña a la dirección de correo electrónico asociada con el usuario.
      Nota: Confirma que tienes acceso a la cuenta de correo electrónico asociada con el usuario de la integración antes de activar el flujo de restablecimiento de contraseña. Además, si tienes habilitado SSO para este usuario, no podrás restablecer la contraseña. Para habilitar la opción de restablecimiento, ve a Profile > System Permissions y desmarca la opción SSO Login Enabled.
   2. Sigue el flujo de restablecimiento de contraseña desde la cuenta de correo electrónico. Toma nota de la contraseña nueva, ya que la necesitarás para un paso posterior.

Configura un conjunto de permisos

Si ya tienes acceso a un conjunto de permisos que es apropiado para un usuario de integración, puedes omitir este paso y continuar con Configura un token de seguridad. De lo contrario, sigue estos pasos a fin de configurar un conjunto de permisos para el usuario de integración y el objeto de Salesforce.

Si deseas configurar un conjunto de permisos para el usuario de integración, haz lo siguiente:

1. En el menú Setup, haz clic en Users > Permission Sets.
2. En el panel Permission Sets, haz clic en el botón New.
3. En el cuadro de diálogo Permission Sets, ingresa los siguientes detalles:
   • Label: ingresa un nombre para el conjunto de permisos.
   • License: selecciona Salesforce en el menú desplegable License.
   • Haz clic en Guardar.
4. En la lista de opciones de configuración de System, desplázate hacia abajo y selecciona System Permissions.
5. En la página System Permissions, haz clic en el botón Edit.
6. Desplázate hacia abajo en la lista de permisos disponibles y selecciona la casilla de verificación API Enabled.

   También se requiere el permiso Solo usuario de API, pero no se puede habilitar hasta que se restablezca el token de seguridad requerido. Este permiso se agrega en un paso posterior.

7. (Opcional) Desplázate y selecciona Modify All Data y View All Data, si corresponde. Estos permisos no son obligatorios, pero pueden ser útiles si quieres otorgar automáticamente al usuario de integración acceso a objetos nuevos. Recomendamos habilitar estos permisos solo para realizar pruebas en una zona de pruebas.
8. Desplázate hasta la parte superior de la lista de permisos y haz clic en Save.
9. Confirma la configuración y haz clic en Save.

Para configurar el conjunto de permisos para el objeto de Salesforce, haz lo siguiente:

1. Haz clic en Permission Set Overview para volver a la página de configuración principal Permissions Set.
2. Selecciona Object Settings en la sección Apps del panel Permissions Set.
3. Desplázate hacia abajo y selecciona los objetos de Salesforce que requieran un conjunto de permisos. En este ejemplo, se usa el objeto Opportunity.
   NOTA: Los CDC solo admiten un subconjunto de objetos estándares de Salesforce. Para obtener más información, consulta Cambia la compatibilidad con objetos de eventos.
4. Haz clic en el botón Edit en la página de detalles del objeto.
5. Selecciona las casillas de verificación para los tipos de registros. Si sabes qué tipos de registros son obligatorios, selecciónalos. Si no sabes qué tipos de registros son obligatorios, selecciónalos todos.
6. Selecciona las casillas de verificación de los Permisos de objetos que deseas habilitar. Se recomiendan las opciones Read y Ver todo.
7. Para otorgar Acceso de lectura o Acceso de edición a cada campo de objeto, selecciona la casilla de verificación correspondiente.
   Nota: No se requiere acceso de escritura para su uso con CDC.
8. Desplázate hasta el final de la página y haz clic en Guardar.

Configura un token de seguridad

Si ya creaste un token de seguridad para el usuario de integración y restableces la contraseña, se enviará de forma automática un correo electrónico con un token de seguridad nuevo. Puedes usar el token nuevo y pasar a Crea una app conectada.

De lo contrario, sigue estos pasos a fin de restablecer el token de seguridad para el usuario de integración:

1. Accede a Salesforce como el usuario de integración mediante el nombre de usuario y la contraseña configurados en un paso anterior.
2. En el menú principal, haz clic en la foto de perfil y, luego, en Settings.
3. En el menú Settings, selecciona Reset My Security Token para abrir el panel Reset Security Token.
4. Haz clic en el botón Reset Security Token.
5. Busca un correo electrónico que contenga el token de seguridad nuevo en la cuenta de correo electrónico asociada con el usuario de integración. Toma nota del token de seguridad nuevo, ya que lo necesitará para un paso posterior.
6. (Opcional) Habilita el permiso Solo usuario de API en System Permissions para tu conjunto de permisos, como se describió con anterioridad en Configura un conjunto de permisos.

Crea una app conectada

Se requiere el permiso de administración del sistema para configurar una app conectada. Si actualmente has iniciado sesión como usuarios de integración, asegúrate de salir y volver a acceder como sysadmin.

Sigue estos pasos para configurar una app conectada:

1. Haz clic en el ícono de ajustes y selecciona Setup.
2. En el menú Setup, busca y selecciona App Manager, como se muestra en la siguiente imagen:
3. Haz clic en Nueva app conectada.
4. En el panel de configuración, proporciona los siguientes detalles:
   • Connected App Name: ingresa un nombre para la aplicación conectada.
   • API Name: ingresa el nombre de la API.
   • Contact email: ingresa un correo electrónico para la app conectada. Lo ideal sería un alias de correo electrónico de grupo.
   • API (Enable OAuth Settings): selecciona Enable OAuth Settings. Luego, configura lo siguiente:
     1. (Opcional) Callback URL: esto solo es necesario si quieres que un servicio externo realice la validación. Si decides proporcionar una devolución de llamada, asegúrate de incluir el prefijo http(s)://.
     2. Selected OAuth Scopes: selecciona:
        • Acceder y administrar datos (API)
        • Realizar solicitudes en tu nombre en cualquier momento (refresh_token, offline_access)
5. Haz clic en Guardar.
   Nota: La app conectada que se creó recientemente no funcionará durante los primeros 2 a 10 minutos después de la creación.
6. Haz clic en Continuar. Debes volver a autorizarla con un código de verificación que se enviará a tu dirección de correo electrónico.
7. Después de verificar el código correctamente, se muestran un secreto de consumidor y una clave de consumidor en la página siguiente. Toma nota de estos valores, ya que se usarán cuando se configure el módulo de Auth para Apigee.
8. Haz clic en el botón Administrar.
9. En la página Connected App Detail, haz clic en el botón Edit Policies.
10. En la sección OAuth Policies, cambia el valor del menú desplegable Permitted Users a Admin approved users are pre-authorized.
11. Haz clic en Guardar.
12. Desplázate hasta la sección Profiles y Permission Sets de la página para seleccionar el perfil o el conjunto de permisos que deseas aplicar a la app conectada.
    Puedes seleccionar un perfil, un conjunto de permisos o una combinación de ambos, lo que permitirá que los usuarios con el perfil o el conjunto de permisos correctos accedan a la app conectada.
13. Selecciona el perfil o el conjunto de permisos deseados.
14. Haz clic en Guardar.

Pasos previos para usar eventos de los CDC

Antes de configurar tu activador de Apigee para que use eventos de CDC, asegúrate de agregar un objeto configurado a los CDC en Salesforce:

1. Accede a Salesforce como sysadmin.
2. Haz clic en el ícono de ajustes y, luego, en Configuración.
3. Con el panel de navegación izquierdo, busca y selecciona Change Data Capture.
4. En la página de configuración captura de datos modificados, busca el objeto de Salesforce que deseas usar en la columna Available Entities y arrástralo a la columna Selected Entities.
   Nota: Se puede seleccionar un máximo de 5 objetos por licencia de Salesforce para los CDC. Comunícate con tu representante de Salesforce para obtener más información y opciones de licencias.
5. Haz clic en Guardar.

Pasos previos para usar eventos de Plataforma

Antes de configurar el activador de Apigee para que use eventos de Plataforma, completa los siguientes pasos en Salesforce:

• Crea un evento de plataforma
• Actualiza los permisos del evento de plataforma

Crea un evento de Plataforma

Para crear un evento de Plataforma, sigue estos pasos:

1. Accede a la instancia de Salesforce con tus credenciales de sysadmin.
2. Haz clic en el ícono de ajustes y selecciona Setup.
3. En el panel de navegación, busca Plataforma y, luego, haz clic en Eventos de Plataforma.

4. En la página Eventos de Plataforma, haz clic en Evento de Plataforma nuevo y configura las siguientes propiedades:

• Etiqueta
• Plural Label
• Object Name(Este campo se propaga automáticamente)
• Publish Behavior Selecciona cualquiera de los siguientes valores:
  • Publish After Commit: anula la transmisión de eventos si no se cumple una condición.
  • Publish Immediately: activa el evento de inmediato, sin esperar ninguna validación.
  Para obtener más información sobre el comportamiento de publicación, consulta Eventos y transacciones de plataforma.
• Deployment Status: selecciona Deployed si el evento está listo para la implementación (opcional).

Haz clic en Guardar.

Crea campos personalizados. Para crear los campos personalizados, haz clic en New en la sección Campos personalizados y relaciones y selecciona el tipo de campo personalizado. Puedes crear tantos campos personalizados como sea necesario.

Después de crear los campos personalizados, en la página Eventos de Plataforma, observa el valor del campo Nombre de API. El nombre del objeto termina en _e, lo que significa que es un objeto de evento de plataforma. Para un objeto CDC, el nombre del objeto termina con _c.

Actualiza los permisos del evento de plataforma

El conjunto de permisos debe actualizarse para permitir que el usuario acceda al evento de plataforma recién creado.

Para actualizar los permisos, sigue estos pasos:

1. En el menú Setup, haz clic en Users > Permission Sets.
2. En la página Permission Sets, haz clic en el permiso que creaste antes.
3. Haz clic en Object Settings > Plural Label of the Platform Event.
4. En la sección Object Permissions, habilita los permisos de lectura y creación.
5. Haz clic en Guardar.

Agrega un activador de Salesforce

Para agregar un activador de Salesforce a una integración nueva o existente, sigue los pasos que se indican a continuación:

1. En la IU de Apigee, selecciona tu organización de Apigee.
2. Haz clic en Desarrollar > Integraciones.
3. Elige una integración existente o crea una nueva haciendo clic en Crear integración.

   Si creas una integración nueva, haz lo siguiente:

   1. Escribe un nombre y una descripción en el diálogo Crear integración.
   2. En la lista de regiones compatibles, elige Región para la integración.
   3. Haz clic en Crear.

   Esto abrirá la integración en la página del diseñador de integración.

4. En la barra de navegación Diseñador de integración, haz clic en +Agregar una tarea o un activador > Tareas para ver la lista de tareas disponibles.
5. Selecciona una integración existente o haz clic en Crear integración.
6. En el editor de integración, haz clic en + Add a task/trigger > Triggers para ver los activadores disponibles
7. Haz clic en el elemento Salesforce Trigger y arrástralo al diseñador.

Configura el activador de Salesforce

Para configurar el activador de Salesforce, sigue estos pasos:

1. Haz clic en Salesforce Trigger en el editor de integración para ver el panel de configuración del activador.
2. Selecciona una instancia de Salesforce en el menú desplegable Salesforce instance configuration.

   Si no tienes una instancia de Salesforce, crea una nueva. Para obtener más información, consulta Crea una instancia nueva de Salesforce.

3. Selecciona un canal de Salesforce en el menú desplegable Salesforce channel configuration.

   Si no tienes un canal de Salesforce, crea uno nuevo. Para obtener más información, consulta Crea un canal nuevo de Salesforce.

4. Si elegiste el tipo de evento como CDC, selecciona cualquiera de las siguientes operaciones:
   • Create
   • Update
   • Delete
   • Undelete

   El activador se ejecuta solo si la operación específica o la operación de intervalo se producen.

   El activador de Salesforce se puede configurar para una sola operación. Si deseas ejecutar el activador para varias operaciones, crea un activador de Salesforce para cada operación.

Crea una instancia nueva de Salesforce

Para configurar una nueva instancia de Salesforce, realiza los siguientes pasos:

1. En las propiedades editables del activador, haz clic en Seleccionar una configuración de instancia de Salesforce > + Agregar nueva configuración de instancia de Salesforce.
2. En el cuadro de diálogo Agregar configuración de instancia de Salesforce, configura las siguientes propiedades:
• Salesforce instance connection name: ingresa un nombre para la instancia.

  Después de la configuración, usarás este nombre para hacer referencia a la instancia de Salesforce.

• Dominio de Salesforce: Ingresa una autoridad de servicio para la instancia. Puedes encontrar el dominio en tu cuenta de Salesforce. Por ejemplo, instance.my.salesforce.com. En la siguiente imagen, se muestra el dominio de Salesforce:

  

• Perfil de autenticación: Selecciona un perfil de autenticación.

  Si no tienes un perfil de autenticación, crea un perfil nuevo del tipo de autenticación Credenciales de contraseña del propietario de recursos de OAuth 2.0. En la siguiente imagen, se muestran los campos necesarios para crear un perfil de autenticación:

  

  Para obtener información sobre los campos, consulta Credenciales de la contraseña del propietario de recursos de OAuth 2.0. Para la instancia de Salesforce, ingresa los siguientes valores:
  • ID de cliente: Ingresa la clave de consumidor que anotaste cuando configuraste una app conectada.
  • Secreto: Ingresa el secreto del consumidor que anotaste cuando configuraste una app conectada.
  • Contraseña: Ingresa la contraseña del usuario con el formato USER_PASSWORDSECURITY_TOKEN. Reemplaza lo siguiente:
    • USER_PASSWORD: la contraseña de usuario de Salesforce.
    • SECURITY_TOKEN: el token de seguridad que estableciste para la integración.
    Por ejemplo, si tu USER_PASSWORD es test-password y SECURITY_TOKEN es 737K27NCa3O6, tu contraseña será test-password737K27NCa3O6.

ID de organización de Salesforce: Ingresa el ID de la organización de la instancia de Salesforce. Puedes obtener el ID de tu administrador de Salesforce.

Haga clic en Add.

Crea un canal nuevo de Salesforce

Para configurar un nuevo canal de Salesforce, realiza los siguientes pasos:

1. En las propiedades editables del activador, haz clic en Seleccionar una configuración de canal de Salesforce > + Agregar nueva configuración de canal de Salesforce.
2. En el cuadro de diálogo Agregar configuración de canal de Salesforce, ingresa el nombre del objeto para la propiedad Nombre del objeto de Salesforce.

   Si no estás seguro del nombre del objeto, comunícate con el administrador de Salesforce.

3. Haga clic en Add.

Variables de salida

La respuesta del activador de Salesforce está disponible en las variables de salida.

En la siguiente tabla, se describen las variables de salida para un evento de CDC:

Variable	Tipo de datos	Description
SalesforceTriggerCdcPayload	JSON	Detalles del evento de cambio.
SalesforceTriggerEvent	JSON	Contiene replayId del evento.
SalesforceTriggerSchema	String	Esquema del activador.
SalesforceTriggerCdcSnapshot	JSON	Una instantánea del objeto después del evento de cambio. Este campo solo está disponible para operaciones Update y Create.
SalesforceTriggerCdcRecordId	String	Contiene el recordId del registro actualizado o agregado. El recordId es un identificador del objeto de Salesforce modificado.

Las variables de salida para un evento de plataforma se describen en la siguiente tabla:

Variable	Tipo de datos	Description
SalesforceTriggerPEPayload	JSON	Detalles del evento de cambio.
SalesforceTriggerEvent	JSON	Contiene replayId del evento.
SalesforceTriggerSchema	String	Esquema del activador.

El parámetro de salida para este activador es la variable JSON CdcTriggerPayload. La variable JSON contiene objetos de registro actualizados.

Prácticas recomendadas

Se recomienda usar el activador de Salesforce en los casos en los que desees usar notificaciones de Salesforce para activar integraciones sin escribir código personalizado a fin de publicar eventos de Salesforce. Cada pequeño cambio de campo en tu caso de Salesforce activará un evento de CDC de Salesforce, lo que activará una integración, que puede provocar un ruido de integración significativo. Evalúa usar Cambiar filtros de eventos para filtrar solo los eventos de CDC necesarios que activan la integración. El uso de Cambiar filtros de evento puede ayudar a reducir el ruido de integración y garantizar el cumplimiento de las limitaciones de las licencias.

Del mismo modo, te recomendamos anular la publicación de cualquier integración con este activador cuando ya no sea necesaria. Hasta que no se publique o se borre, la integración continuará escuchando los CDC de Salesforce y los eventos de la Plataforma.

Consideraciones

Antes de usar el activador de Salesforce para ejecutar tu integración, considera lo siguiente:

• Por lo general, Salesforce envía un máximo de 100,000 eventos de CDC y plataforma por día. Habla con tu administrador de Salesforce para conocer las restricciones de licencias antes de elegir los eventos de CDC para el activador de integración.
  Nota: Varias integraciones que usan el mismo canal de Salesforce no duplicarán el consumo de la cuota de Salesforce.
• Si planeas subir cargas masivas a Salesforce, considera pausar los CDC para reducir el ruido de integración y garantizar el cumplimiento de las limitaciones de licencia.
• El tamaño máximo de mensaje de evento que Salesforce puede publicar es de 1 MB. Para obtener más información, consulta Asignaciones de capturas de datos modificados.
• Apigee no admite eventos de los CDC de Salesforce para las siguientes regiones de miniclúster:
  • asia-northeast1
  • asia-south1
  • australia-southeast1
  • europe-west2
  • europe-west3
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-east4
  • us-west2