Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Updating Next-Best-Action Designer

Updated on January 19, 2022

This content applies only to Pega Cloud environments

In Pega Marketing and Pega Customer Decision Hub, Next-Best-Actions are automated decisions based on predictive analytics, adaptive analytics, and traditional business rules. With Next-Best-Action Designer, you can define Next-Best-Action decisions and requirements that apply to the whole organization, or to specific business issues or groups.

Pega Customer Decision Hub Pega Customer Decision Hub Pega Customer Decision Hub Pega Customer Decision Hub Pega Customer Decision Hub

Planning an update of Next-Best-Action Designer

Caution: Do not perform the update directly in your live Production environment. Doing that will cause the unexpected results.

When preparing for an update, take into account the environments that you have in your pipeline. To avoid interrupting normal business operations with downtime for the update, the following update path is recommended:

  1. Run the pre-update check and resolve all of the identified errors.
  2. Update Next-Best-Action Designer in the Staging Clone environment.
  3. After the update is successful and tested, push the changes to the live Production system.
  4. Push the changes from Staging Clone to downstream instances such as BOE, Staging, Dev or QA environments after Production is updated.
    Note: Make sure to sync all Next-Best-Action Designer dependent Artifacts before migrating the Next-Best-Action Designer upgraded Artifacts for maintaining the same configuration in all instances. Avoiding this may cause problems with migrating Artifacts from Production to downstream instances.
Note: For more information about why if you are updating to Pega Customer Decision Hub version 8.7, your Customer Contact Policy will be moved to Outbound Limits, see Change from Customer Contact Policy to Outbound Limits.

Migrating Next-Best-Action Designer from version 1 to version 2

When planning a migration, consider the various environments that you may have in your pipeline. Best practice is to first perform the migration in a Staging Clone environment, in a dedicated, unlocked update ruleset version, and then migrate all the rule changes to other environments in the pipeline.

To migrate Next-Best-Action Designer:

  1. Suspend any outbound schedules defined for the existing Next-Best-Action configuration defined in Next-Best-Action Designer version 1.
  2. Ensure that all Pega Customer Decision Hub assets are checked in.
  3. Ensure that the ruleset and version used by your access group are unlocked, or create an unlocked version of the ruleset. By default, the ruleset used to store the configuration is Artifacts.
  4. Ensure that the ruleset and version used by your Context Dictionary is unlocked. You can check the ruleset and version on the SettingsContext Dictionary landing page in App Studio.
  5. In Dev Studio, click RecordsSysAdminDynamic System Settings.
  6. Click Create.
  7. Enter the following information:
    Short description
    Optionally, enter the description of this Dynamic System Setting, for example, Enables the update of Next-Best-Action Designer to version 2.
    Owning Ruleset
    Enter PegaMKT-Engine.
    Setting Purpose
    Enter MKTEnableNBADversion2Upgrade.
  8. Click Create and open.
  9. Set the value of the setting to True.
  10. Click Save.
  11. Log off from Pega Customer Decision Hub and then log back in.
  12. In App Studio or in the Pega Customer Decision Hub portal, click Add menu Next-Best-ActionDesigner.

    The Next-Best-Action Designer now shows the option to update to version 2.

  13. Click Migrate now. The configuration of next-best-action and its strategy framework is updated.
  14. If you do not plan to implement action treatments, which were introduced in Pega Marketing version 8.2, deactivate Next-Best-Action treatment processing. This ensures that offers created before the update function correctly. After you associate your offers with treatments, you can enable treatment processing again. For more information, see the Pega Customer Decision Hub 8.7 User Guide on the Pega Customer Decision Hub product page.
    1. Click the gear icon in the upper right corner of the Next-Best-Action Designer.
    2. Set the Channel treatment processing toggle to OFF.
    3. Click Submit.

After migrating Next-Best-Action Designer, review and test the migrated strategies to ensure that they work with the new configuration.

Updating Next-Best-Action Designer version 2

Update your Next-Best-Action Designer configuration to support the latest features and updates, if you have already used Next-Best-Action Designer version 2 in previous versions of Pega Marketing or Pega Customer Decision Hub.

Next-Best-Action Designer in non-production environments:

All instances of Production environments level 4 or below automatically update Next-Best-Action Designer as part of a Pega Customer Decision Hub update. Ensure that the following prerequisites are met before performing a Customer Decision Hub update:

  1. After running the Pre-Upgrade Check as a part of your planning, ensure that all of the identified errors are resolved before proceeding with the update.
  2. Ensure that no next-best-action outbound runs are currently active, and that no runs are planned for the same time that you want to run the Next-Best-Action Designer update.
    Note: Updates can take 30-45 minutes.
  3. Ensure that no inbound requests, such as real-time events and real-time container requests, are planned for the same time that you want to run the Next-Best-Action Designer update.
  4. Ensure that the ruleset and version used by your access group are unlocked, or create an unlocked version of the ruleset. By default, the Artifacts ruleset is used to store the configuration.
  5. Ensure that at least one unlocked version of the ruleset used for Context Dictionary exists
  6. Optional: To avoid potential issues during the update, check in all checked-out artifacts related to Next-Best-Action Designer.
  7. Optional: To ensure that future development is based on the updated rulesets and that your applications consistently reference the latest features, roll the Artifacts ruleset version.
Note: When upgrading from version 8.3 or earlier, ensure that the CSMS Data Flow in the context data does not have a compose shape on the master segment table. If the Data Flow still contains the compose shape, it means that the CSMS Data Flow might have been overridden. In such cases, manually delete the compose shape of the master segment. If there are two contexts in your Context Dictionary, search for two Data Flows that start with the name defined for each context. For example, if you have defined the contexts as Customer and Account, search for CustomerDataCSMS and AccountDataCSMS Data Flows.

Migrating Artifact into other instances:

Seamless updates of Next-Best-Action Designer are not enabled in production-level environments (such as Production and BOE) due to runtime concerns during the updates.

To migrate the artifacts into production-level environments you should use the Pega Deployment Manager. See for more information about migrating artifacts into production before the Go/No-Go stage.

To maintain synchronization across all the environments, it is recommended to migrate Artifacts from Production to Dev, QA,Staging and BOE. You can refer to for further details.

Removing deprecated Action Outcomes data sets

Along with the Outboud Limits, improved way of tracking time period for policies necessitates you to remove deprecated Action Outcomes data sets from Interaction History Summaries while updating Next-Best-Action Designer.

  1. Dev Studio, click ConfigureDecisioningDecisionsData SourcesInteraction History Summaries.
  2. Find Action Outcomes for the past 7 Days and Action Outcomes for the past 30 Days.
  3. Click Manage.
  4. Select Not materialized.
    Note: It is recommended to remove these two data sets completely while updating to the newest version.
  5. Click Advanced.
  6. Click the Remove dataset from the configuration icon.
  7. Click Save.
    Note: If the OfferOutcomesForPast10Days and OfferOutcomesForPast30Days data sets are present before the update, you should dematerialize and remove them, following the same steps as described above. These has been withdrawn in version 8.7.

Change from Customer Contact Policy to Outbound Limits

If you are updating to Pega Customer Decision Hub version 8.7, your Customer Contact Policy will be moved to Outbound Limits. This is a required migration and there is no backward compatibility once Next-Best-Action Designer has been updated to version 8.7.

The Quarterly and Yearly policy periods will no longer be supported and therefore will not be updated. If you are using the Quarterly and Yearly contact policy periods, you must change them to Monthly, Semimonthly, Weekly, or Daily for that policy to be migrated to version 8.7.
  1. In the Pega Customer Decision Hub portal, click Next-Best-ActionDesignerConstraints.
  2. Click Edit
  3. In the Contact policy library workspace chose the contact policy.
  4. Click the More icon next to the contact policy and choose Edit contact policy.
  5. Make the necessary changes.
    If the Customer Contact Policy is not currently in use, meaning that the dates have passed, or have not yet begun, or that the policy is marked as unavailable, but there are policies defined, the policies will be migrated to version 8.7 as a current available Contact Policy. If you do not want this to happen, you must remove the policy before the update:
    1. In the Contact policy library workspace chose the contact policy you want to remove.
    2. Click the More icon next to the contact policy
    3. Click Delete contact policy.
    Also, you will need at least as many days of data in Interaction History as the longest policy period defined. That is, if you have a Monthly policy period, you will need 30 days of data in Interaction History.
    Note: All of the rules related to Contact Policy are withdrawn in Pega Customer Decision Hub version 8.7.
  • Previous topic Configuring actions in Pega Customer Service
  • Next topic Importing Next-Best-Action settings from a template

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us