Anagentisaninternalbackgroundprocessoperatingontheserverthatrunsactivitiesonaperiodic

basis.Agentsrouteworkaccordingtotherulesinyourapplicationtheyalsoperformsystemtasks
suchassendingemailnotificationsaboutassignmentsandoutgoingcorrespondence,generating
updatedindexesforthefulltextsearchfeature,synchronizingcachesacrossnodesinamultiple
nodesystem,andsoon.
Agentsareautonomousandasynchronous:theactivitiestheycallrunindividuallyontheirown
schedules,andoneactivitydoesnothavetofinishbeforeanotheroneruns.
ThisarticlelinkstomultiplePRKBarticlesthatarepublishedasagroupandcanbereadin
sequence.
ThePDNcontainsotherarticlesaboutagents,inadditiontothoseinthisgroup.ClicktheContents
outlineviewonthispageorusesearchtoaccessadditionalagentsarticles.

Agentsrunactivitiestoaccomplishtheirtasks.Toprovideinformationtotheagentactivities,your
applicationmustplaceentriesintoanagentqueuesotheagentknowsthatthereisworktoprocess.
TheQueueForAgentmethodtakesappropriatedatafromtheworkobjectorassignmentthatan
agentneedstohave,andstoresthatdatainaqueueentryfortheagent.

SuggestedApproach
Inyourapplication,calltheQueueforAgentmethodfromwithintheprocessingoftheobject(work
object,assignment,etc.)wheretheagenttaskisbeingcreated.Youcancallthemethoddirectly,or
cancallthestandard@baseclass.QueueForAgentactivity.

CalltheQueueForAgentmethodusingasteppagewiththeclassofwhateverworkobjectthe
agentisprocessing.NOTE:IntheQueueForAgentactivity,thismethodiscalledwithablankstep
page.Itisassumedthatthisactivityisitselfbeingcalledfromoneoftheprocessingactivitiesforthe
workobjectwhentheQueueForAgentactivityiscalled,thecallshouldincludetheappropriatework
objectsteppage,whichthenispassedintotheQueueForAgentactivityandbecomesitsprimary
page.
TheQueueforAgentmethodparametersare:
Parameter

Description

AgentRuleSet

Required.TheRuleSetinwhichtheagentisstored.Thisshouldalsobethenameofthe
Agentsruleinwhichthisagentiscontained.

AgentName

Required.Thisparametercontainsthenameoftheagent(asdefinedontheAgentsrule).

MaxAttempts

Optional.Thisparameterspecifiesthenumberoftimesthesystemshouldtrytoprocess
thisentrythedefaultis1.Ifthemaximumnumberofattemptsismade,andtheentryis
stillunsuccessfullyprocessed,thesystemwilltreattheitemasafailure.
If,forexample,acustomerhasanagentwhich(amongotherprocessing)updatesthe
statusofaworkobject,thentheagentmustobtainalockonthatworkobjectbefore
changingitsstatus.Thefirstorsecondtimethattheagentattemptstogetalockonthat
workobject,itmayfail,ifanotheruserhasthatworkobjectopenatthesametime.This
parameterallowsthedevelopertohandlethatsituationwithoutanimmediatefailurethe
agentcantrythespecifiednumberoftimestoobtainthelockontheworkobjectbefore
failing.

MinimumAgeFo
r
Processing

Optional.Thisparameterspecifiestheminimumlengthoftime(inmilliseconds)thatan
entrymustremaininqueuebeforeitmaybeprocessedthedefaultis0(theitemmaybe
processedassoonasitisenteredintotheagentqueue).
Asanexample,acustomermayhaveanentrywithaMaxAttemptsvalueof3.Ifthe
workobjectislocked(exampleabove),tryingtoprocessitagainimmediatelywill
probablynotgivetheuseranytimetocloseit,sothenextattemptshouldbedelayeda
littlethisparameterputssometimeinbetweentries.Or,aqueueentrymaybecreated
byworkobjectprocessing.Iftheagenthappenstowakeupandprocessthisentry
immediatelyafteritwasentered,theworkobjectwouldstillbeinuse(andlocked)bythe
user,causingagentprocessingtofail.Therefore,puttingasmalldelayinbeforetryingto
runtheagentprocesscouldgivetheuserenoughtimetoclosetheworkobjectandgoon
tosomethingelse.

Accessgroupsforagents
Suggestedit

Comments(2)

20
40
60
80
100

Totalvotes:9

Someagentsmayneedadditionalaccessprivilegesinordertoaccomplishtheirprocessingthis
meansthatyoumustsetupAccessGroupsforthoseagents.
Thethreeagentsthatareshippeddonotrequireanyadditionalaccess,iftheyareusedwithoutany
changes.However,ifyouchangethePegaAgentactivitiesorresavetheseagentsintoother
RuleSets,youmustconfigureoneormoreAccessGroupsfortheseagents.
Important:AccessgroupsareonlyneededforLegacyorAdvancedmodeagents,oragents
definedpriortoVersion5.4.
QuickLinks:
AddingAccessGroupinformationpriortoV5.4
AgentsinunlockedRuleSets

AgentsinlockedRuleSets
AccessgroupsontheBATCHrequestorrecord
AddingAccessGroupinformationVersion5.4andlater
Legacy/AdvancedmodeagentsinunlockedRuleSets
Legacy/AdvancedmodeagentsinlockedRuleSets
AccessgroupsontheBATCHrequestorrecord

SuggestedApproach
Whenuserslogin,theloginprocessusestheiraccessgrouptosetupaRuleSetlistineachusers
profile,tobeusedforthatusersruleresolution.Agentsdonotloginasusersdo.However,when
anagentruns,eachagentactivityisruninitsownrequestor,andthusrequiresalistofRuleSetsto
bedefinedsoaRuleSetListisavailabletouseforruleresolution(doneasapartofprocessingthe
agentactivities).
AgentsrequireaccesstoallRuleSetsintheapplicationthathaveruleswhichareinvokedbythe
agentactivities.Thisrequiredaccessmayincludenotonlytheagentactivitiesthemselves,butany
activitiesorotherrules(Whens,models,etc.)calledbytheagentactivities.TheseRuleSetsmust
beincludedintheagentsAccessGroup,sothattheagentmaycorrectlycompleteitsprocessing.
Therefore,dependinguponthetaskitneedstoperform,anagentsAccessGroupmustgiveit
accessto:

anyrulesitneedstoruntheagentactivity(includingotheractivities,Whens,models,etc.)
whateverrolesandprivilegesareneededtodoitsbusinessprocessing(sendemail,update
aworkitem)
whateverrolesandprivilegesareneededtoupdatethequeueentryintheagentqueue

AddingAccessGroupInformationpriortoV5.4
InversionspriortoV5.4,youmustcreateanaccessgroupforanyagentwhichneedsaccess
outsidetheRuleSetinwhichitwasdefined.
TopofPage
AgentsinunlockedRuleSets
AgentswhicharedefinedinanapplicationRuleSetmayhaveaccesstoalltheactivities,etc.that
theyrequire.IfyoucreateanagentwhichaccessessomefunctionalitynotintheagentsRuleSetor

prerequisitesoftheagentsRuleSet,youmustdefineanaccessgroupwhichincludesbothRuleSets
(theagentsRuleSet,andtheRuleSetwheretheadditionalfunctionalityis),andincludethataccess
groupontheagentruleform.
Enterthataccessgroupnameintheagentrule,intheAccessGroupfieldontheScheduletab:

TopofPage
AgentsinlockedRuleSets
FortheAgentsrulesinlockedRuleSets(suchasthoseshipped),itisnotpossibletoaddanAccess
GroupintheAgentsform.Fortheseagents,theaccessgroupinformationmustbeaddedtothe
AgentSchedule(DataAgentQueue)formassociatedwitheachagentsrule,intheAccessGroup
fieldontheScheduletab.

