Skip to main content


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

Pega Marketing agents

Updated on May 27, 2021
Note: This content is valid until Pega Marketing or Pega Customer Decision Hub version 8.4. For the latest version of this article, see the Pega Customer Decision Hub User Guide on the Pega Customer Decision Hub product page.

 

On top of the standard Pega Platform agents, a set of agents exist that manage the different aspects of Pega Marketing. Review and monitor these agents on a regular basis to ensure that your application is running optimally. In the event of a failure in any of the agents, understanding the agent's role helps to assess the impact of the failure on the application.

The following tables contain descriptions of these agents, which is divided based on the part of the application that the agent is used in. For each of the agents listed, the Multi-node column contains a recommendation on whether the agent should be run on multiple nodes, based on the purpose of the agent and how it scales for performance.

Segmentation agents

Agent nameMulti-nodeDescriptionNode type
DeferredSegmentsYes

Handles requests to manually run a segment from the Segment rule form. If there are many manual requests for larger segments, then having this agent running on multiple nodes speeds up segment runtime.

Queue items for this agent are instances of the System-Queue-DeferredSegments class.

If there are Broken-Process queue items for this agent, marketers might experience failures or delays in their segments. Review the details on the queue item to determine the cause of the failure.
BackgroundProcessing
SegmentScheduleYes

Manages the scheduled run of segments, which is configured in the Options and Schedule tab of the Segment rule form. If there are recurring runs, the agent auto-manages its own queue items. There should be only one queue item per segment at any given point in time.

Queue items for this agent are instances of the System-Queue-ScheduledTask class with the Agent Name set to PegaMKT-Engine:SegmentSchedule.

Broken-Process queue items for this agent imply failures in scheduled running of segment. Consequently, these segments might have stale or incomplete data.
BackgroundProcessing
AnalysisScheduleYesSimilar functionality to the SegmentSchedule agent, but instead of segments, it runs Analysis Project rules according to the schedule.BackgroundProcessing
ManageMasterSegment Keeps the Master Segment view in sync with all the segments currently created in the system. The Master Segment is used by Pega Marketing 8.2 and older to support the segment filter functionality. In Pega Marketing 8.3, this agent still exists but is no longer used for segment filter support.BackgroundProcessing

Offer runtime agents

Agent NameMulti-nodeDescriptionNode type
ProcessOverlayActionYesPerforms background processing of the Update wait time and Stop offers actions on the Offer rule. For more information, see Monitoring Waiting Offers in the Pega Marketing User Guideon the Pega Marketing product page.BackgroundProcessing

ProcessProgramRun

Yes

Initiates a campaign run at runtime. The agent creates the necessary infrastructure, such as batch classes and tables, and executes the strategy based on the segment input population that is configured. If configured on the campaign, it also triggers the refresh/rerun of the segment before starting a strategy. In a non-partitioned environment, this agent applies volume constraints.

Queue items for this agent are instances of the System-Queue-ProgramRun class.

If the Campaign Run work object does not show any progress for a long time, review the status of this agent and its associated queue items.
Batch
ProcessEventRunYes

Handles the processing of received real-time events. The agent reads the list of received events from a staging table, processes them, and then removes them from the table.

Processing an event involves:

  • Checking the validity of the inbound event data for each of the associated campaigns
  • Checking the validity of the customer (if configured)
  • Assembling the appropriate context
  • Executing the strategy associated with the campaign
  • Executing offers that the strategy outputs

Event campaigns use the MKT_EVENT_P<ProgramID> tables instead of the batch output tables.

RealTime
ProcessCampaignRunYes
This agent is only available if Field Marketing is available as part of your Pega Marketing application.

Executes the offers for the selected list of customers in a Field Marketing campaign.

Batch
ProcessWaitFlowsYes

Triggers an Offer flow for the WaitExpired paths in an Offer flow. Every campaign run creates one or more (if partitioned) of these queue items to periodically scan the batch table for records whose wait duration has expired. If any such offers are found, this agent resumes their processing along the WaitExpired path.

Queue items for this agent are instances of the System-Queue-WaitFlow class.

Batch
ProcessWaitingGenericFlowYes

When Offers are initiated in a non-batch scenario (such as Inbound), the records are stored in the MKT_DATA_OFFER table in the data schema. This agent scans through such Offers to find any that have expired and resumes their processing along the WaitExpired path.

Queue items for this agent are instances of the System-Queue-GenericWaitFlow class.

RealTime
RunHandleResponsesDF Supports updating the adaptive model responses based on the stages and timeouts configured in the outcome optimization configuration. The agent checks if a real-time data flow run is in progress for the pxHandleResponses data flow. If not, it creates one and starts the data flow run.Batch
ProcessWaitingNBAOffersNoPeriodically checks if there are actions that need Wait Expired configured for the Next-Best-Action Designer triggered events.

Primarily operates on the table/class that is mapped to PegaMKT-Data-NBAOffer.

RealTime

Delivery channels agents

