Como Criar Eventos dentro de uma Aplicação RAP

Por que seu Business Object deveria "alertar" quando algo muda?

Imagine que toda vez que uma viagem é reservada no seu sistema, três outros sistemas precisam saber: o financeiro, o de aprovação e um data lake. A forma antiga é cada um ficar perguntando "mudou algo?" de tempos em tempos (polling) ou você sair acoplando chamadas síncronas uma a uma. A forma moderna é o seu Business Object gritar uma vez — "viagem reservada!" — e quem se interessar escuta.

Esse "grito" é um RAP Business Event. Desde o release 2208 no cloud (BTP ABAP Environment e S/4HANA Cloud) e 2022 no on-premise, um Business Object do ABAP Cloud define, levanta e publica eventos de negócio nativamente, e o SAP Event Mesh entrega esse evento a quem assinou. E o recurso continua evoluindo: eventos derivados (2308), side effects orientados a eventos (2502 no cloud; S/4HANA 2025 no on-premise/private) e, no release 2025, filtragem outbound e tópicos dinâmicos com o Advanced Event Mesh.

Uma linha do tempo rápida: como o ABAP chegou até aqui

Eventos no ABAP não nasceram com o RAP — o que nasceu com o RAP foi a integração nativa deles ao modelo de programação:

Essa integração é o ponto-chave: o evento é declarado na BDEF, pode ser adicionado via behavior extension e tem ciclo de vida e estado de API próprios através do event binding — ou seja, é um artefato de primeira classe do modelo, não um apêndice.

Por que eventos em vez de chamadas síncronas?

Porque eventos trocam o acoplamento forte de uma chamada direta pelo modelo publish/subscribe — e isso muda a arquitetura inteira. Os ganhos concretos:

• Desacoplamento: o produtor não sabe quem consome. Zero, um ou dez consumidores — tanto faz, e adicionar um novo não toca no produtor.

• Resiliência assíncrona: se o consumidor cair, a mensagem espera na fila do Event Mesh.

• Near-real-time: o destino reage em segundos, sem polling nem batch.

• Clean Core: nada de modificação no standard — o evento sai pela camada RAP, e eventos standard extensíveis podem ser enriquecidos via derived events, sem tocar no objeto original.

Não use evento para um fluxo síncrono em que você precisa da resposta na hora (ex.: validar e devolver erro ao usuário). Para isso, uma ação RAP ou uma chamada direta é melhor. Evento é "avise e siga", não "pergunte e espere".

Casos de uso: onde isso encaixa de verdade

Caso 1 — Status de documento replicado para um sistema externo via CPI

Um cenário clássico de projeto: uma requisição de compra (ou ordem, ou documento fiscal) muda de status no S/4HANA e um sistema externo de procurement precisa refletir isso. Em vez de o CPI ficar consultando uma API a cada X minutos, o BO levanta um evento de mudança de status, o Event Mesh entrega numa queue e o iFlow do CPI consome (via adapter AMQP), transforma e chama a API do sistema externo. O S/4 nem sabe que o CPI existe — e se o sistema externo estiver fora do ar, a mensagem espera na fila. Contra duplicatas, o iFlow usa o Idempotent Process Call com o ID do evento.

Caso 2 — Workflow no BTP disparado por criação de registro

Um registro crítico é criado (um cadastro, um contrato) e precisa passar por aprovação no SAP Build Process Automation. O BPA assina o topic do evento "created" e instancia o processo automaticamente. Zero código de disparo no lado do processo.

Caso 3 — Alimentar data lake / analytics em tempo quase real

Cada fato de negócio (pedido criado, entrega confirmada) vira um evento com payload enxuto de chaves. Um consumidor genérico assina a família de topics com wildcard e alimenta o pipeline de dados. Quem precisar do registro completo consulta a API OData/CDS depois — o evento é o gatilho, não o transporte de massa.

Caso 4 — Enriquecer um evento standard da SAP (derived event)

