Close popover

Table of Contents

How to reduce maintenance of service rules and listeners with global resource settings

Summary

When you migrate an application from one server or environment to another, references to the external systems that those applications connect to, such as endpoint URLs and JNDI servers, may change.

Some of these references are in rules, which may belong to locked RuleSet Versions. To avoid having to unlock and update rules, and to manually update these references after migrating, configure them using the V5.3 Global Resource Settings feature.

Quick Links

Overview

Implementing the Global Resource Settings feature

  1. Determine which references will use the Global Resource Settings feature
  2. Create a class to contain the environment properties
  3. Create the environment properties
  4. Create a Model Rule to assign values to the environment properties
  5. Create a Declarative Page

Supporting information

Overview

The Global Resource Settings feature acts like a set of environment variables. Use the Global Resource Settings syntax to represent values that can change—in this case, references to external systems—rather than hard-coding that information in your applications.

Global Resource Settings syntax

The Global Resource Settings syntax has two parts:

=PageName.PropertyName

where PageName is the name of a page, and PropertyName is the name of a property on that page. At runtime, the property value contains a reference to an external system—a JNDI server name, for example.

Before you can use the Global Resource Settings syntax to reference external systems, however, you must create a number of supporting rules.

back to top

Supporting rules

When you implement the Global Resource settings feature, you create various rules to store the values for your references to external systems—a class rule, multiple property and model rules, and a declarative page rule.

  • The class rule acts as a container, holding the property and model rules. You can create your own class or modify the PegaSample-Env class to suit your system.
  • The properties (called environment properties in the rest of this document) act as variables, representing references to external systems. To simplify creating the properties, V5.3 includes standard Embed-Env-Connect classes. These classes contain environment properties for each external system type that the Global Resource Settings feature supports. Refer to these properties in the PropertyName portion of the Global Resource Settings syntax.
  • The model rules store values for the environment properties. Standard Utility functions can retrieve the property values.
  • The declarative page rule brings the environment property rules together with the values that are stored in the model, and writes those property/value pairs to the clipboard. Refer to this declarative page in the PageName portion of the Global Resource Settings syntax.

At runtime, Process Commander evaluates any value that uses the Global Resource Settings syntax and substitutes the appropriate value from the clipboard.

back to top

About Declarative Pages

Declarative pages allow you to create clipboard pages and use Activity rules to populate those pages with data. These pages can be shared (in read-only mode) by all users on a given node. To implement the Global Resource Settings feature, create a declarative page that calls the LoadResourceSettings activity. This activity loads the model that you created. At runtime, the declarative page creates a clipboard page that is populated with the system's environment properties and the associated values from the model.

For more information about Rule-Declare-Pages rules and declarative pages, consult the Help topics.

back to top

Passwords and the Global Resource Settings feature

You must encode any passwords you store using the Global Resource Settings feature. The Encode() function provides base64 encoding. See Utility functions for the Global Resource Settings feature for more information.

Note: Create the supporting rules for the Global Resource Settings feature before you save a rule that uses the Global Resource Settings syntax to represent a password.

back to top

Implementing the Global Resource Settings feature

Implementing the Global Resource Settings feature is a multi-step process with two main tasks:

The following sections describe these tasks in detail.

Task One: Set up the values for the Global Resource Settings

Complete the following steps to set up the values for your Global Resource Settings:

1: Determine which references will use the Global Resource Settings feature

The first step in implementing the Global Resource Settings feature is to determine which references to external systems will use the feature. See Fields that Support the Global Resource Settings Syntax for a list of the supported reference types.

back to top

2: Desiginate a class for the declarative page

After you have decided which references to implement the Global Resource Settings feature for, create or identify a class to contain environment properties that represent those references. A page of that class becomes the declarative page for the application.

As a best practice, choose a class name that includes the application name. (Later, use the same approach when choosing a name for the declarative page itself). This helps avoid later confusion when users access multiple applications, each of which has a declarative page.

Process Commander includes a sample class PegaSample-Env and sample activity PegaSample-Env.LoadResourceSettings that demonistrate a (non-working) example of this approach.

back to top

3: Create the environment properties

Now create the properties themselves. To make this process easier, V5.3 includes standard Embed-Env-Connect classes. These classes contain environment properties for each external system type that the Global Resource Settings feature supports. This means that instead of creating each resource settings property individually, you can create one instance of a Page property that references the appropriate Embed-Env- class for your system.

In the class you identified in step 2, create N page properties, where N is the number of connectors that you want to use Global Resource Settings.  Each page property should reference an Embed-Env-* class that is appropriate for that type of connector

See Embed-Env Classes and default environment properties for a list of the embed classes and the environment properties.

Complete the following steps to create the environment property rules for your system:

  1. Select Application>New>Rule >Property>Property. The New Rule Instance form appears.
  2. Fill out the form, specifying the class that you created in step 2 in the Applies To field.
  3. Click Create. The Property form appears.
  4. Fill out the form. Set the Property Mode field to Page. Set the Page Class field to the appropriate Embed-Env- class for your application. For example, if you are implementing Global Resource Settings for a SOAP connector, set the field to Embed-Env-SOAP. See Embed-Env Classes and Default Environment Properties for a list of the Embed- classes and their environment properties.
  5. Save your property rule.
  6. Repeat steps a - e for each connector rule that will use the Global Resource Settings feature.

For example, if your application includes two SOAP connectors, one for Time and one for Expense, repeat the preceding steps twice to create one property rule named Time, and one property rule named Expense. This process creates the following properties:

  • .Time.pyEndpointURL
  • .Expense.pyEndpointURL

back to top

4: Create a model rule to assign values to the environment properties

After you have created the environment properties for your applications, you must create at least one model rule to assign values to those properties.

You may want to create multiple model rules of the same name, each containing values that are appropriate for a certain environment type. For example, you might want to create three different models for your SOAP connector environment properties—one with values for the development environment, one with values for the testing environment, and one with values for the production environment. In this case, you would circumstance the model rule to run for the appropriate environment type, based on the value of the pyProductionLevel property.

For complete information on Production Levels, see the Administration and Security Guide. For more information on circumstancing, see the Application Developer Help.

Complete the following steps to create a model rule for the environment properties:

  1. Click the Rules by Type tab. Locate the Technical node and click the + sign to expand it.
  2. Click Model. A list of instances appears.
  3. Click the New icon. The New Rule Instance form appears.
  4. Fill out the form. In the Applies To field, enter the name of the class that you created in step 2.
  5. Click Create. The Model form appears.
  6. Fill out the form, entering the names of the properties that you created in step 3 in the Properties fields, and the values you want to set the properties to in the Value fields. The following image shows these fields filled in for a SOAP service endpoint URL:zzz
  7. Process Commander provides a number of utility functions that retrieve values for the various environment properties and encode passwords. For more information about these functions, including how to use them to retrieve values for your environment properties and encode passwords, see Utility functions for the Global Resource Settings feature.
  8. Save your changes.

back to top

5: Create a Declarative Page

A declarative page is created and updated by a Declare Pages rule (Rule-Declare-Pages rule type). Declarative pages allow you to create clipboard pages that are available to any user on one server node. Populate the clipboard page for first use (and refresh the clipboard pages as needed) by calling activities.

To implement the Global Resource Settings feature, create a Declarative page that calls the LoadResourceSettings activity. This activity populates the clipboard page with the values from a model rule that you specify.

Complete the following steps to create a Declarative page:

  1. From the Rules by Type explorer, select Technical > Declare Pages. A list of Declarative Pages rules appears.
  2. Click the New icon. The New Rule Instance form appears.
  3. Fill out the form and click Create. The Declare Pages form appears.
  4. Enter the name of the class that you created in step 2 in the Page Class field.
  5. Select LoadResourceSettings from the Load Activity field, and fill out the other fields as appropriate for your system.
  6. Save your changes.

back to top

Task Two: Use the Global Resource Settings syntax for references to external systems

After you have set up the values for your Global Resource Settings, use the Global Resource Settings syntax to refer to these values. The syntax consists of two parts:

=PageName.PropertyName

where PageName is the name of the declarative page that you created in step 5, and PropertyName is one of the properties that you created in step 3. For example, if you want to use the Global Resource Settings syntax to refer to a SOAP Service Endpoint URL, and your Declarative page is named MyDeclarativePage, the reference would be:

=MyDeclarativePage.pySOAPURL

At runtime, the reference resolves to the value of the pySOAPURL property that is located on the specified declarative page.

See Fields that Support the Global Resource Settings Syntax for a list of fields that support the Global Resource Settings feature.

back to top

Supporting Information

The following section lists the classes, environment properties, utility functions, and fields that support the Global Resource Settings feature.

Embed-Env Classes and Default Environment Properties

The following table lists the Embed-Env classes included in V5.3, and the default environment properties that each class contains (Figure 1).

Class

Property

Embed-Env-Connect-MQ

pyServerName

pyRequestQueueManager

pyRequestQueue

pyResponseQueueManager

pyResponseQueue

Embed-Env-Connect-HTTP

pyEndpointURL

Embed-Env-Connect-SOAP

pyEndpointURL

Embed-Env-Connect-JMS

pyJNDIServerName

pyonnectionFactory

