Manage custom fields

When should I manage custom fields with the Object Manager

This article introduces how to manage custom fields without the Object Manager. However, when managing custom fields for the following objects, it is highly recommended to use the Object Manager. For more information, see Manage custom fields with the Object Manager.

• Account
• Credit Memo
• Debit Memo
• Invoice
• Payment
• Product
• Product Rate Plan
• Product Rate Plan Charge
• Refund
• Subscription
• Subscription Rate Plan
• Subscription Rate Plan Charge
• Usage

The following table describes the differences between managing custom fields with or without the Object Manager:

View custom fields

To view the custom fields that are defined for a business object, perform the following steps:

1. • If the object is related to accounts, subscriptions, invoices, or products, click your username at the top right and navigate to Settings > Billing.
   • If the object is related to payments or refunds, click your username at the top right and navigate to Settings > Payments.
   • If the object is related to accounting or revenue, click your username at the top right and navigate to Settings > Finance.

2. Click Manage Custom Fields.

   Zuora lists the objects that support custom fields. For each object, Zuora displays the number of custom fields that have been defined.

3. Select the object.

   "Invoice Detail" refers to the Invoice Item object.

Zuora lists the custom fields that have been defined for the object. The custom fields are listed in the following groups:

• Indexed - Indexed custom fields have better performance than non-indexed custom fields. For example, if you are querying custom fields using synchronous API requests, you can expect the best performance if all of the custom fields are indexed.
• Non-Indexed - Non-indexed custom fields are functionally identical to indexed fields, but have lower performance.

If your Zuora tenant has integrations with external systems, you may see integration-related custom fields in the System group.

If you have the Multi-entity feature enabled, Zuora displays the sharing status of each custom field. If a custom field is defined in the global entity and has been shared with your entity, the value in the Shared column is "Yes" followed by the name of the parent entity. You cannot modify or delete a custom field that has been shared from the global entity.

See the "Share Custom Fields With Sub-entities" section for information about sharing custom fields defined in your entity.

Create custom fields

To define a custom field for a business object, perform the following steps:

1. View the existing custom fields for the object. See the "View Custom Fields" section for more information.

2. In the Indexed or Non-Indexed group, click Add New Field.

3. Select a field type, then enter the field definition.

   For example:

   

   You must make sure every Picklist value is unique when you fill in Picklist Values. The picklist value is case-insensitive. For example, "Business" and "BUSINESS" are treated as the same value and cannot both be added. There is no limit on the number of values for a picklist-type field.

   If you select Required, Zuora will require users to specify a value for the field when creating an object. If you select UI Read Only, users will be able to update the field's value via the Zuora API but not via the Zuora UI. 

   The suffix __c (two underscores and the letter "c") is automatically appended to the end of the API name when Zuora creates the custom field.

4. Click Save.

Zuora creates the custom field. The custom field will then appear in the Zuora UI. For example:

This means that if you define a custom field, then immediately perform a ZOQL query such as select BetaTester__c from Account, the query will not return any values for BetaTester__c.

To apply the default value to an existing object, you must modify the object via the Zuora UI or the Zuora API.

Modify custom fields

To modify the definition of a custom field, perform the following steps:

1. In the list of custom fields for an object, click the label or API name of the field. The custom field detail page opens. 

2. Click Edit.

3. Modify the field definition.

   You cannot change the field type. 

   If the field type is Picklist, you can remove picklist values for custom fields if these values meet all of the following conditions:
   • They are not used anywhere in your application. If an object record uses a picklist value and this record is deleted later, the picklist value cannot be removed. Deleted object records can be exported through AQuA or Data Query.
   • They are not default values of the custom fields.
   • They are not shared with other entities if you have the Multi-entity feature enabled.

   In addition, you can disable picklist values for custom fields through the Zuora UI if picklist values meet both conditions. After picklist values are disabled, you cannot use them to create or update objects through the Zuora UI.

   • They are saved in the system.
   • They are not default values of the custom fields.

   If Multiple-entity is enabled for your tenant, you can disable picklist values of shared custom fields in the parent entity, and your update will be synchronized to all child entities.

4. Click save.

If you modify or delete a custom field, you must update any integrations that access the field. For example:

• If you change the label of a field, the API name of the field will also change. Any integration that continues to use the old API name will receive an error. You must update integrations to use the new API name.
• If you decrease the length of a field, any integration that sends data that exceeds the new field length will receive an "Invalid_value" error. You must check the maximum length of data that integrations could send.

Delete custom fields

To delete the definition of a custom field, perform the following steps:

1. Click Remove to the right of a custom field from the list view.
2. In the confirmation dialog, click Yes.
   Note that you cannot edit the custom field while deletion is in progress. The label and API name of the custom field are displayed in gray during the deletion. The deletion time varies based on the data volume of this field in your Zuora tenant. For example, deleting a custom field with 10 million records might take more than two hours.

When the deletion is completed, this custom field will be removed from the list after reloading the page.

Share custom fields with sub-entities

If you have the Multi-entity feature enabled, you can share your global entity's custom fields with all sub-entities. By default, custom fields that you define in your global entity are not shared with any other entities.

After you share a custom field with sub-entities, each sub-entity has access to a custom field with the same definition (label, type, etc) as the global custom field. Values of the custom field are not copied between entities.

To share a custom field with all sub-entities of your global entity:

1. Use the entity switcher to switch to your global entity.

2. View the custom fields for the object that has the custom field. See the View Custom Fields section for more information.

3. Locate the custom field to share, then click Share.

4. In the dialog box that appears, click Yes.

The sharing status of the custom field changes to "Yes" after Zuora has shared the custom field with all sub-entities of your global entity.

You cannot delete a custom field while it is shared with sub-entities.

Enable custom fields in Connect Tax Engines

See the step 5 in Set up Connect Tax Engines.

Notes and limitations

• The Required option is not available when defining custom fields for the following objects:
  • Amendments
  • Subscription Rate Plans
• For the Usage object, do not create a custom field with the same name as a standard Zuora field. This avoids ambiguity when importing usage files.
• The Integer and Number field types apply only to non-indexed custom fields.
• The built-in minimum and maximum values for custom fields with the Integer or Number field type are as follows:

  	Integer	Number
  Minimum value	-2^63	-9999999999999.99
  Maximum value	(2^63)-1	9999999999999.99