Integration Server 10.5 | Built-In Services Reference Guide | XML Folder | Summary of Elements in this Folder | pub.xml:documentToXMLString
 
pub.xml:documentToXMLString
WmPublic. Converts a document (IData object) to an XML string.
This service recurses through a given document, building an XML representation from the elements within it. Key names are turned into XML elements, and the key values are turned into the contents of those elements.
This service would convert this document (IData object)...
To an XML document that looks like this...
<?xml version="1.0" ?>
<tns:AcctInfo>
xmlns:tns="http://localhost/DerivedAddress/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
<acctNum type=platinum>G97041A</acctNum>
<phoneNum cc=011>216-741-7566</phoneNum>
<address country=USA>
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
</address>
<address country=USA xsi:type="tns:DerivedAddress">
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
<landMark>Besides Ohio River-Bank Square</landMark>
<telNo>001222555</telNo>
</address>
<serialNum>19970523A</serialNum>
<serialNum>20001106G</serialNum>
<serialNum>20010404K</serialNum>
</tns:AcctInfo>
Note that:
*Key names that start with the attribute prefix (which, in this example, is the "@" character) are turned into attributes of the elements in which they occur. For example, the @type key in the acctNum element is converted to the type=platinum attribute of the <acctNum> element in the resulting XML String.
*Some modules, such as EDI and FlatFile, have fields that begin with the @ symbol that will be considered attributes regardless of whether the attrPrefix is @ or another character. For example, the FlatFile module always considers fields named @record-id and @delimiters to be attributes.
*When a document type contains a String variable that represents a required attribute (meaning that the variable name starts with the "@" symbol and the Required property is set to True in Designer) and the input document does not contain the required attribute, Integration Server adds an empty attribute during document encoding. For example, if the document type contains a required String variable named @myAttribute but @myAttribute is missing from the input document, Integration Server adds myAttribute ="" to the XML document.
Note:
Because empty xmlns attributes are invalid, if the document type contains a required String variable named @xmlns and the input document does not specify a value for the @xmlns attribute, Integration Server does not add xmlns="" to the XML document.
*Also note that the *body key is used to represent the value of a simple element that contains both a text value and an attribute. See the acctNum and phoneNum keys for an example of this kind of element.
*The *doctype field is used to represent the IS document type to which the IData object conforms. This field is used to populate the relevant value for the xsi:type attribute in the XML string. The document type referred by the *doctype field should either be created by importing an XSD file (XML schema) or generated while consuming WSDL for a provider or consumer web service descriptor. You should also select the Register document types with schema type option in the New Document Type wizard when generating a document type from an XML schema.
*Fields that are not String or Document based (for example, Floats or Integers) are converted to XML values using the underlying object's toString method.
Input Parameters
attrPrefix
String Optional. Prefix that designates keys containing attributes. The default prefix is "@".
For example, if you set attrPrefix to ATT_ and document contained the following element:
pub.xml:documentToXMLString would convert the ATT_currency key to the attribute, currency=dollars, in the <tx> element as shown below:
<tx currency=dollars>
<acct>cash</acct>
<amt>120.00</amt>
</tx>
document
Document IData object that is to be converted to XML. Note that if you want to produce a valid XML document (one with a single root node), document must contain only one top-level IData object (that is, a single document). The name of that document will serve as the name of the XML document's root element.
For example, document shown in the example in this service's description contains one top-level document named AcctInfo, which would result in one root element named <AcctInfo> in the resulting XML String.
If you needed to produce an XML fragment (for example, a loose collection of elements that are not encompassed within a single root element) then document can contain multiple top-level elements. To produce this type of output, you must also set the addHeader and enforceLegalXML parameters to false.
nsDecls
Document Optional. Namespaces associated with any namespace prefixes that are used in the key names in document. Each entry in nsDecls represents a namespace prefix/URI pair, where a key name represents a prefix and the value of the key specifies the namespace URI.
For example, to define the URIs associated with two prefixes called GSX and TxMon, you would set nsDecls as follows:
For each prefix specified in nsDecls, pub.xml:documentToXMLString generates an xmlns attribute and inserts it into the top-most element of the resulting XML String. For example, if nsDecls had the two keys shown above, pub.xml:documentToXMLString would insert the following attributes into the root element of the XML String:
xmlns:gsx="http://www.gsx.com"
xmlns:TxMon="http:www.acrtrak/txMonitor"
Note:
Alternatively, you can declare a namespace by including an @xmlns key in document. (If you were not using the @ character to designate attributes, use the correct attribute prefix in your code.)
addHeader
String Optional. Flag specifying whether the header element:
<?xml version="1.0"?>
is to be included in the resulting XML String.
Set to:
*true to include the header. This is the default.
*false to omit the header. (You would omit the header to generate an XML fragment or to insert a custom header.)
encode
String Optional. Flag indicating whether to HTML-encode the data. Set this parameter to true if your XML data contains special characters, including the following: < > & " '
Set to:
*true to HTML-encode the data.
For example, the string expression 5 < 6 would be converted to <expr>5 &lt; 6</expr>, which is valid.
If you do not want a leading & (ampersand) character encoded when it appears as part of a character or entity reference, set preserveRefs to true.
*false to not HTML-encode the data. This is the default.
For example, the string expression 5 < 6would be converted to <expr>5 < 6</expr>, which is invalid.
preseveRefs
String Optional. Flag indicating whether the leading & (ampersand) of a well-formed entity or character reference is left as & or further encoded as &amp; when the data is to be HTML-encoded (encode is set to true).
Set to:
*true to preserve the leading & (ampersand) in an entity or character reference when the service HTML-encodes the data.
*false to encode the leading & (ampersand) as &amp; when the & appears in an entity or character reference. This is the default.
The pub.xml:documentToXMLString service ignores the value of preseveRefs when encode is set to false.
documentTypeName
String Optional. Fully qualified name of the document type that describes the structure and format of the output document (for example, examples.rtd:exampleRecord1).
You can use this parameter to ensure that the output includes elements that might not be present in document at run time, or to describe the order in which elements are to appear in the resulting XML String.
If you are using derived type processing, you must provide this parameter.
generateRequiredTags
String Optional. Flag indicating whether empty tags are to be included in the output document if a mandatory element appears in the document type specified in documentTypeName but does not appear in document. Set to:
*true to include mandatory elements if they are not present in document.
*false to omit mandatory elements if they are not present in document. This is the default.
Note:
The generateRequiredTags is only applicable if documentTypeName is provided.
generateNilTags
String Optional. Flag indicating whether the resulting XML string includes the attribute xsi:nil for elements that are null. Set to:
*true to generate the xsi:nil attribute for an element if the Allow null property for the corresponding field is set to true and the field is null in document.
Note:generateRequiredTags must also be set to true to generate the xsi:nil attribute in the XML String.
*false to omit the xsi:nil attribute even if a nillable field is, in fact, null. This is the default.
enforceLegalXML
String Optional. Flag indicating whether the service throws an exception when document contains multiple root elements or illegal XML tag names. Set to:
*true to throw an exception if document would produce an XML String containing multiple root elements and/or illegal XML tag names.
*false to allow the resulting XML String to contain multiple root elements and/or illegal XML tag names. You would use this setting, for example, to create an XML fragment composed of multiple elements that were not all enclosed within a root element. This is the default.
dtdHeaderInfo
Document Optional. Contents of the DOCTYPE header to be inserted into the XML String. (You can retrieve this information from an incoming document using pub.xml:getXMLNodeType.)
Key
Description
systemID
String Optional. System identifier for the DTD, if any.
publicID
String Optional. Public identifier for the DTD, if any.
rootNSPrefix
String Optional. Namespace prefix of the rootLocalName, if any.
rootLocalName
String Optional. Local name (excluding the namespace prefix) of the root element.
bufferSize
String Optional. Initial size (in bytes) of the String buffer that documentToXMLString uses to assemble the output XML String. If the String buffer fills up before documentToXMLString is finished generating the XML String, it reallocates the buffer, expanding it by this amount each time the buffer becomes full.
If you do not set bufferSize, documentToXMLString looks to see whether a default buffer size is specified in the following parameter on the server:
watt.server.recordToDocument.bufferSize
If so, it uses this value to allocate the String buffer. If this parameter is not set, documentToXMLString uses a default buffer size of 4096 bytes.
For best performance, you should always set bufferSize to a value that closely matches the size of the XML String that you expect documentToXMLString to produce. This practice will spare the server from having to enlarge the buffer repeatedly if the XML String is many times larger than the default buffer or if you arbitrarily set bufferSize to a value that is too small.
Setting bufferSize to an appropriately sized value will also prevent your service from unnecessarily consuming more memory than it needs if the XML String is much smaller than the default buffer size or if you arbitrarily set bufferSize to a value that is too large.
Output Parameters
xmldata
String XML String produced from document.
Usage Notes
If you are building an IData that will be converted to an XML String, keep the following points in mind:
*If you want to generate a simple element that contains only a character value, represent it with a String element in document as shown in the following:
*If you want to generate an element that contains children, represent with an IData in document as shown in the following.
To produce attributes, put the attribute values in keys whose name starts with the character(s) specified in attrPrefix. For example, if you use the default attrPrefix, the names of all keys containing attributes (and only those keys containing attributes) must start with the @ character (for example, @type, @xmlns).
Also, when you include attributes, make sure that keys representing attributes are direct children of the elements in which they are to be applied. For example, if you want to include an xmlns attribute in the <AcctInfo> element in the example shown in the description of this service, you must create a String field named @xmlns in the AcctInfo field within document.
*If you want to generate a simple element that contains a character value and one or more attributes, you must represent it as an IData that has one key for each attribute and a key named *body that contains element's value. For example, if you wanted to produce the following element:
<phoneNum cc=011>216-741-7566</phoneNum>
You would include the following in document:
*To include namespaces, make sure you do the following:
*Include the appropriate namespace prefix in the key names in document. For example, to produce an element called acctNum that belongs to a namespace that is represented by the "GSX" prefix, you would include a key named GSX:acctNum in document.
*Define the URIs for the prefixes that appear in document. You can do this through nsDecls or by including an @xmlns key in the element where you want the xmlns attribute to be inserted. See the nsDecls description above for more information about declaring namespaces.
To return the processed XML document to the client that originally submitted it, invoke pub.flow:setResponse. Keep in mind that you may need to modify the encoding.
To generate the xsi:nil attribute for an element in the XML String, the following must be true:
*documentTypeName must be provided.
*generateRequiredTags and generateNilTags must be set to true.
*The element must correspond to a field that is nillable. That is, the Allow null property must be set to True.
*If the element corresponds to a document field, at run time, the document must not contain any content. However, if the document contains a *body field, the pub.xml:documentToXMLString service generates the xsi:nil attribute for the corresponding element if the value of *body is null.
If a document field is nillable and is null at run time, the resulting XML String does not contain any child elements for the element that corresponds to the document.
By default, the pub.xml:documentToXMLString service uses the prefix "xsi" for the nil attribute, where xsi refers to the namespace http://www.w3.org/2001/XMLSchema-instance. If nsDecls declares a different prefix for this namespaces, the service uses that prefix instead of xsi.