TopofPage
AccessGroupsontheBATCHRequestorRecord
WhenyouchangeanagentactivityandhavetoaddAccessGroupinformationforagentsinlocked
RuleSets,youcouldaddittotheappropriateAgentSchedulerecordforeachnodeofthesystem(as
explainedabove).Thatcanbehardtotrack,though,iftherearemanynodes,orifnodesare
continuallybeingaddedorremoved.
Topreventcontentionandwastingresources,youwilldisablemostagentsonallbutonenodeofa
multinodesystem(seeRunningAgentsinaMultiNodeSystem).Thus,formostagents,you
wouldnthavetoworryaboutnodesbeingaddedorremoved.However,someagents,suchasthe
PegaProComagent,arebedesignedtoruninamultinodeenvironment.Forthoseagents,you
maywanttoaddaccessgroupinformationattheRequestorlevel.
Allprocessesarerunasrequestorsontheserver,whethertheyareusersessionsorAgents.The
DataAdminRequestorclassholdsfourinstances:

APP
BATCH
BROWSER
PORTAL

AgentsusetheBATCHrequestortype,whichcontainsaccesstothestandardPegaProCom
RuleSet.

IfyouonlywantoneAgentsaccessgroup,createtheaccessgroupwithalltheRuleSetsrequiredfor
allagents.Then,insteadofhavingtoenterthisaccessgroupintoalltheAgentsrules,enteritinto
therequestorBATCHrecord.Thisaccessgroupwillthenbeusedforallagentsinthesystem.
TopofPage

AddingAccessGroupInformationVersion5.4andlater
InVersion5.4,forStandardmodeagents,eachqueueentrywillbeprocessedintheauthorization
contextoftheuserwhoseprocessing(workobject,assignment,etc.)generatedthatentry.
Therefore,noadditionalaccessgroupsareneeded.
TopofPage
Legacy/AdvancedmodeagentsinunlockedRuleSets
AswithreleasespriortoVersion5.4,agentswhicharedefinedinanapplicationRuleSetmayhave
accesstoalltheactivities,etc.thattheyrequire.Ifyoucreateanagentwhichaccessessome
functionalityinaRuleSetnotintheprerequisitesoftheagentsRuleSet,youmustdefineanaccess
groupwhichincludesbothRuleSets,andincludeitontheagentruleform.
Enterthataccessgroupnameintheagentrule,intheAccessGroupfieldontheSecuritytab:

TopofPage
Legacy/AdvancedmodeagentsinlockedRuleSets
AllbutoneoftheagentsshippedwithProcessCommanderVersion5.4areLegacymodeagents.
Therefore,ifanychangesarerequiredtotheseagents,youmustaddaccessgroupinformation.
AswithProcessCommanderreleasespriortoVersion5.4,itisnotpossibletoaddanAccessGroup
intheAgentsform,astheProcessCommanderRuleSetsarelocked.Theaccessgroupinformation
mustbeaddedtotheAgentSchedule(DataAgentQueue)formassociatedwitheachagentsrule,
intheAccessGroupfieldontheSecuritytab.

TopofPage
AccessGroupsontheBATCHRequestorRecord
InVersion5.4,theSLAandBulkProcessingagents(inPegaProCom)arebothdesignedto
preservetheusersworkobjectcontext(justlikeStandardmodeagents).Therefore,theaccess
groupontheBATCHrequestorisnolongerrequiredunlessyouhavecreatedagentsinyour
applicationwhicharedesignedtorunonmultinodesystems.Inthatcase,youmaywishtosetup
anaccessgroupforthatagentontheBATCHrequestor.
RememberthatifyousetupanaccessgroupontheBATCHrequestor,itaffectsallagents.
TopofPage

Agentscheduleintervals
Suggestedit

Comments(8)

20
40
60
80
100

Totalvotes:3

Summary
Whendesigningagents,oneofthemostimportantdecisionsyoumustmakeishowoftentheagent
shouldrun.Considerwhatkindofagentisbeingcreated,inordertohaveitrunatausefulinterval
neithertoooften(whichwastessystemresources)nortooinfrequently(whichcouldslowdown
processing).

SuggestedApproach
Forexample,abankmighthaveanapplicationtohandlemortgagerequests.Theygetfewerthan10
oftheserequestseachday.Attheendoftheprocess,ifthemortgageisapproved(maybe80%of
thetime),theywanttoautomaticallygenerateandsendalettertotheapplicant,congratulatingthem
ongettingtheirmortgageandwishingthemsuccesswiththeirnewhome.Thissystemmight

generateoneortwolettersperday,whichthedeveloperwishestohavetheagentprocess.Dueto
thislowvolume,havingtheagentcheckforletterrequestseveryfivesecondswouldresultin
excessiveprocessingrunningtheagenteveryhourorevenonceadaymightbesufficient.
Anotherapplicationmightcreateinvoicesforaninternationalretailer,withadailyvolumeof10,000
invoices.Foreachoftheseinvoices,theuseropensaworkobjecttocreatetheinvoiceatacertain
pointintheprocessing,theinvoiceisputintothePendingResearchworkbaskettolookupthatdays
exchangeratefortheinvoiceditems.Anagenttakesallthesetasksoutoftheworkbasket,
accessesanexternaldatabasetogettheappropriateexchangerate,andthenupdatesthe
assignmentandreturnsittotheuser.Givenaneighthourday,thesystemwouldhandle1250
invoicesanhour,orabitover20eachminute.Inthiscase,ifanagentwereusedtolookupthe
exchangerate,havingtheagentruneveryfivesecondsisnotonlynecessary,butthatmighteven
beabitslow.
AgentschedulingisspecifiedintwofieldsontheAgentsruleformandAgentScheduleinstances:
PatternandInterval.TherearetwovaluesavailableforthePatternfield,allowingyoutwochoices
forwhenagentsrun:
Periodic
Recurring
Important:ThevaluesenteredintheAgentsruleforeitherPeriodicorRecurringprocessing
becomeadefaultforthatagent.Itispossibletooverridethesevaluesforanyagentinthe
appropriateAgentScheduleinstance.(Fordetails,seeHowtomodifyanexistingagent.)
NOTE:Dependingupontheagenttypetaskdrivenorscheduledrivendifferentprocessing
occurswhentheagentruns:
taskdrivenagentscheckthequeueforatask
scheduledrivenagentsruntheagentactivitywithoutcheckingthequeueforatask
Becausethegoalofthefollowingsectionsistodescribetheschedulingfunction,ratherthanthe
differenceinprocessing,thegenericphraseprocessinganagenttaskwillbeuseditshouldbe
understoodthatthiscouldrefertoeithertypeofagent,andwouldmeansomethingdifferentbased
onwhichtypeischosen.

Periodic
PeriodicprocessingreferstoagentprocessingwhichisrunattheintervalspecifiedintheInterval
column.TheAgentManagerwakesthisagenteveryintervaltodoitsprocessing.Forexample,if
theintervalissetfor30seconds,thenaftertheAgentManagerrunsthisagent,itsleepsfor30
seconds,andthenwakesupandrunsagain.

