More about Service COM rules

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

DLL generation

See About Service Package data instances for information on generating a Windows Dynamic Linked Library file from Service COM rules.

Initial setup

On the Pega Platform server, the prSOAPServlet servlet implements Service COM rules. This runs as a background requestor with the APP requestor type ( Data-Admin-Requestor class).

Workstation internals

When you use Service COM, your Windows applications or third-party Windows applications can start Pega Platform activities with one-line calls. (Though not visible to the caller, messages between the DLL control and the Pega Platform use SOAP over HTTP protocol.)

For each activity of a package, the generated DLL includes a public method that matches the activity's name. Similarly, method arguments match the activity parameters in quantity, order, and data type. In addition to these public methods, the DLL has four exposed public properties (all strings):

  • sZeusServer — URL of an available Pega Platform server
  • sPortNumber — The TCP/IP port number dedicated to Pega Platform HTTP requests
  • sLoginName — Pega Platform user name
  • sLoginPassword — Pega Platform user password

You can distribute the generated DLL files to third-party application writers. These DLL files can be used as building blocks in Web-based or stand-alone Windows applications. At runtime, when a third-party application starts a public method with a specific activity and specific argument values, the following sequence of events starts (under the DLL wraps). These events are not visible to the application calling the Pega Platform.

  1. The DLL generates a SOAP-conforming XML request. It packs the user name, password, activity name and parameters (arguments) into the request. For additional security, it encodes the password. All character data in the SOAP envelope is encoded, so that characters such as < and > can appear in requests and responses.
  2. The DLL posts the SOAP request using an HTTP connection to a SOAP servlet running on your Pega Platform server. The default path and name is /prweb/PRSOAPServlet.
  3. The Pega Platform SOAP servlet authenticates credentials contained in the request. If the user name and password are accepted, a requestor is opened. (The requestor session is reused during later remote calls.)
  4. The Pega Platform executes the service activity and sends back results in the SOAP response.
  5. The DLL receives the response, parses out the return values (or an error description), converts the results into correct COM data types, and exits the method, making the results available to the calling application.

Calling a Windows DLL

Some applications require a synchronous request to a Windows executable rather than incoming service requests. See How to call a Windows DLL.

Debugging with the Tracer

You can trace the operation of a Service COM rule and the service activity it calls. See Tracing services.

Performance statistics

Through changes to the prlog4j2.xml file, you can obtain performance statistics on the execution of services. See Performance tool — Statistics for services.