Integration with messaging: Command messages and Document messages

Abstract: although the concept of document message and command message is quite simple, it’s usual to see document messages used for everything.

At the highest level, integration is about communicating different applications. This communication can be performed to exchange data or functionality.
If you are doing the integration via messaging, you’ll use messages to communicate applications.

Document messages
A document message is used if the purpose of the integration is to exchange data. The most typical document messages type is an Xml document representing a data structure.

Command messages
If the purpose is to exchange functionality (that is, calling a remote method asynchronously) a command message is used. Command messages are, for example, SOAP requests. A SOAP request contains the name of the method called and the parameters needed to call that method.

Why am I pointing to such an obvious description of integration/document messages/command messages? --> because I’ve seen in many places the misuse of this concept of document vs. command.
The concepts of integration, messaging and asynchronous are relatively new, or at least, relatively popular. Most of developers have learnt to do messaging in a data interchange fashion. As a result, document messages are being used for everything, including for functionality integration.

Let’s see an example: messages to create and update records, for example, Customers:

Common practice, not very elegant:
Use a single document schema that contains the customer data. Send messages to a different endpoint for creation or update. The receiver application knows what to do with the message because it knows where it has been received.

<Customers>
<Customer id=”1234”>
<Name>Foo</Name>
<!-- more data -->
</Customer>
<Customers>

Why is this not very elegant? --> Because the message itself does not describe the purpose. The purpose is in the context. Without the context, the message has no meaning. (Agent Smith said, “Without a purpose, we would not exist” :-)

Another common practice, even worse:
Use two different document schemas, which are very similar. They contain the same data, but they are slightly different.

Document message for creation:
<CreateCustomers>
<Customer id=”1234”>
<Name>Foo</Name>
<!-- more data -->
</Customer>
</CreateCustomers>

Document message for update:
<UpdateCustomers>
<Customer id=”1234”>
<Name>Foo</Name>
<!-- more data -->
</Customer>
</UpdateCustomers>

Why is this a bad practice? --> Ok, you have two schemas for two purposes, but they contain the same data, the same structure. You can reuse schemas via Xsd Import or Xsd Include, but it’s a workaround, not a good solution.

I've seen ever entire industry-oriented document specifications with lots of almost-equal schemas for many different purposes. So you have the same Customer Name field repeated any time a name of a customer is needed... you can imagine the Xsd Import dependency tree is 5-7 levels deep.

Good practice:
In my honest opinion, you should use document messages for data, and command messages for operations. Include parameters in your command message for the values. If your operation a bunch of data, include the document message inside the command message (just as SOAP does!). So the command message is just an envelope for the document message.

Document message for customers:
<Customer id=”1234”>
<Name>Foo</Name>
<!-- more data -->
</Customer>

Command message for operations with customers:
<CustomerActionEnvelope>
<Action>CreateCustomer</Action>
<Parameters>
<!-- insert here the full customer document message -->
<Parameters>
<CustomerActionEnvelope>

In this way, data is separated from meta-data (at schema level) and dependencies are reduced.

If you think this is interesting, go to https://www.eaipatterns.com for a deep explanation of Command Message and Document Message from the patterns point of view.

Comments

• Anonymous
  April 20, 2005
  The comment has been removed

• Anonymous
  April 20, 2005
  Maybe I'not expained well:
  
  In the idea of having a full envelope is to separate data and metadata into two different Schemas, and avoiding dependencies.
  If you just make the difference by changing the root element, it's ok, by it's a simple wrapping rather an envelope. I see two issues with this wrapper or 'easy envelope':
  - It's not clear where the envelope starts, and where the document starts
  - Many different operations (with customers) means many different schemas (one schema for each action), although they are almost equal (the only difference is the root)
  
  Anyways, using full envelopes of course make it a little more complex, so the right choice depends on the actual project.

• Anonymous
  June 20, 2006
  http://www.ringtones-dir.com/get/">http://www.ringtones-dir.com/get/ ringtones site. [URL=http://www.ringtones-dir.com]ringtones download[/URL]: ringtones site free, ringtones site, Free nokia ringtones here. [url=http://www.ringtones-dir.com]samsung ringtones[/url] From website .

• Anonymous
  December 08, 2006
  Someone else below asked this already. I am getting nailed with Spam in my website for our blog website. Is there anyway to stop this? If not, there really isn't any point in leaving it up and active. Any help will be greatly appreciated. http://www.profesjonalna-reklama.pl Thanks Keep up the good work. Greetings from Poland

• Anonymous
  December 11, 2006
  hi ! your blog looks good and have good information