Notethatanintervalperiodbeginsonlyaftertheagentcompletestheprocessingfortheprevious
cycle.Forexample,iftheIntervalissetto30seconds,butprocessingtheagenttaskrequires60
secondsonaverage,thentheagentwakesupandbeginsprocessingonlyeveryminuteandahalf
(approximately).
TheIntervalvalueshouldbethelargestvaluepossible(thelongesttime)consistentwiththeamount
oftimerequiredforprocessingtheagenttask,andthenumberoftasksgeneratedinaspecifiedtime
period.Forexample,ifonaverage,threetasksforthisagentareavailableinaday,thenhavingan
Intervalvalueof30secondswouldmeanalotofwastedsystemresourcestryingtoprocessthese
threetasksunlessitwerevitalthatthesetasksbeprocessedimmediately.However,ifataskfor
thisagentisgeneratedevery10seconds,andtakes10secondstoprocess,havingtheagentrun
every5minutesmeansthatitwouldgethopelesslybehindveryquickly,leavingunprocessedtasks.

Recurring
TheRecurringfeatureallowsyoutospecifyarecurringpatternofdays,weeks,etc.forthisagentto
run.Anintervalperiodmaycrossadaydefinitionforexample,anagentcouldrunprocessing
from11:59to12:01,crossingfromonedatetoanotheroritmightrunatadifferenttimeeachday,
dependingupontheintervalandthelengthoftimetheprocessingtakes.Ifyouwanttoknowwhen
anagentwillrun,youcanspecifyarecurringtimeperiodassumingthattheagentprocessingtobe
doneisappropriateforarecurringtimeperiod,ratherthanhavingtobedoneevery30seconds.

WhenyouchooseRecurringinthedropdown,anAdvancedbuttonappearsintheIntervalcolumn.
ClickingontheAdvancedbuttondisplaysadialogbox,whichallowsyoutochooseatwhatinterval
theagenttaskshouldbeprocessed:

TheStartfieldholdsthedesiredtimeofthefirstexecutionoftheagentsubsequentexecutionsare
thespecifiedperiodlater(24hoursormultiplesof24hours).
NOTE:Ifthetimeenteredhasalreadypassed,theagentwillnotrunthatday.
Thetimezonefieldholdsthelocaltimezone.Thisisanoptionalfieldifitisleftblank,thenthe
systemwillusethetimezonelocaltothisserver.
Important:Tospecifythetimezoneinthisfield,enterthelongtimecodedesignations
(America/New_York)ratherthanthethreeletterdesignations(EST).Thethreeletter
designationsdonothandleDaylightSavingsTime,soyouwouldhavetoupdatethisfieldeverytime
DaylightSavingsTimestartsorends(ESTEDTEST).
Tip:ThetimezonefielddoesnothaveaSmartPrompttoallowyoutochooseyourtimezone.To
seealistofpossibletimezonedesignations,chooseTools>LocaleSettingsandviewtheUse
TimeZonedropdownlist.(Dontchangeyourtimezonesetting!Justnotethedesignation,and
copyitintotheRecurrencewindow.)

IntheRecurrencedialogbox,thereareanumberofPatterntypesavailable:
Daily
Weekly
Monthly
Yearly
Important:JustaswiththeStartfield,whateverisdesignatedinthePatternTypeswillwakethe
agentatthefirstavailabletime.Thus,ifWeeklyischosen,andtheintervalisEvery2weekson
thesedays:Monday,ifthedaytheformiscompletedisWednesday,thisagentdoesnotwakeuntil
thenextappropriateMonday.
Daily
FortheDailypatterntype,therearetwointervalchoices:

Everyweekday(whichdoesnotincluderunningoneitherSaturdayorSunday)
Every[number]days(i.e.,every10days)

Weekly

TheWeeklypatternallowsyoutodeterminetheweekinterval(every2weeks,every10weeks)and
thentospecifythedaythattheagentshouldwake.Atleastoneofthedaysmustbeselected,and
morethanonedaymaybeselected.
NOTE:Ifallthedaysareselected,thenthischoicecanbecomeequivalenttotheDailychoice.
Monthly

TheMonthlypatterntypeallowstwospecifications:
Day[number]ofevery[number]month(s)Thischoiceallowsanumericdesignationofboththe
daysandthemonth.
Example:
Day1ofevery2months
Day15ofevery6months
The[first][day]ofevery[number]month(s)Therearenumerouschoicesforthesedropdowns:

first
second
third
fourth
last
day
weekday
weekendday
Monday
Tuesday
Wednesday

 Thursday
Friday
Saturday
Sunday
Examples:

Thefirstdayofevery2months
ThelastTuesdayofevery6months
ThethirdSundayofevery1month
Thefirstweekenddayofevery12months

Yearly

TheYearlypatterntypeallowsachoiceof:
Every[month][number]wherenumberisthedayofthemonth.
Example:
EveryJanuary1
EveryJune30
EveryDecember25
The[first][day]ofevery[month]ThesedropdownsarethesameasthedropdownsfortheMonthly
patterntype,withtheadditionofthemonthdropdown.
Examples:

ThefirstdayofeveryJanuary
ThelastTuesdayofeveryJuly
ThethirdSundayofeveryOctober
ThefirstweekenddayofeveryDecember

Summary
Twomainclassesthatholdinformationaboutagents:

Agentsrules(instancesofRuleAgentQueue)

AgentSchedules(instancesofDataAgentQueue)

SuggestedApproach
Agentsrulesdefinethebackgroundprocessingthatistobeaccomplishedbyagentsinthesystem,
includingtheactivitythateachagentshouldexecutefortheprocessing,itswakeupschedule,and
itsagentqueuesettings.EachagentthatislistedintheAgentsrulehasonetaskitaccomplishes
(checkingincomingemail,updatingstatusofworkobjects,etc.).TheAgentsrulesapplytothe
entiresystem,nomatterhowmanynodesthesystemhas.
ThereareanumberofAgentsrulesthatareshippedwiththesystemaswithallshippedrules,
theseareinlockedRuleSetsandcannotbechanged.Inordertoallowcustomerstochange
schedulingintervals,orenableordisabletheagents,theAgentScheduleinstancesareprovided.
AgentScheduledatainstancesdeterminewhetheranagentisenabled,and(onamultinode
system)onwhichservernodethatagentwillrun.Itisalsopossibletochangetheagentwakeup
intervalinAgentSchedules.
WhenProcessCommanderstarts,thesystemlooksforalltheAgentsrules.Foreachofthese
rules,thesystemlooksforoneAgentScheduleinstanceforeachnode.
IfthereisnotanAgentScheduleinstancepresentforanode,thesystemcreatesonebycopying
informationfromtheassociatedAgentsrule.Thus,ifasystemhasfivenodes,thenforthePega
RULESAgentsrule,therewillbefivePegaRULESAgentScheduledatainstances.
AftertheAgentScheduleshavebeencreated,theyprovideagentinformationtothesystem.The
systemusestheAgentsrulestodefinetheScheduleinstances.AftertheSchedulesarepresent,
theoriginalvaluesenteredintheAgentsruleforscheduleintervalsorenablingagentsarenotused
thesystemusestheinformationintheAgentSchedulesonly.

Important:TheAgentScheduleinstancesmustnotbecreatedbydeveloperstheyare
createdonlybythesystem.Donotcreateorcopytheseinstances!
Fordetailsonchangingagents,seeHowtomodifyanexistingagen

Summary
Ruleresolutionworksdifferentlyfortheagentsrules,becauseagentsaresystemwide,ratherthan
beingenabledforaparticularuser.

SuggestedApproach
WhentheAgentManagergetsalistofAgentsrules,thedatabasereturnsthebestversionforeach
instance,usingruleresolution.Ifthehighestversionofrulesonthesystemis050401,theAgent
Managerseesonlythatversion,soitrunsthemostrecentversionoftheagents.
NOTE:MultiplecopiesofanagentsrulemaybecreatedinoneRuleSet,butwithdifferentversion
numbers.However,circumstancesanddate/timequalifiersarenotvalidforagentrules.
DevelopersonthesystemwhodonthaveaccesstothehighestnumberedversionoftheRuleSets
(050401)intheirprofilewillseeanolderversion(050201)oftheAgentsruletheywillnotbeable
toseethenewversionoftheAgentsclassesinClassExplorer,sincetheydonthaveaccess.The
AgentManagerisnotsubjecttouserauthorizationissues,however,soitwillusethehighest
numberedversionoftheinstancesforeachRuleSetonthesystem.
Example:AsystemhasthreeversionsofthePegaProComRuleSet:

050402

050401

050201

WhenyoudoubleclickonthePegaProComAgentsruleinClassExplorer,youwillseetheruleyou
haveaccessto,basedonyourRuleSetList(050201).WhentheAgentManagergetsalistofthe
instances,however,itwillonlyseeversion050402.
NOTE:SincetheAgentSchedulesaredatainstances(classDataAgentQueue)anddataisnot
ruleresolved,youseealltheAgentSchedulesforthesystem(evenifyoudonthaveaccess).
Toefficientlymanageyourcluster,youcandedicatecertainnodestorunonlyselectedfunctions,
whichincludesbatchprocessing,search,andservices.Youcanensurethatanodeperformsonly
therequiredfunctionsbyconfiguringittorunonlythefunctionrelatedagents.

Dependingonthenumberofnodes,manuallyconfiguringnodescanbetimeconsuming.
Additionally,runningagentsinamultinodeenvironmentinvolvesthefollowingchallenges:

Wheneveryouwanttoenableordisableanagentorupdateanaccessgroup,youmust
updatetheagentschedulethatcorrespondstoeverynode

YoumustperformtheaboveactioneverytimethenodeIDchanges

ThePega7Platformhelpsyouconfigurenodestorunonlyselectedagentsbyusingasingle
commandwhilestartingupanode.Byusingthiscommand,youcanspecifyagentstoincludeor
excludeandoverrideaccessgroups.

Runselectedagents
(whitelist)
UsetheDincludeAgentscommandtospecifyalistofagentsthatcanberunonthenode.Only
thespecifiedagentsrunonthenode.Otheragents,regardlessoftheirstateintheDataAgent
Queueinstance,aredisabled.
UserscanstartorstoponlytheagentsspecifiedintheincludelistfromtheSystemManagement
Applicationlandingpage.
Thesyntaxforthiscommandis:
DIncludeAgents=RuleSet1:AgentName,RuleSet2:AgentName,

Disableselectedagents
(blacklist)
UsetheExcludeAgentsDcommandtospecifyalistofagentsthatmustnotrunonthenode
underanycircumstance.Agentsthatarenotpartoftheblacklistcontinuetorunbasedonthestatus
setintheDataAgentQueueinstance.
UserscannotstartorstoptheagentsspecifiedintheexcludelistusingtheSystemManagement
Applicationlandingpage.
Thesyntaxforthiscommandisasfollows:
DExcludeAgents=RuleSet1:AgentName,RuleSet2:AgentName,

Youcannotspecifyanincludeandexcludelistatthesametime.

Modifytheaccessgroupof
anagent
UsetheDAccessgroupsForAgentscommandtoupdatetheaccessgroupofaRuleAgent
Queueinstance.Theupdatedaccessgroupisusedforlegacyandadvancedagentsdefinedinthe
RuleAgentQueueinstance.
Thesyntaxforthiscommandisasfollows:
DAccessgroupsForAgents:RuleSet1:AccessGroup1,RuleSet2:Accessgroup2,

Criticalagents
DefaultcriticalagentsandagentsmarkedasKernelinthePega7Platforminstancecontinuetorun
regardlessoftheirinclusioninincludeorexcludelists.

Example
Consideratypicalclustermanagementscenario,whereyouwanttodedicatecertainnodesfor
specificfunctionsasshownbelow:
Node

Dedicatednodefor
search

node001

node002

node003

node004

Dedicatednode
forBIX

DedicatednodeforNBAM(NextBestAction
Marketing)

Fornode001andnode004toincludesearchagents,providethefollowingDparameterswhile
startingthenode:
DIncludeAgents=PegaSearchEngine:FTSIncrementalIndexer
Additionally,youcandisablethesameagentsonothernodesbyusingthiscommand:

DExcludeAgents=PegaSearchEngine:FTSIncrementalIndexer
Fordedicatingnode002torunonlyBIXrelatedagents,providethefollowingDparameterswhile
startingthenode:
DIncludeAgents=PegaBIX:BIXExtractionAgent "
Fordedicatingnode003torunonlycertainNBAMagents,providethefollowingDparameterswhile
startingthenode:
DIncludeAgents=PegaNBAMArtifacts:*,PegaMKTEngine:*,PegaMKT
PushNotification:*,PegaMKTFieldMarketing:*
TooverridetheaccessgroupforagentsinPegaRULES,use:
DAccessgroupsForAgents=PegaRules:PegaNBAM:Agents

SuggestedApproach
BeforeYouBegin:DesignConsiderations
Thereareanumberofdecisionsyoumustmakebeforecreatingagentrules,including:

whatprocessingtheagentwillaccomplish(seeHowtowriteanagentactivity)

whateventinsystemprocessingwillcreatetheagenttask(seeHowtoenteritemsintothe
agentqueue)

howlongtheagentintervalshouldbe

howmanyqueueentriesanagentshouldprocess

inwhatRuleSettheagentwillbesaved

AgentInterval
Whendesigningagents,oneofthemostimportantdecisionsyoumustmakeishowoftentheagent
shouldrun.Youshouldconsiderwhatkindofagentisbeingcreated,inordertohaveitrunata
usefulintervalneithertoooften(whichwastessystemresources)nortooinfrequently(whichcould
slowdownprocessing).
Forexample,abankmighthaveanapplicationtohandlemortgagerequests.Theygetfewerthan
10oftheserequestseachday.Attheendoftheprocess,ifthemortgageisapproved(maybe80%
ofthetime),theywishtoautomaticallygenerateandsendalettertotheapplicant,congratulating
themongettingtheirmortgageandwishingthemwellwiththeirnewhome.Thisapplicationmight
generateoneortwolettersperday,whichthedeveloperwishestohavetheagentprocess.Dueto
thislowvolume,havingtheagentcheckforletterrequestseveryfivesecondswouldresultin
excessiveprocessingrunningtheagenteveryhourorevenonceadaymightbesufficient.

