Definition

Event Bridge is an event bus service designed to use events to connect applications. It employs standardized events to help tenants build loosely coupled, distributed event-driven architectures easily.

It’s extremely helpful to enable third-party applications to extend the behavior without impacting the core business flow.

Case Study

• Scenario 1 - Product Management

Product management is a key module from InsureMO, offering a set of product APIs at the platform level. There is a requirement for the claim system to be notified and to receive complete product information upon product updates to quickly get claim parameters created.

Ideally, there can be three ways to achieve it:

1. Application to wrap a BFF to combine updated product and inform claim API two actions together.
2. Claim side to design a regular job to load product information.
3. Event to be published from the product side for the claim side to listen.

Compared to option 1,2, the event bridge solution is better because once the platform team publishes such an event, the claim team only needs to listen and implement the integration logic in real-time without need to set up a BFF or even take a UI that triggers the BFF.

• Scenario 2 - Batch Alert

Users can define regular execution jobs in the batch module. In the event of a batch failure, users need to be notified via email to take prompt actions.

The event bridge is also used in such a scenario to facilitate email sending. By default, the InsureMO email service can be employed to dispatch a standard batch alert template. However, given the presence of the platform event, if the client has specific requirements for a different email service or an email notification template, the client BFF can also disable the platform event and listen to the event to customize the platform’s behavior.

Key Concepts

