Suscribirse a eventos de plataforma

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

• Describir cómo suscribirse a mensajes de eventos de plataforma.
  
• Suscribirse a un evento en la plataforma y en aplicaciones externas.
  
• Probar eventos de plataforma en un método de prueba de Apex.
  

Nota

¿Es su idioma de aprendizaje español (LATAM)? Comience el reto en un Trailhead Playground en español (LATAM) y copie y pegue los valores en español (LATAM). Si no aprueba el reto en su organización en español (LATAM), recomendamos que (1) cambie la configuración local a Estados Unidos, (2) cambie el idioma a inglés (según estas instrucciones) y, luego, (3) haga clic en el botón “Check Challenge” (Comprobar el reto) nuevamente.

Consulte la insignia Trailhead en su idioma para obtener más información sobre cómo aprovechar la experiencia de Trailhead en otros idiomas.

Suscribirse a eventos de plataforma

Ahora que ya sabe cómo se publican los eventos de plataforma, ¿cómo se suscribiría a estos eventos para recibir notificaciones de las últimas noticias o del envío de un paquete? En Salesforce Platform, se suscribe a eventos usando los desencadenadores de Apex, los procesos, los flujos y el componente Lightning empApi. En una aplicación externa, se suscribe a eventos mediante el modelo de publicación y suscripción de la API.

Suscribirse a notificaciones de eventos de plataforma con desencadenadores de Apex

Es probable que ya haya usado desencadenadores de Apex para realizar acciones basadas en eventos de base de datos. En el caso de los eventos de plataforma, el proceso es similar. Solo tiene que escribir un desencadenador de Apex posterior a la inserción (“after insert”) en el objeto de evento correspondiente para suscribirse a eventos entrantes. Los desencadenadores proporcionan un mecanismo de suscripción automática en Apex. No es necesario crear de forma explícita ni escuchar un canal. Los desencadenadores reciben notificaciones de eventos de varias fuentes con independencia de que se hayan publicado mediante Apex o las API.

Los eventos de plataforma solo son compatibles con desencadenadores posteriores a la inserción. El evento de desencadenador posterior a la inserción se corresponde con el momento posterior a la publicación de un evento de plataforma. Una vez publicado un mensaje de evento, se activa el desencadenador posterior a la inserción.

Para crear un desencadenador de evento de plataforma, use Developer Console.

1. Desde el menú de acceso rápido ( ), haga clic en Developer Console y, luego, en File (Archivo) | New (Nuevo) | Apex Trigger (Desencadenador de Apex).
   
2. Asigne un nombre, seleccione el evento para el sObject y haga clic en Submit (Enviar).
   

Developer Console agrega automáticamente el evento after insert a la plantilla del desencadenador. Además, puede crear fácilmente un desencadenador en la página de definición del evento mediante Configuración y la lista relacionada Desencadenadores, pero debe especificar el término clave after insert.

En el siguiente ejemplo se muestra un desencadenador para el evento Cloud News. Se realiza un proceso de iteración en cada evento y se comprueba si una noticia es urgente mediante el campo Urgent__c. Si una noticia es urgente, el desencadenador crea un caso para enviar a un corresponsal y agrega la ubicación del evento al asunto del caso.

Antes de ejecutar este ejemplo, cree una cola con una etiqueta de Despacho regional. Para aprender a configurar una cola, consulte Configurar colas en la Ayuda de Salesforce. Para obtener más información sobre el objeto Group (Grupo), que representa una cola, consulte Grupo en la Referencia de objetos para Salesforce y Lightning Platform.

En este ejemplo, se asignan casos a una cola. Las colas no forman parte de los eventos de plataforma y no es necesario usarlas para utilizar los eventos de plataforma. La asignación de casos a una cola permite la distribución de casos a un equipo de agentes de asistencia que son miembros de la cola.

