Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Using a script to replace a secure communication certificate

Updated on October 13, 2021

Pega Robotic Automation uses certificates to ensure secure communication between Pega Robot Runtime and the Pega applications that you have automated. Pega updates the certificate periodically, and includes the latest certificate in each Robot Runtime build. When you install or update Robot Runtime to the latest version, you receive the most current certificate (localruntime.pega.com). For more information, see Certificate expiration dates.

Note: You can also use your own certificate instead of thelocalruntime.pega.com certificate and you can use this script to install your certificate. If you use a custom certificate, ensure that the domain that you use matches the domain specified within that certificate.

When you install Robot Studio or Robot Runtime using the Setup wizard or from the command line, a script runs to import the certificate and register the certificate on the port that you selected. When you use the Pega Synchronization Engine to update your environment, this script does not run. If you are using the Pega Synchronization Engine, you can follow these instructions to manually run the script, which will update the certificate and register the port.

Note: Alternatively, you can use Microsoft's Group Policy feature to make these updates. If you use Group Policy, make sure that you bind the certificate to the appropriate port, which you can do using the scripts below as an example.

To update the certificate without updating Robot Runtime, perform the following tasks in this order to replace the certificate:

  1. In a test environment, install the latest version of Robot Runtime.
  2. In a test environment, export the certificate.
  3. In a production environment, locate the port.
  4. In a production environment, run a batch or PowerShell script to install the certificate on your production computers.
Note: You can download and customize sample batch and PowerShell scripts from the link on this page. In some customer environments, the execution of batch or PowerShell scripts is disabled. You can update a certificate using either of the sample scripts, and you can choose the type of script that you prefer. The batch file executes on the command line using PowerShell.

Installing Robot Runtime to get the localruntime.pega.com certificate

  1. Download the latest version of Robot Runtime from Digital Delivery.
  2. In a test environment, follow the installation instructions to install Robot Runtime.
  3. In the Robotic Desktop Automation (RDA) Integration pane, select the Enable RDA Integration option. This option installs the certificate in the test environment.

Exporting the localruntime.pega.com certificate

During this task, you will need to note the following information, which you will use when you customize the script file:

  • The hash value of the Thumbprint property.
  • The password you choose to protect the Personal Information Exchange (PFX) file.
  • The path to the certificate.

Follow these steps to use the Microsoft Management Console (MMC) to export the localruntime.pega.com certificate from the test environment.

  1. Click the Search icon on the task bar and enter mmc.exe. Right-click on mmc.exe and select Run as Administrator.
  2. Click File > Add/Remove Snap-in.
  3. In the Add or Remove Snap-ins window, under Available snap-ins, selectCertificates and click Add.
  4. Select the Computeraccountoption and click Next.
  5. Choose Local computerandclick Finish.
  6. In the Add or Remove Snap-ins window, click OK.
  7. Expand the Certificates (Local Computer) > Personalfolders under the Console root, and then select the Certificatesfolder.
  8. Double-click the localruntime.pega.com certificate and then click the Details tab.
  9. Scroll down to the Thumbprint property and note the hash value stored there. You will enter it in the script. Then click Copy to File.
  10. On the Certificate Export Wizard, click Next.
  11. Select the Yes, export the private key option and click Next.
  12. Select the Personal Information Exchange -PKCS #12 (.PFX) option, select the check boxes for the following options, and then click Next:
  • Include all certificates in the certification path if possible
  • Export all extended properties
  • Enable certificate privacy
  1. Select the Password check box, then enter and confirm the password that you want to use to protect the PFX file. Note the password, and then click Next.
  2. Enter a file name and location to export the certificate, and then click Next.
  3. Verify the file name and path and ensure that the Export Keys and Include all certificates in the certification path options are set to Yes, and the File Format is Personal Information Exchange (*.pfx). Note the path and then click Finish.

Locating the port

In this task, you use a Robot Runtime computer in a production environment to locate and verify the port that Robot Runtime uses to communicate with the Pega application. Bind the localruntime.pega.com or your certificate's REST service to this port to ensure secure communications between Robot Runtime and the Pega application. The default port is 9443.

  1. In a text editor, open a RuntimeConfig.xml file used in a production environment. This file is located at %appdata%\pegasystem (for 19.1 and higher) or %appdata%\OpenSpan (for 8.0 SP1 and lower).
  2. In the Robotics > LocalApiService section, locate the port key. The value stored in this key is the port binding. Make a note of this value. The following is an example:

<LocalApiService enabled="true" SSL="true" port="9443" allowedOrigins="*pega.com" JWTSecurity="false" PegaServerURL="https://MyPegaServer.com/prweb"/>

Creating the script

You can create a batch or PowerShell script to make installing the certificate easier. Download and open the sample scripts from the following ZIP file:

Sample scripts for installing local Robot Runtime certificates

Customize these scripts to install the certificate. After you customize the script, run the saved script on each Robot Runtime computer that needs an updated certificate.

Customizing the batch file

  1. Open the sample batch file in a text editor.
  2. Replace Line 5 - ipport PortNumber with the port number that you verified in the previous task.
  3. Replace Line 8 - p value with the password you used when exporting the certificate.
  4. Replace Line 8 - importpfx value with the path to the certificate.
  5. Replace Line 11 - $certHash value with the certificate hash value.
  6. Replace Line 11 - $port value with the port binding number.
  7. Save the batch file.

The following is an excerpt from the script in the sample batch file:

Excerpt from sample batch file script for installing local Robot Runtime certificates
Excerpt from sample batch file script for installing local Robot Runtime certificates
Note: If you use a custom certificate, enter the domain for the custom certificate on line 2.

Customizing the PowerShell file

  1. Open the sample batch file in a text editor.
  2. Replace Line 5 - ipport PortNumber with the port number that you verified in the previous task.
  3. Replace Line 8 - p value with the password you used when exporting the certificate.
  4. Replace Line 8 - importpfx value with the path to the certificate.
  5. Replace Line 12 - $certHash value with the certificate hash value.
  6. Replace Line 14 - $port value with the port binding number.
  7. Save the PowerShell file.

The following is an excerpt from the script in the sample PowerShell file:

Excerpt from sample PowerShell script for installing local Robot Runtime certificates
Excerpt from sample PowerShell script for installing local Robot Runtime certificates

 

 

  • Previous topic Checking your certificate expiration date
  • Next topic Replacing the Pega RDA certificate with a self-provisioned certificate

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us