Integrate Software AG Products Using Digital Event Services : MashZone NextGen Explorer Administration : Configure DES data source : DesEventBroker microservice API
DesEventBroker microservice API
The DesEventBroker microservice provides subscribe and unsubscribe methods for subscribing for events of a configured event type and append them to a topic hosted by a Kafka instance and for deleting the subscription again.
Subscribe method
The subscribe method takes a SubscriptionRequest specifying the desired subscription and returns an according SubscriptionResponse.
SubscriptionRequest
A SubscriptionRequest is a JSON object having the following properties.
Property Name
Type
Description
Default Value
SubscriptionRequest
kafkaConfiguration
JSON
Object
The property for configuring the Kafka topic the received events should be appended to.
Mandatory: No
see KafkaConfiguration
transformer Configuration
JSON
Object
The property for configuring the transformation of received events to records that can be written to Kafka.
Mandatory: No
see TransformerConfiguration
universal MessagingUrl
String
The property for specifying the URL of the Universal Messaging instance used for sending events.
Mandatory: Yes
"nsp://localhost:9000"
eventTypeName
String
The property for specifying the event type that should be subscribed.
Mandatory: Yes
KafkaConfiguration
bootstrapServers
String
For detailed information please refer the Apache Kafka documentation.
Mandatory: No
"localhost:19004"
acks
String
"1"
retries
Integer
0
batchSize
Integer
16 * 1024
lingerMs
Integer
0
bufferMemory
Integer
32 * 1024 * 1024
keySerializerClass Name
String
"org.apache.kafka. common.serialization. StringSerializer"
valueSerializerClass Name
String
"org.apache.kafka. common.serialization. ByteArraySerializer"
TransformerConfiguration
topic
String
Specifies the topic a received and transformed event should be appended to.
The configuration property topic specifies the name of the Kafka topic.
The configuration property topicFactoryClassName specifies a class that maps events to topic names and implements the com.softwareag.va. des.factories.EventFunction interface.
The configuration of both topic and topicFactoryClassName is not allowed.
If neither topic nor topicFactoryClassName is configured a topic with the configured eventTyeName is used for appending received and transformed events.
Mandatory: No
topicFactoryClass Name
String
Property Name
Type
Description
Default Value
partition
Integer
Specifies the partition to which a received and transformed event should be sent.
The configuration property partition specifies the partition.
The configuration property partitionFactoryClassName specifies a class that maps events to partitions and implements the com.softwareag. va.des.factories. EventFunction interface.
The configuration of both partition and partitionFactoryClassName is not allowed.
If neither partition nor partitionFactoryClassName is configured but a key is present a partition will be chosen using a hash of the key. If neither key nor partition is present a partition will be assigned in a round-robin fashion.
Mandatory: No
partitionFactory ClassName
String
timestampField
String
Specifies the timestamp of a received and transformed event.
The configuration property timestampField specifies the name of the event type's field holding the timestamp information. The field must be of type TIME.
The configuration property timestampFactoryClassName specifies a class that maps events to Java epoch timestamps and implements the com.softwareag.va. des.factories.EventFunction interface.
The configuration of both timestampField and timestampFactoryClassName is not allowed.
If neither timestampField nor timestampFactoryClassName is configured, the received and transformed events are stamped with current system time.
Mandatory: No
timestampFactory ClassName
String
keyField
String
Specifies the key of a received and transformed event.
The configuration property keyField specifies the name of the event type's field holding the key.
The configuration property keyFactoryClassName specifies a class that maps events to keys and implements the com.softwareag.va. des.factories. EventFunction interface.
The configuration of both keyField and keyFactoryClassName is not allowed.
If neither keyField nor keyFactoryClassName is configured, the received and transformed events will have no key.
Mandatory: No
keyFactory ClassName
String
valueFactory ClassName
String
Specifies a class that maps events to values and implements the com.softwareag. va.des.factories. EventFunction interface.
If not configured, the value of the received and transformed events will be the serialized event itself.
Mandatory: No
"com.softwareag.va. des.factories. Serialized BytesValueFactory"
The default values of SubscriptionRequest are sufficient if events are received via the default UniversalMessaging and written to embedded Kafka. In this case only the name of the event type that should be subscribed has to be specified.
{
"eventTypeName" : "<fully qualified name of the event type
to be subscribed>"
}
Due to the provided default values this SubscriptionRquest is equivalent to the following SubscriptionRequest.
{
"kafkaConfiguration" : {
"bootstrapServers" : "localhost:19004",
"acks" : "1",
"retries" : 0,
"batchSize" : 16384,
"lingerMs" : 0,
"bufferMemory" : 33554432,
"keySerializerClassName" : "org.apache.kafka.common.
serialization.StringSerializer",
"valueSerializerClassName" : "org.apache.kafka.common.
serialization.ByteArraySerializer"
},
"transformerConfiguration" : {
"topic" : "<fully qualified name of the event
type to be subscribed>",
"valueFactoryClassName" : "com.softwareag.va.des.factories.
SerializedBytesValueFactory"
},
"universalMessagingUrl" : "nsp://localhost:9000",
"eventTypeName" : "<fully qualified name of the event
type to be subscribed>"
}
If the events are not received via the default UniversalMessaging or written to a Kafka instance not running on localhost:19004 or the transformation needs to be reconfigured adapt the SubscriptionRequest accordingly.
SubscriptionResponse
A SubscriptionResponse is an empty JSON object.
Unsubscribe method
The unsubscribe method takes an UnsubscriptionRequest specifying the subscription to be removed and returns an according UnsubscriptionResponse.
UnsubscriptionRequest
An UnsubscriptionRequest is a JSON object having the following properties.
Property Name
Type
Description
Default Value
eventTypeName
String
The property for specifying the event type that should be unsubscribed.
Mandatory: Yes
An UnsubscriptionRequest looks as follows.
{
"eventTypeName" : "<fully qualified name of the event type
to be subscribed>"
}
UnsubscriptionResponse
An UnsubscriptionResponse is an empty JSON object.
Configuration of the real-time data source
After subscribing for events of configured event types corresponding real-time data sources can be deployed to VA. In order to achieve this goal JSON files describing the real-time data sources have to be placed in the <MashZone NextGen installation>/VisualAnalytics/data/auto-deploy/stream directory for each subscribed DES event type. The JSON file must contain a single JSON object which supports the following properties.
Property Name
Type
Description
Default Value
zookeeperInstances
String
A comma-separated list of Zookeeper servers, e.g., localhost:2181,localhost:2182.
Mandatory: No
zookeeper.urls configured in VA server or "127.0.0.1:19003" if not configured
brokerInstances
String
For detailed information please refer the Apache Kafka documentation.
Mandatory: No
kafka.bootstrap.servers configured in VA server or "127.0.0.1:19004" if not configured
topicName
String
The property specifying the name of the topic used for polling events.
Mandatory: No
messageType
repositoryRoot
String
The property pointing to the common root of the annotation repository and the type repository
Mandatory: No
"../../common/DigitalEventServices/TypeRepository"
messageType
String
The property for specifying the name of the event type that should be analyzed.
Mandatory: Yes
windowSize
Long
The size of the temporal window used for aggregating in milliseconds.
Mandatory: Yes
The supported default values are sufficient if events are written to MashZone NextGen Explorer embedded Kafka and DES and MashZone NextGen Explorer are installed in the same SoftwareAG directory. In this case only the name of the event type that should be analyzed and the size of the temporal window has to be specified.
{
"messageType" : "<fully qualified name of the subscribed
event type>",
"windowSize" : 60000
}
Due to the provided default values this JSON object is equivalent to the following JSON object.
{
"zookeeperInstances" : "127.0.0.1:19003",
"brokerInstances" : "127.0.0.1:19004",
"topicName" : "<fully qualified name of the subscribed
event type>",
"repositoryRoot" : "../../common/DigitalEventServices/TypeRepository",
"messageType" : "<fully qualified name of the subscribed
event type>",
"windowSize" : 60000
}
If the events are not written to a Kafka instance not running on localhost:19004 or DES and MashZone NextGen Explorer are not installed in the same SoftwareAG directory adapt the JSON object accordingly.
Copyright © 2017 Software AG, Darmstadt, Germany.
Product LogoContact Support   |   Community   |   Feedback