Example - Migrating legacy custom objects with relationships

This example guides you through migrating legacy custom objectd data with a many-to-one relationship into the new Custom Objects framework.

Example overview

AutoRep Garage, a fictional business, uses Zendesk to manage customer service for vehicle repair requests. Their Zendesk instance includes a relationship between two legacy custom objects: Vehicle and Service Entry, where each Service Entry is associated with a specific Vehicle.

Here is their vehicle-related information in the Vehicle legacy custom object:

Field Name	Type	Key	Notes
license_plate	string	Vehicle license plate	Used for search and identification
make	string	Vehicle make
model	string	Vehicle model
vehicle_type	string	Vehicle type (sedan, suv, truck)
owner_id	string	User id of the vehicle's owner
vin	string	Vehicle VIN number

Here is their service-related information in the Service Entry legacy custom object:

Field key	Type	Description
service_type	string	Type of service
description	string	Description of service performed
date	string	Date of service
cost	string	Cost of service

The one-to-many relationship links the Vehicle object (source) to the Service Entry object (target). This means each service entry record can only be related to one vehicle record. However, a vehicle record could have many service entries.

Step 1: Defining the new custom objects and relationships

AutoRep Garage first creates new versions of the Vehicle and Service Entry legacy custom objects. While creating the new versions of the custom objects, they must keep the following schema differences between legacy and new custom objects in mind:

• Replace legacy relationship types with lookup relationship fields, which are always one-to-many relationships. These lookup fields are placed on the “many” side of the relationship. For example, since one Vehicle can have many Service Entries, the Service Entry object includes a lookup relationship field pointing to the Vehicle.

• New custom objects have a required name field , which acts as the primary identifier for lookup fields and search purposes. In this example, AutoRep Garage decides to use license plate values as the name for Vehicle records because license plates are unique and easy values for agents to recognize.

You can create custom objects either through the Admin Center or programmatically using the custom objects API. For instructions, see Creating custom objects to integrate with custom data in Zendesk help or Creating custom objects in the developer documentation.

Because the Service Entry lacks a proper name field in the source data, configure the new custom object's name field to use an automatically generated number to provide unique names to the imported and future records. Example: use an "SRV" prefix and start numbering from 100000.

With all of those considerations in mind, this is the schema for the new Vehicle custom object:

Field Name	Type	Key
License plate	name (text)	name
Make	text	make
Model	text	model
Vehicle type	dropdown with 3 options	vehicle_type
Owner	text	owner
Last service date	date	last_service_date
VIN	text	vin

This is the custom object schema for the new Service Entry object:

Field Name	Type	Key
Service id	name (autonumber)	name
Vehicle	lookup	vehicle
Service type	dropdown	service_type
Date	date	date
Cost	decimal	cost

Step 2: Preparing and transforming your record data

Before importing your records into the new framework, you must prepare and transform the record data. Export your existing records from Zendesk, clean and standardize the data, and align it with the new schema.

To prepare your custom object records:

1. Export the data from your legacy custom object using List Legacy Objects Record.

   Note: The endpoint response is returned in JSON format, not CSV. In this example, we transformed the JSON response into CSV and placed each dataset on a separate sheet for ease of us. You then export each sheet as its own CSV file since Zendesk imports one CSV file at a time. If you want to convert your data into CSV format, you'll have to do it manually or with a tool or script to facilitate bulk import. For more information on preparing and transforming your record data, see Copying your legacy data over.

2. Modify the CSV headers and data to match the new Vehicle object schema field keys.

   • Rename license_plate to name to match the new mandatory name field.
   • Rename record_id to external_id to uniquely identify each record during import.
   • Updated vehicle-type to be consistent with the Custom Objects asset dropdown in Admin Center. In this example, convert "SUV" to "suv".
   

3. Modify the CSV headers and data to match the new Service Entry object schema field keys.

   • Rename record_id to external_id for building the relationship between the service entry and the vehicle.
   • No name field is required here since the object will be created with an autogenerated name.
   • Standardize vehicle-type values as described above.
   

The Vehicle-to-Service sheet defines the relationship between the Vehicle object (source) and the Service Entry object (target). For example, the first row with entries 1234355 and 1112345 links the oil change service entry to the vehicle with license plate ABC1234 using their external ids.

To create this relationship:

1. Use VLOOKUP or similar function to create a vehicle lookup field in the Service Entry data containing the matching Vehicle's external_id.

   In this example, the formula is =VLOOKUP(E2,'Vehicle-to-Service'!$A$2:$B$6,2,0)

   