Agent NameMulti-nodeDescriptionNode type
SendEmailsInBulkNoPeriodically reads the email output table PR_DATA_CORR_EMAIL and performs email transmission. The agent removes successfully transmitted emails and, in the event of a failure, updates the status to Failed.Custom1, Batch
MonitorChannelQueueYesUpdates the log file used to monitor the email queue. Pega Marketing can log sent, failed, and queued emails, as well as the queue depth, that is, the emails which have not been processed yet. By default, the agent updates the log file at one-hour (3600 seconds) intervals.BackgroundProcessing
SendSMSInBulkNoPeriodically reads the SMS output table PR_DATA_CORR_SMS and performs SMS transmission. The agent interfaces with the configured SMSC and transmits the SMS message. In the event of a failure, the agent removes any successfully transmitted SMS messages and updates the status to Failed.Custom2, Batch
InboundSMSReceiverNoPeriodically sets up listeners to handle inbound SMS messages for the configured Inbound SMS Accounts. The agent calls the InboundConnector activity to set up the listener. For each message that is received, the agent creates a new instance of PegaMKT-Data-Inbound-SMS, populates the appropriate details, and saves it to the database.RealTime
InboundSMSOfferFlowNoProcesses instances of PegaMKT-Data-Inbound-SMS. For each message, the agent determines the relevant Customer and SMS Account context, parses the inbound message based on the SMS Account configuration, uses this information to determine the behavior and Offer, and (if appropriate) initiates/resumes the offer.RealTime
OutboundMasterNo

Note: Used for backward compatibility and upgrade purposes.

A master outbound agent that determines which File/Database Templates need to be processed, and then creates queue items for the WriteOutboundAgent to process them.

Batch
WriteOutboundAgentYes

Note: Used for backward compatibility and upgrade purposes.

A standard agent that performs File and Database output processing based on the details in the queue item created by the OutboundMaster agent. WriteOutboundAgent processes records from the MKT_STAGING table in the Pega Marketing (PM) schema.

BackgroundProcessing
FileDBScheduleYes

Note: Used for backward compatibility and upgrade purposes.

Performs the scheduled finalization for the File and Database output channels.

BackgroundProcessing
PushNotificationMasterNoPeriodically checks the push notifications table PR_DATA_PUSH_MESSAGE to create new queue items for the PushNotificationProcessor agent in order to transmit notification messages. Each queue item corresponds to a (logically simulated) partition value in the table.BackgroundProcessing
PushNotificationProcessorYesProcesses messages that are part of a specific partition in the PR_DATA_PUSH_MESSAGE table. The agent transmits these messages based on the configurations for the Push Notification App and Variant (specified on the Push Notifications landing page).BackgroundProcessing
APNs Feedback ServiceNoUses the Apple APNs Feedback service to periodically retrieve uninstalled push tokens and calls Pega Marketing's Push Notification Un-registration service to remove these uninstalled push tokens from the registered list.BackgroundProcessing
File/DB template based job schedulersNo
These are not enabled out-of-the-box, but when a file or DB template is configured with schedule options and then saved, the new job schedules with the name of the template rule and the channel appended will be created in the artifacts ruleset.

For example, if the name of DB template was OutboundDailyNBA, then the job scheduler will be created, in the configured artifacts ruleset, with the name: OutboundDailyNBA__DB.

BackgroundProcessing

Queue processor

Agent NameMulti-nodeDescriptionNode type
FinalizeFileDBTemplate 

This queue processor is disabled by default to help optimize performance. However, if your file and database templates must be processed at extremely high volume, this dedicated queue processor can be enabled to further increase the performance.

For more information, see Optional: Enabling the FinalizeFileDBTemplate queue processor.

BackgroundProcessing

Paid media agents

Note: Paid media agents are disabled by default. Refer to the table below for information about when to enable each agent.
Agent NameMulti-nodeDescriptionWhen to enableNode type
ProcessPaidMediaRunsYesInitiates a paid media run for paid media queue items created by campaign runs when paid destinations are configured in the Next-Best-Action hierarchy. After the paid media run starts, data flows are created for each paid destination in the hierarchy. Once all data flow runs are either completed or failed, work objects are created for any errors that occurred during the run. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure paid destinations in the Next-Best-Action hierarchy.Batch

ProcessExpiredPaidAudienceRecords

