ScriptObject Object.

🡨 Go Back to Export.json File Overview

ScriptObject Object Overview
Usage of ScriptObjects
ScriptObject Object Properties

ScriptObject Object Overview ⇧

Within the SFDMU's export.json file, the ScriptObject object functions as a child element of the global Script object. This structure allows for specific configuration settings tailored to individual Salesforce objects (sObjects).

Properties defined within a ScriptObject are designed to override equivalent properties at higher levels in the configuration hierarchy. This capability ensures that settings can be customized for each sObject, providing precise control over the migration parameters for those particular objects.

Usage of ScriptObjects ⇧

The objects property of the Script object is utilized to declare an array of ScriptObjects that are processed during the migration. Below is how they can be configured:

{
  "objects": [
    
    // ScriptObject for upserting Accounts
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      // Additional ScriptObject properties
    },
    
    // ScriptObject for upserting Contacts
    {
      "query": "SELECT Id, AccountId FROM Contact",
      "operation": "Upsert",
      "externalId": "LastName",
      // Additional ScriptObject properties
    }
  ]
}

ScriptObject Object Properties ⇧

afterAddons (Array of AddonManifestDefinition) ⇧

Optional. Defines add-ons that are executed after the migration operation. For detailed information on the events that can be utilized, see: Supported Add-On Api events.

Item Type: AddonManifestDefinition

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "afterAddons": [
        {
          "module": "PostMigrationCleanup",
          "args": {
            "cleanupType": "Remove Temporary Data"
          }
        }
      ]
      // Additional ScriptObject properties
    }
  ]
  // ... other export.json properties
}

afterUpdateAddons (Array of AddonManifestDefinition) ⇧

Optional. The afterUpdateAddons property in the export.json file specifies add-ons that are activated after each update operation during a migration job. For further details on the types of add-on events supported, refer to: Supported Add-On Api events.

Item Type: AddonManifestDefinition

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Contact",
      "operation": "Update",
      "externalId": "Email",
      "afterUpdateAddons": [
        {
          "module": "PostUpdateTasks",
          "args": {
            "task": "Verify Contact Data"
          }
        }
      ]
      // Additional ScriptObject properties
    }
  ]
  // ... other export.json properties
}

beforeAddons (Array of AddonManifestDefinition) ⇧

Optional. Defines events that trigger before the migration operation. More details are available at: Supported Add-On Api events.

Item Type: AddonManifestDefinition

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "beforeAddons": [
        {
          "module": "PreMigrationAudit",
          "args": {
            "checkDuplicates": true,
            "logLevel": "verbose"
          }
        }
      ]
      // Additional ScriptObject properties        
    }
  ]
  // ... other export.json properties    
}

beforeUpdateAddons (Array of AddonManifestDefinition) ⇧

Optional. Specifies add-ons to be invoked before each update operation within the migration job. Detailed information can be found at: Supported Add-On Api events.

Item Type: AddonManifestDefinition

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Update",
      "externalId": "AccountId",
      "beforeUpdateAddons": [
        {
          "module": "DataValidationModule",
          "args": {
            "validateFields": ["Email", "Phone"],
            "errorHandling": "log"
          }
        }
      ]
      // Additional ScriptObject properties        
    }   
  ] 
  // ... other export.json properties    
}

bulkApiV1BatchSize (Integer) ⇧

Optional. Specifies the batch size for Bulk API V1 operations at the object level, overriding the global setting if provided.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "bulkApiV1BatchSize": 9500
      // Additional ScriptObject properties        
    }
  ]
  // ... other export.json properties    
}

deleteByHierarchy (Boolean) ⇧

Optional, Default: false The deleteByHierarchy property in the SFDMU Plugin's ScriptObject activates hierarchical deletion of records from the source. When set to true, it modifies the typical "Delete" operation to remove not only the records specified by the query but also all related records, effectively cleaning entire data hierarchies.

This property ensures that no related data remains in the source, making it ideal for comprehensive cleanup tasks where dependencies between records must be addressed.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Delete", // Default target is the destination
      "deleteByHierarchy": true // Overrides to delete records from the source hierarchically
      // Additional ScriptObject properties                
    }    
  ]
  // ... other export.json properties    
}

This setup ensures a thorough cleanup of both the selected and related records from the source, adhering strictly to defined relational hierarchies. For more details, refer to Advanced Features: Delete by Hierarchy.

deleteFromSource (Boolean) ⇧

Optional, Default: false The deleteFromSource property in the SFDMU Plugin's ScriptObject specifies whether records selected by the object's query should be deleted exclusively from the source organization. When set to true in conjunction with the "Delete" operation, it ensures that only source data is removed, and no operations are performed on the destination.

