Using the Messaging-Service

Owned by Team Kolibri (Unlicensed)
Last updated: Feb 16, 2024 by Mr. Schmittberger
5 min read

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.

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. 

TopicMessageDescription

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