Anotherapplicationmightcreateinvoicesforaninternationalretailer,withadailyvolumeof10,000
invoices.Foreachoftheseinvoices,theuseropensaworkobjecttocreatetheinvoiceatacertain
pointintheprocessing,theinvoiceisputintothePendingResearchworkbaskettolookupthatdays
exchangeratefortheinvoiceditems.Anagenttakesallthesetasksoutoftheworkbasket,
accessesanexternaldatabasetogettheappropriateexchangerate,andthenupdatesthe
assignmentandreturnsittotheuser.Givenaneighthourday,thesystemwouldhandle1250
invoicesanhour,orabitover20eachminute.Inthiscase,ifanagentwereusedtolookupthe
exchangerate,havingtheagentruneveryfivesecondsisnotonlynecessary,butthatmighteven
beabitslow.
Fordetailsonsettingupagentintervals,seeAgentSchedulingIntervals.
SettingtheMaxRecordsValue
AsstatedintheAgentIntervalsectionabove,youmustjudgehowmanyqueueentriesyour
applicationwillproduce,todeterminehowoftentheagentshouldrun.Linkedwiththisdecisionis
thedeterminationofthenumberofentriestheagentshouldprocessfromtheagentqueuebefore
goingtosleepforthatinterval.
Iftheapplicationproducesthousandsofqueueentriesthattheagentmustprocess,thedeveloper
mustbalancecompletingalltheseentriesinatimelymannerwithhavingtheagentruntoolong.For
example,onamultinodesystem,iftheagentdrainsthequeuewhenitruns,thentheagentonone
nodewilldoallthework,possiblyaffectingperformanceforthatnode.Itismuchmoreefficientto
setuptheagentrulesothattheagentoneachnodeworksonabatchofentriesandthengoesto
sleep,leavingsomeentriesinthequeueforthenextnodetoprocess.Iftheagentissettorun
every5minutes,andtoprocess50entries,thentheprocessingwillbespreadaroundthenodes,
andnoonenodewouldhavetochurnthroughalltheentriesinthequeue.
SavingAgentsintoRuleSets
Aswithallrules,therewillbeaRuleSettowhichanagentanditsassociatedactivitieswilllogically
belong.ThismightbeinyourbasecompanyRuleSet,ifthefunctionalityappliesacrossallthe
companysapplications.Iftheagenthasspecificfunctionalitywhichisusedinonlyoneapplication,
itmightgointothatapplicationRuleSet.YoumustdetermineintowhichRuleSettosaveyouragent.
OnlyoneAgentsrulecanbedefinedoneachRuleSettherefore,afterdeterminingwhichRuleSet
yournewagentshouldbesavedto,seeifthereisanAgentsrulealreadydefinedforthatRuleSet.If
thereis,addyournewagenttothatexistingrule.IfthereisnoAgentsruledefined,createanew
AgentsruleforthatRuleSetwithyournewagentinformation.

Important:SinceAgentshavesystemwidefunctionality,theymustrunonsystemwide
RuleSets,withsystemwideaccessgroups.ItisnotpossibletorunAgentsrulesorAgent
SchedulesfromapersonalRuleSet,orwithanAccessGroupsavedtoapersonalRuleSet.

CreatetheRule
Createoropentheruleform
DeterminewhetherthereisanexistingAgentsintheRuleSetwherethisnewagentwillbesaved.If
thereisnot,createanewAgentsrule:
1.FromRulesbyType,expandtheSysAdminlink.RightclickonAgents,andclickNew.
2.OntheNewform,intheRuleSetNamefield,entertheRuleSetwherethisAgentsrulewillbe
defined.(ThismustbeavalidRuleSetinthesystem.)EntertheversionforthisRuleSet,andclick
Create.
Addanagenttotherule
Foreachnewagent,enterintotheAgentsformtheagentname,class,activity,andschedule,based
onthepriordecisionsyoumadeandtherulesyoucreated.

1.AgentNameEnterthenameofthisnewagent.
2.PatternChoosetheappropriatePatternfromthedropdownlist.(SeeAgentScheduling
Intervals.)

3.IntervalIfthePatternchosenwasPeriodic,enteratimeinterval,inseconds,intothisfield,
specifyinghowoftenthisagentshouldrun.

IfthePatternchosenwasRecurring,specifytherecurrencetimeframeforthisagent(daily,

weekly,monthly).
4.ChoosetheQueueModefromthedropdownbox.Formostagents,thisshouldbeStandard.
(SeeHowAgentQueuesWorkQueueMode.)
5.ChecktheEnabled?fieldtoenabletheagent.
6.Clicktheorangearrowtotheleftoftheagenttodisplaytheadditionalagentfields.

7.ClassEnterthenameoftheclassonwhichtheagentisdefined.Thisclassshouldbethe
sameastheclassoftheworkobjectwhichthisagentwillbeprocessing.
8.ActivityNameEnterthenameoftheagentactivitythatwascreatedforthisagent.Thisactivity
shouldbedefinedontheclassspecifiedabove.
9.ParamsIfthereareparametersforthisactivity,clicktheParamsbutton,andentervaluesfor
theparameterswhicharedisplayed.
10.EnterthemaximumnumberofrecordstobeprocessedbythisagentintotheMaxRecords
field.
11.VerifythattheAutoQueueManagerboxischecked,toenabletheAutoQueueManager
functionality.Foralmosteveryagent,AQMshouldbeenabled.(SeeAgentQueuesAutoQueue
Manager.)
Configureagentwidesettings
1.VerifythattheEnablethisagentboxischecked.Thisenablesalltheagentsinthelist,and
allowsthesystemtocreatetheAgentScheduleinstance(s).

2.FortheagentsintheformwhichhaveaPatternofPeriodic,youmayalsospecifyadefault
IntervalforalltheagentsintheAgentWideSettingsfield.
3.Ifnecessary,enterthenameoftheaccessgroupthatwascreatedintheAccessGroupfieldon
theSecuritytab.

4.Savetheruleform.
5.Afteraperiodtypically10minutesorlessthesystemautomaticallycreatesAgentSchedule
datainstances,oneforeachnodecorrespondingtothenewagentrule.IftheEnablethisagent
boxintheagentruleischecked,itisalsoenabledintheAgentScheduleinstances,andprocessing
begins.(YoucancausethesystemtocreatetheAgentScheduleinstancesdirectlybystoppingand
restartingthesystem.)
AhelpfultutorialthatcoversarangeofagentdeploymentisHowtoproducePDFreportsona
nightlyschedule.
Anintuitiveuserinterfacehelpsyouspecifyhowfrequentlyanagentruns.
1. Selectanexistingagent,orcreateanewonebyselectingApplication>New>Rule>
SysAdmin>Agents.EachRuleSethasnomorethanoneAgentsrule,whichcanmanage
multipleagents.
2.

3. SelectRecurringforthePatternandclicktheAdvancedInterval(sec)button.The
Recurrencedialogappears.DependingonwhichPatternradiobuttonyouselect,yousee
optionsrelevanttoyourselection.
4. Daily:

5.
6. Weekly:

7.
8. Monthly:

9.

10. Yearly:
11.

12.
13. Note:forallpatterns,specifyaStartTimeusingtheselectionfieldsatthetopoftheform.
SpecifyyourtimezoneexactlyasitappearsinyourOperatorProfile(oranothervalidTMZ
codevalue).

14.
15. Tosettheagenttorunonthefirstdayofeachmonth,selecttheMonthlypattern.Youcan
selectthefirstradiobuttonandset"Day1ofevery1month(s)",orselectthesecondradio
buttonandset"Thefirstdayofevery1month(s)".Reviewtheotheroptionstoseeifthereis
asettingthatmeetsyourneedsmoreprecisely.
16.

17. SettheStartTime.Theagentwillstartassoonafterthattimeasasresourcesforitbecome
availableontheserver.
18. Whenyouaresatisfiedwiththesettings,clickOKtodismisstheRecurrenceform.
19. IntheAgentsrule,makesuretheEnabled?checkboxfortheagentyoucreated,andthe
EnablethisagentcheckboxunderAgentWideSettingsarebothselected.

20. SavetheAgentsrule.Theagentisnowsettorunsoonafterthetimeyouhavespecifiedon
thefirstdayofeachmonth.
Afteraperiodtypicallytenminutesorlessthesystemautomaticallypreparesthestructurebehind
thescenesthatwillruntheagentaccordingtothescheduleyouhavespecified.Youcancausethis
tohappenimmediatelybystoppingandrestartingthesystem.
Agentsrunactivitiestoaccomplishtheirtasks.Inordertohaveinformationwithwhichtorunthe
agentactivities,entriesmustbeputintotheagentqueuesotheagentknowsthatthereisataskto
process.
Dependinguponthetasktheagentshouldaccomplish,differentpartsofyourapplicationmaywrite
anentrytotheagentqueue.Iftheagenttaskinvolvesprocessinganassignment,forexample,
theremightbeanactivitycalledfromtheAssignmentactivityintheflowwhichwritesthequeue
entry.Iftheagentneedstosendanemailtoacustomeraspartofclosingaworkobject,thenan
activitymightbecalledaspreorpostprocessinginaflowaction,orcalleddirectlyinaUtilityshape.
Onceyouhavedeterminedthatataskcanbeaccomplishedinthebackground(seeHowtoCreate
AnAgentBeforeYouBegin),yourapplicationcanuseeither@@baseclass.QueueForAgent
activityortheQueueForAgentmethodtoenterthosetasksintotheAgentQueue.(SeeAboutthe
QueueForAgentMethod.)

