Devops 84
Devops 84
Devops 84
DevOps is a set of practices that bridge application development and operational behavior to reduce time to
market without compromising on quality and operational effectiveness. It allows application developers and
business owners to quickly respond to customer needs, develop a quicker feedback cycle, and ultimately achieve
business value faster.
DevOps encourages a culture of collaboration between development, quality, and operations teams to reduce or
eliminate barriers through fundamental practices such as continuous integration, continuous delivery, and
continuous deployment. Adopting these practices and the tools to support them creates a standardized
deployment process so that you can deploy predictable, high-quality releases.
Pega Platform provides the tools necessary to support continuous integration, delivery, and deployment through
Deployment Manager, which provides a low-code, model-driven experience to configure and run continuous
integration and delivery (CI/CD) workflows or deployment pipelines for your application. Deployment Manager
provides out-of-the-box tools to enforce best CI/CD practices for your application. You can fully automate
deployment pipelines, starting with automated integration of developer changes through branch merging and
validation, application packaging, artifact repository management, deployments, test execution, guardrail
compliance, and test coverage enforcement.
Pega Platform also includes support for open DevOps integration using popular third party tools such as Jenkins
and Microsoft Azure DevOps by providing an open platform, with all the necessary hooks and services. With open
DevOps integration, you can build a deployment pipeline using third-party tools to automate branch merging,
application packaging and deployment, test execution, and quality metric enforcement.
For more information about configuring DevOps workflows, see the following topics:
In a DevOps workflow, the most important best practice for application developers to adopt is continuous
integration. Continuous integration is the process by which development changes to an application are
integrated as frequently as possible, at least once a day and preferably multiple times a day, every time
developers complete a meaningful unit of work.
Use DevOps practices such as continuous integration and continuous delivery to quickly move application
changes from development through testing to deployment on your production system. Use Pega Platform
tools and common third-party tools to implement DevOps.
Change the application version number each time you deploy changes to a production system. As a best
practice, use semantic versioning, because it offers a logical set of rules about when to increase each
version number.
DevOps is a culture of collaboration by development, quality, and operations teams to address issues in their
respective areas. To sustain progress and bring continued improvement, tools and processes are put in
place. Use DevOps practices such as continuous integration and delivery (CI/CD) pipelines to break down
code into pieces and automate testing tasks, so that multiple teams can work on the same features and
achieve faster deployment to production.
Installing and enabling for Sonatype Nexus Repository component for Sonatype Nexus Repository Manager 3
To create a connection between Pega Platform or Deployment Manager and Nexus Repository Manager 3,
use the Sonatype Nexus Repository component. Use this repository for centralized storage, versioning, and
metadata support for your application artifacts.
Installing and enabling Sonatype Nexus Repository component for Sonatype Nexus Repository Manager 2
Create a connection between Pega Platform or Deployment Manager and Sonatype Nexus Repository
Manager 2 with the Sonatype Nexus Repository component. Use this repository for centralized storage,
versioning, and metadata support for your application artifacts.
With minimal disruption, you can safely migrate your application changes throughout the application
development life cycle, from development to deployment on your staging and production environments. In
the event of any issues, you can roll back the deployment and restore your system to a state that was
previously known to be working.
As part of the Standard Release process, after you set up and package a release on your shared
development environment, you can deploy your application changes to your staging or production
environment.
As part of the Standard Release process for migrating your application changes from development to
production, you set up and package the release on your shared development environment.
The following tables provide information about the types of changes that you can make within a release, the
release types, and the release management process to follow based on the types of changes that you want
to deploy.
Having an effective automation test suite for your application in your continuous delivery DevOps pipeline
ensures that the features and changes that you deliver to your customers are of high-quality and do not
introduce regressions.
Use Deployment Manager to configure and run continuous integration and delivery (CI/CD) workflows for
your Pega applications from within Pega Platform. You can create a standardized deployment process so
that you can deploy predictable, high-quality releases without using third-party tools.
When you use continuous integration and delivery (CI/CD) workflows, you set up the systems in your
environment based on your workflow requirements. For example, if only one team is developing an
application, you can use a single system for application development and branch merging.
Understanding continuous integration and delivery pipelines with third party automation servers
Use DevOps practices such as continuous integration and continuous delivery to quickly move application
changes from development, through testing, and to deployment. Use Pega Platform tools and common third-
party tools to implement DevOps.
To enforce best practices when developing an application and to ensure that application changes are of high
quality, developers should use Pega Platform features such as branches. Before merging branches and
integrating changes, developers should also verify that the application meets guardrail compliance and that unit
tests pass. If the validation of development changes passes, the branch is merged into the application ruleset.
However, if validation fails, then the merge is rejected, and developers should be notified so that they can
address the failure and resubmit their changes. The feedback cycle of validating and integrating development
changes should be as fast as possible, preferably 15 minutes or less, because it increases productivity in the
following ways:
Developers do not spend unnecessary time to see that their changes are valid, which enables them to make
incremental changes.
Incremental changes tend to be easier to validate, debug, and integrate.
Other developers spend reduced time coordinating making changes and can be confident that they are
building on validated functionality.
How you implement best practices for continuous integration depends on whether you have a smaller scale
development with one or two scrum teams using a shared development environment or multiple distributed
development teams. See the following topics for more information:
Development environments can be shared by one or more teams collaborating on the production
application. To practice continuous integration, use a team application layer, branches, and release toggles.
Understanding development best practices in a distributed development environment with multiple teams
If you have multiple teams working on the same application, each team should have a separate, remote
development server on which developers work. A central Pega Platform server acts as a source development
system, which allows teams to integrate features into the application in a controlled manner and avoid
unexpected conflicts between teams working in the same rulesets.
Build a team application layer that is built on top of the main production application. The team application
layer contains branches, tests, and other development rulesets that are not intended to go into production.
For more information, see the Pega Community Using multiple built-on applications.
Create a branch of your production ruleset in the team application. For more information, see Adding
branches to your application.
Perform all development work in the branch.
Optional: Use release toggles to disable features that are not ready for general use. Using toggles allows you
to merge branch content frequently even if some content is not final. For more information, see Toggling
features on and off.
Optional: Create formal review tasks for other members of the development team to review your content.
For more information, see Creating a branch review.
Optional: Use the branch developer tools to review the content and quality of your branch. For more
information, see Reviewing branches.
Optional: Lock the branch. For more information, see Locking a branch.
Frequently merge the branch from the team application layer to the production rulesets. For more
information, see Merging branches into target rulesets.
Note: It is recommended that no more than two or three scrum teams share a development environment.
Multiple teams can share development systems, which can depend upon geographical distribution of teams,
system load, risk of teams making system-wide changes, and demand for system restarts.
Build a team application layer that is built on top of the main production application. The team application
layer contains branches, tests, and other development rulesets that are not intended to go into production.
For more information, see Using multiple built-on applications.
Put all necessary configuration information for the development server in a development application that
you can maintain, package, and deploy on demand so that you can quickly start up new remote
development systems.
Create a branch of your production ruleset in the team application. For more information, see Adding
branches to your application.
Name the branch with the feature or bug ID from your project management tool so that you can associate
changes with a corresponding feature or bug.
Perform all development work in the branch in versioned rules. Use branches for targeted collaboration and
so that you can use development best practices such as conducting branch reviews and monitoring
application quality metrics. You can also quickly test and roll back changes before you merge branches.
Do not do branch development on the source development system to avoid having multiple versions of the
same branch on the both the source development system and remote development system. The same
branch might contain different contents that conflict with each other.
Avoid developing rules in unlocked rulesets. Lock rulesets to ensure that rules are not accidentally and
directly changed, because changes should be introduced only when branches are merged. Use a continuous
integration server such as Deployment Manager to ensure that passwords to locked rulesets are not shared
publicly.
Optional: Use release toggles to disable features that are not ready for general use. Using toggles allows you
to merge branch content frequently even if some content is not final. For more information, see Toggling
features on and off.
Optional: Create formal review tasks for other members of the development team to review your content.
For more information, see Creating a branch review.
Optional: Use the branch developer tools to review the content and quality of your branch. For more
information, see Reviewing branches.
Optional: Lock the branch before you migrate it to the source development system. For more information,
see Locking a branch.
Avoid deleting a branch before you migrate it into the main development system.
Delete a branch after you import it into the main development system so that you do not import older data
or rule instances and unintentionally merge them into the main application.
Maintain a branch only as long as you need it. The longer that you keep a branch, the likelihood increases
that the branch will have conflicts, which can be difficult to resolve.
Be aware that you cannot make some rule updates in branches, such as updates to application records,
classes, libraries, and schema. Senior application architects on he team should make these changes directly
on the main development system.
The release pipeline in the following diagram illustrates the best practices for using Pega Platform for DevOps. At
each stage in the pipeline, a continuous loop presents the development team with feedback on testing results.
This example includes the following assumptions:
Understanding development
Pega Platform developers use Agile practices to create applications and commit the changes into branches
in a shared development environment. Automated and manual testing provides rapid feedback to
developers so that they can improve the application.
With continuous integration, application developers frequently check in their changes to the source
environment and use an automated build process to automatically verify these changes. Continuous
integration identifies issues and pinpoints them early in the cycle. Use Jenkins with the prpcServiceUtils tool
and the execute test service to automatically generate a potentially deployable application and export the
application archive to a binary repository such as JFrog Artifactory.
With continuous delivery, application changes run through rigorous automated regression testing and are
deployed to a staging environment for further testing to ensure that there is a high confidence the
application is ready to deploy on the production system.
Understanding deployment
After an application change passes the testing requirements, use Jenkins and the prpcServiceUtils tools to
migrate the changes into production after complete validation through automated testing on the staging
system. Use application release guidelines to deploy with minimal downtime.
Understanding development
Pega Platform developers use Agile practices to create applications and commit the changes into branches in a
shared development environment. Automated and manual testing provides rapid feedback to developers so that
they can improve the application.
Leverage multiple built-on applications to develop and process smaller component applications. Smaller
applications move through the pipeline faster and are easier to develop, test, and maintain.
Create one Pega Platform instance as a source environment that acts as a single source of truth for the
application. This introduces stability into the developer environment and ensures that a problem in one
developer environment does not affect other environments.
Use Pega Platform developer tools, for example:
The rule compare feature allows you to see the differences between two versions of a specific rule.
The rule form search tool allows you to find a specific rule in your application.
Follow branch-based development practices:
Developers can work on a shared development environment or local environments.
Content in branches migrates from the development environments to merge into the source
environment.
Create an archive by exporting and storing backup versions of each branch in a separate location in the
application repository. If a corrupted system state requires you to restore the source environment to a
previous known good application version, the branches can be down-merged to reapply the changes in
those branches that were lost as part of the restore.
Use unit tests to ensure quality.
Ensure that the work on a ruleset is reviewed and that the changes are validated. Lock every complete and
validated ruleset.
Regularly synchronize the development environments with the source environment.
For more information, see the following articles and help topics:
Application development
Understanding best practices for DevOps-based development workflows
Using multiple built-on applications
Searching for a rule
Checking out a rule
Checking in a rule
Comparing rule versions
Understanding best practices for version control in the DevOps pipeline
Branching
Rule development in branches
Merging branches into target rulesets
Using the Lock and Roll feature for managing ruleset versions
Adding a branch from a repository
Publishing a branch to a repository
Creating a toggle
Testing
Pega Platform application testing in the DevOps pipeline
PegaUnit testing
To automatically generate a valid application, properly define the application Rule-Admin-Product rule and
update the rule whenever the application changes. The prpcServiceUtils tool requires a predefined Rule-
Admin-Product rule.
To identify issues early, run unit tests and critical integration tests before packaging the application. If any
one of these tests fails, stop the release pipeline until the issue is fixed.
Publish the exported application archives into a repository such as JFrog Artifactory to maintain a version
history of deployable applications.
For more information, see the following articles and help topics:
Use Jenkins with the prpcServiceUtils tool to deploy the packaged application to test environments for regression
testing or for other testing such as performance testing, compatibility testing, acceptance testing, and so on. At
the end of the continuous delivery stage, the application is declared ready to deploy to the production
environment. Follow these best practices to ensure quality:
Use Docker or a similar tool to create test environments for user acceptance tests (UAT) and exploratory
tests.
Create a wide variety of regression tests through the user interface and the service layer.
Check the tests into a separate version control system such as Git.
If a test fails, roll back the latest import.
If all the tests pass, annotate the application package to indicate that it is ready to be deployed. Deployment
can be done either automatically with Jenkins and JFrog Artifactory or manually.
For more information, see the following articles and help topics:
Understanding deployment
After an application change passes the testing requirements, use Jenkins and the prpcServiceUtils tools to
migrate the changes into production after complete validation through automated testing on the staging system.
Use application release guidelines to deploy with minimal downtime.
For more information, see the following articles and help topics:
When you use semantic versioning, the part of the version number that is incremented communicates the
significance of the change. Additional information about semantic versioning is available on the web.
The version number, in the format NN-NN-NN, defines the major version (first two digits), minor version (middle
digits), and patch version (last digits), for example, 03-01-15.
Major versions include significant features that might cause compatibility issues with earlier releases.
Minor versions include enhancements or incremental updates.
Patch versions include small changes such as bug fixes.
Rulesets include all versions of each rule. Skimming reduces the number of rules by collecting the highest version
of rules in the ruleset and copying them to a new major or minor version of that ruleset, with patch version 01.
For more information about skimming, see Skim to create a higher version.
Work in branches.
Consider creating a major version of your application if you upgrade your application server or database
server to a major new version.
For small single scrum teams:
Increment both the patch and the minor version during every merge.
Developers merge into the next incremented patch version.
For multiple scrum teams:
Assign a user the role of a release manager, who determines the application version and release
strategy. This user should be familiar with concepts and features such as rulesets, ruleset versioning,
application records, and application migration strategies.
The release manager selects a development ruleset version number that includes a patch version
number.
Developers merge into the highest available ruleset version.
Frequently increment ruleset versions to easily track updates to your application over time.
Maintain an application record that is capped at major and minor versions of its component rulesets.
You can set up a CI/CD pipeline for your Pega Platform application using one of two methods:
Use third-party tools, such as Jenkins, to start a job and perform operations on your software. For more
information, see Configuring a continuous integration and delivery pipeline.
Use Deployment Manager, where you use Pega Platform as the orchestration server that runs the pipeline,
packages your application, and manages importing packages from and exporting packages to repositories
that connect from one system to another. For more information, see Understanding model-driven DevOps
with Deployment Manager.
If you are working in a continuous integration and delivery (CI/CD) pipeline, you can add a branch from a
repository to your development application. You cannot add a branch that contains branched versions of a
ruleset that is not in your application stack.
If you are using a continuous integration and delivery (CI/CD) pipeline with third-party tools such as Jenkins,
you can publish a branch from your development application to a Pega repository on the main development
system (remote system of record) to start a merge.
If you are using continuous integration in a CI/CD pipeline with either Deployment Manager or third-party
automation servers such as Jenkins, after you merge branches, you can rebase your development application
to obtain the most recently committed rulesets. Rebasing allows development teams working in separate
development environments to share their changes and keep their local rule bases synchronized. Having the
most recently committed rules on your development system decreases the probability of conflicts with other
development teams.
Related Content
Article
Article
PegaUnit testing
2. Right-click the application into which you want to import a branch and select Add branch from repository.
3. In the Add branch from repository dialog box, from the Repository list, select the repository that contains the
branch that you want to import.
4. In the Branch name field, press the Down Arrow key and select the branch that you want to import.
5. Click Import.
6. Click OK.
7. If you are using multiple branches, reorder the list of branches so that it matches the order in which rules
should be resolved.
Related Content
Article
2. Right-click the branch that you want to push to a repository and click Publish to repository.
3. In the Push branch to repository dialog box, select the repository from the Repository list.
4. Click Publish.
Result: You receive a message if the repository is not configured properly or is down, and you cannot push
the branch to the repository.
5. Click Close.
Related Content
Article
Article
For example, you can publish a branch from your development application to a Pega repository on a source
development system, which starts a job on Jenkins as your automation server and merges branches. You can also
use the Merge branches wizard to start a Deployment Manager build by first merging branches in a distributed or
nondistributed, branch-based environment. After the merge is completed, you can rebase the rulesets on your
development application to obtain the merged rulesets.
Before you can rebase your development system, you must first configure a Pega repository and then enable
ruleset versions for them. You must also have the appropriate permissions for rebasing.
When you use continuous integration and delivery (CI/CD pipelines) third-party automation servers, you use
Pega Platform as a binary repository for rule artifacts during development. You also use Pega repositories
when you are rebasing your development application when you are using third-party automation servers or
Deployment Manager.
If you are using a continuous integration and continuous delivery (CI/CD) pipeline with Deployment Manager
or third-party auomation servers such as Jenkins, you can rebase your development application to obtain the
most recently committed rulesets through Pega repositories after you merge branches on the source
development system.
Related Content
Article
1. If you are using Pega repositories with third-party automation servers such as Jenkins, enable the Pega
repository type.
You do not need to enable Pega repositories if you are using Deployment Manager. For more information,
see Enabling the Pega repository type.
2. Create a connection to a Pega type repository that supports ruleset version artifacts. For more information,
see Adding a Pega repository.
3. Enable ruleset versions for Pega repositories by configuring the HostedRulesetsList dynamic system setting
on the system of record. For more information, see Enabling ruleset versions for Pega repositories for
rebasing.
4. Ensure that you the pxCanRebase privilege so that you can rebase rules. This privilege is associated with the
sysadmin4 role.
If you do not have this privilege, you can add it to your role. For more information, see Specifying privileges
for an Access of Role to Object rule.
2. On the Settings tab, in the Value field, enter a comma-separated list of the rulesets on the remote
development system. Enclose each ruleset value within quotation marks, for example, “HRApp.”
3. Click Save.
Related Content
Article
Enabling the Pega repository type
Article
If you are using Deployment Manager, the Pega repository type is already enabled; otherwise, you must first
enable it for your application by completing the following steps:
1. Click Records Decision When and open the pyCanRebase rule that applies to @baseclass.
4. In the Conditions tab, click Actions Edit and change the condition to true.
5. Click Submit.
6. Click Save.
7. If you are rebasing rules to refresh your development system with the latest rulesets that are hosted on a
remote development system, enable ruleset versions for Pega repositories. For more information, see
Enabling ruleset versions for the Pega repository.
Related Content
Article
Creating a repository
Article
Before you begin: To rebase rules, you must first merge branches to make changes to rules. Changes made to
rules in an unlocked ruleset version will not be visible by the rebase functionality.
Note: Only one rebase event at a time is supported per development system to prevent accidentally overriding a
rebase event that is in progress.Note: You can improve rebase performance by frequently incrementing the
application patch version.
1. If you are migrating and merging branches separately, manually migrate branches for an application that
has a new major or minor version. Rebase only pulls the ruleset version that is visible to your current
application.
For example: For example, if you previously migrated a branch for an application of version 1.x but are
now working on a 2.x application version, migrate the 2.x branch ruleset to the main development system
before rebasing. Otherwise, rebase refreshes your development system with the 1.x ruleset versions.
2. In the header of Dev Studio click the name of your application, and then click Definition.
3. On the Definition tab, click Get latest ruleset versions.
4. In the Select repository list, select the repository from which to retrieve rules to see a list of ruleset versions
that will be rebased.
5. Click Rebase.
If there are no import conflicts, your development application is refreshed with the rules.
If there are import conflicts, the system displays them. For example, a conflict can occur if you made a
change to the same ruleset version on your local development system or if you modified a non-resolved
rule in the ruleset, such as the Application record. To resolve a conflict, complete the following step.
6. If you have conflicts, you must resolve them before rebasing continues, either by overwriting or rejecting the
changes on your development system. Complete the following steps to import the ruleset and either
overwrite or reject the changes that you made to the ruleset on the development system:
a. For each ruleset, click the Download Archive link and save the .zip file.
b. Click the Click here to launch the Import wizard link at the top of the Rebase rule form to open the
Import wizard, which you use to import the .zip files. For more information, see Importing rules and data
by using the Import wizard.
c. In the wizard, specify whether to use the older version of the ruleset or overwrite the older version with
the newer version.
d. After you resolve all conflicts, restart the rebase process by starting from step 1.
Related Content
Article
Article
The component for Sonatype Nexus Repository Manager 3 supports Pega 8.1, 8.2, 8.3, and 8.4.
Note: Because of potential conflicts, you should not use both Sonatype Nexus Repository Manager 2 and
Sonatype Nexus Repository Manager 3 type repositories in one application. If you want to use both repository
types, contact [email protected].
For answers to frequently asked questions, see the Nexus FAQ page.
Download and enable the component so that you can configure a Sonatype Nexus Repository Manager 2
repository.
After downloading and enabling the Sonatype Nexus Repository Manager 3 component, create a repository
in Pega Platform.
When you use repository APIs to interact with Nexus Repository Manager 3, note the following information:
Related Content
Article
Article
Repository APIs
2. In the header of Dev Studio, click the name of your application, and then click Definition.
3. In the Application rule form, on the Definition tab, in the Enabled components section, click Manage
components.
4. Click Install new, select the file that you downloaded from Pega Marketplace, and then click Open.
5. Select the Enabled check box to enable this component for your application, and then click OK.
6. In the list of enabled components, select PegaNexus3Repository, select the appropriate version, and then
click Save.
7. If you are using Deployment Manager, on each candidate system and on the orchestration system, perform
one of the following tasks:
Related Content
Article
Note: You can create only raw type repositories.To create a repository, do the following steps:
2. In the Create Repository rule form, enter a description and name for your repository, and then click Create
and open.
3. In the Edit Repository rule form, on the Definition tab, click Select.
5. In the Repository configuration section, configure location information for the repository:
a. In the System URL field, enter the URL of your Nexus Repository Manager 3 server.
c. In the Root path field, enter the path of the folder where repository assets are stored. Do not include the
repository folder in the path, and do not start or end the path with the slash (/) character.
For example: To store assets in a folder with the URL http://myexusrepo.com/repository/raw/myCo/devops , enter the
following information:
System URL: http://mynexusrepo.com
Repository name: raw
Root path: myCo/devops
The connector will allow you to browse the assets in this folder from inside Pega Platform.
a. In the Authentication profile field, enter the name of a new authentication profile, and then click the
Open icon to configure the profile.
The authentication profile stores the credentials that Pega Platform needs to authenticate with the
Nexus Repository Manager 3 API.
b. In the Create Authentication Profile rule form, in the Type list, select Basic.
Only Basic authentication is supported. For more information about Basic authentication profiles, see
Configuring a Basic authentication profile.
a. Enter the user name, password, realm, and host name required to authenticate with Sonatype Nexus
Repository Manager 3. For more information, see the Sonatype Nexus Repository Manager 3
documentation.
c. Click Save.
8. To verify that the system URL, authentication profile, and repository name are configured properly, in the
Edit Repository rule form, on the Definition tab, click Test connectivity.
If there are any errors, ensure that the credentials in the authentication profile are correct and that Pega
Platform can access the system URL that you entered.
Note: Testing connectivity does not verify that the root path is configured properly.
9. Click Save.
Related Content
Article
Sonatype Nexus Repository Manager 3 does not support the create folder API (D_pxNewFolder), because the
repository cannot have empty folders.
The create file API (D_pxNewFile) and get file API (D_pxGetFile) only support Basic Authentication and support
a file size of up to 5 GB.
The delete API (D_pxDelete) does not work on folders, only files. If all the files in a folder are deleted, the
folder is also deleted.
Related Content
Article
For answers to frequently asked questions, see the Nexus FAQ page.
Download and enable the component so that you can configure a Nexus Repository Manager 3 repository.
After downloading and enabling the component for Sonatype Nexus Repository Manager 2, create a
repository in Pega Platform.
When you use repository APIs to interact with Nexus Repository Manager 2, note the following information:
Related Content
Article
Article
Repository APIs
2. In the header of Dev Studio, click the name of your application, and then click Definition.
3. In the Application rule form, on the Definition tab, in the Enabled components section, click Manage
components.
4. Click Install new, select the file that you downloaded from Pega Marketplace, and then click Open.
5. Select the Enabled check box to enable this component for your application, and then click OK.
6. In the list of enabled components, select Pega Nexus Repository Connector, select the appropriate version,
and then click Save.
7. If you are using Deployment Manager, on each candidate system and on the orchestration system, perform
one of the following tasks:
Related Content
Article
2. In the Create Repository rule form, enter a description and name for your repository, and then click Create
and open.
3. In the Edit Repository rule form, on the Definition tab, click Select.
5. In the Repository configuration section, configure location information for the repository:
b. In the Repository ID field, enter the ID of the repository, which you can find on the Configuration tab in
Nexus Repository Manager 2.
For more information, see the documentation for Nexus Repository Manager 2.
c. In the Root path field, enter the path of the folder where repository assets are stored. Do not include the
repository folder in the path, and do not start or end the path with the slash (/) character.
For example: To store assets in a folder with the URL http://myexusrepo.com/repository/raw/myCo/devops , enter the
following information:
System URL: http://mynexusrepo.com
Repository ID: raw
Root path: myCo/devops
The connector will allow you to browse the assets in this folder from inside Pega Platform.
a. In the Authentication profile field, enter the name of a new authentication profile and click the Open
icon to configure the profile.
The authentication profile stores the credentials that Pega Platform needs to authenticate with the
Nexus Repository Manager 2 API.
b. In the Create Authentication Profile rule form, in the Type list, select Basic.
a. Enter the user name, password, realm, and host name required to authenticate with Nexus Repository
Manager 2. For more information, see the Nexus Repository Manager 2 documentation.
c. Click Save.
8. To verify that the system URL and authentication profile are configured properly, in the Edit Repository
rule form, on the Definition tab, click Test connectivity.
If there are any errors, ensure that the credentials in the authentication profile are correct and that Pega
Platform can access the system URL that you entered.
Note: Testing connectivity does not verify that the repository ID or root path are configured properly.
9. Click Save.
Related Content
Article
Downloading and enabling the component
Sonatype Nexus Repository Manager 2 does not consider recursiveDelete parameter for the delete API
(D_pxDelete). All folder deletes are considered recursive.
The create file API (D_pxNewFile) and get file API (D_pxGetFile) only support Basic Authentication and support
a file size of up to 5 GB.
Related Content
Article
For more information about prpcServiceUtils for service-enabled scripting, see Using service-enabled scripting and
the prpcServiceUtils tool.
Download and install prpcServiceUtils so that you can use it with Jenkins deploy applications.
Configure your build environment to call the prpcServiceUtils.bat or prpcServiceUtils.sh script and pass
parameters to import or export the RAP.
Configure your build environment to call the prpcServiceUtils.bat or prpcServiceUtils.sh script and pass
parameters to import or export the RAP:
You can enter build steps to import an archive or export an archive, or you can do both in one job.
2. Extract the files onto any location to which Jenkins has access.
Related Content
Article
Article
Ant Plugin
Environment Injector Plugin
Build with Parameters Plugin
c. In the value field, enter the location where you extracted the prpcServiceUtils.zip file.
d. Click Add.
Related Content
Article
Article
2. Click Configure.
4. Click Add Parameter and create the parameters that Jenkins passes to the prpcServiceUtils tool:
Product parameters
Parameter name Type Default value
Application parameters
SystemName=$BUILD_TAG
Source Code Management=None
Inject environment variables to the build process=Properties Content
7. 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 (for
example, ruleset or version), replace the existing rule with the imported rule.
For work - If a work object with the same key exists but belongs to a different application (for example,
it has a 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 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. Set the artifact directory where exported logs and files are downloaded In the following format: ARTIFACTS_DIR=
<var>path to artifact directory</var>
Note: You can also set the directory later by specifying -artifactsDir when you run the batch file.
9. In the Properties Content section, enter the static properties in the format ParameterName=Value.
Parameter
Default value
name
The host name and port number of the Pega Platform server from which to export
SourceHost
the archive file.
SourceUser The operator name. This operator must have export privileges.
Parameter
Default value
name
SourcePassword The operator password.
Target properties for import:
Parameter
Default value
name
The host name and port number of the Pega Platform server that contains the
TargetHost
archive file to import.
TargetUser The operator name. This operator must have import privileges.
Related Content
Article
Article
Related Content
Article
Article
Article
a. In the Build section, click Add build step and select Invoke Ant.
c. In the Build File field, enter the path to the build file:
a. In the Build section, click Add build step and select Execute Windows batch command.
a. In the Build section, click Add build step and select Execute Shell batch command.
b. In the Command field, enter the following command: $PEGA_HOME/scripts/utils/prpcServiceUtils.sh export --connPropFile
$WORKSPACE/${SystemName}_export.properties --artifactsDir $WORKSPACE
Related Content
Article
Article
a. In the Build section, click Add build step and select Invoke Ant.
c. In the Build File field, enter the path to the build file:
a. In the Build section, click Add build step and select Execute Windows batch command.
a. In the Build section, click Add build step and select Execute Shell batch command.
Related Content
Article
Article
2. When the parameter values are displayed, verify the default settings and edit any values.
3. Set the artifact directory where exported logs and files are downloaded in the following format: -artifactsDir=
<var>path to artifact directory</var>
4. Click Build.
Related Content
Article
The process that you use to release changes to your application is different depending on the types of changes
that you are making. This topic describes the Standard Release process that you can use to deploy changes to
rules, data instances, and dynamic system settings. The Standard Release process is a self-service way to deploy
changes without downtime. Other methods for releasing changes to your application are not covered in this
article. For more information, see Application release changes, types, and processes.
This Standard Release process applies to both on-premises and Pega Cloud Services environments. As a Pega
Cloud Services customer, if you use this self-service process to release changes to your application, you are
responsible for those changes. For more information, see Change management in Pega Cloud Services and
Service level agreement for Pega Cloud Services.
The Standard Release process includes the following steps and is scalable to the number and types of
environments that you have:
1. Package the release on your shared development environment. For more information, see Packaging a
release on your development environment.
2. Deploy the changes to your staging or production environment. For more information, see Deploying
application changes to your staging or production environment.
Before you migrate your application, both your environment and application must meet certain
requirements. For example, you must be able to download a RAP archive to a file system location with the
required available space.
You have at least two existing Pega Platform environments. These environments can be any combination of
sandbox and production environments, and can be on-premises or in the Pega Cloud virtual private cloud
(VPC).
You can log in to a machine from which you will complete the release process, such as your organization's
laptop, workstation, or server.
You have a location on a file system with enough available space to store the RAP archives. You must be
able to download the RAP archive to this location and upload a RAP archive to another system from this
location.
You have complied with stated application guideline and guardrail requirements.
Your application rule must specify rulesets that have a patch version. Most application rules have the ruleset
version in the stack set to 01-01, such as "Ruleset: 01-01". You must change this to specify your rulesets to
the patch level of their version, which is "Ruleset: 01-01-01". This is required for your top-level application
rule and all built-on applications, except the base PegaRULES built-on application. This application structure
gives you greater control over the release of your software, minimizes the impact of the release on
application users, and provides for the smoothest recovery path in case of a troubled deployment.
All developers in the organization use a single shared development environment (recommended by
Pegasystems).
The organization follows a distributed development model, where individual developers or development
teams have their own isolated development environments.
The release process works for either development scenario, because it begins after changes have been merged
into the appropriate ruleset versions. Regardless of development scenario or team size, development teams must
use branching and merging for releasing applications. Otherwise, you cannot take full advantage of the tools and
capabilities of the Pega Platform. For more information, see Understanding application migration scenarios.
This Standard Release process applies to both on-premises and Pega Cloud Services environments. As a Pega
Cloud Services customer, if you use this self-service process to release changes to your application, you are
responsible for those changes. For more information, see Change management in Pega Cloud Services and
Service level agreement for Pega Cloud Services.
In the event of any issues, you can roll back the deployment and restore your system to a state that was
previously known to be working.
Before you deploy application changes, you must know about the types of changes that you can make within a
release, the release types, and the release management process to follow based on the changes you want to
deploy. For example, SQL changes that remove columns from database tables or remove data types can interrupt
service for users of the application. You must deploy these types of changes during scheduled downtime when
users are offline. For more information, see Understanding application release changes, types, and processes.
After you create the application archives, deploy them to your target system. This process is the best way to
deploy changes into your staging or production environment, control their activation, and recover from
problematic deployments.
After you deploy the changes, the release engineer and specified users can test the changes. For the staging
environment, test the performance and the user interface, run automated tests, and do acceptance testing.
For the production environment, perform validation tests.
After your Rules archive and Data archive are successfully deployed, changes are activated in various ways.
Activation is the process by which a category of changes becomes usable by appropriate users of the
system, if they have access.
In the event of a problematic deployment, the first goal is to prevent further issues from occurring. Then you
can roll back the deployment and restore your system to a state that was previously known to be working.
The user who imports the archives must have the zipMoveImport and SchemaImport privileges on the target
system.
1. Ensure that you have connectivity to both the target system and to the location where the archives are
stored.
2. Use the prpcServiceUtils command line utility to import the archives to the target system:
Deploy the Rules archive by following the steps in Importing rules and data by using a direct connection
to the database. Your changes are sent to the system, imported to the database, and ready for
activation.
Deploy the Data archive by following the steps in Rolling back and committing tracked data. When you
deploy the Data archive, you use the same tool that you used to deploy the Rule archive but with
different properties. You can roll back these changes if required.
Result: For information about allowing automatic schema changes, see Editing administrator privileges for
importing archives with schema changes into production.
1. On the target system, create a copy of the access group for your application. This step is a one-time process,
because now this access group is available anytime you deploy changes.
2. Update the copied access group so that it references the new application version.
3. Find the operator ID record for a test user and give that operator ID record access to the access group that
you just created.
Result: You can now safely test your changes in the system at the same time as other users who are running on
the previous version.
When you are satisfied that your release was deployed successfully, Release Engineering can activate the release
for all users in the production environment.
Data changes, including schema changes, take effect immediately after being imported to the system. Your
application might be able to access these fields immediately. After testing and when you are sufficiently
comfortable, you should commit these changes. To commit data changes, follow the steps in Rolling back and
committing tracked data.
To activate rule changes, you need to update the access groups that point to the prior version of your application
rule:
1. In Dev Studio, click Records.
3. Search for the access groups to be updated by specifying your application name in the search box and
filtering the list.
4. After you locate the access group, open the record and increment the version number for your application to
the new release version.
5. Click Save.
Result: If you deploy code changes that need to be compiled, you must restart the system. Code changes cannot
be made without downtime, and your System Administrator must perform a system restart. For information about
the types of changes that you can make within a release, the release types, and the release management process
to follow, see Understanding application release changes, types, and processes.
1. Ensure that no new operators can access the problematic application. You can temporarily disable access to
the entire system. For more information, see How to temporarily disallow new interactive logins with a
Dynamic System Setting.
2. Roll back the problematic rules changes. You can roll back changes by updating the access group for your
application and specifying the previous version of your application.
Result: Roll back the data instances that you changed to their previous version. To roll back data changes, use
the prpcServiceUtils command line utility. For more information, see Rolling back and committing tracked data.
This process replaces those modified data instances with their prior definition, rolling back your data changes to
the last known, good state.
This Standard Release process applies to both on-premises and Pega Cloud Services environments. As a Pega
Cloud Services customer, if you use this self-service process to release changes to your application, you are
responsible for those changes. For more information, see Change management in Pega Cloud Services and
Service level agreement for Pega Cloud Services.
After you set up and package the release, you are ready to deploy the changes to your staging or production
environment.
When developers merge changes by using the Merge Wizard, they must select the ruleset version to which
to merge them. The release engineer is responsible for ensuring that each release has an unlocked ruleset
version that acts as the release target and into which these merges can be performed. Developers are
responsible for merging their branches into the correct, unlocked ruleset version and addressing any
conflicts.
After all merges are completed, the release engineer locks the applications and rulesets to be released. They
are also responsible for creating the new, higher-level ruleset versions and higher-level application rules for
the next release.
Creating the application archives
For each release, you create one or two RAP archives, depending on the changes you made to your
application. The user who exports the archives must have the zipMoveExport privilege.
Note: As a best practice, lock your built-on applications first, and then work your way up the stack to your
top-level application. This way, as each higher version application rule is created, you can open that rule and
update the version of the built-on application.
b. Click Roll.
5. Click Run.
Result: The application rules and ruleset versions for the current release are locked and require passwords to
make changes. Also, you will have created the higher-level ruleset versions and application rules that will be used
for the next release.
Related Content
Article
The Rules RAP, which contains the Rules portion of your release, instances from Rules- types only, and all
rules changes.
The Data RAP, which contains the Data portion of your release, instances from Data classes only, and all
data changes.
Splitting the release into a Rules RAP and a Data RAP provides you with more control over the deployment and
activation of your changes on other systems.
More RAP archives might be created during the development process. Import these RAP archives to a single
system from which the Rules RAP and Data RAP will be created. This method provides the greatest level of control
over the release by separating the release process from the development process.
1. Define the RAPs by using the Application Packaging wizard or by copying an existing RAP rule. For more
information, see Product rules.
a. Export the rules. For more information, see Export rules into an archive file
c. Store these archives in a standard location to which you have access, and that will be accessible during
deployment.
Result: A Rules archive and a Data archive are created as the result of this process.
Related Content
Article
Rules by name
Requires
a
Activates Support
Technical by Activates Activation requires Release Request
Change type
changes access immediately restart frequency (Pega
group Cloud
Services
only)
Rule-
Rule-
Application-
Rule
Rule-Obj-
Rules Class
(including Rule-Ruleset-
non-rule- Yes Yes No Daily/Weekly No
Name
resolved
rules) Rule-Ruleset-
Version
Rule-Access-
Role-Obj
Rule-Access-
Deny-Obj
Data
Data- No Yes No Weekly No
instances
MonthlyCertain
dynamic
system
YesCertain dynamic NoCertain dynamic settings
system settings system settings activate only
Dynamic Data-Admin- activate only on activate only on on system
system System- No system restart and system restart and restart and No
settings Settings require you to follow require you to follow require you to
Requires
the Environment the Environment follow the
a
Activates release process. release process. Environment Support
Technical by Activates Activation requires release
Release Request
Change type process.
changes access immediately restart frequency (Pega
group Yes Cloud
No
Services
Treat functional Treat functional only)
changes that changes that
reference code as a reference code as a
Code release, which Code release, which
requires a system requires a system
restart to activate if restart to activate if
you are making code you are making code
changes. changes.
Change type – Change type –
This column This column
lists the high- lists the high-
level category level category
of changes that of changes that
you can make you can make
in a release. in a release.
Technical Technical
changes – changes –
Technical Technical
changes changes
describe the describe the
rule types or rule types or
artifacts for a artifacts for a
change type. change type.
Rule- and Data- Rule- and Data-
include all include all
subtypes under subtypes under
that parent that parent
type, unless type, unless
specifically specifically
identified for a identified for a
different different
change type. change type.
Activates by Activates by
access group – access group –
Rule resolution Rule resolution
for this change for this change
type is type is
controlled by controlled by
the access the access
groups of an groups of an
operator. operator.
Activates Activates
immediately – immediately –
Rule resolution Rule resolution
uses this uses this
Rule-Utility- change type
Function change type
Functional Yes immediately immediately Monthly Yes
Rule-Utility- after after
Library deployment. deployment.
Activation Activation
requires restart requires restart
– This change – This change
type requires a type requires a
system restart system restart
before it is before it is
available to the available to the
rule resolution rule resolution
process. process.
Release Release
frequency – frequency – Requires
Release Release a
Activates frequency frequency Support
indicates the indicates the
Technical by Activates Activation requires Release Request
Change type period in which period in which
changes access immediately restart frequency (Pega
group you can deploy you can deploy Cloud
this type of this type of Services
change to change to only)
production. production.
Requires a Requires a
Support Support
Request (Pega Request (Pega
Cloud only) – As Cloud only) – As
a Pega Cloud a Pega Cloud
customer, you customer, you
are responsible are responsible
for any for any
application application
changes that changes that
you make; you make;
however, as a however, as a
best practice, best practice,
inform and inform and
engage Pega engage Pega
Support before Support before
releasing releasing
application application
changes. You changes. You
can open a can open a
Support Support
Request on My Request on My
Support Portal. Support Portal.
For more For more
information, information,
see My Support see My Support
Portal FAQ. Portal FAQ.
Changes
outside of
Environment Pega No No Yes Quarterly Yes
(JVM, XML
configuration)
Requires
a
New Support
Release Application users Significant Release Self-
Activates for users application Request
type affected UX impact frequency service
version (Pega
Cloud
only)
Environment
After restart All No Quarterly Yes No Yes
release
Activation of a Activation of a
Major release Major release
occurs based on occurs based on the
the change types change types that
that the release the release
contains. For contains. For
information about information about
how each change how each change
type is activated, type is activated,
see Table 1. see Table 1.
Does
Requires a
your
Follow Support
release
this Request
contain
release (Pega Cloud
the
process Services
following
only)
changes?
Does Data Dynamic Data Significant
Rules Requires
system a Functional Code Environment
your instances model UX impact
Follow Support
settings
release
this Request
contain
X X
release (Pega-Cloud - - - - - Bug fix No
the
process Services
following Standard
X X X
only) X - - - - No
changes? release
Database
- X - - X - - - Yes
release
Treat functional
changes that
reference code
as a Code
release, which
requires a
system restart to
activate if you
are making code
changes.
Rules – Are
you
deploying
Rules-
records in
this release?
Data
instances –
Are you
deploying
Data-
records in
this release?
Dynamic
System
Settings –
Are you
loading
Data-Admin-
System-
Settings
records in
this release?
Significant
UX impact –
Will users
need to
significantly
relearn a
process, or
are there
significant
layout
changes?
Code – Are
you loading
JAR files as
part of this
release?
Data model
– Are there
changes to
your data
model in
Does this release
Requires a (SQL)? Code
your
- - - - X - - Yes
Follow Support Environment release
release
this Request changes –
contain
release (Pega Cloud Will there be
the
process Services operating
following
only) system or
changes?
application
server
changes in
this release?
Follow this
release
process –
Based on
your
answers to
these
questions,
follow this
release
process.
Requires a
Support
Request
(Pega Cloud
Services
only) – As a
Pega Cloud
Services
customer,
you are
responsible
for any
application
changes
that you
make;
however, as
a best
practice,
inform and
engage
Pega
Support
before
releasing
application
changes.
You can
open a
Support
Request on
My Support
Portal. For
more
information,
see My
Support
Portal FAQ.
Certain
Dynamic
System
Settings
Does activate
Requires
only on a Environment
-
your - - - - X - Yes
Follow Support
system release
release
this Request
restart and
contain
release (Pega
requireCloud
you
the
process to Services
follow the
following
only)
Environment
changes?
release
process.
Major
X X X X X X X X Yes
release
At a high level, the recommended test automation strategy for testing your Pega applications is as follows:
Create your automation test suite based on industry best practices for test automation
Build up your automation test suite by using Pega Platform capabilities and industry test solutions
Run the right set of tests at different stages of your delivery pipeline
Test early and test often
Industry best practices for test automation can be graphically shown as a test pyramid. Test types at the bottom
of the pyramid are the least expensive to run, easiest to maintain, take the least amount of time to run, and
should represent the greatest number of tests in the test suite. Test types at the top of the pyramid are the most
expensive to run, hardest to maintain, take the most time to run, and should represent the least number of tests
in the test suite. The higher up the pyramid you go, the higher the overall cost and the lower the benefits.
Quickly identify areas within your application that need improvement by viewing metrics related to your
application's health on the Application Quality dashboard.
Before you create Pega unit test cases and test suites, you must configure a test ruleset in which to store
the tests.
PegaUnit testing
Automated unit testing is a key stage of a continuous development and continuous integration model of
application development. With continuous and thorough testing, issues are identified and fixed prior to
releasing an application, which improves the application quality.
UI testing
Perform UI-based functional tests and end-to-end scenario tests to verify that end-to-end cases work as
expected. Use the third party Selenium starter kit for CRM or the built-in scenario testing tool to perform the
UI testing.
Quickly identify areas within your application that need improvement by viewing metrics related to your
application's health on the Application Quality dashboard.
The Application Quality settings provides configurable options related to quality metrics. You can change the
default settings for metrics displayed to meet your business needs.
View historical test coverage metrics and generate reports containing the number of executable rules and
their test coverage. Use the data to analyze changes in test coverage, and to verify which rules require
testing.
View a report that contains the results of test coverage sessions to determine which rules in your application
are not covered with tests. You can improve the quality of your application by creating tests for all
uncovered rules that are indicated in the reports.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
For example, view your application's compliance score and see the number and severity of guardrail violations
that were found in your application. You can then improve your application's compliance score and overall quality
by investigating and resolving the violations.
To open the Application Quality dashboard, from the Dev Studio header, click Configure Application Quality
Dashboard .
Rule, case, and application – View the number of executable rules (functional rules that are supported by
test coverage) and the number of case types in the selected applications. To view metrics for a different
combination of applications, select a different list on the Application: Quality Settings page.
Guardrail compliance – View the compliance score and the number of guardrail violations for the included
applications, as well as a graph of changes to the compliance score over time. To see more details about the
application's guardrail compliance, click View details.
Test coverage – View the percentage and number of rules that are covered by tests, and the last generation
date of the application-level coverage report for the selected applications, as well as a graph of changes to
application-level coverage over time. To see test coverage reports or to generate a new coverage report,
click View details.
Note: If the EnableBuiltOnAppSelectionForQuality switch is turned on, then coverage sessions metrics are
also displayed on the Application Quality Dashboard for the built-on applications selected in Application:
Quality Settings.
Unit testing – View the percentage and number of Pega unit test cases that passed for the selected
applications, over the period selected on the Application Quality Settings landing page. The graph illustrates
the changes to the test pass rate over time. To see reports about test compliance and test execution, click
View details.
Case types – View guardrail score, severe guardrail warnings, test coverage, unit test pass rate, and scenario
test pass rate for each case type in the applications. To view additional details about a case type, click View
details.
Data types – View guardrail score, severe guardrail warnings, test coverage, and unit test pass rate for each
data type in the applications. To view additional details about a data type, click View details.
Other rules – View guardrail score, test coverage, test pass rate, the number of warnings, a list of rules with
warnings, the number and list of uncovered rules, and the number and list of failed test cases for rules that
are used in the selected applications but that are not a part of any case type.
The Application Quality dashboard displays metrics for guardrails, test coverage, and unit testing that you
can use to assess the overall health of your application and identify areas that require improvement. You can
change the default ranges for the color codes by modifying the corresponding when rules in the Data-
Application-Quality class.
Related Content
Article
Article
Article
The following table describes the relationship between colors, default ranges, and when rules. For each metric in
the Red, Orange, and Green columns, the top row indicates the default range for each color and the bottom row
indicates the corresponding when rule.
Related Content
Article
Note: To change settings on the landing page and to enable the EnableBuiltOnAppSelectionForQuality toggle that
allow you to select which built-on applications are included, your operator ID must have the SysAdm4 privilege.
On the Application Quality settings landing page, you can modify the following settings:
Application(s) included – If you want the test coverage report to include only rules from the current
application, select Current application only. If you want the test coverage report to also include rules from
built-on applications, select Include built-on applications. By default, only current application is selected. If
you enable the EnableBuiltOnAppSelectionForQuality toggle, you can select which built-on application will be
included.
Note: If a master user starts an application-level coverage session for an application, then that user's
configuration of this setting is in effect for all users that execute test coverage for the duration of this
session.
Ignore test rulesets when calculating Guardrail score – When you enable this setting, Guardrail score is
calculated without taking test rulesets into account. This is the default behavior. When you disable this
setting, test rulesets are taken into account when calculating Guardrail score.
Quality trends – Use this setting to change the date range of the trend graphs on the Application Quality,
Application: Test coverage and Application: Unit testing landing pages. The default value is Last 2 weeks.
Test case execution – Use this setting to change the number of days, from the time that they are executed
that tests are treated as executed by the Application Quality dashboard and coverage reports. By default, a
test executed later than seven days ago is considered too old to be included on the Application Quality
dashboard and in reports.
Scenario test case execution – Use this setting to add a delay (in milliseconds) to the execution of steps in a
scenario test.
Related Content
Article
Article
Article
Article
On the Test Coverage landing page, view a chart displaying test coverage metrics and generate specific user-
level, application-level, and merged coverage reports. User-level reports contain the results of a single test
coverage session that a user performs, while application-level reports contain results from multiple test coverage
sessions that many users run. Merged reports contain results from multiple most recent application-level reports.
Generate a user-level test coverage report to identify which executable rules in your currently included
applications are covered and not covered by tests. The results of this type of report are not visible on the
Application Quality Dashboard.
Generating an application-level test coverage report
Generate an application-level coverage report that contains coverage results from multiple users. Use this
report to identify which executable rules in your currently included applications are covered and not covered
by tests. The results of this type of report are visible on the Application Quality Dashboard.
When an application-level coverage session is running, you can perform tests of the application to contribute
to an application-level test coverage report that identifies the executable rules in your application that are
covered and not covered by tests.
Generate application-level coverage reports for every application in your system and in your application
stack, and then merge the most recent reports to a single report, to gain a consolidated overview of test
coverage for all your top-level or built-on applications.
1. In the header of Dev Studio, click Configure Application Quality Test Coverage .
Note: If the Application level coverage is in progress message is displayed, you cannot start a user-level coverage
session.
4. Enter the title of the coverage report, and then click OK.
5. To provide data for the report, run all of the tests that are available for your included applications, for
example, Pega unit automated tests and manual tests.
Note: If you close the tab or log out without clicking Stop, the report is not generated.
7. Review the results of the coverage session. In the Coverage history section, click Show Report.
8. Optional:
To see whether coverage reports were generated by other users, click Refresh.
9. Optional:
Related Content
Article
1. In the header of Dev Studio, click Configure Application Quality Test Coverage .
4. Enter the title of the coverage report, and then click OK.
5. Optional:
To provide data for the report, run all of the tests that are available for your currently included applications,
for example, Pega unit automated tests and manual tests.
6. Inform all relevant users that they can log in to the application and start running tests.
7. Wait until all users have completed their tests and have logged off.
Note: If you stop an application coverage session before a user has logged off, the coverage data of this
user is not included in the report.
9. Review the results of coverage session. In the Coverage history section click Show Report.
10. Optional:
To see whether coverage reports were generated by other users, click Refresh.
11. Optional:
Before you begin: Ensure that application-level coverage is in progress before you log in. If application
coverage is started after you log in, you cannot contribute to it unless you log off and log in again. Only users with
the pzStartOrStopMasterAppRuleCoverage privilege can initiate application-level coverage.
a. In the header of Dev Studio, click Configure Application Quality Test Coverage .
b. Verify that you see the Application level coverage is in progress message.
If you do not see the message, application-level coverage is not active, however, you can still start a
user-level test coverage session.
2. To provide data for the report, execute all the tests that are available for the included applications, for
example, Pega unit automated tests and manual tests.
Note: During the coverage session your local configuration for included applications is overridden by the
configuration of the user that started the application-level coverage session.
Note: If you do not log off before the rule coverage session is stopped, you will not contribute to the report. If
you log off and then log in again while the coverage session is still active, your test coverage sessions are
saved as a new session that will be included in the application coverage report.
Related Content
Article
Insight from a merged application report helps you avoid creating duplicate tests for rules that are used across
multiple applications. Note: Because a merged report is an instance of an application-level report, when a
merged report is the most recent one for an application, it is included in the next merged report.
Before you begin: Ensure that your operator ID has the pzStartOrStopMasterAppRuleCoverage privilege.
Generate at least one application-level coverage report for another application in your system or for a built-on
application in your current application. For more information, see Generating an application-level test coverage
report
1. Switch to the main application that you want to use as the baseline for the merged report. See Switching
between applications in.
2. In the header of Dev Studio, click Configure Application Quality Test Coverage .
5. Enter the title of the merged report, and then click Next.
6. In the list of the most recent reports, select the reports that you want to include in the merged report, and
then click Create.
Result: Dev Studio automatically adds the MRG_ prefix to every merged report to differentiate them from
standard application-level coverage reports and to facilitate finding them.
8. Open the merged report. In the Coverage history section find the merged report that you created and click
Show report.
9. Optional:
To open a report that is included in the merged report, in the Merged reports section, click the report name.
1. In the header of Dev Studio, click Configure Application Quality Test Coverage .
3. In the Coverage history section, hover over the row with the relevant test coverage session, and then click
Show Report.
4. Optional:
To include only the rules that were updated after a specific date, in the Rules updated after field, click
the calendar icon, select a date and time, and then click Apply.
To include all the rules that are covered with tests, click Covered.
To include all the rules that are not covered with tests, click Uncovered.
To filter the rules, in the column header that you want to filter, click the filter icon, enter the filter
criteria, and then click Apply.
To open a single report that is included in a merged report, in the Merged reports section, click the
report name.
To open a rule that is included in the report, click the rule name.
Setting up for test automation
Before you create Pega unit test cases and test suites, you must configure a test ruleset in which to store the
tests.
Before you can create unit test cases or scenario tests, you must configure a test ruleset in which to store
the tests.
1. In the Dev Studio header, open your application rule form by clicking your application and selecting
Definition.
Note: The test ruleset must always be the last ruleset in your application stack.
5. Select the Use this ruleset to store test cases check box.
Result: When you save test cases for rules, they are saved in this ruleset.
Related Content
Article
PegaUnit testing
PegaUnit testing
Automated unit testing is a key stage of a continuous development and continuous integration model of
application development. With continuous and thorough testing, issues are identified and fixed prior to releasing
an application, which improves the application quality.
Automated unit testing involves creating unit test cases for tests that are run against individual rules, grouping
multiple test cases into test suites, running the tests, and viewing the results. When the tests run, the results are
compared to the expected results that are defined in assertions.
A test case identifies one or more testable conditions (assertions) that are used to determine whether a rule
returns an expected result. Reusable test cases support the continuous delivery model, providing a way to
test rules on a recurring basis to identify the effects of new or modified rules.
You can group related unit test cases or test suites into a test suite so that you can run multiple test cases
and suites in a specified order. For example, you can run related test cases in a regression test suite when
changes are made to application functionality.
Setting up and cleaning the context for a test case or test suite
You can set up the environment and conditions required for running a test case, determine how to clean up
test data at the end of the test run, and set pages on which to automatically run rules.
Viewing unit test reports
View a graph with test pass rate trend data, a summary of Pega unit tests that were run, and an overview of
Pega unit test compliance for currently included applications on the Reports tab on the Unit Testing landing
page.
On the Application: Unit testing landing page you can display a list of unit tests that are not associated with
any rule and export this list to an XLS or a PDF file. You should deactivate these unit tests because they will
always fail.
Running test cases and suites with the Execute Tests service
You can use the Execute Tests service (REST API) to validate the quality of your code after every build is
created by running unit test cases that are configured for the application.
Understanding Pega Platform 7.2.2 and later behavior when switching between Pega unit testing and
Automated Unit Testing features
Beginning with Pega 7.2.2, you can use Pega unit testing to create test cases to validate the quality of your
application by comparing the expected test output with results that are returned by running rules.
In older versions of Pega Platform, automated unit tests were created using the Automated Unit Testing
(AUT) tool, which has since been replaced by PegaUnit testing. If you have automated unit tests that were
created using AUT and they haven't been changed to PegaUnit test cases, then you can switch back to AUT
to manage those tests.
To create test cases, you must have a rule set that can store test cases. For more information, see Creating a test
ruleset to store test cases.
Note: AUT is deprecated. Use PegaUnit testing instead to create automated test rules.
Automated unit testing information is available on the Testing Applications landing page on Pega Community and
in the automated unit testing topics in the help.
Create test cases for automated unit testing to validate application data by comparing expected output to
the actual output that is returned by running rules.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
Related Content
Article
Creating a rule
Article
Article
Creating a specialized or circumstance rule
You can create automated unit testing test cases for the following rule types:
Activity
Decision table
Decision tree
Flow
Service SOAP
Note: AUT is deprecated. Use PegaUnit testing instead to create automated test rules.
Automated unit testing information is available on the Testing Applications landing page on Pega Community and
in the automated unit testing topics in the help.
Related Content
Article
Article
Rules development
The Unit Test Suite rule form consists of the Contents tab.
Note: AUT is deprecated. Use PegaUnit testing instead to create automated test rules.
Automated unit testing information is available on the Testing Applications landing page on Pega Community
and in the automated unit testing topics in the help.
You must have the AutomatedTesting privilege to work with unit test suite rules.
You can create a unit test suite that includes all the test cases for a specific rule type, or you can select individual
rules and specify the sequence in which to run them.
To run a unit test suite, use the Schedule gadget on the Automated Unit Testing landing page. For more
information, see Working with the deprecated AUT tool. From that gadget, you can choose to run the unit test
suite immediately or schedule the run for a future time.
For unit test suites that are scheduled to run at future times, an agent activity in the Pega-AutoTest agents rule
checks for unit test suite requests every five minutes and runs those that are due. When the agent activity
finishes running a unit test suite, it sends an email message with the results. By default, this completion email
message is sent to the person who scheduled the unit test suite run, and to any additional email addresses
specified at the time the run is scheduled. If no email addresses are specified at the time the run was scheduled,
no email message is sent.
Access
For more information, see Working with the deprecated AUT tool to work with the Unit Test Suites that are
available to you. You can:
Use the Automated Unit Tests gadget to see the Unit Test Suites and the test cases in each.
Use the Create Suite button on the Schedule gadget to create unit test suites.
Use the calendar button on the Schedule gadget to run unit test suites immediately and to schedule unit
test suite runs.
Category
Unit Test Suites are instances of the Rule-AutoTest-Suite class. They belong to the SysAdmin category.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
Use the Contents tab to define the unit test suite. Specify a user (Operator ID) that the Pega-AutoTest agents
are to use by default when running the suite, and select the test cases to include.
To create a unit test suite rule, use the Create Suite button on the Schedule gadget of the Automated Unit Testing
landing page. To open the Automated Unit Testing landing page, select Dev Studio > Application > Automated
Unit Testing.
You must have the AutomatedTesting privilege to be able to create unit test suites. For information about how to
enable this privilege, see About Automated Unit Testing.
A unit test suite rule has a single key part, the unit test suite name:
Field Description
Name Enter a short, descriptive name for the unit test suite.
Create a separate RuleSet to hold test cases and unit test suites, rather than using a RuleSet that will be moved
to a production system. For more information, consult the articles in the Testing Applications category of Pega
Community.
For general information about the Create and Save As forms, see:
Creating a rule.
Copying a rule or data instance .
As with most rules, when you search for a Unit Test Suite, the system shows you only those rules that belong to a
RuleSet and version that you have access to.
Related Content
Article
In the navigation pane of Dev Studio, click Configure Application Quality Automated Testing Unit Testing
Test Cases .
2. In the Test case name column, click the test case that you want to open.
Related Content
Article
Article
Article
PegaUnit testing
Article
Viewing test details and results on the Application:Unit testing landing page
Before you begin: Unit test a rule and convert the test run into a test case. For more information, see Unit
testing individual rules.
1. Optional:
To modify the rule or class that is used for the test, in the upper-right corner of the Definition tab, click the
Gear icon, select the rule or class and then click Submit.
If you are testing a strategy rule, then the componentName and pzRandomSeed parameters are also
displayed. If you change either of these parameters, the test case does not return the expected results.
componentName – The name of the component (for example, Switch) that you are testing.
pzRandomSeed – Internal parameter, which is the random seed for the Split and Champion Challenger
shapes.
2. Optional:
To prevent the test from being run as part of a test suite or from a REST service, on the Definition tab, select
the Disable check box.
The test case will be run only when you click Actions Run .
3. In the Expected results section, add assertions that define the expected results of the test. For more
information about creating assertions, see Assertions.
4. On the Setup & Cleanup tab, configure the actions to perform and the objects and clipboard pages to be
available before and after the test runs. You can also clean up the clipboard after the test is run by applying
additional data transforms or activities. For more information, see Setting up your test environment.
5. Click Save.
6. In the Details dialog box, enter a label that identifies the test case. The test case identifier is generated
based on the label and cannot be modified after it is saved.
Viewing test case results
After you run a unit test case, you can view the results of the test run.
When the test was last run and the user who ran it.
The rule associated with the test.
The parameters sent.
Errors for failed tests.
Unexpected results for failed tests. This information also includes the run time of the test and the expected
run time of the test if the expected run time assertion fails.
2. In the Run history column, click View for the test case that you want to view.
3. In the Test Runs Log dialog box, click the row for the instance of the test case that you want to view to
open the test results in a new tab in Dev Studio.
You can also view test case results in the Edit Test Case form after you immediately run the test, in the Test
Case tab of the rule form or, for data pages, in the Data Page testing landing page.
Related Content
Article
PegaUnit testing
Article
Viewing test details and results on the Application:Unit testing landing page
To run multiple test cases, select the test cases that you want to run, and then click Run selected.
To run a disabled test case or a single test case, click the test case to open it, and then click Actions
Run .
Related Content
Article
PegaUnit testing
Article
Viewing test details and results on the Application:Unit testing landing page
1. Export a list of all the Pega unit test cases that are in your application or for a rule type.
To export a list of all the unit test cases that are in your application, in the header of Dev Studio, click
Configure Application Quality Automated Testing Unit Testing Test Cases .
To export a list of Pega unit test cases that are configured on a rule form, click Test Cases in the rule
form.
2. Click Export to Excel.
Related Content
Article
PegaUnit testing
Article
Viewing test details and results on the Application:Unit testing landing page
You can run test cases whenever code changes are made that might affect existing functionality. For example, an
account executive wants to ensure that a 10% discount is applied to all preferred customers. You create a test
case that verifies that this discount is applied to all preferred customers in the database. The test case test fails if
there are any preferred customers for which the 10% discount is not applied. You then add a new preferred
customer to the database and run the test case to make sure that the customer is correctly configured to receive
the discount and that the discount for other preferred customers is not affected.
Additionally, you can group related unit test cases into a test suite so that you can run multiple test cases and
suites in a specified order. For example, you can run related test cases in a regression test suite when changes
are made to application functionality. For more information about test suites, see Grouping test cases into suites.
After you create test cases and test suites, you can run them in a CI/CD pipeline for your application by using
Deployment Manager or a third-party automation server such as Jenkins. For more information, see
Understanding continuous integration and delivery pipelines.
Activities
Declare expressions
Case types
Flows
Collections
Map values
Data pages
Report definitions
Data transforms
Strategies
Decision tables
When
Decision trees
Typically, you unit test a rule, and then convert it to a test case. For flow and case type rules, you record the test
case.
For most rules, you can create a reusable test case by converting a unit test to a test case, configuring case
details, and then defining expected test results with assertions (test conditions). When the test case runs,
the test results are compared to the expected results defined for the rule’s assertions. If the test results do
not meet the defined assertions, then the test fails.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
When you create a unit test case for a flow or case type, you run the flow or case type and enter data for
assignments and decisions. The system records the data that you enter in a data transform, which is created
after you save the test form. You can start recording at any time.
You can view a list of the unit test cases that have been created for your application and select the one that
you want to open.
After you run a unit test case, you can view the results of the test run.
You can export a list of all the unit test cases that are in your application or configured on a rule form.
Related Content
Article
Running test cases and suites with the Execute Tests service
Article
Certain conditions apply on the data that you can record for flow and case types. For information, see Data that
you can record for flows and case types about the data that you can record.
Before you begin: Exclude properties in your work class from the test by modifying the
pxCapturePropertyIgnore data transform. For more information, see Excluding work class properties from form
and case type tests.
3. Click Create test case in the lower-right of the screen to save the recording as a test case.
4. Click Save, enter a label that identifies the test case, and then click Submit.
5. Optional:
To modify the rule or class that is used for the test, in the upper-right corner of the Definition tab, click the
Gear icon, select the rule or class, and then click Submit.
6. Optional:
To prevent the test from being run as a part of a test suite or from a REST service, on the Definition tab,
select the Disable check box.
The test case will be run only when you manually click Actions Run .
7. In the Expected results section, add assertions that define the expected results of the test. For more
information about creating assertions, see Defining expected test results with assertions.
8. On the Setup & Cleanup tab, configure the actions to perform and the objects and clipboard pages to be
available before and after the test runs. You can also clean up the clipboard after the test is run by applying
additional data transforms or activities. For more information, see Setting up and cleaning the context for a
test case or test suite.
9. Click Save.
10. Configure the unit test case. See Creating unit test cases for rules for more information.
Result:
After you save the test case, a data transform, which captures the input that you entered, is created and
associated with the test case. You can edit this data transform to modify the test case input. The Edit test case
form also displays the path of the flow or case type.
Data that you can record for flows and case types
When you create a unit test case for a flow or case type, the system records the data that you enter.
Excluding work class properties from form and case type tests
Exclude properties in your work class from the test by modifying the pyDataCapturePropertyIgnores data
transform.
Related Content
Article
Article
Article
Data that you can record for flows and case types
When you create a unit test case for a flow or case type, the system records the data that you enter.
Starter flows. Non-starter flows may be tested from a starter flow that calls on the non-starter flow.
When a flow or case type runs, a pyWorkPage is created on the clipboard and captures information such as
data that you enter for assignments. It also captures information such as case ID, date and time that the
case was created, and the latest case status.
There are additional assertions that you can configure for flows and case types, including case status,
assigned to, and attachment exists. For these assertions, the system compares expected values to the value
that is recorded on the pyWorkPage.
If you refresh or cancel recording the flow or case type, data that is on the pyWorkPage might not be
accurate.
Local actions and flow actions that are configured as part of the flow or case type.
Child cases that are created and finish running before the flow or test case resumes running.
Related Content
Article
Some properties, like .pyID, are not processed when a Pega unit test case is run. These properties vary for every
test run. The pxDataCapturePropertyIgnore data transform displays the properties that Pega unit tests do not
process.
a. In the navigation pane click App Classes , and enter Work- in the Search field.
b. Expand Data Model > Data Transform and then click pyDataCapturePropertyIgnores.
2. Save the data transform to your Work- class and in your test ruleset.
3. For each property that you want to exclude in the data transform, do the following steps:
c. In the Target field, enter the property that you want to exclude.
d. In the Source field, enter two double quotation marks, separated by a space: " " .
When a test runs, it applies assertions in the order that you define them on the Definition tab of the test case. All
assertions, except for run time assertions, must pass for the test to be successful.
For example, an account executive wants to ensure that a 10% discount is applied to all preferred customers. You
can create a test case that verifies that this discount is applied to all preferred customers in the database. If the
test does not pass, the results indicate where the 10% discount is not applied.
Note: On decision trees and decision rules, you cannot configure properties from a read-only data page or a data
page that is a declarative target.
You can verify that an activity returns the correct status when it runs by configuring an activity status
assertion. You can also assert if an activity has an error and, if it does, what the message is so that you can
validate that the message is correct.
For flows and case types, you can use the assigned to assertion to verify that an assignment is routed to the
appropriate work queue or operator.
For flows and case types, you can verify that the flow or case type has an attachment of type file or note
(attached using the Attach Content shape) or email (attached using the Send Email shape) attached.
For flows and case types, you can verify the number of cases that were created when the case type or flow
was run.
You can configure a case status assertion on a flow or case type to verify the status of the case.
Configuring decision result assertions
After you create a unit test case for a decision table or decision tree, the system generates a decision result
assertion. This assertion displays the input values for testing the rule, and the result that is generated by the
rule.
You can create an assertion for the expected run time of the rule. The expected run-time assertion is less
than or equal to an amount of time that you specify, in seconds.
You can create list assertions for page lists on a rule to determine if either the expected result is anywhere
in the list of results returned by the rule. Even if the order of results changes, the test will continue to work.
Some rules, such as activities and data transforms, can create or remove pages from the system. You can
create page assertions to determine whether or not a page exists after a unit test case runs. You can also
assert if a property has an error and, if it does, what the message is so that you can validate that the
message is correct.
You can configure property assertions to validate that the actual values of properties returned by a rule are
the expected values. You can also assert if a property has an error and, if it does, what the message is so
that you can validate that the message is correct.
You can configure assertions to compare the number of items returned in a page list, page group, value list,
or value group on the rule to the result that you expect to see on the clipboard.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
3. In the Value list, click the status that you expect the activity to return when the test runs.
4. To validate the message that displays for the activity, select Validate message, select a Comparator, and
then enter the message that you want to validate in the Value box.
5. Optional:
To add a comment, click the Add comment icon, enter a comment, and then click OK.
6. Click Save.
Related Content
Article
Article
Article
If you have multiple assignments on a flow or test case, you can route each assignment to an operator ID or work
queue. Clipboard pages are created for each assignment under the pyWorkPage page and capture the
assignment details, including the operator ID or work queue to which the assignment was routed. The assigned to
assertion compares the operator ID or work queue to the last assignment that is configured on the flow or case
type, which depends on where you stop recording the flow or case type.
For example, your flow has a Customer Details assignment, which is routed to the operator ID johnsmith . It also has a
subprocess with an Account Information assignment, which is routed to the account_processing work queue.
If you record only the Customer Details assignment, the assigned to value is johnsmith . If you also record the Account
Information assignment, the assigned to value is account_processing .
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
5. In the Value field, press the Down Arrow key and select the operator ID or work queue.
6. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
7. Click Save.
Related Content
Article
Article
Article
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
3. From the Attachment type list, select one of the following options, and then provide the value for each field:
File: Select to specify that the attachment type is file, and then enter the following values:
Description: Enter the text that was provided as the description in the Attach Content shape.
Name: Enter the name of the file that was provided in the Attach Content shape.
Note: Select to specify that the attachment type is note, and then enter text that was entered as the
note description in the Attach Content shape.
Email: Select to specify that the attachment type is an email, and then enter the email subject that was
provided in the Send Email shape.
5. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
6. Click Save.
On case types and flows, you can test whether an attachment of type file or note, which were attached in the
Attach Content shape, or email, which was attached using the Send Email shape, exists.
Related Content
Article
Article
Article
Article
Article
If you have multiple attachments on a flow or test case that match the expected value of the assertion, the
assertion runs for every attachment that exists. If the system finds an attachment that matches the assertion
value, the assertion passes and iterates over all the attachments on the flow or case type. If no attachment
exists, the assertion fails
The system compares the expected output on attachments that are recorded on the pyWorkPage page. For
example, if a case type has a parent case that spins off a child case, and you record just the child case, the
pyWorkPage page records attachments for only the child case and not the parent case, which is recorded on the
pyWorkCover page.
In addition, if you create a test case from a parent case that generates a child case that is returned to the parent
case after the child case runs, the pyWorkPage page records the attachments only on the parent case.
For example, your case has an Attach Content shape that attaches a Process immediately note in the first stage of the
case type. In the third stage, your case has a Send Email shape that attaches an email with the subject Request
approved. The assertion passes if you searched for either the Process immediately note or Request approved email subject.
Related Content
Article
Article
Article
Attaching content to a case
Article
For example, a Job Application case type runs a child case that processes background checks. If you record the
entire Job Applicant case type and the child case type, the number of case instances for Job Application case type
is one, and the number of case instances of Background Check child case type is one.
If you do not run the run the Background Check child case type when you create the test case, the number of
Background Check case instances is zero.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
To select a case type from your work pool, press the Down Arrow key and select the case type.
Enter a case type that is not part of your work pool.
5. In the Value field, enter the number of cases to compare against the output.
6. Optional:
Click Add to add another case instance count assertion and repeat steps 4 through 6.
7. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
8. Click Save.
Related Content
Article
Article
Article
If you have multiple assignments on a flow or case type, you can configure a case status on each assignment. The
pyWorkPage on the clipboard captures the latest case status, which depends on where you stop recording the
flow or case type.
For example, your flow has a Customer Details assignment, with the case status set as New. It also has a subflow with
an Account Information assignment, with the case status set as Pending.
If you record only the Customer Details assignment, the case status, which is captured in the .pyStatusWork property
on the pyWorkPage, is set to New. If you also record the Account Information assignment, the case status is set to
Completed.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
4. In the Value field, press the Down Arrow key and select the case status.
5. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
6. Click Save.
Related Content
Article
Article
Article
You can manually update the input values, add properties, remove properties, and modify the default decision
result if the test is modified.
Note: This assertion is supported on when rules, decision tables, and decision trees only.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
2. To add multiple input values and results to the assertion, or add other assertions, perform one of the
following actions:
Note: You can add multiple input values and results to this assertion but cannot add other assertion types to
this test case. You can add other assertion types to this test case only if you have a single input and result
entry for the assertion.
To add multiple input values and results to the assertion:
1. Select the Multiple input combinations check box.
2. Enter values for the input and result that you expect the assertion to generate when the test stops
running.
3. Click Add and enter values for each additional input and result that you want to test.
To use one input value and result, enter the values that you expect the assertion to generate when the
test stops running. You can then add additional assertions to the test case.
3. To update the assertion to reflect properties that were added to the rule, click Refresh.
Note: Refresh updates the assertion with properties that are added to the rule. If properties have been
removed from the rule, then you need to manually remove the properties from the assertion.
4. Add or remove properties by clicking Manage properties and then entering the changes. You need to enter
data for properties that were added to the rule.
Result: The properties are reflected as unexpected results in test case results.
5. In the rule form, click Save.
Result:
The test case runs the decision tree or decision table with each input combination and compares the result
with the expected decision result for that combination.
Other decision result combinations or other configured assertions then run. If the expected result of any of
the input combinations in the decision result assertion does not match the result that the rule returns, the
assertion fails.
Related Content
Article
Article
Article
An actual run time that is significantly longer than the expected run time can indicate an issue. For example, if
you are using a report definition to obtain initial values for a data page from a database, there might be a
connectivity issue between the application and the database.
By default, after you create a Pega unit test case for a data page, the system generates the expected run-time
assertion. The default value of the expected run time is the time that is taken by the rule to fetch results when
the test was first run. The system compares that time against future run-time tests.
You can change the default value and configure expected run time assertions for all rule types.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
3. In the Value field, enter a value, in seconds, that specifies the amount of time within which the execution of
the rule should be completed.
4. Optional:
If you want the test case to fail when the rule is not run within the specified time, select the Fail the test case
when this validation fails check box.
5. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
6. Click Save.
Related Content
Article
Article
For example, you can verify if a product is present in a product list in a data page, regardless of where the
product appears in the list results. You can also verify if there is at least one employee with the name John in the
results of the Employee list data page.
You can also configure assertions for page lists to apply assertions to all the results that are returned by a rule so
that you do not have to manually create assertions for each result in the list.
For example, you can verify that a department name is Sales and that a department ID starts with SL for each
department in the list of results in the Sales department data page. You can also verify if a discount of 10% is
applied to each customer in the list of results of the VIP customers data page.
You can configure list assertions for page lists on a rule to apply assertions to all the results that are returned by
the rule. Configure an ordered list assertion so that you do not have to manually create assertions for each result
in the list.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
b. If you are adding properties for flows, case types, decision trees, decision tables, or data pages:
1. In the of object field, enter the path of the object with which the properties are compared during
the assertion. Proceed to step d.
c. If you are adding properties for data transforms or activities, complete the following tasks:
1. From the Thread list in the Actual results section, select the thread that contains the page whose
properties or pages you want to add. In the Page field, enter the page whose properties or pages
you want to add.
2. In the of object field, enter the path of the object with which the properties are compared during
the assertion.
3. Proceed to step d.
d. Select the properties or pages that you want to add. You can search for a property or its value by
entering text in the search bar and pressing Enter.
If you select a page, all embedded pages and properties from the page are added. Added properties are
displayed in the right pane.
When you add multiple properties, the assertion passes if the expected output and results match for all
properties.
4. Optional:
In the Filter field, enter a property and value on which to filter results or open the Expression Builder by
clicking the Gear icon to provide an expression that is used to filter results. The list assertion applies only to
the page list entries that are specified for this filter value.
5. From the Comparator list, select the comparator that you want to use to compare the property with a
specified value.
Select the is in comparator to compare a text, integer, or decimal property to multiple values. The assertion
passes if the property matches any of the values that you specify.
6. In the Value field, either enter a value with which to compare the property or open the Expression Builder by
clicking the Gear icon to enter an expression that is used to provide the value.
Note: The Gear icon is not displayed until after you have saved the rule form.
7. To add a comment, click the Add comment icon, enter a comment, and click OK.
8. Click Done.
9. Click Save.
Result:
When you run the test case, the system searches for the specified properties in the page list. One of the following
occurs:
If you selected In ANY Instance, the assertion passes if all the properties in the set match the expected
values in the page list. If none of the properties match any of the values in the page list, the assertion does
not pass.
If you selected In ALL instances, the assertion passes if all the properties in the set match the expected
values in every entry in the page list. If any of the properties do not match any entry in the page list, the
assertion does not pass.
Related Content
Article
Article
Article
Article
You can configure page assertions for embedded pages, data pages, data pages with parameters, and embedded
pages within data pages that either have or do not have parameter stop-level pages.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
4. In the Comparator list, select the comparator that you want to use to compare the property with a specified
value:
To ensure that the page is created after the unit test runs, select exists. The assertion passes if the
system does not find the page.
To ensure that the page is removed after the unit test runs, select does not exist. The assertion passes
if the system does not find the page.
To ensure that the page has an error after the unit test runs, select has errors. The assertion passes if
the system finds errors on the page.
To ensure that the page is free of errors after the unit test runs, select has no errors. The assertion
passes if the system finds no errors on the page.
To ensure that the page has a specific error message after the unit test runs, select has error with
message and then enter the message in the Value box or click the Gear icon to build an expression. The
assertion passes if the page contains the complete error message.
To ensure that the page has a portion of an error message after the unit test runs, select has error
message that contains and then enter the message in the Value box or click the Gear icon to build an
expression. The assertion passes if the page contains the words or phrases in the error message.
5. Optional:
To add another page to the assertion, click Add pages, and then perform steps 3 through 4.
6. Optional:
To add a comment, click the Add comment icon, enter a comment, and then click OK.
7. Click Save.
For example: An activity runs every week to check the last login time of all operators and deletes any operator
record (page) from the system if the last login was six months ago. When you test this activity, you can:
1. Set up the clipboard to load an operator page that has the last login time as six months ago.
2. Create a page assertion that ensures that the page no longer exists after the activity runs.
Page assertions
You can configure page assertions to determine if a page exists on the clipboard or if a page has errors.
Related Content
Article
Article
Article
Page assertions
You can configure page assertions to determine if a page exists on the clipboard or if a page has errors.
Embedded pages
Data pages
Data pages with parameters
Embedded pages within data pages that either have or do not have parameters
Top-level pages
For example, an activity runs every week to check the last login time of all operators and deletes any operator
record (page) from the system if the last login was six months ago. When you test this activity:
Set up the clipboard to load an operator page that has the last login time as six months ago.
Create a page assertion that ensures that the page no longer exists after the activity runs.
Related Content
Article
Article
For example, you can create an assertion that verifies that a customer ID, which appears only once on a data
page, is equal to 834234.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
2. In the Assertion type list, select Property, and then click Add properties.
For data transforms, activities, flows, or case types, in the Actual results section, select the page
containing the properties to add.
For other rules, select the property or page that you want to add.
Result: Properties are displayed in the righte pane. If you selected a page, then all embedded pages and
properties from the page are added.
4. To add another property or page, click Add row, and then repeat step 3.
Result:
When you add multiple properties, the assertion passes if the expected output and results match for all
properties.
5. In the Comparator list, select the comparator that you want to use to compare the property with a specified
value. Do one of the following:
Select the is in comparator to compare a text, integer, or decimal property to multiple values. The
assertion passes if the property matches any of the values that you specify.
Select the is not in comparator. The assertion passes if the property does not match any of the values that
you specify.
Select the has error with message comparator to verify that the property has the exact message that you
specify in the Value box.
Select the has error message that contains comparator to verify that the property has a portion of the message
that you specify in the Value box.
6. In the Value field, enter a value with which to compare the property. Separate values for the comparators by
using the pipe (|) character. For text properties, use double quotation marks at the beginning and end of the
value, for example, "23|15|88" .
For example:
For example, if you want the assertion to pass when Age property matches either the 5 or 7 values,
configure the assertion as .Age is in 5|7 .
7. Optional:
To add a comment, click the Add comment icon, enter a comment, and then click OK.
8. Click Save.
Related Content
Article
Article
Article
For example, you can create an assertion that verifies that the number of returned results for the number of
employees is greater than X number of employees, less than Y number of employees, or equal to Z number of
employees.
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
a. In the Page field, enter the page that contains the property for which you want to test the result count.
b. In the Page class field, select the class to which the page belongs.
3. In the of object field, enter the path of the object with which the results are compared or counted against
during the assertion.
In the Filter field, enter a property and value on which to filter results or open the Expression Builder by
clicking the Gear icon to provide an expression that is used to filter results. The list assertion applies only to
the page list entries that are specified for this filter value.
6. In the Value field, enter the value that you want to compare with the object.
7. Optional:
To add a comment, click the Add comment icon, enter a comment, and click OK.
8. Click Save.
Result:
When you run the test case, the assertion fails if the expected value does not match the result count returned
from the page list, page group, value list, or value group.
Related Content
Article
Article
Article
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
You can view a list of the unit test suites that have been created for your application and select the one that
you want to open.
You can run a unit test suite to validate rule functionality by comparing the expected value to the output
produced by running the rule. Test cases are run in the order in which they appear in the suite.
After you run a unit test suite, you can view the test run results. For example, you can view the expected and
actual output for assertions that did not pass.
You can add test cases to a unit test suite. When you run a test suite, the test cases are run in the order in
which they appear in the suite.
After you run a unit test suite, you can view the test run results. For example, you can view the expected and
actual output for assertions that did not pass.
Related Content
Article
Article
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Test Suites .
3. Optional:
In Description, enter information that you want to include with the test suite. For example, enter information
about when to run the test suite.
4. In the Category list, click the type of scenario test suite you are creating:
Provide a value, in seconds, that specifies the length of time within which the run time of the suite should
complete in the Expected max runtime field. If you want the test suite to fail when the expected run time has
been exceeded, select the Fail the test suite when runtime validation fails check box.
6. Add unit tests cases or other test suites to the test suite:
To add test cases to the test suite, in the Test cases section, click Add, select the test cases to include
in the suite, and then click Add.
To add test suites to the test suite, in the Test suites section, click Add, select the test suites to
include in the suite, and then click Add.
Note: To filter information by multiple criteria, click the Advanced filter icon.
7. Optional:
To change the order in which the test cases or test suites run, drag them to a different position in the
sequence.
a. Click Save and then enter a Label that describes the purpose of the test suite.
Note: Pega Platformautomatically generates the Identifier based on the label you provide. The
identifier identifies the scenario test suite in the system. To change the identifier, click Edit. The
identifier must be unique to the system.
b. Optional:
In the Context section, change details about the environment in which the test suite will run. You can:
Change the development branch in which to save the scenario test suite.
Select a different application for which to run the scenario test suite.
Select a different ruleset in which to save the scenario test.
9. Click Save.
Remove test cases or suites from the test suite by selecting them and clicking Remove.
Apply one or more data pages, data transforms, or activities to set up the clipboard before running a
test suite in the Setup section of the Setup & Cleanup tab. You can also create objects, load work and
data objects, and add user pages from the clipboard which will be available on the clipboard when
running the test suite. For more information, see Setting up your test environment.
Apply additional data transforms or activities to clean up the clipboard in the Cleanup section of the
Setup & Cleanup tab. You can also prevent the test data from being removed after the test suite runs.
For more information, see Cleaning up your test environment.
Run a configured test suite by clicking Actions Run .
Note: If you made changes to the suite, such as adding or removing test cases or test suites, save
those changes before running the suite. Otherwise, the last saved version of the suite will run.
View more details about the latest result by clicking View details in the banner. Viewing details is
possible after a test suite runs. For more information, see Viewing unit test suite run results.
To view historical information about previous test runs, such as test date, the run time, expected run
time, and whether test passed or failed, click View previous runs.
11. Click Save. If you are saving the form for the first time, you can modify the Identifier. After you save the rule
form, you cannot modify this field.
Related Content
Article
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Test Suites .
2. In the Test suite name column, click the test suite that you want to open.
Related Content
Article
Article
Viewing test details and results on the Application:Unit testing landing page
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Test Suites .
2. Select the check box for each test suite that you want to run.
3. Click Run selected. The test cases run, and the Result column is updated with the result, which you can click
to open test results.
You can stop the test run by clicking Stop test execution.
Note: The test suite continues to run even if you close or log out of the Pega Platform, close the Automated
Testing landing page, or switch to another Dev Studio tab.
Related Content
Article
Viewing test details and results on the Application:Unit testing landing page
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Test Suites .
2. In the Run history column, click View for the test suite that you want to view.
Note: To quickly view results of the most recent run, click the result in the Result column.
3. In the Test suite runs log dialog box, click the row for the instance of the test suite run that you want to
view to open the results of that run in a new tab in Dev Studio.
Note: You can also view test results after you run the test in the Edit Test Suite rule form.
Related Content
Article
Article
Viewing test details and results on the Application:Unit testing landing page
1. Optional:
Open the Pega unit test suite, if it is not already open.
3. In the Add test cases dialog box, select the test cases that you want to add to the test suite.
Note: You can click the Advanced filter icon to filter information by multiple criteria.
4. Click Add.
Related Content
Article
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Test Suites .
2. In the Run history column, click View for the test suite that you want to view.
Note: To quickly view results of the most recent run, click the result in the Result column.
3. In the Test suite runs log dialog box, click the row for the instance of the test suite run that you want to
view to open the results of that run in a new tab in Dev Studio.
Note: You can also view test results after you run the test in the Edit Test Suite rule form.
Related Content
Article
Article
Viewing test details and results on the Application:Unit testing landing page
Setting up and cleaning the context for a test case or test suite
You can set up the environment and conditions required for running a test case, determine how to clean up test
data at the end of the test run, and set pages on which to automatically run rules.
You can set clipboard pages, apply data transforms, load data pages, execute activities, create and load objects.
All the referenced data pages, and data objects and user pages that were created during a test run will be
automatically removed at the end of each run. To further clean up the clipboard, add steps to apply additional
data transforms and execute activities. You can set up or clean up the clipboard if you are running a test for which
the output or execution depends on other data pages or information.
For example, your application contains a data page D_AccountTransactionsList. This data page is sourced by a
report definition or activity that loads the transactions of the logged-in customer, based on the account type for
which the customer views transactions.
The customer number and account type that the customer selects are dynamic properties that are stored on the
work page of the case. The report definition or activity retrieves these properties as parameters from the work
page and filters the results as it obtains the results for the data page.
When you create a test case for D_AccountTransactionsList, ensure that one of the following conditions is met:
The parameter properties are on the work page of the clipboard before running the data page test.
Your data page has an activity or report definition that refers to the properties of another data page that is
on the clipboard to filter the results.
The system always runs data transforms, activities, and strategies on the RunRecordPrimaryPage page,
regardless of which page you chose when you unit tested the rule in the Run dialog box. The system also runs
flows and case types on the pyWorkPage. To update the page with any information required to set up test data,
click the Setup tab.
Configure which actions you want to run and which objects and pages you want to view on the clipboard
before, during, and after the test is run.
After you run a unit test case or test suite, user and data pages used to set up the test environment and the
parameter page are automatically removed by default. You can apply additional data transforms or activities
to remove other pages or information on the clipboard before you run more test cases or suites.
Related Content
Article
Article
Data pages
Article
Article
Data Transforms
Article
To set up the environment and conditions that are required before running this test case, copy or create clipboard
pages, apply data transforms, load data pages, execute activities, and create and load objects. Then, define the
connections to data pages or third-party databases to simulate during the test. Finally, after running the test case,
set up the environment and conditions that are required by applying data transforms, loading data pages,
executing activities, and creating and loading objects.
Before you begin: Open the test case or test suite that you want to set up. For more information, see Opening a
unit test case or Creating unit test suites.
2. Optional:
To make specific conditions available during test execution, expand the Before rule execution section, and
then configure the conditions:
To define simulation settings for the test, expand the Simulation section, and then configure the simulations.
For more information, see Simulating data pages and third-party connections.
4. Optional:
To make specific conditions available after test execution, expand the After rule execution section, and then
add additional clipboard data.
Note: You can set up actions after rule execution for test cases only.
5. To run the rule under on a page and avoid copying the entire page to RunRecordPrimaryPage, in the
Advanced section, enter the page under which you want to run the rule.
6. Click Save.
When setting up your test environment, you can set to copy or create clipboard pages before the test runs.
When setting up your test environment, you can add additional clipboad data before or after the test runs.
You can create apply data transforms, load data pages, execute activities, load objects, create data objects,
and create work objects.
When setting up your test environment, you can simulate data pages and third-party connections. Such
simulations let you run your tests without depending on the availability of third-party servers.
Related Content
Article
Clipboard tool
Article
Article
Data pages
Article
Article
Data Transforms
1. On the Setup & Cleanup tab for the test case or test suite for which you want to set up the context, expand
the Before rule execution section, and then expand the Setup data section.
3. In the Description box, enter a description of the clipboard page you want to copy or create.
4. Optional:
b. To copy a clipboard page from a different thread, click the current thread name, and then click desired
thread name.
c. Select the check box next to the page that you want to be available in the clipboard during test
execution, and then click Next.
d. Edit the clipboard page and then click OK. You can rename the parent page, modify the values of
existing properties or add new properties and their values to the parent page and child pages.
5. Optional:
b. In the Page Name field, enter a name of the page you want to create.
c. In the Class field, enter or select the class of the page you want to create.
d. Click Next.
e. Edit the clipboard page and then click OK. You can rename the parent page, modify the values of
existing properties or add new properties and their values to the parent page and child pages.
1. On the Setup & Cleanup tab for the test case or test suite for which you want to set up the context, choose
whether to add the data before or after the rule runs.
To add the data before the test rule runs, select Before rule execution section, expand the
Additional clipboard data subsection.
To add the data after the test rule runs, select After rule execution.
2. For each action you want to perform to the clipboard data, click Add step and then select the action.
To apply a data transform:, select Apply data transform, and then, in the Name field, enter or select the
name of the data transform to apply.
To load a data page, select Load data page, and then, in the Name field, enter or select the name of the
data to apply.
To execute an activity, select Execute activity, and then, in the Name field, enter or select the name of
the activity to apply.
To load an object, select Load object, enter or select the class of the object in the Of class field, and
then enter a name for the page in the Load on page field.
To create a data object, select Create data object, enter or select the class of the object in the Of class
field, and then enter a name for the page in the Load on page field.
To create a work object, select Create work object, and then, in the Of class field, enter or select the
class of the work object.
3. Optional:
If parameters are configured on rules, then you can modify them by clicking the gear icon, and providing
values in the Configure parameters dialog box, and then clicking Submit.
4. Optional:
If keys are configured on loaded or created objects, then you can define their values by clicking the With
Keys gear icon, and providing values in the Configure parameters dialog box.
3. In the Setup section, expand the Simulation section, and then click Add rules.
4. To include a rule that the test rule directly references, on the Referenced rules tab, select the rules to
simulate, and then click Add.
5. To include any rule that the test rule does not directly reference, do the following for each rule:
b. In the Rule type list, click the type of rule that you want to simulate.
c. In the Class box, enter the class of the rule that you want to simulate.
d. In the Rules field, enter the rule that you want to simulate.
The selected rules display in the Simulation section on the Setup & Cleanup tab.
6. In the Simulate with list for each rule, click a simulation method:
Select As defined in the rule to use the default simulation defined in the rule.
Select Select datatransform rule to define your own data transform rule. You can reuse this rule in other
test cases.
Select Define data here to manually provide test data specific to this particular test case. You can copy
pages from the clipboard or create new pages and populate them with required test data.
Select None to disable the simulation.
Related Content
Article
Article
Data Transforms
Article
Before you begin: Open the unit test case. For more information, see Opening a unit test case.
2. To keep the test data on the clipboard at the end of the test run, clear the Cleanup the test data at the end
of run check box in the Cleanup section.
4. Select Apply data transform or Execute activity, and then provide the appropriate data transform or activity
in the next field.
5. If parameters are configured on the rule, you can configure them by clicking the Parameters link and
providing values in the Configure parameters dialog box.
6. Optional:
Provide additional information in the Enter comments field.
7. Click Save.
After you run a unit test case or test suite, user and data pages used to set up the test environment and the
parameter page are automatically removed by default.
Related Content
Article
Article
Article
Note: You can override this behavior if you want the data from the current test to be available to the subsequent
tests.
You can also apply additional data transforms or activities to remove other pages or information on the clipboard
before you run more tests. Cleaning up the clipboard ensures that data pages or properties on the clipboard do
not interfere with subsequent tests. For example, when you run a test case, you can use a data transform to set
the values of the pyWorkPage data page with the AvailableDate, ProductID, and ProductName properties.
You can use a data transform to clear these properties from the pyWorkPage. Clearing these values ensures that,
if setup data changes on subsequent test runs, the test uses the latest information. For example, if you change
the value of the AvailableDate property to May 2018, you ensure that the data page uses that value, not the older
(December 2018) information.
Related Content
Article
Article
Setting up and cleaning the context for a test case or test suite
Article
Article
Data Transforms
By default, a test case is considered as executed if it ran in the last 7 days. You can change the number of days
for which a test can be considered executed on the Application: Quality Settings landing page. The overview also
includes the percentage of rules on which Pega unit test cases are configured. View Pega unit test reports to
check the quality of your application and identify rules that did not pass Pega unit testing.
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing Reports .
2. Optional:
To filter information by more than one criterion, click the Advanced filter icon.
3. Optional:
Generate and export a report for test coverage and test runs for a rule type.
a. For the rule type for which you want to export a report, click a number in the column of the table for
either pie chart.
b. Click Actions.
Related Content
Article
Article
Article
Viewing test details and results on the Application:Unit testing landing page
Article
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Unit Testing .
3. Optional:
Generate and export a report that contains a list of test cases that are not associated with any rules.
Related Content
Article
Article
Viewing test details and results on the Application:Unit testing landing page
Article
Running test cases and suites with the Execute Tests service
You can use the Execute Tests service (REST API) to validate the quality of your code after every build is created
by running unit test cases that are configured for the application.
A continuous integration (CI) tool, such as Jenkins, calls the service, which runs all the unit test cases or test suites
in your application and returns the results in xUnit format. The continuous integration tool interprets the results
and, if the tests are not successful, you can correct errors before you deploy your application.
When you use Jenkins, you can also use the Execute Tests service to run unit tests after you merge a branch on a
remote system of record and start a job. For more information, see Remotely starting automation jobs to perform
branch operations and run unit tests.
You can quarantine a test case by marking it Disabled. A disabled test case is not run by the Execute Tests
service. Test case quarantines prevent noncritical tests from running if they are causing failures so that the
service can continue to run.
Request parameters
Response
The service returns the test results in an XML file in xUnit format and stores them in the location that you
specified in the LocationOfResults request parameter.
When you run the Execute Tests service, you can specify the access group that is associated with the
application for which you want to run all unit test cases or a test suite. If you do not specify an access group
or application name and version, the service runs the unit test cases or test suite for the default access
group that is configured for your Pega Platform operator ID.
Configure your build environment so that it can call the Execute Tests service and run all the unit test cases
or a test suite in your application. Your configuration depends on the external validation engine that you use.
After you configure your validation engine, run the service and verify the test results. Your test suites and
test cases must be checked in so that you can run them.
Test failures
Test cases and suites that are run using Execute tests services can fail for a few reasons.
Request parameters
The Execute Tests service takes certain string request parameters.
ApplicationInformation – Optional. The name and version of the application for which you want to run Pega
unit test cases. You can pass it instead of the AccessGroup parameter.
If you pass only this parameter, the service runs all the test cases in the application.
If you do not pass this parameter, the service runs all the test cases in the application that are
associated with the default access group that is configured for your operator.
AccessGroup – Optional. The access group that is associated with the application for which you want to run
Pega unit test cases. You can pass it instead of the ApplicationInformation parameter.
If you pass this parameter, the service runs all the test cases in the application that are associated with
this access group.
If you do not pass this parameter, the service runs all the test cases in the application that are
associated with the default access group that is configured for your operator.
LocationOfResults – The location where the service stores the XML file that contains the test results. This
parameter is optional for test cases and test suites.
RunWithCoverage – Determines whether the application-level test coverage report is generated after the
Execute Tests service runs all relevant test cases or the selected test suite. For more information, see
Generating an application-level test coverage report.
If you set the parameter to False, the application-level test coverage report is not generated. This is the
default behavior.
If you set the parameter to True, and application-level coverage is not running, the Execute Tests
service starts application-level coverage mode, runs all unit tests, stops coverage mode, and generates
the application-level coverage report. This report is displayed on the test coverage landing page in the
Application level section.
If you set the parameter to True, and application-level coverage is already running, the Execute Tests
service returns an error.
Response
The service returns the test results in an XML file in xUnit format and stores them in the location that you
specified in the LocationOfResults request parameter.
<test-case errors="2" failures="0" label="Purchase order transformation with a bad element in the output
expected" name="report-bad-element-name" skip="0" tests="7"> <nodes expected="/" result="/"><nodes
xmlns:purchase="urn:acme-purchase-order" expected="/purchase:order[1]" result="/purchase-order[1]"><error
type="Local name comparison">Expected "order" but was "purchase-order"</error><error type="Namespace
URI comparison">Expected "urn:acme-purchase-order" but was ""</error></nodes></nodes><sysout>This text
is captured by the report</sysout><syserr/></test-case>
1. In the navigation pane of Dev Studio, click the Operator menu, and then click Operator.
2. In the Application Access section, select your default access group.
3. Selecting default access group configuration
4. Click Save.
For example, the following procedure describes how to configure the Jenkins server to call the service.
2. Install the HTTP request plug-in for Jenkins to call the service and the JUnit plug-in so that you can view
reports in xUnit format.
d. Specify whether to install the plug-in without restarting Jenkins or to download the plug-in and install it
after restarting Jenkins.
3. Configure the Pega Platform credentials for the operator who authenticates the Execute Tests service.
b. Click the drop-down arrow next to the domain to which you want to add credentials, and click Add
credentials.
c. In the Username field, enter the operator ID that is used to authenticate the service. This operator
should belong to the access group that is associated with the application for which you want to run test
cases and test suites.
e. Click OK.
b. In the Jenkins Location section, in the Jenkins URL field, enter the URL of the Jenkins server.
b. Click Configure.
c. In the Build section, click Add build step, and select HTTP Request from the list.
d. In the HTTP Request section, in the URL field, enter the endpoint of the service. Use one of the following
formats:
If you are using multiple parameters, separate them with the ampersand (&) character, for example,
http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests?
ApplicationInformation?=ApplicationInformation:<application_name:application_version>&TestSuiteID=
<pxInsName>
7. Click Advanced.
8. In the Authorization section, from the Authenticate list, select the Pega Platform operator ID that
authenticates the service that you configured in step 3.
9. In the Response section, in the Output response to file field, enter the name of the XML file where Jenkins
stores the output that it receives from the service. This field corresponds to the LocationOfResults request
parameter. In the Post-build Actions section, from the Add post build section list, select Publish Junit test
result report and enter **/*.xml in the Test Report XML field. This setting configures the results in xUnit
format, which provides information about test results, such as a graph of test results trends. These results
are displayed on your project page in Jenkins.
2. In the Build History pane, click the build that you ran.
4. In the All Tests section, click root. The results of all tests are displayed.
5. Optional:
Expand a test result in the All Failed Tests section and view details about why the test was not successful.
Test failures
Test cases and suites that are run using Execute tests services can fail for a few reasons.
The operator does not have access to the location of the results.
The access group that is passed by the service either does not exist or no access group is associated with
the operator ID.
The application name and version that are passed do not exist.
An application is not associated with the access group that is passed by the service.
No Pega unit test cases or test suites are in the application.
The test suite pxInsName does not exist for the application name and version or for the access group that is
passed by the service.
In addition, if you have the AutomatedTesting privilege, you can use Automated Unit Testing (AUT) and switch
between Pega unit testing and AUT, for example, if you want to view test cases that you created in AUT. The
following list describes the application behavior when you use Pega unit testing and AUT:
When you unit test activities that are supported by both Pega unit testing and AUT, the Run Rule dialog box
displays updated options for creating unit tests for Pega unit testing. However, you cannot create unit test
cases for AUT by using this dialog box.
When you use Pega unit testing, you can create, run, and view the results of Pega unit testing on the Test
Cases tab for the supported rule types.
You can view, run, and view the results of Pega unit test cases by clicking Dev Studio Automated Testing
Test Cases . You can also switch to the AUT landing page by clicking Switch to old version.
When you switch to the AUT landing page, you can create, run, and view the results of unit test cases for AUT
on the Test Cases tab for activities, data transforms, and data tables, which are supported by both Pega unit
testing and AUT. You can create unit test cases only by clicking the Record test case button and using the
older Run Rule dialog box.
In the Automated Unit Testing landing page, you can restore the Automated Rule Testing landing page by
clicking Switch to new version. When you click the Test cases tab in an activity, decision table, or decision
tree, the tab displays options for creating Pega unit test cases.
If you use the Automated Unit Testing landing page, and then log out of the system, Dev Studio displays the
Dev Studio Application Automated Unit Testing > menu option instead of the Dev Studio Application
Automated Testing > option. To return to the Automated Unit Testing landing page, click Switch to new
version on the Automated Unit Testing landing page.
Note: AUT has been deprecated and is not supported in the current version of Pega Platform. Switch to and use
AUT only if you have existing automated unit tests created with AUT. See PegaUnit testing more information.
To use AUT, your operator ID must have the AutomatedTesting privilege through an access role.
Switch from PegaUnit testing to AUT by clicking Configure Automated Testing Test Cases and clicking Switch
to old version on the Automated Unit Testing landing page.
Click the Test cases tab of the Automated Unit Testing landing page to display options for creating unit tests
for activities, decision tables, and decision trees.
If you are using the Automated Unit Testing landing page and then log out of the system, you can click
Configure Application Automated Unit Testing , and then click Switch to new version to restore the
Automated Testing landing page.
Note: If the underlying test case rule belongs to a ruleset that uses the check-out feature, you must
have the test case rule checked out to you before re-recording the test case.
Withdrawn test cases and suites are not displayed on the Automated Unit Tests tab.
If you ran a unit test against a saved test case for a decision table, decision tree, activity, or Service SOAP rule
and selected the All Cases option in the Run Rule form, those results also appear in the Dashboard tab.
For activity test cases, if the activity test case has an approval list, differences are reported only for pages and
properties on the list. If the test case has an approval list and the only differences are for pages and properties
not on the list, those differences are not reported. If differences are found for items on the approval list, you can
remove the item from the approval list for that test case.
If you do not want any emails sent, clear the Send Completion Email field.
5. Click OK.
By default, the Pega-AutoTest agents run scheduled unit test suites run every five minutes. When the suite is
finished, the agent activity sends an email with the results. By default, this email is sent to the operator who
requested the unit test suite run and to any email addresses listed in the Send Completion Email array. If no email
addresses appear in that field, no email message is sent.
You can automate testing of rules by creating test cases for automated unit testing. Automated unit testing
validates application data by comparing expected output to the actual output that is returned by running
rules.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
Related Content
Article
Article
Article
Viewing test details and results on the Application:Unit testing landing page
The Operator ID specified here is the default one used to run the unit test suite. When defining the unit test
suite's run schedule using the Schedule gadget of the Automated Unit Testing landing page, you have the option
to specify a different Operator ID and override the one specified here.
You can specify Test Cases in both the Rule Types To Include section and the Query Test Cases To Include
section of this form. If you specify Test Cases in both sections, when the unit test suite runs, those test cases
defined in the Rule Types To Include section will run before the test cases in the Query Test Cases To
Include section.
1. In the RuleSets for Test Cases field, select the RuleSet that holds the test cases you want to include in this
test suite.
If the test cases are in more than one RuleSet, click the Add icon to add rows to specify the additional
RuleSets.
2. In the User ID for Agent Processing field, select the Operator ID for the Pega-AutoTest agents to use by
default when they run this test suite.
This ID must provide access to the RuleSet that this test suite belongs to, as well as access to the RuleSets
listed in the RuleSets field.
3. Optional:
To specify that the work items created during the test case execution are to be deleted afterwards, select
the Remove Test Work Objects? check box.
The fields in the Application Test Cases To Include section provide options to specify the test cases by
application name and version.
4. In the Application Name fieldSelect the name of the application that has the test cases you want to include in
the unit test suite.
5. In the Application Version field, select the version of the application that has the test cases you want to
include in the unit test suite.
The fields in the Rule Types To Include section provide options to select the test cases by rule type. You
can specify that all the test cases for a particular rule type are included in this unit test suite, or you can
constrain the list with a When condition rule.
6. In the Rule Type field, select those rule types for which you want to include their test cases in this unit test
suite:
Activities
Decision Tables
Decision Trees
Flows
Service SOAP service records
Leave blank to include all the test cases that were created for rules of the type specified in the Rule
Type field.
The test cases that meet the conditions in the when condition rule are included in the unit test suite
The fields in the Query Test Cases To Include section provide options to select specific Test Cases to
include in this unit test suite. List the test cases in the order in which you want them to be run.
8. In the Test Case Name field, enter a search string for the test case you want to find.
9. To list test cases that match the query string in the Test Case Name field, click Query.
The list is not limited by RuleSet. If test cases exist that match the search string, the List Test Case window
appears. Select the test cases you want to include and then click OK. The test cases are added to the list in
this section of the form.
10. In the Test Case Key field, enter the three-part key of a Test Case rule.
Class Name
Instance Name (Ins Name)
Purpose
When you use the Query button to find and add a test case, the system automatically fills in this field.
11. In the Description field, enter the short description of the Test Case.
When you use the Query button to find and add a test case, the system automatically fills in this field.
12. In the RuleSet field, enter the RuleSet of the test case.
When you use the Query button to find and add a test case, the system automatically fills in this field.
Verify that this RuleSet is included in the RuleSets for Test Cases list at the top of this form. If the RuleSet for
the test case is not in that list, add it now. Otherwise, the Test Case does not run when the unit test suite
runs.
Related Content
Article
Article
UI testing
Perform UI-based functional tests and end-to-end scenario tests to verify that end-to-end cases work as expected.
Use the third party Selenium starter kit for CRM or the built-in scenario testing tool to perform the UI testing.
Pega provides Selenium-based UI test framework and sample UI tests that you can leverage to build up test
automation suite for your Pega application. These test frameworks are built with maintenance and best
practices in mind.
Run scenario tests against a user interface to verify that the end-to-end scenarios are functioning correctly.
The UI-based scenario testing tool allows you to focus on creating functional and useful tests, rather than
writing complex code.
The starter kit comes with a generic Selenium based UI test framework that you can use for creating UI page
objects and UI tests for your Pega application. It includes sample UI test framework to support testing core Pega
CRM applications – Pega Sales Automation, Pega Customer Services and Pega Marketing. The kit comes with out
of the box (OOTB) sample tests to validate real core use cases of those CRM applications. You can use this kit as
reference when creating your own UI page objects and end-to-end UI test scripts. The framework and tests are
Behavior Driven Development (BDD) based and leverage the Cucumber framework.
For more information, including guidelines on getting started, running, and writing UI tests, see Selenium Starter
Kit on Pega Marketplace.
You can test either a specific case type or an entire portal by clicking Scenario Testing in the run-time toolbar to
open the test recorder. When you use the test recorder and hover over a testable element, an orange highlight
indicates that the element can be tested. Interactions are recorded in a visual series of steps and the execution of
a test step can include a delay.
Provide data to your test cases with a predefined data page. This data page can provide unique values for each
execution of the test case. You can populate the data page by using any source, including activities or data
transforms.
Tests are saved in a test ruleset. After they are saved, tests are available on the Application: Scenario testing
landing page. From the landing page you can run a test or view the results of a previous test run.
Record a set of interactions for a case type or portal in scenario tests. You can run these tests to verify and
improve the quality of your application.
You can view a list of the scenario test cases that have been created for your application and select the one
that you want to open.
Group related scenario tests into test suites to run multiple scenario test cases in a specified order. You can
then run the scenario test suites as part of purpose-specific tests, such as smoke tests, regression tests, or
outcome-based tests. Additionally, you can disable or quarantine individual scenario tests for an application
so that they are not executed when the test suite runs.
The scenario testing landing page provides a graphical test creation tool that you can use to increase test
coverage without writing complex code.
Before you begin: Create a test ruleset in which to store the scenario test. For more information, see Creating a
test ruleset to store test cases.
In App Studio, on the lower-left side of the screen, click the Test icon.
In Dev Studio, on the lower-right side of the screen, toggle the run-time toolbar, and then click the
Toggle Automation Recorder icon.
3. In the Scenario tests pane, click Create test case, and then select the test type:
4. Record the steps for the test by clicking the user interface elements.
Result: When you hover over a testable element, an orange highlight box appears. When you click an
element, you record an implicit assertion and add the interaction to the list of test steps.
5. Optional:
b. Click the Mark for assertion icon on the orange highlight box.
d. Define the assertion by completing the Name, Comparator, and Value fields.
6. When you finish adding steps, in the Test case pane, click Stop and save test case.
b. In the Context section, select a branch or ruleset in which you want to save the test.
c. In the Apply to field, enter the name of a class that is relevant to the test.
d. Click Save.
Result: The test case appears on the Scenario testing landing page.
Related Content
Article
Article
1. In the navigation pane of Dev Studio, click Configure Application Quality Automated Testing Scenario Testing
Test Cases .
2. In the Test case name column, click the test case that you want to open.
Related Content
Article
To create a scenario test suite, add scenario test cases to the suite and then specify the order in which you
want the tests to run. You can also modify the context in which to save the scenario test suite, such as the
development branch or the ruleset.
Unit Test Suites identify a collection of Test Cases and their rulesets, and a user (Operator ID) whose
credentials are used to run the Unit Test Suite. Unit Test Suites are used to automatically run groups of test
cases together and make unit testing more efficient.
Run scenario test suites to check application functionality. You can check the run history, add or remove test
cases from the suite, or reorder the test cases before running the suite.
After you run a scenario test suite, you can view the test results. For example, you can view the expected
and actual output for assertions that did not pass.
Related Content
Article
Article
When the test suite runs, the test cases run in the order that they are listed. You can reorder cases only on the
page in which they display and cannot move cases or suites from one page to another.
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Scenario Testing Test
Suites .
3. Optional:
In Description, enter information that you want to include with the test suite. For example, enter information
about when to run the test suite.
4. In the Category list, click the type of scenario test suite you are creating:
5. In the Scenario test cases section, click Add, select the test cases you want to add to the suite, and then click
Add.
Note: To filter information by multiple criteria, click the Advanced filter icon.
6. Optional:
To change the order in which the test cases run, drag the case to a different position in the sequence.
a. Click Save and then enter a Label that describes the purpose of the test suite.
Note: Pega Platformautomatically generates the Identifier based on the label you provide. The
identifier identifies the scenario test suite in the system. To change the identifier, click Edit. The
identifier must be unique to the system.
b. Optional:
In the Context section, change details about the environment in which the test suite will run. You can:
Change the development branch in which to save the scenario test suite.
Select a different application for which to run the scenario test suite.
Change the class to apply to the scenario test suite.
Select a different ruleset in which to save the scenario test.
c. Click Submit.
Related Content
Article
Article
Article
Article
1. In the header of Dev Studio, click Configure Application Quality Automated Testing Scenario Testing Test
Suites .
2. Optional:
To view more information about the latest test results, click View details.
To view information about earlier results, click View previous runs.
c. Modify the test cases in the suite from the Scenario test cases section.
To remove test cases from the suite, click Remove, and then click Save.
To include additional test cases in the suite, click Add, select the test case, click Add, and then
click Save.
d. To change the order in which the test cases will run, drag a case to a different position in the sequence
and then click Save.
e. To prevent individual test cases from running as part of the suite, select the case, click Disable, click
Save, and then close the test case.
f. Close the test suite, return to the Application: Scenario testing page, and then click Actions Refresh .
3. Optional:
To view details about previous test results, click View in the Run history column.
4. Select the check box for each test suite that you want to run and then click Run selected. The test suites run
and the Result column is updated with the result, which you can click to open test results.
Related Content
Article
Article
Article
Article
Article
2. To view results of the most recent run, click the result in the Result column. For information about why a test
failed, click Failed in the Result column.
3. To view historical details about a specific test suite, in the Run history column, click View.
Related Content
Article
Article
Article
Article
Article
On the scenario testing landing page, you can view and run scenario test cases. By viewing reports, you can also
identify case types and portals that did not pass scenario testing.
On the scenario testing landing page, you can perform the following tasks:
View test execution and coverage information for case type tests and portal tests.
Open a test case rule where you can add assertions to your test.
View the results of the most recent test run.
Select and run individual test cases, or group tests into test suites that you can use to run multiple tests in a
specified order.
Download a list of tests, their type, the name of a portal or case that is tested, and the time and the result of
the last run.
Related Content
Article
Article
With Deployment Manager, you can fully automate your CI/CD workflows, including branch merging, application
package generation, artifact management, and package promotion to different stages in the workflow. You can
download Deployment Manager for Pega Platform from the Deployment Manager Pega Marketplace page.
For answers to frequently asked questions, see the Deployment Manager FAQ page.
Deployment Manager release notes
These release notes provide information about enhancements, known issues, issues related to updating from
a previous release, and issues that were resolved in each release of Deployment Manager.
Deployment Manager is a simple, intuitive, and ready-to-use application that offers built-in DevOps
capabilities to users. It leverages Pegasystems’s market-leading case management technology to manage an
automated orchestration engine, enabling you to build and run continuous integration and continuous
delivery (CI/CD) pipelines in a model-driven manner.
Use Deployment Manager to configure and run continuous integration and delivery (CI/CD) workflows for
your Pega applications from within Pega Platform. You can create a standardized deployment process so
that you can deploy predictable, high-quality releases without using third-party tools.
Follow these best practices when you use branches in your Deployment Manager pipelines. The specific
practices depend on whether you have a single development team or multiple development teams in a
distributed environment.
In Deployment Manager 4.4.x and later, you can package and deploy test cases separately on the candidate
systems in the pipeline. When you configure a pipeline in Deployment Manager, you specify the details of
the test package that you want to deploy, including the stage in the pipeline until which you want to deploy
the package.
In Deployment Manager 3.1.x and later, you can create custom repository types to store and move your
artifacts. For example, you can create a Nexus repository and use it similarly to how you would use a Pega
Platform-supported repository type such as file system. By creating custom repository types, you can extend
the functionality of Deployment Manager through the use of a wider variety of repository types with your
artifacts.
You can use Deployment Manager 4.x if Pega Platform 7.4 is installed on your candidate systems
(development, QA, staging, and production). You can use many of the latest features that were introduced in
Deployment Manager 4.x, such as managing your deployments in a dedicated portal.
Use Deployment Manager to configure and run continuous integration and delivery (CI/CD) workflows for
your Pega applications from within Pega Platform. You can create a consistent deployment process so that
you can deploy high-quality releases without the use of third-party tools.
The Deployment Manager releases for the corresponding versions of documentation are no longer available
to be downloaded from Pega Marketplace.
For answers to frequently asked questions, see the Deployment Manager FAQ page.
Deployment Manager 4.8.1 includes the following enhancements and resolved issues:
Deployment Manager 4.6.1 includes the following enhancements and resolved issues.
Deployment Manager 4.5.1 includes the following enhancements and resolved issues.
Deployment Manager 4.4.1 includes the following enhancements and known issues.
Deployment Manager 3.3.1 includes the following enhancements and known issues.
Deployment Manager 1.1.2 includes the following known and resolved issues.
Enhancements
The following enhancements are available in this release:
Asses application security by using the enhanced Pega Security Checklist task
With the Pega Security Checklist, you can easily secure your applications and systems in one convenient
area of Pega Platform™. The Security Checklist:
Performs a detailed assessment of your current security configuration to determine whether the
settings follow best practices for application development.
Provides a status on each task in the Security Checklist page and blocks your application deployment if
any task fails.
Stores an audit trail of the security configuration analysis and status at the time of deployment.
With Deployment Manager 4.8, you can now use Deployment Manager pipelines for deploying application
revisions. If you choose not to migrate your deployments to a DevOps pipeline, Revision Manager remains
backward compatible.
Deployment Manager service administrators can now create or edit authentication profiles in the
Deployment Manager UI instead of accessing profiles in Dev Studio.
Application-level rollbacks now provide a more granular approach to restore points, which you can use to
revert rules and data instances in a specific application. This feature requires Pega Platform 8.4 and later.
You can now trigger deployments by using production-ready artifacts from a previous production
deployment. Two new fields, Pipeline and Deployment, replace the existing fields, Select a repository
and Select an artifact, to provide a more efficient deployment approach and eliminate repository
interactions from Orchestrator.
The Deployment Manager UI for updating application dependencies is now read-only for pipelines that are
created in versions 4.7 and earlier. This functionality supports client migrations to the new deployment-
centric method of dependency configuration.
You can now add Jenkins tasks to the Continuous Integration (CI) phase of a deployment pipeline. For a list of
available parameters for a Jenkins task in CI, see the Configuring Jenkins documentation.
Deployment manager now blocks deployments in systems with a production level of 5 if the artifact contains
draft flows. If the production level is lower than 5, a warning message is displayed in the Deployment History
and Reports section, which indicates that draft flows might cause production failures.
You can now stop all the ongoing deployments for a pipeline at once. Stop all deployments to quickly
troubleshoot issues and resolve failed pipelines.
You can now use a self-service chatbot to obtain troubleshooting tips and more information about common
Deployment Manager issues. When you search for information, the chatbot provides you with answers and
links to more information.
Deployment Manager now provides enhanced diagnostics so that you can troubleshoot more issues. You
receive warnings if you are using the defaultstore repository or Pega type repository in any environment.
Start another pipeline by using the Trigger deployment task in an active pipeline, which allows you to
add pipeline stages.
Stop a deployment if a Jenkins task in the pipeline fails.
Archive inactive pipelines. By default, archived pipelines do not appear in the Deployment Manager
interface.
Temporarily disable pipelines that frequently fail to prevent additional deployments on the pipeline.
Start a new test coverage session for the Enable test coverage task every time you run a pipeline.
Starting a new session prevents deployments from failing if a test coverage session is already running
on the pipeline.
Filter pipelines by application name and version on the Deployment Manager landing page.
In deployment logs, view all the new rule and data instances and all the changed rule and data
instances that are in an application package that imported into a candidate system.
Deployment Manager now provides APIs so that you can provide for new features in your applications:
Enhancements
The following enhancements are available in this release:
Data migration pipelines allow you export data from a production environment to a simulation environment
where you can test impact of the changes made to your decision framework safely without having to deploy
to a production environment. You can now use Deployment Manager to create data migration pipelines that
allow you to automatically export data from a production environment and import it into a simulation
environment. Additionally, you can configure a job scheduler rule to run pipelines during a specified period of
time.
For a tutorial on configuring simulation pipelines, including how to use Deployment Manager with them, see
Deploying sample production data to a simulation environment for testing.
For more information about configuring and using simulation pipelines with Deployment Manager, see Data
migration pipelines with Deployment Manager 4.6.x.
You can now allow a role to access Dev Studio, and all the users of that role can switch to Dev Studio from
the Operator icon. By being able to switch to Dev Studio, users can access Dev Studio tools to further
troubleshoot issues that Deployment Manager cannot diagnose.
Ability to easily move to new orchestration systems by configuring a dynamic system setting
When you move from an existing orchestration system to a new one, you can now configure a dynamic
system setting that specifies the URL of the new orchestration system.
The position of the Validate test coverage task was not retained.
If you added a Validate test coverage task in a pipeline, the task automatically moved under the Add task
menu option after you saved the pipeline configuration. The position of the task is now saved.
Deployment Manager installations on systems running on Db2 failed with a database error. You can now
install Deployment Manager on Db2.
Some HTTP requests to the api service package did not include PRRestService. It is now included in all
requests if it is needed to direct all traffic to the API node.
Tasks could not be added before the Deploy task in Deployment Manager 4.5.1 when using the API.
When you used the API to create pipelines, you could not add tasks before the Deploy task, although you
could add a task when you configured the pipeline in Deployment Manager. You can now add tasks before
the Deploy task with the API.
Sometimes, test changes in branches were merged into an incorrect ruleset version if multiple application
versions were used and a test application was configured on the pipeline. Test changes in branches are now
merged into the correct ruleset versions.
Deployment Manager displayed a message for reaching the limit for pending changes.
Sometimes, Deployment Manager displayed an error message that you reached the maximum limit for
pending changes. The limit has been increased, and the error no longer appears.
The Jenkins configuration diagnostics check failed when cross-site request forgery (CSRF) protection was
disabled.
When CSRF protection was disabled in Jenkins, pipeline diagnostics for Jenkins configuration failed with an
error message that the Jenkins server was not reachable, even though the Jenkins task in the pipeline
worked correctly. Jenkins diagnostics checks no longer fail in this scenario.
Enhancements
The following enhancements are provided in this release:
For additional validation or environment provisioning, you can now add any task before the Deploy and
Publish tasks, which are automatically added to the pipeline. You can add tasks before the Deploy task in
any stage of the pipeline or before the Publish task in the development stage.
Ability to associate bugs and user stories to branch merges
When you start a deployment by submitting a branch into the Merge Branches wizard, you can now
associate user stories and bugs from Agile Workbench so that you can track branch merges.
Deployment Manager now provides a REST API to deploy existing artifacts so that you can start a production
pipeline with the output of the development pipeline for the same application. You can view the
Documentation/readme-for-swagger.md file for more information on using the API.
Ability to access and pass all relevant parameters of the current deployment for Jenkins tasks
For Jenkins tasks, you can now access and pass all the relevant Jenkins parameters for the current
deployment, which include PipelineName, DeploymentID, RespositoryName, and ArtifactPath. When you
configure the Jenkins task in a pipeline, the values of the parameters are automatically populated.
You can now automatically diagnose more issues with your pipeline so that you spend less time manually
troubleshooting. For example, you can now verify that Jenkins steps are properly configured, and you can
also obtain more information about repository connections with enhanced troubleshooting tips.
Elimination of post-upgrade steps when upgrading from Deployment Manager versions 3.2.1 and later
For upgrades from Deployment Manager 3.2.1 or later to version 4.5.1, you no longer need to run activities
or do any other post-upgrade steps. After the upgrade completes, Deployment Manager performs health
checks before running post-upgrade steps for both on-premises and Pega Cloud Services environments.
Resolved issues
The following issue is resolved in Deployment Manager 4.5.1:
If your target environment is SSL-enabled with private certificates, you can now set the keystore for
Deployment Manager connectors so that they can receive and process tokens. You first configure a keystore
and then update a dynamic system setting to reference the keystore ID. For more information, see "Step 3a:
Configuring authentication profiles on the orchestration server and candidate systems" for your version of
Installing, upgrading, and configuring Deployment Manager.
Resolved issues
The following issues were resolved in this release:
Incorrect status displayed for the Run Pega unit test task
If you refreshed a merge request quickly, the status of the Run Pega unit tests task might have been
incorrectly displayed as the status of the merge. The correct status for the task is now displayed.
When you assigned manual tasks to an operator ID, the Manual task auto-complete displayed duplicate
entries for the same operator ID if the operator ID was added as an administrator or user for multiple
applications. The Manual task no longer displays duplicate entries.
Sometimes, a pipeline deployment might freeze if it could not update the task with the status that it
received from the task. The pipeline no longer freezes.
The Deploy existing artifact dialog box now validates the repository that you select. Error messages are also
displayed when the repository does not list available artifacts or if the repository does not have any artifacts
in it.
Verify security checklist task failed and displayed a Pega Diagnostic Cloud (PDC) error
The Verify security checklist failed when a pipeline had only one stage (development) and the Production
ready check box was selected on the pipeline configuration. A PDC error message was displayed. The task no
longer fails for pipelines with such a configuration.
For the Jenkins task, you could only enter a 32 character token to remotely start a Jenkins job. You can now
enter a token with more than 32 characters.
On pipelines on which dependent applications were configured, they were not deployed. They are now
deployed correctly.
Enhancements
The following enhancements are provided in this release:
Simplified configuration and workflow when merging branches in a distributed branch-based environment
The process for merging branches in distributed branch-based environments has been simplified. On the
remote development system, you can now merge branches and start a deployment by using the Merge
Branches wizard to merge branches onto the source development system without having to use a Pega
repository type.
You can now submit locked branches to the Merge Branches wizard so that you can follow best practices
when working with branches. Best practices include locking branches to prevent changes from being made
to them.
Using the Merge Branches wizard to make merge requests now stores the branch in the development
repository
When you use the Merge Branches wizard to merge branches and start a deployment, the wizard now stores
the branch in the development repository. Also, after the merge is completed, Deployment Manager deletes
the branch from the development system. By storing branches in the development repository, Deployment
Manager keeps a history, which you can view, of the branches in a centralized location.
You can now separately manage both application changes and test cases in the same pipeline by using a
separate product rule that contains only test cases. You can also choose a stage until which test cases are
deployed to ensure that test cases are not deployed on environments such as staging and production, where
they might not be needed. When you create test and production applications in Deployment Manager on
your development system by using the New Application wizard, the wizard automatically creates separate
product rules for your production and test applications.
Usability enhancements
For the Check guardrail compliance task, the default guardrail compliance score has been increased to
97.
Email notifications for Jenkins jobs now include a link to the Jenkins job.
You can now start a Jenkins job when Jenkins has cross-site request forgery (CSRF) protection enabled.
For pipelines that have Jenkins tasks, job history details for successful deployments have a link to the
Jenkins job.
The Pipeline list in the Merge Branches wizard no longer displays pipelines that are not configured to
support branches; previously, you received an error after submitting pipelines that did not support
branches.
If you are using the Merge Branches Wizard but do not have pipelines configured for an application, you
can use still use the wizard to merge branches into target applications.
Known issues
The following are known issues in this release:
The Pega Platform 8.1 and 8.2 versions of the Rule rebasing and Rebasing rules to obtain latest versions
help topics should state that rule rebasing is supported in Deployment Manager.
The Publishing a branch to a repository help topic should state that you can use Deployment Manager to
start a deployment by publishing a branch to the source development system even if you have multiple
pipelines per application version. Also, the note in this help topic no longer applies.
Resolved issues
The following issue has been resolved:
On systems running Pega CRM applications, pipelines were not visible on the Deployment Manager landing
page when the datapage/newgenpages dynamic system setting was set to false. This setting disabled the new
clipboard implementation for optimized read-only data pages. Pipelines are now visible regardless of the
dynamic system setting value.
Enhancements
The following enhancements are provided in this release:
You can now configure notifications in Deployment Manager without having to configure an email account
and listener in Dev Studio. You can also choose which notifications to receive such as whether Pega unit test
tasks succeeded or failed. You can receive notifications through email, in the notification gadget, or both,
and you can create custom notification channels to receive notifications through other means such as text
messages or mobile push notifications.
Note: To use notifications, you must install or upgrade to Pega Platfor 8.1.3 on the orchestration server.
Publishing application changes has been consolidated with viewing application versions in App Studio
You can now publish application changes in App Studio and view information about your Deployment
Manager application versions on one page. By accessing publishing features and viewing information in one
place, you can more intuitively use Deployment Manager with App Studio.
Enhancements
The following enhancements are provided in this release:
Deployment Manager now provides default roles that specify privileges for super administrators and
application administrators. Super administrators can add roles and specify their privileges, and both super
administrators and application administrators can add users and assign them roles for specified applications.
By specifying roles and privileges for Deployment Manager users, you can manage your users more
effectively by controlling access to features for each type of user.
Deployment Manager now provides a dedicated Deployment Manager portal that does not require access to
the Dev Studio portal to access Deployment Manager features. The portal also provides enhancements such
as a navigation panel from which you can easily acdcess features such as reports, without having to open
specific pipelines. Additionally, when you add a pipeline or modify pipeline settings, you can now open the
rule forms for repositories and authentication profiles in Dev Studio from within Deployment Manager.
You can now merge a branch that has rulesets that are in multiple applications if all the rulesets are in the
application stack for the pipeline application. By doing so, you can, for example, merge changes that affect
both a framework and an application layer. You can also merge test assets with the rules that you are testing
without the test assets and rules being in the same application.
Enhancements
The following enhancements are provided in this release:
Deployment Manager has been redesigned to have a more intuitive interface so that you can quickly access
features as you interact with your pipeline. The Deployment Manager landing page now displays a snapshot
of your pipeline configuration, which provides status information such as whether a deployment failed and
on what stage the failure occurred. Additionally, when you click a pipeline to open it, Deployment Manager
now displays important information about your pipeline such as the number of branches that are queued for
merging on the development system.
You can now manage rules and data types, which are in an application package, that are older than the
instances that are on a system. By importing aged updates, skipping the import, or manually deploying
application packages on a system, you have more flexibility in determining the application contents that you
want to deploy.
Several new test tasks have been added so that you deliver higher quality software by ensuring that your
application meets the test criteria that you specify. On the candidate systems in your pipeline, you can now
perform the following actions:
Run Pega scenario tests, which are end-to-end, UI-based tests that you create within Pega Platform.
Start and stop test coverage at the application level to generate a report that identifies the executable
rules in your application that are covered or not covered by tests.
Refresh the Application Quality dashboard with the latest information so that you can see the health of
your application and identify areas that need improvement before you deploy your application.
You can submit application changes to a pipeline in App Studio to start a deployment in Deployment
Manager. The following enhancements have been made:
When you submit application changes into a pipeline, patch versions of the main application are now
created.
You can now add comments, which will be published with your application.
You can now associate user stories and bugs with an application.
You can now view information such as who published the application and when for the application
versions that you have submitted
Run Pega unit tests on branches before merging
You can now run Pega unit tests on branches before they are merged in the pipeline for either the pipeline
application or an application that is associated with an access group. By validating your data against Pega
unit tests, you can deploy higher quality applications.
Enhancements
The following enhancements are provided in this release:
You can now manage rules and data types, which are in an application package, that are older than the
instances that are on a system. By importing aged updates, skipping the import, or manually deploying
application packages on a system, you have more flexibility in determining the application contents that you
want to deploy.
You can now merge a branch that has rulesets that are in multiple applications if all the rulesets are in the
application stack for the pipeline application. By doing so, you can, for example, merge changes that affect
both a framework and an application layer. You can also merge test assets with the rules that you are testing
without the test assets and rules being in the same application.
Enhancements
The following enhancements are provided in this release:
You can now use the Verify security checklist task to ensure that your pipeline complies with security best
practices. It is automatically added to the stage before production when you create a pipeline.
You can now diagnose your pipeline to verify information such as whether the target application and product
rule are on the development environment, connectivity between systems and repositories is working, and
pre-merge settings are correctly configured. You can also view troubleshooting tips and download logs.
Known issues
The following known issue exists in this release:
If you are using a CRM application, you cannot roll back a deployment to a previous deployment.
Enhancements
The following enhancements are provided in this release:
Pipeline setup has been simplified when you install Deployment Manager and when you configure pipelines.
The following enhancements have been made:
Deployment Manager now provides the Pega Deployment Manager application with default operators
and authentication profiles when you install it. You do not need to create authentication profiles for
communication between candidate systems and the orchestration server.
If you are using Pega Cloud, Deployment Manager is automatically populated with the URLs of all the
systems in your pipeline so that you do not need to configure them.
You can now use the Check guardrail compliance task to ensure that the deployment does not proceed if the
application does not comply with best practices for building applications in Pega Platform. This task is
automatically added to all the stages in your pipeline.
Deployment Manager now provides an Approve for production task, which is automatically added to the
stage before production when you create a pipeline. You can assign this task to a user who approves the
application changes before the changes are deployed to production.
Ability to specify the test suite ID and access group for Pega unit testing tasks
For Pega unit testing tasks, you can now run all the Pega unit tests that are defined in a test suite for the
application pipeline. By using a test suite ID, you can run a subset of Pega unit tests instead of all Pega unit
tests for a pipeline application. You can also run all the Pega unit tests for an application that is associated
with an access group so that you can run Pega unit tests for an application other than the pipeline
application.
Deployment Manager now supports first-time deployments, so you do not have to import your application
into each Pega Platform server on your candidate systems the first time that you configure Deployment
Manager.
Enhancements
The following enhancements are provided in this release:
You can now create custom repository types and manage your artifacts with them when you use Deployment
Manager. For example, you can create a Nexus repository type and use it to move your application package
between candidate systems in a pipeline. By creating custom repository types, you can use a wider variety
of repository types with your artifacts to extend the functionality of Deployment Manager.
Use the Merge Branches wizard to submit branches into a continuous integration and delivery pipeline.
You can now submit branches into a continuous integration and delivery (CI/CD) pipeline by using the Merge
Branches wizard in Designer Studio. Deployment Manager can then run pre-merge criteria on branches on
one system so that you do not need to configure additional systems for both branch development and
merging.
Beginning with Pega 7.4, all current and new Pega Cloud customers have a free dedicated sandbox to run
Deployment Manager, which provides the following features:
Default repositories that store and move your application package between systems in the pipeline.
Ability to view, download, and remove application packages from repositories so that you can manage
your cloud storage space.
Ability to deploy an existing application package.
Ability to create multiple pipelines for one version of an application.
Ability to create multiple pipelines for one version of an application. For example, you can create a
pipeline with only a production stage if you want to deploy a build to production separately from the
rest of the pipeline.
You can now browse, download, and delete application package artifacts from the orchestration server. You
do not have to log in to repositories to delete artifacts from them.
Ability to move existing artifacts through pipelines.
You can move existing artifacts through your pipelines. Existing artifacts are maintained in repositories, and
you can move them through progressive stages in the pipeline.
Publishing application packages to the production repository sometimes fails in multinode environments
In multinode staging environments, a node retrieves an application package from the development
repository and places it into its service export folder to be published to the production repository. However,
Deployment Manager sometimes cannot publish it to the production repository, because the request might
be sent to a different node. This issue has been fixed so that if Deployment Manager sends a request to a
node that does not have the application package, that node retrieves the package from the development
repository and publishes it to the production repository.
Enhancements
The following enhancement is provided in this release:
Improvements have been made to email notifications that are sent to users when an event has occurred. For
example, the email that is sent when a step on which PegaUnit test task fails now includes an attached log
file that provides details of each failed PegaUnit test case.
Known issues
The following issue exists in this release:
To resolve the issue, after you import and install Deployment Manager 02.01.02, perform the following steps
on the orchestration server:
Because this agent is not associated with the correct access group, it cannot process Deployment Manager
activities in the background.
Enhancements
The following enhancement is provided in this release:
Improvements have been made to email notifications that are sent to users when an event has occurred. For
example, the email that is sent when a step on which PegaUnit test task fails now includes an attached log
file that provides details of each failed PegaUnit test case.
Known issues
The following issue exists in this release:
Because this agent is not associated with the correct access group, it cannot process Deployment Manager
activities in the background.
To resolve the issue, after you import and install Deployment Manager 01.01.02, perform the following steps
on the orchestration server:
Resolved issues
The following issue was resolved in this release:
Selections that were made to the Start build on merge check box were not applied when editing a pipeline.
When you edit a pipeline and either select or clear the Start build on merge check box, your changes are
now applied. Additionally, the check box is cleared by default.
You can run deployments involving your application updates with the click of a button, without the need for third-
party automation services such as Jenkins or Bamboo. Fully automated pipelines helpto significantly reduce the
lead time to deliver value to end users.
Using a standardized way to deploy application changes with guardrail-related and testing-related best practices
that are built into the out-of-the-box CI/CD models results in substantial operational efficiencies.
For answers to frequently asked questions, see the Deployment Manager FAQ page.
Deployment Manager provides a number of features so that you can manage your workflows. For example,
Deployment Manager supports continuous integration, continuous delivery, test execution, reporting,
diagnostics, manual approvals, deployment cancellations, change rollbacks, roles and privileges, and
notifications.
If you are using Deployment Manager on-premises, you must first install it.
If you are using Deployment Manager either on-premises or on Pega Cloud Services environments, you must
perform steps to upgrade to a new release.
Deployment Manager is ready to use out of the box. There is no need to build on top of it; however, some
initial configurations are needed before you can get started. For details about how Deployment Manager
works, see .
After you set up and configure Deployment Manager, you can begin using it to create pipelines. You can also
do a number of other tasks, such as creating Deployment Manager roles and users and configuring the
notifications that you want to receive. For detailed information, see .
If you encounter issues with Deployment Manager, you can troubleshoot it in a number of ways.
Obtaining support
If you experience problems using Deployment Manager, submit a support request to My Support Portal.
For information about installing Deployment Manager, see Installing or upgrading to Deployment Manager 4.7.x.
Beginning with Pega Platform 7.4, Pega Cloud Services users have a dedicated instance in their virtual private
cloud (VPC) at the time of onboarding with Deployment Manager functionality preinstalled.
Note: This instance is referred to as the orchestration server and contains the “DevOps” keyword in the URL.
Upgrading to a new release
If you are using Deployment Manager either on-premises or on Pega Cloud Services environments, you must
perform steps to upgrade to a new release.
Pega Cloud Services users should create a support ticket to request a new release.
After you obtain the latest release, refer to the upgrade documentation for information about upgrading to the
latest release. For more information, see Installing or upgrading to Deployment Manager 4.8.x.
Candidate systems – the individual environments that host the target application, typically the development,
QA, staging, and production environments.
Repository – the artifact repository that stores the application archive as defined by a product rule.
DMAppAdmin – the operator ID, provided out of the box, that is used by an application pipeline to execute all
the tasks such as deploying, running tests, checking guardrail scores, and so on.
DMReleaseAdmin – the operator ID, provided out of the box, that has administrative privileges for
Deployment Manager. This is the user that you will start with for the Deployment Manager.
Note: You should make changes only in the development environment and then move them to higher
environments. Do not make changes in any other environment.
a. Log in to the orchestration server and enable the DMReleaseAdmin operator ID.
b. Log in to candidate systems (development, QA, staging, and production) and enable the DMAppAdmin
operator ID. Ensure that the same password is set on all environments.
c. On the orchestration server, open the DMAppAdmin authentication profile and set the password to the
DMAppAdmin operator ID password that you set in step 1b.
d. On all candidate systems, open the DMReleaseAdmin authentication profile and set the password to the
DMReleaseAdmin operator ID password that you set in step 1a.
2. On each candidate system, open your target application and add PegaDevOpsFoundation as a built-on
application. For more information, see Configuring candidate systems.
3. To use branches for application development, set the RMURL dynamic system setting on the development
environment to be the orchestration server URL.
4. For on-premises users, set up repositories for artifact archiving. For more information, see Creating
repositories on the orchestration server and candidate systems.
Deployment Manager leverages JFrog Artifactory, Amazon S3, Microsoft Azure, or file system repository
types. After you configure one of these repositories, you will select one to use when you create your
pipelines.
You will specify this product rule when you create your pipeline.
6. To receive email notification for deployments, configure email accounts on the orchestration server.
For more information, see Configuring email accounts on the orchestration server.
7. If you are using Jenkins, configure Jenkins so that it can communicate with the orchestration server.
For more information, see Configuring Jenkins.
1. Log in to the Deployment Manager portal on the orchestration server with the DMReleaseAdmin operator ID.
2. Create a pipeline by modeling stages and steps and specifying environments, applications, product rules,
and repositories.
3. Run diagnostics by clicking Actions Diagnose pipeline to verify that your pipeline is correctly configured.
4. Run deployments directly from Deployment Manager or from development environments as you merge your
branches.
Run diagnostics and follow troubleshooting tips if your deployments fail to run.
Review pipeline logs that are available on the pipeline landing page and the output from diagnostics to
troubleshoot your workflows.
Attach logs from Deployment Manager and the output from diagnostics in your support tickets.
Obtaining support
If you experience problems using Deployment Manager, submit a support request to My Support Portal.
With Deployment Manager, you can fully automate your CI/CD workflows, including branch merging, application
package generation, artifact management, and package promotion to different stages in the workflow.
Deployment Manager supports artifact management on repository types such as Amazon S3, file system,
Microsoft Azure, and JFrog Artifactory. Additionally, in Deployment Manager 3.3.x and later, you can create your
own repository types; for more information, see Creating and using custom repository types for Deployment
Manager. Deployment Manager also supports running automations on Jenkins that are not supported in Pega
Platform such as running external regression or performance tests. In addition, Pega Cloud pipelines are
preconfigured to use Amazon S3 repositories and are configured to use several best practices related to
compliance and automated testing.
Deployment Manager is installed on the orchestration server, on which release managers configure and run
pipelines. With Deployment Manager, you can see the run-time view of your pipeline as it moves through the
CI/CD workflow. Deployment Manager provides key performance indicators (KPIs) and dashboards that provide
performance information such as the deployment success rate, deployment frequency, and task failures. Use this
information to monitor and optimize the efficiency of your DevOps process.
A CI/CD pipeline models the two key stages of software delivery: continuous integration and continuous
delivery.
The CI/CD pipeline comprises several systems and involves interaction with various Pega Platform servers.
For example, you can use a QA system to run tests to validate application changes.
Understanding repositories in the pipeline
Deployment Manager supports Microsoft Azure, JFrog Artifactory, Amazon S3, and file system repositories for
artifact management of application packages. For each run of a pipeline, Deployment Manager packages and
promotes the application changes that are configured in a product rule. The application package artifact is
generated on the development environment, published in the repository, and then deployed to the next
stage in the pipeline.
If you use branches for application development, you can configure merge criteria on the pipeline to receive
feedback about branches, such as whether a branch has been reviewed or meets guardrail compliance
scores.
If you do not use branches for application development, but you use ruleset-based development instead, you
configure the continuous delivery pipeline in Deployment Manager.
In the continuous integration stage, developers continuously validate and merge branches into a target
application. In the continuous delivery stage, the target application is packaged and moved through progressive
stages in the pipeline. After application changes have moved through testing cycles, including Pega unit,
regression, performance, and load testing, application packages are deployed to a production system either
manually or, if you want to continuously deploy changes, automatically.
Note: You should make changes only in the development environment and then move those changes to a higher
environment. Do not make changes in any other environment.
Orchestration server – Pega Platform system on which the Deployment Manager application runs and on
which release managers or application teams model and run their CI/CD pipelines. This system manages the
CI/CD workflow involving candidate systems in the pipeline
Candidate systems – Pega Platform servers that manage your application's life cycle; they include the
following systems:
Development system – The Pega Platform server on which developers build applications and merge
branches into them. The product rule that defines the application package that is promoted to other
candidate systems in the pipeline is configured on this system. Distributed development environments
might have multiple development systems.
In this environment, developers develop applications on remote Pega Platform development systems
and then merge their changes on a main development system, from which they are packaged and
moved in the Deployment Manager workflow.
QA and staging systems – Pega Platform servers that validate application changes by using various
types of testing, such as Pega unit, regression, security, load, and performance testing.
Production system – Pega Platform server on which end users access the application.
A pipeline uses development and production repositories. After a pipeline is started, the application package
moves through the pipeline life cycle in the following steps:
1. The development system publishes the application package to the development repository.
2. The QA system retrieves the artifact from the development repository and performs tasks on the artifact.
3. The staging system retrieves the artifact from the development repository and publishes it to the production
repository.
4. The production system deploys the artifact from the production repository
If there are no merge conflicts, and merge criteria is met, the branch is merged; the continuous delivery pipeline
is then started either manually or automatically.
In a distributed, branch-based environment, you can have multiple development systems, and developers author
and test the application on remote Pega Platform development systems. They then merge their changes on a
development source development, from which they are packaged and moved in the Deployment Manager
workflow.
1. Developers update rules and check them in directly to the application rulesets on the development system.
2. The product rule that contains the application rules to be packaged and moved through the systems in the
pipeline is on the development system.
3. Continuous delivery is started manually at a defined schedule by using Deployment Manager.
The following figure describes the workflow of a pipeline in an environment without branches.
If you use branches for application development in a non-distributed environment, developers work on branches
and merge them on the development system, after which the continuous delivery pipeline is started
automatically or manually.
In a distributed branch-based environment, you can have multiple development systems, and developers author
and test the application on a remote development system. They then merge their changes on a source
development system, from which the changes are merged and moved in the Deployment Manager workflow.
For more information about best practices to follow in the DevOps pipeline, see Understanding the DevOps
release pipeline.
Best practices for using branches in Deployment Manager depend on whether you have a single
development team or multiple teams in a distributed environment.
In general, perform the following steps when you use branches with Deployment Manager:
1. In Deployment Manager, create a pipeline for the target application. If your application consists of multiple
built-on applications, it is recommended that you create separate pipelines for each application.
By using separate pipelines for built-on applications, you can perform targeted testing of each built-on
application, and other developers can independently contribute to application development.
For more information about multiple built-on applications, see Using multiple built-on applications.
2. Ensure that the target application is password-protected on all your systems in the pipeline.
a. In Designer Studio (if you are using Deployment Manager 3.4.x) or Dev Studio (if you are using
Deployment Manager 4.1.x or later), switch to the target application by clicking the name of the
application in the header, clicking Switch Application, and then clicking the target application.
b. In the Designer Studio or Dev Studio header, click the name of the target application, and then click
Definition.
d. In the Edit Application form, click the Require password to update application checkbox.
f. In the Update password dialog box, enter a password, reenter it to confirm it, and click Submit.
3. If you want to create a separate product rule for a test application, create a test application that is built on
top of the main target application. For more information, see Using branches and test cases.
4. On the source development system (in a distributed environment) or development system (in a
nondistributed environment), create a development application that is built on top of the either the target
application (if you are not using a test application) or the test application.
5. Include the PegaDevOpsFoundation application as a built-on application for either the team application or the
target application.
a. In either the development application or target application, in the Dev Studio or Designer Studio
header, click the application, and then click Definition.
b. In the Edit Application form, on the Definition tab, in the Built on applications section, click Add
application.
c. In the Name field, press the down arrow key and select PegaDevOpsFoundation.
d. In the Version field, press the down arrow key and select the version for the Deployment Manager
version that you are using.
f. If you are using a distributed environment, import the application package, including the target,
development, and test (if applicable) applications, into the remote development system.
6. Do one of the following actions:
If you are using a distributed environment, add branches to the team application on the remote
development system. For more information, see Adding branches to your application.
If you are using multiple built-on applications, maintain separate branches for each target application.
For more information, see the Pega Communityarticle Using multiple built-on applications.
If you are using a non-distributed environment, create a branch of your production rulesets in the team
application. For more information, see Adding branches to your application. You should create separate
branches for each target pipeline.
If you are using either a non-distributed network (in any version of Deployment Manager) or a
distributed network (in Deployment Manager 4.4.x or later), first lock the branches that you want to
validate and merge in the application pipeline and then submit the branches in the Merge Branches
wizard.
For more information, see Submitting a branch into an application by using the Merge Branches wizard.
If you are using a distributed network and Deployment Manager 4.4.x or and are publishing branches to
a source development system to start a build, do the following actions:
1. On the remote development system, publish the branch to the repository on the source
development system to start the pipeline. For more information, see Publishing a branch to a
repository.
2. If there are merge conflicts, log in to the team application on the source development system, add
the branch to the application, resolve the conflict, and then merge the branch.
If you using a distributed network and versions of Deployment Manager earlier than 4.4.x with one
pipeline per application, do the following steps so that you can merge branches onto the source
development system:
1. On the remote development system, create a Pega repository that points to the target application
on the source development system. For more information, see Adding a Pega repository.
2. On the remote development system, publish the branch to the repository on the source
development system to start the pipeline. For more information, see Publishing a branch to a
repository.
3. If there are merge conflicts, log in to the team application on the source development system, add
the branch to the application, resolve the conflict, and then merge the branch.
If you using a distributed network and versions of Deployment Manager earlier than 4.4.x with multiple
pipelines per application and application version:
1. Package the branch on the remote development system. For more information, see Packaging a
branch.
2. Export the branch.
3. Import the branch to the source development system and add it to the team application. For more
information, see Importing rules and data by using the Import wizard.
4. Merge branches into the target application to start the pipeline by using the Merge Branches
wizard.
To use a separate test package, you must create a test application layer on the development systems in your
pipeline.
You must first configure your application stack on either the development or source development system.
Configuring the application stack on the remote development system in a distributed, branch-based
environment
If you are using a distributed, branch-based environment, you must configure the application stack on the
remote development system.
Branches in the development application can contain rulesets that belong to the target application, test
application, or both. When you start a deployment either by using the Merge Branches wizard or by
publishing a branch to a repository on the main development system, the branches in both the target and
test applications are merged in the pipeline.
When you add or modify a pipeline, you specify whether you want to deploy test cases and then configure
details for the test application, including its name and access group to which it belongs, in the Application
test cases section. You also select the stage until which you want to deploy the pipeline. For more
information about using Deployment Manager, see .
If you are using a distributed, branch-based environment, complete the following steps on the remote
development system.
If you are using a branch-based environment, complete the following steps on the development system.
If you are not using branches, complete the following steps on the development system.
2. Create a test application, which contains the test rulesets that you want to separately deploy, that is built on
the target application.
3. Create a development application that is built on top of the test application, which developers can log in to
so that they can create and work in branches.
2. Create a test application, which contains the test rulesets that you want to separately deploy, that is built on
the target application.
When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests, Enable test
coverage, and Validate test coverage tasks are run for the access group that is specified in the Application test
cases section.
You must also perform the following steps on the candidate system on which you are running tests:
3. Select the Include built-on applications radio button, and then click Save.
To create a custom repository type to use with Deployment Manager, complete the following steps:
1. Create a custom repository type. For more information, see Creating a custom repository type.
2. If you are using Deployment Manager 3.3.x or 4.1.x or later on each candidate system, add the ruleset that
contains the custom repository type as a production ruleset to the PegaDevOpsFoundation:Administrators
access group.
a. In the header of either Designer Studio (if you are using Deployment Manager 3.3.x) or Dev Studio (if
you are using Deployment Manager 4.1.x or later), click Records Security Access Group .
b. Click PegaDevOpsFoundation:Administrators.
c. Click Advanced
d. In the Run time configuration section, click the Production Rulesets field, press the Down arrow key, and
select the ruleset that contains the custom repository type.
3. Import the ruleset on which the custom repository is configured in to the orchestration system and add the
ruleset to the PegaDeploymentManager application stack.
a. On the orchestration system, import the ruleset by using the Import wizard. For more information, see
Importing rules and data by using the Import wizard.
b. In either the Designer Studio or Dev Studio header, in the Application field, click
PegaDeploymentManager, and then click Definition.
c. On the Edit Application rule form, in the Application rulesetsfield, click Add ruleset.
d. Click the field that is displayed, press the Down arrow key, and then select the ruleset that contains the
custom repository type.
Configure the orchestration server and candidate systems so that Deployment Manager 4.x works with Pega
7.4. Use Deployment Manager 4.x on the orchestration system with candidate systems that are running
Pega 7.4. and Deployment Manager 3.4.x.
For example, you can update a dynamic system setting on a quality assurance system, which has an application
package that contains the older instance of the dynamic system setting. Before Deployment Manager deploys the
package, the system detects that the version of the dynamic system setting on the system is newer than the
version in the package and creates a manual step in the pipeline.
In Deployment Manager 4.5.x, some of the repository diagnostics do not work for candidate systems that are
running Pega 7.4. These diagnostics work in Deployment Manager 4.6.x.
1. On the orchestration system, install or upgrade to the latest version of Pega Platform.
2. On the orchestration system, install or upgrade to the latest version of Deployment Manager 4.x. For more
information, see Installing or upgrading to Deployment Manager 4.8.x.
For more information about the Import wizard, see Importing rules and data by using the Import
wizard.
Related Content
Article
Only super administrators can enable and disable the chatbot. For more information about user roles, see
Understanding roles and users.
To enable the chatbot, select the Enable self-service Deployment Manager web chatbot check box.
To disable the chatbot, clear the check box.
3. Click Save.
4. At the top of the General Settings page, click the Page back icon.
5. Click the Refresh icon to refresh Deployment Manager and apply your changes.
With Deployment Manager, you can fully automate your CI/CD workflows, including branch merging; application
package generation; artifact management; and package promotion, to different stages in the workflow.
Deployment Manager 4.8.x is compatible with Pega 8.1, 8.2, 8.3, and 8.4. You can download it for Pega Platform
from the Deployment Manager Pega Marketplace page.
For answers to frequently asked questions, see the Deployment Manager FAQ page.
Note: Each customer Virtual Private Cloud (VPC) on Pega Cloud Services has a dedicated orchestrator instance to
use Deployment Manager. You do not need to install Deployment Manager to use it with your Pega Cloud
application.
Note: To use notifications, you must install or upgrade to Pega 8.1.3 on the orchestration server.
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate
tasks and allow you to quickly deploy high-quality software to production.
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate
tasks so that you can quickly deploy high-quality software to production.
Using data migration pipelines with Deployment Manager 4.8.x
Data migration tests provide you with significant insight into how the changes that you make to decision
logic affect the results of your strategies. To ensure that your simulations are reliable enough to help you
make important business decisions, you can deploy a sample of your production data to a dedicated data
migration test environment.
Note: You should make changes only in the development environment and then move them to higher
environments. Do not make changes in any other environment.
Note: Each customer virtual private cloud (VPC) on Pega Cloud Services has a dedicated orchestrator instance to
use Deployment Manager. If you are upgrading from an earlier release, contact Pegasystems Global Client
Support (GCS) support to request a new version.
Note: This document describes the procedures for the latest version of Deployment Manager 4.8.x. To use
notifications, you must install or upgrade to Pega 8.1.3 on the orchestration server.
For information on configuring Deployment Manager for data migration pipelines, see Installing, upgrading, and
configuring Deployment Manager 4.8.x for data migration pipelines.
You must install Deployment Manager if you are using it on-premises. Because Pega Cloud Services
manages the orchestration server in any Pega Cloud subscription, Pega Cloud Services manages the
installation and upgrades of Deployment Manager orchestration servers.
Configure the orchestration server and candidates in your pipeline for all supported CI/CD workflows. If you
are using branches, you must configure additional settings on the development system after you perform the
required steps.
If you are using branches in either a distributed or nondistributed branch-based environment, configure the
development system so that you can start deployments when branches are merged. Configuring the
development system includes defining the URL of the orchestration server, creating development and target
applications, and locking application rulesets.
As part of your pipeline, users can optionally receive notifications through email when events occur. For
example, users can receive emails when tasks or pipeline deployments succeed or fail. For more information
about the notifications that users can receive, see .
1. Install Pega Platform 8.1, 8.2, 8.3, or 8.4 on all systems in the pipeline.
2. On each system, browse to the Deployment Manager Pega Marketplace page, and then download the
DeploymentManager04.08.0x.zip file for your version of Deployment Manager.
4. Use the Import wizard to import files into the appropriate systems. For more information about the Import
wizard, see Importing rules and data by using the Import wizard.
5. On the orchestration server, import the following files:
PegaDevOpsFoundation_4.8.zip
PegaDeploymentManager_4.8.zip
7. If you are using a distributed development for CI/CD workflows, on the remote development system, import
the PegaDevOpsFoundation_4.8.zip file.
If you are upgrading from version 3.2.1 or later, the upgrade automatically runs, and you can use
Deployment Manager when post-upgrade steps are run. You do not need to perform any of the required
configuration procedures but can configure Jenkins and email notifications. For more information, see
Configuring additional settings.
If you are not upgrading, continue the installation procedure at Configuring authentication profiles.
Deployment Manager provides default operator IDs and authentication profiles. You must enable the default
operator IDs and configure the authentication profiles that the orchestration server uses to communicate
with the candidate systems.
The orchestration server is the system on which the Deployment Manager application is installed and release
managers configure and manage CI/CD pipelines. Configure settings on it before you can use it in your
pipeline.
Configure each system that is used for the development, QA, staging, and production stage in the pipeline.
If you are using Deployment Manager on premises, create repositories on the orchestration server and all
candidate systems to move your application between all the systems in the pipeline. You can use a
supported repository type that is provided in Pega Platform, or you can create a custom repository type.
1. On the orchestration server, enable the DMReleaseAdmin operator ID and specify its password.
b. In the header of Dev Studio, click Records Organization Operator ID , and then click DMReleaseAdmin.
c. On the Edit Operator ID rule form, click the Security tab.
e. Click Save.
g. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then
click Submit.
2. On each candidate system, which includes the development, QA, staging, and production systems, enable
the DMAppAdmin operator ID.
If you want to create your own operator IDs, ensure that they point to the PegaDevOpsFoundation
application.
b. In the header of Dev Studio, click Records Organization Operator ID , and then click DMAppAdmin.
c. In the Explorer panel, click the operator ID initials, and then click Operator.
f. Click Save.
h. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then
click Submit.
3. On each candidate system, update the DMReleaseAdmin authentication profile to use the new password. All
candidate systems use this authentication profile to communicate with the orchestration server about the
status of the tasks in the pipeline.
a. Log in to each candidate system with the DMAppAdmin operator ID and the password that you
specified.
c. Click DMReleaseAdmin.
e. In the Password dialog box, enter the password, and then click Submit.
4. On the orchestration server, modify the DMAppAdmin authentication profile to use the new password. The
orchestration server uses this authentication profile to communicate with candidate systems so that it can
run tasks in the pipeline.
a. Log in to the orchestration server with the DMAppAdmin user name and the password that you
specified.
c. Click DMAppAdmin.
e. In the Password dialog box, enter the password, and then click Submit.
a. In the header of Dev Studio, create and configure a keystore. For more information, see Creating a
keystore for application data encryption.
d. On the Settings tab, in the Value field, enter the ID of the keystore that you created in the previous
step.
e. Click Save.
For more information about dynamic system settings, see Creating a dynamic system setting.
If you are upgrading to Deployment Manager 4.8.x, resume the post-upgrade procedure from step 2.
For more information, see Running post-upgrade steps.
If you are not upgrading, continue the installation procedure. For more information, see Configuring the
orchestration server.
When you install Deployment Manager on all the systems in your pipeline, default applications, operator IDs,
and authentication profiles are installed. Authentication profiles enable communication between the
orchestration server and candidate systems.
The DMReleaseAdmin and DMAppAdmin operator IDs do not have default passwords.
When you install Deployment Manager on all the systems in your pipeline, default applications, operator IDs, and
authentication profiles that communicate between the orchestration server and candidate systems are also
installed.
Note: The DMReleaseAdmin and DMAppAdmin operator IDs do not have default passwords.
1. If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd
service packages.
b. Click api.
c. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
e. Click cicd.
f. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
2. To move the orchestration server to a different environment, first migrate your pipelines to the new
orchestration server, and then configure its URL on the new orchestration server.
This URL will be used for callbacks and for diagnostics checks.
a. In the header of Dev Studio, click Create SysAdmin Dynamic System Settings .
e. On the Settings tab, in the Value field, enter the URL of the new orchestration server in the format
http://hostname:port/prweb.
f. Click Save.
Configure the candidate systems in your pipeline. For more information, see Configuring candidate systems.
1. On each candidate system, add the PegaDevOpsFoundation application to your application stack.
a. In the header of Dev Studio, click the name of your application, and then click Definition.
b. In the Built on application section, click Add application.
c. In the Name field, press the Down arrow key and select PegaDevOpsFoundation.
d. In the Version field, press the Down arrow key and select the version of Deployment Manager that you
are using.
e. Click Save.
2. If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd
service packages.
b. Click api.
c. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
e. Click cicd.
f. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
3. To use a product rule for your target application, test application, or both, other than the default rules that
are created by the New Application wizard, on the development system, create product rules that define the
test application package and the target application package that will be moved through repositories in the
pipeline.
For more information, see Creating a product rule that includes associated data by using the Create menu.
When you use the New Application wizard, a default product rule for your target application is created that
has the same name as your application. Additionally, if you are using a test application, a product rule is
created with the same name as the target application, with _Tests appended to the name.
Configure repositories through which to move artifacts in your pipeline. For more information, see Creating
repositories on the orchestration server and candidate systems
If you are using Deployment Manager on Pega Cloud Services, default repositories, named
"pegacloudcustomerroot" for both the development and production repositories, are provided. If you want to use
repositories other than the ones provided, you can create your own.
For more information about creating a supported repository, see Creating a repository.
For more information about creating a custom repository type, see Creating and using custom repository types for
Deployment Manager.
You cannot use the Pega repository type to store application artifacts for the following reasons:
The Pega repository type points to the temporary folder where the Pega Platform node that is
associated with Deployment Manager stores caches. This node might not be persistent.
This repository type is suitable onlyfor single node deployments. In multinode deployments, each time a
requestor is authenticated, the requestor could be in a different node, and published artifacts are not
visible to the repository.
At most companies, the security practice is that lower environments should not connect to higher
environments. Using a Pega repository typically means that a lower environment can access a higher
environment.
You can only use Pega type repositories if are rebasing your development system to obtain the most
recently committed rulesets after merging them.
You can use file system type repositories if you do not want to use proprietary repositories such as
Amazon s3 or JFrog Artifactory.
You cannot use the defaultstore repository type to host artifacts or product archives for the production
applications. It is a system-managed file system repository; it points to the temporary folder where the Pega
Platform node that is associated with Deployment Manager stores caches.
Ensure that each repository has the same name on all systems.
When you create JFrog Artifactory repositories, ensure that you create a Generic package type in JFrog
Artifactory. Also, when you create the authentication profile for the repository on Pega Platform, you must
select the Preemptive authentication check box.
After you configure a pipeline, you can verify that the repository connects to the URL of the development and
production repositories by clicking Test Connectivity on the Repository rule form.
1. On the development system (in nondistributed environment) or the main development system (in a
distributed environment), create a dynamic system setting to define the URL of the orchestration server,
even if the orchestration server and the development system are the same system.
e. On the Settings tab, in the Value field, enter the URL of the orchestration server in the format
http://hostname:port/prweb/PRRestService .
f. Click Save.
For more information about dynamic system settings, see Creating a dynamic system setting
2. Complete the following steps on either the development system (in a non-distributed environment) or the
remote development system (in a distributed environment).
a. Use the New Application wizard to create a new development application that developers will log in to.
This application allows development teams to maintain a list of development branches without
modifying the definition of the target application.
b. Add the target application of the pipeline as a built-on application layer of the development application
by first logging into the application.
c. In the header of Dev Studio, click the name of your application, and then click Definition.
e. In the Name field, press the Down arrow key and select the name of the target application.
f. In the Version field, press the Down arrow key and select the target application version.
g. Click Save.
3. Lock the application rulesets to prevent developers from making changes to rules after branches have been
merged.
a. In the header of Dev Studio, click the name of your application, and then click Definition.
b. In the Application rulesets section, click the Open icon for each ruleset that you want to lock.
5. If you are managing test cases separately from the target application, create a test application. For more
information, see Managing test cases separately in Deployment Manager.
6. Optional:
To rebase your development application to obtain the most recently committed rulesets after you merge
your branches, configure Pega Platform so that you can use rule rebasing.
For either new Deployment Manager installations or upgrades, you must configure settings on the orchestration
server so that users can receive email notifications. For more information, see Configuring email accounts on the
orchestration server.
Additionally, you can configure Jenkins if you are using Jenkins tasks in a pipeline. For more information, see
Configuring Jenkins.
Deployment Manager provides the Pega-Pipeline-CD email account and the DMEmailListener email listener. If
you are configuring email accounts for the first time, specify your details for this account in Pega Platform.
For more information, see .
Configuring Jenkins
If you are using a Run Jenkins step task in your pipeline, configure Jenkins so that it can communicate with
the orchestration server.
Otherwise, if you are upgrading, do the appropriate steps for the email account that you are using. See one of the
following topics for more information:
Configuring an email account when upgrading and using the Pega-Pipeline-CD email account
Configuring email accounts when upgrading and using the Default email account.
For new Deployment Manager installations, on the orchestration server, configure the Pega-Pipeline-CD
email account so users can receive email notifications for events such as task completion or failure.
Configuring an email account when upgrading and using the Pega-Pipeline-CD email account
If you are upgrading to Deployment Manager 4.7.x and using the Pega-Pipeline-CD email account for sending
emails, the DMEmailListener email listener always listens to the Pega-Pipeline-CD account. If you are using a
different listener, you must delete it.
Configuring email accounts when upgrading and using the Default email account
If you are upgrading to Deployment Manager and using the Default email account, after you upgrade to
Deployment Manager 4.7.x, you must do certain steps so that you can send email notifications.
Emails are preconfigured with information about each notification type. For example, when a deployment
failure occurs, the email that is sent provides information, such as the pipeline name and URL of the system
on which the deployment failure occurred.
Configuring email accounts for new Deployment Manager
installations
For new Deployment Manager installations, on the orchestration server, configure the Pega-Pipeline-CD email
account so users can receive email notifications for events such as task completion or failure.
1. In the navigation pane of Dev Studio,click Records, and then click Integration-Resources Email Account .
2. Click Pega-Pipeline-CD.
3. In the Edit Email Account rule form, configure and save the email account.
For more information about configuring email accounts, see Creating an email account in Dev Studio.
Delete the listener that is listening to the Pega-Pipeline-CD account by doing the following steps:
1. In the header of Dev Studio, click Configure Integration Email Email listeners .
2. On the Email: Integration page, on the Email Listeners tab, click the listener that you want to delete.
3. Click Delete.
a. In the navigation pane of Dev Studio,, click Records, and then click Integration-Resources Email Account
.
b. Click Default.
c. On the Edit Email Account form, configure and save the email account.
For more information about configuring email accounts, see Creating an email account in Dev Studio
2. If you have an email listener that listens to the same email address that you configured in Deployment
Manager in the previous step, delete the listener to ensure that the DMEmailListener is listening to the email
account that you configured.
a. In the header of Dev Studio,, click Configure Integration Email Email listeners .
b. On the Email: Integration page, on the Email Listeners tab, click the listener that you want to delete.
c. Click Delete.
Configuring Jenkins
If you are using a Run Jenkins step task in your pipeline, configure Jenkins so that it can communicate with the
orchestration server.
1. On the orchestration server, create an authentication profile that uses Jenkins credentials.
If you are using a version of Jenkins earlier than 2.17.6, create an authentication profile on the
orchestration server that specifies the credentials to use.
1. Click Create Security Authentication Profile .
2. Enter a name, and then click Create and open.
3. In the User name field, enter Jenkins user ID.
4. Click Set password, enter the Jenkins password, and then click Submit.
5. Click the Preemptive authentication check box.
6. Click Save.
7. Go to step 4.
For more information about configuring authentication profiles, see Creating an authentication
profile.
If you are using Jenkins 2.17.6 or later and want to use an API token for authentication, go to step 2.
If you are using Jenkins 2.17.6 or later and want to use a Crumb Issuer for authentication, go to step 3.
2. If you are using Jenkins version 2.17.6 or later and want to use an API token for authentication, do the
following steps:
b. Click People, click the user who is running the Jenkins job, and then click Configure API token .
c. Generate the API token.
d. Create an authentication profile on the orchestration server by clicking Create Security Authentication
Profile .
f. Click Set password, enter the API token that you generated, and then click Submit.
h. Click Save.
i. Go to step 4.
For more information about configuring authentication profiles, see Creating an authentication profile.
3. If you are using Jenkins version 2.17.6 or later and want to use a Crumb Issuer for authentication, do the
following steps:
b. Click Manage Jenkins Manage Plugins and select the check box for the Strict Crumb Issuer plug-in.
d. In the CSRF protection section, in the Crumb Issuer list, select Strict Crumb Issuer.
e. Click Advanced, and then clear the Check the session ID check box.
f. Click Save.
g. Create an authentication profile on the orchestration server by clicking Create Security Authentication
Profile .
i. Click Set password, enter the Jenkins password, and then click Submit.
k. Click Save.
l. Go to step 4.
For more information about configuring authentication profiles, see Creating an authentication profile.
7. On the General tab, select the This project is parameterized check box.
9. To add parameters that you can use in Run Jenkins step tasks in the pipeline, click Add parameter, select
String parameter, and enter the string of the parameter. The system automatically populates these values in
Jenkins tasks. You can add any of the following strings:
a. If you are using Jenkins tasks for continuous integration (you are using branches), add any of the
following strings:
PipelineName: Pipeline name on which the Run Jenkins step task is configured.
ApplicationName: Application for which the pipeline is configured.
RepositoryName: Repository to which the merged branch is published.
BranchName: Branch for which the Run Jenkins step task is configured.
BranchFilePath: Location of the branch.
OrchestratorURL: URL of the orchestration server. Add this parameter to stop a pipeline when
the Run Jenkins step fails in a pipeline.
PipelineID: ID of the pipeline on which the Run Jenkins step task is configured.
b. If you are using Run Jenkins step tasks for continuous delivery (in staging, QA, or production
environments), add any of the following strings:
PipelineName: Pipeline name on which the Run Jenkins step task is configured.
RepositoryName: Repository that the Deploy task uses for the stage (for example, staging) on
which the Run Jenkins step task is configured.
DeploymentID: ID of the current deployment.
DeploymentArtifactName: Artifact name that the Deploy task uses on the stage on which the
Run Jenkins step task is configured.
StartedBy: ID of the operator who started the deployment.
CurrentStage: Name of the stage on which the Run Jenkins step task is configured.
ArtifactPath: Full path to the artifact that the Deploy task uses.
OrchestratorURL: URL of the orchestration server. Add this parameter to stop a pipeline when
the Run Jenkins step fails in a pipeline.
PipelineID: ID of the pipeline on which the Run Jenkins step task is configured. Add this parameter
to stop a pipeline when the Run Jenkins step task fails in a pipeline.
10. In the Build Triggers section, select the Trigger builds remotely check box.
11. In the Authentication Token field, select the token that you want to use when you start Jenkins jobs remotely.
12. In the Build Environment section, select the Use Secret text(s) or file(s) check box.
a. Click Add, and then select User name and password (conjoined).
e. In the Add credentials dialog box, in the Username field, enter the operator ID of the release manager
operator that is configured on the orchestration server.
g. Click Save.
15. If Jenkins is running on Microsoft Windows, add the following post-build tasks:
a. Click Add post-build action, and then select Post build task.
b. In the Post-Build Actionssection, in the Log text field, enter a unique string for the message that is
displayed in the build console output when a build fails, for example BUILD FAILURE.
c. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%" .
e. In the Post-Build Actions section, in the Log text field, enter a unique string for the message that is
displayed in the build console output when a build is successful, for example BUILD SUCCESS.
f. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"%BuildID%\"}"
"%CallBackURL%"
g. Click Save.
h. Go to step 17.
16. If Jenkins is running on Linux, add the following post-build tasks. Use the dollar sign ($) instead of the percent
sign (%) to access the environment variables:
a. Click Add post-build action, and then select Post build task.
b. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build fails, for example BUILD FAILURE.
c. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
e. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build is successful, for example BUILD SUCCESS.
f. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
g. Click Save.
h. Go to step 17.
17. To stop a pipeline deployment if a Jenkins build fails, add a post-build script:
a. Click Add post-build action, and then select Post build task.
b. In the Log text field, enter a unique string for the message that is displayed in the build console output
when a build fails, for example JENKINS BUILD FAILURE.
c. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X PUT --data "{"AbortNote":"Aborted
from jenkins job"}" %OrchestratorURL%/PRRestService/cicd/v1/pipelines/%PipelineID%/builds/%DeploymentID%/abort
d. Click Save.
On the orchestration server, release managers use the Deployment Manager landing page to configure CI/CD
pipelines for their Pega Platform applications. The landing page displays all the running and queued application
deployments, branches that are to be merged, and reports that provide information about your DevOps
environment such as key performance indicators (KPIs).
Note: These topics describes the features for the latest version of Deployment Manager 4.8.x.
Note: To use notifications, you must install or upgrade to Pega 8.1.3 on the orchestration server.
For more information about using Deployment Manager and data migration pipelines, see Exporting and
importing simulation data automatically with Deployment Manager.
Deployment Manager provides a dedicated portal from which you can access features.
If your role has the appropriate permission, you can access Dev Studio from within Deployment Manager.
You can switch to Dev Studio to access features such as additional tools to troubleshoot issues. You can also
open, modify, and create repositories and authentication profiles.
Define roles and users to manage which users can access Deployment Manager and which features they can
access. For example, you can create a role that does not permit users to delete pipelines for a specific
application.
You can enable notifications to receive updates about the events that occur in your pipeline. For example,
you can choose to receive emails about whether unit tests failed or succeeded. You can receive notifications
in the Deployment Manager notifications gadget, through email, or both. By default, all notifications are
enabled for users who are configured in Deployment Manager.
When you add a pipeline, you specify merge criteria and configure stages and steps in the continuous
delivery workflow. For example, you can specify that a branch must be peer-reviewed before it can be
merged, and you can specify that Pega unit tests must be run after a branch is merged and is in the QA
stage of the pipeline.
You can open the systems in your pipeline and log in to the Pega Platform instances on each system. For
example, you can access the system on which the QA stage is installed.
You can filter the pipelines that the dashboard displays by application name, version, and pipeline
deployment status. By filtering pipelines, the dashboard displays only the information that is relevant to you.
You can view the status of the merge requests for a pipeline to gain more visibility into the status of your
pipeline. For example, you can see whether a branch was merged in a deployment and when it was merged.
Deployment reports provide information about a specific deployment. You can view information such as the
number of tasks that you configured on a deployment that have been completed and when each task started
and ended.
Starting deployments
You can start deployments in a number of ways. For example, you can start a deployment manually if you
are not using branches, by submitting a branch into the Merge Branches wizard, or by publishing application
changes in App Studio to create a patch version of your application. Your user role determines if you can
start a deployment.
Pausing a deployment
When you pause a deployment, the pipeline completes the task that it is running, and stops the deployment
at the next step.
Stopping a deployment
If a deployment has errors, the pipeline stops processing on it. You can perform actions on it, such as rolling
back the deployment or skipping the step on which the error occurred.
Deployment Manager provides several features that help you troubleshoot and resolve issues with your
pipeline.
If a manual step is configured on a stage, the deployment pauses when it reaches the step, and you can
either complete it or reject it. For example, if a user was assigned a task and completed it, you can complete
the task to continue the deployment. Deployment Manager also sends you an email when there is a manual
step in the pipeline. You can complete or reject a step either within the pipeline or through email.
You can manage aged updates in a number of ways such as importing them, skipping the import, or
manually deploying applications. Managing aged updates gives you more flexibility in how you deploy
application changes.
You can view, download, and delete application packages in repositories that are on the orchestration server.
If you are using Deployment Manager on Pega Cloud Services, application packages that you have deployed
to cloud repositories are stored on Pega Cloud Services. To manage your cloud storage space, you can
download and permanently delete the packages.
If your role has the appropriate permissions, you can archive inactive pipelines so that they are not displayed
on the Deployment Manager landing page.
If your role has the appropriate permissions, you can disable a pipeline on which errors continuously cause a
deployment to fail. Disabling a pipeline prevents branch merging, but you can still view, edit, and stop
deployments on a disabled pipeline.
When you delete a pipeline, its associated application packages are not removed from the repositories that
the pipeline is configured to use.
To log in to Deployment Manager, on the orchestration server, enter the DMReleaseAdmin operator ID and the
password that you specified for it.
For more information on enabling a role to access Dev Studio, see Providing access to the Dev Studio portal.
Related Content
Article
Deployment Manager provides two default roles, which you cannot modify or delete, that define privileges for
super administrators and application administrators. Privileges for super administrators are applied across all
applications, and privileges for application administrators are applied to specific applications. Super
administrators can also add roles and specify the privileges to assign to them. Super administrators and
application administrators can add users and assign them access to the applications that they manage.
You can create roles that have specific privileges and then assign users to those roles to manager
Deployment Manager users. To use roles and privileges, you must first create the
EnableAttributeBasedSecurity dynamic system setting.
If you are a super administrator, you can add and modify roles. Users within a role share defined
responsibilities such as starting a pipeline.
Deployment Manager provides a dedicated portal from which you can access features. From within
Deployment Manager, when you configure pipeline details, you can open, modify, and create repositories
and authentication profiles in Dev Studio if you have permissions to use the Dev Studio portal.
If you are a super administrator or application administrator, you can add users to Deployment Manager and
specify their roles. Only super administrators can create other super administrators or application
administrators who can access one or more applications. Application administrators can create other
application administrators for the applications that they manage.
Super administrators can give other users super administrative privileges or assign them as application
administrators to any application. Application administrators can assign other users as application
administrators for the applications that they manage.
You can modify your own user details, such as first and last name, and you can change your password.
Deleting users
If you are a super administrator or application administrator, you can delete users for the applications that
you manage.
1. In the header of Dev Studio, click Create SysAdmin Dynamic System Settings .
7. Click Save.
If you are a super administrator, add or modify a role by doing the following steps:
1. In the navigation pane of Deployment Manager click Users, and then click Roles and privileges.
3. In the Add role or Edit role dialog box, in the Name field, enter a name for the role.
5. Click Submit.
To provide access to the Dev Studio portal for a role, complete the following steps:
1. In the navigation pane of Deployment Manager, click Users, and then click Roles and privileges.
3. In the Add role or Edit Role dialog box, in the Name field, enter a name for the role.
5. Click Submit.
Result: If you specify Dev Studio as a default portal for the PegaDeploymentManager:Administrators access
group, all the users that you add in the Deployment Manager portal can access Dev Studio.
1. In the navigation pane of Deployment Manager click Users, and then click People.
3. In the Add user dialog box, click the User field, and do one of the following actions:
Press the Down arrow key and select the user that you want to add.
Enter an email address.
4. Click Add.
5. From the Role list, select the role to assign to the user.
6. If you selected the App admin role or a custom role, in the Applications field, enter the application name that
the user can access.
7. Click Send invite to send an email, which contains the user name and a randomly generated password for
the user to log in to Deployment Manager with, to the user.
1. In the navigation pane of Deployment Manager click Users, and then click People.
3. In the Roles and privileges section, modify the user role and applications that they can access, as
appropriate.
4. Click Save.
1. In the navigation pane of Deployment Manager click Users, and then click People.
3. In the Personal details section, modify your name, email address, and phone number, as appropriate.
b. In the Change operator ID dialog box, enter your new password, reenter it to confirm it, and then
click Submit.
5. Click Save.
Deleting users
If you are a super administrator or application administrator, you can delete users for the applications that you
manage.
1. In the navigation panel of Deployment Manager, click Users, and then click People.
2. On the People page, click the Delete icon for the user that you want to delete.
By default, all notifications are enabled for users who are configured in Deployment Manager.
Receiving email notifications requires that an email account is configured on the orchestration server. You
can view and update your email settings in Deployment Manager.
Creating custom Deployment Manager notification channels
You can extend Deployment Manager notification capabilities by creating custom notification channels. For
example, you can send text messages to mobile devices when tasks start, stop, and are unsuccessful.
Managing notifications
Enable and receive notifications so that you can remain informed about important tasks in your pipeline. For
example, you can receive emails when certain tasks fail.
Changing your email settings requires access to Dev Studio, so your user role must have permission to access
Dev Studio. For more information, see Understanding roles and users.
a. At the top of the Settings: Email configuration page, click Dev Studio.
b. In the Edit Email Account form, configure and save the email account that you want to use to receive
notifications.
c. In the bottom left corner of Dev Studio, click Back to Deployment Manager to return to the Deployment
Manager portal.
2. Add the application ruleset, which contains the channel that you created, to the Deployment Manager
application.
a. In the header of Dev Studio, click Deployment Manager, and then click Definition.
b. On the Edit Application rule form, in the Application rulesets section, click Add ruleset.
c. Press the Down arrow key and select the ruleset and version that contains the custom notification
channel.
3. Enable the channel that you created on the appropriate notifications by saving the notification in the
application ruleset that contains the channel.
For example: If you want to use the Mobile channel for the pyStartDeployment notification, save the
pyStartDeployment notification in the application ruleset that contains the Mobile channel.
c. On the Channel configurations page, select the channel that you want to use.
d. Save the rule form.
When notifications are enabled, you can receive notifications about the events that occur in your pipeline,
such as when tasks start or stop. You can receive notifications through email, the Deployment Manager
notifications gadget, or both. You can also create custom notification channels to meet application
requirements such as sending notifications as phone text messages or as push notifications on mobile
devices.
Deployment Manager provides the following notifications to which you can add channels:
pyAbortDeployment
pyTaskFailure
pyTaskFailure
pyTaskCompletion
pyStartDeployment
pyStageCompletion
pySchemaChange
pyDeploymentCompletion
pyAgedUpdateActionTaken
pyAgedUpdateActionRequired
Managing notifications
Enable and receive notifications so that you can remain informed about important tasks in your pipeline. For
example, you can receive emails when certain tasks fail.
To enable notifications and select the notifications that you want to receive, do the following steps:
5. Click Submit.
You can create multiple pipelines for one version of an application. For example, you can use multiple pipelines in
the following scenarios:
To move a deployment to production separately from the rest of the pipeline. You can then create a pipeline
that has only a production stage or development and production stages.
To use parallel development and hotfix life cycles for your application.
If you are using Pega Cloud Services, when you add a pipeline, you specify details such as the application
name and version for the pipeline. Many fields are populated by default, such as the URL of your
development system and product rule name and version.
When you add a pipeline on premises, you define all the stages and tasks that you want to do on each
system. For example, if you are using branches, you can start a build when a branch is merged. If you are
using a QA system, you can run test tasks to validate application data.
You can modify the details of your pipeline, such as configuring tasks, updating the repositories that the
pipeline uses, and modifying the URLs of the systems in your environment. You cannot modify information if
your pipeline is running.
2. Click New.
3. Specify the details of the application for which you are creating the pipeline.
a. To change the URL of your development system, which is populated by default with your development
system URL, in the Development environment field, press the Down arrow key and select the URL.
This is the system on which the product rule that defines the application package that moves through
the repository is located.
b. In the Application field, press the Down arrow key and select the name of the application.
c. In the Version field, press the Down arrow key and select the application version.
d. Click the Access group field and select the access group for which pipeline tasks are run.
This access group must be present on all the candidate systems and have at least the sysadmin4 role.
Ensure that the access group is correctly pointing to the application name and version that is
configured in the pipeline.
e. In the Pipeline name field, enter a unique name for the pipeline.
4. If you are using a separate product rule to manage test cases, to deploy a test case, in the Application test
cases section, select the Deploy test applications check box; then, complete the following steps:
a. In the Test application field, enter the name of the test application.
b. In the Version field, enter the version of the test case product rule.
c. In the Access group field, enter the access group for which test cases are run.
d. In the Product rule field, enter the name of the test case product rule.
e. From the Deploy until field, select the pipeline stage until the test case product rule will be deployed.
Note: When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests,
Enable test coverage, and Verify test coverage tasks are run for the access group that is specified in
this section.
For the Run Pega scenario tests task, the user name that you provide should belong to the access group
that is associated with the test application.
5. To change product rule that defines the contents of the application, the Product rule field, enter the name of
the product rule that defines the contents of the application, which is populated by default with the
application name.
6. To change the product rule version, in Version field, enter the version, which is populated by default with the
application version.
7. Click Create.
Result: The system adds tasks, which you cannot delete, to the pipeline that are required to successfully
run a workflow, for example, Deploy and Generate Artifact. For Pega Cloud Services, it also adds mandatory
tasks that must be run on the pipeline, for example, the Check guardrail compliance task and Verify security
checklist task.
8. Add tasks that you want to perform on your pipeline, such as Pega unit testing.
For more information, see Modifying stages and tasks in the pipeline.
2. Click New.
3. Specify the details of the application for which you are creating the pipeline.
a. In the Development environment field, enter the URL of the development system.
This is the system on which the product rule that defines the application package that moves through
the repository is located.
b. In the Application field, press the Down arrow key and select the name of the application.
c. In the Version field, press the Down arrow key and select the application version.
d. In the Access group field, press the Down arrow key and select the access group for which pipeline
tasks are run.
This access group must be present on all the candidate systems and have at least the sysadmin4 role.
e. In the Pipeline name field, enter a unique name for the pipeline.
f. In the Product rule field, enter the name of the product rule that defines the contents of the application.
4. If you are using a separate product rule to manage test cases, in the Application test cases section, to deploy
a test case, select the Deploy test applications check box; then, complete the following steps:
a. In the Test application field, enter the name of the test application.
b. In the Version field, enter the version of the test case product rule.
c. In the Access group field, enter the access group for which test cases are run. Ensure that the access
group is correctly pointing to the application name and version that is configured in the pipeline.
d. In the Product rule field, enter the name of the test case product rule.
e. From the Deploy until field, select the pipeline stage until which the test case product rule will be
deployed.
When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests, Enable
test coverage, and Verify test coverage tasks are run for the access group that is specified in this
section.
For the Run Pega scenario tests task, the user name that you provide should belong to the access group
that is associated with the test application.
b. In the Application name field, press the Down arrow key and select the application name.
c. In the Pipeline field, press the Down arrow key and select the pipeline.
d. In the Deployment field, press the Down arrow key and select the deployment that contains the
production-ready artifact of the dependent application.
If you want the latest artifact of the dependent application to be automatically populated, select latest.
For more information about dependent applications, see Managing application dependencies.
For more information on updating existing dependencies, see Updating application dependencies in
Deployment Manager.
a. Click Next.
6. In the Environment details section, in the Stages section, specify the URL of each candidate system and the
authentication profile that each system uses to communicate with the orchestration system.
a. In the Environments field for the system, press the Down arrow key and select the URL of the system.
b. If you are using your own authentication profiles, in the Authentication field for the system, press the
Down arrow key and select the authentication profile that you want to communicate from the
orchestration server to the system.
By default, the fields are populated with the DMAppAdmin authentication profile.
7. In the Artifact management section, specify the development and production repositories through which the
product rule that contains application contents moves through the pipeline.
8. In the Development repository field, press the Down arrow key and select the development repository.
9. In the Production repository field, press the Down arrow key and select the production repository.
10. In the External orchestration server section, if you are using a Jenkins step in a pipeline, specify the Jenkins
details.
b. In the Authentication profile field, press the Down arrow key and select the authentication profile on the
orchestration server that specifies the Jenkins credentials to use for Jenkins jobs.
If you are not using branches, click the No radio button, and then go to step 15.
If you are using branches, go to step 14.
To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
a. In the Password field, enter the password that locks the rulesets on the development system.
Result: The system adds tasks, which you cannot delete, to the pipeline that are required to successfully
run a workflow, for example, Deploy and Generate Artifact. The system also adds other tasks to enforce best
practices such as Check guardrail compliance and Verify security checklist.
15. To specify that a branch must meet a compliance score before it can be merged:
c. In the Weighted compliance score field, enter the minimum required compliance score.
d. Click Submit.
For more information about compliance scores, see Compliance score logic
c. Click Submit.
17. To run Pega unit tests on the branches for the pipeline application or for an application that is associated
with an access group before it can be merged:
c. To run all the Pega unit tests for an application that is associated with an access group, in the Access
Group field, enter the access group.
d. Click Submit.
For more information about creating Pega unit tests, see Creating Pega unit test cases.
Result:
When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests, Enable test
coverage, and Verify test coverage tasks are run for the access group that is specified in the Application test
cases section.
For the Run Pega scenario tests task, the user name that you provide should belong to the access group that
is associated with the test application.
18. To start a deployment automatically when a branch is merged, click the Trigger deployment on merge check
box.
Do not select this check box if you want to manually start deployments.
19. Clear a check box for a deployment life cycle stage to skip it.
20. In the Continuous Deployment section, specify the tasks to be performed during each stage of the pipeline.
See the following topics for more information:
Running Pega unit tests by adding the Run Pega unit tests task
Running Jenkins steps by adding the Run Jenkins step task
Specifying that an application meet a compliance score by adding the Check guardrail compliance score
task
Ensuring that the Application Security Checklist is completed by adding the Verify security checklist
task
Starting test coverage by adding the Enable test coverage task
Stopping test coverage by adding the Validate test coverage task
Running Pega scenario tests by adding the Run Pega scenario tests task
Refreshing application quality by adding the Refresh application quality task
Modifying the Approve for production task
21. Clear the Production ready check box if you do not want to generate an application package, which is sent to
the production repository.
You cannot clear this check box if you are using a production stage in the life cycle.
If you use Pega unit tests to validate application data, add the Pega unit testing task on the pipeline stage
where you want to run it. For example, you can run Pega unit tests on a QA system.
If you are using Jenkins to perform tasks in your pipeline, you can add the Jenkins task to the stage on which
you want it to run.
Use manual steps so that users must take an action before a pipeline deployment can continue. Users can
either accept the task to continue the deployment or reject the task to stop it.
You can use the Check guardrail compliance score task so that an application must meet a compliance score
for the deployment to continue. The default value is 95, which you can modify.
You can start another pipeline by adding the Trigger deployment task to a stage in your current pipeline. By
starting another pipeline from a current pipeline, you can add more stages to your pipeline.
For your pipeline to comply with security best practices, you can add a task so that to ensure that all the
steps in Application Security Checklist are performed.
Add the Enable test coverage task to start test coverage. Starting and stopping test coverage generates a
report that identifies the executable rules in your application that are either covered or not covered by tests.
As a best practice, to ensure application quality, you should test all the rules in your application for which
testing is supported.
Add this task to stop a test coverage session. Starting and stopping test coverage generates a report that
identifies the executable rules in your application that are either covered or not covered by tests. As a best
practice, to ensure application quality, you should test all the rules in your application for which testing is
supported.
Running Pega scenario tests by adding the Run Pega scenario tests task
If you are using Pega scenario tasks, you can run them in your pipeline by using the Run Pega scenario tests
task. Deployment Manager supports Selenium 3.141.59.
To refresh the Application Quality dashboard, which provides information about the health of your
application, on the candidate system, add the Refresh application quality task. You can refresh the
dashboard after running Pega unit tests, checking guardrail compliance, running Pega scenario tests, and
starting or stopping test coverage.
The Approve for production task is added to the stage before production. Use this task if you want a user to
approve application changes before those changes are send to production.
Running Pega unit tests by adding the Run Pega unit tests task
If you use Pega unit tests to validate application data, add the Pega unit testing task on the pipeline stage where
you want to run it. For example, you can run Pega unit tests on a QA system.
When you use separate product rules for test cases and run a pipeline, the Pega unit testing task is run for the
access group that is specified in the Application test cases section, which you configure when you add or modify a
pipeline.
To run Pega unit tests for either the pipeline application or for an application that is associated with an access
group, do the following steps:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
To run all the Pega unit tests that are in a Pega unit suite for the pipeline application, in the Test Suite
ID field, enter the pxInsName of the test suite.
You can find this value in the XML document that comprises the test suite by clicking, in Dev Studio,
Actions XML on the Edit Test Suite form. If you do not specify a test suite, all the Pega unit tests for the
pipeline application are run.
To run all the Pega unit tests for an application that is associated with an access group, in the Access
Group field, enter the access group.
For more information about creating Pega unit tests, see Creating Pega unit test cases.
4. Click Submit.
5. Continue configuring your pipeline. For more information, see one of the following topics:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. In the Job name field, enter the name of the Jenkins job (which is the name of the Jenkins deployment) that
you want to run.
5. In the Parameters field, enter parameters, if any, to send to the Jenkins job.
6. Click Submit.
7. Continue configuring your pipeline. For more information, see one of the following topics:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. In the Job name field, enter text that describes the action that you want the user to take.
4. In the Assigned to field, press the Down arrow key and select the operator ID to assign the task to.
5. Click Submit.
6. Continue configuring your pipeline. For more information, see one of the following topics:
To specify that an application must meet a compliance score, do the following steps:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. In the Weighted compliance score field, enter the minimum required compliance score.
4. Continue configuring your pipeline. For more information, see one of the following topics:
To add the Trigger deployment task to a stage in your pipeline, perform the following steps:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. In the Application name field, press the Down arrow key, and then select the application that you want to
deploy.
4. In the Pipeline name field, press the Down arrow key and, then select the pipeline that you want to start.
5. If you want to deploy the artifact that you are deploying in the current pipeline, select the Deploy current
artifact check box. Otherwise, a new application is deployed on the pipeline.
6. Click Submit.
Before you begin: You must log in to the system for which this task is configured, and then mark all the tasks in
the Application Security checklist as completed for the pipeline application. For more information about
completing the checklist, see Preparing your application for secure deployment.
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. Click Submit.
4. Continue configuring your pipeline. For more information, see one of the following topics:
For more information about application-level coverage reports, see Generating an application-level test coverage
report.
When you use separate product rules for test cases and run a pipeline, the Enable test coverage task is run for
the access group that is specified in the Application test cases section, which you configure when you add or
modify a pipeline.
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. Select the Start a new session check box to start a test coverage session every time that the pipeline runs
the deployment. If you do not select this check box, if a test coverage session is already running, the pipeline
pauses and returns an error.
4. Click Submit.
5. Continue configuring your pipeline. For more information, see one of the following topics:
Related Content
Article
Article
Article
Modifying application details
For more information about application-level coverage reports, see Generating an application-level test coverage
report.
When you use separate product rules for test cases and run a pipeline, the Validate test coverage task is run for
the access group that is specified in the Application test cases section, which you configure when you add or
modify a pipeline.
1. Add this task below the Enable test coverage task by doing one of the following actions:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. Click Submit.
4. Continue configuring your pipeline. For more information, see one of the following topics:
Running Pega scenario tests by adding the Run Pega scenario tests
task
If you are using Pega scenario tasks, you can run them in your pipeline by using the Run Pega scenario tests task.
Deployment Manager supports Selenium 3.141.59.
To add the Run Pega scenario tests task, do the following steps:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. In the User name field, enter the user name for the Pega Platform instance on which you are running
scenario tests.
Note: For the Run Pega scenario tests task, if you are using a separate product rule for a test application,
the user name that you provide should belong to the access group that is associated with the test
application.
5. From the Test Service Provider field, select the browser that you are using to run the scenario tests in the
pipeline.
a. In the Provider auth name field, enter the auth name that you you use to log in to the test service
provider.
b. In the Provider auth key field, enter the key for the test service provider.
c. Go to step 9.
8. If you selected Standalone, in the Provider URL field, enter the URL of the Selenium Standalone Server by
using one of the following:
9. In the Browser field, enter the browser that you are using to record scenario tests.
11. In the Platform field, enter the development platform that you are using to record tests.
12. In the Screen resolution field, enter the resolution at which are recording scenario tests.
14. Continue configuring your pipeline. For more information, see one of the following topics:
Click a task, click the More icon, and then click either Add task above or Add task below.
Click Add task in the stage.
3. Click Submit.
4. Continue configuring your pipeline. For more information, see one of the following topics:
3. In the Assign to field, press the Down arrow key and select the user who approves the application for
production.
An email is sent to this user, who can approve or reject application changes from within the email.
4. Click Submit.
5. Continue configuring your pipeline. For more information, see one of the following topics:
You can modify application details, such as the product rule that defines the content of the application that
moves through the pipeline.
You can modify the URLs of your development and candidate systems and the authentication profiles that
are used to communicate between those systems and the orchestration server.
Modifying repositories
You can modify the development and production repositories through which the product rule that contains
application contents moves through the pipeline. All the generated artifacts are archived in the Development
repository, and all the production-ready artifacts are archived in the Production repository.
If you are using a Jenkins step, specify details about the Jenkins server such as its URL.
If you are using branches in your application, specify options for merging branches into the base application.
You can modify the stages and the tasks that are performed in each stage of the pipeline. For example, you
can skip a stage or add tasks such as Pega unit testing to be done on the QA stage.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
4. In the Development environment field, enter the URL of the development system, which is the system on
which the product rule that defines the application package that moves through the repository is located.
5. In the Version field, press the Down arrow key and select the application version.
6. In the Product rule field, enter the product rule that defines the contents of the application.
8. f you are using a separate product rule to manage test cases, in the Application test cases section, complete
the following steps:
a. To deploy test cases, select the Deploy test applications check box.
b. In the Test application field, enter the name of the test application.
c. In the Version field, enter the version of the test case product rule.
d. In the Access group field, enter the access group for which test cases are run.
e. In the Product rule field, enter the name of the test case product rule.
f. From the Deploy until field, select the pipeline stage until which the test case product rule will be
deployed.
Note: When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests,
Enable test coverage, and Verify test coverage tasks are run for the access group that is specified in
this section.
For the Run Pega scenario tests task, the user name that you provide should belong to the access group
that is associated with the test application.
9. If the application depends on other applications, in the Dependencies section, add those applications.
a. Click Add.
b. In the Application name field, press the Down arrow key and select the application name.
c. In the Application version field, press the Down arrow key and select the application version.
d. In the Repository name field, press the Down arrow key and select the repository that contains the
production-ready artifact of the dependent application.
If you want the latest artifact of the dependent application to be automatically populated, ensure that
the repository that contains the production-ready artifact of the dependent application is configured to
support file updates.
e. In the Artifact name field, press the Down arrow key and select the artifact.
For more information about dependent applications, see Listing product dependencies.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
4. In the Environments field for the system, press the Down arrow key and select the URL of the system.
5. In the Authentication field for the system, press the Down arrow key and select the authentication profile
that you want to communicate from the orchestration server to the system.
6. Click Save.
Modifying repositories
You can modify the development and production repositories through which the product rule that contains
application contents moves through the pipeline. All the generated artifacts are archived in the development
repository, and all the production-ready artifacts are archived in the production repository.
You do not need to configure repositories if you are using Pega Cloud Services; you can use different repositories
other than the default ones that are provided.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
4. If you are using Deployment Manager on premises, or on Pega Cloud Services with default repositories,
complete the following tasks:
a. In the Application repository section, in the Development repository field, press the Down arrow key and
select the development repository
b. In the Production repository field, press the Down arrow key and select the production repository.
5. If you are using Deployment Manager on Pega Cloud Services and want to use different repositories other
than the default repositories, complete the following tasks:
b. In the Development repository field, press the Down arrow key and select the development repository.
c. In the Production repository field, press the Down arrow key and select the production repository.
6. Click Save.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
5. In the Authentication profile field, press the Down arrow key and select the authentication profile on the
orchestration server that specifies the Jenkins credentials to use for Jenkins jobs.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
4. If you are not using branches, click the No radio button, and then go to step 6.
a. Click Yes.
To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
To merge branches into a new ruleset, click New ruleset.
a. In the Password field, enter the password that locks the rulesets on the development system.
6. Click Save.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
3. To specify that a branch must meet a compliance score before it can be merged:
c. In the Weighted compliance score field, enter the minimum required compliance score.
d. Click Submit.
For more information about compliance scores, see Compliance score logic.
c. Click Submit.
5. To run Pega unit tests on the branches for the pipeline application or for an application that is associated
with an access group before it can be merged:
c. To run all the Pega unit tests for an application that is associated with an access group, in the Access
Group field, enter the access group.
d. Click Submit.
For more information about creating Pega unit tests, see Creating Pega unit test cases
6. To start a deployment automatically when a branch is merged, select the Trigger deployment on merge
check box. Do not select this check box if you want to manually start a deployment.
7. Clear a check box for a deployment life cycle stage to skip it.
8. In the Continuous Deployment section, specify the tasks to be performed during each stage of the pipeline.
See the following topics for more information:
Running Pega unit tests by adding the Run Pega unit tests task
Running Jenkins steps by adding the Run Jenkins step task
Specifying that an application meet a compliance score by adding the Check guardrail compliance score
task
Ensuring that the Application Security Checklist is completed by adding the Verify security checklist
task
Starting test coverage by adding the Enable test coverage task
Stopping test coverage by adding the Validate test coverage task
Running Pega scenario tests by adding the Run Pega scenario tests task
Refreshing application quality by adding the Refresh application quality task
Modifying the Approve for production task
9. Clear the Production ready check box if you do not want to generate an application package, which is sent to
the production repository. You cannot clear this check box if you are using a production stage in the life
cycle.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the pop-out arrow for the system that you want to open.
2. At the top of the dashboard, in the View lists, select the information with which you want to filter the display
of pipelines, and then click Apply.
2. In the Development stage, click X Merges in queue to view all the branches that are in the queue or for
which merge is in progress.
3. In the Merge requests ready for deployment dialog box, click View all merge requests to view all the
branches that are merged into the pipeline.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
To view the report for the current deployment, click the More icon, and then click View report.
To view the report for a previous deployment, expand the Deployment History pane and click Reports
for the appropriate deployment.
Reports provide a variety of information about all the deployments in your pipeline. For example, you can
view the frequency of new deployments to production.
Related Content
Article
2. From the list that appears in the top right of the Reports page, select whether you want to view reports for
all deployments, the last 20 deployments, or the last 50 deployments.
Starting deployments
You can start deployments in a number of ways. For example, you can start a deployment manually if you are not
using branches, by submitting a branch into the Merge Branches wizard, or by publishing application changes in
App Studio to create a patch version of your application. Your user role determines if you can start a deployment.
You can start a deployment manually if you are not using branches and are working directly in rulesets. You
can also start a deployment manually if you do not want deployments to start automatically when branches
are merged.
You can publish application changes that you make in App Studio to the pipeline. Publishing your changes
creates a patch version of the application and starts a deployment. For example, you can change a life cycle,
data model, or user interface elements in a screen and submit those changes to systems in the pipeline.
In either a branch-based or distributed, branch-based environment, you can immediately start a deployment
by submitting a branch into a pipeline in the Merge Branches wizard. The wizard displays the merge status
of branches so that you do not need to open Deployment Manager to view it.
Related Content
Article
1. If you do not want deployments to start automatically when branches are merged:
a. If the pipeline is not open, in the navigation pane, click PipelinesApplication pipelines, and then click the
name of the pipeline.
If the pipeline that you want to start is open, click Start deployment.
In the navigation pane, click Pipelines Application pipelines , and then click Start deployment for the
pipeline that you want to start.
3. In the Start deployment dialog box, start a new deployment or deploy an existing application by
completing one of the following actions:
4. To start a deployment and deploy a new application package, do the following steps:
b. Click Deploy.
c. Go to step 5.
5. To start a deployment and deploy an application package that is packaged in one of the previous production
deployments, do the following steps (only production-ready deployments can be used here, development
artifacts are not supported):
c. In the Pipeline field, press the Down arrow key and select the pipeline.
d. In the Deployment field, press the Down arrow key and select the previous deployment of that pipeline.
6. Click Deploy.
Ensure the following items are properly configured before making application changes in App Studio.
A product rule exists with the same name and version as the application being deployed. For more
information see Creating a product rule by using the create menu
A pipeline has been created in Deployment Manager for the application being deployed.
There is at least one unlocked ruleset in the application.
The users who will publish changes are logged into the application being deployed on the development
system.
The users who will publish changes have been granted a role in Deployment Manager that can start
deployments.
The RMURL dynamic system setting, which defines the URL of orchestration server, is configured on the
system.
Your pipeline should have at least one quality assurance or staging stage with a manual task so that you do not
deploy changes to production that have not been approved by stakeholders.
Before you begin: Before start a branch merge, do the following tasks.
1. Check all rules into their base rulesets before you merge them.
2. Check if there are any potential conflicts to address before merging branches. For more information, see
Viewing branch quality and branch contents.
3. As a best practice, lock a branch after development is complete so that no more changes can be made. For
more information, see Locking a branch.
Click Turn editing on, and then, in the navigation pane, click Settings Versions .
In the App Studio header, click Publish.
The Settings page displays the stages that are enabled in the application pipeline in Deployment Manager.
The available stages are, in order, quality assurance, staging, and production.
It also displays the application versions that are on each system. The version numbers are taken from the
number at the end of each application deployment name in Deployment Manager. For example, if a
deployment has a name of "MyNewApp:01_01_75", the dialog box displays "v75".
2. Submit an application from development to quality assurance or staging in your pipeline by completing the
following steps:
a. Click either Publish to QA or Publish to staging.
b. To add a comment, which will be published when you submit the application, add a comment in the
Publish confirmation dialog box.
c. If Agile Workbench has been configured, associate a bug or user story with the application, in the
Associated User stories/Bugs field, press the Down arrow key and select the bug or user story.
d. Click OK.
Result: Each unlocked ruleset version in your application is locked and rolled to the next highest
version and is packaged and imported into the system. The amount of time that publishing application
changes takes depends on the size of your application.
A new application is also copied from the application that is defined on the pipeline in Deployment
Manager. The application patch version is updated to reflect the version of the new rulesets; for
example, if the ruleset versions of the patch application are 01-01-15, the application version is updated
to be 01.01.15. A new product rule is also created.
In addition, this application is locked and cannot be unlocked. You can use this application to test
specific patch versions of your application on quality assurance or staging systems. You can also use it
to roll back a deployment.
3. Make changes to your application in the unlocked rulesets, which you can publish again into the pipeline. If
an application is already on the system, it is overridden by the new version that you publish.
4. If you configured a manual step, request that stakeholders review and test your changes. After they
communicate to you that they have completed testing, you can publish your changes to the next stage in
the pipeline.
5. Publish the application to the next stage in the pipeline by clicking the link that is displayed.
The name of the link is the Job name field of the manual task that is defined on the stage.
Result: If you do not have a manual task defined, the application automatically moves to the next stage.
To submit a branch into an application by using the Merge Branches wizard, perform the following steps:
1. In the navigation pane of Dev Studio,, click App, and then click Branches.
3. Click Proceed.
4. Click Switch to standard merge to switch to the Merge Branches wizard that you can use to merge branches
into target rulesets. For more information, see Merging branches into target rulesets .
5. In the Application pipelines section, from the Pipeline list, select the application for which the pipeline is
configured into which you want to merge branches.
6. In the Merge Description field, enter information that you want to capture about the merge.
7. In the Associated User stories/bugs field, press the Down arrow key, and then select the Agile Workbench
user story or bug that you want to associate with this branch merge.
8. Click Merge.
Result:
The system queues the branch for merging, generates a case ID for the merge, and runs the continuous
integration criteria that you specified.
If there are errors, and the merge is not successful, an email is sent to the operator ID of the release manager
that is specified on the orchestration server.
The branch is stored in the development repository and, after the merge is completed, Deployment Manager
deletes the branch from the development system. By storing branches in the development repository,
Deployment Manager keeps a history, which you can view, of the branches in a centralized location.
If your development system is appropriately configured, you can rebase your development application to obtain
the most recently committed rulesets after you merge your branches. For more information, see Rebasing rules to
obtain latest versions.
If you are using a separate product rule for a test application, after you start a deployment either by using the
Merge Branches wizard, the branches of both the target and test applications are merged in the pipeline.
You can submit a branch to your application and start the continuous integration portion of the pipeline when the
following criteria is met:
You can start a branch merge, which triggers a deployment, by using the Merge Branches wizard. You must
configure certain settings before you can submit a branch to your application.
You can start a branch merge, which triggers a deployment, by submitting a branch into an application in
the Merge Branches wizard. By using the wizard to start merges, you can start a deployment without
additional configuration.
To pause a deployment:
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
3. Click Pause.
Related Content
Article
Understanding roles and users
Stopping a deployment
If your role has the appropriate permissions, you can a deployment to prevent it from moving through the
pipeline.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
Related Content
Article
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the More icon, and then do one of the following actions:
To resume running the pipeline from the task, click Resume from current task.
To skip the step and continue running the pipeline, click Skip current task and continue.
To roll back to an earlier deployment, click Rollback.
Pega Platform 8.4 supports application-level rollback. To leverage this functionality, candidate and
orchestrator environments must be on Deployment Manager 4.8 or above. For older versions of
Deployment Manager (4.7.x and below) or users on Pega Platform 8.3 or below, rollback defaults to
the system-level.
You can:
View deployment logs for information about the completion status of operations.
Run diagnostics to verify that your environment is correctly configured.
Stop all deployments that are running on a pipeline.
Use a chatbot to obtain information about common issues.
View logs for a deployment to see the completion status of operations, for example, when a data simulation
is moved to the simulation environment. You can change the logging level to control which events are
displayed in the log.
Diagnosing a pipeline
You can diagnose your pipeline to troubleshoot issues and verify that your pipeline is configured properly
Stopping all deployments
You can stop all the deployments on a pipeline at once to quickly troubleshoot issues and resolve failed
pipelines.
Deployment Manager provides a chatbot that you can use to obtain information about common issues, such
as connectivity between systems, Jenkins configuration, and branch merging. After you enter your search
text, the chatbot provides you with relevant answers and links to more information.
1. In Dev Studio, on the appropriate candidate system, change the logging level to control which events the log
displays.
For example: For example, you can change logging levels of your deployment from INFO to DEBUG for
troubleshooting purposes. For more information, see Logging Level Settings tool.
2. To disable logging of new and updated rule and data instances in imported application packages, perform
the following steps:
1. On the candidate system for which you want to disable reporting, in the navigation pane of Admin
Studio, click Resources Log categories .
2. On the Log categories page, for the DeploymentManager.DeltaInstanceLogging log level, click the More
icon, and then click Change logging level.
3. In the Change pxBackgroundProcessing.Agents log level dialog box, in the Update log level of category
to list, select OFF.
4. Click Submit.
3. If the pipeline is not open, in the navigation pane, click Pipelines Application pipelines .
To view the log for the current deployment, click the More icon, and then click View logs.
To view the log for a previous deployment, expand the Deployment History pane, and then click Logs
for the deployment.
Diagnosing a pipeline
You can diagnose your pipeline to troubleshoot issues and verify that your pipeline is configured properly
For example, you can determine if the target application and product rule are in the development environment,
connectivity between systems and repositories is working, and pre-merge settings are correctly configured.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
Note: If the RMURL dynamic system setting is not configured, Deployment Manager displays a message that
you can disregard if you are not using branches, because you do not need to configure the dynamic system
setting.
Stopping all deployments
You can stop all the deployments on a pipeline at once to quickly troubleshoot issues and resolve failed pipelines.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
3. In the Abort open deployments dialog box, enter a reason for stopping the deployments, and then click
OK.
Before you begin: If the chatbot is disabled, enable it. For more information, see Enabling and disabling the
chatbot.
To use the Deployment Manager chatbot to help resolve issues, perform the following steps:
1. In the bottom right corner of the Deployment Manager portal, click the chatbot icon.
a. Click the appropriate link from the list of issues that the chatbot displays.
b. Enter text for which you want to receive more information, and then click Enter.
3. To clear the chatbot history, in the chatbot window, click the More icon, and then click Clear chat history.
Use the chatbot to obtain more information about common Deployment Manager issues, such as branch
merging and pipeline configuration. You can disable and enable the chatbot. By default, the chatbot is
enabled.
If you have the appropriate privileges, schema changes are automatically applied to the candidate system,
the application package is deployed to the candidate system, and the pipeline continues.
If you do not have the appropriate privileges, Deployment Manager generates an SQL file that lists the
schema changes and sends it to your email address. It also creates a manual step, pausing the pipeline, so
that you can apply the schema changes. After you complete the step, the pipeline continues. For more
information about completing a step, see Completing or rejecting a manual step.
You can also configure settings to automatically deploy schema changes so that you do not have to manually
apply them if you do not have the required privileges. For more information, see Configuring settings to
automatically deploy schema changes.
Your user role must have the appropriate permissions so that you can manage schema changes.
You can configure settings to automatically deploy schema changes that are in an application package that
is to be deployed on candidate systems. Configure these settings so that you do not have to apply schema
changes if you do not have the privileges to deploy them.
Related Content
Article
1. On the candidate system, in Pega Platform, set the AutoDBSchemaChanges dynamic system setting to true
to enable schema changes at the system level.
b. In the dialog box that appears for the search results, click AutoDBSchemaChanges.
d. Click Save.
2. Add the SchemaImport privilege to your access role to enable schema changes at the user level. For more
information, see Specifying privileges for an Access of Role to Object rule.
Result: These settings are applied sequentially. If the AutoDBSchemaChanges dynamic system setting is set to
false, you cannot deploy schema changes, even if you have the SchemaImport privilege.
For more information about the database/AutoDBSchemaChanges dynamic system setting, see Importing rules
and data by using a direct connection to the database.
Schema changes are also attached to the deployment report for the pipeline.
Related Content
Article
Deployment Manager also generates a manual step if there are schema changes in the application package that
the release manager must apply. For more information, see Schema changes in application packages.
To complete or reject a manual step within the deployment, do the following steps:
1. To complete or reject a manual step from within an email, click either Accept or Reject.
a. If the pipeline is not open, in the navigation pane, click Pipelines Application pipelines , and then click
the name of the pipeline.
To resolve the task so that the deployment continues through the pipeline, click Complete.
To reject the task so that the deployment does not proceed, click Reject.
Related Content
Article
Article
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click View aged updates to view a list of the rules and data instances, which are in the application package,
that are older than the instances that are on the system.
To import the older rule and data instances that are in the application package into the system, which
overwrites the newer versions that are on the system, click Overwrite aged updates.
To skip the import, click Skip aged updates.
To manually deploy the package from the Import wizard on the system, click Deploy manually and
resume. Deployment Manager does not run the Deploy step on the stage.
An aged update is a rule or data instance in an application package that is older than an instance that is on a
system to which you want to deploy the application package. By being able to import aged updates, skip the
import, or manually deploy your application changes, you now have more flexibility in determining the rules
that you want in your application and how you want to deploy them.
Related Content
Article
If you are using a separate product rule to manage a test application, the name of the product rule is the same as
that of the product rule with _Tests appended to it.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the pipeline for which you want to download or delete packages.
6. To delete a package, select the check boxes for the packages that you want to delete and then click Delete.
a. Click the More icon, and then click Archive for the pipeline that you want to archive.
Related Content
Article
a. Click the More icon, and then click Disable for the pipeline that you want to disable.
3. To enable a disabled pipeline, click the More icon, and then click Enable.
Related Content
Article
Deleting a pipeline
If your role has the appropriate permission, you can delete a pipeline. When you delete a pipeline, its associated
application packages are not removed from the repositories that the pipeline is configured to use.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Application
pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the More icon, and then click Delete for the pipeline that you want to delete.
Related Content
Article
When you use Deployment Manager 4.8.x in data migration pipelines, you automate exporting data from the
production environment and into the simulation environment. Data migration pipelines also require the following:
For more information about data migration pipelines, see these articles on Pega Community:
For information about using all the Deployment Manager 4.8.x features, see Configuring and running pipelines
with Deployment Manager 4.8.x.
Installing, upgrading, and configuring Deployment Manager 4.8.x for data migration pipelines
You can use Deployment Manager 4.6.x or later in data migration pipelines so that you can automatically
export simulation data from a production system and import it into a simulation system. For more
information about using Deployment Manager 4.8.x with data migration pipelines, see .
Create and run data migration pipelines in Deployment Manager 4.8.x to automatically export simulation
data from a production environment into a simulation environment in which you can test simulation data.
You can also use Deployment Manager to monitor and obtain information about your simulations, for
example, by running diagnostics to ensure that your environment configurations are correct and by and
viewing reports that display key performance indicators (KPIs).
To install, upgrade, and configure Deployment Manager on the simulation and production environments and on
the orchestration server, perform the following steps:
For first-time installations or upgrades from Deployment Manager 3.2.1, install Deployment Manager on
the candidate systems (production and simulation environments) and the orchestration server.
Upgrading is done automatically, and you do not need to do post-upgrade steps.
2. For first-time installations, configure communication between the orchestration server and the candidate
systems:
3. To move the orchestration server to a different environment, migrate your pipelines to the new orchestration
server, and then, on the new orchestration server, configure the URL of the new orchestration server. This
URL is used to update the task status on the orchestration server and diagnostics checks.
Creating a pipeline
Create a pipeline by defining the production and simulation environments and the application details for the
pipeline. By using a data migration pipeline, you can export and import simulation data automatically.
Modifying a pipeline
You can change the URLs of your production and simulation environments. You can also change the
application information for which you are creating the pipeline.
Diagnosing a pipeline
You can diagnose your pipeline to verify its configuration. For example, you can verify that the orchestration
system can connect to the production and simulation environments.
You can schedule a data migration pipeline to run during a specified period of time by creating and running
a job scheduler. The job scheduler runs a Deployment Manager activity (pzScheduleDataSyncPipeline) on the
specified pipeline, based on your configuration, such as weekly or monthly.
If you do not run a data migration pipeline based on a job scheduler, you can run it manually in Deployment
Manager.
Pausing a pipeline
Pause a pipeline to stop processing the data migration. When you pause a data migration, the pipeline
completes the current task and stops the data migration.
Stopping a pipeline
Stop a pipeline to stop data migrations from being exported and imported.
If a data migration has errors, the pipeline stops processing on it, and you can either resume or stop running
the pipeline.
Deleting a pipeline
When you delete a pipeline, its associated application packages are not deleted from the pipeline
repositories.
View the logs for a data migration to see the completion status of operations, for example, when a data
migration moves to a new stage. You can change the logging level to control the events are displayed in the
log. For example, you can change logging levels of your deployment from INFO to DEBUG for troubleshooting
purposes. For more information, see Logging Level Settings tool.
You can view a report for a specific data migration to gain more visibility into data migrations on a pipeline.
Reports provide a variety of information about all the data migrations in your pipeline so that you can gain
more visibility into data migration processing. For example, you can view the average time taken to
complete data migrations.
Creating a pipeline
Create a pipeline by defining the production and simulation environments and the application details for the
pipeline. By using a data migration pipeline, you can export and import simulation data automatically.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click New.
3. On the Environment Details page, if you are using Deployment Manager on-premises, configure
environment details.
This information is automatically populated if you are using Deployment in Pega Cloud Services
environments, but you can change it.
a. In the Environment fields, enter the URLs of the production and simulation environments.
b. If you are using your own authentication profiles, from the Auth profile lists, select the authentication
profiles that you want the orchestration server to use to communicate with the production and
simulation environments.
c. Click Next.
4. On the Application details page, specify the application information for which you are creating the
pipeline.
c. From the Access group list, select the access group for which you want to run pipeline tasks. This
access group must be present on the production and simulation environments and have at least the
sysadmin4 role.
e. Click Next.
Result: The Pipeline page displays the stages and tasks, which you cannot delete, that are in the pipeline.
5. Click Finish.
Modifying a pipeline
You can change the URLs of your production and simulation environments. You can also change the application
information for which you are creating the pipeline.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click Action Settings .
b. In the Environment fields, enter the URLs of the production and simulation environments.
4. To change the application information for which you are creating the pipeline, click Application details.
b. From the Access group list, select the access group for which you want to run pipeline tasks.
This access group must be present on the production and simulation environments and have at least
the sysadmin4 role.
5. Click Save.
Diagnosing a pipeline
You can diagnose your pipeline to verify its configuration. For example, you can verify that the orchestration
system can connect to the production and simulation environments.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
For more information about job scheduler rules, see Job Scheduler rules.
1. On the orchestration server, in the navigation panel of Dev Studio, click Records SysAdmin Job Scheduler .
2. On the Create Job Scheduler rule form, enter the label of the scheduler and select the ruleset into which to
save the job scheduler.
4. On the Edit Job Scheduler rule form, on the Definition tab, from the Runs on list, configure the job scheduler
to run on all or one nodes:
To run the job scheduler on all nodes in a cluster, click All associated nodes.
To run the job scheduler on only one node in a cluster, click Any one associated node.
5. From the Schedule list, select how often you want to start the job scheduler, and then specify the options for
it.
If you want to resolve the pzScheduleDataSyncPipeline activity in the context of Deployment Manager,
go to step 7.
If you want to resolve the activity in the context that is specified in the System Runtime Context, go to
step 8.
c. Go to step 9.
8. to resolve the activity in the context that is specified in the System Runtime Context:
b. Update the access group of the batch requestor type access group with the access group that can
access Deployment Manager; in the header of Dev Studio, clicking Configure System General .
c. On the System:General page, on the Requestors tab, click the BATCH requestor type.
d. On the Edit Requestor Type rule form, on the Definition tab, in the Access Group Name field, press the
Down arrow key and select the access group that can access Deployment Manager.
e. Click Save.
9. On the Job Schedule rule form, in the Class field, press the Down arrow key and select Pega-Pipeline-
DataSync.
10. In the Activity field, press the Down arrow key and select pzScheduleDataSyncPipeline.
11. Click the Parameters link that appears below the Activity field.
12. In the Activity Parameters dialog box, in the Parameter value field for the PipelineName parameter, enter
the data migration pipeline that the job scheduler runs.
13. In the Parameter value field for the ApplicationName parameter, enter the application that the data
migration pipeline is running.
If the pipeline for which you want to run a data migration is open, click Start data migration.
If the pipeline is not open, click Pipelines Data migration pipelines , and then click Start data migration.
Pausing a pipeline
Pause a pipeline to stop processing the data migration. When you pause a data migration, the pipeline completes
the current task and stops the data migration.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click Pause.
Stopping a pipeline
Stop a pipeline to stop data migrations from being exported and imported.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the More icon, and then clickAbort.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
To resume running the pipeline from the task, click Start data migration pipeline.
To stop running the pipeline, click Abort.
Deleting a pipeline
When you delete a pipeline, its associated application packages are not deleted from the pipeline repositories.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
2. Click the Delete icon for the pipeline that you want to delete.
3. Click Submit.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
To view the log for the current data migration, click the More icon, and then click View logs.
To view the log for a previous data migration, expand the Deployment History pane and click Logsfor
the appropriate deployment.
If the pipeline is not open, in the navigation pane of Deployment Manager, click Pipelines Data
migration pipelines , and then click the name of the pipeline.
If the pipeline is open, click the name of the pipeline.
To view the report for the current deployment, click the More icon, and then click View report.
To view the report for a previous deployment, expand the Deployment History pane and click Reports
for the appropriate deployment.
2. From the list that appears in the top right of the Reports page, select whether you want to view reports for
all deployments, the last 20 deployments, or the last 50 deployments.
Use Deployment Manager to configure and run continuous integration and delivery (CI/CD) workflows for
your Pega applications from within Pega Platform. You can create a standardized deployment process so
that you can deploy predictable, high-quality releases without using third-party tools.
With Deployment Manager, you can fully automate your CI/CD workflows, including branch merging, application
package generation, artifact management, and package promotion to different stages in the workflow.
Deployment Manager 3.4.x is compatible with Pega 7.4. You can download it for Pega Platform from the
Deployment Manager Pega Exchange page.
Note: These topics describe the features for the latest version of Deployment Manager 3.4.x.
Note: Each customer Virtual Private Cloud (VPC) on Pega Cloud Services has a dedicated orchestrator instance to
use Deployment Manager. You do not need to install Deployment Manager to use with your Pega Cloud Services
application.
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate
tasks and allow you to quickly deploy high-quality software to production.
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate
tasks so that you can quickly deploy high-quality software to production.
Note: This document describes the features for the latest version of Deployment Manager 3.4.x.
Install Deployment Manager 3.4.x on-premises. Each customer virtual private cloud (VPC) on Pega Cloud has
a dedicated orchestrator instance to use Deployment Manager. You do not need to install Deployment
Manager to use it with your Pega Cloud application. If you are upgrading from an earlier release to
Deployment Manager 3.4.x, contact Pegasystems Global Customer Support (GCS) to request a new version.
After you install Deployment Manager 3.4.x, you must do post-upgrade steps. Before you upgrade, ensure
that no deployments are running, have errors, or are paused.
Complete the following tasks to set up a pipeline for all supported CI/CD workflows. If you are using
branches, you must configure additional settings after you perform the required steps.
After you configure the orchestration server and all your candidate systems, configure additional settings so
that you can create pipelines if you are using branches in a distributed or non-distributed branch-based
environment.
As part of your pipeline, you can optionally send email notifications to users or configure Jenkins if you are
using a Jenkins task.
If you are using Deployment Manager on premises, complete the following steps to install it:
Note: If you are upgrading from Deployment Manger 3.2.1, after you import files on premises or Deployment
Manager 3.4.x is deployed on Pega Cloud Services, finish the upgrade immediately so that your pipelines work in
Deployment Manager 3.4.x.
2. Browse to the Deployment Manager Pega Marketplace page, and then download the
DeploymentManager03.0240x.zip file to your local disk on each system.
4. Use the Import wizard to import files into the appropriate systems. For more information about the Import
wizard, see Importing a file by using the Import wizard.
PegaDevOpsFoundation_03.04.0x.zip
PegaDeploymentManager_03.04.0x.zip
6. On the development, QA, staging, and production systems, import the PegaDevOpsFoundation_03.04.0x.zip
file.
7. If you are using a distributed development, on the remote development system, import the
PegaDevOpsFoundation_03.04.0x.zip file.
To upgrade to Deployment Manager 3.4.x either on Pega Cloud Services or on premises, perform the following
steps:
1. Enable default operators and configure authentication profiles on the orchestration server and candidate
systems. For more information, see Configuring authentication profiles on the orchestration server and
candidate systems.
2. On each candidate system, add the PegaDevOpsFoundation application to your application stack.
a. In the Designer Studio header, click the name of your application, and then click Definition.
c. In the Name field, press the Down arrow key and select PegaDevOpsFoundation.
d. In the Version field, press the Down arrow key and select the version of Deployment Manager that you
are using.
e. Click Save.
If you are upgrading from Deployment Manager 3.2.1, you do not need to do the rest of the steps in this
procedure or the required steps in the remainder of this document. If you are upgrading from earlier releases
and have pipelines configured, complete this procedure.
Note: If you are upgrading from Deployment Manager 3.2.1, you do not need to do the rest of the steps in
this procedure or the required configuration steps steps. If you are upgrading from earlier releases and have
pipelines configured, complete this procedure.
4. In Designer Studio, search for pxUpdatePipeline, and then click the activity in the dialog box that displays the
results.
a. In the Designer Studio header, click the name of your application, and then click Definition.
b. In the Edit Application rule form, on the Definition tab, in the Built on application section, for the
PegaDeploymentManager application, press the Down arrow key and select 03.04.01.
c. Click Save.
e. In the Available Source Ruleset(s) section, select the first open ruleset version that appears in the list,
and then click the Move icon.
Note: All your current pipelines are stored in the first open ruleset. If you modified this ruleset after you
created the application, select all the ruleset versions that contain pipeline data.
9. In the target RuleSet/Information section, in the Name field, press the Down arrow key and select Pipeline
Data.
11. For the Delete Source RuleSet(s) upon completion of merge? option, click No.
Result: Your pipelines are migrated to the Pega Deployment Manager application. Log out of the orchestration
server and log back in to it with the DMReleaseAdmin operator ID and the password that you specified for it.
Note: You do not need to perform any of the required configuration procedures.
Deployment Manager provides default operator IDs and authentication profiles. You must enable the default
operator IDs and configure the authentication profiles that the orchestration server uses to communicate
with the candidate systems.
The orchestration server is the system on which release managers configure and manage CI/CD pipelines.
Configure it before you use it in your pipeline.
Configure each system that is used for the development, QA, staging, and production stage in the pipeline.
If you are using Deployment Manager on-premises, create repositories on the orchestration server and all
candidate systems to move your application between all the systems in the pipeline. You can use a
supported repository type that is provided in Pega Platform, or you can create a custom repository type.
1. On the orchestration server, enable the DMReleaseAdmin operator ID and specify its password.
c. In the Designer Studio header, click the operator ID initials, and then click Operator.
f. Click Save.
h. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then
click Submit.
i. Clear the Force password change on next login check box if you do not want to change the password for
the DMReleaseAdmin operator ID the next time that you log in.
2. On each candidate system, update the DMReleaseAdmin authentication profile to use the new password. All
candidate systems use this authentication profile to communicate with the orchestration server about the
status of the tasks in the pipeline.
a. Log in to each candidate system with the DMAppAdmin user name and the password that you specified.
c. Click DMReleaseAdmin.
e. In the Password dialog box, enter the password, and then click Submit.
3. On each candidate system, which includes the development, QA, staging, and production systems, enable
the DMAppAdmin operator ID. If you want to create your own operator IDs, ensure that they point to the
PegaDevOpsFoundation application.
b. In the navigation pane of Designer Studio, click Records Organization Operator ID , and then click
DMAppAdmin.
c. In the header of Designer Studio, click the operator ID initials, and then click Operator.
f. Click Save.
h. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then
click Submit.
i. Clear the Force password change on next login check box if you do not want to change the password for
the DMReleaseAdmin operator ID the next time that you log in.
4. On the orchestration server, modify the DMAppAdmin authentication profile to use the new password. The
orchestration server uses this authentication profile to communicate with candidate systems so that it can
run tasks in the pipeline.
a. Log in to the orchestration server with the DMAppAdmin user name and the password that you
specified.
e. In the Password dialog box, enter the password, and then click Submit.
a. If you are upgrading to Deployment Manager 3.4.x, resume the upgrade procedure from step 2. For
more information, see Upgrading to Deployment Manager 3.4.x.
b. If you are not upgrading, continue the installation procedure. For more information, see Configuring the
orchestration server.
When you install Deployment Manager on all the systems in your pipeline, default applications, operator IDs,
and authentication profiles that communicate between the orchestration server and candidate systems are
also installed.
Note: The DMReleaseAdmin and DMAppAdmin operator IDs do not have default passwords.
1. If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd
service packages.
b. Click api.
c. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
e. Click cicd.
f. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
2. Configure the candidate systems in your pipeline.
1. On each candidate system, add the PegaDevOpsFoundation application to your application stack.
a. In the Designer Studio header, click the name of your application, and then click Definition.
c. In the Name field, press the Down arrow key and select PegaDevOpsFoundation.
d. In the Version field, press the Down arrow key and select the version of Deployment Manager that you
are using.
e. Click Save.
2. If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd
service packages.
b. Click api.
c. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
e. Click cicd.
f. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is
cleared.
3. To use a product rule for your target application, test application, or both, other than the default rules that
are created by the New Application wizard, on the development system, create product rules that define the
test application package and the target application package that will be moved through repositories in the
pipeline.
For more information, see Product rules: Completing the Create, Save As, or Specialization form.
When you use the New Application wizard, a default product rule is created that has the same name as your
application.
For more information, see Configuring repositories on the orchestration server and candidate systems.
If you are using Deployment Manager on Pega Cloud Services, default repositories are provided. If you want to use
repositories other than the ones provided, you can create your own.
For more information about creating a supported repository type, see Creating a repository connection.
For more information about creating a custom repository type, see Creating and using custom repository types for
Deployment Manager.
After you configure a pipeline, you can verify that the repository connects to the URL of the development and
production repositories by clicking Test Connectivity on the Repository rule form.
1. On the development system (in nondistributed environment) or the main development system (in a
distributed environment), create a dynamic system setting to define the URL of the orchestration server,
even if the orchestration server and the development system are the same system.
e. On the Settings tab, in the Value field, enter the URL of the orchestration server. Use this format:
http://hostname:port/prweb/PRRestService .
f. Click Save.
2. On either the development system (in a non-distributed environment) or the remote development system (in
a distributed environment), use the New Application wizard to create a new development application that
developers will log in to.
This application allows development teams to maintain a list of development branches without modifying the
definition of the target application.
3. On either the development system or remote development system, add the target application of the pipeline
as a built-on application layer of the development application.
b. In the Designer Studio header, click the name of your application, and then click Definition.
d. In the Name field, press the Down arrow key and select the name of the target application.
e. In the Version field, press the Down arrow key and select the target application version.
f. Click Save.
4. On either the development system or remote development system, lock the application rulesets to prevent
developers from making changes to rules after branches have been merged.
a. In the Designer Studio header, click the name of your application, and then click Definition.
b. In the Application rulesets section, click the Open icon for each ruleset that you want to lock.
5. To publish branches to a development system to start a branch to merge, configure a Pega repository.
It is recommended that you merge branches by using the Merge Branch wizard. However, you can publish a
branch to the remote development system to start a deployment. Publishing a branch when you have
multiple pipelines per application is not supported.
a. On either the development system or remote development system, in Designer Studio, enable Pega
repository types.
b. Create a new Pega repository type. For more information, see Creating a repository connection.
d. Ensure that the default access group of the operator that is configured for the authentication profile of
this repository points to the pipeline application on the development system (in a nondistributed
environment) or source development system (in a distributed environment).
You can optionally configure email notifications on the orchestration server. For example, users can receive
emails when pre-merge criteria are not met and the system cannot create a deployment.
Configuring Jenkins
To configure the orchestration server to send emails, complete the following steps:
1. Use the Email wizard to configure an email account and listener by clicking Designer Studio Integration Email
Email Wizard .
This email account sends notifications to users when events occur, for example, if there are merge conflicts.
For detailed information, see the procedure for “Configuring an email account that receives email and
creates or manages work” in Entering email information in the Email wizard
2. From the What would you like to do? list, select Receive an email and create/manage a work object.
3. From the What is the class of your work type? list, select Pega-Pipeline-CD.
4. From the What is your starting flow name? list, select NewWork.
5. From the What is your organization? list, select the organization that is associated with the work item.
6. In the What Ruleset? field, select the ruleset that contains the generated email service rule.
7. In the What RuleSet Version? field, select the version of the ruleset for the generated email service rule.
9. In the Email Account Name field, enter Pega-Pipeline-CD, which is the name of the email account that the listener
references for incoming and outgoing email.
10. In the Email Listener Name field, enter the name of the email listener.
Begin the name with a letter, and use only letters, numbers, the ampersand character (&), and hyphens.
11. In the Folder Name field, enter the name of the email folder that the listener monitors.
12. In the Service Package field, enter the name of the service package to be deployed.
Begin the name with a letter, and use only letters, numbers, and hyphens to form an identifier.
13. In the Service Class field, enter the service class name.
14. In the Requestor User ID field, press the Down arrow key, and select the operator ID of the release manager
operator.
15. In the Requestor Password field, enter the password for the release manager operator.
16. In the Requestor User ID field, enter the operator ID that the email service uses when it runs.
17. In the Password field, enter the password for the operator ID.
18. Click Next to continue the wizard and configure the service package.
For more information, see Configuring the service package in the Email wizard.
19. After you complete the wizard, enable the listener that you created in the Email Wizard.
Emails are also preconfigured with information about each notification type. For example, when a
deployment failure occurs, the email that is sent provides information, such as the pipeline name and URL of
the system on which the deployment failure occurred.
Deployment start – When a deployment starts, an email is sent to the release manager and, if you are using
branches, to the operator who started a deployment.
Deployment step failure – If any step in the deployment process is unsuccessful, the deployment pauses. An
email is sent to the release manager and, if you are using branches, to the operator who started the branch
merge.
Deployment step completion – When a step in a deployment process is completed, an email is sent to the
release manager and, if you are using branches, to the operator who started the branch merge.
Deployment completion – When a deployment is successfully completed, an email is sent to the release
manager and, if you are using branches, to the operator who started the branch merge.
Stage completion – When a stage in a deployment process is completed, an email is sent to the release
manager and, if you are using branches, to the operator who started the branch merge.
Stage failure – If a stage fails to be completed, an email is sent to the release manager and, if you are using
branches, to the operator who started the branch merge.
Manual tasks requiring approval – When a manual task requires email approval from a user, an email is sent
to the user, who can approve or reject the task from the email.
Stopped deployment – When a deployment is stopped, an email is sent to the release manager and, if you
are using branches, to the operator who started the branch merge.
Pega unit testing failure – If a Pega unit test cannot successfully run on a step in the deployment, an email is
sent to the release manager and, if you are using branches, to the operator who started the branch merge.
Pega unit testing success – If a Pega unit test is successfully run on a step in the deployment, an email is
sent to the release manager and, if you are using branches, to the operator who started the branch merge.
Schema changes required – If you do not have the required schema privileges to deploy the changes on
application packages that require those changes, an email is sent to the operator who started the
deployment.
Guardrail compliance score failure – If you are using the Check guardrail compliance task, and the
compliance score is less than the score that is specified in the task, an email with the score is sent to the
release manager.
Guardrail compliance score success – If you are using the Check guardrail compliance task, and the task is
successful, an email with the score is sent to the release manager.
Approve for production – If you are using the Approve for production task, which requires approval from a
user before application changes are deployed to production, an email is sent to the user. The user can reject
or approve the changes.
Verify security checklist failure – If you are using the Verify security checklist task, which requires that all
tasks be completed in the Application Security Checklist to ensure that the pipeline complies with security
best practices, the release manager receives an email.
Verify security checklist success – If you are using the Verify security checklist task, which requires that all
tasks be completed in the Application Security Checklist to ensure that the pipeline complies with security
best practices, the release manager receives an email.
Configuring Jenkins
If you are using a Jenkins task in your pipeline, configure Jenkins.
1. On the orchestration server, create an authentication profile that uses Jenkins credentials.
b. In the User name field, enter the user name of the Jenkins user.
c. Click Set password, enter the Jenkins password, and then click Submit.
e. Click Save.
2. Because the Jenkins task does not support Cross-Site Request Forgery (CSRF), disable it by completing the
following steps:
c. In the CSRF Protection section, clear the Prevent Cross Site Request Forgery exploits check box.
d. Click Save.
6. On the General tab, select the This project is parameterized check box.
8. In the Build Triggers section, select the Trigger builds remotely check box.
9. In the Authentication Token field, select the token that you want to use when you start Jenkins jobs remotely.
10. In the Build Environment section, select the Use Secret text(s) or file(s) check box.
a. Click Add, and then select User name and password (conjoined).
e. In the Add credentials dialog box, in the Username field, enter the operator ID of the release manager
operator that is configured on the orchestration server.
12. Configure information in the Post-Build Actions section, depending on your operating system:
13. If Jenkins is running on Microsoft Windows, add the following post-build tasks:
a. Click Add post-build action, and then select Post build task.
b. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build fails, for example BUILD FAILURE.
c. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%" .
e. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build is successful, for example BUILD SUCCESS.
f. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"%BuildID%\"}"
"%CallBackURL%"
g. Click Save.
14. If Jenkins is running on Linux, add the following post-build tasks. Use the dollar sign ($) instead of the percent
sign (%) to access the environment variables:
a. Click Add post-build action, and then select Post build task.
b. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build fails, for example BUILD FAILURE.
c. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
e. In the Log text field, enter a unique string that for the message that is displayed in the build console
output when a build is successful, for example BUILD SUCCESS.
f. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "
{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
g. Click Save.
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate tasks
and allow you to quickly deploy high-quality software to production.
On the orchestration server, release managers use the DevOps landing page to configure CI/CD pipelines for their
Pega Platform applications. The landing page displays all the running and queued application deployments,
branches that are to be merged, and reports that provide information about your DevOps environment such as
key performance indicators (KPIs).
Note: These topics describe the features for the latest version of Deployment Manager 3.4.x.
When you add a pipeline, you specify merge criteria and configure stages and steps in the continuous
delivery workflow. For example, you can specify that a branch must be peer-reviewed before it can be
merged, and you can specify that Pega unit tests must be run after a branch is merged and is in the QA
stage of the pipeline.
Manually starting a deployment in Deployment Manager
You can start a deployment manually if you are not using branches and are working directly in rulesets. You
can also start a deployment manually if you do not want deployments to start automatically when branches
are merged.
If you are using Deployment Manager in a distributed, branch-based environment and using multiple
pipelines per application, first export the branch to the source development system, and then merge it.
If a manual step is configured on a stage, the deployment pauses when it reaches the step, and you can
either complete it or reject it if your role has the appropriate permissions. For example, if a user was
assigned a task and completed it, you can complete the task in the pipeline to continue the deployment.
Deployment Manager also sends you an email when there is a manual step in the pipeline. You can complete
or reject a step either within the pipeline or through email.
If your role has the appropriate permissions, you can manage aged updates in a number of ways, such as
importing them, skipping the import, or manually deploying applications. Managing aged updates gives you
more flexibility in how you deploy application changes.
You can configure settings to automatically deploy schema changes that are in an application package that
is to be deployed on candidate systems. Configure these settings so that you do not have to apply schema
changes if you do not have the privileges to deploy them.
When you pause a deployment, the pipeline completes the task that it is running, and stops the deployment
at the next step. Your user role determines if you can pause a deployment.
Stopping a deployment
If your role has the appropriate permissions, you can a deployment to prevent it from moving through the
pipeline.
If a deployment has errors, the pipeline stops processing on it. You can perform actions such as rolling back
the deployment or skipping the step on which the error occurred.
You can view the status of all the branches that are in your pipeline. For example,you can see whether a
branch was merged in a deployment and when it was merged.
View logs for a deployment to see the completion status of operations, for example, when a deployment
moves from staging to production. When the Deploy task runs, the application package is imported in to the
candidate system. By default, logs record all the new rule and data instances and all the updated rule and
data instances that are in this application package. You can disable the logging of such rule and data types
and can change the logging level to control which events are displayed in the log.
Deployment reports provide information about a specific deployment. You can view information such as the
number of tasks that you configured on a deployment that have been completed and when each task started
and ended. If there were schema changes on the deployment, the report displays the schema changes.
Reports provide a variety of information about all the deployments in your pipeline. For example, you can
view the frequency of new deployments to production.
Deleting a pipeline
If your role has the appropriate permission, you can delete a pipeline. When you delete a pipeline, its
associated application packages are not removed from the repositories that the pipeline is configured to use.
You can view, download, and delete application packages in repositories that are on the orchestration server.
If you are using Deployment Manager on Pega Cloud Services, application packages that you have deployed
to cloud repositories are stored on Pega Cloud Services. To manage your cloud storage space, you can
download and permanently delete the packages.
You can create multiple pipelines for one version of an application. For example, you can use multiple pipelines in
the following scenarios:
To move a deployment to production separately from the rest of the pipeline. You can then create a pipeline
that has only a production stage or development and production stages.
To use parallel development and hotfix life cycles for your application.
If you are using Pega Cloud Services, when you add a pipeline, you specify details such as the application
name and version for the pipeline. Many fields are populated by default, such as the URL of your
development system and product rule name and version.
When you add a pipeline on premises, you define all the stages and tasks that you want to do on each
system. For example, if you are using branches, you can start a build when a branch is merged. If you are
using a QA system, you can run test tasks to validate application data.
You can modify application details, such as the product rule that defines the content of the application that
moves through the pipeline.
You can modify the URLs of your development and candidate systems and the authentication profiles that
are used to communicate between those systems and the orchestration server.
Modifying repositories
You can modify the development and production repositories through which the product rule that contains
application contents moves through the pipeline. All the generated artifacts are archived in the development
repository, and all the production-ready artifacts are archived in the production repository.
If you are using a Run Jenkins step, configure Jenkins server information so that you can run Jenkins jobs.
If you are using branches in your application, specify options for merging branches into the base application.
You can modify the stages and the tasks that are performed in each stage of the pipeline. For example, you
can skip a stage or add tasks such as Pega unit testing to be done on the QA stage.
3. Specify the details of the application for which you are creating the pipeline.
a. To change the URL of your development system, which is populated by default with your development
system URL, in the Development environment field, press the Down arrow key and select the URL.
This is the system on which the product rule that defines the application package that moves through
the repository is located.
b. In the Application field, press the Down arrow key and select the name of the application.
c. In the Version field, press the Down arrow key and select the application version.
d. Click the Access group field and select the access group for which pipeline tasks are run.
This access group must be present on all the candidate systems and have at least the sysadmin4 role.
Ensure that the access group is correctly pointing to the application name and version that is
configured in the pipeline.
e. In the Pipeline name field, enter a unique name for the pipeline.
4. Click Create.
Result: The system adds tasks, which you cannot delete, to the pipeline that are required to successfully
run a workflow, for example, Deploy and Generate Artifact. For Pega Cloud Services, it also adds mandatory
tasks that must be run on the pipeline, for example, the Check guardrail compliance task and Verify security
checklist task.
5. Add tasks that you want to perform on your pipeline, such as Pega unit testing. For more information, see
Modifying stages and tasks in the pipeline.
3. Specify the details of the application for which you are creating the pipeline.
a. In the Development environment field, enter the URL of the development system. This is the system on
which the product rule that defines the application package that moves through the repository is
located.
b. In the Application field, press the Down arrow key and select the name of the application.
c. In the Version field, press the Down arrow key and select the application version.
d. In the Access group field, press the Down arrow key and select the access group for which pipeline
tasks are run.
This access group must be present on all the candidate systems and have at least the sysadmin4 role.
e. In the Pipeline name field, enter a unique name for the pipeline.
f. In the Product rule field, enter the name of the product rule that defines the contents of the application.
b. In the Application name field, press the Down arrow key and select the application name.
c. In the Application version field, press the Down arrow key and select the application version.
d. In the Repository name field, press the Down arrow key and select the repository that contains the
production-ready artifact of the dependent application.
If you want the latest artifact of the dependent application to be automatically populated, ensure that
the repository that contains the production-ready artifact of the dependent application is configured to
support file updates.
e. In the Artifact name field, press the Down arrow key and select the artifact.
For more information about dependent applications, see Product rules: Listing product dependencies for
Pega-supplied applications.
a. Click Next.
5. In the Environment details section, in the Stages section, specify the URL of each candidate system and the
authentication profile that each system uses to communicate with the orchestration system.
a. In the Environments field for the system, press the Down arrow key and select the URL of the system.
b. If you are using your own authentication profiles, in the Authentication field for the system, press the
Down arrow key and select the authentication profile that you want to communicate from the
orchestration server to the system.
By default, the fields are populated with the DMAppAdmin authentication profile.
6. In the Artifact management section, specify the development and production repositories through which the
product rule that contains application contents moves through the pipeline.
7. In the Development repository field, press the Down arrow key and select the development repository.
8. In the Production repository field, press the Down arrow key and select the production repository.
9. In the External orchestration server section, if you are using a Jenkins step in a pipeline, specify the Jenkins
details.
b. In the Authentication profile field, press the Down arrow key and select the authentication profile on the
orchestration server that specifies the Jenkins credentials to use for Jenkins jobs.
11. If you are using branches in your application, in the Merge policy section, specify merge options. Do one of
the following actions:
To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
To merge branches into a new ruleset, click New ruleset.
12. In the Password field, enter the password that locks the rulesets on the development system.
Result: The system adds tasks, which you cannot delete, to the pipeline that are required to successfully
run a workflow, for example, Deploy and Generate Artifact. The system also adds other tasks to enforce best
practices such as Check guardrail compliance and Verify security checklist.
14. To specify that a branch must meet a compliance score before it can be merged:
c. In the Weighted compliance score field, enter the minimum required compliance score.
d. Click Submit.
For more information about compliance scores, see Compliance score logic
c. Click Submit.
16. To start a deployment automatically when a branch is merged, click the Trigger deployment on merge check
box. Do not select this check box if you want to manually start deployments.
17. Clear a check box for a deployment life cycle stage to skip it.
18. In the Continuous Deployment section, specify the tasks to be performed during each stage of the pipeline.
See the following topics for more information:
Running Pega unit tests by adding the Run Pega unit tests task
If you use Pega unit tests to validate application data, add the Pega unit testing task on the pipeline stage
where you want to run it. For example, you can run Pega unit tests on a QA system.
If you are using Jenkins to perform tasks in your pipeline, you can add the Run Jenkins step to the stage on
which you want it to run. If you have configured the Jenkins OrchestratorURL and PipelineID parameters,
when this task fails, the pipeline stops running. For more information about configuring these parameters,
see .
Use manual steps so that users must take an action before a pipeline deployment can continue. Users can
either accept the task to continue the deployment or reject the task to stop it.
Specifying that an application meet a compliance score by adding the Check guardrail compliance score task
You can use the Check guardrail compliance score task so that an application must meet a compliance score
for the deployment to continue. The default value is 97, which you can modify.
Ensuring that the Application Security Checklist is completed by adding the Verify security checklist task
For your pipeline to comply with security best practices, you can add a task to ensure that all the steps in
the Application Security Checklist are performed. For customers on Pega Platform 8.4 and above, a new
Security Checklist API is available to provide an automated security configuration assessment. Both
candidate and orchestrator environments should be on or above Deployment Manager 4.8 to utilize this
functionality.
The Approve for production task is added to the stage before production. Use this task if you want a user to
approve application changes before those changes are send to production.
To run Pega unit tests for either the pipeline application or for an application that is associated with an access
group, do the following steps:
Click a manually added task, click the More icon, and then click either Add task above or Add task
below.
Click Add task in the stage.
To run all the Pega unit tests that are in a Pega unit suite for the pipeline application, in the Test Suite
ID field, enter the pxInsName of the test suite.
You can find this value in the XML document that comprises the test suite by clicking, in Designer
Studio, Actions XML on the Edit Test Suite form. If you do not specify a test suite, all the Pega unit tests
for the pipeline application are run.
To run all the Pega unit tests for an application that is associated with an access group, in the Access
Group field, enter the access group.
For more information about creating Pega unit tests, see Creating Pega unit test cases.
4. Click Submit.
5. Continue configuring your pipeline. For more information, see one of the following topics:
Click a manually added task, click the More icon, and then click either Add task above or Add task
below.
Click Add task in the stage.
2. In the Job name field, enter the name of the Jenkins job (which is the name of the Jenkins deployment) that
you want to run.
4. In the Parameters field, enter parameters, if any, to send to the Jenkins job.
5. Click Submit.
6. Continue configuring your pipeline. For more information, see one of the following topics:
To add a manual step that a user must perform in the pipeline, do the following steps:
Click a manually added task, click the More icon, and then click either Add task above or Add task
below.
Click Add task in the stage.
2. From the Task list, select Manual.
3. In the Job name field, enter text that describes the action that you want the user to take.
4. In the Assigned to field, press the Down arrow key and select the operator ID to assign the task to.
5. Click Submit.
6. Continue configuring your pipeline. For more information, see one of the following topics:
To specify that an application must meet a compliance score, do the following steps:
Click a manually added task, click the More icon, and then click either Add task above or Add task
below.
Click Add task in the stage.
3. In the Weighted compliance score field, enter the minimum required compliance score.
4. Continue configuring your pipeline. For more information, see one of the following topics:
You must log in to the system for which this task is configured, and then mark all the tasks in the Application
Security checklist as completed for the pipeline application. For more information about completing the checklist,
see Preparing your application for secure deployment.
Click a manually added task, click the More icon, and then click either Add task above or Add task
below.
Click Add task in the stage.
3. Click Submit.
4. Continue configuring your pipeline. For more information, see one of the following topics:
3. In the Assign to field, press the Down arrow key and select the user who approves the application for
production. An email is sent to this user, who can approve or reject application changes from within the
email.
4. Click Submit.
5. Continue configuring your pipeline. For more information, see one of the following topics:
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
3. In the Development environment field, enter the URL of the development system, which is the system on
which the product rule that defines the application package that moves through the repository is located.
4. In the Version field, press the Down arrow key and select the application version.
5. In the Product rule field, enter the product rule that defines the contents of the application.
7. f you are using a separate product rule to manage test cases, in the Application test cases section, complete
the following steps:
a. To deploy test cases, select the Deploy test applications check box.
b. In the Test application field, enter the name of the test application.
c. In the Version field, enter the version of the test case product rule.
d. In the Access group field, enter the access group for which test cases are run.
e. In the Product rule field, enter the name of the test case product rule.
f. From the Deploy until field, select the pipeline stage until which the test case product rule will be
deployed.
Note: When you use separate product rules for test cases and run a pipeline, the Run Pega unit tests,
Enable test coverage, and Verify test coverage tasks are run for the access group that is specified in
this section.
For the Run Pega scenario tests task, the user name that you provide should belong to the access group
that is associated with the test application.
8. If the application depends on other applications, in the Dependencies section, add those applications.
a. Click Add.
b. In the Application name field, press the Down arrow key and select the application name.
c. In the Application version field, press the Down arrow key and select the application version.
d. In the Repository name field, press the Down arrow key and select the repository that contains the
production-ready artifact of the dependent application. If you want the latest artifact of the dependent
application to be automatically populated, ensure that the repository that contains the production-ready
artifact of the dependent application is configured to support file updates.
e. In the Artifact name field, press the Down arrow key and select the artifact.
For more information about dependent applications, see Listing product dependencies.
9. Click Save.
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
3. In the Environments field for the system, press the Down arrow key and select the URL of the system.
4. In the Authentication field for the system, press the Down arrow key and select the authentication profile
that you want to communicate from the orchestration server to the system.
5. Click Save.
Modifying repositories
You can modify the development and production repositories through which the product rule that contains
application contents moves through the pipeline. All the generated artifacts are archived in the Development
repository, and all the production-ready artifacts are archived in the Production repository.
You do not need to configure repositories if you are using Pega Cloud Services; you can use different repositories
other than the default ones that are provided.
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
3. If you are using Deployment Manager on premises, or on Pega Cloud Services with default repositories,
complete the following tasks:
a. In the Application repository section, in the Development repository field, press the Down arrow key and
select the development repository
b. In the Production repository field, press the Down arrow key and select the production repository.
4. If you are using Deployment Manager on Pega Cloud Services and want to use different repositories other
than the default repositories, complete the following tasks:
b. In the Development repository field, press the Down arrow key and select the development repository.
c. In the Production repository field, press the Down arrow key and select the production repository.
5. Click Save.
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
6. Click Save.
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
To merge branches into a new ruleset, click New ruleset.
a. In the Password field, enter the password that locks the rulesets on the development system.
4. Click Save.
1. If the pipeline is not open, in the navigation pane, click Pipelines , and then click the name of the pipeline.
3. To specify that a branch must meet a compliance score before it can be merged:
c. In the Weighted compliance score field, enter the minimum required compliance score.
d. Click Submit.
For more information about compliance scores, see Compliance score logic.
c. Click Submit.
5. To start a deployment automatically when a branch is merged, select the Trigger deployment on merge
check box. Do not select this check box if you want to manually start a deployment.
6. Clear a check box for a deployment life cycle stage to skip it.
7. In the Continuous Deployment section, specify the tasks to be performed during each stage of the pipeline.
See the following topics for more information:
8. Click Finish.
1. If you do not want deployments to start automatically when branches are merged:
1. If the pipeline is not open, in the navigation pane, click Pipelines Application pipelines
2. Click Pipeline model.
3. Select the Trigger deployment on merge check box.
If the pipeline that you want to start is open, click Start deployment.
Click Pipelines , and then click Start deployment for the pipeline that you want to start.
3. In the Start deployment dialog box, start a new deployment or deploy an existing application by
completing one of the following actions:
4. To start a deployment and deploy a new application package, do the following steps:
b. Click Deploy.
c. Go to step 5.
5. To start a deployment and deploy an application package that is on a cloud repository, do the following
steps:
c. In the Select a repository field, press the Down arrow key and select the repository.
d. In the Select an artifact field, press the Down arrow key and select the application package.
6. Click Deploy.
1. On the remote development system, package the branch. For more information, see Packaging a branch.
3. On the source development system, import the branch by using the Import wizard. For more information,
see Importing a file by using the Import wizard.
4. On the source development system, start a deployment by using the Merge Branches wizard. For more
information, see Submitting a branch into a pipeline.
If you are using one pipeline per application, you can publish a branch to start the merge. For more
information, see Publishing a branch to a repository.
Deployment Manager also generates a manual step if there are schema changes in the application package that
the release manager must apply. For more information, see Schema changes in application packages.
To complete or reject a manual step within the deployment, do the following steps:
1. To complete or reject a manual step from within an email, click either Accept or Reject.
b. Click a pipeline.
To resolve the task so that the deployment continues through the pipeline, click Complete.
To reject the task so that the deployment does not proceed, click Reject.
3. Click View aged updates to view a list of the rules and data instances, which are in the application package,
that are older than the instances that are on the system.
To import the older rule and data instances that are in the application package into the system, which
overwrites the newer versions that are on the system, click Overwrite aged updates.
To skip the import, click Skip aged updates.
To manually deploy the package from the Import wizard on the system, click Deploy manually and
resume. Deployment Manager does not run the Deploy step on the stage.
An aged update is a rule or data instance in an application package that is older than an instance that is on a
system to which you want to deploy the application package. By being able to import aged updates, skip the
import, or manually deploy your application changes, you now have more flexibility in determining the rules
that you want in your application and how you want to deploy them.
For example, you can update a dynamic system setting on a quality assurance system, which has an application
package that contains the older instance of the dynamic system setting. Before Deployment Manager deploys the
package, the system detects that the version of the dynamic system setting on the system is newer than the
version in the package and creates a manual step in the pipeline.
Configuring settings to automatically apply schema changes
You can configure settings to automatically deploy schema changes that are in an application package that is to
be deployed on candidate systems. Configure these settings so that you do not have to apply schema changes if
you do not have the privileges to deploy them.
1. On the candidate system, in Pega Platform, set the AutoDBSchemaChanges dynamic system setting to true
to enable schema changes at the system level.
b. In the dialog box that appears for the search results, click AutoDBSchemaChanges.
d. Click Save.
2. Add the SchemaImport privilege to your access role to enable schema changes at the user level. For more
information, see Specifying privileges for an Access or Role to Object rule.
Result: These settings are applied sequentially. If the AutoDBSchemaChanges dynamic system setting is set to
false, you cannot deploy schema changes, even if you have the SchemaImport privilege.
For more information about the database/AutoDBSchemaChanges dynamic system setting, see Importing rules
and data by using a direct connection to the database.
If an application package that is to be deployed on candidate systems contains schema changes, the Pega
Platform orchestration server checks the candidate system to verify that you have the required privileges to
deploy the schema changes. One of the following results occurs:
If you have the appropriate privileges, schema changes are automatically applied to the candidate system,
the application package is deployed to the candidate system, and the pipeline continues.
If you do not have the appropriate privileges, Deployment Manager generates an SQL file that lists the
schema changes and sends it to your email address. It also creates a manual step, pausing the pipeline, so
that you can apply the schema changes. After you complete the step, the pipeline continues. For more
information about completing a step, see Completing or rejecting a manual step.
You can also configure settings to automatically deploy schema changes so that you do not have to manually
apply them if you do not have the required privileges. For more information, see Configuring settings to
automatically deploy schema changes.
Pausing a deployment
When you pause a deployment, the pipeline completes the task that it is running, and stops the deployment at
the next step.
To pause a deployment:
3. Click Pause.
Stopping a deployment
Stop a deployment to discontinue processing.
To stop a deployment:
2. Click the More icon, and then do one of the following actions:
To resume running the pipeline from the task, click Resume from current task.
To skip the step and continue running the pipeline, click Skip current task and continue.
To roll back to an earlier deployment, click Rollback.
To stop running the pipeline, click Abort.
2. Click a pipeline.
For example, you can change logging levels of your deployment from INFO to DEBUG for troubleshooting
purposes. For more information, see Logging Level Settings tool.
2. Click a pipeline.
3. Click the Gear icon for the deployment for which you want to view the log file.
2. Click a pipeline.
3. Click the Gear icon for the deployment for which you want to view the deployment report.
2. Click a pipeline.
2. Click the Delete icon for the pipeline that you want to delete.
3. Click Submit.
If you are using a separate product rule to manage a test application, the name of the product rule is the same as
that of the product rule with _Tests appended to it.
2. Click the pipeline for which you want to download or delete packages.
5. To download a package, click the package, and then save it to the appropriate location.
6. To delete a package, select the check boxes for the packages that you want to delete and then click Delete.
However, you can use a distributed development environment if multiple teams are simultaneously developing an
application. A distributed development environment can comprise multiple development systems, on which
developers author and test the application. They then migrate their changes into and merge them on a
development source system from which those changes are packaged and moved in the CI/CD workflow.
When you configure a distributed development environment, ensure that you are following best practices for
development and version control.
For more information about development best practices, see Understanding best practices for DevOps-based
development workflows.
For more information about versioning best practices, see Understanding best practices for version control in
the DevOps pipeline.
Distributed development environments offer a number of benefits when multiple development teams are
working on the same application. For example, each development team can continue to work on its own
Pega Platform server even if other team servers or the source development system are unavailable.
Distributed development consists of several systems, including remote development systems, the source
development system, and an automation server.
When you work in a distributed development environment, you generally work in branches and merge them
to incorporate changes into the base application. The implementation of some of your tasks depends on your
specific configuration, such as which automation server you are using.
Each development team can do system-wide configuration and maintenance on its own Pega Platform
server without affecting other team systems.
Because each team works on its own remote development system, teams can continue working even if the
development source system or another team server experiences system or application issues. System or
application issues are introduced to the source development system or to another team server.
A distributed development setup helps to insulate the source development system from changes introduced
by developers. Distributed development also reduces or eliminates the creation of unnecessary rules or data
instances application testing generates.
Teams can have co-located development servers that have reduced latency, which also increases
productivity.
Reduce the need for coordination across teams when introducing changes and packaging the final
application.
Distributed development simplifies the application packaging process, because developers package the
application on the development source system, which includes all the latest application rulesets to be
packaged.
If you use an automation server such as Deployment Manager, when you merge changes on the source
development system, you can audit application updates.
The distributed development environment comprises systems that perform the following roles:
Remote development systems – the systems on which development work takes place, typically in branches.
Each team usually uses one Pega Platform server on each system.
Development teams can use tools such as container management or provisioning scripts to quickly start up
remote development systems.
Source development system – the Pega Platform server that stores the base application, which contains only
the latest production changes. It is also the system from which the application is packaged. You merge
branches on this system from remote development systems.
You should maintain high availability and have a reliable backup and restore strategy for the source
development system.
Automation server – the server that automates continuous integration or continuous delivery jobs that are
part of an application lifecycle, such as automated testing, application packaging, task approval, and
deployment.
You can use a number of tools as the automation server, such as Deployment Manager, Jenkins, or Bamboo.
While an automation server is not a requirement, it is recommended that you use one, because it reduces
the manual steps that you need to do in a DevOps workflow.
In general, working in a distributed development environment consists of the following tasks and methods:
1. On the remote development system, build a team application layer that is built on top of the main
production application. The team application layer contains branches, tests, and other development rulesets
that do not go into the production application. For more information, see the Pega Community Using multiple
built-on applications.
a. In the header of Dev Studio, click the name of your application, and then click Definition.
b. In the Edit Application rule form, in the Application rulesets section, click the Open icon for the ruleset
that you want to lock.
d. In the Lock Ruleset Version dialog box, in the Password field, enter the password that locks the
ruleset.
f. Click Submit.
3. Create a branch of your production ruleset in the team application. For more information, see Adding
branches to your application.
5. Use release toggles to disable features that are not available for general use. For more information, see
Toggling features on and off.
6. Create a review so that other developers can review branch content. For more information, see Creating a
branch review.
7. Conduct developer reviews to review the content and quality of the branch. For more information, see
Reviewing branches.
9. Migrate branches to the source development system and then merge and validate the branches. Depending
on your configuration, you can either do both steps at the same time or separately. Do one of the following
tasks:
a. To migrate and merge branches at the same time, perform step 10.
10. To migrate and merge branches at the same time, do one of the following actions:
Use Deployment Manager to create pipelines and start a deployment. For more information, see
Migrating and merging branches by using Deployment Manager.
Configure third-party automation servers to automatically merge branches after you publish branches
to the source development system. For more information, see Migrating and merging branches with
third-party automation servers.
11. To migrate a branch and then separately merge and validate the branch, migrate branches to the source
development system by doing one of the following tasks:
Publish a branch to the source development system. For more information, see Publishing a branch to a
repository.
Use prpcUtils to automatically package and migrate the application. For more information, see
Automatically deploying applications with prpcUtils and Jenkins.
Manually migrate the application package by packaging and exporting it. For more information, see
Exporting a branch to the source development system.
12. Merge and validate branches by using the Merge Branches wizard. For more information, see Merging
branches into target rulesets.
13. Migrate the merged rules back to the remote development systems by doing one of the following tasks:
Rebase the development application to obtain the latest ruleset versions from the source development
system. For more information, see Understanding rule rebasing.
Use prpcServiceUtils to export a product archive of your application and import it to the remote
development systems. For more information, see Automatically deploying applications with prpcUtils
and Jenkins.
Manually migrate the application by exporting it from the development source system and then
importing it into the remote development system. For information, see Importing a branch into remote
development systems after merging.
If you are using Deployment Manager as your automation server, you can use it to merge branches on the
source development system. You must configure certain settings on the source development system before
you can create pipelines that model pre-merge criteria and can merge branches.
If you are using a third-party automation server such as Jenkins, you can automatically start a branch merge
after you publish the branch to the development source system.
You can migrate a branch to the source development system by publishing a branch to it through a Pega
repository.
Do the following tasks to configure Deployment Manager to merge branches on the source development system:
1. Configure the source development system so that you can merge branches on it. For more information, see
Configuring the development system for branch-based development.
2. Create a pipeline for your application, which includes modeling pre-merge criteria, such as adding a task
that developers must complete a branch review before merging branches. For more information, see
Configuring an application pipeline.
Submit an application into the Merge Branches wizard. For more information, see Starting a deployment
as you merge branches from the development environment.
Publish application changes in App Studio. For more information, see Publishing application changes in
App Studio.
1. Create a repository connection between the remote development system and the development source
system. For more information, see Creating a repository.
2. Publish the branch to the source development system through the repository. For more information, see
Publishing a branch to a repository.
Note: To automatically merge the branch after publishing it, follow the procedure in Migrating and merging
branches with third-party automation servers.
1. Create a Pega repository connection between the remote development system and the source development
system. For more information, see Adding a Pega repository.
2. Publish the branch to the source development system through the Pega repository. For more information,
see Publishing a branch to a repository.
1. On the remote development system, package the branch. For more information, see Packaging a branch.
2. On the source development system, import the application package by using the Import wizard. For more
information, see Importing rules and data by using the Import wizard.
Importing a branch into remote development systems after
merging
After you merge branches on the source development system, manually migrate the merged branches back to
the remote development system by packaging and then importing it.
To migrate a branch back to the remote development system, do the following tasks:
1. On the source development system, package the branch. For more information, see Packaging a branch.
2. On the remote development systems, import the application package by using the Import wizard. For more
information, see Importing rules and data by using the Import wizard.
You can set up a continuous integration and delivery (CI/CD) pipeline that uses a Pega repository in which you
can store and test software and a third-party automation server such as Jenkins that starts jobs and performs
operations on your software. Use a CI/CD pipeline to quickly detect and resolve issues before deploying your
application to a production environment.
For example, you can configure an automation server with REST services to automatically merge branches after
you publish them to a Pega repository. You can also configure Jenkins to create branch reviews, run PegaUnit
tests, and return the status of a merge.
When you work in a continuous integration and development environment, you can configure a repository on
a source development system to store and test software. You publish branches to repositories to store and
test them. You can also configure a pipeline with REST services on your automation server to perform
branch operations, such as detecting conflicts, merging branches, and creating branch reviews, immediately
after you push a branch to the repository.
Remotely starting automation jobs to perform branch operations and run unit tests
In a continuous integration and delivery (CI/CD) workflow, repositories provide centralized storage for
software that is to be tested, released, or deployed. You can start a job remotely from an automation server,
such as Jenkins, and use the branches REST and merges REST services to merge branches when you push
them from your development system to a Pega repository on a source development system.
After you have configured an automation server and system of record (SOR) so that you can remotely start
jobs on the automation server, you can implement a continuous integration and development pipeline with
the branches REST and merges REST services. These services detect potential conflicts before a merge,
merge rules in a branch, obtain the status of the merge, and create branch reviews. By remotely starting
jobs that automatically perform branch operations, your organization can deliver higher-quality software
more quickly.
To use branches with repositories, you must perform the following tasks:
1. In Dev Studio, create a repository. For more information, see Creating a repository.
2. On the source development system, create a development application that is built on all the applications
that will go into production. You must also create a ruleset in the development application that contains all
the rules that you are using for continuous integration.
For example: For example, if you have a production application MyCoAppwith with the rulesets MyCo:01-01
and MyCoInt:01-01, you can create a MyCoDevAppdevelopment application that is built on MyCoAppand has
only one ruleset, MyCoCIDev:01-01. This ruleset contains the data transforms that are needed to set default
information, such as the application into which branches will be merged.
You can use the branches REST and merge REST services in your pipeline to perform branch operations. The
branches REST service provides subresources that you can use to detect conflicts, merge branches, and
create branch reviews.
3. Configure a continuous integration and development pipeline so that your automation server, such as
Jenkins, starts a job immediately after you push a branch to the source development system.
Use the branches REST and merge REST services in the pipeline to perform branch operations, such as
detecting conflicts and merging branches. For more information, see Remotely starting automation jobs to
perform branch operations and run unit tests.
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 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 development source system. Your pipeline can run all unit 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 Understanding rule rebasing. In addition,
you can configure your pipeline to send emails to users, such as when a job starts or when a conflict is detected.
Configure your automation server so that you can remotely start jobs on it. Your configuration depends on
the automation server that you use.
Configure a dynamic system setting on the main development system to define your automation server URL.
Your configuration depends on the automation server that you use.
After you configure your automation server and your source development system, you can configure a
pipeline on your job to automate the testing and merging of rules. Actions that you can do include obtaining
merge conflicts, creating branch reviews, and running unit tests.
1. Open a web browser and navigate to the location of the Jenkins server.
c. On the Available tab, select the Build Authorization Token Root Plugin check box.
d. Specify whether to install the plug-in without restarting Jenkins or download the plug-in and install it
after restarting Jenkins.
b. On the General tab, click the This project is parameterized check box.
d. 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.
g. Click Save.
a. Click Configure.
b. On the General tab, in the Build Triggers section, select the Trigger builds remotely (e.g., from scripts)
check box.
c. In the Authentication Token field, enter an authentication token, which can be any string.
d. Click Save.
7. Click Save.
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 unit test cases or test suites. For more information, see Running test
cases and 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, seeImplementing a CI/CD pipeline with
repository APIs.
To access the documentation about the data model, click Resources API .
For more information about response codes, see Pega API HTTP status codes and errors.
Use the branches REST service to retrieve a list of conflicts before you run tests and merge branches and
perform additional tests on conflicts before performing a merge operation. You can also create branch
reviews.
Use the merges REST service to obtain the status of the merge that you created by using the merge
subresource.
Use the conflicts subresource to retrieve a list of conflicts before running tests, allowing the pipeline to fail
more quickly so that you can correct errors faster.:
Use the merge subresource to perform additional tests on conflicts, and then perform a merge operation.
Request – http://serverURL/prweb/api/v1/branches/{id}/conflicts
Parameter – ID. The name of the branch for which you want to receive conflicts. This parameter is required.
Response – The conflicts subresource returns the number of conflicts.
Request – http://serverURL/prweb/api/v1/branches/{id}/merge
Parameter – ID. The name of the branch that you want to merge. This parameter is required.
Response – The merge subresource returns a unique ID after a validation event occurs. During the merge,
the status is saved to an instance of the System-Queue-Merge class.
To verify the status of a merge, use the Merges REST service, using the ID returned by the response.
You can also use the Queue Management landing page to view information about and remove merge requests
without needing to know the response ID. Open the landing page by clicking Dev StudioSystem Operations Queue
Management .
You can also update logging levels to INFO on the pzMergeServicePostActionProcessing activity to log
informational messages. These messages could provide information about why exceptions are occurring and also
act as a reference that you can use if you are working with Pegasystems Global Customer Support. For more
information about logging levels, see Logging Level Settings tool.
Request – http://serverURL/prweb/api/v1/branches/{id}/review
Parameter – ID. The name of the branch for which you want to create a review. This parameter is required.
Request body – The email account of the user creating the review and the users who are reviewing the
branches. Use the following format:
Request – http://serverURL/prweb/api/v1/merges/{ID}
Parameter – ID. The unique identifier that you obtained by running the merge subresource of the branches
REST service. This parameter is required.
Response – The merges REST service returns the status from the System-Queue-Merge instance.