XMLData services

Use XMLData services to convert DOM nodes to XMLData format, query XML nodes, retrieve and set attributes, instance tags, and namespace declarations, and convert XMLData documents to XML strings.

domNodeToXMLData

Converts a DOM node and its child nodes to a document in the XMLData format and optionally validates each node.

This service converts each element and attribute in the DOM node to the XMLData format.
Note: The XMLData is an IData document arranged in a particular format that is described by an XML document type.

A DOM node tree is a special representation of an XML document that can be consumed by any program that uses standard DOM APIs. For example, the xmlStringToXMLNode and mlStringToEnhancedXMLNode services produce a DOM tree. A DOM node tree contains parsed XML content.

Input parameters for domNodeToXMLData

  • node: org.w3c.dom.Node DOM node that is to be converted to an XMLData (Document).
    Note: The com.wm.lang.xml.Node is a DOM node.

  • conformsTo: String. Optional. Fully-qualified name of the XML document type on webMethods Integration against which to validate the DOM node. Specify a value for conformsTo only if you want to do the following:

    • Validate the DOM node as part of converting it to XMLData. webMethods Integration validates a DOM node in the tree as part of converting the tree node to an XMLData-formatted Document.
    • Use the XML document type to direct the conversion of the DOM node. That is, the structure of the XML document type determines the structure of the resulting XMLData.
    Note: You must specify an XML document type for conformsTo if you intend to modify the generated XMLData using the mapping tools available in the pipeline.
    Note: To create an XMLData-formatted Document using the XML document types created from an XML Schema definition, you need specify only one of the XML document types or XML fields created from the schema. webMethods Integration locates the related XML document types, using the complete collection of XML document types and XML fields created from the schema during conversion and validation.

    If you do not specify an XML document type for conformsTo, webMethods Integration does not validate the input nodes as part of the conversion. Additionally, the service formats the resulting XMLData in a generic way instead of in a manner that matches an XML document type.

  • maxErrors: String. Optional. Number of errors to be collected. Default value is 1. When the number of errors found is equal to maxErrors, the validation processor stops validation and returns the result. If maxErrors is set to -1, the validation processor returns all errors.

    The service uses the maxErrors input parameter only when a conformsTo value is specified.

  • ignoreContent: String. Optional. Flag that specifies whether the validation processor will validate simple content where simple content is content keys of the type String, String List, or String Table. Set to:

    • true to ignore content (that is, do not validate the content of keys of the type String, String List, or String Table). webMethods Integration validates the structure and key names of the XML document only.
    • false to validate content. This is the default.

    The service uses the ignoreContent input parameter only when a conformsTo value is specified.

  • failIfInvalid: String. Optional. Flag that indicates whether the service should fail and throw an exception if the object is invalid. Set to:

    • true to indicate that the service should fail if the object is invalid.
    • false to indicate that service should signal success and return errors to the pipeline if object is invalid. This is the default.

    The service uses the failIfInvalid input parameter only when a conformsTo value is specified.

Output parameters for domNodeToXMLData

  • isValid: String. Conditional. Flag that indicates whether or not validation of the DOM node was successful.

    • true indicates that the validation was successful.
    • false indicates that the validation was unsuccessful.

    The service returns isValid only if conformsTo specifies an XML document type.

  • errors: Document List. Conditional. Errors encountered during validation. Each document contains the following information:

    Key Description
    pathName String. Location of the error in XQL.
    errorCode String. Error code (for example, VV-001).
    errorMessage String. Error message (for example, Missing Object).

    The service returns errors only if conformsTo specifies an XML document type.

  • xmlDataDocument: Document. An XMLData-formatted document that represents the elements and attributes in the DOM node.

Usage notes for domNodeToXMLData

  • If the conformsTo input parameter specifies an XML document type or an XML field, the domNodeToXMLData service uses the XML document type (and any other XML document types and XML fields created from the same XML schema definition) to direct the structure of the XMLData, and validates each DOM node in the tree as part of converting it.

  • You can use the Schema validate service to validate XMLData.

  • When validating XML, webMethods Integration uses the Java regular expression compiler.

  • When validating XML, webMethods Integration uses the W3C recommendation XML Schema Part 2: Datatypes.

