Getting Started

Define a Route

Routes allow messages to be delivered to an external system (or destination). A route connects the Everyware Cloud messaging service to the destination with a one-way channel. A route is defined by several parameters which specify:

• the source of the messages
• the conversion (if any) that need to be applied to the messages
• the destination of the messages
• the retry policy and the error handling

When possible, parameters have a default values that can be adapted to the specific use case. Each route is an instance of a template; the templates currently supported are the following:

• Apache Kafka
• REST Endpoint

A route can also be temporary disabled if necessary. Using the forwardable flag it can be propagated to child accounts.

Forwarded Routes

📘

Routes Scope

Routes can be defined only for level-one accounts (tenants) and the root account (tenant). Child accounts of level higher than one can inherit a route from their parent account through route forwarding feature but cannot define their own new routes.

Routes can be propagated to child accounts of any level in the hierarchy by setting the field Forwardable to true; check the configuration of the RouteService in the account Settings tab, if it's enabled then the forwarded rules are applied otherwise they will not.

The configuration of the rule applied to the child account is the same of the parent account included the destination. The Forwardable feature is implemented in such a way that account segregation is always enforced, that is, the route can only handle messages belonging to the child account.

Common Parameters for all Routes

The following are common Apache Camel parameters for all routes.

If the message is not delivered successfully within the max number of delivery attempts (defined through the parameter Maximum Redeliveries), it is logged and discarded.

Retry attempts follow an exponential backoff algorithm that is always enabled. The Back Off Multiplier parameter value is set to 2 by default (not configurable). The Maximum Redeliveries value is used as highest exponent of the Back Off Multiplier parameter value, while the Redelivery Delay is used as the starting base delay.

Blacklisting Feature

This feature help you prevent a set of addresses, host, subnets to be used as destinations for the routes. To implement this, the feature uses a black list. When a message has to be routed to a destination the Route service checks the addresses contained in the blacklist, if the destination is contained in the list, the service will raise an error and the delivery to the destination will be blocked.
Usually, the black list will contain a list of subnets instead a long list of single IP addresses. If a specific address within one of the blacklisted subnets needs to be reached by a route, then it can be added to the white list. The service will check the white list before checking the black list, if a match is found then the delivery to the destination is allowed.
The black list as well as the white list need to be defined as container properties. Please check the section container properties for more informations regarding how to configure this feature and the default values.

Performance Notes

Message routes have an impact in terms of workload and resource usage on the Messaging Service component which handles the connections from the devices. The magnitude of the impact depends on several factors related to the specific business use case:

• the number of active routes
• the retry policy of each route
• the reliability of the infrastructure including the network and the external services that have to be reached by the routes.

📘

Best Practice

In order to avoid possible consequences on the service level, take some time to fine tune the values of the retry policy parameters and the number of active routes in order to check that the final configuration of the routes works well for your use case.