iWay Service Manager Component Reference Guide > Available Services > Document Insert Service (com.ibi.agents.XDDocInsertAgent)

Document Insert Service (com.ibi.agents.XDDocInsertAgent)

Topics:

Syntax:

com.ibi.agents.XDDocInsertAgent

Description:

The Document Insert service is used to insert data within an XML Document. The data can be text or parsed XML content. The insertion point is specified by an XPath expression.

Parameters:

The following table lists and describes the parameters for the Document Insert Service.

Parameter

Description

Data Source

The text or XML data to insert in the document.

Data Format

Determines how the Data Source is interpreted.

  • The Text format treats the Data Source as character Data.
  • The XML format parses the Data Source as an XML fragment within the XML Namespace context of the Parent Element.

Replace Content

Determines whether the existing children of the parent node are removed before the data is inserted.

XML Namespace Provider

Provider for the mapping between the XML namespace prefix and the namespace URI in the XPath expressions. If left blank, the XPath expressions in the Parent Element and the Next Sibling cannot contain namespaces.

XPath Syntax

Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.

Create Parent Element

Determines whether the parent element is created if it is missing.

Parent Element

Path to the element where the data will be inserted. If left blank, the parent is the root element. If Create Parent Element is set to true, then the expression must adhere to the Restricted XPath syntax, or else the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. The Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate that the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be declared in the XML Namespace provider. The predicate is optional, but if present it has the form [@ns1:attr1='val1' and @ns2:attr2='val2' and ...]. If no element matches the Restricted XPath expression and Create Parent Element is set to true, then the necessary elements and attributes will be created such that the expression would match successfully.

Next Sibling

Path to the next sibling node. If the sibling node is found, the data will be inserted before this node. Otherwise, the data is added as the last child of the Parent Element.

The Data Source is evaluated to obtain a string. If the Text format is selected, the string becomes the value of a text node that will be inserted. If the XML format is selected, the string is parsed as an XML fragment within the XML Namespace context of the Parent Element. An XML fragment can have multiple root nodes. All the XML Namespace declarations active on the Parent Element will be available without the need to redeclare them explicitly in the Data Source. This reduces surprises in case the resulting document is serialized and reparsed later. For the XML format, this service does not reparse the whole input document. Only the Data Source and a small wrapper containing the Namespace declarations are parsed.

If the XML Namespace declarations in the input document are unknown or unpredictable, it is recommended to explicitly declare all namespace declarations in the Data Source. In particular, the default namespace might have to be undeclared if the Data Source contains elements in the global namespace.

The Replace Content parameter is Boolean. When selected, the existing children of the parent node are removed before the data is inserted. In particular, this option is required when you wish to assign a new text value to a Parent Element that already has a value.

The XML Namespace Provider is optional. It is the name of the provider that gives the mapping between XML Namespace prefixes and XML Namespace URIs. If left blank, the Parent Element and Next Sibling path expressions cannot contain namespace prefixes.

The Parent Element is an XPath expression pointing to the element where the data will be inserted.

The Next Sibling is an XPath expression that points to a child of the parent element. The data will be inserted before this node. If the parameter is left blank or the sibling is not found, the data is added as the last child of the parent. This parameter is ignored if Replace Content is selected. The operation will fail if the Next Sibling is not a child of the Parent Element.

When the Create Parent Element parameter is true, the Parent Element will be created if needed, but the XPath expression must adhere to the Restricted XPath syntax. When the Create parent Element parameter is false, the parent element must exist but the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. For more information on the Restricted XPath, see the Way Service Manager Security Guide.

Edges:

The following table lists and describes the line edges that are returned by the Document Insert Service (com.ibi.agents.XDDocInsertAgent).

Edge

Description

success

The iteration completed successfully.

fail_parse

An iFL expression could not be evaluated.

fail_operation

The operation could not be completed.

Example 1: Charter Data

This example shows how to set the text value of an element.

The table below lists the parameters and values for the Charter data.

Parameter

Value

Data Source

 
NewValue

Data Format

 
text

Replace Content

 
True