NoRemoves individuals from the All Next-Best-Action managed audience after the time specified in the paidmedia/allNBAAudience/TimeToLive Dynamic System Setting. By default, this agent runs once every day. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure paid destinations in the Next-Best-Action hierarchy. 
ProcessPaidSegmentRunsYesInitiates a paid segment synchronization after the refresh of a segment that has paid destinations enabled. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure any paid segment synchronization.Batch
ProcessPaidMediaReSyncYesProcesses the resynchronization queue for paid destinations. Resynchronization queue items are created for each update to the PII mappings used by Paid Media Manager or to an individual's PII values, such as an email address, phone number, or device ID. The ProcessPaidMediaReSync agent processes the queue item and triggers the resynchronization for the right destination. By default, this agent runs every 5 seconds. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure any paid destinations.Batch
PaidMediaArtifactsMasterNoCreates one queue item for each destination where you enabled automatic campaign generation. PaidMediaArtifactsGenerator must be enabled to process the queue items created by this agent. By default, this agent runs every 30 minutes. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.If you enabled automatic campaign generation in the paid destination settings.BackgroundProcessing
PaidMediaArtifactsGeneratorYesCreates Facebook Ads and Google Ads lookalike audiences as well as campaign and ad set scaffoldings.  By default, this agent runs every 30 seconds and processes any queue items created by PaidMediaArtifactsMaster. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.If you enabled automatic campaign generation in the paid destination settings.BackgroundProcessing
PaidCustomerReSyncMasterNoIdentifies the changes in individual PII data, such as email addresses and phone numbers. If you update an individual's email address or phone number, at the next agent run, the agent triggers a re-synchronization of customer data. For each unique paid destination, the agent creates one CustomerReSync data flow run. Outbound, real-time and segment-based paid audience synchronization is postponed while the CustomerReSync data flow runs. If a synchronization is in progress, the CustomerReSync data flow for that destination is postponed until the current synchronization is completed. By default, this agent runs once every 7 days. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure any paid destinations.Batch
UpdatePaidMediaMatchRateNoUpdates the match rates for paid audiences visible on the Paid Audiences landing page. By default, this agent runs once every hour. For more information, see Paid Media Manager in the Pega Marketing User Guide on the Pega Marketing product page.After you configure any paid destinations.Batch

Paid media job schedulers

Note: Paid media job schedulers are disabled by default. Refer to the table below for information about when to enable each job scheduler.
Job Scheduler NameDescriptionWhen to enable
PaidNotificationsGeneratorCreates error and notification work objects. By default, this scheduler runs once every hour.After you configure any paid destinations. For more information, see "Implementing Paid Media Manager" in the Pega Marketing Implementation Guide on the Pega Marketing product page.
PaidMediaESCheckAndReindexChecks the paid media master records count in the database table and ES index. If there are any conflicts, the schedule reindexes the ES index with records from the master database table.If you enabled full-text search on the Search landing page. For more information, see "Enabling elastic search for Paid Media Manager" in the in the Pega Marketing Implementation Guide on the Pega Marketing product page.
TokenValidityCheckerChecks the validity of the tokens used to communicate with paid destinations. If the token is expired or invalid, the scheduler creates an error work object with the default urgency of 80 and displays a notification in the notifications section of Next-Best-Action Designer. For segment synchronization, the notification is displayed in the notifications section of the Paid Sync tab of the segment.After you configure any paid destinations. For more information, see "Implementing Paid Media Manager" in the Pega Marketing Implementation Guide on the Pega Marketing product page.
OfflineConversionRTTrigger Runs at regular intervals to read the real-time offline events from the synchronization staging table and synchronize them to the network. By default, this job scheduler runs once every hour.When you want to synchronize the offline events captured through CaptureResponse REST API to the network For more information, see "Using offline conversion push to improve re-targeting with data from real-world interactions" in the Pega Marketing Implementation Guide on the Pega Marketing product page.
RemoveStalePaidMediaEntries
Identifies distributed map entries created by a failed node, and removes them from the distributed map created by audience synchronization. By default, this job scheduler runs once every day.
After you configure any paid destinations. For more information, see "Implementing Paid Media Manager" in the Pega Marketing Implementation Guide on the Pega Marketing product page.

Cleanup and data-mining agents

Agent NameMulti-nodeDescriptionNode type
ProcessPurgingNo

Cleans up batch assets, such as classes and tables, that are created while running a program. A cleanup occurs when the following conditions have been met:

  • The ProcessProgramRun agent has completed the processing for all of its offers. The status of all offers must be Completed.
  • The timeframe to purge a work object has lapsed. The timeframe is specified as a number of days. You can view this setting in the Pega Marketing portal, on the Application settings landing page, in the Delete campaign data older than field. For more information, see Administrative Settings in the Pega Marketing User Guide on the Pega Marketing product page.

Additionally, the ProcessPurging agent configuration uses the MKTPurgeMaxRecords setting to determine the maximum number of records that may be purged during a cleanup. By default, the maximum number of purged records is set to 100. To change the default value, you first need to add this setting to the Dynamic System Settings list, and then set the new maximum number.

BackgroundProcessing
RefreshCampaignOfferStatsNo
This agent is only available if Field Marketing is available as part of your Pega Marketing application.
Performs data mining by periodically refreshing a materialized view in the database to summarize the Interaction History data for Field Marketing reporting purposes.
BackgroundProcessing

Startup and maintenance agent

Agent NameMulti-nodeDescriptionNode type
PegaMKTStartupAgentYesHandles routines, maintenance, and checks that need to occur during the application server startup. The agent can be used for data instance re-sets or for whenever something must be done during node startup.BackgroundProcessing
ResilenceHandlerNoDetects segmentation process crashes during runtime and recovers the long running and not recoverable processes to a healthy state. The processes can be re-run or edited again.BackgroundProcessing

Tags

Pega Marketing 7.4 - 8.4 System Architect Lead System Architect System/Cloud Ops Administrator Low-Code App Development System Administration

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.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us