Configuration of system hooks, split in AMQP hooks and webhooks.

Characteristics

Profile Name	`systemHookConfiguration.json`
Referenced by Services	`authentication,api,commander`
Storage Location	global configuration file: Git `system` directory app-specific configuration files (as of 2022 Summer): Git `apps/<app` `name>/system` directory

Parameters

Parameter Section	Parameter	Type	Description
`amqp`		List of mappings in JSON format.	List of single AMQP Hook configurations each of them defined via following parameters. Read by API gateway and COMMANDER service. As of version 2021 Summer, placeholders can be used as provided by spring. They can reference values in the system environment including configuration files and command line arguments. The placeholders will be replaced by the referenced values of the environment variable during the starting process of the corresponding service. The syntax follows the spring placeholders: `${<reference>}`.
	`bulkSize`	`integer`	Maximum bulk size for a message.
	`enable`	`boolean`	Specifies whether this configuration is active/enabled (`true`) or inactive/disabled (`false`).
	`password`	`string`	Password for the AMQP server.
	`predicate`	`string`	Condition that specifies when the AMQP hook is used. supported scripting languages: SpEL (Spring Expression Language) and JavaScript. All properties that are available in the corresponding webhook's JSON request body can be referenced. Especially, the `options` section including the property `tenant` is available at each webhook entry point.
	`queue`	`string`	Name of the queue to which the messages are written. Only one messaging queue can be used. The messaging queue specified for the first defined AMQP hook will apply to all following AMQP hook definitions as well. The messaging system needs to support AMQP 1.0.
	`type`	`string`	Defines the processing step during which the AMQP hook will be trigger.
	`url`	`string`	AMQP server endpoint, e.g. `127.0.0.1:5672`
	`user`	`string`	Username for the AMQP server.
`webhooks`		List of mappings in JSON format.	List of single Webhook configurations each of them defined via following parameters. Read by AUTHENTICATION service and API gateway. If multiple Webhooks are registered for the same Webhook type, the predicate is applied to the original predicate target for each of them and in the order of definition.
	`enable`	`boolean`	Specifies whether this configuration is active/enabled (`true`) or inactive/disabled (`false`).
	`predicate`	`string`	Condition that specifies when the webhook is used. Supported scripting languages: SpEL (Spring Expression Language) and JavaScript. All properties that are available in the corresponding webhook's JSON request body can be referenced. Especially, the `options` section including the property `tenant` is available at each webhook entry point. >> Predicate Evaluation
	`type`	`string`	Defines the processing step during which the webhook will be trigger.
	`url`	`string`	Endpoint to be called by the webhook if the `predicate` matches.

Configuration File Management

It is possible to configure multiple system hooks having the same type. They are considered one after the other beginning from the top of the configuration file. If app-specific systemHookConfiguration.json files are specified (possible as of 2022 Summer), they are considered after the global configuration file and in alphabetical order.

The configuration files can be retrieved and updated by administrators with direct access to the git server.

As of 2022 Summer, the systemHookConfiguration.json configuration files can also be retrieved and updated via the yuuvis® Momentum endpoints listed below. The changes are applied immediately after a successful update of the configuration.

GET /api/system/systemhooks - Retrieve the global systemHookConfiguration.json.
POST /api/system/systemhooks - Update the global systemHookConfiguration.json.
POST /api/system/systemhooks/validate - Validate the global systemHookConfiguration.json.
GET /api/system/apps/{app}/systemhooks - Retrieve the app-specific systemHookConfiguration.json.
POST /api/system/apps/{app}/systemhooks - Update the app-specific systemHookConfiguration.json.
POST /api/system/tenants/{tenant}/apps/validate - Validate the app-specific systemHookConfiguration.json.

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. If the range attribute is detected, the AMQP hook recognizes the imported content to be a compound document and initiates asynchronous text extraction of all parts of the content.
This concrete example webhook triggers at every login and retrieves the roles of the user trying to authenticate.

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

As of 2022 Summer, it is also possible to apply the configuration via endpoint as described above without the necessity to manually restart affected services.

Example System Hook Configuration

{
    "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}"
            }
        ]
    }
}

systemHookConfiguration.json

Table of Contents

Characteristics

Parameters

Configuration File Management

Example