You are here: Reference > Rule types > XMLs > XML Stream form - Completing the XML tab

XML Stream form
Completing the XML tab

  1. About 
  2. New 
  3. Mapping 
  4. Pages & Classes 
  5. XML 
  6. History 
  7. More... 

This tab contains the XML code. If Auto-generated XML is checked, the XML code is generated from the tree structure on the Mapping tab; you cannot edit the generated value.

If Auto-generated XML is cleared, enter the XML code in the XML SOURCE field.

XML schema

Field

Description

Schema URL

Optional. Enter the URL of an XML Schema document to use as input for building the XML tree structure on the Mapping tab. Used only when the Auto-generated XML option is checked. For SOAP services that reference this rule, the Schema URL value is added to the generated WSDL document as an external document import.

This field supports the Global Resource Settings syntax (=PageName.PropertyName). The default property name for this field is pySchemaLocation. For more information, see Using the Global Resource Settings feature.

Auto-generated XML

Select in most cases so that the Pega 7 Platformcan generate the stream XML (as visible in the XML Source field) from the tree structure on the Mapping tab.

Clear this field to allow you to type XML source code into the XML Source field through typing or a text editor such as NotePad or an XML editor. This text is processed by stream processing before use; you can use JSP tags.

Use SOAP 1.1 encoding Select to encode the generated XML using the encoding rules of Section 5 of the SOAP 1.1 protocol. If checked, attributes will be added to element tags for explicitly declaring the type of the element. Used only when the Auto-generated XML option is checked.
Add type attribute to root node Select to add an xsi:type attribute to the root element. This attribute is used to resolve substituted XML content at the service endpoint. For more information about substituted XML content, see PDN article 26003 XSD type and element substitution and the Connector and Metadata Accelerator.
Omit extra spaces

Select to eliminate extra space characters in the processed HTML. This can make transmission or processing more efficient. It does not alter the appearance of the HTML when displayed in a browser.

When selected, the way the system handles stream processing is different for JavaServer Pages (JSP) streams and HTML streams.

JSP streams replace consecutive spaces and control characters with a single space. For example: << space >><< new line >><<tab>> is converted to << space >>. Two or more consecutive space characters are replaced with a single space, except within the curly brace characters defining directives.

As a best practice, remove all line breaks and whitespace. For example:

<pega:choose>

   <pega:otherwise>

Some Value

</pega:otherwise>

</pega:choose>

becomes:

<pega:choose><pega:otherwise>Some Value</pega:otherwise></pega:choose>

HTML streams delete control characters appearing at the beginning of the rule definition and immediately after a directive, but otherwise behave like JSP streams. For example:

<< tab >>{some directive}<< tab >><< space >><< tab >>{some directive}<< space >><< space >>

is converted to:

{some directive}<< space >>{some directive}<< space >>

HTML stream processing copies space characters within the text of a property value and non-breaking spaces (&NBSP;) into the processed HTML without change.

Generate for

This field and the Convert to JSP button appear only when the rule contains directives rather than JSP tags. (The value that appears is HTML.)

As a best practice, use JSP tags rather than directives. In most cases, you can convert XML Stream rules that use directives to use JSP tags automatically, using the button. See Converting from directives to JavaServer Page tags.

Do not save the rule form when the source contains both JSP tags and directives.

If this rule is circumstance-qualified or time-qualified, make this Generate for value match the Generate for value of the base rule. The base rule and the qualified rules must all use JSP tags or all use directives.

Convert to JSP

This button appears only after you save the form when the Generate for value is HTML and this rule is created by a Save As operation. See Converting from directives to JavaServer Page tags.

XML SOURCE

This field is read-only unless Auto-generated XML is cleared.

Enter XML source text. You can type directly into the text area, or you can click the pencil to open Notepad or your registered XML editor.

Use of JSP tags in XML stream rules offers superior performance and other advantages over directives. Although both directives and JSP tags are supported, JSP tags are recommended for new development. Conversion of existing XML stream rules that use directives to functionally equivalent rules that use JSP tags is straightforward.

Recall that the default forms of the <pega:reference > JSP tag (and the reference directive) cause the system to place a space character before and after the output text value of the property. When no added spaces are desired, use the LITERAL keyword in the reference directive:

{ .pyLabel LITERAL }

or equivalently the text mode for the reference JSP tag:

