Azure Service Bus Plugin

The plugin provides functionality to interact with Service Bus.

Installation

  1. Copy the below line to dependencies section of the project build.gradle file

    Please make sure to use the same version for all VIVIDUS dependencies.
    Example 1. build.gradle
    implementation(group: 'org.vividus', name: 'vividus-plugin-azure-service-bus', version: '0.6.13')

  2. If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Configuration

Authentication

The authentication process relies on the configuration of the environment variables.

See the official "Azure identity" guide to get more details on what types of authentication could be used.

Azure environment selection

Azure environment could be optionally specified using the property azure.environment (sets the environment for all Azure plugins). The default value is AZURE.

The supported environments are only:

  • AZURE

  • AZURE_CHINA

  • AZURE_GERMANY

  • AZURE_US_GOVERNMENT

Azure subscription selection

Azure subscription must be configured via AZURE_SUBSCRIPTION_ID environment variable.

Azure Service Bus Configuration

Azure Service Bus configurations are established via set of properties with the following format:

azure.service-bus.{service-bus-key}.{property-name}=property value

where:

  1. service-bus-key - The key associated with the Azure Service Bus connection configuration, which will be used as a step parameter.

  2. property-name - The name of Service Bus property. One of:

    1. channel-type - The type of Service Bus messaging channel: either QUEUE or TOPIC.

    2. namespace - The name of the namespace Service Bus belongs to.

    3. name - The queue or topic name.

    4. subscription-name - The name of the topic subscription. Only for TOPIC channel type.

Steps

Send message

Send message to the specified Azure Service Bus Queue or Topic.

When I send message to `$serviceBusKey` service bus with payload:`$payload`

  • $serviceBusKey - The key associated with the Azure Service Bus connection configuration, will be used to find required properties values.

  • $payload - Message to send to the service bus.

Example 2. Send simple message to the Service Bus Queue
When I send message to `myProjectQueue` service bus with payload:`Hello World!`

Start consuming messages

Starts Azure Service Bus consumer with the provided configuration to listen the specified Queue or Topic.

The consumer must be stopped when it’s not used. 
When I start consuming messages from `$serviceBusKey` service bus

  • $serviceBusKey - The key associated with the Azure Service Bus connection configuration, will be used to find required properties values.

Example 3. Start consuming messages from the topic configured by Service Bus key myProjectTopic
When I start consuming messages from `myProjectTopic` service bus

Stop consuming messages

Stops Azure Service Bus consumer started by the Start consuming messages step before.

All recorded messages are kept and can be drained into the variable using the step Save messages to the variable.

When I stop consuming messages from `$serviceBusKey` service bus

  • $serviceBusKey - The key associated with the Azure Service Bus connection configuration, will be used to find required properties values.

Example 4. Stop consuming messages from the topic configured by Service Bus key myProjectTopic
When I stop consuming messages from `myProjectTopic` service bus

Wait for the messages

Waits until the count of the consumed messages (from the consumer start or after the last draining operation) matches to the rule or until the timeout is exceeded.

When I wait with `$timeout` timeout until count of consumed `$serviceBusKey` service bus messages is $comparisonRule `$expectedCount`

  • $timeout - The maximum time to wait for the events in ISO-8601 Durations format.

  • $serviceBusKey - The key associated with Azure Service Bus connection configuration, will be used to find required properties values.

  • $comparisonRule - The comparison rule.

  • $expectedCount - The expected count of the events to be matched by the rule.

Example 5. Wait for at least 5 messages from the queue for 30 seconds
When I wait with `PT30S` timeout until count of consumed `myProjectQueue` service bus messages is >= `5`

Save messages to the variable

Drains/Peeks the consumed messages to the specified variable. If the consumer is not stopped, the new events might arrive after the draining. If the consumer is stopped, all the events received from the consumer start or after the last draining operation are stored to the variable.

When I $operation consumed `$serviceBusKey` service bus messages to $scopes variable `$variableName`

  • $operation - operation under the consumed messages, one of:

    • DRAIN - saves the messages consumed since the last drain or from the consumption start and moves the consumer cursor to the position after the last consumed message;

    • PEEK - saves the messages consumed since the last drain or from the consumption start and doesn’t change the consumer cursor position.

  • $serviceBusKey - The key associated with Azure Service Bus connection configuration, will be used to find required properties values.

  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The variable name to store the messages. The messages are accessible via zero-based index, e.g. ${my-var[0]} will return the first received message.

Example 6. Peek and drain messages from the consumer, save them to variables, and compare each other
When I start consuming messages from `myProjectTopic` service bus
When I DRAIN consumed `myProjectTopic` service bus messages to STORY variable `drained-messages`
!-- Perform any actions triggering the publishing of events to Kafka
When I PEEK consumed `myProjectTopic` service bus messages to STORY variable `peeked-messages`
When I stop consuming messages from `myProjectTopic` service bus
Then `${drained-messages[0]}` is not equal to `${peeked-messages[0]}`

Examples

Example 7. Consume messages from the Service Bus topic
When I start consuming messages from `myProjectTopic` service bus
When I wait with `PT30S` timeout until count of consumed `myProjectTopic` service bus messages is >= `2`
When I stop consuming messages from `myProjectTopic` service bus
When I DRAIN consumed `myProjectTopic` service bus messages to STORY variable `drained-messages`
Then `${drained-messages[0]}` is equal to `some-expected-event`
Example 8. Drain messages while the Service Bus consumer is running
When I send message to `myProjectTopic` service bus with payload:`First message`
When I start consuming messages from `myProjectTopic` service bus
When I DRAIN consumed `myProjectTopic` service bus messages to SCENARIO variable `first-drain-messages`
When I send message to `myProjectTopic` service bus with payload:`Second message`
When I DRAIN consumed `myProjectTopic` service bus messages to SCENARIO variable `second-drain-messages`
When I stop consuming messages from `myProjectTopic` service bus
Then `${first-drain-messages[0]}` is not equal to `${second-drain-messages[0]}`
Example 9. Peek messages while the Service Bus consumer is running
When I send message to `myProjectQueue` service bus with payload:`Hello World!`
When I start consuming messages from `myProjectTopic` service bus
When I PEEK consumed `myProjectQueue` service bus messages to SCENARIO variable `peeked-messages`
When I stop consuming messages from `myProjectTopic` service bus
Then `${peeked-messages[0]}` is equal to `Hello World!`