// Trigger for listening to Cloud_News events.
trigger CloudNewsTrigger on Cloud_News__e (after insert) {
    // List to hold all cases to be created.
    List<Case> cases = new List<Case>();
    // Get queue Id for case owner
    Group queue = [SELECT Id FROM Group WHERE Name='Regional Dispatch' AND Type='Queue'];
    // Iterate through each notification.
    for (Cloud_News__e event : Trigger.New) {
        if (event.Urgent__c == true) {
            // Create Case to dispatch new team.
            Case cs = new Case();
            cs.Priority = 'High';
            cs.Subject = 'News team dispatch to ' +
                event.Location__c;
            cs.OwnerId = queue.Id;
            cases.add(cs);
        }
   }
    // Insert all cases corresponding to events received.
    insert cases;
}

Configurar los registros de depuración

A diferencia de los desencadenadores de los objetos estándar o personalizados, los desencadenadores de los eventos de plataforma no se ejecutan en la transacción de Apex usada para la publicación de eventos. El desencadenador se ejecuta en su propio proceso debajo de la entidad Proceso automatizado, la cual se corresponde con un usuario del sistema. Por consiguiente, los registros de depuración resultantes para la ejecución del desencadenador se crean mediante la entidad Proceso automatizado y no están disponibles en Developer Console. Para recopilar los registros de un desencadenador de eventos de plataforma, agregue una entrada de indicador de rastreo para la entidad Proceso automatizado en Configuración.

1. En Configuración, ingrese Registros de depuración en el cuadro Búsqueda rápida y, a continuación, haga clic en Registros de depuración.
   
2. Haga clic en Nuevo.
   
3. Para Tipo de entidad rastreada, seleccione Proceso automatizado.
   
4. Seleccione la fecha de inicio y la fecha de caducidad para los registros que desee recopilar.
   
5. Para Nivel de depuración, ingrese * y haga clic en Buscar.
   
6. Seleccione un nivel de depuración predefinido, como SFDC_DevConsole, o haga clic en Nuevo para crear su propio nivel de depuración.
   
7. Haga clic en Guardar.
   

Los registros de depuración para las pruebas de Apex son una excepción. Se incluyen registros para desencadenadores de eventos en el mismo registro de ejecución de las pruebas.

Consideraciones sobre los desencadenadores de eventos de plataforma

Orden del procesamiento de eventos

Un desencadenador procesa las notificaciones de eventos de plataforma secuencialmente y en el mismo orden en el que se reciben. El orden de los eventos se basa en el Id. de reproducción de eventos. Un desencadenador de Apex puede recibir un lote de eventos cada vez. El orden de los eventos se mantiene en cada lote. Los eventos de un lote se pueden originar en uno o varios publicadores.

Ejecución de desencadenadores asíncrona

Un desencadenador de eventos de plataforma se ejecuta en su propio proceso de forma asíncrona y no forma parte de la transacción que ha publicado el evento. Por lo tanto, es probable que se observe un retraso entre el momento en que se publica el evento y el momento en que el desencadenador procesa el evento. No espere que el resultado de la ejecución del desencadenador esté disponible de inmediato después de la publicación del evento.

Usuario del sistema Proceso automatizado

Dado que los desencadenadores de eventos de plataforma no se ejecutan en función del usuario que los ejecuta, sino en función del usuario del sistema Proceso automatizado, hemos establecido el campo de Id. del propietario de forma explícita en nuestro ejemplo CloudNewsTrigger. Hemos usado el Id. de una cola de usuario de ejemplo llamada Regional Dispatch (Envío regional) para el desencadenador de ejemplo. Si crea un registro de Salesforce con un campo OwnerId en el desencadenador (por ejemplo, un caso o una oportunidad), establezca de forma explícita el Id. de propietario. Una alternativa para los casos y los prospectos es usar reglas de asignación para establecer el propietario.

Además, los campos del sistema de registros creados o actualizados en el desencadenador de eventos, como CreatedById y LastModifiedById, hacen referencia a la entidad Proceso automatizado. De manera parecida, la declaración UserInfo.getUserId() de Apex devuelve la entidad Proceso automatizado.