Without setting deleteFromSource to true, the "Delete" operation targets the destination organization, removing records there instead. This property is critical for precise data management, especially when the aim is to clean the source environment without affecting the target.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Opportunity",
      "operation": "Delete",        // Default target is the destination
      "deleteFromSource": true      // Alters target to the source
      // Additional ScriptObject properties                
    }    
  ]
  // ... other export.json properties    
}

This configuration ensures deletion occurs only in the source organization, thereby leaving the destination data intact. For complete details on this functionality, refer to the section on Advanced Features: Delete from Source in the SFDMU documentation.

deleteOldData (Boolean) ⇧

Optional, Default: false. When set to true, old target records are deleted before performing any further operation. This acts similarly to the Delete operation but allows for additional operations like insert or update to be performed concurrently.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "deleteOldData": true
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

deleteQuery (String) ⇧

Optional, Default: none. Defines a SOQL query string used to select old records from the target organization for deletion. If omitted, the main ScriptObject.query is used for both deleting and updating records.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "deleteQuery": "SELECT Id FROM Account WHERE LastModifiedDate < LAST_YEAR"
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

excluded (Boolean) ⇧

Optional, Default: false. Setting this property to true excludes the corresponding sObject from the migration process. This is useful for documentation purposes or when certain sObjects need to be temporarily disabled without removing their configuration.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "excluded": true
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

excludedFields (Array of string) ⇧

Optional. Specifies field names to be excluded from the data migration process. These fields are omitted from the original SOQL query and do not participate in the migration.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "excludedFields": ["Phone", "Name"]
    }
  ]
  // ... other export.json properties    
}

Details:

Function: The excludedFields array ensures specified fields are not retrieved during SOQL query execution, effectively omitting them from the migration.
Usage: Useful when using multiselect keywords to exclude fields due to access restrictions or irrelevance.

excludedFromUpdateFields (Array of string) ⇧

Optional. This parameter specifies field names that should be excluded from being updated in the target organization. While these fields are retrieved from both the source and target organizations, they are not updated in the target.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "excludedFromUpdateFields": ["Phone", "Name"]
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

Details:

Functionality: The excludedFromUpdateFields array allows fields to be included in SOQL queries and retrieved from both source and target organizations, but ensures these fields are not updated in the target organization.
Use Case: This setting is particularly useful when fields need to be accessed for purposes such as data transformation or validation (via TransformRecords Core Add-On) but should not be altered in the target.
Comparison: Unlike the excludedFields property, which completely omits fields from the migration process, excludedFromUpdateFields retrieves but does not update them in the target org.

externalId (String) ⇧

Optional, Default: "Name" or different name field according to the sObject type Defines the external ID field for the sObject, which is used to map child records and manage relationships during migration operations other than "Insert" and "Readonly". It's crucial that the field name is spelled correctly as this setting is case-sensitive.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "UniqueField__c"
      // Additional ScriptObject properties                
    }    
  ]
  // ... other export.json properties    
}

fieldMapping (Array of MappingItem) ⇧

Optional. Provides field mappings as defined in the Fields Mapping documentation.

Item Type: MappingItem

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id, Name FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "fieldMapping": [
        {
          "sourceField": "Name",
          "targetField": "NewName__c",
          "targetObject": "Account__c"  
        }
      ]
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

filterRecordsAddons (Array of AddonManifestDefinition) ⇧

Optional. Specifies add-ons to filter records during the migration process. Further details can be found at: Supported Add-On Api events.

Item Type: AddonManifestDefinition

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT all FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "filterRecordsAddons": [
        {
          "module": "AdvancedFiltering",
          "args": {
            "criteria": "Active Accounts Only",
            "excludeFields": ["InactiveDate"]
          }
        }
      ]
      // Additional ScriptObject properties                
    }    
  ]
  // ... other export.json properties    
}

hardDelete (Boolean) ⇧

Optional, Default: false. When set to true, records are hard deleted from the target org, bypassing the Recycle Bin. This option can be used in conjunction with other deletion operations such as Delete, DeleteSource, and DeleteHierarchy, or when deleteOldData=true is set and the Bulk API is in use.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "hardDelete": true
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

master (Boolean) ⇧

Optional, Default: true. This property controls the data processing mode for the object within the data model hierarchy. Setting this property to true designates the object as a "master," ensuring that all its records are processed, whereas setting it to false marks the object as a "slave," where only a minimal subset of records necessary for maintaining relationships with selected parent objects from other configurations are processed.

Example of export.json Configuration:

{
  "objects": [
    {
    "query": "SELECT Id, AccountId FROM Contact",
    "operation": "Upsert",
    "externalId": "Name",
    "master": false
    // Additional ScriptObject properties                
  }
  // ... other export.json properties
}

Details:

Master Setting (true): Assigns the object as a "master" in the data model hierarchy. The Plugin processes all records for this object, adhering to any specified limitations or conditions, such as a LIMIT clause in the SOQL query.
Slave Setting (false): Converts the object to a "slave" role relative to "master" objects in the configuration. This setting directs the Plugin to determine and process only the essential subset of records required to preserve relationships between objects. The actual number of records processed may vary, potentially ignoring the LIMIT clause depending on relational requirements.

mockFields (Array of MockField) ⇧

Optional. Defines fields that should be updated with anonymized data during the migration process. Details on how to configure data anonymization are available in the Data Anonymization documentation.

Item Type: MockField

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id, Name FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "mockFields": [
        {
           "name": "Name",
           "pattern": "name",
           "excludedRegex": "^DummyAccount$",
           "includedRegex": "Account\\sTo\\sMask"
        }
      ]
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

operation (String) ⇧

Optional, default "Readonly" This parameter specifies the type of operation to be executed on the Salesforce Object (sObject) during the migration process. It defines how records will be handled, with each operation tailored to specific use cases.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name"
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

Details: The operation setting determines how data is processed for the current sObject:

"Insert": Creates new records in the target organization, regardless of whether previous versions exist.
"Update": Updates existing records only, overwriting all fields.
"Upsert": Performs an insert or update operation based on the presence of the record, overriding existing values.
"Readonly": Retrieves records without making any changes; useful for including sObjects that are referenced from another sObject but are not to be modified.
"Delete": Removes records from the target organization; does not update or alter them.
"HardDelete": Similar to "Delete", but when using the Bulk API, records are permanently deleted without being sent to the Recycle Bin.
"DeleteSource": Deletes records from the source organization. For more details, see DeleteSource operation.
"DeleteHierarchy": Deletes records and their related hierarchical data from the target organization. For further information, see DeleteHierarchy operation.

parallelBulkJobs (Integer) ⇧

Optional, Default: 1. Defines the number of Bulk API jobs that can be run in parallel for this specific sObject, potentially overriding the global setting.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "parallelBulkJobs": 2
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

parallelRestJobs (Integer) ⇧

Optional, Default: 1. Similar to parallelBulkJobs, this property defines the number of REST API jobs that can be executed concurrently for this specific sObject.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "parallelRestJobs": 2
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

query (String) ⇧

Mandatory. This parameter specifies the SOQL (Salesforce Object Query Language) query string that is used to export fields from the specified Salesforce Object (sObject). The query should encompass all necessary fields for the operation, although nested queries and complex field relationships are not supported. Subqueries for filtering purposes are permitted.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id, Name FROM Account WHERE CreatedDate > LAST_N_DAYS:30",
      "operation": "Upsert",
      "externalId": "Name"
      // Additional ScriptObject properties                
    }
  ]
  // ... other export.json properties    
}

Details:

Query Composition: The SOQL query should list all fields required for export from the sObject, including any referenced fields. The plugin automatically resolves and processes all references between objects, simplifying data handling.
Field Inclusion: Only the fields listed in the query will be exported. Omitting a field from the query means it will not be part of the export.
Query Flexibility: You can refine your data selection using SQL-like clauses such as WHERE, LIMIT, OFFSET, etc., to filter the records according to specific criteria.
Support for Subqueries: While nested queries and complex fields like Account__r.Name are not supported, you can still utilize subqueries within the WHERE clause (e.g., WHERE Id IN (SELECT Id FROM ...)) to enhance query specificity and data relevance.

queryAllTarget (Boolean) ⇧

Optional, Default: false. This setting determines whether all records from the target organization are queried, overriding any limitations (such as WHERE, LIMIT, OFFSET, or ORDER BY clauses) specified in the object's SOQL query. This is particularly useful for ensuring complete synchronization of recent records from the source with all corresponding records in the target.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id, Name FROM Account WHERE LastModifiedDate = LAST_N_DAYS:2",
      "operation": "Upsert",
      "externalId": "Name",
      "queryAllTarget": true
      // Additional ScriptObject properties                
    },
    {
      "query": "SELECT Id, Email FROM Contact WHERE CreatedDate > LAST_N_DAYS:30",
      "operation": "Update",
      "externalId": "Email",
      "queryAllTarget": true
      // Additional ScriptObject properties
    }
  ]
  // ... other export.json properties    
}

Details:

Functionality: When queryAllTarget is set to true, the plugin queries all records from the target organization, bypassing any constraints defined in the SOQL query for the target org. The full query string remains applicable for retrieving records from the source organization.
Use Case: This feature is crucial when you need to synchronize recently modified records from the source organization with all corresponding records in the target organization, irrespective of when those target records were last updated.
Default Behavior: With queryAllTarget set to false, the plugin adheres to the query string's restrictions, retrieving the latest records defined by conditions like LAST_N_DAYS. This might lead to mismatches in source-to-target synchronization if different records have been modified within the specified period in the source and target organizations.
Enhanced Synchronization: Activating queryAllTarget ensures that while recent records are queried from the source, all records from the target are considered for updating. This approach enhances the potential for updated source records to find matching counterparts in the target, thus improving data consistency and synchronization effectiveness.

