Hi,

Pegasystems provides two command-line utilities to perform remote operations, prpcUtils and prpcServiceUtils. The functionalities are similar and overlapped, but there are some differences in the provided functionalities, command arguments, and parameters. In this post, I will share the differences, when to use one over the other, and some tips. I've created a detailed step-by-step guide. Please see attached.

1. prpcUtils vs prpcServiceUtils

I've summarized the differences in the table below. The functions colored in pink are covered in the attached guide. The architectural difference is that prpcUtils is a JDBC-based synchronous utility while prpcServiceUtils is a REST-based asynchronous utility. prpcUtils works directly on the target database thru JDBC, hence database has to be up to function (Pega Platform doesn't have to be up). On the other hand, prpcServiceUtils uses REST Service, hence Pega Platform has to be up to function. prpcUtils is synchronous and your command returns when the operation is completed (usually about a minute). prpcServiceUtils is asynchronous, and your command returns in a few seconds after queuing a job. You'll have to retrieve asynchronous job status by another getStatus command to verify the operation is successfully completed. Both utilities are included in the distribution media under ./scripts/utils directory, and prpcServiceUtils is also downloadable from Pega Community site. The advantage of prpcServiceUtils is that it can integrate with third-party CI/CD tool such as Jenkins. The advantage of prpcUtils is, in my opinion, the simplicity.

2. When to use one over the other

There are some differences in the functionalities that prpcUtils and prpcServiceUtils provide, so check which functionality you want to run remotely and decide which utility to use. If you need to integrate with third-party CI/CD tool such as Jenkins, consider prpcServiceUtils. If you want to use the only functionalities common in both utilities, then it is up to you to decide which one to use. If it is difficult to directly connect to the database (ex. DB is in outsourced data center and you don't know the credentials, or JDBC port is closed, etc), then prpcServiceUtils would be the only option. If customer is on-premise and there is no hurdle in direct connection to the database, then prpcUtils is also an option (personally I prefer prpcUtils as I feel it's more straightforward).

3. Something you may want to know

Here are a few tips and known limitations you may want to know so you don't have to spend your time in unnecessary troubleshooting.

3-1. Hotfix installation

Be noted, if you use prpcUtils or prpcServiceUtils to install Hotfix, the installation state won't be reflected on UI in Dev Studio (unless you do scan or commit operation manually from Dev Studio). This is a known limitation of Hotfix Manager. I've created an FDBK item to synchronize the state on UI regardless of where you install Hotfix from.

• If you install Hotfix from Dev Studio, it shows up in Hotfix Manager

• If you install Hotfix from prpcUtils or prpcServiceUtils, it is not reflected in Hotfix Manager by itself

3-2. Export R-A-P archive

In prpcUtils, you only need to specify the full path / file name of the R-A-P archive file and pzInsKey of the R-A-P rule instance. [email protected] works for running user. It's a synchronous operation and the file is downloaded to the path you specified in a single export command.

In prpcServiceUtils, you need to run two commands - export and getStatus. prpcServiceUtils is an asynchronous operation and export command only queues a job. Be noted, unless you retrieve an asynchronous job status, the file is not downloaded. The file is created in the "GETSTATUS" directory (not "EXPORT" directory). Also, pzInsKey property is removed in prpcServiceUtils and you have three properties to fill in - Product, Application, and Branch. If only one of them is fulfilled, the fulfilled one takes effect. If all of them are fulfilled, Product takes precedence. Lastly in prpcServiceUtils, you need to specify application-specific user for "pega.rest.usrname" or it throws an error. [email protected] won't work.

3-3. Expose operation

Some people are confused but expose operation does not mean physical addition of columns to the database table. ALTER TABLE ADD COLUMNS DDL statement has to be run separately either by DBMS or PRPC in advance. This expose operation only handles column population part (i.e. copy information from Blob to the exposed columns). The next confusion is, in prpcUtils, you should be able to find exposed columns populated right after you run expose command. However, in prpcServiceUtils you may find the columns remain null. This issue happens when you add columns from DBMS directly. In that case, the engine can't recognize there was a change in the table structure, and prpcServiceUtils doesn't trigger column population job. Then why prpcUtils always works? It is because prpcUtils starts a new JVM and columns addition is recognized at its start-up. So, if you add columns from DBMS directly and you are going to use prpcServiceUtils, you need to restart Tomcat (or resave Data-Admin-DB-Table instance from Dev Studio) to let the engine know. Be noted, if you let PRPC run the DDL during the R-A-P import process, the engine knows it and there is no need to restart system. Lastly, when you are populating exposed columns for Single Value properties, [email protected] user works for both prpcUtils and prpcServiceUtils. However, if you are populating Declare Index tables for Page List properties, you need to use application-specific user / access group. In prpcUtils, there is a property called "expose.declareIndex.accessgroup". Enter something like "MyApp:Authors" here. On the other hand, in prpcServiceUtils, this property doesn't exist - you need to specify application-specific user for "pega.rest.username" in common settings instead. Without these settings, Declare Index tables won't get refreshed.

* Most of commands in prpcUtils and prpcServiceUtils work with [email protected] but some commands don't. It may be easier to use application-specific user (SysAdm4) for all commands.

Hope this helps.

Thanks,