Puede sustituir el usuario que ejecuta de un desencadenador de evento de plataforma de modo que el desencadenador se ejecute bajo ese usuario en vez del Proceso automatizado. Configure el desencadenador utilizando PlatformEventSubscriberConfig en la API de metadatos o la API de herramientas. Para obtener más información, consulte Configurar el usuario y el tamaño de lotes para su desencadenador de eventos de plataforma en la Guía del desarrollador de eventos de plataforma.

Límites regulados de Apex

Como ocurre en caso de los desencadenadores de objetos estándar y personalizados, los desencadenadores de eventos de plataforma están sujetos a límites regulados de Apex.

Limitaciones de los desencadenadores de Apex

Los desencadenadores de eventos de plataforma comparten muchas de las limitaciones de los desencadenadores de objetos estándar y personalizados. Por ejemplo, no puede realizar llamadas Apex de forma sincronizada desde los desencadenadores.

Tamaño de lotes de desencadenadores

El tamaño de los lotes en un desencadenador de evento de plataforma es de 2000 mensajes de eventos, que es mayor que el tamaño de los lotes de desencadenadores de objetos de Salesforce, que es de 200. El tamaño de los lotes se corresponde con el tamaño de la lista Trigger.New. Puede modificar el tamaño de los lotes de un desencadenador de eventos de plataforma. Para obtener más información, consulte Configurar el usuario y el tamaño de lotes para su desencadenador de eventos de plataforma en la Guía del desarrollador de eventos de plataforma.

Lista relacionada Suscripciones en la página de definición de eventos

Puede ver el estado de todos los desencadenadores de eventos en la página de detalles de definición de eventos de plataforma de Configuración. Debajo de Suscripciones, se indica cada desencadenador activo junto con la información de ejecución y el estado. Esta información incluye el Id. de reproducción de los últimos eventos publicados y procesados. El estado indica si el desencadenador está en ejecución o desconectado de la suscripción debido a errores sin solución o permisos insuficientes. El estado Error solo se alcanza cuando un desencadenador supera el número máximo de reintentos. En la siguiente captura de pantalla se muestra la lista relacionada Suscripciones de la página de detalles del evento Cloud News.

• La lista relacionada Suscripciones también enumera flujos y procesos suscritos al evento.
  
• La lista relacionada Subscriptions (Suscripciones) no incluye a los suscriptores que utilizan el modelo de publicación y suscripción de la API o el componente Lightning empApi. Obtiene información acerca de los otros tipos de suscriptores más adelante en esta unidad.
  
• Para eventos de plataforma de alto volumen, el valor Último Id. publicado no está disponible y siempre se muestra como No disponible.
  

Gestionar suscriptores de desencadenador de Apex de un evento

Como administrador del sistema, puede reanudar una suscripción suspendida donde se dejó, comenzando desde el mensaje de evento más temprano que está disponible en el bus de eventos. Si desea omitir mensajes de eventos que están causando errores o ya no son necesarios, puede reanudar la suscripción desde el extremo, comenzando desde nuevos mensajes de eventos.

Para gestionar una suscripción de desencadenador, en la lista relacionada Suscripciones, haga clic en Gestionar junto al desencadenador de Apex.

En la página de detalles de suscripción, seleccione la acción apropiada.

• Para suspender una suscripción en ejecución, haga clic en Suspend (Suspender).
  
  
• Para reanudar una suscripción suspendida, comenzando desde el primer mensaje de evento disponible en el bus de eventos, haga clic en Reanudar.
  
• Para reanudar una suscripción suspendida, a partir de nuevos mensajes de eventos, haga clic en Resume from Tip (Reanudar desde extremo).
  
  

No puede gestionar suscripciones para flujos y procesos a través de la lista relacionada Suscripciones.