getAttributes

Retrieves the attributes from an XMLData document.

If an XML Schema definition contains a complex type definition with an anyAttribute declaration, the XML document type created from the schema contains a corresponding *anyAttribute field. As the purpose of the anyAttribute declaration is to act as a placeholder or wildcard, the XML document type cannot have a more specific representation. Use the getAttributes service to retrieve the attribute and attribute value included in an XML document at run time. That is, use the service to find the unknown attributes that are not declared in the XML document type. To set the attribute value in the XMLData, you must use the XML setAttribute service.

Input parameters for getAttributes

  • xmlDataAttributes: Document. The *attributes from which you want to retrieve a list of attributes. The *attributes field is an XMLData document.

    If an element of complex type defines or carries attributes, webMethods Integration places the attributes in an *attributes document that is of type XMLData.

  • ncName: String. Optional. The NCName (non-colonized name) of the attribute. The NCName is also called the local name. If you do not specify a value for ncName, the service returns all attributes belonging to the namespace specified in the namespace input parameter.

  • namespace: String. Optional. The namespace URI for the attribute. If you do not specify a value, the service looks for attributes that do not belong to a namespace.

Output parameters for getAttributes

  • results: Document List. A list of XMLData documents that contain the attributes that match the supplied ncName and namespace values. If no attributes match the supplied values, the service returns an empty (zero-length) list.

    Key Description
    ncName String. The NCName of the attribute.
    namespaceName String. The namespace URI for the attribute.
    value String. The value of the attribute.

getGroupObjects

Queries the object tags and objects in a group of unknown structure to return information about the tags in the group.

The structure of a group is unknown when:

  • The conversion from XML to XmlData is not directed by an XML document type.
  • The complexContent model for a group is anyType.
  • A content model contains any or substitutionGroup particles.

The service returns information for a specific tag or set of tags in a group. (A group consists of tags and objects.) This is in contrast to getGroupValues which returns information about the values in a group.

The service takes a group as input and, for output, produces a list of descriptive information Documents about each tag in the group that meets the provided query criteria. A tag is comprised of a particle-id, a local name, and an optional namespace. The object associated with a tag can be an array if the tag is defined as holding repeating values (maxOccurs > 1).

Input parameters for getGroupObjects

  • query: Document. Document containing the group to query and the query parameters.

    Key Description
    groupValue Document. The group to be queried in an XmlData document.
    ncName String. Optional. The NCName (non-colonized name) of the tags you want to query in the group. The NCName is also called the local name. If you do not specify a value for ncName, the service queries all tags belonging to the namespace specified in the namespace parameter.
    namespace String. Optional. The namespace URI for the tag you want to query in the group. If you specify an empty String, the service queries only tags that do not belong to a namespace. If you do not specify a namespace, the service looks for tags that belong to any namespace. If no ncName and no namespace is specified, the service queries all tags.
    particleID String. Optional. The sequential number for the particle in a group that you want to query. A value of 1 refers to the first instance of the field with ncName#namespace name.

Output parameters for getGroupObjects

  • results: Document List. Query results. Returns one document for each tag in the input group that meets the query parameters.

    Key Description
    ncName String. NCName portion of the tag.
    namespace String. Namespace portion of the tag.
    particleID String. ParticleId portion of the tag.
    tagType

    String. Type of tag. The tagType is one of the following:

    • any
    • group
    • element
    • substitution
    object Object. The object associated with the tag.
    objectType

    String. The base object type. The objectType is one of the following:

    • String
    • Document
    • Object
    hasRepeatingValues

    String. Indicates if the object is an array.

    • true indicates the object is an array.
    • false indicates the object is not an array.
    size String. The size of the array.

Usage notes for getGroupObjects

  • Together, the ncName, namespace, and particleId identify a particular field in the XmlData group.

