# 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>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.cumuluspro.net/developer-guide/straatos-api/straatos-xml-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.