1. Event: The carrier of data.
2. [Event Bus](#Event Bus): A relay station for events, responsible for the intermediate dumping of events.
   1. [Event Source](#Event Source): The source of the event, responsible for producing the event.
   2. [Event Rule](#Event Rule): Used to monitor specific types of events. When a matching event occurs, the event is routed to the event target associated with the event rules.
   3. [Event Trace](#Event Trace): Event Trace.
3. Integration: Integrate with third-party systems.
4. Schema: Define the structure of an event. Event Bridge provides a schema for all events generated by the event source. You can customize a schema for events sent to a custom event bus. The above schemas are stored in the schema registry, and event targets can download event schemas from the schema registry to achieve fast access to events.

Event

• Definition: Events are data records of state changes.
• Example: The following is an example event:

{
    "data": {
        "UserName": "James",
        "Email": "James@mail.com",
        "Telephone": "1333333333333",
        "RealName": "James",
        "DefaultLang": "011"
    },
    "source": "gimo:urp",
    "subject": "gimo:urp:ui:test",
    "time": "2023-11-19T21:04:41",
    "type": "urp:User:CreateUser",
    "id": "e414341e-32af-4a4f-864b-d2c9268f602a",
    "dataContentType": "application/json;charset=utf-8",
    "dataSchemaId": 1234,
    "eventBusName": "GimoBus"
}

Parameter Description

Event Bus

• The event bus is responsible for receiving events from event sources.
• Pre-configured bus: The GIMO dedicated line is a pre-set configuration that tenants cannot change. It can receive GIMO event sources and GIMO event sources can only be sent to GIMO dedicated line.
• The event bus of Event Bridge includes the following types:
  • Platform Bus:
    • GIMO
    • LIMO
  • Baseline Bus
    • Gemini
    • GBalife
    • Autoshop
  • Tenant Customized Bus
    • The Tenant-defined bus is used to receive events from tenant applications, and tenant events can only be published to the tenant’s custom bus.

Event Source

The Event Source is the source of the event, responsible for publishing the event to the Event Bridge. The Event Bridge supports the following event sources:

• GIMO Event Source

  By configuring predefined event sources, event types, and event targets, events can be published from the event source to the GIMO dedicated line. After filtering through event patterns, events can be routed to the event targets.

• Baseline/Tenant event sources

  • Customized applications can be configured to use the SDK to access Event Bridge. By setting up a custom bus, defining specific event patterns, and specifying event targets, events generated by these applications will be published to the custom bus, filtered according to the defined patterns, and routed to the specified targets.

  • Events can be published to Event Bridge by requesting a Webhook.

Event Type

Event Bridge supports publishing GIMO events as event sources to the event bus, which serves as a unified entry point for processing and distributing these events.

Examples

• urp:User:CreateUser
• product:Product:CreateProduct
• batchv2:Alter:JobAlter

Event Rule

• Event rules are used to filter and transform events.
• Including:
  • Event Pattern: Filter Pattern
  • Event Content Conversion: Event Content Conversion
  • Event Target: Rule Target

Filter Pattern

The event filter is a pattern definition used by Event Bridge to filter related events. Event Bridge filters events through event patterns and routes them to event targets, which must have the same structure as the matching events.

Matching principle

• The event must contain all the field names listed in the event pattern, and the field names in the event pattern must have the same nested structure as the field names in the event.
• The event pattern is precisely matched character by character, and attention to capitalization. During the matching process, no standardized operations will be performed on the string.
• The values to be matched follow JSON rules: Strings and numbers are enclosed in quotation marks, and keywords such as true, false, and null are not enclosed in quotation marks.
• The event pattern supports the semantics of OR, and in event pattern matching, each Key supports AND semantics. The value of Key supports the semantics of array OR.

Filter Type

• [Specified Value Matching](#Specified Value Matching)
• [Prefix Matching](#Prefix Matching)
• [Suffix Matching](#Suffix Matching)
• [Exclusion Matching](#Exclusion Matching)
• [Numeric Matching](#Numeric Matching)
• [IP Address Matching](#IP Address Matching)
• [Multi Pattern Matching](#Multi Pattern Matching)
• [Array Matching](#Array Matching)
• [Null Matching](#Null Matching)
• [Existing Matching](#Exist Matching (exists))
• [equals-ignore-case Matching](#Equals-ignore-case Matching (equals-ignore-case))
• [Wildcard Matching](#Wildcard Matching( * ?))

Specified Value matching

You can specify the value of a certain field for matching. For example, the following example event pattern only matches events where source is gimo: urp.

Prefix Matching

You can specify the prefix of a field’s value for matching. For example, the following example event pattern only matches events starting with gimo in the source field.

Suffix Matching

You can specify the suffix of a field’s value for matching. For example, the following example Event Filter only matches events in subject with prefix gimo: urp: user, suffix is . jpg, or . txt.

Exclusion Matching

anything-but

You can specify any value of a field to match, except for the provided value. You can use anything but with strings and numerical values. For example, the following example Event Filter only matches all events where state is not initializing and x-limit is not ‘123’.

The following example Event Filter only matches state events that are not ’stopped’ and ’overloaded‘.

The following example Event Filter only matches x-limit events that are not ‘100’, ‘200’, and ‘300’.

The following example Event Filter only matches events with a prefix of state that is not init.

The following example Event Filter only matches events where source is not a gimo product.

The following example Event Filter only matches events where source is not a gimo.

Numeric Matching

You can specify the numerical value or range of a certain field. For example, the following example Event Filter only matches events where c-count is greater than 0 but less than or equal to 5(>0 && <=5), d-count is less than 10, and x-limit is equal to 301.8.

IP Address Matching(cidr)

You can specify the IP address of the field in data. For example, in the following example Event Filter, only events with source ip as ‘10.0.0.0/24’are matched.

Multi Pattern Matching

Multiple rules can be combined into more complex Event Filters. For example, the following example Event Filter combines prefix matching, exclusion matching, IP address matching, and numerical matching.

Array Matching

The value of each field in the Event Filter is an array. If any value in the array matches the value in the event, the pattern matches. If the values in the event are also arrays, as long as the intersection with the array of Event Filter is not an empty set, the pattern matches.

Null Matching

You can create an Event Filter to match events that contain null values or empty strings.

Exist Matching (exists)

You can specify whether a field exists in data.

Equals-ignore-case Matching (equals-ignore-case)

You can specify the value of a certain field to match regardless of capitalization.

Wildcard Matching( * ?)

• * can specify any number of wildcard characters in a given string value. However, continuous wildcard characters are not supported.
• ? can specify a wildcard character in a given string value.

Event Convert

• Event Bridge converts an event into an event type that the event target can receive before it is routed to the event target.
• Conversion Type
  • [Complete Event](#Complete Event)
  • [Partial Event](#Partial Event)
  • Constant
  • Template
  • [Environment Variable](#Environment Variable)

Complete Event

When the conversion type is a Complete Event, Event Bridge does not convert the event and routes the complete structure of native Cloud Events to the event target.

Partial Event

When the Conversion Type is a partial event, Event Bridge extracts parameters from Cloud Events through JSONPath and routes the specified event content to the event target.

Constant

When the conversion type is Constant, the event only acts as a trigger. And regardless of the content of the event, Event Bridge routes the constant to the event target.

Template

When the conversion type is Template, by customizing the template and defining the variables required in the template, Event Bridge extracts the parameters from Cloud Events through JSONPath, stores these values in the variables, and then routes them to the event target in the format defined by the template. The template supports the following types:

• Simple String
• Simple JSON
• JSON with Mixed Variables and Constants
• Nested JSON

Simple String

Simple JSON

JSON with Mixed Variables and Constants

Nested JSON

Environment Variable

When the conversion type is an environment variable, Event Bridge extracts parameters from the configuration center and routes the specified event content to the event target.

Event Target(Rule Target)

• The event target is the processing terminal responsible for consuming the event.
• Target Type
• Retries and dead messages

Event Target Type

Currently, below target types are supported:

• [Insuremo Mail Service](#InsureMO Mail Service)
• [Platform RabbitMq](#Platform Rabbitmq)
• [Preset Http Client](#Preset HTTP Client)
• [Api Destination](#API Destination)
• [User Message](#Ui Message Box)

InsureMO Mail Service

• Target Sample

    {
        "Id":1234,
        "TypeId":123,
        "PushRetryStrategy":"BACKOFF_RETRY",
        "ErrorTolerance":"ALL",
        "DeadLetterRecord":false,
        "Params":[
            {
                 "Value": "{\"test\":\"test\"}",
                "ResourceKey":"CONTENT",
                "Form":"TEMPLATE",
            	"Template":"${test}"
            },
            {
                "Value":"test",
                "ResourceKey":"SUBJECT",
                "Form":"CONSTANT"
            },
            {
                "Value":"container.service.mail.account",
                "ResourceKey":"ACCOUNT",
                "Form":"ENV_PARAM"
            },
            {
                "Value":"lib-admin@insuremo.com",
                "ResourceKey":"TO",
                "Form":"CONSTANT"
            },
            {
                "Value":"PBU-ENGINEERING-COMMON@insuremo.com",
                "ResourceKey":"CC",
                "Form":"CONSTANT"
            },
             {
                "Value":"false",
                "ResourceKey":"PRIORITY",
                "Form":"CONSTANT"
            }
        ]
    }

Please note that if form is “Tenant Profile”, it will go to container tenant management to find tenant support mail group configuration. If you don’t have it, please check with the SiteOps team.

Platform RabbitMq

• Target Sample: Sending to Applications

   {
       "Id":1234,
       "TypeId":123,
       "PushRetryStrategy":"BACKOFF_RETRY",
       "ErrorTolerance":"ALL",
       "DeadLetterRecord":false,
       "Params":[
           {
               "ResourceKey":"BODY",
               "Form":"ORIGINAL"
           },
           {
               "Value":"APP",
               "ResourceKey":"SEND_TYPE",
               "Form":"CONSTANT"
           },
           {
               "Value":"$.data.testKey",
               "ResourceKey":"TOPIC",
               "Form":"JSONPATH"
           },
           {
               "Value":"platform-pub,dd",
               "ResourceKey":"APP_NAME",
               "Form":"CONSTANT"
           }
       ]
   }

• Target Sample: Broadcasting

    {
        "Id":1234,
        "TypeId":123,
        "PushRetryStrategy":"BACKOFF_RETRY",
        "ErrorTolerance":"ALL",
        "DeadLetterRecord":false,
        "Params":[
            {
                "Value":"{\"age\":\"26\"}",
                "ResourceKey":"BODY",
                "Form":"TEMPLATE",
            	"Template":"{\"test\": \"test\", \"age\":${age}}"
            },
            {
                "Value":"$.data.testKey",
                "ResourceKey":"TOPIC",
                "Form":"JSONPATH"
            },
            {
                "Value":"BROADCAST",
                "ResourceKey":"SEND_TYPE",
            "Form":"CONSTANT",
            }
        ]
    }

​

Preset HTTP Client

• Target Example

    {
        "Id":1234,
        "TypeId":123,
        "PushRetryStrategy":"BACKOFF_RETRY",
        "ErrorTolerance":"ALL",
        "DeadLetterRecord":false,
        "Params":[
            {
                "Value":"{\"test\":\"test\"}",
                "ResourceKey":"BODY",
                "Form":"TEMPLATE",
            	"Template":"${test}"
            },
            {
                "Value":"platform-pub",
                "ResourceKey":"SERVICE_NAME",
                "Form":"CONSTANT",
            }
        ]
    }

​

API Destination

• Target Sample

    {
        "Id": 1234,
        "TypeId": 222,
        "Endpoint": "http://test/test333",
        "ErrorsTolerance": "ALL",
        "PushRetryStrategy": "BACKOFF_RETRY",
        "DeadLetterRecord":false,
        "Params": [
            {
                "ResourceKey": "NAME",
                "Form": "CONSTANT",
                "Value": "test333"
            },
            {
                "ResourceKey": "HEADER_PARAMS",
                "Form": "TEMPLATE",
                "Value": "{\"headerKey1\":\"Content-Type\",\"headerValue1\":\"multipart/form-data\",\"headerKey2\":\"$.data.name\",\"headerValue2\":\"1\",\"headerKey3\":\"$.data.name\",\"headerValue3\":\"$\",\"headerKey4\":\"$.data.name\",\"headerValue4\":\"$.data.name\"}",
                "Template": "{\"${headerKey1}\":\"${headerValue1}\",\"${headerKey2}\":\"${headerValue2}\",\"${headerKey3}\":\"${headerValue3}\",\"${headerKey4}\":\"${headerValue4}\"}"
            },
            {
                "ResourceKey": "BODY_PARAMS",
                "Form": "TEMPLATE",
                "Value": "{\"bodyKey1\":\"sdd\",\"bodyValue1\":\"33\",\"bodyKey2\":\"$.data.test\",\"bodyValue2\":\"$\",\"bodyKey3\":\"$.data.vali\",\"bodyValue3\":\"$.data.fire\"}",
                "template": "{\"${bodyKey1}\":\"${bodyValue1}\",\"${bodyKey2}\":\"${bodyValue2}\",\"${bodyKey3}\":\"${bodyValue3}\"}"
            },
            {
                "ResourceKey": "QUERY_STRING_PARAMS",
                "Form": "TEMPLATE",
                "Value": "{\"queryKey1\":\"$.data.name\",\"queryValue1\":\"$.data.age\",\"queryKey2\":\"$.data.gender\",\"queryValue2\":\"2\"}",
                "Template": "{\"${queryKey1}\":\"${queryValue1}\",\"${queryKey2}\":\"${queryValue2}\"}"
            }
        ]
    }

​

UI Message Box

• Target Sample

    {
        "Id": 1234,
        "TypeId": 222,
        "ErrorsTolerance": "ALL",
        "PushRetryStrategy": "BACKOFF_RETRY",
        "Params": [
           {
                "Value":"{\"test\":\"test\"}",
                "ResourceKey":"BODY",
                "Form":"TEMPLATE",
            	"Template":"${test}"
            }
        ]
    }

Retry and Dead Message

• Retry strategy

  • Backoff retry (default): The maximum number to retry is 3, and the time interval between each retry is a random value between 10 and 20 seconds.
  • Exponential decay retry: The maximum number to retry is 176, and the time interval between each retry increases exponentially to 512 seconds, with a total retry duration of 1 day. The specific interval for each retry is 1, 2, 4, 8, 512 seconds.

• Fault tolerance strategy

  • Allow fault tolerance (recommended): Allow exception fault tolerance. When an exception occurs, it will not block execution. If the maximum number of retries is exceeded, the message will be stored in the dead message queue or directly discarded according to the configuration(item in configuration center??).
  • Prohibit fault tolerance: Fault tolerance is not allowed, and execution will be blocked when an exception occurs and exceeds the retry times(item in configuration center??).

• Dead Message queue

  • The dead message queue will be restricted based on the task dimension. In case of an inability to process or exceed the retry count, the failed raw data will be placed into the dead message queue record unchanged.

Event Trace

By using the event tracking function, you can view the content of events published to Event Bridge, including event details, as well as the processing trajectory of events in Event Bridge.

• Query method

  • Query by Event ID
  • Query by time range

• Time trajectory

  • Receiving events:

    You can see the time when Event Bridge received the event, as well as the source and type of the received event.

  • Filter events:

    You can see the rule matching done by Event Bridge for events.

  • Delivery Event:

    You can see the time and status of Event Bridge delivering events to the event target.

Integration

Assist in calling the HTTP interface of third-party systems without the need for additional architecture to complete interface calls. With the help of HTTP endpoints, it is easy to build and connect SaaS applications, and breakthrough data silos, provide cross-product and cross-platform connectivity capabilities, and promote the integration of cloud products, applications, and SaaS services.

Multiple APIs can share a set of connection configurations, providing convenient and pluggable authentication capabilities.

• [API Destinations](#Api Destination)
• Connection

API Destination

The HTTP endpoint defines the metadata of the API. When creating event rules, different HTTP endpoints can be referenced to access different third-party systems, and different rules can also reference the same HTTP endpoint.

Support the splicing of URL by reading configuration parameters or Jsonpath

for example: ${alert.server}${alert.urls}

NOTE: API Destination is only responsible for delivering events to consumers, so the timeout is 5s

Connection

• Connection is mainly used to achieve connectivity between external services and the current HTTP endpoint.

• The Connection contains authentication configuration information, and Event Bridge has selected the three most commonly used authentication methods currently available

  • Basic Auth
    • When using, the username and password need to be verified to access data resources. The username and password are prefixed with a Basic space and sent together to the target service. After the target server passes the authentication, it will respond to the request of Event Bridge. If the authentication fails, it will directly call back.
  • Bearer Token
    • You can use the current user’s token or read it through the configuration parameters and Jsonpath. for example: ${alert.token}
  • OAuth
    • OAuth has four authorization methods, namely authorization code, hidden, password, and client credentials. Event Bridge uses a client credential authorization method. In this mode, it is necessary to configure the information required to obtain client credentials in Event Bridge, including OAuth Service address, client ID, client password, etc. Event Bridge supports both GET/POST methods to obtain client credentials.
  • API Key
    • You can customize the KeyName and KeyValue accessed by the API, and Event Bridge will transmit them to the server for authentication through HttpHeader

Schema

• Schema is used to define the data format of event bodies and achieve reliable data exchange in heterogeneous systems.

• Schema is a version control specification that describes the format and content of data, used to define the data format of event bodies.

NOTE: The schema version cannot be modified after creation.

• The initial definition of a schema must be JSON text that complies with the OpenAPI 3.0 specification.

• Example

   {
           "openapi": "3.0.0",
           "info": {
               "title": "Input the schema descrition here",
               "version": "1.0.0"
           },
           "paths": {},
           "components": {
               "schemas": {
                   "Cloudevents": {
                       "type": "object",
                       "required": [
                           "id",
                           "source",
                           "subject",
                           "time",
                           "type",
                           "data"
                       ],
                       "properties": {
                           "id": {
                               "type": "string"
                           },
                           "source": {
                               "type": "string"
                           },                 
                           "subject": {
                               "type": "string"
                           },
                           "time": {
                               "type": "string"
                           },
                           "type": {
                               "type": "string"
                           },
                           "data": {
                               "ref": "#/components/schemas/<bizdatastructure>"
                           },
                           "publishtime": {
                               "type": "string"
                           },
                           "eventbusname": {
                               "type": "string"
                           },
                           "publishaddr": {
                               "type": "string"
                           }
                       }
                   },
                   "bizdatastructure": {}
               }
           }
       }

UI Operation

Add Bus

1. Select menu Public Setting > Event Bridge > Event Bus.
2. Click “Add Bus”. Input the bus defination info.

3. New Event Resource for the bus.

4. New Rule for the bus. More details about the rule, please refer to Event Rule.

The “Filter Pattern”, please refer to Filter Type.

4. New Target for the bus. More details about the event target, please refer to Event Target.

Event Trace

After the bus is created, you can find it in search result list.

Click “Edit” or “View”, you can see the bus defination details. Switch to tab “Event Trace”, you can see the trace details after the bus is used.

​

Development Reference

• [SDK Dependency](#SDK Dependency) - [Send Event](#Send Event) - [Receive Event](#Receive Event), use it when the target type is Reset HTTP Client.
• [URL Request](#URL Request)

SDK Dependency

Send Event

• pom Dependency

       <dependency>
           <groupId>com.ebao.vela</groupId>
           <artifactId>vela-event-support</artifactId>
       </dependency>

• Java Example

       	   @Autowired
           private EventPutService eventPutService;
       
       
           public void test(){
               User user = new User();
               user.setUserName("James");
               user.setEmail("James@email.com");
               user.setTelephone("13333333333");
               user.setRealName("James");
               user.setDefaultLang("011");
               CloudEvent cloudEvent = EventBuilder.newBuilder()
                       .withId(UUID.randomUUID().toString())
                       .withEventBus("GimoBus")
                       .withSource("gimo:urp")
                       .withType("urp:config:CreateUser")
                       .withSubject("gimo:urp:api:test")
                       .withTime(LocalDateTime.now())
                       .withData(user).build();
           eventPutService.put(cloudEvent);
           }

​

Receive Event

• pom Dependency

       <dependency>
           <groupId>com.ebao.vela</groupId>
           <artifactId>vela-event-support</artifactId>
       </dependency>

• Java Example

       @Service
       public class TestEventRevice<T> implements EventReceivedRest<T> {
       
           @Override
           public void receivedEvent(T a) {
            // business logic...
           }
       }

​

URL Request

• url:

  http://{{server}}/api/platform/platform-pub/eventBridge/event/v1/putEvent

• method:

  post

• request body

       {
           "data":{
               "UserName":"James",
               "Email":"James@mail.com",
               "Telephone":"1333333333333",
               "RealName":"James",
               "DefaultLang":"011"
           },
           "id":"e414341e-32af-4a4f-864b-d2c9268f232",
           "source":"gimo:urp",
           "time":"2023-11-19T21:04:41",
           "type":"urp:User:CreateUser",
           "dataContentType":"application/json;charset=utf-8",
           "eventBusName":"GimoBus"
       }

​