<pega:reference name=".pyLabel" mode="text" />

If the output XML document is to conform to a DTD definition that uses the CDATA convention, always use the LITERAL keyword in the reference directive or the literal mode for the JSP tag. This causes the output value to contain any < and > characters in the property rather than converting these characters to the XML entities &lt; and &gt;.

Use the <% and %> delimiters to surround an inline Java scriptlet within the XML source code.

XML generation

Field

Description

Auto-generated XML

Select in most cases so that the Pega 7 Platformcan generate the stream XML (as visible in the XML Source field) from the tree structure on the Mapping tab.

Clear this field to allow you to type XML source code into the XML Source field through typing or a text editor such as NotePad or an XML editor. This text is processed by stream processing before use; you can use JSP tags.

Use SOAP 1.1 encoding Select to encode the generated XML using the encoding rules of Section 5 of the SOAP 1.1 protocol. If checked, attributes will be added to element tags for explicitly declaring the type of the element. Used only when the Auto-generated XML option is checked.
Add type attribute to root node Select to add an xsi:type attribute to the root element. This attribute is used to resolve substituted XML content at the service endpoint. For more information about substituted XML content, see PDN article 26003 XSD type and element substitution and the Connector and Metadata Accelerator.
Omit extra spaces

Select to eliminate extra space characters in the processed HTML. This can make transmission or processing more efficient. It does not alter the appearance of the HTML when displayed in a browser.

When selected, the way the system handles stream processing is different for JavaServer Pages (JSP) streams and HTML streams.

JSP streams replace consecutive spaces and control characters with a single space. For example: << space >><< new line >><<tab>> is converted to << space >>. Two or more consecutive space characters are replaced with a single space, except within the curly brace characters defining directives.

As a best practice, remove all line breaks and whitespace. For example:

<pega:choose>

   <pega:otherwise>

Some Value

</pega:otherwise>

</pega:choose>

becomes:

<pega:choose><pega:otherwise>Some Value</pega:otherwise></pega:choose>

HTML streams delete control characters appearing at the beginning of the rule definition and immediately after a directive, but otherwise behave like JSP streams. For example:

<< tab >>{some directive}<< tab >><< space >><< tab >>{some directive}<< space >><< space >>

is converted to:

{some directive}<< space >>{some directive}<< space >>

HTML stream processing copies space characters within the text of a property value and non-breaking spaces (&NBSP;) into the processed HTML without change.

Generate for

This field and the Convert to JSP button appear only when the rule contains directives rather than JSP tags. (The value that appears is HTML.)

As a best practice, use JSP tags rather than directives. In most cases, you can convert XML Stream rules that use directives to use JSP tags automatically, using the button. See Converting from directives to JavaServer Page tags.

Do not save the rule form when the source contains both JSP tags and directives.

If this rule is circumstance-qualified or time-qualified, make this Generate for value match the Generate for value of the base rule. The base rule and the qualified rules must all use JSP tags or all use directives.

Convert to JSP

This button appears only after you save the form when the Generate for value is HTML and this rule is created by a Save As operation. See Converting from directives to JavaServer Page tags.

XML SOURCE

Field

Description

XML SOURCE

This field is read-only unless Auto-generated XML is cleared.

Enter XML source text. You can type directly into the text area, or you can click the pencil to open Notepad or your registered XML editor.

Use of JSP tags in XML stream rules offers superior performance and other advantages over directives. Although both directives and JSP tags are supported, JSP tags are recommended for new development. Conversion of existing XML stream rules that use directives to functionally equivalent rules that use JSP tags is straightforward.

Recall that the default forms of the <pega:reference > JSP tag (and the reference directive) cause the system to place a space character before and after the output text value of the property. When no added spaces are desired, use the LITERAL keyword in the reference directive:

{ .pyLabel LITERAL }

or equivalently the text mode for the reference JSP tag:

<pega:reference name=".pyLabel" mode="text" />

If the output XML document is to conform to a DTD definition that uses the CDATA convention, always use the LITERAL keyword in the reference directive or the literal mode for the JSP tag. This causes the output value to contain any < and > characters in the property rather than converting these characters to the XML entities &lt; and &gt;.

Use the <% and %> delimiters to surround an inline Java scriptlet within the XML source code.

Related Topics Link IconRelated information