Azure Event Hub Trigger

Listen to messages from Azure Event Hub.

In order to launch a Process through Azure Event Hub messaging, Azure Event Hub Trigger can be used.

You can learn more about Triggers in general here.

What is Azure Event Hub Trigger?

Azure Event Hub Trigger is much like AMQP Trigger, and listens for new content in Azure Event Hub messaging system and activates Processes accordingly. Suitable for event-driven architectures where asynchronous communication is key.

Usage

To use a Trigger in your Process, add it to your Process canvas, and connect it to the beginning of your Process using a Sequence flow. If you are using multiple Triggers in your Process, all Triggers must connect to the same shape, which is also the first non-Trigger shape in your Process.

Once added to your Process, you can change the Trigger's type to match your requirement and give it a unique name. By default, the Trigger's type will provide a corresponding name for the Trigger. You can then configure the parameters for the chosen Trigger type.

For Azure Event Hub Trigger, you should set up an Event Hub beforehand, and then connect the Trigger to it through its connection string, SAS token or OAuth. You should also specify which Hub to listen to, as well as to which Consumer Group the Trigger is participating in. After setting up the connection to Event hub, you can optionally set up load balancing, batching and storage options related to Azure Event Hub.

By creating a Process using Azure Event Hub Trigger and activating said Process, the Frends Agent will start listening for events from the Hub and trigger the Process as necessary to handle the Event messages.

Configuration

To set up a Azure Event Hub Trigger, add the shape to Process canvas and connect it as part of your Process. After that, you can select the Trigger type and configure the parameters for it.

The common parameters available for all Triggers are explained on the Trigger reference page. The following configuration parameters are available for Azure Event Hub Trigger.

Authentication method

Selector to choose the authentication method used to connect to Azure Event Hub. Correct option depends on your requirements for security, as well as what options there are available for you in Azure Event hub management, and how you choose to set up authentication there.

Connection String

Connection String can be used to connect to your Azure Event Hub using a namespace URI and a Shared Access Key.

SAS Token

Instead of connection string and Shared Access Key, Shared Access Signature (SAS) token can alternatively be used. Much like the connection string, this method requires the namespace for your Azure Event Hub, as well as the SAS Token instead of Shared Access Key. SAS token commonly contains more details about what you are allowed to access using the token, and when it will expire, making it slightly more secure.

OAuth2

OAuth2 can also be used to authenticate to your Azure Event Hub. As is common with Microsoft and Azure services, using OAuth requires creation of app registration in your Azure management portal, and allowing said registration to connect to your Azure Event Hub.

OAuth2 is the recommended way to connect to Azure Event Hub, requiring slightly more set up than the other two methods, while being more secure and as easy to use afterwards.

Event Hub name

Name of the hub to listen to for messages. Environment Variables can be used here to use different hub for each Environment.

Consumer Group name

Name of the Consumer (message receiver) Group this Process participates in. Separate Consumer Groups can read the same event streams independently, allowing for example multiple Processes to read the same messages for different purposes, without taking some messages away from other Processes. Default Consumer Group is $Default.

Data encoding

Encoding format for the message data. Defaults to UTF-8.

Pass data as base64 encoded byte array

Toggle option to choose whether the incoming event data should be parsed into a string, or leave it as raw binary data in base64 encoding. Default is off, meaning the incoming data will be parsed into a string using the encoding format defined above.

Load balancing strategy

Allows you to choose how the load is balanced between partitions using Event Processor Client.

Balanced strategy gives more stability, rebalancing the partitions for each consumer less often.

Greedy strategy performs rebalancing faster, changing partitions and ownership more often. This is useful when the event receivers change often, but causes more overhead.

Update checkpoint immediately

Toggle switch to select whether or not the checkpoint is updated immediately after Process starts, or only after successful execution. Updating the checkpoint essentially means acknowledging messages in the hub up to that point. Defaults to off, requiring a successful Process execution before messages are acknowledged.

Event batch size

Numerical field to specify how many messages should at most be handled simultaneously. All the messages from the batch are handled within the same Process Instance.

Checkpoint Blob storage container URI

URI for the blob storage location the Process should use for Event Hub.

Azure Blob storage is used to store the state of event processing, in case a restart or failure happens and the state is lost from memory. Event Hub usage requires read and write access to the specified container.

Blob storage authentication method

Selector to choose the authentication method used to connect to Azure Event Hub. Correct option depends on your requirements for security, as well as what options there are available for you in Azure Blob storage management, and how you choose to set up authentication there.

Connection String

Connection String can be used to connect to your Azure Blob storage using a namespace URI and a Shared Access Key.

SAS Token

Instead of connection string and Shared Access Key, Shared Access Signature (SAS) token can alternatively be used. Much like the connection string, this method requires the namespace for your Azure Blob storage, as well as the SAS Token instead of Shared Access Key. SAS token commonly contains more details about what you are allowed to access using the token, and when it will expire, making it slightly more secure.

OAuth2

OAuth2 can also be used to authenticate to your Azure Blob storage. As is common with Microsoft and Azure services, using OAuth requires creation of app registration in your Azure management portal, and allowing said registration to connect to your Azure Blob storage.

OAuth2 is the recommended way to connect to Azure Blob storage, requiring slightly more set up than the other two methods, while being more secure and as easy to use afterwards.

Do not log trigger parameters

Toggle option that when enabled, hides the Trigger parameters from being logged in Process Instances.

Reference Values

In addition to the default Trigger reference values, Azure Event Hub Trigger provides the following additional values.

#trigger.data (Frends.ExecutableProcess.CaseInsensitivePropertyTree)

Object containing the data derived from input parameters and the resulting data from processing the Trigger.

#trigger.data.events (Azure.Messaging.EventHubs.PartitionEvent[])

Array of PartitionEvent objects received in the batch of messages, containing the message contents and properties.

#trigger.data.events[].contentType (String)

Optional MIME type of the received message.

#trigger.data.events[].correlationId (String)

Optional identifier for a chain of events.

#trigger.data.events[].enqueuedTime (DateTimeOffset)

Timestamp when the event was added to the Event Hub.

#trigger.data.events[].eventBody (String)

Message contents. Either a parsed string in the chosen encoding, or base64 encoded string of binary data, depending on the parameter setting in the Trigger.

#trigger.data.events[].messageId (String)

Optional unique identifier for the message.

#trigger.data.events[].offsetString (String)

Position of the event in the partition stream, presented as a large integer in string format.

#trigger.data.events[].partitionKey (String)

Optional key used to map events to specific partitions.

#trigger.data.events[].properties (Dictionary<String, String>)

Custom application-specific metadata for the message.

#trigger.data.events[].sequenceNumber (Long)

Unique number assigned to the event within the partition.