> For the complete documentation index, see [llms.txt](https://help.cumuluspro.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cumuluspro.net/developer-guide/straatos-api/straatos-xml-api.md).

# Straatos XML API

### New XML Document

Create new XML document. The documentElementName can contain namespace prefix (e.g. `ns:company`) if documentElementNamespace is provided. The documentElementNamespace is optional — for elements without namespace this parameter should not be specified.

#### Input Parameters

<table><thead><tr><th width="192.181884765625">Name</th><th>Description</th></tr></thead><tbody><tr><td>string ElementName</td><td>Name of root element</td></tr><tr><td>string Namespace</td><td>[Optional] Namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

console.log(xmlDocument.xml);
```

#### Result

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<ns:root xmlns:ns="https://www.cumuluspro.com/api/1.0"/>
```

***

### Parse XML

Parse `data` parameter (either a `byte[]` or `string`) containing XML and returns XML document.

#### Input Parameters

<table><thead><tr><th width="193.0908203125">Name</th><th>Description</th></tr></thead><tbody><tr><td>string Xml</td><td>XML string</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlString = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>' +
'<root>' +
'<element>element value 1</element>' +
'<element>element value 2</element>' +
'</root>';

var xmlDocument = straatos.parseXML(xmlString);
```

#### Sample Code with XML Namespace

```javascript
var xmlnsString = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>' +
'<ns:root xmlns:ns="https://www.cumuluspro.com/api/1.0">' +
'<ns:element>element value 1</ns:element>' +
'<ns:element>element value 2</ns:element>' +
'</ns:root>';

var xmlnsDocument = straatos.parseXML(xmlnsString);
```

#### Result

XML document object

***

### Add Element

Adds child element to current element. If `namespaceURI` is specified, `name` can contain a prefix, e.g. `ns:company`. For elements without namespace, no `namespaceURI` should be specified.

#### Input Parameters

<table><thead><tr><th width="194">Name</th><th>Description</th></tr></thead><tbody><tr><td>string ElementName</td><td>Name of element</td></tr><tr><td>string Namespace</td><td>[Optional] Namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.text = 'element value 2';

console.log(xmlDocument.xml);
```

#### Result

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<root>

<element>element value 1</element>

<element>element value 2</element>

</root>
```

***

### Select Multiple Elements

Select elements using given XPath expression, relative to current element. Optionally, namespaces can be specified, e.g. `{ 'ns': 'urn:my—urn', 'ns2': 'urn:my-urn-2' }`.

#### Input Parameters

<table><thead><tr><th width="193.09088134765625">Name</th><th>Description</th></tr></thead><tbody><tr><td>string Xpath</td><td>Xpath of element</td></tr><tr><td>Namespace</td><td>[Optional] Namespace prefix: namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var addMultipleElementsStatus = 'fail';

var rootElement = xmlDocument.documentElement;

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.text = 'element value 2';

var elements = rootElement.selectElements('/root/element');

elements.forEach(function (element, index) {

  console.log('element at index ' + index + ': ' + element.text);

});
```

#### Sample Code with XML Namespace

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootnsElement = xmlnsDocument.documentElement;

var nselement1 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement1.text = 'ns:element value 1';

var nselement2 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement2.text = 'ns:element value 2';

var nselements = rootnsElement.selectElements('/ns:root/ns:element', { 'ns': 'https://www.cumuluspro.com/api/1.0' });

nselements.forEach(function (element, index) {

  var elementValue = 'ns:element value '+(index +1);

  console.log('element Value: ' + elementValue);

  if(element.text !== elementValue){
    selectElementStatus = 'fail';
  }

  console.log('element at index ' + index + ': ' + element.text);

});
```

#### Result

element at index 0: element value 1element at index 1: element value 2.

#### Result with XML Namespace

element at index 0: ns:element value 1.

element at index 1: ns:element value 2.

***

### Select Single Element

Select first element matching given XPath expression, relative to current element. Optionally, namespaces can be specified, e.g. `{ 'ns': 'urn:my—urn', 'ns2': 'my-urn-2' }`.

#### Input Parameters

<table><thead><tr><th width="193.0909423828125">Name</th><th>Description</th></tr></thead><tbody><tr><td>string Xpath</td><td>Xpath of element</td></tr><tr><td>Namespace</td><td>[Optional] Namespace prefix: Namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.text = 'element value 2';

console.log(xmlDocument.xml);

var elements = rootElement.selectSingleElement('/root/element');

console.log(elements.text);
```

#### Example with XML Namespace

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootnsElement = xmlnsDocument.documentElement;

var nselement1 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement1.text = 'ns:element value 1';

var nselement2 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement2.text = 'ns:element value 2';

var nselements = rootnsElement.selectSingleElement('/ns:root/ns:element', { 'ns': 'https://www.cumuluspro.com/api/1.0' });

console.log(nselements.text);
```

#### Result

element value 1.

#### Result with XML Namespace

ns:element value 1.

***

### Remove Element

Removes element from document.

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.text = 'element value 2';

element1.remove();
```

#### Result

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<root>

<element>element value 2</element>

</root>
```

***

### Add Attribute

Adds a new attribute to element. If `namespaceURI` is specified, `name` can contain prefix, e.g. `ns:attr`. For attributes without namespace, no `namespaceURI` should be specified.

#### Input Parameters

<table><thead><tr><th width="192.1817626953125">Name</th><th>Description</th></tr></thead><tbody><tr><td>string AttributeName</td><td>Attribute Name</td></tr><tr><td>string AttributeValue</td><td>Attribute value</td></tr><tr><td>string NameSpace</td><td>[Optional] Namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('attr', 'attribute value');

console.log(xmlDocument.xml);
```

#### Sample Code with XML Namespace

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootnsElement = xmlnsDocument.documentElement;

rootnsElement.addAttribute('ns:attr', 'attribute value', 'https://www.cumuluspro.com/api/1.0');

console.log(xmlDocument.xml);
```

#### Result

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<root attr="attribute value"></root>
```

#### Result with XML Namespace

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<ns:root xmlns:ns="https://www.cumuluspro.com/api/1.0" ns:attr="attribute value">

</ns:root>
```

***

### Select Attribute

Evaluates XPath expression relative to current element. Optionally, namespace can be specified.

#### Input Parameters

<table><thead><tr><th width="190.3636474609375">Name</th><th>Description</th></tr></thead><tbody><tr><td>string AttributeName</td><td>Attribute name</td></tr><tr><td>Namespace</td><td>[Optional] Namespace prefix: Namespace of element</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var selectAttributeStatus = 'fail';

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('attr', 'attribute value');

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.addAttribute('elementAttr', '25');

element2.text = 'element value 2';

console.log('xpath string attr: ' + rootElement.stringValue('@attr'));
```

#### Example with XML Namespace

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootnsElement = xmlnsDocument.documentElement;

rootnsElement.addAttribute('ns:attr', 'attribute value', 'https://www.cumuluspro.com/api/1.0');

var nselement1 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement1.text = 'ns:element value 1';

var nselement2 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement2.text = 'ns:element value 2';

nselement2.addAttribute('ns:elementAttr', '25', 'https://www.cumuluspro.com/api/1.0');

var attributeValue = rootnsElement.stringValue('@ns:attr', { 'ns': 'https://www.cumuluspro.com/api/1.0' });

console.log('xpath string attr: ' + attributeValue);
```

#### Result

xpath string attr: attribute value.

#### Result with XML Namespace

xpath string attr: attribute value.

***

### Select Element using Attribute

Evaluates XPath expression relative to current element. Optionally, namespace can be specified.

#### Input Parameters

<table><thead><tr><th width="192.18182373046875">Name</th><th>Description</th></tr></thead><tbody><tr><td>string AttributeFilter</td><td>Attribute filter.</td></tr><tr><td>Namespace</td><td>[Optional] Namespace prefix: Namespace of element.</td></tr></tbody></table>

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var selectElementAttributeStatus = 'fail';

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('attr', 'attribute value');

var element1 = rootElement.addElement('element');

element1.text = 'element value 1';

var element2 = rootElement.addElement('element');

element2.addAttribute('elementAttr', '25');

element2.text = 'element value 2';

var element = rootElement.stringValue('element[@elementAttr = "25"]');

console.log('xpath string query by attr: ' + element);
```

#### Example with XML Namespace

```javascript
var xmlnsDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootnsElement = xmlnsDocument.documentElement;

rootnsElement.addAttribute('ns:attr', 'attribute value', 'https://www.cumuluspro.com/api/1.0');

var nselement1 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement1.text = 'ns:element value 1';

var nselement2 = rootnsElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');

nselement2.text = 'ns:element value 2';

nselement2.addAttribute('ns:elementAttr', '25', 'https://www.cumuluspro.com/api/1.0');

var attributeValue = rootnsElement.stringValue('ns:element[@ns:elementAttr = "25"]', { 'ns': 'https://www.cumuluspro.com/api/1.0' });

console.log('xpath string query by attr: ' + attributeValue);
```

#### Result

xpath string query by attr: element value 2.

#### Result with XML Namespace

xpath string query by attr: ns:element value 2.

***

### Remove Attribute

Removes attribute by name.

#### Input Parameters

string AttribueName.

#### Sample Code

```javascript
var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('attr', 'attribute value');

rootElement.removeAttribute('attr');

console.log(rootElement.xml);
```

#### Result

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root></root>
```