Skip to main content
Version: TeamForge 24.0

TeamForge Webhooks-based Event Broker Overview

important

Usage of the TeamForge Webhooks-based Event Broker outside of TeamForge is not supported, as it is bundled with TeamForge and is only supported for TeamForge webhook integration.

Features​

The current release, called the V4 Engine is the new version of the TeamForge Webhooks-based Event Broker, delivered as part of TeamForge 19.3. It provides the following features:

Event registration
Subscriber and Subscription registration
Publisher registration
Topics, Queues, and Sync events
Guaranteed, once and once-only, in-order delivery
Message, Header, URL and Method transformation capabilities
Message callback support for asynchronous load-balanced long-running jobs
Sophisticated JSON subscription filters for both Header and content based filtering of messages
In-built ES5 compliant JavaScript engine for message transformations and synchronous responses, business rules execution, and orchestration.

Events​

An event in WEBR is basically a message type. Examples of events include:

  • Artifact create (TeamForge.Artifact.Create) or Artifact update (TeamForge.Artifact.Update) in TeamForge
  • Build event in Jenkins
  • Defect being filed in Jira (JIRA.Bug.Create), and so on

Where, TeamForge.Artifact.Create and JIRA.Bug.Create are the event names in WEBR. Every message published to WEBR should be tagged with an event name.

Events to be published through the TeamForge Webhooks-based Event Broker must be registered. Registering an event is required before you register the publisher or subscriber.

An event has the following key properties:

  • a unique Event Name
  • Content Type (Example: application/json)
  • Event Type (TOPIC/QUEUE/SYNC)
  • Event Format—This is a sample event that is used to understand the encoding and format of the message. JSON messages are validated. There is no message schema support.

Event Types​

This table provides the supported event types—TOPIC, SYNC, and QUEUE.

Event TypeDescription
TOPIC (Post-Submit)
  • These message types are typically to be used for post-submit scenarios.
  • Each event can be subscribed to by multiple subscribers and subscriptions.
  • The message is delivered to all the subscription endpoints.
SYNC (Pre-Submit)
  • These are used for pre-submit scenarios, typically to externalize business rules.
  • Subscriptions are restricted to only one. However, subscription filters can be used to maintain multiple subscription endpoints. In such cases, one single subscription endpoint is resolved at runtime.
  • The publisher is guaranteed to get the response from the subscription endpoint synchronously.
QUEUE
  • These message types are used for Web API driven load balancing.
  • Subscriptions are grouped by filters.
  • Only one subscription in a subscription group will be delivered the message.

Publishers​

Publishers publish events. In the case of the TeamForge Webhooks-based Event Broker, a Publisher can be equated to an application. Example: TeamForge, Ossum, JIRA, Jenkins, Nexus.

Each registered publisher gets a unique ID. This ID is used while publishing messages to WEBR.

Subscribers​

Subscribers subscribe to and receive messages. Subscribers in the TeamForge Webhooks-based Event Broker equated to applications. Example: TeamForge, Ossum, JIRA, Jenkins, Nexus.

Subscriptions​

Each subscriber can have several subscriptions per event. Each subscription consists of the following critical properties:

  • Subscriber
  • Event Name
  • Webhook Endpoint URL—This can be an external URL or an internal endpoint such as webr:// (which is used internally by the pre-submit webhooks to deliver the message to the internal ES5 compliant Javascript virtual machine for executing the business rules) or orch://<orchname> (to run an orchestration script).
  • Header and content based subscription filter. For more information on subscription filter, see Scripts and Filters in the TeamForge Webhooks-based Event Broker.
  • Headers to be passed to the URL, typically only external webhook endpoint URLs.
  • For TOPIC subscriptions, a "Transform script" can be provided if message transformation is required. For more information on transform script, see Scripts and Filters in the TeamForge Webhooks-based Event Broker.
  • For SYNC subscriptions, if the response is embedded with the TeamForge Webhooks-based Event Broker using the "Internal JSVM" (internal JavaScript Virtual Machine), a response script can be provided. For more information on response script, see Scripts and Filters in the TeamForge Webhooks-based Event Broker.

TeamForge Integrations Using the TeamForge Webhooks-based Event Broker​

TeamForge can be integrated with Jenkins, JIRA, TestLink, and Nexus using the TeamForge Webhooks-based Event Broker.

For more information, see: