Setup System Name in Pega
In this article, we will understand about the System name configuration in Pega environments.
What is a system instance in Pega?
– System is a data instance that belongs to SysAdmin category.
– System name uniquely identifies each system and corresponds to Pega Platform system
For example In an Organization
– mkp_dev, mkp_st, mkp_uat, mkp_prod can uniquely identify the development, test, acceptance and production systems in mkp department
– whereas ctm_dev, ctm_st etc, can uniquely identify systems in ctm department.
Important note: Systems/ system names DO NOT map one on one with Pega applications. You can map the system to one clustered infra with a common database. So, one system can hold multiple applications.
You can specify more than one system instance but only one can be active at a time.
Let’s say an Organization decided to use Pega software to treat their customer.
On receiving the appropriate license for the Pega version and Framework (if applicable), Pegasystems will provide the right enterprise package for installation.
We know that the entire Pega code base stays in the database. Fresh Pega installation refers to installing the package into the database and setting up the Pega server(s).
Let’s see the default system names that come with the fresh installation.
Switch to Records -> SysAdmin -> System, to view the list of system names.
You see there are two system names – pega, prpc.
What is the current system name?
Navigate to Configure -> System -> Settings -> System name
As highlighted, you see the Pega as the current system name by default.
You will also see a list of requestor types for the available system names – prpc and pega.
Records -> SysAdmin -> Requestor types
Check the following post for more information on requestor types – https://myknowpega.com/2017/05/13/requestor-types/
Whenever you fresh install the Pega software, the first step you will be doing is creating a new system name and setting it to default.
Assume that we are going to treat the Pega personal edition as the development environment for myknowpega (mkp) system.
So you need to do two steps
- Create a new system name
- Set the new system name as default system name.
Create a new system name
1. You can always create a new system name manually
Records -> SysAdmin -> System -> Create new, to create a new system name.
2. System names can also get created automatically when you set the system name as default system name. We will see this first
Set the new system name as the default system name –
We will see all 4 different ways to set or modify the default system name.
1. Create and set the new system name from system landing page
Switch to Configure-> System -> Settings -> System name landing page.
You can see the description clearly. A new system name will be created automatically by cloning the current system name and all associated instances.
Just enter the new name and click submit.
Important note: You should always restart the server for the change to take effect.
2. Set the default system name using dynamic system settings.
DSS name – prconfig/identification/systemName/default
All you need to do is change the value in DSS to the new name and restart the server.
In the Unauthenticated ruleset post, I have already explained the steps in creating a new system name manually and set the new system name as default using DSS settings.
3. Update the system name environment settings in prconfig.xml file.
Environment name in the prconfig.xml will be Identification/SystemName.
Note that the DSS name is also something similar.
Pega recommends using the DSS settings to override most of the prconfig.xml file configurations. The main reason is DSS instances are stored in database and can share the settings across multiple servers that run on the same database. prconfig.xml settings are specific to each server. So node specific or server specific settings, place it in the prconfig.xml and for system wide settings, use DSS.
Note: There are many other DSS configurations that can override the prconfig.xml configuration. On the DSS name, just filter on prconfig name.
You will find the prconfig.xml file in the following location –
C:PRPCPersonalEditiontomcatwebappsprwebWEB-INFclasses
Let’s start with the tutorial
Create and set the new system name from the Landing Page.
Step 1: Switch to Configure-> System -> Settings -> System name landing page
Step 2: Specify the new system name and click the submit button.
Make a note of node ID (It starts with 5..)
As soon as you click on the submit button, you know what Pega does here.
It does two things
a) Automatically creates a new system name.
Pega clones the current system name – pega into a new system name – mkp_dev
Click and open the system name. You will see the settings cloned from the system name – pega
b) Automatically updates the system name DSS to the new name.
In the end, all it does is use the system wide DSS settings.
Step 3: Restart the server.
Now you see the DSS is set to the new system name. Just restart the server.
After restarting, let’s verify if the new system name is in effect.
Switch to Configure-> System -> Settings -> System name landing page
You see the current name as mkp_dev
You also see a new node ID created for the new system name (starts with 4..)
Important note: whenever you change the system name, a new node ID is created.
Also, verify the requestor types created for the system name – mkp_dev
Let’s say there is a new change that comes in, where you need to change the system name from mkp_dev to myknowpega_dev.
For tutorial purposes, we will try updating the prconfig.xml
Step 1: Delete the system-wide settings. DSS – identification/systemName
Because DSS always overrides the prconfig settings.
Step 2: Update the prconfig to add a new system name value.
Below is the syntax.
<env name=”Identification/SystemName” value=”myknowpega_dev”/>
Save the file.
Step 3: Restart the server.
Let’s verify the automatically created new system name. You see it is automatically created by system, by saving the prpc instance.
Important note: You can always create the system name manually.
Check the system name landing page.
You see the new system name as the current name also, new node ID is created with required action – Update prconfig.xml and restart. Because Pega knows that we are not using DSS rule and updated the prconfig.xml.
4. Update the system name using prpcutils script.
Prpcutils is a command line utility that can be executed from the backend. All you have to do is setup the right database properties and execute the bat file (Windows) or shell script (Linux) using changeSystemName option.
We are at the end of this article.
As a summary
– You can always create a system name data instance manually and set the system name as the default system name using either DSS settings or by updating the prconfig.xml
– System name instance can also be created automatically when you update the system name in the landing page as well as updating the prconfig.xml
– System name set in the DSS instance always overrides the system name value in the prconfig.xml file. For system wide settings, use DSS instance and for server specific settings, use prconfig file settings.
– System name changes can also be automated using prpcutils script.