getGroupValues

Queries the contents of a group with unknown structure to return information about the values in the group.

The contents of a group can be unknown when the instance content corresponds to an anyType, substitutionGroup, or content created without using document type-directed conversion. A group consists of tags and values.

The getGroupValues service accepts a group as input along with an optional set of query parameters. The service produces a set of descriptive information documents about each value in the group. Because each tag can have repeating values, the result list can be much longer than the number of tags present in the provided group. However, the result can be thought of as a flattened list of the objects associated with the tags.

Input parameters for getGroupValues

  • query: Document. Group from which to obtain values and any query parameters to identify the particular field or fields for which you want to obtain values.

    Key Description
    groupValue Document. The group to be queried.
    ncName String. Optional. The NCName (non-colonized name) of the tag you want to query in the group. The NCName is also called the local name. If you do not specify a value for ncName, the service queries all tags belonging to the namespace specified in the namespace parameter.
    namespace String. Optional. The namespace URI for the tag you want to query in the group. If you specify an empty String, the service queries tags that do not belong to any namespace. If you do not specify a namespace and a ncName, the service returns information about all tags.
    particleId String. Optional. The sequential number for the particle in a group that you want to query. A value of 1 refers to the first instance of the field with ncName#namespace name.
    objectIndex String. Optional. Index of an object in the group. You can supply objectIndex instead of supplying ncName, namespace, and particleId.

Output parameters for getGroupValues

  • results: Document List. IData array containing the results of the query for group values. The array contains one document for each value. Because an object can contain multiple values, the length of the list might be longer than the number of tags contained in the group. All the values from all of the tags are combined into a single list, representing the list of values as they appeared in the input XML.

    This service simplifies obtaining values for content when the object tags are a mixture of any and substitution tags. The returned array has the corresponding tags for the value as it appeared in the original XML rather than as it appears in the document type object model.

    Key Description
    objectIndex String. The offset of the object in the list of group objects in the provided groupValue. This is the tag to which the value belongs. If a tag has more than one value, then more than one item in the results array will have the same objectIndex.
    ncName String. NCName portion of the value tag. If the tagType is a substitution or any tag, the value tag will not have the same NCName as the object tag.
    namespace String. Namespace portion of the value tag. If the tagType is a substitution or any tag, the value tag will not have the same namespace as the object tag.
    particleId String. ParticleID portion of the value tag. If the tagType is a substitution or any tag, the particleId is 1.
    index String. The offset into the repeating values for the object that corresponds to objectIndex.
    tagType

    String. Type of tag. The tagType is one of the following:

    • group
    • element
    value Object. Value associated with the tag at the returned index.
    valueType

    String. The base value type. The valueType is one of the following:

    • simple: indicates a String value.
    • group: indicates that the value is an IData that does not contain attributes, nor does it contain a repeating top-level group.
    • complex: indicates the value contains attributes and/or a repeating top-level group.
    • none: indicates an empty model.
    complexContent Object. Conditional. The complexContent for the returned value. The complexContent is returned for complex values only.
    repeatingComplexContent

    String. Conditional. Indicates if the top-level group value is an array.

    • true indicates the object is an array.
    • false indicates the object is not an array.

    This variable is returned only for complex values (that is, when valueType is complex).
    complexContentType

    String. Conditional. The type of complex content. The complexContentType can be one of the following:

    • simple
    • group
    • none
    attributes Document. Conditional. An IData containing the attribute and values. This variable is returned only for complex values (that is, when valueType is complex).

getInstanceTag

Retrieves the value of a specified instance tag from a field in an XMLData document.

An element in an XML document may contain information that is unique to that particular instance document, including instance (xsi) assertions such as type, nil, or schemaLocation. Because instance information cannot be asserted in an XML schema definition, an XML document type cannot contain fields for the instance information. When an XML instance document is parsed and converted to XMLData, webMethods Integration places the instance information in an *instance field under the parent of the field that contains the instance information. Use the getInstanceTag service to retrieve the instance information from the XMLData created from the XML document. To set the value of the instance information in the XMLData, use the XML setInstanceTag service.