restApiBatchSize (Integer) ⇧

Optional. Specifies the batch size for REST API operations at the object level, potentially overriding the global setting.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "restApiBatchSize": 500
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

skipExistingRecords (Boolean) ⇧

Optional. When set to true, updates are skipped for records that already exist in the target. This is useful when wanting to insert new records without updating existing ones during an upsert operation.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "skipExistingRecords": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

skipRecordsComparison (Boolean) ⇧

Optional. When set to true, SFDMU skips comparing source and target records during update operations, thereby updating records regardless of whether their data matches.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "skipRecordsComparison": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

targetRecordsFilter (String) ⇧

Optional. Allows the use of an additional SOQL-like expression to filter target records just before they are updated, ensuring only the desired records are affected.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "targetRecordsFilter": "CreatedDate > LAST_N_DAYS:30"
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

Refer for the details: Target Records Filter

updateWithMockData (Boolean) ⇧

Optional, Default: false. When set to true, enables the data anonymization feature for the sObject, allowing sensitive data to be replaced with anonymized values.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "updateWithMockData": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

useCSVValuesMapping (Boolean) ⇧

Optional, Default: false. When set to true and the CSV file is specified as the data source, it enables value mapping for this object, allowing for custom mappings between CSV values and Salesforce field values.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "useCSVValuesMapping": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

useFieldMapping (Boolean) ⇧

Optional, Default: false. When set to true, it enables field mapping for this object, allowing custom mappings between source and target fields.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "useFieldMapping": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

useQueryAll (Boolean) ⇧

Optional, Default: false. When set to true, it uses the /queryAll API endpoint instead of /query when querying source records, allowing inclusion of deleted records in the query result.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account WHERE IsDeleted = true",
      "operation": "Upsert",
      "externalId": "Name",
      "useQueryAll": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

useValuesMapping (Boolean) ⇧

Optional, Default: false. When set to true and the Salesforce org is set as the data source, it enables value mapping for this object, allowing custom mappings between Salesforce org values and target field values.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "useValuesMapping": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

useSourceCSVFile (Boolean) ⇧

Optional, Default: false. When set to true and Salesforce org is set as the data source, it uses a specific CSV file as the source instead of querying the org. This is useful when data needs to be imported from a CSV file into the Salesforce environment for this specific object, while other objects are populated from the source org.

Example of export.json Configuration:

{
  "objects": [
    {
      "query": "SELECT Id FROM Account",
      "operation": "Upsert",
      "externalId": "Name",
      "useSourceCSVFile": true
      // Additional ScriptObject properties                
    }
  ]
    // ... other export.json properties    
}

Last updated on 1st May 2024

SFDMU Overview

Full Documentation

Examples

FAQ

Troubleshooting

Additional Information

ScriptObject Object.

Table of Contents

ScriptObject Object Overview ⇧

Usage of ScriptObjects ⇧

ScriptObject Object Properties ⇧

afterAddons (Array of AddonManifestDefinition) ⇧

afterUpdateAddons (Array of AddonManifestDefinition) ⇧

beforeAddons (Array of AddonManifestDefinition) ⇧

beforeUpdateAddons (Array of AddonManifestDefinition) ⇧

bulkApiV1BatchSize (Integer) ⇧

deleteByHierarchy (Boolean) ⇧

deleteFromSource (Boolean) ⇧

deleteOldData (Boolean) ⇧

deleteQuery (String) ⇧

excluded (Boolean) ⇧

excludedFields (Array of string) ⇧

excludedFromUpdateFields (Array of string) ⇧

externalId (String) ⇧

fieldMapping (Array of MappingItem) ⇧

filterRecordsAddons (Array of AddonManifestDefinition) ⇧

hardDelete (Boolean) ⇧

master (Boolean) ⇧

mockFields (Array of MockField) ⇧

operation (String) ⇧

parallelBulkJobs (Integer) ⇧

parallelRestJobs (Integer) ⇧

query (String) ⇧

queryAllTarget (Boolean) ⇧

restApiBatchSize (Integer) ⇧

skipExistingRecords (Boolean) ⇧

skipRecordsComparison (Boolean) ⇧

targetRecordsFilter (String) ⇧

updateWithMockData (Boolean) ⇧

useCSVValuesMapping (Boolean) ⇧

useFieldMapping (Boolean) ⇧

useQueryAll (Boolean) ⇧

useValuesMapping (Boolean) ⇧

useSourceCSVFile (Boolean) ⇧