Cuando guarda un desencadenador, la suscripción de desencadenador se reanuda automáticamente. Para más información, consulte Ver y gestionar suscriptores de un evento en la página de detalles del evento de plataforma en la Guía del desarrollador de eventos de plataforma.

Probar desencadenadores de eventos de plataforma

Asegúrese de que su desencadenador de eventos de plataforma funciona correctamente mediante la adición de una prueba de Apex. Para poder empaquetar o implementar cualquier código Apex (incluidos los desencadenadores) en producción, es necesario realizar pruebas con el código Apex. Para publicar eventos de plataforma en una prueba de Apex, incluya las declaraciones de publicación entre las declaraciones Test.startTest y Test.stopTest.

// Create test events
Test.startTest();
// Publish events
Test.stopTest();
// Perform validation here

En un contexto de prueba, la llamada al método de publicación incluye en la cola la operación de publicación. La declaración Test.stopTest() permite la publicación del evento. Después de Test.stopTest(), realice las validaciones correspondientes.

El siguiente es un ejemplo de una clase de prueba para nuestro evento Cloud_News y su desencadenador asociado. La publicación del evento activa el desencadenador asociado. Después de Test.stopTest(), la prueba verifica que la publicación se realizó correctamente inspeccionando el valor devuelto por isSuccess() en Database.SaveResult. Del mismo modo, la prueba consulta el caso que creó el desencadenador. Si se encuentra el registro del caso, el desencadenador se ejecutó correctamente y se superó la prueba.

@isTest
public class PlatformEventTest {
    @isTest static void test1() {
        // Create test event instance
        Cloud_News__e newsEvent = new Cloud_News__e(
            Location__c='Mountain City',
            Urgent__c=true,
            News_Content__c='Test message.');
        Test.startTest();
        // Call method to publish events
        Database.SaveResult sr = EventBus.publish(newsEvent);
        Test.stopTest();
        // Perform validation here
        // Verify that the publish was successful
        System.assertEquals(true, sr.isSuccess());
        // Check that the case that the trigger created is present.
        List<Case> cases = [SELECT Id FROM Case];
        // Validate that this case was found.
        // There is only one test case in test context.
        System.assertEquals(1, cases.size());
    }
}

Suscribirse a notificaciones de eventos de plataforma con un componente Lightning

Las aplicaciones Lightning pueden utilizar el componente web o Aura Lightning empApi para suscribirse a eventos en la aplicación.

Suscribirse a un componente web Lightning

Para utilizar los métodos empApi en su componente web Lightning, importe los métodos desde el módulo lightning/empApi de la manera siguiente.

import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled }
    from 'lightning/empApi';

Luego llame a los métodos importados en su código JavaScript.

Para consultar un ejemplo de cómo utilizar el módulo lightning/empApi y una referencia completa, consulte la documentación lightning-emp-api en la Biblioteca de componentes Lightning.

Suscribirse a un componente Aura

Para utilizar los métodos empApi en su componente Aura, agregue el componente lightning:empApi dentro de su componente personalizado y asígnele un atributo aura:id.

<lightning:empApi aura:id="empApi"/>

Luego, en el controlador del lado del cliente, agregue funciones para llamar a los métodos de componentes.

Para consultar un ejemplo de cómo utilizar el componente lightning:empApi y una referencia completa, consulte la documentación lightning:empApi en la Biblioteca de componentes Lightning.

Suscribirse a notificaciones de eventos de plataforma con clics

Para iniciar un flujo cuando se recibe un mensaje de evento de plataforma, cree un flujo desencadenado por evento de plataforma. Desde el elemento Inicio, elija un evento de plataforma cuyos mensajes de evento desencadenan la ejecución del flujo.

Mientras crea el flujo puede utilizar los valores de campo del mensaje de evento de la plataforma; para ello, haga referencia a la variable global de $Record.