O evento standard de Business Partner traz, por padrão, praticamente só o número do BP. Se o consumidor precisa de nome e sobrenome no payload, você cria um derived event sobre o evento standard, com payload customizado — sem modificar nada do objeto original. Falamos dele em detalhe mais abaixo.

Caso 5 — Carga inicial (initial load) orientada a eventos

Vai plugar um consumidor novo num objeto que já tem milhares de registros? A recomendação da SAP é não reaproveitar os eventos standard para a carga inicial — outros handlers locais podem reagir a eles e gerar efeitos colaterais indesejados. O padrão é criar um evento custom dedicado de initial load e um programa ABAP que lê os dados e dispara um evento por registro:

METHOD if_oo_adt_classrun~main.
  SELECT FROM I_BusinessPartner
    FIELDS BusinessPartner, BusinessPartnerCategory, BusinessPartnerUUID
    INTO TABLE @DATA(lt_bp).

  LOOP AT lt_bp ASSIGNING FIELD-SYMBOL(<bp>).
    zbp_initload_bp=>raise_initial_load(
      VALUE #( ( BusinessPartner = <bp>-BusinessPartner
                 %param = CORRESPONDING #( <bp> ) ) ) ).
  ENDLOOP.

  COMMIT WORK.   " sem isso, nenhum evento sai
ENDMETHOD.

Quando NÃO usar

A arquitetura de ponta a ponta

Conhecer cada peça evita perder horas procurando onde a mensagem "sumiu". O caminho completo:

E as transações/artefatos de operação que você vai usar (on-premise / private cloud):

No BTP ABAP Environment / S/4HANA Cloud Public, o channel nasce de um communication arrangement com o cenário SAP_COM_0092 (Enterprise Event Enablement), usando a service key da instância do Event Mesh — e a configuração outbound é feita no app Fiori "Enterprise Event Enablement".

Passo a passo

1. Definir o payload (abstract entity)

O conteúdo do evento é tipado por uma CDS abstract entity. Mantenha-a enxuta — payload é contrato, e payload gordo acopla o consumidor ao seu modelo interno. Importante: as chaves da entidade sempre viajam no payload, com ou sem parâmetro; a abstract entity só adiciona campos extras:

define abstract entity ZD_Travel_Booked
{
  TravelId   : /dmo/travel_id;
  CustomerId : /dmo/customer_id;
  TotalPrice : /dmo/total_price;
  Currency   : /dmo/currency_code;
}

2. Declarar o evento na behavior definition

O evento pode ser declarado em qualquer entidade de um BO managed ou unmanaged — e o parâmetro é opcional (sem ele, o payload leva só as chaves):

define behavior for ZI_Travel alias Travel
implementation in class zbp_i_travel unique
{
  create; update; delete;

  // evento de negócio com payload tipado
  event travelBooked parameter ZD_Travel_Booked;

  // evento sem parâmetro: payload = só as chaves
  event travelCancelled;
}

3. Disparar com RAISE ENTITY EVENT

Aqui a documentação é bem específica, e vale conhecer as regras exatas:

• RAISE ENTITY EVENT é um statement EML que só pode ser usado em ABAP behavior pools — e não confunda com o RAISE EVENT clássico de ABAP Objects, que é outra coisa.

• Você só pode levantar eventos definidos na BDEF do mesmo RAP BO, referenciados como Entidade~Evento.

• O dado após o FROM é do tipo derivado TABLE FOR EVENT Entidade~Evento: a linha traz no mínimo as chaves primárias (endereçáveis pelo grupo %key) e, se houver parâmetro, o %param.

• Esses tipos não têm %tky nem %is_draft — ou seja, não existe evento específico para instâncias draft. Evento é coisa de dado persistido.

• A recomendação oficial: levantar o evento nos métodos saver save ou save_modified; em BOs managed, o padrão é usar um additional save e disparar de lá.

METHOD save_modified. " ou additional save no managed
  IF create-Travel IS NOT INITIAL.
    RAISE ENTITY EVENT ZI_Travel~travelBooked
      FROM VALUE #( FOR travel IN create-Travel
        ( %key   = travel-%key
          %param = VALUE #( TravelId   = travel-TravelId
                            CustomerId = travel-CustomerId
                            TotalPrice = travel-TotalPrice
                            Currency   = travel-CurrencyCode ) ) ).
  ENDIF.
