Skip to main content


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

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

XSD type and element substitution for SOAP connectors

Updated on September 10, 2021

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

For more information about XML substitution and polymorphism, see the IBM article Web services tip: Use polymorphism as an alternative to xsd:choice.

XML substitution components in a WSDL or XML schema

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

Linked XSD file

For element substitution, substitutable elements contain a substitutionGroup attribute.
The substitutionGroup attribute in substitutable elements

The substitutionGroup attribute in substitutable elements

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

This example is based on a type substitution scenario.

When the Connector and Metadata Accelerator 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:

Sample XML fragment

Sample 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 PRPC, the inheritance of the NameInfoType is similar to what is displayed in the following figure:

Inheritance of NameInfoTypeInheritance of NameInfoType

In addition, the Connector and Metadata Accelerator 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:
Element substitution in each substitution class

Element substitution in each substitution class

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.
Substitution of the default PersonalInfo element

Substitution of the default PersonalInfo element

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 Overview of rule resolution.

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 PRPC 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.
    Response with name and email information
  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.

    Type substitution table

    The data model of the application displays as shown in the following figure. Notice the two classes present—AlphaCorp-Int-EmailInfoType and AlphaCorp-Int-NameInfoType.

    Data model of the application

  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.
    Structure of the PersonalInfoList page on the clipboardThe 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.
  • Previous topic Calling web services using queued execution
  • Next topic How to build SOAP services based on an XML Schema Definition

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.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us