Page Comparison

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

StatusstatuscolourYellow

Ressources

partly described in Tutorial Extending Functionalities by using System Hooks

Page Properties

hidden

true

id

DONE

title

PROGRESS

Priority

Note

content in tutorial Extending Functionalities by using System Hooks

Assignee

Antje

Product Version
Report Note	presentable
Assignee

Resources & Remarks

concept article linking to the respective tutorials

Modification History

Name	Date	Product Version	Action
Antje	08 FEB 2021	2.4	New page properties macro.

Excerpt
System Hooks, that allow for messaging triggered by function calls under specified conditions.

...

Section

border	true

Column

Table of Contents

exclude	(Table of Contents\|Read on\|Concept of System Hooks\|Webhooks\|Another interesting Tutorial\|System Hooks)

Introduction

With an AMQP Hook, messages are sent to a configured messaging system using Advanced Message Queuing Protocol 1.0 (AMPQ). Where and when these messages are sent is defined in the System Hook configuration. Any changes to the System Hook configuration will not apply until the affected services have been restarted.

The AMQP Hooks allow for asynchronous reactions to events like object creation, update or deletion. There are different types of AMQP Hooks available, each of them specialized for selected function calls. The messages contain the properties of the object which metadata which is the target of the function call triggering the AMQP Hook. The action code is included in there in the message as the message as well as the history code that is added to the audit trail. The AMQP Hook can be triggered by any endpoint that induced the characteristic history codes of the AMQP Hook.

AMQP Hook Configuration

Parameters

The AMQP configuration is located in the amqp key under the systemhooks top-level key. It is represented as a list of one or more System Hooks whose parameters are described in the table below:

...

Parameter

Types of AMQP Hooks

Response FormatJSONDescriptionExample Predicate

1) reaction to every object creation:
spel:true

2) reaction to every object creation having a content range attribute:
spel:contentStreams[0]['range'].length() > 0

3) reaction to every object creation without content:
spel:options['action']=100

Action Codes - History Codes

AMQP Hook Type	Description

enable

booleanIs this configuration active/enabled?

predicate

string

Condition that specifies when the system hook is used. Supported scripting languages: Spring Expression Language (SpEL) und Javascript.

type

stringDefines the processing step for which the system hook is to be used.

url

stringAMQP server endpoint, e.g. 127.0.0.1:5672.

user

stringUsername for the AMQP server.

password

stringPassword for the AMQP server.

queue

stringName of the queue to which the messages are written.

bulkSize

integerMaximum bulk size for a message.

Example Configuration

The parameters of the AMQP Hook are specified in JSON format. In the configuration file, multiple AMQP Hooks can be defined in a list called amqp. It must however be observed that 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. Of course, the messaging system needs to support AMQP 1.0. Any changes to the AMQP Hook configuration require a restart of the API Gateway.

The example code below configures an AMQP Hook triggered by a document import. This configuration has exactly one System Hook, which is an AMQP Hook of the type object.insert.document. If the evaluation of the predicate for a document on import results is true (in our example only for compound documents), the API-Gateway sends a message with the metadata of the document to the defined messaging system. In addition, the configuration specifies a bulkSize of 10, i.e. for a batch import of 100 documents matching the predicate, 10 messages with 10 metadata entries per message are written to the queue named lc.textextraction.

Code Block

title	systemHookConfiguration.json
linenumbers	true

{
    "systemhooks": {
        "amqp": [
            {
                "enable": true,
                "predicate": "spel:(contentStreams != null && contentStreams.size() > 0 && contentStreams[0]['range'] != null && contentStreams[0]['range'].length() > 0) ? true : false",
                "type": "object.insert.document",
                "url": "127.0.0.1:5672",
                "user": "admin",
                "password": "admin_pwd",
                "queue": "lc.textextraction",
                "bulkSize": 10
            }
        ]
    }
}

Activating the AMQP Hook

