While asynchronous operations are typical uses of a message broker, synchronous responses also have specific uses in the form of externalizing application behaviour, such as executing business rules.
The TeamForge Webhooks-based Event Broker provides for SYNC events (Pre-submit). Unlike other event types where the TeamForge Webhooks-based Event Broker responds back once the message is stored within it, for SYNC messages, the TeamForge Webhooks-based Event Broker resolves subscriptions to one endpoint, invokes it, and passes back the response to the caller, along with the http status code returned by the subscription endpoint.
How it works?
Fundamental to effective usage of SYNC events is to understand their primary purpose — externalizing application behavior through business rules. Therefore, when such an event, such as
Artifact.Create.Presubmit is sent to the TeamForge Webhooks-based Event Broker, there must be only one subscription to invoke and return the response.
Hence, the TeamForge Webhooks-based Event Broker validates the subscriptions for an event as follows:
- If there is no filter specified, there can only be one subscription per SYNC event.
- If a subscription filter is provided, the TeamForge Webhooks-based Event Broker ensures that duplicate subscriptions with the same filter are not provided.
- However, at the time when subscriptions are entered, it is not possible to check whether a later incoming message could resolve to more than one subscription. Hence, such a check is done during message intake. For more information, see Message Receipts and Processing.
Message Receipts and Processing
When the TeamForge Webhooks-based Event Broker receives a SYNC event message, it first identifies all
ACTIVEsubscriptions that qualify to receive the messaes.
Subscriptions that subscribe to the event, with no filters will qualify.
If a subscription has a
HeaderFilterStringproperty, then the subscription will qualify only if the message is sent along with a http header called
FILTER_STRING, which should contain the same value as the
HeaderFilterStringproperty in the subscription. This is a pure string comparison and doesn’t involve parsing the body.
If the subscription filter is present (a subscription filter can be added in addition to the
HeaderFilterString), the filter is applied to the combined header and body of the message. For more information on the subscription filter, see Scripts and Filters in the TeamForge Webhooks-based Event Broker. If the condition evaluates to
true, then the subscription will qualify.
The expectation is that either none or one subscription will quality. If more than one subscription qualifies for the message, the TeamForge Webhooks-based Event Broker will take only the first subscription and log an error listing the multiple subscriptions that are qualified for the message.
It will check if the subscription endpoint URL is
IF subscription is internal,
$statuscodeare seeded into the VM.
The incoming http headers are parsed into a native JSON object and assigned to
The incoming message payload is assigned to
$statuscodeis set to
If the content type is
$inmessageis converted to a JSON object. Else, it is left as a string.
The script is now executed within the context of the above variables.
$outmessageis retrieved and forms the response payload.
$statuscodeis retrieved and set as the response http status code.
Response is sent bact to caller.
- The payload and headers are sent to the webhook endpoints.
- The response and return http statuses are passed back to the caller.
For the examples on how it can be used, see Scripts and Filters in TeamForge Webhooks-based Event Broker.