pyRequestDestination

pyResponseDestination

Embed-Env-Connect-EJB

pyJNDIServerName

Embed-Env-Listener-Email

pyResponseServerName

pyReplyAs

Embed-Env-Listener-File

pySourceLocation

Embed-Env-Listener-MQ

pyRequestQueueManager

pyRequestQueue

pyResponseQueueManager

pyResponseQueue

pyBackoutRequeue

Embed-Env-Server-Email

pyHostName

pyPortNumber

pyReplyAs

pyUserID

pyPassword

Embed-Env-Server-JNDI

pyProviderURL

pySecurityPrincipal

pySecurityCredentials

Embed-Env-Server-MQ

pyChannelName

pyHostName

pyPassword

pyPortNumber

pyUserID

. Embed-Env Classes and Standard Property Names

back to top

Utility Functions for the Global Resource Settings Feature

Standard utility functions gather environment property values and encode passwords. Call these functions in your model rules.

To use these functions to retrieve environment property values or encode passwords, enter a call to the appropriate function in the model rule's Value field. The syntax of the call is as follows:

Lib(LibraryName).FunctionName()

where LibraryName is the name of the function library, and FunctionName is the name of the function you are calling.

The following table lists Utility functions for use with the Global Resource Settings feature (Figure 2):

Pega-RULES.Utilities Library

Name

Description

Parameters

getDataSystemSetting

Reads the specified Data-Admin-System-Setting from the database and returns it as a string.

owningRuleSet (Required)- The RuleSet that the system setting is associated with.

setting (Required) - The setting to retrieve from the database.

getRuleSystemSetting

Reads the specified Rule-Admin-System-Setting from the database and returns it as a string.

owningRuleSet (Required)- The RuleSet that the system setting is associated with.

setting (Required) - The setting to retrieve from the database.

getJavaSystemProperty

Returns the specified Java system property as a String.

key (Required) - The system property to retrieve.

getJavaPropertyFromFile

Loads the specified Java properties file and returns the value of the property specified in the function's Key parameter as a String. If the property cannot be found, the function returns an empty string.

fileName (Required) - The name of file containing the Java property.

key (Required) - The property to retrieve.

getJNDIEntry

Does a lookup for the specified JNDI entry and returns it as a string. If the lookup cannot be performed, the function returns an empty string and writes an error to the log.

name (Required) - The name of the JNDI entry.

Pega-RULES.Default Library

Name

Description

Parameters

Encode

Implements a simple encoding and decoding algorithm that incorporates base64 encoding.

Use this function to encode password values for use with the Global Resource Settings feature.

inputStr (Required) - The string to encode.

Figure 2.Utility Functions

back to top

 

Fields that Support the Global Resource Settings Syntax

The following table lists the fields in the Process Commander user interface that support the Global Resource Settings syntax (Figure 3). You can also find this information in the online help topic for each Process Commander form that supports the Global Resource Settings syntax.

Connector Rules

Rule Type

Field Name

Rule-Connect-SOAP

Service Endpoint URL

Rule-Connect-JMS

JNDI Server

Connection Factory

Destination Name (Request section)

Destination Name (Response section)

Rule-Connect-MQ

MQ Server Name

Request Queue Manager

Request Queue Name

Response Queue/Model Name

Response Queue Manager

Rule-Connect-EJB

Server Name

Rule-Connect-EJB

Endpoint URL

Rule-Connect-dotNet

Service Endpoint URL

Data Classes

Type

Field Name

Data-Admin-Connect-EmailListener

Node Name

Send Email As

Data-Admin-Connect-Email Server

Host Name

Port Number

User ID

Password

Send Email As

Data-Admin-Connect-FileListener

Source Location

Data-Admin-Connect-JMSListener

JNDI Server

Connection Factory JNDI Name

Topic or Queue JNDI Name (Request section)

Topic or Queue JNDI Name (Response section)

Data-Admin-Connect-JMSMDBListener

JNDI Server

Topic or Queue JNDI Name (MDB Descriptor Properties section)

Connection Factory JNDI Name

Topic or Queue JNDI Name ("REPLYTO" Connection section)

Factory Username

Factory Password

Data-Admin-Connect-JNDIServer

Provider URL

Security Principal

Security Credentials

Data-Admin-Connect-MQListener

Backout Queue

Queue Name (Request section)

Queue Manager ( Request section)

Queue Name (Reply To section)

Queue Manager (Reply To section)

Data-Admin-Connect-MQServer

Host Name

Port Number

Channel

User ID

Password

Figure 3. Fields that Support the Global Resource Settings Syntax

back to top

Suggest Edit

90% found this useful

Have a question? Get answers now.

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