Using prpcServiceUtils and Jenkins for automated application deployment

You can use Jenkins to automate exporting and importing Pega 7 Platform applications. Download the prpcServiceUtils command-line tool and configure Jenkins to export or import archives. You can use a single Jenkins build job to both export and import an application archive, or you can create separate jobs for each task.

Audience

This article is written for users who need to configure a build environment and who have a working understanding of Ant and Jenkins.

Requirements

Ensure that your system includes the following items:

  • Jenkins 1.651.1 or later
  • Jenkins Plugins:
    • Ant Plugin
    • Environment Injector Plugin
    • Build with Parameters Plugin
  • Ant version 1.9 or later
  • JDK version 1.7 or later

Installing the prpcServiceUtils tool

Download and install the current version of the prpcServiceUtils tool:

  1. Download the prpcServiceUtils.zip file onto the Jenkins server. For more information, see Remote configuration command-line tool (prpcServiceUtils).
  2. Extract the files onto any location to which Jenkins has access.

Configuring your Jenkins system

Configure your build environment to call the prpcServiceUtils.bat or prpcServiceUtils.sh script and pass parameters to import or export the RAP:

  1. Verify that the following Jenkins plugins are installed:
    • Ant Plugin
    • Environment Injector Plugin
    • Build with Parameters Plugin
  2. Open a web browser and navigate to the Jenkins server.
  3. Click Manage Jenkins.
  4. Click Configure System.
  5. Configure the PEGA_HOME environment variable:
    1. In the Global properties section, select Environmental variables.
    2. In the name field, enter PEGA_HOME.
    3. In the value field, enter the location where you extracted the prpcServiceUtils.zip file.
    4. Click Add.
  6. ​Click Apply, and then click Save.

Configuring the Jenkins project

Configure the Jenkins project to pass data to the prpcServiceUtils tool:

  1. Complete one of the following actions:
    • Create a project if you have not already done so.
    • Open an existing project.
  2. Click Configure.
  3. Select This build is parameterized.
  4. Click Add Parameter and create the parameters that Jenkins passes to the prpcServiceUtils tool:
    • To import or export a RAP, create the following parameters:
      Parameter name Type Default value
      productName String The name of the RAP rule used to generate the archive
      productVersion String The version number of the RAP rule
    • To import or export an application, create the following parameters:
      Parameter name Type Default value
      applicationName String The name of the application
      applicationVersion String

      The version number of the application

  5. Select Prepare an environment for the run.
  6. In the Properties Content section, set the following properties:

    SystemName=$BUILD_TAG

    Source Code Management=None

    Inject environment variables to the build process=Properties Content

  7. Optional. In the Properties Content section, set the ImportExistingInstances property to one of the following values. The default is unset:

    • override:

      • For rules - If a rule with the same key exists in the system but the rule resolution properties differ (e.g. RuleSet, Version, etc), then replace the existing rule with the imported rule.

      • For work - If a work object with the same key exists but it belongs to a different application (e.g. different class hierarchy but same classgroup name and same ID prefix), replace the existing work object with the imported work object.

    • skip:

      • For rules - If a rule with the same key exists in the system and the rule resolution properties differ, do not replace the existing rule.

      • For work - If a work object with the same key exists but it belongs to a different application, do not replace the existing work object.

    • unset: The import will fail if keys already exist either for rule instances that have different rule resolution properties, or for work objects that belong to a different applications that use the same classgroup name.

  8. Optional. Set the artifact directory where exported logs and files are downloaded. The default is the logs directory.

    ARTIFACTS_DIR=<var>path to artifact directory</var>

    You can also set this later by specifying -artifactsDirwhen you run the batch file.
  9. In the ​Properties Content section, enter the static properties in the following format
    ParameterName=Value
    • Source properties for export:

      Parameter name Default value
      SourceHost The host name and port number of the Pega 7 Platform server from which to export the archive file.
      SourceUser The operator name. This operator must have export privileges.
      SourcePassword The operator password.
    • Target properties for import:

      Parameter Name Default Value
      TargetHost The host name and port number of the Pega 7 Platform server that contains the archive file to import.
      TargetUser The operator name. This operator must have import privileges.
      TargetPassword The operator password.
  10. Click Save.

Adding build steps to import or export the archive

You can enter build steps to import an archive or export an archive, or you can do both in one job.

Adding export build steps

To add export steps to your build job, follow this process:

  1. Add an Invoke Ant build step:
    1. In the Build section, click Add build step and select Invoke Ant.
    2. In the Targets field, enter exportprops.
    3. In the Build File field, enter the path to the build file:
      • Windows: $PEGA_HOME\samples\Jenkins-build.xml
      • UNIX: $PEGA_HOME/scripts/samples/jenkins/Jenkins-build.xml
  2. Add a build step to run either prpcServiceUtils.bat or prpcServiceUtils.sh:
    • On Windows, create an Execute Windows batch command build step:
      1. In the Build section, click Add build step and select Execute Windows batch command.
      2. In the Command field, enter the following command:

        %PEGA_HOME%\scripts\utils\prpcServiceUtils.bat export --connPropFile %WORKSPACE%\%SystemName%_export.properties --artifactsDir %WORKSPACE%

    • On UNIX, create an Execute Shell batch command build step:
      1. In the Build section, click Add build step and select Execute Shell batch command​.
      2. In the Command field, enter the following command:

        $PEGA_HOME/scripts/utils/prpcServiceUtils.sh export --connPropFile $WORKSPACE/${SystemName}_export.properties --artifactsDir $WORKSPACE

  3. Click Save.

Adding import build steps

To add import steps to your build job, follow this process:

    1. Add an Invoke Ant build step:
      1. In the Build section, click Add build step and select Invoke Ant.
      2. In the Targets field, enter importprops.
      3. In the Build File field, enter the path to the build file:
        • Windows: $PEGA_HOME\samples\Jenkins-build.xml
        • UNIX: $PEGA_HOME/scripts/samples/jenkins/Jenkins-build.xml
    2. Add a build step to run either prpcServiceUtils.bat or prpcServiceUtils.sh:
      • On Windows, create an Execute Windows batch command build step:
        1. In the Build section, click Add build step and select Execute Windows batch command.
        2. In the Command field, enter the following command:

          %PEGA_HOME%\scripts\utils\prpcServiceUtils.bat import --connPropFile %WORKSPACE%\%SystemName%_import.properties --artifactsDir %WORKSPACE%

      • On UNIX, create an Execute Shell batch command build step:
        1. In the Build section, click Add build step and select Execute Shell batch command​.
        2. In the Command field, enter the following command:

          $PEGA_HOME/scripts/utils/prpcServiceUtils.sh import --connPropFile $WORKSPACE/${SystemName}_import.properties --artifactsDir $WORKSPACE

    3. Click Save.

    Running the job

    Follow these steps to import or export the archive:

    1. In Jenkins, click Build with Parameters.
    2. When the parameter values are displayed, verify the default settings and edit any values.
    3. Optional. Set the artifact directory where exported logs and files are downloaded. The default is the logs directory.

      -artifactsDir=<var>path to artifact directory</var>

    4. Click Build.
    Suggest Edit

    97% found this useful

    Have a question? Get answers now.

    Visit the Pega Support Community to ask questions, engage in discussions, and help others.