Mapping Web Service message parameters
After you specify which Apama events you want to map to the Web Service messages, you need to create mapping rules that associate Apama event fields with parameters in the Web Service messages. Apama's adapter editor in Software AG Designer provides a visual mapping tool to create the mapping rules. Web Service messages fall into three categories, each of which can be mapped to Apama events.
Input mapping specifies how fields in an Apama event are connected to the parameters in a Web Service input message. These are also known as request messages.
Output mapping specifies how parameters in a Web Service output message are connected to the fields in an Apama event. These are also known as response messages.
Fault mapping specifies how Apama event fields and Web service parameters are connected when a fault message is delivered.
When you select an operation in the adapter editor's Event Mappings tab, in the Operations Name column, the Mapping Definitions section of the editor displays hierarchical representations of the Apama event and the Web Service operation. The source tree is on the left and the target on the right. For input event messages, the Apama event is the source and the Web Service message is the target; for output and fault messages the Web Service is the source and the Apama event is the target.
There is a tab for each type of Apama event specified: input, output, and fault events. You must specify an input event for each operation that you add. You can add the same operation more than once. If you do, you can specify a different input event or the same input event for each additional instance of the operation. Optionally, you can specify one output event and/or one fault event for each operation instance that you add.
On the adapter editor's Event Mappings tab, in the Mapping Definitions section, you specify the mapping rules by clicking on an entity in one tree and dragging a line to the entity in the other tree.
In the Mapping Definitions section, for input messages, the Apama event fields are displayed to the left and the Web Services operation parameters on the right. To create a mapping rule, click on the event field and drag a line to the desired operation parameter.
There are several approaches for how to map Apama event fields to the parameters in Web Services messages, depending on the complexity of the events and the message parameters.
Simple. Use this approach when a simple Apama event field can be associated with a corresponding type in the Web Service message. A simple Apama event field is of type
integer,
float,
boolean,
decimal, or
string. For example, you can use the simple approach to map a
string event field to a message parameter of type
xsd:string.
Convention-based. Use this approach when the structure of an Apama event corresponds directly with the XML structure of the Web Service message. The Apama event must have been defined by following the conventions described in
Convention-based XML mapping. In this case, Apama (at runtime) automatically converts the event instance to the request XML structure of the Web Service, and also converts the Web Service response XML to an event instance.
Template-based. Use this approach when the XML definition of the Web Service message contains a complex type. You must supply an XML template file that defines the complex type. In the template file, you use variables that will be replaced with values from the Apama event fields. You then map event fields to the variables in the template.
Combination. This approach combines the convention-based and template-based approaches. Use this approach when the adapter can automatically convert at least one event field (
event or
sequence type) to XML that models a message parameter and when at least one of the values of the converted fields serves as a value for a variable in a template.
You can also specify if a mapping rule requires a an XPath, XSLT, or XMLDecode transformation. For more information on how to specify a transformation type, see
Specifying transformation types.
The visual mapping tool allows you to add custom entries to the SOAP Headers, HTTP Headers, and SOAP Body if the Web Service requires it. For more information on customizing mapping rules, see
Customizing mapping rules.
When you save a Web Service configuration, the XML files used to interact with the Web Services and the appropriate service monitors are generated. See
Web Services Client adapter artifacts for more information.