ENDMETHOD.

Por que a save sequence? Porque o evento representa um fato consolidado. A própria arquitetura reforça isso: o BO registra o evento, que é levantado pouco antes do commit ser disparado — nunca no meio de uma validação que ainda pode falhar. (Se você não domina a save sequence, vale revisar o cenário RAP Unmanaged, onde ela é o coração do salvamento.)

Bônus: disparando a partir de código legado (não-RAP)

E se o fato de negócio acontece num report clássico, numa BAPI, num user exit? A SAP documenta o padrão: você não precisa de um BO transacional completo — basta um RAP BO mínimo cuja única função é hospedar o evento, com um método estático público no behavior pool servindo de wrapper para o RAISE ENTITY EVENT:

CLASS zbp_travel_events IMPLEMENTATION.
  METHOD raise_travel_booked. " método estático público (wrapper)
    RAISE ENTITY EVENT ZI_Travel~travelBooked FROM it_events.
  ENDMETHOD.
ENDCLASS.

" ...em qualquer código legado:
zbp_travel_events=>raise_travel_booked( it_events ).
COMMIT WORK.

4. Criar o event binding — e entender a anatomia do topic

O event binding conecta o evento RAP ao topic. Ele referencia um namespace, um SAP object type e uma operation — a concatenação dos três, mais a versão, forma o type/topic do evento. É um objeto próprio que você cria no ADT (New > Other Repository Object > Event Binding), adicionando a root entity e o nome do evento da BDEF. Na prática:

Namespace:        ztravel
SAP Object Type:  Travel
Operation:        Booked

=> Type do evento:      ztravel.Travel.Booked.v1
=> Topic outbound:      ztravel/Travel/Booked/*     " * = versão
=> Assinatura na queue: <namespace-da-instância>/ce/ztravel/Travel/Booked/*

Os nomes são livres, mas a recomendação oficial é definir e seguir uma convenção clara — o topic é o contrato público do seu evento.

5. Criar o channel e o outbound binding

O channel representa uma conexão com uma instância de serviço do Event Mesh. On-premise/private: /n/IWXBE/CONFIG, colando a service key da instância, e ativação do channel. Depois, em /n/IWXBE/OUTBOUND_CFG, você cria o topic binding ligando o topic do seu event binding ao channel — sem esse passo explícito, o evento não é publicado. No BTP/Cloud Public, o equivalente é o communication arrangement SAP_COM_0092 + configuração no app Enterprise Event Enablement.

6. Validar: Event Monitor e o payload que chega

Disparou e não chegou? Antes de sair caçando no Event Mesh, confira /n/IWXBE/EVENT_MONITOR: se o evento não aparece lá, o problema é do lado do produtor (geralmente o famigerado commit ou o topic binding faltando); se aparece e não chega na queue, o problema é channel/assinatura.

Quando chega, a mensagem segue o padrão CloudEvents: o type é o do event binding, e o campo data carrega as chaves do BO + a estrutura do parâmetro. Ilustrativamente:

{
  "specversion": "1.0",
  "type": "ztravel.Travel.Booked.v1",
  "source": "/default/sap.s4h/S4H_001",
  "id": "a8e21f4c-...",
  "time": "2026-07-01T14:32:11Z",
  "data": {
    "TravelId":   "00000042",
    "CustomerId": "000123",
    "TotalPrice": "1250.00",
    "Currency":   "BRL"
  }
}

Consumo local: eventos sem Event Mesh nenhum

Detalhe que muita gente não conhece: um RAP event também pode ser consumido no mesmo sistema em que foi levantado, sem broker, sem binding, sem channel. Basta um RAP event handler class:

• Uma classe global definida com FOR EVENTS OF nome_do_BO;

• Dentro dela (em Local Types), uma classe local que herda de cl_abap_behavior_event_handler e implementa métodos FOR ENTITY EVENT;

• O handler é chamado localmente e processado de forma assíncrona, somente após o commit ter sido concluído com sucesso — você já está fora da save sequence do produtor, mas continua sujeito às fases transacionais do RAP (cl_abap_tx).

CLASS zeh_travel DEFINITION PUBLIC ABSTRACT FINAL
  FOR EVENTS OF ZI_Travel.
ENDCLASS.

" Local Types:
CLASS lhe_travel DEFINITION INHERITING FROM cl_abap_behavior_event_handler.
  PRIVATE SECTION.
    METHODS on_travel_booked FOR ENTITY EVENT
      it_params FOR Travel~travelBooked.
ENDCLASS.

CLASS lhe_travel IMPLEMENTATION.
  METHOD on_travel_booked.
    " o handler inicia na fase MODIFY (default);
    " para gravar no banco / disparar o "fazer", feche a fase antes:
    cl_abap_tx=>save( ).

    LOOP AT it_params INTO DATA(ls_param).
      " reagir ao evento: log, notificação, disparo de processo...
      INSERT ztravel_log FROM @( VALUE #(
        travel_id  = ls_param-TravelId
        event_type = 'BOOKED'
        created_at = utclong_current( ) ) ).
    ENDLOOP.
  ENDMETHOD.
ENDCLASS.

Casos de uso do consumo local: desacoplar processos pesados dentro do mesmo sistema (o handler roda assíncrono), disparar log/notificação após o fato consolidado, ou o padrão avançado de consumir um evento standard localmente e re-disparar um evento custom enriquecido quando derived events não estão disponíveis.

Como o consumidor recebe: queue vs. webhook

No Event Mesh, há duas formas de consumir os eventos de uma queue, e a escolha muda totalmente o tratamento de erros:

Webhook: QoS e o mecanismo de retry

Dois detalhes de configuração do webhook mudam tudo:

• QoS 0 = fire and forget: o código HTTP de retorno não é avaliado — a mensagem sai da fila mesmo se o endpoint falhou. Para produção, use QoS 1: a mensagem só é confirmada quando o webhook responde 2xx.

• Retry próprio: se o endpoint não responde em até 1 minuto ou devolve não-2xx, a mensagem é considerada não confirmada e reentregue após ~15 minutos, repetidamente, até um 2xx ou até a mensagem expirar (TTL). E um webhook segura apenas um punhado de mensagens não confirmadas por vez — endpoint lento trava a esteira.

Dead Message Queue e redelivery

Mensagem que não é consumida com sucesso não pode ficar travando a fila para sempre. É aí que entra a Dead Message Queue (DMQ) e o Max Redelivery Count:

• O Max Redelivery Count vai de 0 a 255 — e atenção à semântica: 0 significa redelivery ilimitado, não "zero tentativas". Ao configurar uma DMQ, é obrigatório definir o Max Redelivery Count ou habilitar o Respect Time to Live.

• Atingido o limite de tentativas (ou expirado o TTL), a mensagem é considerada "morta" e movida para a DMQ — onde você investiga sem bloquear o fluxo.

Uma configuração de partida sensata para uma fila produtiva consumida via AMQP:

Filtrando com wildcards no topic

O consumidor não precisa assinar um topic exato. O Event Mesh permite wildcards: * casa um único nível da hierarquia do topic e > casa um ou mais níveis. Na prática:

ztravel/Travel/Booked/v1     " topic exato: só este evento, só esta versão
ztravel/Travel/Booked/*      " este evento, qualquer versão (o padrão do outbound)
ztravel/Travel/*/*           " QUALQUER operação de Travel (Booked, Cancelled...)
ztravel/>                    " tudo do namespace ztravel, qualquer profundidade

Assim, uma única assinatura captura uma família inteira de eventos — útil para um consumidor genérico de "tudo que acontece com Travel". Aliás, você já usa wildcard sem perceber: o sufixo de versão do topic outbound é exatamente isso.

Eventos derivados: estendendo eventos standard

