Versions Compared

Key

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

...

Ressources

  • Xxx

Remarks

concept article linking to the respective tutorials

Page Properties
hiddentrue
Status
Status
colourYellow
titlePROGRESS
Priority1
Note
AssigneeAntje
Excerpt

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

...

bordertrue
Column

Table of Contents

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 (question)metadata which is the target of the function call triggering the AMQP Hook. The action code is included in there (question) in 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 (question) kann ich das irgendwo in der Endpunktdoku dann erkennen?.

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

...

Type

...

Description

...

enable

...

predicate

...

condition that specifies when the system hook is used
supported scripting languages: SpEL (Spring Expression Language) and Javascript. 

...

type

...

url

...

user

...

password

...

queue

...

bulkSize

...

Example Configuration

The parameters of the AMQP Hook are specified in JSON format. In the configuration file (question) ich würde den hier auch noch mal nennen, 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 service.

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 service 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.

{ "systemhooks
Code Block
titlesystemHookConfiguration.json
linenumberstrue
idDONE

Product Version
Report Note
Assignee

Resources & Remarks

Modification History

NameDateProduct VersionAction
Antje08 FEB 20212.4New page properties macro.



Please exchange the previous denomination (object.insert.document) by the current denomination (dms.response.insert). The old denomination will not be supported in yuuvis® Momentum 2.4 anymore.

As of Version2019 Winter
DescriptionObject creation events can trigger this AMQP Hook with the corresponding object properties in its body.
Example 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 Codes101 - OBJECT_CREATED_WITH_CONTENT
100 - OBJECT_CREATED
Example Message


Code Block
languageyml
{
    "objects": [      
        {
            "properties": {
                "system:objectId": {
                    "value": "333c226c-3a44-5e66-7777-8d999a0000e1"
                },
                "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"
          

...

     

...

 }

...

Activating the AMQP Hook

In our example of asynchronous full-text indexing, the API-gateway service is responsible for evaluating the system hook. To apply the configuration, the API-gateway service must be restarted after saving the configuration file. Messages will then be send to the messaging system (question) haben wir hier was zur Installation for the import of compound documents.

AMQP Hook Types

dms.response.insert (previous object.insert.document)

Please exchange the previous denomination (object.insert.document) by the current denomination (dms.response.insert). The old denomination will not be supported in yuuvis® Momentum 2.4 anymore.

Response FormatJSON
DescriptionObject creation events can trigger this AMQP Hook with the corresponding object properties in its body.
Example 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 Codes101 - OBJECT_CREATED_WITH_CONTENT
100 - OBJECT_CREATED
Example Response
Code Block
languageyml
{
    "objects": [,
                "system:traceId": {
                    "value": "1234567887654321"
                },
                "Name": {
                    "value": "test.eml"
                }
            },
            "contentStreams": [
                {
                    "contentStreamId": "0AB98765-CDEF-4321-ABCD-098EF76AB543",
                    "archivePath": "default/DOCUMENT/32/15/7/",
              {      "length": 82683,
     "properties": {
                "system:objectIdmimeType": {
"message/rfc822",
                    "valuefileName": "333c226c-3a44-5e66-7777-8d999a0000e1"test.eml",
                     },"digest": "12345678123456781234567812345678123456781234567812345678",
                    "system:baseTypeIdrange": {"1234-12345,123456-123458,123489-234567,245678-345678",
                    "valuerepositoryId": "system:documentrepo252"
                },
            ],

  "system:objectTypeId": {         "options": {
             "valueaction": "document"101,
             "detail": "OBJECT_CREATED_WITH_CONTENT"

},           }      "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

...

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

...

Code Block
languageyml
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": "333c226c-3a44-5e66-7777-8d999a0000e1"
                },
                "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": "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/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": 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": "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/D2/AD/7/",
                    "length": 82683,
                    "mimeType": "message/rfc822",
                    "fileName": "test.eml",
                    "digest": "12345678123456781234567812345678123456781234567812345678",
                    "range": "1234-12345,123456-123458,123489-234567,245678-345678",
                    "repositoryId": "repo252"
                }
            ]

  }
   

           }       

        }
    ]
}

dms.response.delete

...

1) reaction to every object deletion:
spel:true

2) reaction to every object deletion of type document:
spel:properties['system:objectTypeId']['value']=='document'

3) reaction to every failed deletion of objects that were flagged for deletion:
spel:options['action']==202

...

Code Block
languageyml
{
    "objects": [      
        {
            "properties": {
                "system:objectId": {
                    "value": "333c226c-3a44-5e66-7777-8d999a0000e1"
                },
                "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": "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": "0AB98765-CDEF-4321-ABCD-098EF76AB543",
                    "archivePath": "default/DOCUMENT/32/15/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

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

...

iconfalse

Read on

...

width25%

System Hooks

...

width25%

Webhooks

...

]
}