Table of Contents

Remotely starting automation server jobs to perform branch operations and run PegaUnit tests

You can start a job remotely from an automation server, such as Jenkins, and configure a continuous integration and development pipeline with the branches REST and merges REST services to merge branches when you push them from your development system to a Pega repository on a remote system of record (SOR). In a continuous integration and delivery pipeline, repositories provide centralized storage for software that is to be tested, released, or deployed.

Pega® Platform can communicate with common repository technologies and also can act as a binary repository. Pega Platform can browse, publish, or fetch artifacts that are created whenever an action creates a RAP file: for example, exporting an application, product, branch, or component into a remote system of record. By starting jobs remotely and using the automation server to detect conflicts and merge branches, your organization can deliver higher-quality software more quickly.

For more information about using branches with repositories, see Using branches with Pega repositories in a continuous integration and delivery pipeline.

After you push a branch to a system of record, your automation server tool runs a job. Your pipeline can detect conflicts before a merge. If there are conflicts, the merge does not proceed. If there are no conflicts, the merge proceeds on the system of record. Your pipeline can run all PegaUnit test cases or a test suite to validate the quality of your build. After a merge is completed, you can rebase the rules on your development system to import the most recently committed rules from your system of record. For more information, see Rebasing rules to obtain latest versions. In addition, you can configure your pipeline to send emails to users, such as when a job starts or when a conflict is detected.

The following figure displays an example workflow of the pipeline:Workflow of a continuous integration pipeline on an SORWorkflow of a continuous integration pipeline on a system of record

To start jobs remotely and configure a pipeline, do the following tasks:

  1. Configure your automation server
  2. Defining the automation server URL
  3. Configure the pyPostPutArtifactSuccess activity
  4. Configure a continuous delivery pipeline

The following tasks describe how to configure a pipeline and system of record by using Jenkins as the example automation server.

Configuring your automation server

Configure your automation server so that you can remotely start jobs on it. Your configuration depends on the automation server that you use. For example, the following procedure describes how to configure Jenkins.

  1. Open a web browser and navigate to the location of the Jenkins server.
  2. Install the Build Authorization Token Root Plugin.
    1. Click Manage Jenkins.
    2. Click Manage Plugins.
    3. On the Available tab, click the Build Authorization Token Root Plugin check box.
    4. Specify whether to install the plug-in without restarting Jenkins or download the plug-in and install it after restarting Jenkins.
  3. Configure your Jenkins job to use parameters.
    1. Open the job and click Configure.
    2. On the General tab, click the This project is parameterized check box.
    3. Click the Add Parameter drop-down list and click String Parameter.
    4. In the Name field, enter notificationSendToID, which is the operator ID of the user who started the Jenkins job. Email notifications about the job are sent to the email address that is associated with the user ID.
    5. Click the Add Parameter list, and click String Parameter.
    6. In the Name field, enter branchName.
    7. Click Save.
  4. ​Configure the build trigger for your job.
    1. Click Configure. On the General tab, in the Build Triggers section, click the Trigger builds remotely (e.g., from scripts) check box.
    2. In the Authentication Token field, enter an authentication token, which can be any string.
    3. Click Save.

Defining the automation server URL

Configure a Dynamic System Setting on the system of record to define your automation server URL. Your configuration depends on the automation server that you use. For example, the following procedure describes how to configure settings if you are using Jenkins.

  1. Click Create+ > Sysadmin > Dynamic System Settings.
  2. Enter a description in the Short description field.
  3. In the Owning Ruleset field, enter Pega-API.
  4. In the Setting Purpose field, enter JenkinsURL.
  5. Click Create and open.
  6. On the Settings tab, in the Value field, enter http://myJenkinsServerURL/buildByToken/buildWithParameters.
  7. Click Save.

Configuring the pyPostPutArtifactSuccess activity