Input parameters for getInstanceTag

  • xmlDataParent: Document. The XMLData document that is a parent of the field for which to retrieve the instance tag value.

  • ncName: String. The NCName (non-colonized name) of the field for which you want to retrieve an instance tag value. The NCName is also called the local name.

  • namespace: String. Optional. The namespace URI for the field for which you want to retrieve an instance tag value. If you do not specify a value, the service looks for tags that do not belong to a namespace.

  • particleId: String. The sequential number for the particle in a model group for which you want to retrieve an instance tag value. A value of 1 refers to the first instance of the field with ncName#namespace name in a model group.

  • index: String. Optional. If the field for which you want to retrieve a tag value is a repeating field (minOccurs > 0), specify the index for the occurrence for which you want to retrieve a tag value. A value of 0 refers to the first instance of a repeating field.

    Note: Repeating elements are represented as arrays in XMLData.

  • tagName: String. Name of the instance tag for which you want to retrieve a value, such as type, nil, schemaLocation.

    Note: Tag names are case-sensitive.

Output parameters for getInstanceTag

  • tagValue: String. Value of the tag.

Usage notes for getInstanceTag

  • Together, the ncName, namespace, particleId, and index identify a particular field in the XMLData document.

getNamespaceTags

Retrieves the namespace declarations, specifically the prefix and namespace URI, associated with a particular field in an XMLData document.

An element in an XML document may contain information that is unique to that particular instance document, including namespace declarations and instance assertions such as type, nil, or schemaLocation. A namespace declaration associates a prefix with a namespace URI. Because namespace declarations cannot be asserted for an element in an XML schema definition, an XML document type cannot contain fields for the namespace declarations. When an XML instance document is parsed and converted to XMLData, webMethods Integration places the namespace declarations in a *namespace field under the parent of the element that contains the namespace declaration. Use the getNamespaceTag service to retrieve the namespace declarations for a particular field from the XMLData created from the XML document. To set the value of a namespace declaration for a particular field in the XMLData, use the XML setNamespaceTag service.

Input parameters for getNamespaceTags

  • xmlDataParent: Document. The XMLData document that is a parent of the field for which to retrieve the namespace tag and value.

  • ncName: String. The NCName (non-colonized name) of the field for which you want to retrieve a namespace declaration. The NCName is also called the local name.

  • namespace: String. Optional. The namespace URI for the field for which you want to retrieve the namespace declaration. If you do not specify a namespace, the service looks for a field that does not belong to a namespace.

  • particleId: String. The sequential number for the particle in a model group for which you want to retrieve a namespace declaration. A value of 1 refers to the first instance of the field with ncName#namespace name in a model group.

  • index: String. Optional. If the field for which you want to retrieve a namespace declaration is a repeating field (minOccurs > 0), the index for the occurrence for which you want to retrieve the namespace declaration. A value of 0 refers to the first instance of a repeating field.

    Note: Repeating elements are represented as arrays in XMLData.

Output parameters for getNamespaceTags

  • results: Document List. A document (IData) containing namespace declarations for the specified field. A namespace declaration consists of a prefix and a namespace URI.

    Key Description
    tagName String. Prefix specified in the namespace declaration. The tagName parameter contains an empty string if this is the default namespace declaration.
    tagValue String. The namespace URI associated with the namespace declaration.

Usage notes for getNamespaceTags

  • Together, the ncName, namespace, particleId, and index identify a particular field in the XMLData.

queryXMLNode

Queries an XML node and returns the results in the XMLData format in which field names are fully qualified with an ncName and a namespace.

The fields parameter specifies how data is extracted from the node to produce an output variable. This output variable is called a binding because the fields parameter binds a certain part of the document node to a particular output variable. At run time, this service must include at least one fields entry and at least one entry in fields. The result of each query you specify in fields is returned in a variable whose name and type you specify.