TheQueueForAgentactivitycallstheQueueForAgentmethod.Youcanuseeither,depending
uponwhatisoccuringinyourapplicationatthepointyouwishtoqueuethetask.

Inanactivity,usethemethod

Iftheapplicationisataflowsteporotherareawhereanactivitycanbeeasilycalled,usethe
activity

NOTE:Thestepsbelowassumethatyourapplicationisrunninganactivitythestepsaresimilarfor
addingtheactivityitself.
1.Addanadditionalstepintoyouractivity,atthepointwheretheagenttaskentryshouldgo.
2.Enteradescriptionofthetaskbeingentered,andthenenterQueueForAgentintotheMethod
field.
3.ExpandtheparametersfortheMethodfield,andentervaluesfortheparameters:

agentRuleSet

agentName

MaxAttempts

MinimumAgeForProcessing

4.Saveyourchanges.

Summary
Afteragentshavebeencreated,youmayneedtomodifythem.
Howyouupdateanagentruledependsonwhethertheagentisoneofthreestandardagents,or
wascreatedforyourapplication.

SuggestedApproach
Therearetwotypesofexistingagents:

custom

standardandotherlockedagents

CustomAgents
ChangingtheAgentsruledirectlyisthemostefficientwaytoupdateagents.Ifyouhaveaccess,
changetheagentdirectlyinitsrule.Changingtheagentactivity(whichwouldalsorequirethe
additionofanAccessGroupforLegacyorAdvancedmodeagents),orchangingtheagentintervals,
orenablingordisablingagentsareallchangeswhichshouldbemade,ifpossible,intheAgentsrule.
ThechangesarethenautomaticallycopiedintoalltheassociatedAgentSchedulerecordsforthe
systemthenexttimetheAgentManagerruns.

NOTE:IfyouchangeoneoftheagentactivitiesandsaveittoacustomerRuleSet,thatnewactivity
willonlybeusediftheagentAccessGroupgivesappropriateaccesstotheRuleSet.
LockedAgents
Itisnotpossibletogetaccesstochangesomeagents.IftheRuleSetversioninwhichtheAgents
ruleisdefinedislocked(likethePegaRuleSets),thentherulecannotbechangeddirectly.
Inthiscase,youmaymakesomechanges(suchasenablingordisabling,orsettingtheInterval)to
theAgentSchedulerecordforthatAgentsrule.Youmustbecareful,however,tomakethese
changestoeachAgentScheduleinstancewhichexistsforthatAgentsrule(oneachnode),sothat
theagentfunctionalityisconsistentacrossnodesinthesystem

SuggestedApproach
Whenanagentwakesup,thesystemchecksthatagentsqueueforentriesifentriesarethere,the
systembeginsprocessingthefirstentry.Theagentactivityisrunforthatentryiftheprocessing
succeeds,thechangesaresavedifitfails,allthechangesarerolledback.(SeeOverviewofagent
processing)
Mostagentprocessinginvolvesworkobjects.Aspartofthebackgroundqueuefunctionality,the
agentattemptstoobtainalockontheworkobjectbeingprocessedbeforemakinganychangestoit.
Agentprocessingcanfailfortwomainreasons:

Theagentcannotobtainthelockontheworkobject(oftenbecausearequestoralready
holdsalockonit)

Theagentacquiresthelock,buttheprocessingfailsforsomeotherreason,andthechanges
arerolledback

InV5.4+,forbothofthesesituations,thistaskremainsintheagentsqueuewithastatusofBroken
Process.
IMPORTANT:AsstatedinHowagentqueueswork,tasksareleftintheagentqueueonlyifthe
AgentQueueManager(AQM)isenabled
IftheAQMisdisabled,thenassoonasataskisretrievedfromanagentqueueforprocessing,itis
removedfromthatqueue.Iftheprocessingfailsforanyreason,thattaskislost.Therefore,itis
bestpracticetoleaveAQMenabled.
Repairingbrokenqueueitems:
Asystemadministratorcaninsomecases,repairindividualqueueentrieswhosestatusisBroken
Process,byresettingthemusingtheBrokenQueueItemsreport.

1.OnPRPC6.1andlower,fromtheViewmenu,chooseSystem>BrokenQueueItems.
NOTE:Thismenuchoicerequirestheusertoholda"sysadm4"levelaccessrole.
OnPRPC6.1andhigher,clickPegabutton>ProcessandRules>Tools>WorkAdmin>Broken
QueueItems.ThismenuselectionrunsthestandardlistviewreportSystemQueue
.BrokenItems.All.Userswhoholdthe@baseclass.ReconcileBrokenQueueItemsprivilegecan
resubmitordeletebrokenqueueitems.
AlistofallclasseswhichinheritfromtheSystemQueueclassappears:

2.Clickoneradiobuttontoselecttheclasswherethebrokenqueueentriesyouwishtoprocessare
defined,andclickExecuteView.TheBrokenSystemQueueItemsreportappearswithinformation
abouteachbrokenqueueitem.

Thefollowingbuttonsappearatthetoprightofthewindow:

Button

Purpose

Refresh

Refreshesthislist(incaseotheragentshaverunandaddedBrokenProcessentriestothe
list).Clicktoseewhetheradditionalitemshavebeenaddedtothelistsinceyoulastdisplayedit.

Select
All

Selectsallentriesinthelist.Clicktoprocessallentriesatonce,insteadofprocessingthemone
atatime.

Deselect Deselectsallentriesinthelist.
All
Requeue ChangestheItemStatusoftheselectedentriesfromBrokenProcesstoScheduled.Clickto
reenteritemsyouselectedintotheagentsqueue,sotheagentmaytryagaintoprocessthem.
Delete

Removestheselecteditemsfromthequeue.Clickingtodeleteallthetasksyouselected.Ifyou
choosetoclearthesebrokentasksoutofthesystem,theprocessingtheyrequestwillnotbe
retriedbytheagent.

3.Determinehowyouwishtorepairthebrokenitem,andthenusethebuttonstoeitherrequeuethe
tasksordeletethem.

SuggestedApproach
AgentsthatareupgradedfromasystempriortoVersion5.4haveaQueueModesettingofLegacy
intheirAgentsruledefinition.Thisallowstheoldactivitytorunwithoutchangesandcorrectly
processtheagenttask.IfyouresavetheseLegacyagentsrules,youwillseeawarningatthe
bottomoftheruleform:
>>Warning>>:OneormoreagentsareinLegacyMode.PleaseseeUpgradinganExistingAgent
toVersion5.4onthePDNtoupgradethese.
ThiswarningwillalsoappearontheAgentScheduleinstancesassociatedwiththisAgentsrule.

NOTES:

ThisLegacysettingisnotvalidfornewagentsitwillonlyappearasthedefaultforexisting
agentswhichareupgradedtoVersion5.4orlater.

SomeofthePegaagentsarestillLegacyagents,andwillhavethiswarning.ThePega
agentsareintheprocessofbeingupgradedyoumayignorethewarningforthoseagents.

ThiswarningwillnotpreventyoufromsavingtheAgentsrule,norwillitpreventtheagentsfrom
running.ItisjustanotetoyoutoupgradeyourexistingagentstousetheimprovedVersion5.4
agentfunctionality.

