How to set mustUnderstand in an outgoing SOAP Message

Am using WebMethods IS 9.6 CoreFix 12 on Windows 8.1

Produced a WSD using a client WSDL and Schema.

Declared their certificate via a WSC Endpoint and linked policy X509 Authentication and Signature to the WSC. This produces a complete message with correct certification.

The issue for this customer is that in their service they do not handle mustUnderstand and we happen to send this in our request.

I have tried to use a WMConsumer handler on this WSC to get the SOAPMessage and header to reset this value. I have tried to use a Java Service to use DOM to remove this attribute from the constructed message.

The problem with this seems to be that the handler is executed before security is added to the soap message. Consequently at the time of execution these details aren’t in the message.

There appear to be parameters to be set in message addressing both within the call to the WSD client, and in the WSC endpoint. However setting these one way or the other appears to have no impact at all on this entry in the eventual message.

So my question is, how can I instruct my WSD to observe this in the message it produces?

Any help apperciated :smiley:

#Found this KB, hope this should give me some insight.


IS Header handling and the mustUnderstand attribute and WSD property.


  1. The mustUnderstand attribute should be present on the actual HeaderElement within a request instance, but should not be present in the WSDL.
    The mustUnderstand attribute of a header is a way for the sender of the request to indicate that the receiver of the request must understand the header or it cannot process the request. If the receiver does not understand the header, it MUST respond with the NotUnderstood Fault. This behavior is defined in the SOAP Specification.

The IS WSD definitions expose a mustUnderstand Property for the Header definitions associated with an operation in a WSD for both Provider WSDs and Consumer WSDs.

The IS 7.1 WSDL generation for Provider WSDs has issues with the mustUnderstand WSD property and will incorrectly generate mustUnderstand attributes in the WSDL when the mustUnderstand property is set to true for a header defined within an Operation within a WSD.
Directly from the 7.1.2 readme File:
WSDL generated for an IS Provider fails WS-I compliance checks when header attributes Must Understand or Role Header properties are specified. When generating WSDL for a provider web service with a header specifying Must Understand=True or specifically setting the Role property of a header, the IS will insert the mustUnderstand= or Actor attributes into the soap:header element of the soap:binding in the generated WSDL. This causes the WS-I compliance check on the WSDL to fail.
To work around this issue, do not specify the Must Understand or Role properties on a header within a Provider WSD. If needed, these attributes may be set in the actual soap:header of the request prior to invoking the web service on the client side.
For Provider WSD:
You should never set the mustUnderstand property to true in the WSD, period. It serves no useful purpose and simply generates invalid WSDL.

For a Consumer WSD:
If you set the mustUnderstand property of a Header in the WSD to true, the SOAP Header in the outbound SOAP request will contain the mustUnderstand=1 attribute.
If you set the mustUnderstand property of a Header in the WSD to false, the SOAP Header in the outbound SOAP request will not contain the mustUnderstand attribute.

  1. How does an IS Provider WSD use/honor the mustUnderstand attribute when present on an inbound SOAP request instance?
    An IS Handler does not need to remove the mustUnderstand attribute from the header as you describe in Axis2. In the IS, simply having a Handler assigned in the WSD that has declared support for the Qname, when the Handler was Registered, is enough for the IS to consider that header “Understood”.

When an inbound request instance contains a header with the mustUnderstand attribute set to 1, we look at all of the Provider Handlers associated with the WSD. If there are no Provider Handlers associated with the WSD, or none of the associated handlers was registered to support the QName of the header in question, the IS will respond with the Not Understood SOAP Fault, as required by the soap specification. If we find a handler that has declared support for the header, we consider it “understood” and continue processing.

  1. There is no way in WSDL 1.1 to define a header as optional or required.
    WS-I basic Profile declares that if a header is present in the WSDL definition, it is to be treated as a Required Header.
    The IS adopts this ws-i stance for all headers with regard to Provider WSDs, regardless of the ws-i compliance setting for the WSD.

Hope this helps to clarify IS required vs. optional headers, the mustUnderstand attribute in a request instance and the mustUnderstand property in a WSD.

Dear Mahesh,

Many thanks for taking the time to post.

It’s always good to see whats declared in the books about such things, I too have read manuals to see where this might be set.

I am particularly interested in the consumer part.

In my case, there are no security statements in the WSDL. In the generated WSD it allows the setting of this field in messageAddressingProperties. I set it here. Within the WSD generated from the WSDL, I can follow this variable in debug, however at the point where the call is made to pub.client:soapClient, there is no field to map the value to, nor a field one can set to maintain this value into the soap call. I wonder if there is another selection to be made when creating the WSD that should be observed to allow the setting of this field in flight?

I have closely checked the values one can set from the WSD itself within binder settings etc, but there isn’t an obvious candidate to accept this value.

Anyway the result is that despite this value being set to false in the WSD, the mustUnderstand statement is still made in the SOAP header. If there is anything else to observe in the setting up of the WSD , or WEB service in the IS, any information on that would be much appreciated.

Many thanks again for your input :smiley:

Eventually, having no luck to set this through configuration, I removed via a string replace in the outbound callback service of the WSC, this works but i’m sure isn’t the best means to this end