In our example of asynchronous full-text indexing, the API-Gateway is responsible for evaluating the system hook. To apply the configuration, the API-Gateway must be restarted after saving the configuration file. Messages will then be send to the messaging system for the import of compound documents.

AMQP Hook Types

dms.response.insert

Action / History Codes
dms.response.delete	Object deletion events can trigger this AMQP Hook with the corresponding object properties in its body.	200 - OBJECT_DELETED 202 - OBJECT_FLAGGED_FOR_DELETE
dms.response.insert	Object creation events can trigger this AMQP Hook with the corresponding object properties in its body.	101 - OBJECT_CREATED_WITH_CONTENT 100 - OBJECT_CREATED

Example Response Code Blocklanguageyml

{
    "objects": [      
        {
            "properties": {
                "system:objectId": {
                    "value": "5d460d53-b471-4c07-a5a6-d9ad95bddfe4"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "document"
                },
                "system:createdBy": {
                    "value": "111c226c-3a44-5e66-7777-8d999a0000e1"
                },
                "system:creationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:lastModifiedBy": {
                    "value": "111c226c-3a44-5e66-7777-8d999a0000e5"
                },
                "system:lastModificationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "system:tenant": {
                    "value": "default"
                },
                "system:traceId": {
                    "value": "1234567887654321"
                },
                "Name": {
                    "value": "test.eml"
                }
            },
            "contentStreams": [
                {
                    "contentStreamId": "0AB98765-CDEF-4321-ABCD-098EF76AB543",
                    "archivePath": "default/DOCUMENT/32/15/7/",
                    "length": 82683,
                    "mimeType": "message/rfc822",
                    "fileName": "test.eml",
                    "digest": "12345678123456781234567812345678123456781234567812345678",
                    "range": "1234-12345,123456-123458,123489-234567,245678-345678",
                    "repositoryId": "repo252"
                }
            ],

           "options": {
             "action": 101,
             "detail": "OBJECT_CREATED_WITH_CONTENT"

           }       

        }
    ]
}

dms.response.update

Response FormatJSONDescriptionExample Predicate

1) reaction to every object update:
spel:true

2) reaction to every tag creation:
spel:options['action']==110

3) reaction to every tag deletion:
spel:options['action']==210

4) reaction to every metadata update:
spel:options['action']==300

5) reaction to every content update:
spel:options['action']==301

Action Codes - History Codes

Object update events and tag operations can trigger this AMQP Hook with the corresponding object properties in its body.

300 - OBJECT_METADATA_CHANGED
301 - OBJECT_DOCUMENT_CHANGED
325 - OBJECT_RESTORED_FROM_VERSION (as of 2022 Spring)
303 - OBJECT_UPDATE_CONTENT_MOVED
110 - OBJECT_TAG_CREATED
310 - OBJECT_TAG_UPDATED
210 - OBJECT_TAG_DELETED

Example Response

Code Block

language	yml

