Deep Copy Setup
Introduction
To create copies of a record with any related or child records, you can add the Deep Copy Lightning Component to any custom object. The Deep Copy Lightning Component feature is available for Lightning pages in FieldFX Back Office. Use Deep Copy to add a new record by copying an existing record and its related items.
For the latest updates, see FX Lightning Package Release Notes.
Copied records and all of the related or child records are locked during the copy process until the copy completes. This includes both the items being copied from and the new records being copied to. |
Deep Copy is a Lightning Component. This component expands on the functionality of the Deep Copy feature, but only works in Lightning Experience. FXL Deep Copy is included in the Base Managed Package and does not require installation of the separate Lightning Managed Package. |
You can add a new job by copying an existing job and its tickets, ticket items, and scheduled crew.
To use the FieldFX Lightning package starting with version 1.225, you must use the FieldFX Managed Package version 1.529 or higher. To find the version numbers you have installed, see Check Version Number for FieldFX Managed Package and FieldFX Lightning Managed Package. |
Prerequisites
To set up or use the Deep Copy feature:
Required Licenses | Required Permissions | Before continuing, complete these tasks |
||||
---|---|---|---|---|---|---|
|
Performance of Deep Copy depends on various factors including, but not limited to, the number of
|
How Deep Copy Works
You can set up Deep Copy component on any custom FieldFX object but not on Salesforce objects.
By default, records deep copy asynchronously (one record at a time).
When you add a new record using Deep Copy:
-
<Copy>
displays at the end of the new record name. -
The new record has a new Tracking Number (if applicable).
-
The new record is in the status that has Initial Status Console selected (if applicable).
-
The following items don’t copy to the new record:
-
The Attachments feature in FieldFX has been deprecated and replaced with the Files API. To upload files to tickets or jobs, make sure the FXL File Viewer Lightning Components is added to the ticket or job record page.
Follow the steps in Set Up Attachments Using the Files API.
-
All affected records are locked during the copy process:
-
Records being copied from are locked from being edited:
-
Originating record
-
All descendant objects related to the originating record (that is children, grandchildren, and so on).
A user deep copies a Job record.
The original Job, the Tickets for that Job, the Ticket Items for each Ticket on the Job, and so on are all locked from being edited.
-
-
New records created and copied to cannot be edited or copied from while locked:
-
New record created as the copy.
-
All new descendant records related to the newly created parent record (that is children, grandchildren, and so on).
A user deep copies a Job record.
The new Job, the Tickets for the Job, the Ticket Items for each Job, and so on are all locked for editing and cannot be copied from.
-
-
Locks are released once the copy process completes and all related items have been copied to new records.
Deep Copy vs. Clone
The Deep Copy Lightning Component copies existing records and their related child items, including children of the child items.
The Clone feature copies existing records but doesn’t copy child items.
Configuration Options
To configure the Deep Copy, you can:
-
Exclude fields from copying
-
Initiate a dry run before copying anything
-
Copy records one at a time
-
Use filters to exclude data from copying
Exclude Fields from Copying
You can exclude fields from copying to new records by adding them to a CloneBlackoutFields field set.
When you add fields to a CloneBlackoutFields field set:
-
Unique values in those fields do not copy to new records
-
Default values for those fields do copy to new records
By default, Deep Copy never copies data from the following fields:
-
Id
-
External ID
-
Status
-
SyncID
-
Tracking Number
-
Auto Number
-
Formula
Also, the data from the these fields are required:
-
Invoice Item fields on ticket items
-
Job lookups on ticket items
Dry Run Mode
Select Dry Run to see what data will copy without actually copying anything.
Use this mode for testing new functionality and troubleshooting issues. |
Asynchronous Mode
Select Syncs to deep copy records asynchronously (one record at a time).
Use this mode for deep copying large items, such as price books. |
Filters
You can use these filters to exclude records meeting criteria from copying.
The system uses JSON notation for filters:
* Add filters in key:value pairs as "sObjectType":"SOQL filter"
Be sure to surround each side of the pair in double quotation marks.
"FX5__Ticket__c":"FX5__Sync__c=true", "FX5__Ticket__c":"RecordType.DeveloperName='Equipment'"
Separate multiple filters with commas. Do not end with a comma.
Archived Items Filter
Use the following filter to only copy items that are not archived.
FX5__IsArchived__c = false
Status Filter
Use this filter when you copy tickets for jobs to avoid copying tickets that are currently In Progress.
FX5__Status__r.Name != "In Progress"
Crew Planning Filter
Use this filter when you copy crew planning records for jobs.
It prevents duplicate crew planning records getting added if you have AutoAddJobCreatorToCrew selected in FX Settings.
{FX5__Crew_Member__r.User__c != "{!$User.Id}" OR (FX5__Role_on_Job__c!=null OR FX5__Charge_Code__c != null)}
Objects with Parent and Child Records
You can copy records that have child records within the same objects.
For example, a price book with child price books or a job with child jobs.
To deep copy a parent job with all of the child jobs and deeper records, use the following filter:
"FX5__Job__c":"(Id IN :sourceIds OR Parent_Job__c IN :sourceIds)"
Best Practices
-
Grant all users sharing access and permissions for records they need to copy.
-
Don’t create a master-detail relationship between two FieldFX objects that matches an existing master-detail relationship.
-
Don’t give a custom object the same name as a FieldFX object.
-
Don’t give a custom field the same name as a managed field on a FieldFX object.
-
Test Deep Copy functionality in a Sandbox before you deploy it to Production.
-
Remove the Clone button from page layouts for objects that feature a Deep Copy button.
-
For self-referencing parent/child relationships, the FXL Deep Copy component only supports up to 2 levels of records.
-
If you are Deep Copying a Timesheet that is in progress, you won’t be able to create a timecard.
If you try a create a timecard during a deep copy, an error occurs since the deep copy is attempting to link the ticket items to the same timesheet as the original ticket item. There are labor ticket items linked to the timecards which are in a locked timesheet.
Step-by-Step Guides
Add and Customize a FXL Deep Copy Lightning Component to a Page
Add the component multiple times to the same page with different configurations, such as one time with Dry Run selected and another time with Dry Run deselected. |
-
Create a Lightning Record page for the object to set up for Deep Copy.
The easiest method is to access a record for the object you would like to add Deep Copy to while in Lightning Experience, select then click Edit Page.
-
Add the FXL Deep Copy Lightning Component to the page.
-
Make the following entries in the component settings:
Command Text
Name of the button users will see on the page.
sObject Types
API names of all of the objects in the tree to copy, separated by commas.
Do not include a space between the sObject names.
If an invalid object is listed, an error message displays and the button is disabled.
Filters
Any additional filters desired to control the items that copy.
List filters in
key:value
pairs of"sObjectType" : "SOQL filter"+
. Separate multiple filters with commas.To limit tickets to the Equipment record type where Sync is true, enter:
"FX5__Ticket__c+":"FX5__Sync__c=true", "FX5__Ticket_Item__c":"RecordType.DeveloperName='Equipment'"
Display Field
Field to show after the Deep Copy.
Use the API name, such as
FX5__Tracking_Number__c
Sync Mode
When to show the information about the copied record.
Selected
Displays record information when the top level record is copied. Child records continue to copy in the background.
Deselected
Does not display copied record information until all child record copies complete.
For most use cases, select this option.
Dry Run
Select to display a message showing how many records from each object type would be copied without actually copying records
Skip Email
Success Run
Select to skip getting emails on if the creation of a record deep copy was successful.
Error Notification
Select to skip getting emails on error notifications when a error occurs from creating a deep copy of the record.
Skip Platform Notification
Select to skip notifications from the platform after the success creating a deep copy of the record.
-
You can optionally define Visibility filters to control when the option displays on the page.
-
Save the page changes and activate as necessary.
Track Source ID Of Origin Records
-
During a Deep Copy with the FXL Deep Copy Lightning component, the origin record ID can be added to the copied record.
-
This can be done for any level of a Deep Copy.
-
The field can be a Text field or a Self-referencing Lookup field.
Use care with a lookup field, as it may affect the org’s limits imposed by Salesforce.
-
For any object where the source ID is desired, add an unmanaged field,
FXDeepCopySource__c
. -
If the field exists on an object during a Deep Copy, the field is populated with the source ID of the copied record.
Create a Lookup Field
-
Go to the org’s Setup page, then select Object Manager
This procedure assumes you are using Lightning Experience. -
Select the object whose records you want to track the source of like a job or a ticket.
-
Select Fields & Relationships.
-
Click New to add a field.
-
Select Lookup as the field type, then click Next.
-
In Related To, select the object you are adding the field to, then click Next.
This creates the self-referencing lookup.
-
Make the following entries:
Field Label
Copy the
FXDeepCopySource
field Label exactly.Field Name
Accept the defaulted entry.
Child Relationship Name
Accept the defaulted entry.
(Optional)
Add a Lookup Filter if desired.
-
Click Next.
-
Adjust field security for profiles as desired, then click Next.
-
Add the field to page layouts as desired by selecting the check box for each page layout and click Save.
-
As needed, modify page layouts for the object to place the field in the desired location.
Create a Text Field
To create a text field, use the Lightning Experience and not Salesforce Classic.
-
Go to the org’s Setup page, then select Object Manager.
-
Select the object whose records you want to track the source of like a Job or a Ticket.
-
Select Fields & Relationships.
-
Click New to add a field.
-
Select Text as the field type, then click Next.
-
Make the following entries:
Field Label
FXDeepCopySource
Copy the Field Label exactly. Length
50
Field Name
Accept the default entry
-
Click Next.
-
Adjust field security for profiles as desired, then click Next.
-
Add the field to page layouts as desired by selecting the check box for each page layout.
-
Click Save.
-
As needed, modify page layouts for the object to place the field in the desired location.