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

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, enter the System Name property:
   SystemName=$BUILD_TAG
7. 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.

8. 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. Click Build.