Process Versioning & Deployment

once an approval process is live and records have been submitted against it, approvals pro locks the configuration you cannot edit an active process directly — you must create a new version this preserves audit integrity any historical approval can be traced back to the exact configuration that produced it this page covers the versioning model, how to safely move a process between sandbox and production, and the gotchas to watch for during a version cutover the versioning model every approval process has a version number c when you click create new version the current version is cloned in place (process → paths → steps → approvers → conditions → variables) the clone gets the next version number and starts in inactive state the original version keeps running until you activate the new one when you click activate current version the new version becomes active the previous version is automatically deactivated in flight approvals continue on the previous version new submissions use the new version note matrices are the one exception matrix records ( appro matrix c , matrix field c , matrix line c ) are not cloned by versioning the new version continues to reference the same matrix records as the old one matrix data changes take effect immediately on both active and future versions — which is usually desirable, but means version cutovers cannot be used to "hide" matrix changes step 1 create a new version open the approval process you want to modify click create new version in the top right action bar confirm in the popup — click create the page refreshes and shows the new version the process name gets a suffix (e g , v2 ) to distinguish it step 2 make your changes on the new version, you can edit anything except matrix references add/remove/reorder paths add/remove/reorder steps change approvers on steps change entry criteria conditions and logic update email templates and recipient configuration toggle process and step level settings note nothing you do on the new version affects the active version in flight approvals are safe step 3 test before activating before you activate a new version in production test in a sandbox create the new version in a sandbox first, run test records through the new logic, and confirm the paths, steps, and notifications behave as intended use preview mode on a representative record, open show approval path to preview which steps will trigger without actually submitting check the pre activation state ensure no records are in a recalled state — see the warning in the next section step 4 activate when you're ready, click activate current version on the new version and confirm from that moment new submissions use the new version in flight submissions continue on the old version users approving on the old version don't notice the change — the ui continues to reflect the process version each record was submitted against the "activate while recalled" trap warning if you activate a new version while a record is in the recalled state (not yet resubmitted), the resubmission promotes that record to the new process version smart approvals ( remember approval decision ) does not carry remembered decisions across process versions — all steps will require re approval, even ones that were previously approved avoidance before activating, run a report "approval requests where status = 'recalled' " wait for that list to drain (either resubmit or reject) before flipping the version if you must activate while recalled records exist, plan for admins to manually re approve previously decided steps on those records deploying an approval process between environments approvals pro ships a first class import / export tool for moving entire approval processes between orgs this replaces the older pattern of deploying the underlying records via the metadata api or data loader — it handles the parent child id remapping automatically step 1 export from the source org open the approvals pro app click the import/export tab select the export sub tab pick the approval process to export click export a json file downloads containing the full process configuration — paths, steps, approvers, conditions, variables, email template references note the export does not include matrix data (since matrices are data driven and org specific) or approval email template records (since they reference org specific salesforce template ids) those must be set up separately in the target org step 2 prepare the target org before importing, ensure the target org has everything the process will reference the target object exists (e g , quote , opportunity ) and has all custom fields the process references approval status field exists with the required picklist values ( pending , approved , rejected , recalled ) public groups and roles referenced by approver records exist with matching developername values salesforce email templates referenced by the process exist and have been registered in approval email templates any matrices the process uses exist with matching names step 3 import to the target org open the approvals pro app in the target org click the import/export tab → import sub tab click upload files and select the json from step 1 the system validates references automatically and reports any missing dependencies resolve any issues (usually missing fields or groups) and re upload step 4 activate in target the imported process lands in inactive state run it through preview mode with a test record, then click activate current version deploying via salesforce metadata (alternative) if your release process is ci/cd based (sfdx, change sets, ant migration tool), you can also deploy approvals pro configuration as records via the data loader or a custom deployment script export records in dependency order approver c , variable c , matrix c , matrix field c , matrix line c , approval process c , approval path c , process path c , approval step c , step approver c , condition c use the import key c field (present on most config objects) as your external id set it to a stable, environment agnostic value during export upsert in the same order into the target org, using import key c as the match key the built in import/export is easier for most cases; fall back to metadata based deployment only when you need to integrate with an existing ci pipeline related best practices → managing approvers and process versions docid\ h8xc9gykfudb7auncqlpu package upgrade guide docid\ zmk5zbbwcj1znuhwfyyjm — packaging level upgrades configuring approval processes docid\ kcmpddjgungd5jvuo8ngj — the editing experience for a new version