If you are using Jenkins, configure the pyPostPutArtifactSuccess activity on your system of record to create a job after a branch is published on the system of record. If you are using other automation servers, create and call a Connector that is supported by your continuous integration tool.

  1. Click App > Settings.
  2. In the search field, enter Pega-RepositoryManagement.
  3. Expand Technical > Activity.
  4. Click pyPostPutArtifactSuccess.
  5. Save the activity to your application ruleset.
  6. On the Steps tab, in the Method field, enter Call pxImportArchive.
  7. Expand the arrow to the left of the Method field.
  8. Click the Pass current parameter page check box to import the archive that was published to the system of record. If there are errors during import, you can exit the activity.
  9. ​Ensure that the session authenticated by the Pega Repository Service Package has access to the ruleset that contains the pyPostPutArtifactSuccess activity. For more information about configuring authentication on service packages, see Service Package form - Completing the Context tab.
  10. Define the page and its class.
    1. Click the Pages & Classes tab.
    2. In the Page name field, enter a name for the page.
    3. In the Class field, enter Pega-API-CI-AutomationServer.
  11. Click the Steps tab.
  12. Add a step to create the new page on the clipboard.
    1. In the Method field, press the Down Arrow key and click Property-Set.
    2. In the Step page field, enter the name of the page that you entered on the Pages & Classes tab.
  13. Configure the parameters to pass to the pzTriggerJenkins activity.
    1. Click Add a step.
    2. In the Method field, press the Down Arrow key and click Property-Set.
    3. Click the arrow to the left of the Method field to open the Method Parameters section.
    4. In the PropertiesName field, enter Param.Job.
    5. In the PropertiesValue field, enter the name of your project.
    6. Click the plus sign.
    7. In the PropertiesName field, enter Param.Token.
    8. In the PropertiesValue field, enter the authentication token that you provided for your project.
    9. Click the plus sign.
    10. In the PropertiesName field, enter Param.BranchName.
    11. In the PropertiesValue field, enter @whatComesBeforeFirst(Param.ArtifactName,'_').
    12. Optional: To specify a different URL from the JenkinsURL Dynamic System Setting that you created in the first step of the Configuring Dynamic System Settings, click the Plus sign icon.
    13. In the PropertiesName field, enter Param.OverrideEndPointURL.
    14. In the PropertiesValue field, enter the endpoint URL.
    15. Optional: To send notifications to users if you are calling the activity in a context where there is no operator ID page, click the Plus sign icon.
    16. In the PropertiesName field, enter Param.OverrideNotificationSendToID.
    17. In the PropertiesValue field, enter Param.PutArtifactOperatorID.
  14. ​Add a step to call the pzTriggerJenkinsJob activity.
    1. Click Add a step.
    2. In the Method field, enter Call pzTriggerJenkinsJob.
    3. In the Step page field, enter the name of the page.
    4. Click the arrow to the left of the Method field to expand it.
    5. Click the Pass current parameter page check box.
  15. Configure other activity settings, as appropriate. For more information, see Creating an activity.
  16. Save the rule form.

Example of configured activityExample of a configured activity

Configuring a continuous delivery pipeline

After you configure your automation server and your remote system of record, you can configure a pipeline on your job to automate the testing and merging of rules. You can do the following actions:

  • Send a notification with the job URL to the user who published the branch or started the job.
  • Call the branches REST service with GET /branches/{ID}/conflicts to obtain a list of conflicts. If there are no conflicts, you can continue the job; otherwise, you can end the job and send a notification to the user to indicate that the job failed.
  • Use the merges subresource for the branches REST service to merge branches.
  • Call the merges REST service with GET /branches/{ID}/merge to obtain the status of a merge.
  • Use the reviews subresource for the branches REST service to create a branch review.
  • Use the Execute Tests service to run PegaUnit test cases or test suites. For more information, see Running PegaUnit test cases and test suites with the Execute Tests service.
  • Set up Jenkins to poll the job, using the unique ID that the branches service returned when you merged the branch, until the status is no longer set to Processing. If the merge is successful, you can continue the job; otherwise, you can send a notification to the user to indicate that the job failed.
  • Publish the rulesets into which the branches were merged to a repository such as JFrog Artifactory.
  • Notify the user that the job is complete.

For more information about the branches REST and merges REST services, see Implementation of a continuous integration and delivery pipeline with the branches REST and merges REST services.

Suggest Edit

100% found this useful

Have a question? Get answers now.

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