Example - Migrating legacy custom objects without relationships

This example guides you through migrating legacy custom object data without relationships (not linked to other records) 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 legacy custom object named Vehicle with the following fields.

Field key	Type	Description
license_plate	string	Vehicle license plate
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
last_service_date	date	Date of the vehicle's last service
vin	string	Vehicle VIN number

Agents use a custom sidebar app to list all vehicles linked to a requester. When an agent selects a vehicle, the app automatically populates the following four ticket fields:

• license_plate
• make
• model
• vehicle_type

Step 1: Defining the new custom objects

First, define a new schema for the Vehicle object for the new Custom Objects framework while keeping in mind the following schema differences:

• Name field: The name field is required and acts as the primary identifier for lookup and search purposes. AutoRep Garage chooses the license plate as the name because it is unique and easy for agents to recognize.

• Field types: The new custom objects framework offers more field types, helping AutoRep Garage organize data better. For example, AutoRep Garage configures the vehicle type as a drop-down field rather than text.

For instructions, see Creating custom objects to integrate with custom data in Zendesk help.

Here is the new custom object schema for this example.

Field Name	Type	Key	Notes
License plate	name (text)	name	Used for search and identification
Make	text	make	Can be coverted to a drop-down later
Model	text	model	Can be converted to a drop-down later
Vehicle type	dropdown with 3 options	vehicle_type	Options: sedan, suv, truck
Owner	lookup (User)	owner
Last service date	date	last_service_date
VIN	text	vin

Note: A user is, by definition, a record of the User object and can be represented as a legacy relationship record. The owner field can be modeled either as a legacy relationship between the Vehicle and User or as a simple text field on the legacy object. For simplicity, this example stores the owner as a text field.

Step 2: Preparing and transforming your record data

Before importing your records into the new framework, 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 for ease of use. 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. For example, convert "SUV" to "suv".
   

Step 3: Uploading and validating your data

To bring your data into Zendesk’s custom objects framework, start by preparing your CSV file with the relevant records. Then, upload the file using Zendesk’s data importer, map your CSV columns to the custom object fields, and initiate the import. After the process completes, review the import summary for any errors, warnings, or skipped rows. If issues are found, correct your data and re-import. Finally, verify that the imported records appear correctly in your custom object. For more information, see Bulk importing custom object records in Zendesk help.

To upload and validate your data:

1. In Admin Center, select Objects and rules > Custom Objects > Objects.

2. Select the Vehicle object.

3. Use Zendesk’s data importer to upload your Vehicle CSV file.

4. Map each CSV column to the corresponding Vehicle object field.

5. Begin the import process and wait for it to complete.

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 file to correct the issues. Re-upload the file following the same import steps.

After successful import, verify the data by opening several Vehicle entries to confirm that all fields are populated correctly.

Step 4: 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's schema and field keys.

Step 5: 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 6: 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.