WebSphere Lombardi Edition 7.2 > Modeling processes > Advanced modeling tasks > Integrate with other systems > Create inbound integrations
Posting a message to Lombardi Event Manager
To post a message from an external system to Lombardi Event Manager, you must use the message structure. You can use Java Message Service (JMS) to post a message to the Event Manager. See About the Event Manager in Lombardi Administration Guide to see how the Event Manager processes incoming requests.
Understand the message structure
The message that you post to the Event Manager must contain an event name (the message event ID generated when you create an Undercover Agent) and it can contain parameter names and values in key-value pairs. ( Create an Undercover Agent for an incoming message event describes the message event ID that you should use for the event name.) The message must be structured as XML as shown in the following example:
<eventmsg> <!-- The process app acronym and event name are required: The snapshot and UCA name are optional --> <event processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event_name]</event> <!--Optional: The name of the queue for the event to run in--> <queue>[queue name]</queue> <!--Any parameters the UCA may require-- <parameters> <parameter> <key>param1</key> <value>![CDATA[value1]]</value> </parameter> </parameters> </eventmsg>If you do not include the snapshot name in the message, the Event Manager uses the default snapshot on the target Process Server for start message events. For intermediate message events, if you do not include the snapshot name in the message, all active snapshots receive events.
Note that if the value of the <value> element contains XML elements or similar content, you need to wrap the value in a CDATA tag as shown in the preceding example. For information about passing parameter values for each complex variable type, see the following section.
Passing complex variable types to Undercover Agents
You can use Undercover Agents (UCAs) to instantiate services automatically, without human interaction by a Lombardi participant. When you include a Message Event in a Lombardi BPD, you must assign a UCA to it for the Message Event to execute at run time. The Event Manager, which is part of the Lombardi Process Server, handles the scheduling and queuing of UCAs.
In addition to user-created complex variable types, the following complex variable types can be used to invoke UCAs at run time:
Record XMLDocument Date and Time XMLElement Boolean XMLNodeList Map ANY (default) For example, to invoke a UCA using an XML message, let's say your run-time process contains a Message Event that waits for an incoming message. This message contains an input parameter whose value includes the Customer Name, Description, and Age.
First, create the service and then associate the service with an Undercover Agent (the service describes what happens when the UCA is invoked at run time). Then, send the message with the following syntax:
<eventmsg> <event processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event name]</event> <parameters> <parameter> <key>customerParam</key> <value> <Name>John</Name> <Description>John Description</Description> <Age>30</Age> </value> </parameter> </parameters> </eventmsg>The following sections provide examples of how to pass the content of the <value> element. The conversion from the event XML format to a complex type is handled automatically by the Lombardi engine.
When the Any type is used to pass a parameter value, the actual Lombardi type must be supplied using the type attribute of the corresponding element. The type attribute can be omitted only when Lombardi knows the exact type or when the type is String. The value of the attribute must be an existing Lombardi type—or in case of an array, a Lombardi type concatenated with the [] string at the end.
Passing Lombardi Structured types
All structured objects are passed as XML structures, where every object property corresponds to an XML element.
For example:
Variable type: Customer - Name: String (John Doe) - Description: String (Single) - Age: Integer (30)
is mapped to:
XML: <value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> </value>Keep the following important rules in mind:
- Every object property is mapped to an XML Element with the same name as the property name. The element name is case sensitive. For example, if the property is Name, the element name must be <Name>, not <name>.
All XML element attributes are reserved. If you pass an attribute (excluding type), an error is returned because the passed Document is not valid.
When an array is passed, it is mapped as a sequence of XML elements with the same name. There are two possibilities:
Passing root level arrays: Every object array item must be placed as content of an <item> element. For example:
<value> <item> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </item> <item> <Name>Jane Doe</Name> <Description>Married</Description> <Age>31</Age> </item> </value>Passing array properties: Every object in the object array is converted to XML using the object property name as an XML Element name. For example:
<value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> <Address> <Street>10506 Jollyville Rd</Street> <City>Austin</City> </Address> <Address> <Street>10507 Research Blvd</Street> <City>Austin</City> </Address> </value>If an object property is null, the corresponding element is skipped.
Passing Record type
The Record type is serialized in the same way as Structured types. However, because all values are considered of type ANY, the type information must also be passed (using the type attribute) in order for the correct objects to be instantiated during de-serialization.
Passing Date/Time types
The format for passing dates is yyyy/MM/dd HH:mm:ss.S z.
When the value is converted to the Calendar Java object, it preserves the time zone, and no other modifications (such as adjusting it to the server time zone) is performed.
Passing Boolean type
The valid values for the Boolean type are true or false (case is not considered).
Example:
<value>TRUE</value>
Passing Map type
A Map type is passed to a UCA using the following structure:
<value> <entry> <key> … </key> <value> … </value> </entry> </value> For example: <value> <entry> <key>TX</key> <value>Texas</value> </entry> <entry> <key>CA</key> <value>California</value> </entry> </value>Because all values and keys in this case need to be of the ANY type, the type information must also be passed in order for the correct objects to be instantiated during deserialization. If the object is of the String type, the type does not need to be specified.
Passing XMLDocument type
An XML Document is passed as an XML escaped string.
Example:
<value> <![CDATA[ <?xml version="1.0"?> <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </value>
Passing XMLElement type
An XML Element is passed as an XML escaped string.
Example:
<value> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </value>
Passing XMLNodeList type
Every node is passed as an XML escaped string. The array of the nodes is encoded as a sequence of <item> elements.
Example:
<value> <item> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </item>| <item> <![CDATA[ <Customer> <Name>Jane Doe</Name> <Description>Married</Description> <Age>31</Age> </Customer> ]]> </item> </value>
Passing ANY type
When the type of an input parameter to a UCA is declared as ANY, the information about the actual type must be passed as part of the XML.
Example:
Define a process with one input parameter, Name, of type ANY. When the data is encoded in XML, the actual type must be supplied as the value for the type attribute. If the type is not passed, the String type is assumed.
<value type=”String”> John Doe </value>
Parent topic: Create inbound integrations