Skip to main content

Custom object records

Zuora

Custom object records

Zuora Custom Objects provide the service to define custom objects. You can extend the Zuora data model to accommodate your specific use cases with custom objects.

This article describes how to view, create, update, and delete custom object records through UI. If you want to access custom object records by API, see Custom Object Records and Custom Object Jobs in Zuora API Reference.

View custom object records

To view custom object records, perform the following steps:

  1. Navigate to Platform > Object Manager.
  2. Click the object name in the Label column. The custom object records page opens.
    You can find all custom object records of the current custom object from the list view.

When using custom object records, keep the following notes in mind:

  • The maximum number of records that can be displayed in the record list is 100,000.
  • The ID of a custom object record contains 36 characters, including four hyphens. For example, 98687943-22ec-4283-be45-01cefb6e5ece.

Create a new custom object record

To create a new custom object record manually, perform the following steps:

  1. Click the Create icon Create.png at the upper right of the record list view.
  2. Input the value for each field and click Save.

If the custom object definition contains a relationship type of field, you need to fill in the mapping field value of the related object. Custom object service currently only supports the related object's ID as the mapping field.

The maximum number of records that you can create for an object type is 10,000,000.

Note that you should not store PCI, sensitive PII, or other regulated data in custom objects. See Responding to individual requests for access, correction, and deletion of data under applicable privacy laws for more information.

You can also create custom object records in bulk. For more information, see Create custom object records in bulk.

Edit a custom object record

To edit a custom object record, perform the following steps:

  1. Click the ID of a custom object record from the record list view. The record details page opens.
  2. Click the edit icon Edit.png to enable the edit mode, and then update the record details as needed.
    Note that if you click the edit icon again, Zuora will exit the edit mode without saving any of your changes.
  3. Click the save icon Save.png to save your changes.

You can also edit custom object records in bulk. For more information, see Update custom object records in bulk.

Delete custom object records

To delete a custom object record, perform the following steps:

  1. Click the Delete icon Delete.png to the right of a record from the record list view.
  2. Click Delete in the confirmation dialog.

To delete the selected records of a custom object, perform the following steps:

  1. Select the records that you want to delete from the record list view.
  2. Click the Delete Selected icon Delete.png at the upper right of the list.
  3. Click Delete in the confirmation dialog.

To delete all the records of a custom object, perform the following steps:

  1. Click the Delete All icon Delete All.png at the upper right of the record list view.
  2. Click Delete in the confirmation dialog.

Note that the records are deleted immediately and, therefore, will not be retained once you confirm the deletion.

You can use the Custom Object Jobs API operations to delete custom object records in bulk. For more information, see Custom object jobs.

Create custom object records in bulk

You can create custom object records in bulk by uploading a .csv file that includes the field values of each record. The column names of the .csv file must align with the custom fields’ API name. For example, brand__c and model__c. Each row in the file represents a new custom object record.

To upload a .csv file and create custom object records in bulk, perform the following steps:

  1. Click the Import icon Import.png at the upper right of the record list view.
  2. From the Action to Perform list, select Bulk Import.
  3. Click Choose File, and then select the .csv file you want to upload.
  4. Click Upload.

Zuora creates a bulk job when receiving an uploaded .csv file. After the bulk job processing is finished, you can find the newly created records by reloading the record list view page. The processing time varies depending on the data volume. For more information about how to view bulk job status in your tenant, see View custom object bulk jobs.

Alternatively, you can also create custom object records in bulk through API. For more information, see Submit a custom object bulk job.

Update custom object records in bulk

You can update custom object records in bulk by uploading a .csv file that includes the field values of each record. The column names of the .csv file must align with the custom fields’ API name. For example, brand__c and model__c. Each row in the file represents a custom object record to be updated. The .csv file for updating must contain a column named Id, linking each row in the file to an existing custom object record.

To upload a .csv file and update custom object records in bulk, perform the following steps:

  1. Click the Import icon Import.png at the upper right of the record list view.
  2. From the Action to Perform list, select Bulk Update.
  3. Click Choose File, and then select the .csv file you want to upload.
  4. Click Upload.

Zuora creates a bulk job when receiving an uploaded .csv file. After the bulk job processing is finished, you can find the updated records by reloading the record list view page. The processing time varies depending on the data volume. For more information about how to view bulk job status in your tenant, see View custom object bulk jobs.

Alternatively, you can also update custom object records in bulk through API. For more information, see Submit a custom object bulk job.

Query custom object records

You can query custom object records by the following ways:

  • Make a Query custom object records call. This is a high-performance query and only filterable fields can be used as filters in this query. See Query syntax of custom object records for details.
  • Use Data Query. This is an asynchronous query and any field can be used in the WHERE clause to filter results. See SQL Queries in Data Query for details.

    Note that it may take up to 60 minutes for a newly created custom object to be available in Data Query.

    To query custom objects in Data Query, the custom object name needs to be prefixed with default__ and custom field API names should be used in the SELECT statement. For example:

    SELECT make__c, model__c, year__c, VIN__c 
    FROM default__Vehicle

View custom object bulk jobs

A custom object bulk job represents a task for managing, such as creating, updating, or deleting, a batch of custom object records of a custom object definition.
To view custom object bulk jobs, perform the following steps:

  1. Navigate to Platform > Object Manager in the left navigation section.
  2. Click Jobs. All custom object bulk jobs are presented in the table.

You can use the Custom Object Jobs API operations to find more details of bulk jobs, such as operation type, processing time, or error messages. For more information, see Custom object jobs.

Notes and limitations

When managing custom object fields, keep the following notes and limitations in mind:

  • The maximum size of .csv files is 15 MB.
  • The uploaded .csv file cannot contain system fields such as CreatedDate, UpdatedDate, and others.
  • The Id system field applies only to the .csv file for updating custom object records in bulk.
  • When creating or updating custom object records in bulk, Zuora uses the value in columns in the .csv file for corresponding custom fields, and uses the default value for fields that are not present in the file.
    For example, assume that a custom object record contains the following custom fields:
    Field name Field API name Default field value Field value in this record
    Sold sold__c False False
    Color color__c White Red
    When updating this record via a .csv file that contains only the Id and sold__c columns, the Color will be set to White instead of Red because the color__c field is not provided in the file.
  • When creating or updating custom object records in bulk, if the .csv file contains records with duplicated values for a unique-type field, Zuora will accept the first record by sequential order in the file, and reject other records with duplicated values. Other records that do not have duplicated values in the same file will be accepted as usual.
    You can find all rejected records of a particular bulk job for creation through the List all errors for a custom object bulk job API operation.
    The following is an example of a .csv file for creating records:
    Row number Unique_text_field__c The_other_boolean_field__c
    2 region001 true
    3 region002 true
    4 region003 false
    5 region002 false
    6 region004 true
    By receiving this file, Zuora will create four records for rows 2, 3, 4, and 6. Row 5 will be rejected because it has a duplicated value (region002) for the unique field (Unique_text_field__c) and is after row 3, which shares the same value for this field.

Events for custom object records

Zuora provides the following events that focus on the usage of custom object records:

  • Custom Object Records High Usage
  • Custom Object Records Max Usage

These events are evaluated on a daily basis. If the number of custom object records of a specific custom object definition exceeds the pre-defined limit value, Zuora will trigger notifications related to these events. For more information about event details and limit values, see Standard events for Zuora Central Platform.

Manage custom object records in Workflow

Zuora Workflow provides the following tasks for you to create, query, update, or delete custom object records: