Extend system object types

Xperience allows you to customize the data structure of certain system objects by modeling additional database columns to store custom data. This can typically be useful if you wish to gather data not collected by a particular out-of-the-box implementation or to add additional properties for the purposes of custom third-party integrations. 

Follow these steps to extend a system object:

1. Open the Modules application and select a system module.
2. Select the Classes tab and select one of the available classes.
3. Switch to the Database columns tab and add required custom fields using the field editor.

You have adjusted the object’s database structure. The added columns respect the configuration of the extended object type. For example, the columns are automatically included in serialized data if the object supports CI/CD. However, the system does not automatically include the columns into editing forms in the administration. To enable administration users to work with the columns, you need to adjust the object’s UI forms. 

For more advanced customization scenarios, you can also build a completely custom user interface capable of fully reflecting your requirements. You can find inspiration on the Example – Offices management application page that guides you through the process of creating and registering an entirely new object in the system and building a corresponding management application in the admin UI. 

Moreover, to learn how to work with the added columns using the API, see Access added columns via the API.

Extend an object’s editing interface

To make the added columns editable via the administration, you must also adjust the object’s UI forms. UI forms are system objects connected to individual classes. They store information describing editing forms for the object, such as the input data type of form fields and assigned UI form components. Administration edit pages then render an editing form based on the provided UI forms.  

Objects can have multiple UI forms, each shown in a different context as required. Creating new objects of a particular type can show a different set of form fields than the edit action, depending on user requirements. However, some extendable objects don’t have any UI forms defined – their editing interface is made to fit a specific application. A typical example are Media files (Media libraries module) that are managed using an image gallery within the Media libraries application. In such cases, it isn’t possible to provide editing options for the added columns without a custom UI form displayed by a custom interface. See the Customizable data classes section for the limitations of each extendable object.

To edit an object’s UI form:

1. Select a system object you extended and switch to the UI forms tab.
2. Select a UI form to edit or create a new one.
   • The two most common UI forms are Create and Edit. They are used either when creating a new object or editing an existing one.
3. Select New field. The Database column selector opens.
   • Use the selector to choose the added column. Data submitted via the created form field is persisted in the selected column.
4. Add the new columns to the form using the field editor.
   • If you are creating a new UI form for the object, pay attention to existing columns marked as Required. If not added to a form, these columns get set to their Default value as configured on the Database columns tab.

The added columns now show in the modified UI form and are editable by administration users. 

Access added columns via the API

To access the columns on the extended object via the API, use the GetValue and SetValue methods of the given Info class:

// Gets the value from the specified column as 'object'
// You can use 'IConversionService' to convert the value to the desired type or use a custom conversion API
var columnValue = userInfoObject.GetValue("ColumnName");

// Sets the column value to the object
userInfoObject.SetValue("ColumnName", "value");

Customizable data classes

This section lists customizable classes together with additional information or limitations.