Skip to main content

Hi Folks,   

We are migrating data from one Salesforce org to another, and some of our custom objects contain approval history records. Specifically, we need to migrate the information stored in ProcessInstance and ProcessInstanceStep. 

However, I’m unable to insert or update these approval history records during the data migration. Is there any supported method to migrate or replicate approval history in the target org? Has anyone successfully handled Approval Process history during an org-to-org migration? 

Any suggestions or best practices would be appreciated.   

 

@* Sales Cloud - Best Practices *  @* Sales Cloud - Getting Started *

1 resposta
  1. 29 de dez. de 2025, 08:25

    Hi @Saivaj C S

    It is not possible to directly migrate or insert records into ProcessInstance or ProcessInstanceStep tables. These are system-managed, read-only objects that Salesforce generates automatically only when an actual approval event occurs. 

    Since you cannot "replay" history to populate these standard tables, you must use a workaround to preserve the data for audit and reference purposes.

    1. Recommended Solution: The "Shadow" Custom Object

    The industry-standard best practice is to migrate this data into a custom object created specifically to store legacy history. 

    • Step 1: Create a Custom Object
      • Create an object named Legacy_Approval_History__c.
      • Create fields to map the essential data: Approver_Name__c, Step_Status__c (Approved, Rejected), Comments__c, Date_Acted__c, and Original_Actor__c.
      • Create a Master-Detail or Lookup relationship to the parent object (e.g., Opportunity or your custom object) so this history appears as a related list on the migrated record.
    • Step 2: Export Source Data
      • Use Salesforce Data Loader or a query tool to export ProcessInstance and ProcessInstanceStep data from your source org.
      • You will likely need to join these exports to get a clean flat file (e.g., "Record X was approved by Person Y on Date Z with Comment A").
    • Step 3: Import to Target
      • Insert these records into your new Legacy_Approval_History__c object using the Data Loader.
      • Result: Users will see a related list called "Legacy Approval History" on the record, preserving the audit trail, even though it is not in the standard Salesforce approval component. 

    2. Alternative: File Attachments (PDF)

    If you do not need to report on this data and strictly need it for compliance:

    • Generate a PDF summary of the approval history for each record in the source org.
    • Migrate these PDFs as Files/Attachments linked to the parent records in the target org.

    3. Handling "Pending" (Active) Approvals

    You cannot migrate an approval process in a "Pending" state.

    • Strategy: You must identify all records currently pending approval in the source org.
    • Action: These records must be re-submitted for approval in the target org after migration. You can automate this using a script or Flow to trigger the approval process immediately after the record is inserted, but the "clock" and step history will reset.

    Summary of ConstraintsHi It is not possible to directly migrate or insert records into ProcessInstance or ProcessInstanceStep tables.