How to read / write published IS documents from / to Universal Messaging?

, ,
#1

Hello,

are there descriptions / code samples of how to send messages to Universal Messaging so that they can be read by the IntegrationServer and interpreted as published documents (with trigger activation in the IS etc)?

And the other way around: How is it possible to read and interpret (extract data) a document published by the IntegrationServer to Universal Messaging?

We try to integrate an existing webMethods application with a non-wM application.

The only thread I could found on this topic is this one: How to publish "document on IS" to UM by java code?. But unfortunately it’s not much of a help.

Any hints will be much appreciated.

#2

Hey,

So the general approach is use JMS for interop, this allows JMS triggers both to and from nonWM applications similar to that link you provided

I am assuming your non WM app cannot be connected to directly from IS because if it could be then IS connecting direct is the simplest approach.

As for samples, I am not so sure they will be available however is it something specific you would like a sample like the trigger package for consuming generic JMS?

Joshua

#3

Hello Joshua,

But it’s still unclear to me how to read the data from the event. It’s encoded using google proto buf, right? How can I know how the internal IS documents are mapped to proto bufs?

Do you mean that we could call IS services directly?

Cheers

#4

Hey,

Indeed, the payload format that both IS and UM understand is google protocol buffers, so as a prerequisite, your document type should be using protobuf encoding in IS (and not IData). Generally speaking, there are two ways to work with a protobuf message. One is to generate a type/stub from a protobuf definition, much similar to how you can generate a stub from an xml schema for a web service call for example. The second option is to approach it as a generic structured document, similar to what a document type in IS looks like. I am assuming you are after the second approach.

In UM native API, the way to handle protobuf events is by using the nProtobufEvent class, which is a subclass of the standard nConsumeEvent. If you’ve published a protobuf encoded event from IS, you should be able to typecast it to nProtobufEvent when you handle it through the UM native API (regardless of whether you are using Java, C# or C++). From this point on, you will need to unmarshall the protobuf payload into a structured document. UM will not do that automatically and in fact most of the time this is not needed.
In order to unmarshall the payload you will need the protobuf definition which can be obtained from the channel attributes (com.pcbsys.nirvana.client.nChannelAttributes#getProtobufDescriptorSets).
The protobuf descriptor is actually a compiled binary itself, and technically one channel can hold several descriptors. Ultimately the goal is to get a com.google.protobuf.Descriptors.Descriptor and build a protobuf DynamicMessage out of it using the protobuf API - DynamicMessage.parseFrom(descriptor, payload), where the payload is com.pcbsys.nirvana.client.nProtobufEvent#getEventData() and the descriptor is the one that corresponds to the event root type (com.pcbsys.nirvana.client.nProtobufEvent#getAttributes().getType()). Once you have a protobuf DynamicMessage you can traverse its attributes as a generic structured document.
Building the descriptors can get quite complex due to a potentially nested structure with multiple complex types and various references between them. The safest approach is to load all definitions in your descriptor. I believe that you can also obtain the definitions from IS - I believe it can store them in files on disk when certain debug option is switched on. You can store them in files after extracting them from the UM channel too, and then load them up using com.google.protobuf.DescriptorProtos.FileDescriptorSet#newBuilder()
In runtime I wouldn’t expect that the protobuf definitions would change frequently (if at all), so it wouldn’t make sense to build these descriptor for every event, but rather maintain a cache. This is how the Enterprise Manager works for example. Unfortunately it’s not a public API that can be exposed.

I searched around but unfortunately I couldn’t find ready-to-use samples. I’ll see if I can get something written up, but it might take some time.

Thanks,
Stefan

2 Likes
#5

Stefan, thank you very much for this wonderful reply! I have not done anything yet, but I think it contains all the necessary informations.

If you’ll find time to write a small example, it would be awesome, but I think event the hints in your last post will be enough.

May I ask you one more question? You wrote “The protobuf descriptor is actually a compiled binary itself”. How can I parse the descriptor? Is it a standard google protobuf format or is it a format devised by SoftwareAG? Also, in publishable doc types in IS, there is the attribute protoBufDescriptor. Is it the descriptor we’re talking about?

Thank you again.

#6

Hey, sorry, I was away for a while.
It should be standard protobuf format. I think IS generates a text file descriptor (.proto file) out of a document type definition, and then uses the protobuf compiler (protoc) to build the binary descriptor file. This binary descriptor is what you need in runtime to marshall/unmarshall the payloads, and it is that same binary that IS would push to UM when you sync a document type from designer.

Thanks,
Stefan