Overview
|
You can use this filter to add an XML element, attribute, text, comment,
or CDATA section node to an XML message. The new node is inserted into
the location specified by an XPath expression or a SOAP actor/role.
XPath is a query language that enables you to select nodes in an XML
document. A SOAP actor/role provides a way of identifying a particular
WS-Security block in a message.
|
General Configuration
|
You can configure the following general setting:
Name:
Enter a suitable name that reflects the role of the filter. For example,
if the purpose of this filter is to add an <Address>
element to the message, it would be appropriate to name this filter
Add Address Element.
|
Configure where to Insert the New Nodes
|
You can insert the new node into a location specified by an XPath expression
or into a WS-Security header for the specified SOAP actor or role. Select one
of the following options:
Insert using XPath:
Select or enter an XPath expression to specify where to insert the new node.
If this expression returns more than one node, the first one is used. If the
expression returns no nodes, the filter returns false. You can add, edit, or
delete XPath expressions using the buttons provided.
Select one of the following options to determine where the new node
is placed relative to the node(s) returned by the XPath expression.
-
Append:
The new node is appended as a child node of the node returned by
the XPath expression. If there are already child nodes of the node
returned by the XPath expression, the new node is added as the last
child node.
-
Before:
The new node is inserted as a sibling node before the node
returned by the XPath expression.
-
Replace:
The node pointed to by the XPath expression is completely
replaced by the new node.
Insert into WS-Security element for SOAP Actor/Role:
Select or enter the name of the SOAP actor/role that specifies the WS-Security
element into which the XML node is inserted. A SOAP actor/role provides a way of
distinguishing a particular WS-Security block from others that may be present in
the message. Actors belong to the SOAP 1.1 specification, and were replaced by
roles in SOAP 1.2. For example, this setting is useful if there is no SOAP header
or WS-Security element in the message because these are created when this option
is specified.
|
Node Source
|
Select one of the following options for the source of the new node:
-
Create a new node:
If this option is selected, a new node is created and inserted
into the location pointed to by the XPath expression configured
above.
-
Insert previously removed nodes:
You can configure a Remove XML Node filter
to remove XML nodes from the message and store them in the
deleted.node.list message attribute. You can then
use the Add XML Node filter to re-insert these
nodes back into a different location inside the message, effectively
moving the deleted nodes in the message. To use this option, select
the Save deleted nodes option on a Remove XML
Node filter that is configured to run before the Add
XML Node filter in the policy.
-
Message attribute:
If this option is selected, a new node is created from the contents
of the selected message attribute.
|
Configure New Node Details
|
Configure the following node details:
Node Type:
Select the type of the new node from the drop-down list. It is important to
note that this selection determines where you can insert the new node
according to the following rules:
-
You can only append a node to a Node Type of
Element or Text .
-
If you append to a
Text node, you must append another
Text node.
-
If you add a new
Attribute node using the Replace
option, it must replace an existing Attribute node.
Node Content:
This field contains the node to be inserted into the message. The Node
Content field must contain valid XML when the Node Type
is set to Element . You can also enter wildcards, which are populated
at runtime by the Enterprise Gateway.
|
Attribute Node Details
|
The following attribute-related fields are only enabled when you select Attribute
from the Node Type drop-down list:
Attribute Name:
Enter the name of the attribute in this field.
Attribute Namespace URL:
Enter the namespace of the attribute in this field.
Attribute Namespace Prefix:
Specify the prefix to use to map the element to the namespace entered
above in this field. The new attribute is prefixed by this prefix.
|
Examples
|
The following are some examples of using the Add XML Node
filter to replace and add attributes and elements.
Replacing an attribute value
To replace an attribute value, perform the following steps:
- In the Configure where to insert the new nodes
section, select Insert using XPath.
- Select a value from the drop-down list (for example,
SOAP
Header "mustUnderstand" attribute ).
- Select the Replace option.
- In the Configure new node details section, select
Attribute from the a Node Type list.
- Enter the Node Content in the text box (for
example, in this case,
1 or 0 ).
- In the Attribute Details section, you must enter
the Attribute Name.
Adding an attribute
To add an attribute to an element, perform the following steps:
- In the Configure where to insert the new nodes
section, select Insert using XPath.
- Select a value from the drop-down list (for example,
SOAP
Header "mustUnderstand" attribute ).
- Select the Append option.
- In the Configure new node details section, select
Attribute from the a Node Type list.
- Enter the Node Content in the text box (for
example, in this case
1 or 0 ).
- In the Attribute Details section,
you must enter the Attribute Name.
Adding an element
To add an element, perform the following steps:
- In the Configure where to insert the new nodes
section, select Insert using XPath.
- Select a value from the drop-down list (for example,
SOAP
Header Element ).
- Select the Append option.
- In the Configure new node details section, select
Element from the a Node Type list.
- Enter the Node Content in the text box (for
example, in this case, the contents of the SOAP header).
Replacing an element
To replace element A with new element B, perform the following steps:
- In the Configure where to insert the new nodes
section, select Insert using XPath.
- Select a value from the drop-down list (for example,
SOAP
Method Element ).
- Select the Replace option.
- In the Configure new node details section, select
Element from the a Node Type list.
- Enter the Node Content in the text box (for example,
in this case, the contents of the SOAP method).
|
|