Best Practices & Design Guide

best practices & design guide this guide helps you design, maintain, and safely extend approvals pro processes it covers recommended patterns, important behaviors to be aware of, and a maintenance checklist to follow when making changes prerequisite complete the initial setup steps in the installation guide docid\ ojiwclkiogqe3gm0juavq before reading this page 1\ understand the object model before designing processes, ground yourself in the hierarchy approval process └── approval path (parallel or sequential) └── approval step (assigned to users or groups) └── approval (individual approver action) └── approval request (the record submitted) key relationships a process can have multiple paths running in parallel or with dependencies between them each path can have multiple steps , executed sequentially within the path steps can depend on other steps within the same path; paths can depend on other paths matrix criteria can be applied at both path and step levels for data driven routing full schema reference object model 2\ designing paths & steps 2 1 parallel paths vs dependent paths parallel paths run independently — all are triggered on submission and proceed simultaneously dependent paths wait until their prerequisite path(s) complete before activating recommendations use dependent paths when sequencing matters — e g , a final qa approval path should depend on a deal desk path so it only activates after deal desk approves note approvers on a dependent path may receive notifications and be able to take action before the prerequisite path fully completes advise approvers to wait for their formal notification before acting 2 2 "skip if not applicable" — use with caution the skip if not applicable setting controls what happens when a step or path's entry criteria are not met checked the step is created in skipped status (provides an audit trail) unchecked the step is not created at all important behavior when using dependent paths with skip if not applicable enabled, if all steps in the prerequisite path are skipped (because none met their entry criteria), the dependent path may remain in dependent status and the approval request stays pending how to avoid this ensure you are on the latest approvals pro package version (addressed in recent releases) if you can't upgrade immediately, uncheck skip if not applicable on paths that serve as dependencies for other paths 2 3 entry criteria + matrix = or logic when a path or step has both entry criteria and a matrix configured, the system evaluates them as or — if either evaluates to true, the path/step is triggered this is a common point of confusion, as most admins expect and example a step has entry criteria discount approval required c = true and a matrix checking quote line amounts > $10,000 if the checkbox is true but the amount is below the threshold, the step still triggers because the entry criteria alone satisfied the or recommendation use one mechanism per step — either entry criteria or matrix, never both if you need both conditions, consolidate them into the matrix by adding the field check as a matrix line condition 2 4 keep step dependencies simple steps within a single path can be configured as dependent on prior steps this is the recommended way to enforce sequential approval within a single track keep step dependencies simple and linear (step 1 → step 2 → step 3) avoid complex cross step dependency webs — they become very hard to debug when something gets stuck 3\ smart approvals (remember approval decision) smart approvals remembers previous approval decisions so that when a record is recalled and resubmitted, already approved steps are not re triggered — unless relevant field values changed 3 1 how it works enable remember approval decision on each step where you want this behavior enable validate field changes on conditions where approvals should be re triggered if specific field values change on resubmission, approvals pro compares current field values against the values at the time of the last approval 3 2 important behaviors dependent steps after recall/resubmit when step 2 depends on step 1 and both have remember approval decision enabled, ensure you are on the latest package version earlier versions had an issue where step 2 could remain in new status instead of advancing to assigned after a recall and resubmit new process version resets remembered decisions if you activate a new version of an approval process while a record is in a recalled state (not yet resubmitted), resubmitting promotes the record to the new process version smart approvals does not carry over remembered decisions across process versions — all steps will require re approval recommendations avoid activating new process versions while records are in a recalled state if you must update a process, wait until all in flight recalled records have been resubmitted first plan for a transition period where admins may need to manually handle records that had their decisions reset 3 3 validate field changes checkbox this setting causes a step to be re evaluated when tracked fields change on resubmission it is configured per condition enable on conditions that gate pricing sensitive or discount sensitive approvals the checkbox may need to be added to your page layout before it is visible in the configuration ui for numeric field comparisons, the engine is nuanced if the new value still triggers the original condition and is no worse than the previously approved value, the step is skipped only a change in a "worse" direction re triggers full mechanics entry criteria → validate field changes 4\ recall and resubmit 4 1 enabling resubmit the allow resubmit setting must be enabled on the approval process for users to resubmit records after they have been approved or rejected without it, users won't see a resubmit button after the approval status changes to approved or rejected why resubmit matters after a quote is approved and unlocked, reps may make further changes (e g , a higher discount) resubmit triggers re evaluation of which steps need re approval steps whose triggering conditions haven't changed are remembered (if smart approvals is enabled) 4 2 recall permissions by default, only the submitter and admins can recall an approval request to enable other users (e g , deal desk coordinators, operations staff) to recall create a custom permission set (e g , approvalsprorecalluser ) add the recallanyapprovalrequest custom permission (shipped with approvals pro) assign to the relevant users to recall records that are already approved (not just pending), also set allowrecallofapprovedrecord = true in approvals pro settings full walkthrough recall & resubmit 4 3 recalled record with no matching paths if a recalled record is resubmitted and no longer meets the criteria of any approval path, the submission may fail rather than auto approving recommendation ensure at least one "catch all" path exists in your process, or build a flow that auto approves when no approval paths are triggered 5\ record locking 5 1 setup enable apex record locking in salesforce setup ( setup → process automation settings ) — required for approvals pro to lock records enable lock record after submit in the approval process settings when a record is locked only system admins can edit it by default approvers can also edit if allow to edit record by approvers is enabled on the process 5 2 records remaining locked after approval in certain configurations involving dependent paths with unanimous approval, path or step statuses may remain pending even after all individual approvals complete this can leave the record locked how to address ensure you are on the latest approvals pro package version as a safeguard, build a record triggered flow that checks if all approval records have status = 'approved' but the approval request is still pending , update the request status and unlock the record 5 3 selective field locking if you want to lock only specific fields during approval (e g , pricing fields) while leaving others editable, use salesforce validation rules targeting the approval status field rather than full record locking and( ispickval(appro approval status c, 'pending'), ischanged(your protected field c) ) this prevents changes to sensitive fields during approval while allowing non approval fields to be edited freely 6\ syncing quote status with approval status approvals pro maintains its own appro approval status c field on the approval request this is separate from the standard salesforce quote status field 6 1 why this matters managing two statuses can create confusion for reps and cause downstream issues — for example, billing or cpq processes that depend on quote status being "approved" may not trigger if only the approval status is updated 6 2 recommended approach build a record triggered flow that syncs the approvals pro status to the quote status trigger when appro approval status c changes on the approval request action update the related quote's status field to match additionally, add a validation rule to prevent users from manually overriding the quote status in a way that conflicts with the approval status and( not(isblank(text(appro approval status c))), ischanged(status), / add your specific mismatch conditions here / ) for records that bypass approvals when the approval status is blank (no approval was required), exclude these from the validation rule so users can set the status directly 7\ matrix criteria matrices allow dynamic approval routing based on record or line item values (e g , trigger approvals for discounts > 20% or for specific product lines exceeding a dollar threshold) 7 1 recommendations keep matrix logic simple each matrix line should test one clear condition do not combine entry criteria with matrix on the same step they evaluate as or (see section 2 3) consolidate all conditions into the matrix instead test in preview mode ( show approval path ) before activating the process ensure referenced fields are always populated matrix line criteria that reference null field values can cause errors full setup approval matrices 8\ managing approvers and process versions 8 1 changing an approver type (user to group or vice versa) changing an approver assignment on a step will disrupt any active workflows on that step safest approaches wait for all in progress approvals on that step to complete, or recall all in progress records, make the approver change, then resubmit do not change approver types while records are actively being approved on that step 8 2 creating new process versions approvals pro supports multiple process versions running simultaneously in progress approvals continue on their original version new submissions use the newly activated version recommendations always create a new version when making changes — do not edit the active version directly plan for a transition period where some records may be on the old version and others on the new do not deactivate an old version while records are still in flight on it full walkthrough process versioning & deployment 8 3 moving steps between paths steps cannot be moved directly from one path to another to relocate a step deactivate (or delete) the step in the original path recreate it under the target path with the same configuration 9\ email notifications 9 1 email templates approvals pro uses classic (visualforce) email templates included in the managed package or created by you lightning email templates are not supported see email templates options for customization set up the email service with the approvalemailservice apex class to enable reply to approve build custom notification flows that trigger on approval record creation or status changes 9 2 path level notifications by default, notification emails are sent when the entire approval request is approved — not when individual paths complete if you need per path notifications, build a flow that triggers when a path's status changes to approved 10\ preview vs submit two distinct capabilities — design for the right one record specific preview ("for this quote, which path will fire and who will approve?") — provided only by the built in show approval path button rendered by the approvals pro lightning component on the record page it evaluates entry criteria and matrix conditions against the current record state configuration catalogue ("what approval paths are configured on this object, and what's their structure?") — provided by appro approvalpathinvocableservice (callable from apex or as a flow invocable) returns static path metadata; does not take a record id and does not evaluate any record's data 10 1 customising the preview experience the approvals pro lightning component renders show approval path alongside submit for approval by default two distinct controls govern what each user sees hidesubmitforapprovalbtn (org wide setting) set to true to hide the default submit button on every record page using the approvals pro component, while leaving show approval path in place configured at setup → custom settings → approvals pro settings → manage toggle this when you want submit to live on a custom button, quick action, or screen flow instead of on the default component submitrecordforapproval (per user custom permission) gates whether a given user can submit at all — regardless of which ui surface they use hiding the default button does not revoke this permission; users still need it to submit through any custom affordance you build together, these let you (a) suppress the default submit button org wide, (b) place submit elsewhere via the submit for approval invocable action, and (c) keep the per user gate on who can actually submit full walkthrough use cases → preview the approval path there is no public service today that performs record specific preview programmatically — to put preview in a place other than the standard record page, embed the approvals pro component on the target lightning page rather than building a custom preview ui 10 2 recommend preview before submit encourage users to open show approval path before clicking submit so they can see which paths and steps will be triggered earlier package versions enforced this (submit was gated on a prior preview); recent versions decouple the two verify behavior against your installed package version ( setup → installed packages ) before relying on either 11\ automation with flows & apex 11 1 invocable actions approvals pro exposes invocable apex actions for use in salesforce flows submit for approval — triggers the approval process for a record approve / reject — programmatically resolve approvals reassign — move an approval to a different user/group recall — recall a submitted record warning salesforce has standard invocable actions with similar names always select the action with the approvals pro namespace ( appro ) full catalog invocable actions 11 2 global methods (apex) for deeper programmatic integration, use the appro approvalutilscontroller global class see global methods 11 3 never directly update status fields do not directly update appro status c , appro path status c , or appro step status c via dml, flow field updates, or data loader always use the approvals pro invocable actions or global methods direct updates bypass workflow logic, skip notifications, and corrupt approval history 12\ permission sets & visibility 12 1 required permission sets permission set purpose approvalspro admin user full configuration and management access approvalspro approver user approve and reject assigned approvals approvalspro submitter user submit records for approval full reference permission reference 12 2 admin visibility across processes by default, admins may only see approval paths and processes they created to enable all admins to view and manage all processes, configure the organization wide default (owd) sharing settings and sharing rules on approvals pro custom objects 12 3 component not appearing if the approvals pro component does not appear on record pages, verify the user has the correct permission set assigned the approvals pro license is active and has not expired the approval component has been added to the lightning record page layout 13\ non standard objects approvals pro references the name field on the object being approved if you are running approvals on objects that do not have a standard name field (e g , case uses casenumber ), you may encounter an error resolution ensure you are on the latest approvals pro package version, which includes support for objects without a standard name field 14\ maintenance checklist use this checklist whenever you add or modify an approval process create a new version of the process (never edit the active version directly) verify no in flight records are in a recalled state before activating the new version test in preview mode (show approval path) before any live submission check for entry criteria + matrix overlap on the same step (they evaluate as or) validate skip if not applicable settings on paths that other paths depend on test the recall → resubmit flow with smart approvals to confirm decisions are remembered confirm email notifications fire at the expected points in the process test edge cases no matching paths, all steps skipped, approver changes mid flight verify record locking/unlocking behaves correctly after approval completes confirm quote status sync — your flow updates quote status from the approval status 15\ troubleshooting quick reference symptom likely cause resolution approval request stuck in pending after all steps approved dependent path + "skip if not applicable" with all steps evaluating to false upgrade to latest package; or uncheck "skip if not applicable" on prerequisite paths matrix based step triggers when conditions are not met entry criteria + matrix evaluated as or use only matrix; move entry criteria into matrix lines record remains locked after approval completes step/path status stuck in pending upgrade to latest package; add a safety net flow smart approvals decisions lost after resubmit new process version activated while record was in recalled state avoid activating new versions during the recall window resubmit button not visible after approval "allow resubmit" not enabled on the process enable "allow resubmit" in approval process settings dependent step stays in new after recall/resubmit earlier package version issue with step propagation upgrade to latest package submit button does nothing older package versions required show approval path to be opened before submit open show approval path first; or upgrade — recent versions decouple preview from submit verify via setup → installed packages "invalid field name" error on submission object does not have a standard name field upgrade to latest package recalled record fails on resubmit with no matching paths no approval paths match current field values add a catch all path or handle with a flow approver acts on dependent step before prerequisite completes notification timing on dependent paths advise approvers to wait for their formal notification admin cannot see approval paths created by another admin salesforce sharing/visibility settings configure owd and sharing rules on approvals pro objects error when adding custom field to configure columns unsupported field type in column configuration remove the custom field from the columns configuration always ensure you are running the latest approvals pro package version many of the behaviors described above have been addressed in recent releases see the package upgrade guide for upgrade instructions