CA API Gateway 9.1

9.4 9.1

Add or Remove XML Element(s) Assertion

The Add or Remove XML Element(s) assertion is used to add or remove XML element to or from a target message—for example, individual signatures. An example context variable input might be "requestXpath.elements" from an XPath expression (note the trailing "s" in elements is mandatory). You can also reference specific index positions of multi-valued context variables (for example, "requestXpath.elements[0]" to reference the first entry in the variable).
gateway90
The
Add or Remove XML Element(s)
assertion is used to add or remove XML element to or from a target message—for example, individual signatures. An example context variable input might be "requestXpath.elements" from an XPath expression (note the trailing "s" in elements is mandatory). You can also reference specific index positions of multi-valued context variables (for example, "requestXpath.elements[0]" to reference the first entry in the variable).
This assertion is intended to be used with context variables set by the following assertions: Sign Element Assertion, Evaluate Request XPath Assertion, or Evaluate Response XPath Assertion.
To learn about selecting the target message for this assertion, see Select a Target Message.
Example:
The following sample policy adds the <d></d> element under <c></c>:
Add_Remove_XML_example.PNG
Where:
For an explanation of the all the "responseXpath" variables that can be set, refer to the Evaluate Response XPath Assertion.
The Add or Remove XML Element(s) assertion does not work on messages modified by the Apply XSL Transformation Assertion. Attempting to do so results in the audit: "Message is not XML".
Using the assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the
    Add or Remove XML Element Properties
     automatically appear; when modifying the assertion, right-click
    <target>:
     Add or Remove XML Elements
     in the policy window and select
    Add or Remove XML Elements Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.   
  3. Configure the properties as follows.
    Setting
    Description
    Variable Name of Existing Element
    If you are adding a new XML element, enter the name of the context variable containing the existing XML element to which you are adding the new element.
    If you are removing an element, specify the context variable that contains a reference to remove a specific signature or other element(s). This variable must have been set by one of the assertions listed at the beginning of this topic.
    Remove Element from Document
    Select this option to remove the XML element specified in the
    Variable Name of Existing Element
     field.
    Add New Element as _______ of Existing Element
    Select this option to add a new XML element, then select the position in which the new element will appear:
    First Child
    Last Child
    Previous Sibling
    Next Sibling
    Example:
       <Parent>
        <PreviousSibling/>
        <ExistingElement>
             <FirstChild/>
             <LastChild/>
        </ExistingElement>
        <NextSibling/>   
   </Parent>
    Variable Name of New Element
    When adding an element, enter the context variable containing the element to be added. This variable can contain an element selected by one of the listed assertions at the beginning of this topic, or it can contain a text string (provided it is a valid XML document fragment).
    The ".element" variable is not compatible with the Add or Remove XML Element(s) assertion when an XPath assertion (Evaluate Request XPath Assertion or Evaluate Response XPath Assertion) is used to capture the DOM node value.
  4. Click [
    OK
    ] when done.

Content feedback and comments