Create Parent Element

 
false

Parent Element

 
/root/elem

The following is a sample input document.

<root><elem>OldValue</elem></root>

The following syntax is the resulting output document.

<root><elem>NewValue</elem></root>

Without Replace Content, the output document would contain two text nodes in the elem element, as shown below:

<root><elem>OldValueNewValue</elem></root>

The following is another sample input document. 

<root><sib>val</sib></root>

The service will return the edge fail_operation with an error document indicating that the Parent Element is missing. The service cannot create the parent element because that parameter is false.

Example 2: Creating the Parent

This example shows how to use Restricted XPath to create the parent element if it is absent from the input document.

The following table lists the parameters and values for creating the parent.

Parameter

Value

Data Source

 
NewValue

Data Format

 
text

Replace Content

 
true

Create Parent Element

 
true

Parent Element

 
 /root/*[1]/self::elem

When the parent element already exists, it will then be updated as usual. The following syntax shows a sample input document.

<root><elem>OldValue</elem></root>

The following is the sample output document.

<root><elem>NewValue</elem></root>

When the parent element is missing, the service will create it. The following syntax shows a sample input document.

<root><sib>val</sib></root>

The output document for it will be:

<root><elem>NewValue</elem ><sib>val</sib ></root>

Notice how the elem element is created before the sib element. This is the result of the carefully crafted Restricted XPath expression. With the simpler expression /root/elem, the elem element is created as the last child of the root element.

Example 3: Inserting an Element

This example shows how to insert an element before a sibling.

The following table lists the parameters and values for inserting an element.

Parameter

Value

Data Source

 
_concat(<newelem,_sreg(newval),</newelem>)

Data Format

 
xml

Replace Content

 
false

XML Namespace Provider

 
xmlnsprov

Create Parent Element

 
false

Parent Element

 
/ns:root

Next Sibling

 
/ns:root/sib2

This assumes that the value of the special register newval is 123 and the XML Namespace provider xmlnsprov maps the prefix ns to http://ns.com.

The Data Source expression must not start with the less than (<) symbol to be evaluated, otherwise it is considered an XML constant.

The following example shows an input document.

<n:root xmlns:n=http://ns.com><sib1/><sib2/></n:root>

Its output document is shown in the following syntax.

<n:root xmlns:n=http://ns.com><sib1/><newelem >123</newelem><sib2/></n:root>

If the Next Sibling is not found in the input document, the operation still succeeds but the data is inserted as the last child of the Parent Element. The following syntax shows a sample input document. 

<n:root xmlns:n=http://ns.com><sib/><n:root>

The output document is shown below.

<n:root xmlns:n=http://ns.com><sib/><newelem >123</newelem></n:root>

Example 4: Inheriting XML Namspaces

This example shows how the XML namespace declarations are inherited from the context of the Parent Element. It also demonstrates a Data Source containing an XML fragment with two root nodes.

The following table lists the parameters and values of the XML namespaces.

Parameter

Value

Data Source

 
<n:newelem/><def/>

Data Format

 
xml

Replace Content

 
true

Create Parent Element

 
true

Parent Element

 
/root/sub

The following example shows an input document.

<root xmlns:n=http://ns.com><sub/></root>

The corresponding output document is:

<root xmlns:n=http://ns.com><sub><n:newelem/ ><def/></root>

Note that he newelem element inherited its namespace prefix from an ancestor node in the input document.

The following example shows an input document.

<root xmlns:n=http://ns.com xmlns=http://default.com></sub></root>

The corresponding output document is:

<root xmlns:n=http://ns.com xmlns=http://default.com><sub><n:newelem/ ><def/></sub></root>

The def element is now in the http://default.com namespace. If you do not wish to have the element in the namespace, then the default namespace must be explicitly undeclared in the Data Source, as shown in the following syntax: 

<n:newelem/><def xmlns=/>

If the application does not control the exact content of the input document, then it is recommended to explicitly declare all XML Namespaces in the Data Source, as shown in the following syntax. 

<n:newelem xmlns:n=http://ns.com/><def xmlns=/