Tousetheagentqueuefunctionality,youmustmakeseveralchangesinyoursystem:
1.Rewritetheagentactivitytoremoveallthetransactionalprocessingtheagentactivityshould
nowonlycontainbusinesslogic.(SeeHowtowriteanagentactivity.)
2.Adjusttheapplicationprocessingsothatthetasksforthisagentareenteredintotheagent
queue.(SeeHowtoenteritemsintoanagentqueue.)
3.ChangetheAgentsruletoreferencethenewagentactivityandclass.ChangetheQueueMode
ofthisagentfromLegacytoStandard,andchecktheAutoQueueManagerfield.
NOTE:SincethisagentisnowStandardmode,theAccessGroupinformationisnolonger
necessary.IfanAccessGroupisspecifiedinthisfield,itwillbeignored.
4.SaveallchangestotheAgentsrule.

(Formoredetailsontheagentqueue,seeUnderstandingtheAgentQueue.)
Servicelevelrules(SLAs)aretimelimitsonassignments,generallygoal,deadline,andlate
intervals.Whenoneofthesetimeintervalsisreachedwithouttheassignmentbeingperformed(or
theworkobjectbeingresolved),thesystemescalatesthisobjecttothedefinednextlevelfor
example,sendsittoamanager.TheProcessServiceLevelEventsagent(inthePegaProCom
Agentsrule)detectsthesegoalsanddeadlinesnotmetandperformsescalationprocessing.
Whenoneofthetimeintervalsisreached,ataskisautomaticallysenttotheinternalSLAqueuefor
theSLAagenttohandle.Totuneyoursystemtopeakefficiency,youmustdeterminehowtheSLA
agentshouldprocessassignments,andadjusthowmanyofthesetaskstheSLAagentprocesses
eachagentintervalbyusingtheSLASystemSettings.
Quicklinks:
Multinodeprocessing
Singlenodeprocessing
SLASystemSettingDescriptions
ChangingtheSLASystemSettings
Beforeyoubegin
Version5.3andprior
Version5.4

SuggestedApproach
SystemSettings(instancesofRuleAdminSystemSettings)areconstantsstoredinruleinstances.
TherearethreeSystemSettingsforSLAprocessing:

SLARefreshListEachIteration

SLAUnitsToProcess

SLAUnitsToRetrieve

Bydefault,theSLAagentrunsevery30secondstoprocessassignments.YoushouldtunetheSLA
processingtobeasefficientaspossiblebyadjustingtheSystemSettingsforthisagent.
First,youneedtodetermine:

howmanyassignmentsshouldbeprocessedinoneagentinterval

howmanyassignmentsshouldberetrievedforoneintervalsprocessing

Thesevalueswillvarydependingupon:

howmanynodesthesystemisrunningon(onesinglenode,ormultiplenodesandis
multiple2nodes,or200?)

howmanyworkobjectswithSLAsarecreatedeachday

MultiNodeProcessing
IfProcessCommanderisrunninginamultinodeenvironment,andtheSLAagentsareconfigured
toprocessalargenumberofassignments,therecanbecontentionbetweendifferentagentstrying
toprocessthesameassignments.
Exampleofcontentionissue:
IftheSLAagentonNodeAretrieves100assignmentstoprocess,itmaysuccessfullyprocessthe
firstoneortwo.However,atthatpoint,theNodeBSLAagentwakesupandalsoretrieves100
assignments,includingmanyoftheoneswhichtheNodeAagentistryingtoprocess.Nowwhen
NodeAtriestoprocessthenextassignment,itmaydiscoverthattheassignmentislockedbyNode
Bforprocessing.Ifthereareanumberofdifferentnodes,eachwiththeirownSLAagent,the
contentionbetweenagentsforassignmentscanwasteresources.
Therefore,formultinodesystems,itisrecommendedthatthenumberofassignmentsretrievedbe
muchsmaller,sothatcontentionisreduced.IftheNodeAagentretrievesfiveassignments,and
processesthemwithoutcontention,thatismuchmoreefficientthanretrieving100andhavingother
agentsblocktheattempttoprocessmostofthem.
backtotop

SingleNodeProcessing
IfProcessCommanderisinstalledonasinglenode,thenthereisonesetofagentsrunning.Since
thereisonlyonenode,therewillbenoagentcontentionamongnodes.Youcansetthenumberof
assignmentstoretrieveandtoprocesstobelarge,astherewillbenoagentcollisionsthenumber
ofassignmentsinthequeuethatarenotselectedforprocessingwillsimplybepickedupinthenext
interval.
backtotop

SLASystemSettingDescriptions
BelowisasummarytableofthethreeSLASystemSettings:

SystemSetting

Description

Default
Value

SLARefreshListEachIteration

Ifthissettingistrue,theneachtimeanSLAagentsuccessfully
processesanassignment,itrefreshestheretrieveditemlist
(retrievesanewlistofassignments).

false

SLAUnitsToProcess

ThissettingcontrolsthenumberofassigmentstheSLAagent
processesduringitsinterval.

20

SLAUnitsToRetrieve

ThissettingspecifiesthenumberofassignmentstheSLAagent
retrievesforprocessing.

100

NOTE:TherearethreetypesofSLAeventsforassignments:
goal
deadline
late
Thissettingreflectsthenumberofeventshandledforeachtype.
Therefore,ifthisentryissetto5,theSLAagentcouldpotentially
processupto15assignments5foreachtype.

ThesettingSLARefreshEachInterationcanbeusedtopreventadditionalinteragentcontention.If
thissettingistrue,theneachtimeanSLAagentsuccessfullyprocessesanassignment,itrefreshes
theretrieveditemlist.Soforexample,iftheSLAUnitsToRetrieveissetto3,andthe
SLAUnitsToProcessissetto10,thesystemwillretrieve3assignmentsandtrytoprocessoneof
them.Thequantityof3toretrieveischosentogiveagoodchancethatatleastoneofthe
assignmentswontbelockedbyanotheragentorauser,andwillbeabletobeprocessed.Ifonly
oneassignmentisretrieved,therecouldbesomeproblemwithitthatpreventsitfrombeing
processed,andtheretrievalprocesswouldhavetobedoneagain,wastingresources.
Aftertheagenthassuccessfullyprocessedoneofthethreeassignments,itrefreshesitslistby
goingbacktothefullqueueofassignmentstoretrieveanotherthree.Itispossiblethatifthevery
firstassignmentwasprocessed,andnootheragentshaveprocessedanyassignmentsinthe
meantime,thatthe2ndand3rdassignmentspickedupinthefirstretrievewillbepickedupagain
however,itismuchmorelikelythatotheragentsfromtheothernodesinthesystemhaverun,soit
willactuallypickupcompletelynewassignments.Itprocessesoneofthesenewthreeassignments
successfully,andthenrefreshesagain,followingthisprocedureuntilithassuccessfullyprocessed
10assignments.Atthispoint,itstops,andwaitsforthenextagentinterval.
Therefreshingproceduremeansthattheagenthasmoreuptodateinformationontheassignments
toprocess.Forexample,theNodeAagentmaypickupassignments1,2,and3.Itsuccessfully
processes#1,andthenrefreshes.Inthemeantime,theNodeBagenthasalsopickedup
assignments1,2,and3.Itcantprocess#1(asitislockedforprocessingbyNodeA),soit
processes#2,andthenrefreshes.WhenNodeArefreshes,itnowpicksup#3,#4,and#5,because

NodeBprocessed#2.ThismeansthatNodeAdoesntwastetimetryingtoprocess#2,whichwas
lockedandthencompletedbyNodeB.
backtotop

