Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

XSD type and element substitution for SOAP connectors

Updated on April 6, 2022

When you create a SOAP connector, support for XSD type and element substitution enables the Connector and Metadata wizard to generate classes with dynamic directed inheritance. The wizard also generates linked map rules when the wizard runs against a WSDL file that references a compatible external XSD document.

XML substitution components in a WSDL or XML schema

For type substitution, a linked XSD file contains an abstract base type and several extension elements.

For element substitution, substitutable elements contain a substitutionGroup attribute.

Alteration of the Connector and Metadata wizard output by XML substitution components

The following example is based on a type substitution scenario.

When the Connector and Metadata wizard is run against a WSDL file that imports an XSD file that defines substitutable XML, a class is generated for each type. Each class that is generated for a substitute type or element is configured to directly inherit from the base type class. Consider the following XML fragment:

In this example, the PersonalInfoBaseType complex type is an abstract type, which means that it is substituted by other types. The NameInfoType complex type is one of the substitutable types. The <xsd:extension> tag specifies PersonalInfoBaseType as the base.

In Pega Platform, the inheritance of the NameInfoType is similar to what is displayed in the following figure:

In addition, the Connector and Metadata wizard creates a series of mapping rules to enable the substitution of rules. The class of the connector contains the Connect rule, in this example AlphaCorp-Int-PersonalInfoService1, that contains a Parse XML rule with a repeatable element called PersonalInfo. This element applies a Parse XML rule called urn:megacorp:xsd:PersonalInfoList1 PersonalInfo. A Parse XML rule of the same name is in each substitute class, which is then called at run time.

This element is substituted by a corresponding element in each substitute class, as shown in the following figure:

By setting the node substitution to Type, the Parse XML rule substitutes the default PersonalInfo element with a PersonalInfo element from the appropriate class, as shown on the XML tab.

For element substitution examples, a section called ELEMENT SUBSTITUTION is completed on the same tab.

Alteration of the run-time processing of rules by XML substitution components

XML substitution and rule resolution work together to provide run time rule substitution. As displayed earlier in this article, the hierarchical structure of the XSD file closely matches the resulting class structure that is generated from the Connector and Metadata Accelerator. Additionally, the generated XML Stream rules use rule resolution to dynamically select the correct rule to include in an outgoing XML stream. For more information about rule resolution, see <new link to rule resolution TBD>.

As described earlier in this article, Parse XML rules require additional configuration to resolve substituted rules. The system uses the Namespace value to find and map the type (or element name, for element substitution) from the original XSD file to a Pega Platform class name. This changes the Applies To class of the referenced Parse XML rule to the appropriate class so that the correct rule is being referenced.

Example of rule substitution at run time

The following example of type substitution shows email and name information being returned from a service and mapped to the correct properties on the clipboard. This mapping takes place when the response is received.

  1. After an employee ID is sent to the service, a response is returned that contains name and email information, as well as the XML type in which these elements are defined.
  2. By using the type substitution table on the XML tab of the Parse XML rule form, substitution of the PersonalInfo element is performed based on the types that are returned in the response. The PersonalInfo element is a repeating element, which means that it is defined on a Page List property. The Page Class of this Page List is set based on the XML type.

    The data model of the application displays the two classes AlphaCorp-Int-EmailInfoType and AlphaCorp-Int-NameInfoType.

  3. The structure of the PersonalInfoList page on the clipboard matches the structure of the tree in the Parse XML rule. The PersonalInfo page list contains two pages, one for each type that is returned by the service.

    The page class for each embedded page is determined by the <xsi:type> attribute for each element that appears under the PersonalInfoList element in the returned XML. When using element substitution, the page class is determined by the element name. You can write conditional activity steps based on page class, or overridable rules to process data in substitutable classes.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us