Você não precisa começar do zero. Desde o release 2308 (disponível no S/4HANA Cloud Public Edition e, no private/on-premise, a partir do S/4HANA 2023) existem os Derived Events: você define um novo evento com payload customizado a partir de um evento SAP standard existente. Os pontos que a documentação destaca:

• O derived event é criado estendendo a behavior definition do BO standard — o que exige que o BO tenha contrato C0 liberado (extensível). Nem todo evento standard é extensível; confira no SAP Business Accelerator Hub, em Events – Event Objects.

• No payload CDS customizado, a anotação @event.context.attribute transforma campos do payload em atributos de filtro — permitindo que o consumidor filtre eventos por conteúdo, não só por topic.

• Se o BO standard não for extensível (sem C0), o workaround documentado é: consumir o evento standard localmente, enriquecer os dados e re-disparar um evento custom — lembrando de mudar para a fase de save com cl_abap_tx=>save( ) antes do RAISE ENTITY EVENT:

" handler local do evento STANDARD re-disparando um evento CUSTOM enriquecido
METHOD consume_bp_changed.
  cl_abap_tx=>save( ).   " RAISE ENTITY EVENT exige a fase de save

  SELECT FROM I_BusinessPartner
    FIELDS BusinessPartner, FirstName, LastName
    FOR ALL ENTRIES IN @it_params
    WHERE BusinessPartner = @it_params-BusinessPartner
    INTO TABLE @DATA(lt_bp).

  RAISE ENTITY EVENT z_bp_events~bpChangedEnriched
    FROM VALUE #( FOR bp IN lt_bp
      ( BusinessPartner = bp-BusinessPartner
        %param = VALUE #( FirstName = bp-FirstName
                          LastName  = bp-LastName ) ) ).
ENDMETHOD.

Side effects orientados a eventos: o evento chegando na UI

Novidade recente: os event-driven side effects permitem que, quando um RAP business event específico é levantado, a UI Fiori Elements recarregue automaticamente os targets definidos — atualização assíncrona da tela, sem F5 do usuário. Disponibilidade: release 2502 nos cloud releases (BTP ABAP Environment e S/4HANA Cloud Public) e, para on-premise/private cloud, a partir do S/4HANA 2025 (liberado em outubro de 2025).

Caso de uso típico do sample oficial: um processamento em background (BGPF) recalcula o estoque, atualiza a entidade e levanta o evento — e o campo Quantity na tela do usuário se atualiza sozinho, com direito a popup de notificação. A sintaxe na BDEF base:

// evento habilitado para side effects
event QuantityUpdated for side effects;

side effects
{
  event QuantityUpdated affects field ( Quantity );
}

E na projection, é preciso liberar o uso — no nível do BO e do evento:

use side effects;
define behavior for ZC_InventoryTP alias Inventory
{
  use action reCalculateInventory;
  use event QuantityUpdated;
  ...
}

O que mais chegou no release 2025

Para quem está em private cloud/on-premise, o S/4HANA 2025 reforçou a arquitetura orientada a eventos com:

• Outbound event filtering: publicação seletiva com base em critérios configuráveis — o evento só sai se atender ao filtro.

• Dynamic topics com o SAP Event Mesh Advanced Plan, para roteamento mais eficiente.

• Event logging abrangente, incluindo captura local de eventos processados com sucesso, e agrupamento de eventos do mesmo tipo/objeto numa sessão como "atividades" — menos ruído no monitoramento.

• Suporte ao SAP Cloud Application Event Hub para consumir eventos de soluções no BTP.

Boas práticas consolidadas

1. Sempre dê COMMIT WORK ao disparar via código próprio. É o erro nº 1.

2. Dispare na save sequence (managed: additional save; unmanaged: save/save_modified): evento é fato consumado, não promessa.

3. Payload enxuto: envie chaves e poucos campos; quem precisar de mais consulta a API. As chaves já vão de graça no payload.

4. Versione o contrato: o event binding já carrega a versão no topic — use isso. Mudar payload quebra consumidores; trate o topic como contrato público.

5. Consumidor idempotente: a entrega é "at least once" — duplicatas vão acontecer. No CPI, resolva com o Idempotent Process Call.

