Service COM form - Completing the Parameters tab

The rule type rule-service-COM is deprecated. As appropriate, migrate to Service dotNET rules.

Use the Parameters tab to define the COM Remote Interface and to specify the mappings between external data values and internal clipboard values. This includes a repeating group of input parameter mappings.

Specify the data types to provide a mapping from the external SOAP type onto the internal Pega Platform type. You can also map values from or to the parameter page.

If SOAP is to return data to the client after the service activity executes, specify a value in the Return Value fields. If the Return fields are blank, the DLL response contains no clipboard data.

Parameters List

Field Description
In/Out Select whether the parameter passes data from the client application to the Pega Platform, from the Pega Platform back to the client application, or both:
  • In — The parameter passes data to the Pega Platform in the request message sent by the client application. The Pega Platform then maps the data to the clipboard using the Map To and Map To Key values. When selected, the Map From and Map From Key values are ignored.
  • Out — The parameter passes data to the client application in the response message sent by the Pega Platform. The Pega Platform then maps the data from the clipboard using the Map From and Map From Key values. When selected, the Map To and Map To Key values are ignored.
  • In/Out — The parameter passes data to the Pega Platform in the request message sent by the client application, then passes data back to the client application in the response message sent by the Pega Platform. The Pega Platform maps this data to the clipboard using the Map To and Map To Key values, and then maps the data from the clipboard using the Map From and Map From Key values.
Data Type Select the external data type of the parameter value: String, Boolean, Long, or Double.
Name Enter the external name of the parameter.
Map To Select how the system creates the input parameter values. The choice you make for this field depends on what you select for Data Type :
  • Clipboard — The system maps the data value to the scalar property specified by the Map ToKey .
  • Username — The system authenticates the user name using the value provided.
  • Password — The system authenticates the password using the value provided.
  • XML ParseRule — Indicates that the incoming data value is a stream of XML that can be parsed using the data mappings specified in a Parse XML rule.
  • HTML PostData — Indicates that the incoming data value is a stream of data posted from an HTML form that contains property key/value pairs in POST format.

If more choices appear, they each identify a custom function rule in a MapTo library. Review the function rule to determine what it does.
Map To Key Identify a target for the choice you made in the Map To field:
  • If the Map To value is Clipboard, enter the property name to which the data is to be mapped. Use the form Param.name parameter name to set a parameter value on the parameter page of the service activity.
  • If the Map To value is HTML PostData, Username, or Password, leave this field blank.

  • If the Map To value is XML ParseRule, enter the Namespace key part of the Parse-XML rule that the system uses to parse the data in the Map To Key field. The system uses the Page Class entered on the Service tab as the first key part, the Applies To key of the parse rule. The system determines the Element Name part of the parse rule key at runtime from the name of the root element of the arriving XML document.

  • 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.
Map From If In/Out is Out or both In / Out, select how the output data maps from the clipboard data:
  • Clipboard — The system maps the data value from the scalar property specified by the Map From key.
  • Constant — The system returns a fixed value.
  • XML Stream — The system composes a stream of XML data formatted by to an XML Stream rule.
  • HTML Stream — The system composes a stream of HTML text formatted by an HTML rule.
  • HTML Frame — The system returns a stream of HTML text generated by the service activity.

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

Map From Key Select a source for the choice you made in the Map From field:
  • If the Map From value is Clipboard, enter the property name to which the data is to be mapped.
  • If the Map From value is Constant, enter a literal string. To include blank spaces in your text string, surround the string with double quotes.
  • If the Map From value is XML Stream, enter the Stream Name key part of the XML Stream rule that is to generate the data. The system uses the Primary Page Class of the service as the Applies To key part.
  • If the Map From value is HTML Stream, enter the Stream Name key part of the HTML rule that is generate the data stream. The system uses the Primary Page Class of the service as the Applies To key part.
  • If the Map From value is HTML Frame, enter the name of the Frame specified in the Show-HTML step of the service activity. Use this to return data from activities that were originally written for interactive browser clients and contain calls to the Show-HTML method.
  • If the Map From value is a Rule-Utility-Function from a MapFrom library, enter or select the property that holds the value to be passed to the custom function.

Return Value

Field Description
Return Value  
Data Type Select the external data type of the return value.
Map From Select how the system maps the output data from the clipboard data. The choice you make for this field depends on what you select for Data Type :
  • Clipboard — The system maps the data value from the scalar property specified by the Map From Key field.
  • Constant — The system returns a fixed value.
  • XML Stream — The system composes a stream of XML data formatted by an XML Stream rule.
  • HTML Stream — The system composes a stream of HTML data formatted by an HTML rule.
  • HTML Frame — The system returns a stream of HTML data generated by the service activity.
Map From Key Enter a source for the choice you made in the Map From field:
  • If the Map From value is Clipboard, enter the property name to which the data is to be mapped.
  • If the Map From value is Constant, enter a literal string. To include blank spaces in your text string, surround the string with double quotes.
  • If the Map From value is XML Stream, enter the Stream Name key part of the XML Stream rule that is to generate the data. Enter only the Stream Name key part; the system uses the Primary Page Class of the service as the Applies To key part of the XML Stream rule instance.
  • If the Map From value is HTML Stream, enter the Stream Name key part of the HTML rule that is to generate the data stream. The system uses the Primary Page Class of the service as the Applies To key part of the HTML rule.
  • If the Map From value is HTML Frame, enter the name of the Frame specified in the Show-HTML step of the service activity. Use to return data from activities that were originally written for interactive browser clients and uses the Show-HTML method.