Dem Objekt wurde ein Tag 'ocr' hinzugefügt. Unter options ist im Attribut "previousVersion" das Dokument vor der Änderung bereitgestellt.


    "objects": [      
        {
            "properties": {
                "system:objectId": {
                    "value": "2b7a3b0a-3038-433e-96bd-493d7702b510"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "document"
                },
                "system:createdBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:creationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:lastModifiedBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:lastModificationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "system:tenant": {
                    "value": "default"
                },
                "system:traceId": {
                    "value": "e686f806ed44f37d"
                },
                "Name": {
                    "value": "test.eml"
                },
                "system:tags": {
                    "value": [["ocr", 1, "2020-09-16T16:57:40.780Z", "ce03f1c20308d77d" ]]
                }
            },
            "contentStreams": [
                {
                    "contentStreamId": "1D2AD7BA-F82B-11EA-A5EA-7FE7FFB009F6",
                    "archivePath": "default/DOCUMENT/D2/AD/7/",
                    "length": 82683,
                    "mimeType": "message/rfc822",
                    "fileName": "test.eml",
                    "digest": "2713BB70F1B3F8F556D2661286A5D45157EB723A815E1066E50F1808228075F7",
                    "range": "47578-68248,115827-136497,184076-204746,252320-272989",
                    "repositoryId": "repo252"
                }
            ],

           "options": {
             "action": 110,
             "detail": "OBJECT_TAG_CREATED",
             "previousVersion" :

{
            "properties": {
                "system:objectId": {
                    "value": "2b7a3b0a-3038-433e-96bd-493d7702b510"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "document"
                },
                "system:createdBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:creationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:lastModifiedBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:lastModificationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "system:tenant": {
                    "value": "default"
                },
                "system:traceId": {
                    "value": "e686f806ed44f37d"
                },
                "Name": {
                    "value": "test.eml"
                }
            },
            "contentStreams": [
                {
                    "contentStreamId": "1D2AD7BA-F82B-11EA-A5EA-7FE7FFB009F6",
                    "archivePath": "default/DOCUMENT/D2/AD/7/",
                    "length": 82683,
                    "mimeType": "message/rfc822",
                    "fileName": "test.eml",
                    "digest": "2713BB70F1B3F8F556D2661286A5D45157EB723A815E1066E50F1808228075F7",
                    "range": "47578-68248,115827-136497,184076-204746,252320-272989",
                    "repositoryId": "repo252"
                }
            ]

  }
   

           }       

        }
    ]
}

dms.response.insert

...

1) reaction to every object deletion:
spel:true

2) reaction to every object

3) reaction to every object

...

Code Block

language	yml

{
    "objects": [      
        {
            "properties": {
                "system:objectId": {
                    "value": "2b7a3b0a-3038-433e-96bd-493d7702b510"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "document"
                },
                "system:createdBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:creationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:lastModifiedBy": {
                    "value": "275c826c-6a61-4e89-9512-8d935a1631e5"
                },
                "system:lastModificationDate": {
                    "value": "2020-09-16T16:57:40.780Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "system:tenant": {
                    "value": "default"
                },
                "system:traceId": {
                    "value": "e686f806ed44f37d"
                },
                "Name": {
                    "value": "test.eml"
                }
            },
            "contentStreams": [
                {
                    "contentStreamId": "1D2AD7BA-F82B-11EA-A5EA-7FE7FFB009F6",
                    "archivePath": "default/DOCUMENT/D2/AD/7/",
                    "length": 82683,
                    "mimeType": "message/rfc822",
                    "fileName": "test.eml",
                    "digest": "2713BB70F1B3F8F556D2661286A5D45157EB723A815E1066E50F1808228075F7",
                    "range": "47578-68248,115827-136497,184076-204746,252320-272989",
                    "repositoryId": "repo252"
                }
            ],

           "options": {
             "action": 200,
             "detail": "OBJECT_DELETED"

           }       

        }
    ]
}

Summary

...

Configuring AMQP Hooks

As a type of system hooks, AMQP 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.

>> systemHookConfiguration.json

Summary

In this article, we gave an introduction to AMQP Hooks, covered the configuration using the example of asynchronous full text indexing . The and provide a list of all AMQP Hooks available. Check out Webhooks which are the second type of System Hooks in yuuvis® Momentum is the Webhook.

Info

icon	false

Read on

Section

Column

width	25%

System Hooks

Insert excerpt

	System Hooks
	System Hooks
nopanel	true

Keep reading

Column

width	25%

Webhooks

Insert excerpt

	Webhooks
	Webhooks
nopanel	true

Keep reading

Versions Compared

Old Version 17

New Version Current

Key

Ressources

Table of Contents

Introduction

AMQP Hook Configuration

Parameters

Types of AMQP Hooks

Example Configuration

Activating the AMQP Hook

AMQP Hook Types

dms.response.insert

dms.response.insert

Summary

Configuring AMQP Hooks

Summary

Read on

System Hooks

Webhooks