Transforming a SOAP message in a message map

In IBM® App Connect Enterprise, a SOAP message is described by a generic model that includes the SOAP Envelope and optionally Attachments. You define your SOAP message parts in a message map by using the Cast function.

About this task

A SOAP message consists of an Envelope and optionally Attachments. The envelope contains a SOAP header and a SOAP body. A SOAP body can include SOAP faults.

When you use SOAP nodes in IBM App Connect Enterprise, you can manipulate the following type of messages:

A SOAP message that is described by a generic model and that contains the SOAP operation-specific data.
An XML message that contains only the SOAP operation-specific data.

In addition to the standard SOAP parts, the SOAP message generic model includes a Context part that includes contextual information about the current SOAP message that is processed. This part is the only one in a message map whose structure is included automatically. You must define the other SOAP message parts manually by using the Cast function.

IBM App Connect Enterprise supports SOAP 1.1 and SOAP 1.2 messages.

Depending on the message domain that you configure in your input node, you might have to consider the differences between SOAP 1.1 and SOAP 1.2 when transforming SOAP messages.

If you receive a SOAP message through a SOAPInput node, the SOAP parser handles SOAP 1.1 or SOAP 1.2 automatically. The SOAP domain uses a common logical tree format that is independent of the exact format of the web service message. For details of the SOAP tree format, see SOAP tree overview.
If you receive a SOAP message through an HTTPInput node, the XMLNSC parser handles your SOAP 1.1 or SOAP 1.2 message differently. When you create a message map, you must be aware of the SOAP version, and configure the correct SOAP 1.1 or SOAP 1.2 schema when you create and configure your graphical data map.

Depending on the nodes that you use when you model your message flow or your service operation, and the message domain you configure, you must use a different schema model:

If you use the SOAP nodes excluding the SOAPExtract node, you must map the SOAP_Domain_Msg in the SOAP domain.
If you use the SOAP nodes including the SOAPExtract node, and the Mapping node is wired after a SOAPExtract node, you must map the schema associated with your operation in the XMLNSC domain. You use the SOAPExtract node to remove SOAP envelopes, allowing just the body of a SOAP message to be processed.
If you use HTTP nodes or MQ nodes, you must map the SOAP 1.1 or the SOAP 1.2 schema as the root model of the map in the XMLNSC domain.

The following table summarizes the different types of nodes and domains that you can use to map a SOAP message and the schema that you must use when you use a message map to transform a SOAP message.

Table 1. Schemas to use when transforming a SOAP message
Message domain	Nodes usage	Schema to configure in a message map
XMLNSC	All SOAP nodes within an integration service operation subflow.	Schema for operation request or response.
XMLNSC	SOAPInput nodes in flows that have a SOAPExtract node before the Mapping node.	Schema for operation request.
XMLNSC	SOAPReply or SOAPRequest nodes that might be preceded in a flow by a SOAPEnvelope node.	Schema for operation request or response.
SOAP	SOAPInput nodes that are wired directly to the Mapping node.	IBM-provided SOAP_Env where the body `xsd:any` has a mapping cast to the schema for the operation request.
SOAP	SOAPReply or SOAPRequest nodes that are wired directly to the Mapping node.	IBM-provided SOAP_Env where the body `xsd:any` has a mapping cast to the schema for the operation request or response.
XMLNSC	Flows that do not contain SOAP nodes. For example, flows that contain HTTP nodes, MQ nodes, or FileInput nodes.	IBM-provided SOAP 1.1 or SOAP 1.2 schema where the body `xsd:any` has a mapping cast to the schema for the operation request or response.

The following table compares the SOAP message structure with the IBM App Connect Enterprise SOAP message generic model:

Table 2. Comparison between the SOAP message structure and the IBM App Connect Enterprise SOAP message representation
Standard SOAP message parts	Status	IBM App Connect Enterprise SOAP message parts	IBM App Connect Enterprise Status
		Context	Required
SOAP header (part of the SOAP envelope)	Optional	Header (part of the SOAP_Domain_Msg)	Optional
SOAP body (part of the SOAP envelope)	Required	Body (part of the SOAP_Domain_Msg)	Required
SOAP faults (part of the SOAP body)	Optional	Fault (part of the Body)	Optional
SOAP Attachments	Optional	Attachment (part of the SOAP_Domain_Msg)	Optional

Procedure

Complete the following steps to configure the SOAP_Domain_Msg when the Mapping node is connected directly from a SOAPInput node with no SOAPExtract node:

Define the transformation for the Context object by using one of the following approaches:
- Copy the Context object by using the Move transform.
- Copy the Context object by using the Move transform, and then use the Override function if you want to modify a few elements with an Assign transform or a Move transform.
- Define transforms for all the Context elements that you want to maintain in the output object.
Define the transformation for the Header object by using one of the following approaches:
- Copy the Header object by using the Move transform.
- Copy the Header object by using the Move transform, and then use the Override function if you want to modify a few elements with an Assign transform or a Move transform.
- Define transforms for all the Header elements that you want to maintain in the output object.
You define SOAP header parts by using the Cast function. You can cast attributes and other header parts. Then, define transforms between the input elements and the output elements in each header part.

The SOAP Header element contains application-specific information, including attributes that define how you process the SOAP message.
Define the transformation for the Body object.
You define SOAP body parts by using the Cast function. You can cast attributes and other body parts. Then, define transforms between the input elements and the output elements in each body part.

Complete the following steps to define the SOAP body parts and their transformations:
1. Cast attributes that are defined as xsd:any into a specific type. Then, define a transform between the input attribute and the output attribute.
2. Cast wildcard elements that are defined as xsd:any into a specific type.
3. Cast a base type element to a derive type element. A derive type element is also known as an extension type element.
  
  In a message map, you cast a base type to a derive type or extension type so that you can define transformations between subtypes of a data type.
  
  For example, addresses are represented differently for different countries. You might want to map addresses from different countries into a common complex structure for addresses.
4. Define transforms between the input and output body elements.
Note: When you use a schema model for your SOAP message or the built-in SOAP domain message, you can also define the xsd:any by using the Add User-Defined function. However, you are recommended to use the schema models that are part of the WSDL service definition, if they are available.
Define the transformation for the Attachment object by using one of the following approaches:
- Copy the Attachment object by using the Move transform.
- Copy the Attachment object by using the Move transform, and then use the Override function if you want to modify a few elements with an Assign transform or a Move transform.
You define SOAP attachment parts by using the Cast function.

Example

Complete the steps in any of the following use cases to learn how to configure the SOAP_Domain_Msg when the Mapping node is wired directly from a SOAPInput node with no SOAPExtract node:

Configure a SOAP message when you use a conditional transform to map an input element to an output element. For example, you create and configure the If, Else if, and Else transform to control the flow of the mapping between elements that are defined as a specific or a derive type in the input and output message assembly by setting conditions. For more information, see Mapping a SOAP message by using a conditional transform.
Configure a SOAP message to transform some input elements to output elements. Use the Override function, Assign transform, and Move transform. For more information, see Mapping a SOAP message by using the Override function.

What to do next

Define more transforms between the input SOAP_Domain_Msg and the output SOAP_Domain_Msg. For more information, see Specifying a transform (mapping operation).