ChangingtheSLASystemSettings
Beforeyoubegin
BeforeyouchangeanyoftheSystemSettings,youneedtodeterminetheappropriatevaluesfor
yourparticularapplication.
Foralargeenterprisesystem,theSLAUnitsToProcessandSLAUnitsToRetrieveshouldbeset
accordingto:

thespeedofthesystem

thethroughputofthesystem

thenumberofnodesinthesystem

theestimatednumberofassignmentsinthesystematanyonetime,foreacheventtype
(goal/deadline/late)

SettheSLARefreshEachInterationasfollows:

trueformultinodesystems

falseforsinglenodesystems

Example:DeterminingSLAUnitsToProcess
Thereare5nodesinthesystem.Youestimatethatatanytime,theremaybe300assignments
whichcouldpotentiallyreachanSLAlimit.These300willbebrokendownbytypeasfollows:

Goal50%(150)

Deadline30%(90)

Late20%(60)

TheSLAUnitsToProcessmightbesetat30(thelargestnumberofeventtypesis150,dividedbythe
5nodes).Tohandlepeaktimes,perhapsthissettingvaluemaybeincreasedto45.
Example:DeterminingSLAUnitsToRetrieve
Asstatedabove,thenumberofassignmentstorequestatonetime(SLAUnitsToRetrieve)is
dependentuponwhethertheagentsarerunninginamultinodesystem.Morespecifically,this
valuedependsuponthesettingforSLARefreshEachIteration.IfthisRefreshsettingisfalse,thenthe
assumptionisyouhaveasinglenodesystem.Inthissituation,youcansetSLAUnitsToRetrieveto
beaveryhighnumber,ascontentionisnotanissueitisrecommendedthatthisvaluebesetto
approximatelydoublethevalueofSLAUnitsToProcess(oralittleless).Youwanttosettheretrieval

valuetobesomewhathigherthantheprocessnumber,incasesomeoftheentriescantbe
processed(duetootherlocksontheworkobjects).
IftheRefreshsettingistrue,thentheassumptionisyouhaveamultinodesystem.Inthatcase,you
shouldkeepthisnumberaslowaspossible,becausethemoreresultsaqueryreturns,theslowerit
performs.However,youwanttobesurethatenoughassignmentsareretrievedsoatleastonecan
beprocessedbytheSLAagent.Itisrecommendedthatyousetthisvaluetobeequaltothe
numberofnodesinthesystem,plussomesmalladditionalnumber(incaseoflocking).Ifthereare
5nodes,thenhavingtheagentononenoderetrieve7or8assignmentsmeansthatatleastone
assignmentwillbeavailabletoprocess(evenifalltheothernodesarecurrentlyprocessing
assignments).
backtotop
Version5.3andprior
InversionspriortoVersion5.4,theSLAsettingshaveadifferentstructurethanothersettings,as
theyarepresentbothasSystemSettingsrules(whicharelocked),andasDynamicSystemSettings
(DataAdminSystemSettingswhichyoumaytune).DeterminehowtheSLAagentshouldprocess
assignments,andthenadjusttheDynamicSystemSettingsaccordingly,asdescribedabove.
Whenpresent,theSLADynamicSystemSettingsoverridetheSystemSettingsvalues.Ifthe
DynamicSystemSettingsarenotpresent,thesystemreadstheSLASystemSettingsinstances,and
thencreatesSLADynamicSystemSettingswiththosedefaultvalues.
WerecommendthatyouusetheDynamicSystemSettingstotestchangesduringdevelopment,and
thenmakeyourpermanentchangesintheSystemSettingsruleswhenyourapplicationisreadyfor
production.
TochangetheSLASystemSettingsrules:
1.DeletethethreeexistingDynamicSystemSettingsforSLA.
2.ReviewyourSLAagentusage,thespeedandthroughputofyoursystem,andthenumberof
workobjects(withanSLAvaluetoprocess)thatarecreatedinaday.Determinethevaluetosetfor
SLAUnitsToProcessandSLAUnitsToRetrieve.
3.FromRulesbyType,expandtheSysAdminlink.ClickonSystemSettings.
4.OpentheSLAUnitsToProcessrule.ClickSaveAs,andsavethisruletoyourapplication
RuleSet.
IMPORTANT:MakesurethatyourSLAagenthasaccesstotheapplicationRuleSetwhereyou
savetheSystemSettings.(ProbablythiswillbetheRuleSetwhereyourworkobjectsaredefined,

sotheagentshouldalreadyhaveaccesstothisRuleSet,butverifythis.SeeAccessGroupsfor
Agentsfordetails.)

5.Foreachlevel,changetheValuefieldtothevalueyoudeterminedinStep2,andsaveyour
changes.
6.Repeatsteps4&5fortheSLAUnitsToRetrievesetting.
7.Ifyouhaveamultinodesystem,repeatsteps3&4fortheSLARefreshListEachIteration.For
eachlevel,changethevaluefromfalsetotrue,andsaveyourchanges.
TochangetheSLADynamicSystemSettings:
1.ReviewyourSLAagentusage,thespeedandthroughputofyoursystem,andthenumberof
workobjects(withanSLAvaluetoprocess)whicharecreatedinaday.Determinewhatvalueto
setforSLAUnitsToProcessandSLAUnitsToRetrieve.
2.FromRulesbyType,expandtheSysAdminlink.ClickonDynamicSystemSettings.
3.OpentheSLAUnitsToProcessinstance.

4.ChangetheValuefieldtothevalueyoudeterminedinStep1,andsaveyourchanges.
5.Repeatsteps3&4fortheSLAUnitsToRetrievesetting.
6.Ifyouhaveamultinodesystem,repeatsteps3&4fortheSLARefreshListEachIteration.
Changethevaluefromfalsetotrue,andsaveyourchanges.
backtotop
Version5.4
InVersion5.4,theSLASystemSettingsareconfiguredthroughSystemSettingrulestheDynamic
SystemSettingsarenolongerused.
Aswithotherrules,theSystemSettingsrulesshippedinthestandardProComRuleSetsarelocked
andcannotbechanged.However,becausetheyarerules,RuleResolutionwillapplyifyouneedto
changeavaluefortheSystemSettings,youcansavetheSystemSettingruletoahigherlevel
RuleSetintheapplicationandchangeitsvalue.Whentheapplicationisrun,theruleinthehigher
levelRuleSetoverridestheoneinthelockedPegaProComRuleSet(asalways).
TochangetheSLASystemSettings,usethefollowingprocedure:
1.ReviewyourSLAagentusage,thespeedandthroughputofyoursystem,andthenumberof
workobjects(withanSLAvaluetoprocess)whicharecreatedinaday.Determinewhatvalueto
setforSLAUnitsToProcessandSLAUnitsToRetrieve.
2.FromRulesbyType,expandtheSysAdminlink.ClickonSystemSettings.
3.OpentheSLAUnitsToProcessrule.ClickSaveAs,andsavethisruletoyourapplication
RuleSet.
IMPORTANT:MakesurethatyourSLAagenthasaccesstotheapplicationRuleSetwhereyou
savetheSystemSettings.(ProbablythiswillbetheRuleSetwhereyourworkobjectsaredefined,

sotheagentshouldalreadyhaveaccesstothisRuleSet,butverifythis.SeeAccessGroupsfor
Agentsfordetails.)

4.Foreachlevel,changetheValuefieldtothevalueyoudeterminedinStep1,andsaveyour
changes.
5.Repeatsteps3&4fortheSLAUnitsToRetrievesetting.
6.Ifyouhaveamultinodesystem,repeatsteps3&4fortheSLARefreshListEachIteration.For
eachlevel,changethevaluefromfalsetotrue,andsaveyourchanges.
backtotop