Each fields list defines bindings for one level of the output with the top-level fields being the pipeline and the first level down fields being contents of a document or document list in the pipeline. As such, the top-level fields parameter is not namespace qualified but the lower-level fields are.

Input parameters for queryXMLNode

  • node: The XML node or enhanced XML node that you want to query. This parameter supports the following types of input:

    • com.wm.lang.xml.Node. XML node that you want to query. An XML node can be produced by XML service loadXMLNode, xmlStringToXMLNode, or an XML content handler.
    • enhanced XML node. The enhanced XML node that you want to query. An enhanced XML node can be produced by XML service loadEnhancedXMLNode, xmlStringToEnhancedXMLNode, or an XML content handler that receives a document with xmlFormat set to enhanced. If you supply an enhanced XML node, you must use XQL to query the node.

  • nsDecls: Document. Optional. Namespaces associated with any namespace prefixes used to specify elements in fields/query. 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.

    nsDecls is not used for creating output fields.

    Instead of defining prefix/namespace pairs in nsDecls, you can specify a namespace for each field using the namespace parameter that is an immediate child of the fields variable (fields/namespace).

  • defaultNamespace: String. Optional. The namespace to use as the default for each namespace parameter. An empty string indicates no default namespace. You can override the default namespace by specifying a namespace for a field in the fields/namespace parameter.

  • fields: Document List. Optional. An array of documents where each document defines a field to be created in the output. Each document contains parameters that describe how data is to be extracted from node. That is, each document in the list contains parameters for a single query.

    Key Description
    name

    String. Optional. Name to assign to the value resulting from the query. That is, the name of a field output by the service. Typically, this name field is used for top-level fields because top-level fields produced by this service equate to named pipeline variables. However, the name field may also be used to name the *attributes document.
    resultType

    String. Object type that the query is to yield. The following shows the allowed values:

    Underlying Value Corresponding Data Type
    Object Object
    Object[] Object List
    Record Document
    Record[] Document List
    String String
    String[] String List
    String[][] String Table
    query

    String. Query identifying the data to be extracted from node. The query must use the prefix-qualified form for tag names (even though the output is formatted as XmlData). If prefix-qualified names are used, the nsDecls parameter must also be set.
    queryType

    String. Query language in which query is expressed. Valid values are WQL and XQL. If the content of node is an enhanced XML node, you must set queryType to XQL.
    childTags

    String. Type of tags generated in the child fields produced by this field. Specify one of the following:

    • element to indicate element tags are created. This is the default.
    • attribute to indicate attribute tags are created. An attribute tag will not have a particleId.
    onnull

    String. Optional. Code indicating what you want queryXMLNode to do when the result is null. Set to one of the following:

    • continue to indicate that all result values are acceptable for this query (including null).
    • fail to indicate that the service should fail if the result of this query is null and continue in all other cases.
    • succeed to indicate that the service should continue if the result of this query is null and fail in all other cases.
    fields

    Document List. Parameters that support nested execution of bindings. Each fields list defines bindings for one level of the output with the top-level being the pipeline and the first level down being contents of a document or document list in the pipeline. The nested fields/fields variable contains the same input parameters as the top-level fields (name, query, resultType, etc.) with the addition of the following parameters needed to identify a particular field in the XMLData-formatted document. The ncName, namespace, and particleId inputs are only supported from the second level and down.

    Key Description
    ncName String Optional. The NCName for the output field.
    namespace String Optional. The namespace portion of the output field. An empty string indicates no namespace. This value overrides the defaultNamespace value.
    particleID String Optional. The particleId portion of the output field.

Usage notes for queryXMLNode

  • The queryXMLNode XMLData service differs from the queryXMLNode XML service which returns the results in the legacy infoset format in which fields are qualified with a prefix and a namespace name. The queryXMLNode XMLData service uses the NCName, namespace, and particleID to qualify the output format. Use the queryXMLNode XMLData service when you are working with XMLData-encoded infoset. Use the queryXMLNode XML service when you are working with the legacy-encoded infoset.

