Custom object definitions
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 definitions through UI. Once a custom object definition is created, you can create custom object records of this type. See Custom object records for more information.
If you want to access custom object definitions by API, see Custom Object Definitions in Zuora API Reference.
View custom object definitions
To view custom object definitions, perform the following steps:
- Navigate to Platform > Object Manager..
- Click the object name in the Label column. The custom object records page opens.
- Click Edit Object Definition. The custom object detail page opens.
Create a new custom object definition
To create a new custom object definition, perform the following steps:
- Navigate to Platform > Object Manager, and then click + Create in the upper right of the page.
- Fill in the information on the new custom object page.
- The Name field is required.
- The API Name field is required.
- Switch the following toggles on or off to indicate whether to audit the creation or deletion of custom object records of this custom object definition:
- Audit Create Record
- Audit Delete Record
- Click + New Custom Field.
- You must create at least one custom field for a new custom object.
- You can add at most 50 custom fields to a custom object.
- All custom fields in a custom object can be indexed.
- Input the information of the custom field on the Add New Custom Field page.
- Field Name: The custom field name displayed on UI. The field name is required.
- API Name: The API name of the custom field. The API name must end with
__c
and cannot be edited once created. The API name is required. - Description: The description of the custom field.
- Field Type: Select a field type for the new custom field. See the following possible values of the field type. The field type cannot be changed once the custom field is created.
- Text: You can define the default value for a text type custom field. To further confine the data value format of this field, select a data format checkbox (URL or UUID) as needed. URL-formatted text fields are not filterable.
If you want to use this field as the display name for the current custom object, select the Display Name checkbox. For more information, see Create the display name for custom objects. - Integer: You can define the default value for an integer type custom field.
- Number: You can define the default value for a number type custom field. Zuora supports up to 13 digits to the left of the decimal point, and up to 9 digits to the right.
- Boolean: You can select the default value for a boolean type custom field.
- Date: You can define the default value for a date type custom field.
- Date and Time: You must enter the values for both date and time if you want to define the default value for a date and time type custom field.
- Picklist: You must add at least one option for a picklist type field. You must make sure every picklist value is unique when you fill in picklist values. The picklist value is case-sensitive. For example, "Business" and "BUSINESS" are treated as different values and can be added together. You can set a default value for a picklist type custom field.
- Multiselect: You can select one or more options for a multiselect-type field. As a comparison, you can select only one option for a picklist-type field.
You must add at least one option for a multiselect-type field. You must make sure every option value is unique when you fill in option values. The option value is case-sensitive. For example, "Business" and "BUSINESS" are treated as different values and can be added together. You can set a default value for a multiselect-type custom field. The multiselect-type fields are not filterable. - Relationship:
- You must select the Namespace for a relationship type field. The com_zuora namespace houses Zuora objects and the default namespace houses the custom objects.
- You must select the Object Name of the object that this custom field is related to.
- Each custom object can contain at most 2 relationship type custom fields.
- The relationship between a custom object and its related object is many-to-one. For example, a custom object of Vehicles could have many records that are related to one Subscription.
- Relationships can be established with Zuora objects or other custom objects.
- The relationship field usually stores the related object's UUID only except for Subscription Name and Rate Plan Charge Number as both of them are unique.
- You can only add relationship type fields to a new custom object or an existing custom object with no records.
- Text: You can define the default value for a text type custom field. To further confine the data value format of this field, select a data format checkbox (URL or UUID) as needed. URL-formatted text fields are not filterable.
- Required: Switch the Required toggle on or off to indicate whether the custom field is required. You can change a required field to optional. However, you can only change an optional field to required on the custom object with no record.
- Filterable: Switch the Filterable toggle on or off to indicate whether the custom field is filterable. Only filterable fields can be used as filters in the high-performance queries submitted through the Query custom object records API. However, any field can be used as a filter when using Data Query. You can change the Filterable value through Update custom object definition API after the field is created.
Limitations:
- One custom object can have a maximum of 10 filterable fields.
- The maximum length of each filterable text field must be 512 or less.
- Unique: Switch the Unique toggle on or off to indicate whether the values in the custom field are unique. You can remove the unique constraint on a custom field. However, you can only add the unique constraint to a custom field if the custom object contains no record.
Limitations:
- One custom object can have a maximum of five fields with unique constraints.
- The unique constraints apply only to filterable fields.
- Auditable: Switch the Auditable toggle on or off to indicate whether Audit Trail will record changes of this custom field. The changes include the creation, update, and deletion.
One custom object can have a maximum of five auditable fields.
Note that you must enable the Custom Object Definition audit trail setting in your Zuora tenant before auditing custom field changes. For more information, see Manage audit trail settings.
- Click the Save and Add Another to save the custom field definition and immediately start creating a new custom field. Repeat until you input the information for the last new custom field. Click Save and Close to save the custom field definition and return to the new custom object page.
- Click Save on the new custom object page.
The new custom object definition will be displayed in the custom object list view.
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.
Update a custom object definition
You can make the following updates to an existing custom object definition:
- Edit existing custom field definitions
- Add new custom field definitions
- Delete existing custom field definitions
To edit an existing custom field in the custom object definition, click the Edit icon to the right of a custom field on the custom object detail page. You can make the following updates to an existing custom field definition:
- Update the default value.
- Change a required field to optional.
- Change an optional field to required if the custom object contains no record.
- Change a filterable field to non-filterable, and vice versa.
- Remove the unique constraint on the field.
- Add a unique constraint to a filterable field if the custom object contains no record.
To add a new custom field definition to a custom object definition, perform the following steps:
- Click + New Custom Field on the custom object detail page.
- A custom object can contain at least 1 and at most 50 custom fields
- All custom fields in a custom object are indexed.
- Input the information of the custom field on the Custom Field page. The Name and API Name are required.
- Click Save and Close to save the new field.
Note that you can only add a required field, a relationship type field, or a unique constraint to an existing custom object with no records.
To delete an existing custom field definition from a custom object definition:
- Click the Delete icon
on the right side of the field on the custom object detail page.
- Click Delete on the confirmation dialog.
Note that you can only delete field definitions for custom object definitions that contain no records.
Delete a custom object definition
To delete a custom object definition, perform the following steps:
- Click the Delete icon
on the right of the custom object in the custom object list view.
- Click Delete in the confirmation dialog.
Note that you can only delete the custom object definitions that contain no custom object records. See Custom object records for more information.
View custom objects usage
You can view how many custom objects have been created towards the limit in your tenant by hovering over the Custom Objects Usage meter in the Custom Objects list view.
Import and export custom objects
You can import custom object definitions in bulk, and export existing definitions for later use.
Import custom objects
To import custom objects, perform the following steps:
- Click the Import icon
at the upper right of the Custom Object list view. The Import Definitions window pops up.
- Paste the JSON format object definitions to the text editor. See the request schema of the Create custom object definitions API for the required JSON structure. You can find a JSON example in the JSON example for import section of this article.
- Click Import.
JSON example for import
The following is a JSON example for import with one custom object definition named Vehicle
:
{ "Vehicle": { "type": "Vehicle", "schema": { "object": "Vehicle", "label": "Vehicle", "title": "Vehicle", "type": "object", "description": "Object stores vehicle information", "enableCreateRecordAuditing": false, "enableDeleteRecordAuditing": false, "properties": { "brand__c": { "maxLength": 512, "description": "The brand of the vehicle", "label": "Brand", "type": "string" }, "model__c": { "maxLength": 512, "description": "The model of the vehicle ", "label": "Model", "type": "string" }, "color__c": { "maxLength": 512, "description": "The color of the vehicle", "label": "Color", "type": "string", "enum": [ "white", "red", "black", "silver", "blue" ], "default": "white" }, "MSRP__c": { "description": "The MSRP of the vehicle", "label": "MSRP", "type": "number" } }, "required": [ "brand__c", "model__c" ], "filterable": [ "brand__c", "model__c" ], "enableRecordMigration": false } } }
Export custom objects
To export custom objects, perform the following steps:
- Select the custom objects that you want to export in the Custom Object list view.
- If you want to export the selected custom object definitions to a JSON file, click the Export to Json icon
. If you want to copy the definitions to the clipboard, click the Copy to Clipboard icon
.
You can then import these selected custom object definitions to another tenant with the exported JSON file or from the clipboard.
Use cases
Create the display name for custom objects
The display name can be used as a user-friendly name for a custom object linked to other custom objects.
For example, suppose that you have created two custom object definitions named "Vehicle" and "Tire Manufacturer" in your tenant. The Vehicle object contains a relationship-type field Tire
linking to the Tire Manufacturer object. You can enable the display name for the Tire Manufacturer object by creating a text-type field Manufacturer Name
. When creating custom object records for the Vehicle object, real manufacturer names can be recorded as values for the Tire
field, instead of meaningless 36-character record IDs.
To create the display name, complete the following steps when creating or editing a custom object definition:
- Create a text-type custom field definition.
- Ensure none of the format checkboxes (UUID or URL) is selected.
- Select the Display Name checkbox.
Display names have the following limitations:
- Each custom object definition can have at most one field as the display name.
- Only text-type fields with no format (such as UUID or URL) can be used as display names.