Convention-based Web Service message mapping example
As an example of using convention-based mapping, consider the following XML documents, which define a request message and a response message:
<WSRequest decisionServiceName="dsName"
xmlns="urn:WSService">
<WorkDocuments messageType="FLAT">
<Node id="idAttrValue1">
<id>id1</id>
<isLeaf>true</isLeaf>
<isRoot>false</isRoot>
<child href="href1"></child>
<child href="href2"></child>
<parent href="href1"></parent>
<parent href="href2"></parent>
<leaf href="href1"></leaf>
<leaf href="href2"></leaf>
</Node>
<Node id="idAttrValue2">
<id>id2</id>
<isLeaf>true</isLeaf>
<isRoot>false</isRoot>
<child href="href1"></child>
<child href="href2"></child>
<parent href="href1"></parent>
<parent href="href2"></parent>
<leaf href="href1"></leaf>
<leaf href="href2"></leaf>
</Node>
<Leaf id="idValue">
<node href="hrefValue1"></node>
</Leaf>
</WorkDocuments>
</WSRequest>
<WSResponse decisionServiceName="dsName"
xmlns="urn:WSService">
<WorkDocuments messageType="FLAT">
<Node id="idAttrValue1">
<id>id1</id>
<isLeaf>true</isLeaf>
<isRoot>false</isRoot>
<child href="href1"></child>
<child href="href2"></child>
<parent href="href1"></parent>
<parent href="href2"></parent>
<leaf href="href1"></leaf>
<leaf href="href2"></leaf>
</Node>
<Node id="idAttrValue2">
<id>id2</id>
<isLeaf>true</isLeaf>
<isRoot>false</isRoot>
<child href="href1"></child>
<child href="href2"></child>
<parent href="href1"></parent>
<parent href="href2"></parent>
<leaf href="href1"></leaf>
<leaf href="href2"></leaf>
</Node>
<Leaf id="idValue">
<node href="hrefValue1"></node>
</Leaf>
</WorkDocuments>
<Messages version="versionX.Y">
<Message>
<severity>Info</severity>
<text>text1</text>
<entityReference href="erHref1"></entityReference>
</Message>
<Message>
<severity>Info</severity>
<text>text2</text>
<entityReference href="erHref2"></entityReference>
</Message>
</Messages>
</WSResponse>
Following are event definitions that follow the conventions of these XML documents. It is important to understand that the EPL field types directly correspond to the types defined in the XML Schema document used by the request and response documents. Likewise, event field names directly correspond to the element names defined in the XML Schema document.
event NodeRef {
string _href;
}
event NodeType {
string _id;
string id;
boolean isLeaf;
boolean isRoot;
sequence<NodeRef> child;
sequence<NodeRef> parent;
sequence<NodeRef> leaf;
}
event LeafType {
string _id;
NodeRef node;
}
event WorkDocumentsType {
string _messageType;
sequence< NodeType > Node;
sequence< LeafType > Leaf;
}
event WSRequestType {
string _decisionServiceName;
WorkDocumentsType WorkDocuments;
}
event MessageType {
string severity;
string text;
NodeRef entityReference;
}
event MessagesType {
sequence<MessageType> Message;
string _version;
}
event WSResponseType {
string _decisionServiceName;
WorkDocumentsType WorkDocuments;
MessagesType Messages;
}
event MyRequest {
WSRequestType WSRequest;
}
event MyResponse {
WSResponseType WSResponse;
}
To use the convention approach to mapping event fields to message parameters:
1. Create an Apama event with fields that correspond in type and order to the parameters of a Web Service operation.
3. With that operation selected, in the Event Mappings tab, right-click the Apama event and select Add Computed Node. For example, the following tree is in the Input tab: 
The Add Computed Node dialog appears:
4. In the Add Computed Node dialog's Select Method field, select Convert to XML from the drop-down list. The dialog is updated to show more information.
When the adapter generates the request XML structure you can customize the namespace and namespace prefix in the generated XML. If sub-elements in the request XML structure are in different namespaces, you cannot use only the convention mapping approach. You must combine it with the template approach. See
Combining convention and template mapping. However, when sub-elements belong to more than one namespace you can use the convention approach without a template to convert the XML structure to an event.
By default the Include empty fields option is enabled. This specifies that empty XML nodes will be generated when empty EPL string fields are encountered within an Apama event. This option does not affect empty strings within a sequence of EPL strings. If you clear the check box to disable the option, empty XML nodes will not be generated.
5. Click OK.
In the mapping tree, Apama Studio adds an entry of type Convert To XML to the selected event node. For example:
6. Drag a line from the Convert To XML entry to the parameters entry. For example:
For the output mapping, map the output Web Service parameter to an event field. If the event field is of an event type that models the output XML (per the convention), the adapter automatically creates the event instance at runtime (implicitly) from the XML. Following is an example of mapping an operation's parameter to an output event:
