Define additional actions triggered by specified events, extend the functionality of yuuvis® Momentum API.

Introduction

System Hooks are functions that apply to core functions of the yuuvis® Momentum API whenever certain conditions are met and that extend or modify those functions. As such, they serve as a modular, external approach for introducing new functionalities as extensions of already existing ones. There are two different types of System Hooks available: AMQP Hooks as a pure messaging tool, and Webhooks with multiple possibilities.

System Hooks

The System Hooks catch the call for a function under certain conditions in order to extend or modify the requested process. Thus, it is possible to externalize functional extensions or modularize components of the function call. In order to react to a function call under a certain condition, the latter is defined as a parameter for the corresponding System Hook in its predicate attribute. The set of conditions that need to be met in order for a System Hook to activate are defined in a SpEL (Spring Expression Language) statement that needs to yield a True result in order to trigger the System Hook.

System Hook Configuration

System Hooks are configured in the \service-manager\config\system\systemHookConfiguration.json configuration file within the service manager in JSON format. Any changes to the System Hook configuration will not apply until the affected services have been restarted.

System Hook Types

Two different types of System Hooks can be used in yuuvis® Momentum, that support two different application  types. Both of them react to function calls under a specified condition defined in SpEL, but their behavior after activation is completely different.

AMQP Hooks

AMQP stands for Advanced Message Queuing Protocol 1.0, which is the encoding scheme the AMQP Hooks are working with. AMQP Hooks are used to generate messages for the AMQP messaging systems whenever any relevant function is performed. They're instantiated using the URL and credentials for an existing messaging queue. The process flow itself is proceeding at the same time and can not be modified with an AMQP Hook.

Any changes to the AMQP Hook configuration require a restart of the API-gateway service. More on AMQP Hooks can be found here.

Webhooks

A Webhook extends the function by an HTTP call. Whenever the predicate of a Webhook delivers a True result, an optional HTTP call to a web URL defined in the Webhook configuration is performed. The process flow is interrupted until the Webhook activity is finished. Thus, the Webhook can perform additional processing steps before passing the data back to resume the interrupted main process. If the predicate of a Webhook delivers a False result, the HTTP call is skipped.

Any changes to the Webhook configuration require a restart of the services, that are responsable for the call of the affected functions. More on Webhooks can be found here.

System Hook Configuration Example

The following example configures both an AMQP Hook and a Webhook.

• The AMQP Hook applies to object imports and checks the contentStreams for the presence of a range attribute. Should the range attribute be detected, the AMQP Hook recognizes the imported content to be a compound document and initiates asynchronous text extraction of all the content parts.
• The example Webhook activates at every login and retrieves the roles of the user trying to authenticate  authorize (permissions)?.

To activate this configuration, both the API-gateway and the Authentication service need to be restarted. 

{
    "systemhooks": {
        "amqp": [
            {
                "bulkSize": 10,
                "enable": true,
                "password": "secret",
                "predicate": "spel:(contentStreams != null && contentStreams.size() > 0 && contentStreams[0]['range'] != null && contentStreams[0]['range'].length() > 0) ? true : false",
                "queue": "lc.textextraction",
                "type": "object.insert.document",
                "url": "10.10.6.242:5672",
                "user": "clouduser"
            }
        ],
        "webhooks": [
            {
                "enable": true,
                "predicate": "spel:true",
                "type": "user.info",
                "url": "http://organization/api/userinfo/${tenant}/${userId}"
            }
        ]
    }
}

Summary

This article gave an introduction into the concept of System Hooks in yuuvis® Momentum. Detailed information on the two different types of System Hooks available can be found in the specific articles: "AMQP Hooks" and "Webhooks". An example configuration of Webhooks is shown in the "Preprocessing Metadata using Webhooks" tutorial.