Service SOAP form — Completing the Request tab

Configure the data mapping of the incoming SOAP request from the external client application to Pega Platform on the Request tab:

  • Complete the Soap action HTTP request header field section to specify a custom SOAPAction URI for the request.
  • Complete the Request Headers section to map data from the SOAP envelope header.
  • Complete the Request Parameters section to map data from the body of the SOAP request.

SOAP action HTTP request header field

Use this section to enter a custom SOAPAction HTTP request header field that allows a server, such as a firewall, to identify the intent of the request, and appropriately filter it. The header field value is a URI that indicates the intent, and it overrides the value that is generated by Pega Platform.

Field Description
Specify customSOAP action URI Select this check box if you want to include a custom SOAPAction URI in the request.
SOAP action URI If you have selected the Specify customSOAP action URI check box, enter the URI of the custom SOAPAction that you want to include in the request. If you leave this value blank, the server presumes that the intent of the SOAP message is provided by the HTTP Request-URI.

When executing a SOAP service, if the SOAPAction header field is empty or does not match the pattern that is specified in the service WSDL document, the first two keys of the Service SOAP rule (service package name and service class name) are derived from the path information of the SOAP endpoint URL. The third key (service method name) is derived from the element name of the first child element of the SOAP body element.

Note: When using the document literal style of SOAP services, the name of the first child element of the SOAP body element is not always the same as the name of the SOAP service method. Do one of the following actions to fix this issue:
  • Use the Save As form of the Service SOAP rule to ensure that the service rule method name and the name of the root element of the XML stream rule used in the SOAP body are the same.
  • Append the service method key to the path information of the SOAP endpoint URL. The format of the endpoint URL will look like this: http://myservicehost:8080/prweb/PRSOAPServlet/SOAP/MyServicePackage/MyServiceClass/MyServiceMethod

Request Headers

Field Description
Data Type Select either string or XML Literal.
Name Enter the external name of the request header.
Description Enter a text description.
Map To If the data type of a request header is XML Literal, set the Map To value to XML ParseRule. If the data type is string, select one of the other Map To options. See the definition of the Map To field in the Request Parameters section.
Map To Key For descriptions of the Map To Key options, see the definition of the Map To Key field in the Request Parameters section.

Request Parameters

Field Description
Data Type Select the data type of the parameter from the subset of XML schema data types supported by SOAP services. See How to complete data mapping for SOAP and dotNet services for details about data types.

Select the XML Page option to indicate that the SOAP operation style for the service rule is to be document-literal rather than RPC-encoded, the parameter is an XML object, and that the data transform specified on the XML Page tab provides the schema definition for the object.

Select the XML Literal data type if the parameter is an XML object and you want to map the actual (literal) XML from an XML stream rule or a single-value text property.
Name Enter the external name of the parameter, to be when the WSDL file is generated. (This need not match a rule or object in Pega Platform.)
Description Optional. Enter a text description of the parameter.
Map To Specify the destination or the type of destination for the value in Pega Platform. The choices in the list depend on value you selected in the Data Type field:
  • Clipboard — Map to the page name or property on the clipboard specified by the Map To Key field. If you selected XML Page as the Data Type, this is the only choice.
  • Requestor ID — Provides the value of the requestor ID to use when the session state is set to stateful but the client application does not support cookies.
  • Username — Provides the Operator ID of an operator ID/password pair to use to authenticate the request when authentication is enabled but the client application does not support HTTP Basic Authentication.
  • Password — Provides the password of an operator ID/password pair to use to authenticate the request when authentication is enabled but the client application does not support HTTP Basic Authentication.
  • XML ParseRule — The incoming data is a stream of XML to be parsed using the actions defined in a parse XML rule.
  • Delimited ParseRule — The incoming data is in a delimited format to be processed by a delimited parse rule.
  • Structured Parserule — The incoming data has a fixed format with fixed-length fields, to be processed by a structured parse rule.
  • HTML PostData — The incoming data value is a stream of data from an HTML form that contains property key/value pairs

If more choices appear, they identify a custom function rule in a MapTo library. Review the function rule to determine what it does.

Map To Key Specify the key to locating the property or the rule in the destination specified in the Map To field:
  • If the Map To value is Clipboard, enter the property name to which the data is to be mapped. If the Data Type is XML Page, create a row on the XML Page tab that associates a page name with a class and a data transform, then specify that page name in the Map To Key field.
  • If the Map To value is XML Parse Rule, enter the Namespace name (second key part) and the Element Name name — third key part — of the appropriate Parse XML rule. Separate the Namespace from the Element name with a space. That is, use the syntax "NamespaceName ElementName" and not "NamespaceName.ElementName." The system uses the page class of this service rule as the first key part of the parse rule.
  • Note: To maintain backward compatibility for service rules created in releases before PRPC Version 5.2, you can specify a data mapping with only a Namespace value. In that case, the system determines the Element Name key at runtime from the root element of the incoming XML document. However, this mapping works only if the Parser Type of the Parse XML rule is set to DOM and validation is not enabled. As a best practice, specify both the Namespace Name and the Element Name of the rule.
  • If the Map To value is Delimited ParseRule, enter the Namespace and Record Type names (second and third key parts) of the appropriate delimited parse rule. The system uses the Applies To class of this service rule as the first key part of the parse rule.
  • If the Map To value is Structured ParseRule, enter the Record Type (third key part) of a structured parse rule. The system uses the Applies To class of this service rule as the first key to the parse rule.
  • If the Map To value is HTML PostData, leave this field blank. The name/value pairs in the string will be mapped to the parameter page of the service activity rather than the primary page.
  • If the Map To value is Requestor ID, Username, Password or HTML PostData, leave this field blank.
  • If the Map To value is a Rule-Utility-Function from a MapTo library, either select a property to hold the results of the function or leave this field blank, as appropriate for the function.