De forma alternativa, puede suscribirse a un evento de plataforma en flujos empleando un elemento Pausa. En lugar de iniciar un flujo cuando recibe un mensaje de evento de plataforma, ese mensaje de evento provoca una entrevista de flujo en pausa para reanudar. Por ejemplo, aquí aparece un elemento Pausa que realiza una pausa del flujo hasta que Salesforce reciba un mensaje de evento de Cloud News. El flujo solo se reanuda si la ubicación del evento coincide con {!contact.MailingCity}. La variable del registro {!contact} almacena valores para un registro de contacto.

Suscribirse a notificaciones de eventos de plataforma con el modelo de publicación y suscripción de la API

El modelo de publicación y suscripción de la API proporciona una única interfaz para publicar y suscribirse a los eventos de plataforma. Basada en la API gRPC y HTTP/2, el modelo de publicación y suscripción de la API publica y entrega de forma eficiente mensajes de eventos binarios en formato Apache Avro. gRPC es un marco de trabajo de código abierto de llamada a procedimientos remotos (RPC) que permite conectar dispositivos, aplicaciones móviles y navegadores a servicios de backend. Para obtener más información, consulte la Documentación de gRPC. Apache Avro es un sistema de serialización de datos. Para obtener más información, consulte Apache Avro.

El modelo de publicación y suscripción de la API utiliza un modelo de suscripciones basadas en extracción, en el que el cliente solicita un número de eventos al servidor según su capacidad de procesamiento. A diferencia de las suscripciones basadas en distribución, en las que un cliente espera recibir nuevos eventos distribuidos desde el servidor, con una suscripción basada en extracción, un cliente solicita eventos al servidor de manera proactiva. Este control de flujo de eventos asegura que el cliente no se abrume con más eventos de los que puede manejar si hay un pico de publicación de eventos.

Algunos de los beneficios que ofrece el modelo de publicación y suscripción de la API son los siguientes:

• Publicación, suscripción y recuperación de esquemas de eventos, todo en una sola API.
  
• Resultados publicados finales de las operaciones de publicación, no los resultados intermedios de las colas.
  
• Control de flujo que permite especificar cuántos eventos recibir en una llamada de suscripción según la velocidad de procesamiento de eventos del cliente.
  
• Transmisión de datos en tiempo real y de alto desempeño que utiliza la compresión a través de HTTP/2.
  
• Soporte para 11 idiomas de programación en el cliente que ofrece la API gRPC, como Python, Java, Node y C++. Para conocer todos los idiomas admitidos, consulte https://grpc.io/docs/languages/.
  

El cliente del modelo de publicación y suscripción de la API puede recuperar el esquema, el Id. de reproducción y la carga del evento recibido por separado, y decodificar la carga. Por ejemplo, la carga del evento Cloud News recibido es muy similar a este mensaje.

{
  "CreatedDate": 1652978695951,
  "CreatedById": "005SM000000146PYAQ",
  "Location__c": "San Francisco",
  "Urgent__c": true,
  "Ink_Percentage__c": "Large highway is closed due to asteroid collision."
}

Para obtener más información, consulte la Documentación del modelo de publicación y suscripción de la API.

Ahora que ya sabe cómo usar los eventos de plataforma en Salesforce Platform y aplicaciones externas, ¡las posibilidades son infinitas! Use los eventos de plataforma para cualquier número de aplicaciones e integraciones, como el procesamiento de transacciones de negocio o la asistencia al cliente proactiva. Los eventos de plataforma le permiten adoptar un modelo de programación basado en eventos y disfrutar de las ventajas de una arquitectura de software basada en eventos.

Recursos

• Documentación del modelo de publicación y suscripción de la API: Java Quick Start para la API de Pub/Sub
  
• Guía del desarrollador de eventos de plataforma: Asignaciones de eventos de plataforma
  
• Guía del desarrollador de eventos de plataforma: Reintentar desencadenadores de eventos con EventBus.RetryableException
  
• Trailhead: Construir un aplicación de notificación instantánea
  
• Ayuda de Salesforce: Reglas de asignación