setAttribute

Sets the value for a specific attribute in an XMLData document.

While the primary purpose of this service is to set the value of an attribute that is the runtime replacement for an anyAttribute declaration, you can use this service to set the value of any of the attributes in an XMLData document.

Input parameters for setAttribute

  • xmlDataAttributes: Document. The *attributes document of type XMLData in which you want to set the value of an attribute.

  • ncName: String: The NCName (non-colonized name) of the attribute whose value you want to set. The NCName is also called a local name.

  • namespace: String. Optional. The namespace URI for the attribute whose value you want to set. Leave namespace blank if the attribute does not belong to a namespace.

  • value: String. The value that you want to assign to the attribute.

Output parameters for setAttribute

None.

setInstanceTag

Sets the value of an instance tag for a specific field in an XMLData document.

Input parameters for setInstanceTag

  • xmlDataParent: Document. The XMLData document that is a parent of the field for which to set the instance tag value.

  • ncName: String. The NCName (non-colonized name) of the field for which you want to set an instance tag value. The NCName is also called the local name.

  • namespace: String. Optional. The namespace URI for the field for which you want to set an instance tag value. If the field does not belong to a namespace, do not specify a value for the namespace input parameter.

  • particleID: String. The sequential number for the particle in a model group for which you want to set an instance tag value. A value of 1 refers to the first instance of the field with ncName#namespace name.

  • index: String. Optional. If the field for which you want to set a tag value is a repeating field (minOccurs > 0), the index for the occurrence for which you want to set a tag value. A value of 0 refers to the first instance of a repeating field. If you specify an array index that is greater than the current size of the array, the array size increases and missing entries are null.

    Note: Repeating elements are represented as arrays in XMLData.

  • tagName: String Name of the instance tag for which you want to set a value, such as type, nil, schemaLocation.

    Note: Tag names are case-sensitive.

  • tagValue: String Value to assign to the instance tag. If you specify a null value, the service removes the tag and its value from the XMLData.

Output parameters for setInstanceTag

None.

setNamespaceTag

Sets the namespace declaration for a particular field.

Input parameters for setNamespaceTag

  • xmlDataParent: Document. The XMLData document that is a parent of the field for which to set a namespace declaration.

  • ncName: String. The NCName (non-colonized name) of the field for which you want to set a namespace declaration. The NCName is also called the local name.

  • namespace: String. Optional. The namespace URI for the field for which you want to set a namespace declaration. If the field does not belong to a namespace, do not specify a value for the namespace input parameter.

  • particleID: String. The sequential number for the particle in a model group for which you want to set a namespace declaration. A value of 1 refers to the first instance of the field with ncName#namespace name.

  • index: String. Optional. If the field for which you want to set a namespace declaration is a repeating element (minOccurs > 0), the index for the occurrence for which you want to set a tag value. A value of 0 refers to the first instance of a repeating field. If you specify an index that is beyond the end of the array, the service increases the size of the array and the intervening indexes have a null value.

    Note: Repeating elements are represented as arrays in XMLData.

  • tagName: String. The prefix to associate with the namespace declaration. Specify an empty string to associate a value with the default namespace declaration, that is, specify: ""

  • tagValue: String. The namespace URI to associate with the prefix in tagName. If you specify a null value, the service removes the namespace declaration from the XMLData.

Output parameters for setNamespaceTag

None.

xmlDataToXMLString

Converts an XMLData document to an XML string.

The xmlDataToXMLString service recurses through a given document formatted as XMLData, building an XML representation from the elements within it. Key names are turned into XML elements and attributes, and the key values are turned into the contents of those elements.

Input Parameters for xmlDataToXMLString

  • xmlDataDocument: Document. XMLData document that is to be converted to XML.

  • 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.

    • false to not HTML-encode the data. This is the default.

      For example, the string expression 5 < 6 would be converted to <expr>5 < 6</expr>, which is invalid.

Output parameters for xmlDataToXMLString

  • xmlString: String XML String produced from xmlDataDocument.