Skip to content

Event handler

The event handler can subscribe and handle events in Lime CRM. It is possible to publish events from any service.

Core events

Lime CRM contains core events for all LimeTypes for all lifecycle events; new, update, delete and restore

They are published to core.lime.[limetype].[event] routing key

Configuration

Connection to RabbitMQ can be configured as described here

Configuration of the service is set as:

# config.yaml
event_handler: 
    catch_handler_exceptions: False
    dlq_ttl: 2592000 # 30 days

Catching Exceptions

catch_handler_exceptions sets how the handler should react to any uncaught exception. The default behavior is to allow the event handler to crash on any event that throws an unhandled exception. Setting this setting to True prevents the crash and instead moves the failing event to a dead letter queue where it can be requeued or removed.

Our current recommendation is to leave this setting off and instead make sure to catch and properly handle any possible exceptions in the event handler itself. This configuration helps for instances where a customisation is not able to properly handle an exception and the event handler cannot be allowed to crash.

Changing this setting requires the relevant queue to first be deleted so that it can be re-created with the correct settings for the DLQ.

Dead Letter Queue

The DLQ is a built-in feature in RabbitMQ that instead of removing a failed event moves it to a separate queue where it can either be requeued or deleted. The default duration that events will remain in the DLQ for is 30 days but this can be adjusted by changing the TTL value at dlq_ttl in the configuration. This configuration value is number of seconds.

Managing the Dead Letter Queue

Any failed messages are moved to queue with the name format of lime.event_handler.{app name}.dlq e.g. lime.event_handler.solution-cool-solution.dlq.

There is no graphical interface for managing the DLQ right now. This can either be managed through the RabbitMQ interface at http://hostname:15672/#/queues or through REST requests to the solution backend.

Viewing Broken Events

This is useful to see whether anything has ended up in the DLQ. The response shows the total number of events as well as a list of the broken events.

curl 'https://HOSTNAME/SOLUTION-NAME/diagnostics/dlq/' -H 'cloud-api-key: CLOUDAPIKEY'

Re-queueing Broken Events

In case the solution can be updated to properly handle the broken events i.e. if the problem was in the code that handles the event it would make sense to requeue the events. This is done through a PUT request on the endpoint.

curl -X PUT 'https://HOSTNAME/SOLUTION-NAME/diagnostics/dlq/' -H 'cloud-api-key: CLOUDAPIKEY'

Removing Broken Events

If the problem is with the content in the events themselves i.e. if the problem comes from an external integration or the code that created the event it would instead make sense to delete the events. This is done with a DELETE request on the endpoint.

curl -X DELETE 'https://HOSTNAME/SOLUTION-NAME/diagnostics/dlq/' -H 'cloud-api-key: CLOUDAPIKEY'