6. Webhook sempre com QoS 1 — QoS 0 descarta mensagem mesmo em erro.

7. Configure DMQ + Max Redelivery (via AMQP) para não travar a fila com poison messages — lembrando que 0 = ilimitado e que webhook ignora esse contador.

8. Use wildcards com critério: > captura demais; prefira o mínimo necessário.

9. Carga inicial com evento dedicado, nunca reaproveitando o evento standard de create/change.

10. Monitore dos dois lados: /IWXBE/EVENT_MONITOR no produtor, fila/DMQ no Event Mesh.

Perguntas frequentes

Posso disparar um evento fora da save sequence?

Tecnicamente, o RAISE ENTITY EVENT compila em qualquer lugar do behavior pool — mas a recomendação oficial é os métodos saver (save/save_modified, ou additional save no managed), garantindo que o evento só sai quando a transação foi persistida. E, ao disparar de código próprio, sempre com COMMIT WORK na sequência.

Posso disparar de um report clássico ou user exit?

Sim — crie um RAP BO mínimo que hospede o evento e exponha um método estático wrapper no behavior pool. É o padrão documentado pela SAP para integrar código legado à arquitetura de eventos.

Funciona com draft?

Não para instâncias draft: os tipos TABLE FOR EVENT não têm %tky/%is_draft. Evento é sempre sobre o dado ativo, persistido.

A entrega é exactly-once?

Não. A semântica é "at least once": o consumidor pode receber duplicatas e deve ser idempotente. No CPI, o Idempotent Process Call garante o efeito exactly-once.

Qual a diferença entre queue e webhook na prática?

Queue é pull (AMQP com controle pleno de redelivery e DMQ; REST só para teste); webhook é push (o Event Mesh empurra para seu endpoint, com retry próprio que ignora o Max Redelivery Count). Escolha queue/AMQP quando precisa de DMQ; webhook quando precisa de reação imediata — e sempre com QoS 1.

Preciso de Event Mesh ou serve o Advanced Event Mesh?

Os conceitos (topic, queue, subscription, DMQ) valem para os dois. O Advanced Event Mesh (baseado em Solace) adiciona recursos como replay, malha distribuída e — a partir do release 2025 — dynamic topics, úteis em cenários de larga escala. No AEM, a convenção recomendada é uma DMQ separada por fila, nomeada <fila>_dmq.

Como testo o evento sem um consumidor real?

Confirme primeiro no /IWXBE/EVENT_MONITOR que o evento foi gerado. Depois, crie uma queue de teste assinando o topic do seu event binding e leia as mensagens via REST API (pull) — ou pelo próprio botão Consume no cockpit do Event Mesh — após disparar o evento e dar COMMIT WORK.

Conclusão

RAP Business Events transformam mudanças de negócio em eventos consumíveis dentro e fora do sistema — integração assíncrona, desacoplada e em tempo quase real, reusando o que você já sabe de RAP. O fluxo é claro: payload tipado, evento na BDEF, RAISE ENTITY EVENT na save sequence, COMMIT WORK, event binding, channel, outbound binding e consumo por queue, webhook ou handler local. Domine o lado do consumidor — idempotência, QoS, DMQ e wildcards — e você tem uma arquitetura orientada a eventos de verdade, não só um "publish" solto.

Referências oficiais

• Business Events (RAP) — SAP Help

• Business Event Consumption — SAP Help

• Raising and Handling Business Events — SAP Learning

• Expose RAP Business Events — SAP Developers

• RAP Business Events em sistema on-premise — SAP Developers

• Manage Queues — SAP Event Mesh

• Derived Events — SAP Community (blog oficial SAP)

• RAP BO Events end-to-end — SAP Community (blog oficial SAP)

• Initial Loads com RAP Events — SAP Community (blog oficial SAP)

• BGPF + Event-Driven Side Effects — SAP-samples (GitHub)

• ABAP Platform no S/4HANA 2025 — SAP Community (blog oficial SAP)

• Trigger e testar RAP event via Event Mesh — SAP Community