{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1132,"path":"api-reference/server-api-reference/c_XMLDocument2ScopedAPI.md","title":"XMLDocument2 - Scoped, Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# XMLDocument2 - Scoped, Global\n\nThe XMLDocument2 API is a JavaScript object wrapper for parsing and extracting XML data from an XML string.\n\nUse this JavaScript class to create an object from an XML string, usually a return value from a web-service invocation, or the XML payload of ECC Queue. Using the XMLDocument2 object in a JavaScript business rule lets you query values from the XML elements and attributes directly.\n\nAn XML string has a tree structure, and the parts of the structure are called nodes. An XMLDocument2 object deals with two node types, element, and document element. An element node is a node with a name and possibly attributes and child nodes. A document-element node is the root node of the XML tree. It is the only node without a parent node.\n\n**Note:** This API works for scoped or global applications.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## Scoped XMLDocument2 - XMLDocument2\\(\\)\n\nCreates an XMLDocument2 object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n## Scoped XMLDocument2 - XMLDocument2\\( GlideScriptableInputStream inputStream\\)\n\nCreates an XMLDocument2 object from an attachment stream.\n\n|Name|Type|Description|\n|----|----|-----------|\n|inputStream|GlideScriptableInputStream|The input stream the XMLDocument2 object encapsulates.|\n\n## Scoped XMLDocument2 - createElement\\(String name\\)\n\nCreates and adds an element node to the current node. The element name is the string passed in as a parameter. The new element has no text child nodes.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|The new element's name.|\n\n|Type|Description|\n|----|-----------|\n|XMLNode|Current XML node.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString); \nxmlDoc.createElement(\"new2\"); \n \ngs.info(xmlDoc);\n```\n\nOutput:\n\n```\n?xml version=\"1.0\" encoding=\"UTF-8\"?>\n \n \n abcd1234 \n 1234abcd \n another \n \n 1234\n \n\n```\n\n## Scoped XMLDocument2 - createElementWithTextValue\\(String name, String value\\)\n\nCreates and adds an element node with a text child node to the current node.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|Name of the element to add.|\n|value|String|Element's text value.|\n\n|Type|Description|\n|----|-----------|\n|XMLNode|Current XML node.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString); \nxmlDoc.createElementWithTextValue(\"new\", \"test\");\ngs.info(xmlDoc);\n```\n\nOutput:\n\n```\n\n \n \n abcd1234 \n 1234abcd \n another \n \n 1234\n test\n \n```\n\n## Scoped XMLDocument2 - getDocumentElement\\(\\)\n\nGets the document element node of the XMLdocument2 object. The document element node is the root node.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|XMLNode|The document element.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\n//returns the root node of the document tree.\nvar rootNode = xmlDoc.getDocumentElement();\ngs.info(rootNode.getTextContent());\n```\n\nOutput:\n\n```\nabcd1234 1234abcd another 1234\n```\n\n## Scoped XMLDocument2 - getFirstNode\\(String xPath\\)\n\nGets the first node in the specified xPath.\n\nThis method only supports a subset of predicate xPath expressions. For example, assume the following document:\n\n```\n \n \n \n \n \n \n \n Windows \n 10 \n \n \n Harry Potter \n 50 \n \n \n Learning XML \n 120 \n \n \n Learning Java \n 99 \n \n \n \n \n```\n\nThis method supports the following xPath expressions with predicates:\n\n```\n\"/store/resources/resource[@type='bookstore']/book[@year='1999']\", \n\"/store/resources/resource[@type='bookstore']/book[@year]\", \n\"/store/resources/resource[@type='bookstore']/book[price > 100]\" \n```\n\nHowever, it does not support the following xPath expressions with predicates:\n\n```\n\"/store/resources/resource[@type='bookstore']/book[2]\", \n\"/store/resources/resource[@type='bookstore']/book[last()]\", \n\"/store/resources/resource[@type='bookstore']/book[position()>2]\" \n```\n\nTo work around this, use xPath without predicates, such as `\"/store/resources/resource[@type='bookstore']/book\")` and then filter the nodes in the script using the getFirstNode\\(\\) and [getNextNode\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_XMLDocument2ScopedAPI.md) methods.\n\n|Name|Type|Description|\n|----|----|-----------|\n|xPath|String|The xPath to obtain the node from.|\n\n|Type|Description|\n|----|-----------|\n|XMLNode|The first node.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\nvar foo = xmlDoc.getFirstNode('/test/one/two');\ngs.info(foo.getTextContent());\n```\n\nOutput:\n\n```\nabcd1234\n```\n\n## Scoped XMLDocument2 - getNextNode\\(Object current\\)\n\nGets the node after the specified node.\n\n|Name|Type|Description|\n|----|----|-----------|\n|current|Object|The current node.|\n\n|Type|Description|\n|----|-----------|\n|XMLNode|The next node.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\nvar foo = xmlDoc. getFirstNode('/test/one/two');\nvar foo2 = xmlDoc.getNextNode(foo);\ngs.info(foo.getTextContent());\ngs.info(foo2.getTextContent());\n```\n\nOutput:\n\n```\nabcd1234\n\nanother\n```\n\n## Scoped XMLDocument2 - getNode\\(String xPath\\)\n\nGets the node specified in the xPath.\n\n**Note:** This method is intended for use with small documents since it parses the entire document to match the xPath expression. If the document is too large, an out of memory error may occur. For large documents, use the [getFirstNode\\(String xPath\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_XMLDocument2ScopedAPI.md) and [getNextNode\\(Object current\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_XMLDocument2ScopedAPI.md) methods, which are designed to stream through the document without parsing the entire document.\n\n|Name|Type|Description|\n|----|----|-----------|\n|xPath|String|xPath of the node to obtain.|\n\n|Type|Description|\n|----|-----------|\n|XMLNode|Current XML node.|\n\n```\n/*\n * Checks if given node indeed of given tag.\n * Params:\n * tag - String, name of tag to check\n * node - XMLNode, node in which to check for the tag\n * Returns:\n * true, if tag is present\n * false, otherwise\n */\nfunction isNodeOfTag (node, tag) {\n try {\n if (tag == node.getNodeName()) {\n gs.info(\"Given node belongs to tag \" + tag);\n return true;\n }\n } catch (error) {\n gs.error(\"Given node might not belong to tag \" + tag + \". Error while checking: \" + error);\n return false;\n }\n}\n\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\n\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\n\nvar node = xmlDoc.getNode(\"/test/one/two\"); // tag 'two' is present in this XML.\nisNodeOfTag(node, \"two\");\n\nvar node = xmlDoc.getNode(\"/test/one/four\"); // tag 'four' is not present in this XML.\nisNodeOfTag(node, \"four\");\n```\n\nOutput:\n\n```\nGiven node belongs to tag two\nGiven node might not belong to tag four. Error while checking: java.lang.NullPointerException\n```\n\n## Scoped XMLDocument2 - getNodeText\\(String xPath\\)\n\nGets all the text child nodes from the node referenced in the specified XPath.\n\n|Name|Type|Description|\n|----|----|-----------|\n|xPath|String|XPath of the text to obtain.|\n\n|Type|Description|\n|----|-----------|\n|String|Text children in the XPath.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString); \ngs.info(xmlDoc.getNodeText(\"//two\"));\n```\n\nOutput:\n\n```\nabcd1234\n```\n\n## Scoped XMLDocument2 - parseXML\\(String xmlDoc\\)\n\nParses the XML string and loads it into the XMLDocument2 object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|xmlDoc|String|The document to parse.|\n\n|Type|Description|\n|----|-----------|\n|Boolean|Flag that indicates whether the content was parsed.|\n\nThis example parses the xmlString and loads it into the xmlDocument2 object.\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString); \nvar rootNode = xmlDoc.getDocumentElement();\n```\n\n## Scoped XMLDocument2 - setCurrentElement\\(XMLNode element\\)\n\nMakes the node passed in as a parameter the current node.\n\n|Name|Type|Description|\n|----|----|-----------|\n|element|XMLNode|The element node to set as the current node.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\n//returns the root node of the document tree.\nvar rootNode = xmlDoc.getDocumentElement(); //returns org.w3c.dom.Element\n// sets the root node as the current element\nxmlDoc.setCurrentElement(rootNode);\n```\n\n## Scoped XMLDocument2 - setEnableCDATAReporting\\(Boolean enable\\)\n\nSets whether nodes are treated as CDATA or regular text after parsing. CDATA reporting is deactivated by default.\n\nThis method must be called with [Scoped XMLDocument2 - parseXML\\(String xmlDoc\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_XMLDocument2ScopedAPI.md).\n\nSee also: [Scoped XMLNode - isCDATANode\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_XMLNodeScopedAPI.md).\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nenable\n\n\n\nBoolean\n\n\n\nFlag that indicates whether to handle CDATA nodes as CDATA or regular text nodes.Valid values:\n\n- true: Enable CDATA reporting.\n- false: Handle CDATA nodes as regular text nodes after parsing and concatenate it with the adjacent text.\n\nDefault: False\n\n
|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example shows how CDATA is parsed in an element with CDATA reporting activated. The result of content.getFirstChild\\(\\) is an element that holds the text value `another`. This element internally contains the information identifying it as a CDATA type. The result of content.getLastChild\\(\\) is an element that holds the text value `element`. This element internally contains the information as a text type.\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" 1234abcd\" +\n \" element\" +\n \" \" +\n \" 1234\" \n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.setEnableCDATAReporting(true); // Enable CDATA reporting\nxmlDoc.parseXML(xmlString);\nvar content = xmlDoc.getFirstNode('/test/one/two');\ngs.info(content.getFirstChild().getTextContent()); // prints \"another\"\ngs.info(content.getLastChild().getTextContent()); // prints \"element\"\n```\n\nOutput:\n\n```\nanother\nelement\n```\n\n**Note:** Without CDATA reporting activated in the example, the entire child concatenates the CDATA as text with the rest of the text \\(`element`\\) in each line as follows:\n\n```\nanotherelement\nanotherelement\n```\n\n## Scoped XMLDocument2 - setNamespaceAware\\(Boolean aware\\)\n\nWhen set to true, the XMLDocument2 object processes the document with XML namespaces.\n\nIf you don't set this, an XML document with namespaces won't be enumerated correctly, and an XPath search would fail. \n\n|Name|Type|Description|\n|----|----|-----------|\n|aware|Boolean|When true, the XMLDocument2 object processes the document with XML namespaces.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## Scoped XMLDocument2 - toString\\(\\)\n\nReturns a string containing the XML.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|A string containing the XML.|\n\n```\nvar xmlString = \"\" +\n \" \" +\n \" abcd1234\" +\n \" 1234abcd\" +\n \" another\" +\n \" \" +\n \" 1234\" +\n \"\";\nvar xmlDoc = new XMLDocument2();\nxmlDoc.parseXML(xmlString);\ngs.info(xmlDoc.toString());\n```\n\nOutput - Line breaks were added to the output for readability.\n\n```\n\n \n \nabcd1234 \n1234abcd \nanother \n \n1234\n\n```\n\n"}}