2. Update the first vehicle entry's function to =CONCAT("external_id:",VLOOKUP(E2,'Vehicle-to-Service'!$A$2:$B$6,2,0)) and then copy this function down to the other rows. This combines the string "external_id:" with the value returned by VLOOKUP.

   For example, if the VLOOKUP returns "1234355", the full result becomes "external_id:1234355".

   

   Zendesk requires lookup fields to be formatted as external_id:<value>. This formula generates the correctly formatted reference string for the vehicle lookup field in the Service Entry CSV.

If your Vehicle, Service Entry, and Vehicle-to-Service are separate sheets in a spreadsheet, you must first export each sheet as its own CSV file since Zendesk imports one CSV file at a time.

Step 3: Uploading and validating your data

The order in which you import your data matters because you are trying to capture legacy relationship data. In this case, AutoRep must import Vehicle records first because it doesn't contain the lookup relationship field that replaces the legacy relationship. After all legacy Vehicle records have been recreated as new custom object records, the Service Entry records can be imported. This order matters because the Service entry CSV file includes vehicle record external_id values. For more information, see Bulk importing custom object records in Zendesk help.

To import your legacy custom object records:

1. In Admin Center, select Objects and rules > Tools > Data importer.

2. Finalize your CSV file for Vehicle records making sure the external_id field is correctly mapped because it must uniquely identify each Vehicle record.

3. Upload your CSV file for Vehicle records and initiate the import.

4. Review the report summary for any errors or warnings. Resolve any issues before proceeding.

5. Finalize your CSV file for Service Entry records, ensuring the external_id field is included and that the vehicle lookup field is mapped to the corresponding Vehicle external_id. This mapping is important to establish the relationship between Service Entry and Vehicles.

6. Upload your CSV file for Service Entry records and initiate the import.

7. Review the report summary for any errors or warnings. Resolve any issues before proceeding.

Validating the imported data and resolving import issues

Review the import summary and logs, looking for:

• Errors: Rows that failed to import due to invalud data or missing required fields.
• Warnings: Rows imported with potential issues that may required attention.
• Skipped rows: Rows that were ignored during import, possibly due to duplicates or data conflicts.

If you find errors or skipped rows, update your CSV files to correct the issues. Re-upload the correct files following the same import steps.

After successful import, verify the data by opening several Vehicle and Service Entry entries to confirm that the records are accurate and that Service Entry entires correctly link to their corresponding Vehicle.

Step 4: (optional) Replacing the app with lookup relationship fields

You can optionally replace the custom sidebar app to use Lookup relationship fields. This allows agents to select a vehicle directly within the ticket interface without relying on a custom app and end users can choose their vehicle from the help center when submitting requests.

To replace the sidebar app:

1. Create a lookup relationship field on the Ticket object that points to the new vehicle custom object.

2. Apply a dynamic filter on this lookup so that only vehicles owned by the ticket requester are shown.

3. Add this lookup field to the appropriate ticket forms used by agents and end users.

4. (Optional) Use cards to display additional vehicle details such as VIN and last service date—directly on the ticket sidebar.

Step 5: (optional) Updating the sidebar app

If you prefer to keep using the custom sidebar app, you’ll need to update it to work with the new custom objects framework.

To update the sidebar app:

1. Modify your app’s API calls to use the new Custom Objects APIs. For example, use this search endpoint to retrieve vehicles owned by a requester:

POST /api/v2/custom_objects/vehicle/records/search
Content-Type: application/json

{
  "filter": {
    "owner": { "$eq": "<requester_id>" }
  }
}

1. Update your app’s logic and data handling to match the new object schema and field keys.

Step 6: Configuring permissions

Grant appropriate permissions so users can access and manage vehicle data securely. With new custom objects you can grant agents and end users permissions. For example, you can:

• Allow agents to read and update vehicle records.
• Enable end user read access if you want customers to select their vehicles in Zendesk Guide.
• Make sure the vehicle lookup field is visible on help center ticket submission forms.

Step 7: Validating and cleaning up

Complete the migration with validation and cleanup steps:

• Compare the number of records in the new custom object with the legacy data to ensure completeness.
• Test workflows from both agent and end-user perspectives to confirm everything works correctly.
• After confirming the updated workflows with new custom objects are successful, delete the legacy custom object records, the the legacy custom objects themselves, and remove any outdated API references, custom app dependencies, or integrations tied to the legacy object.