Using the Messaging-Service

The messaging-service allows other services to share information among themselves and with other services, such as the core-service (DMS service). In this way, services can react to DMS events such as Document created/updated/deleted.

The Messaging Service is a JMS provider and currently runs as an internal Apache ActiveMQ instance.

1 Connecting a Service to the Messaging-Service
- 1.1 JMX dependencies in pom.xml
2 Configuring a Service to Respond to Events
- 2.1 Example: JMS Topic-Listener
3 Defining Custom Messaging Queues
- 3.1 messaging-prod.yml
4 Supported Topics
- 4.1 Since version 9.6.0
- 4.2 or 8.16.43 of the
- 4.3 service-manager:

Connecting a Service to the Messaging-Service

To connect a service deployed in yuuvis® RAD service-manager to the messaging-service, define the following JMS-specific dependencies in its pom.xml.

JMX dependencies in pom.xml

<!-- enable jms support e.g. listen for topics -->
<dependency>
     <groupId>org.springframework</groupId>
     <artifactId>spring-jms</artifactId>
</dependency>
<dependency>
     <groupId>org.apache.activemq</groupId>
     <artifactId>activemq-broker</artifactId>
 </dependency>
<dependency>
     <groupId>org.apache.activemq</groupId>
     <artifactId>activemq-camel</artifactId>
 </dependency>

A microservice that wants to connect to the messaging-service must be started with the mq profile. In this profile, the following required properties are defined.

spring.activemq.broker-url: 'tcp://127.0.0.1:61616'
spring.activemq.in-memory: false
spring.activemq.pooled: true
# for listening to topics:
spring.jms.pubSubDomain: true
# for listening to queues:
#spring.jms.pubSubDomain: false

The spring.jms.pubSubDomain: true property causes the destination specified in the JMS listener to refer to a topic and not to a queue.

Configuring a Service to Respond to Events

To consume messages, set up a JMS listener. The following example creates a topic listener that responds to the creation of DMS objects in the DMS Service.

Example: JMS Topic-Listener

 @JmsListener(destination = "documentChanged")
    public void readMessage(String messageText)
    {
        try
        {
            Object object = new ObjectMapper().readValue(messageText, Object.class);
            if (object != null && object instanceof Map)
            {
                @SuppressWarnings("unchecked")
                Map<String, Object> messagesBody = (Map<String, Object>)object;
                if (messagesBody.get("messages") != null && messagesBody.get("messages") instanceof List)
                {
                    List<?> messages = (List<?>)messagesBody.get("messages");
                    for (Object message : messages)
                    {
                        Map<?, ?> messageBody = (Map<?, ?>)message;
                        this.processMessage(messageBody);
                    }
                }
                else
                {
                    this.processMessage(messagesBody);
                }
            }
        }
        catch (Exception e)
        {
            LOGGER.info(e.getMessage());
        }
    }

The core-service sends its messages bundled as block messages. To be able to process each message separately, these block messages must be split, as shown in the example.
The messaging-service always keeps a message as a plain text message in JSON format.

Defining Custom Messaging Queues

Beginning with version 8.16, to define your own events and queues the configuration of the messaging-service must be extended.
You can add your own queues in the messaging-prod.yml file:

messaging-prod.yml

customqueue:
  - name: myQ1
    event: fileChanged
  - name: myQ2
    event: myOwnEvent,mySecondEvent,fileChanged

The defined events are case-sensitive.

Supported Topics

The following table lists currently-supported topics and the structure of their messages.

Topic	Message	Description
documentChanged indexDataChanged Since version 9.6.0 or 8.16.43 of the service-manager: renditionText	`{ "itemid" : "4D5678653345678", "typeid" : "34522456755ABDE", "typename" : "kundenakte", "versionid" : "675849384758694", "version" : 1 "action" : "update" OR "new" "messageid" : "45678454ABABABA", (cond. "disableQueing": "false"), (cond. "isrenditiontextenabled" : "false") }`	If a dms-object with content-file is created or the content-file is changed, a message with the topic documentChanged is sent. If a dms-object is created or its metadata is changed, a message with the topic indexDataChanged is sent. If both metadata and content-file are created or changed in an update, messages for both topics are sent. The `version` field informs if the dms-object was created or updated: If the value of `version` is equal to `1`, a dms-object is created and `action` will have the value `new`. If a dms-object is updated (`version` > 1), `action` will have the value `update`. If a dms-object (with or without content-file) is deleted (hard), then a message with the topic documentDeleted is sent - see further below. If rendition-plus extracted fulltext from the content-file, the renditionText message is sent (fulltext can be fetched from rest-ws endpoint DmsService.getItemContent with parameter "rendition" set to "TEXT". This message is also sent (again) if a subsequent full-text indexing operation is run with "perform content file export" parameter set to true or if the rendition is created again - if pushed out of the cache or manually deleted.
journalObjectCreated	`{ "itemid" : "4D5678653345678", "typeid" : "34522456755ABDE", "typename" : "kundenakte", "versionid" : "675849384758694", "action" : "new" "messageid" : "45678454ABABABA", "indexDataMap": { "label1": "value1", "label2": "value2"} (cond. "contenttext": "text") }`
contentLinkCreated	`{ "messageid" : "45678454ABABABA", "action" : "contentLinkCreated", "itemid" : "4D5678653345678", "version" : 1, "versionid" : "675849384758694" }` `{ "messageid" : "45678454ABABABA", "action" : "contentLinkCreated", "itemid" : "4D5678653345678", "version" : 1, "versionid" : "675849384758694", "contentid" : "234234234234234", "sourcecontentlinkedcount": 3, "modified" : "2023-02-17T12:36:21+00:00", "modifierid": "1D23F87G34897", "modifier" : "name", "modifiertitle": "" }`
technicalUpdate	`{ "itemid" : "4D5678653345678", "typename" : "kundenakte", "islocationchanged" : "false", "acl" : ["...", "..."], "aclchanged" : "true", "messageid" : "45678454ABABABA" }` `{ "typename" : "kundenakte", "islocationchanged" : "false", "aclchanged" : "true" }`
inboxChanged	`{ "type" : "resubmission"/"subscription" "action": "create"/"update"/"delete" "userid": "45678454ABABABA" "ids" : ["1..23", "45..24"] }` `{ "type" : "workflow", "userid" : "45678454ABABABA", "refreshedItems": ["1..23", "45..24"], "removedItems" : ["1..23", "45..24"] }`
fileChanged		The process file of a workflow (bpm) instance was changed.
documentDeleted	`{ "itemid" : "4D5678653345678", "typeid" : "34522456755ABDE", "action" : "delete" "messageid" : "45678454ABABABA" }`	This message is sent if a dms-object and/or content-file is deleted hard (i.e. not into the recycle bin).
redServerChanged	`{"ORGANISATION_CHANGED" : "Date"}` `{"SECURITY_SYSTEM_CHANGED" : "Date"}` `{"USER_ACL_CHANGED" : null}` `{"SERVER_SHUTDOWN" : ""}` `{"SERVER_START" : ""}` `{"SCHEMA_CHANGED" : ""}`	These are DMS service events that indicate that the system status has been changed. This includes: Organization changed Security system changed DMS service stopped/started Schema definition changed