Populating properties by using a direct connection to the database

You can use the prpcServiceUtils tool to extract a property value from the Storage Stream or pzPvStream (BLOB) column into a newly added table column, by using a web service to connect to an active instance of Pega Platform. As a best practice, use the Database Column Populator when Pega Platform is not running.

You can run the Database Column Populator utility when Pega Platform is in use. However, the utility does not acquire a database lock on the rows it modifies. If a requestor updates an object at the same time that the Database Column Populator updates the corresponding database row, one of the updates might be overwritten and lost.

To populate newly exposed properties by connecting directly to the database, complete the following steps.

  1. Configure the common properties of the prpcUtils.properties file.
    Property name Value
    pega.jdbc.driver.jar Path to the database driver .jar file.
    pega.jdbc.driver.class The database driver class.
    pega.database.type Database vendor type.
    pega.jdbc.url URL of your database.
    pega.jdbc.username Database user name.
    pega.jdbc.password Database password.
    rules.schema.name If you use a split schema, the value for the rules schema name. If you do not use a split schema, the value for the schema name.
    data.schema.name If you use a split schema, the value for the data schema name.
  2. Configure the classes.

    To specify the data for populating the new column, use the include and exclude classes properties. For example, if you include Rule- with descendants and exclude Rule-File- with descendants, Pega Platform processes all descendant classes of Rule-, except rules in Rule-File-. Classes to include (required)

    Property name Value
    expose.classes.included List one or more concrete classes to be processed, separated by commas.
    expose.included.descendent Optional: True (default) or False . If true and a listed class has concrete subclasses (based on pattern inheritance), the subclasses are automatically added to the list of classes to be processed.

    Classes to exclude

    Property name Value
    expose.classes.excluded Optional: If you entered one or more classes in the expose.classes.included property, you can exclude specific subclasses by listing them here. Only instances of the exact class listed are excluded. For example, if you included Rule- classes with descendants you can use this property to filter specific classes.
    expose.excluded.descendent Optional: True (default) or False. If true and a class listed to be excluded has concrete subclasses (based on pattern inheritance), the subclasses are automatically added to the list of classes to be excluded.
  3. Configure the access group, or the Pega user name and password.
    Property name Value
    expose.declareIndex.accessgroup Specifies the access group in which the Rule-Declare-Index of the class being exposed exists. It is used when pega.user.username or pega.user.password is not provided.
    pega.user.username Specifies the Pega user name used to derive the access group in which the Rule-Declare-Index of the class being exposed exists. It is used with pega.user.password when both properties are provided.
    pega.user.password Specifies the Pega password used to derive the access group in which the Rule-Declare-Index of the class being exposed exists. It is used with pega.user.username when both properties are provided.
  4. Configure the keys or date ranges to expose.
    Property name Value
    expose.startKey Optional: You can restrict which instances are processed by using the handle or an initial portion of a handle. Enter the lowest pzInsKey value to be processed, enclosed within quotation marks.

    If you provide a pzInsKey range, specify only a single class in the Include classes field, and leave the other include and exclude class fields blank.

    The pzInsKey range values limit the number of rows returned when using a character sort, not a numeric sort. To process a set of work objects that have similar pzInsKey numeric values, you use date ranges for limiting the range of rows to return.

    expose.endKey Optional: You can restrict which instances are processed using the handle or an initial portion of a handle. Enter the highest pzInsKey value to be processed, enclosed within quotation marks.

    If you provide a pzInsKey range, specify only a single class in the Include classes field, and leave the other include/exclude class fields blank.

    expose.startDate Optional: You can restrict which instances are processed based on creation date. Enter a start date value in YYYYMMDD format.

    Leave blank if the expose.startKey or expose.endKey field is not blank.

    The pzInsKey range values limit the number of rows returned when using a character sort, not a numeric sort. To process a set of work objects that have similar pzInsKey numeric values, you use date ranges for limiting the range of rows to return.

    expose.endDate Optional: You can restrict which instances are processed based on creation date. Enter an end date value in YYYYMMDD format. The end date cannot be the same as the start date. Leave at least one day between the dates, for example,

    expose.startDate=20171014

    expose.endDate=20171016

    Leave blank if the expose.startKey or expose.endKey field is not blank.

  5. Configure the reindexing behavior.
    Property name Value
    expose.reindex True (default) or False. Set to true to regenerate Index- instances derived from the instances specified, based on Declare Index rules.

    To expose property references, set expose.reindex=true .

    expose.reindexType Specify the rulesets to process:
    • nonpega : (Default) Process only non-Pega rulesets
    • full : Process Pega and non-Pega rulesets
    • pega : Process only Pega rulesets

    In most cases, enter nonpega . You do not need to process Pega rulesets unless you are instructed to process them by Global Customer Support.

    expose.commitRate Specifies the number of data instances to process with each database commit. The default is 100.
    expose.numOfThreads Specifies the number of threads to use. If no value is specified, the default is the number of classes being updated. When updating large sets of data, set the number of threads to a higher value.
    expose.update.rule.summary True (default) or False, specifying whether to update Data-Rule-Summary on the database. The default is false.
  6. Save and close the prpcUtils.properties file.
  7. To populate the columns, run the prpcUtils.bat or prpcUtils.sh script with the expose option, for example:
    prpcUtils.bat expose
    1. Optional: Pass one or more arguments.
      prpcUtils script argument Value
      connPropFile The full path to the connection.properties file that includes information for multiple targets.
      driverClass Your JDBC driver class. For example, oracle.jdbc.OracleDriver.
      driverJAR Location of your JDBC .jar file.
      dbType Database vendor type, such as mssql, udb, oracledate, postgres, and db2zos.
      dbURL JDBC URL to the database.
      dbUser Database user name.
      dbPassword Database password.
      archivePath Full path to the archive to be imported or exported.
      propFile The full path to the properties file, to override the default prpcUtils.properties.
      hfixAction If manageHotfixes is selected, sets the hotfix operation. Valid values are commit, rollback, generateDDL, install, and scan.
      rulesSchema The rules schema.
      dataSchema The data schema.
      noFailOnError Set to true or false. When enabled, instances that fail to import are skipped and import continues instead of failing.
      U Pega user name.
      P Pega password.
      accessGroup AccessGroup in which the Rule-Declare-Index of the classes being exposed exists. Applicable for the expose utility if --U or --P are not provided.