Custom Objects

Overview

gaiia ships with a set of standard objects covering the building blocks of an internet or communications service business — Accounts, Inventory Items, Tickets, Network Sites, Addresses, Properties, and more. Custom Objects let you define your own object types alongside those, for the parts of your business that don't fit a standard object out of the box.

This article covers what custom objects are, when to use one, how the data is shaped, and how to build, manage, and integrate them in your tenant.

What custom objects are

A standard object is a data type gaiia provides for everyone. An Account is the same shape in every tenant; an Inventory Item is the same shape in every tenant. They have a fixed schema gaiia maintains, and you can extend them with custom fields, but you cannot define new objects.

A custom object is a data type you define, scoped to your tenant. You name it, give it fields, and start creating records. Once defined, custom object records behave like the rest of the platform — they show up in lists, are searchable, are reportable, fire workflow events, and are available via the gaiia API.

Example — Carrier: most CSPs that resell voice work with one or more upstream carriers. Each carrier has a name, a country, a default per-minute rate, a portability flag, and a list of supported service types. Because many customers don't need carriers, there's no standard "Carrier" object in gaiia — making it a great candidate for a custom object.

When to use a custom object

A custom object is the right tool when all of the following are true:

• The concept doesn't already fit one of gaiia's standard objects.
• You'll have multiple records of this concept (not a single value).
• The data needs to be reported on, referenced from elsewhere, or managed as its own dataset.

If the data is a single piece of metadata about something gaiia already models, use a custom field on the relevant standard object instead. Likewise, avoid custom objects for short-lived or throwaway data, workflow configuration, or anything that doesn't need to persist as a queryable record. Once a custom object has records, you've made a commitment to its shape — schema changes propagate to every existing record.

Key concepts

A custom object has four building blocks:

• Object Definition — the shape: name, plural name, API name, icon, description, and the list of fields it contains. Defining an object doesn't create data; it creates the type.
• Field — one characteristic of the object. Fields have a type, and can be marked required or unique. Exactly one field per object is the primary display field: the value shown when a record is referenced anywhere else in gaiia.
• Reference field — a special field whose value is a pointer to another record, either a standard object record or another custom object record.
• Record — a single entry of the object. If the object is "Carrier," a record is "Acme Telecom" or "Bell Voice."

Field types

Custom objects support the following field types:

A reasonable starting set of fields for the Carrier example:

• Name — Text, required, unique, primary display.
• Country — Dropdown.
• Default per-minute rate — Number.
• Supports porting — Toggle.
• Supported service types — Multi select, with options Voice, SMS, Data.
• Account manager — Single reference to a User record.
• Notes — Text.

Reference fields

A reference field stores a pointer to another record. The pointer can target a standard object record or a custom object record. From the holding record's view, it's just another field — the value happens to be "this User record" or "this Carrier record" instead of a plain string.

References can be single (one target record) or multi (zero or more target records). Reference fields on a custom object can target any of gaiia's standard objects, as well as other custom objects (custom-to-custom references).

Example: add an "Account manager" field to the Carrier object pointing at a User record. Every Carrier record then knows who owns the relationship with that carrier, and reporting can group carriers by account manager without re-typing the user's name on every record.

Building a custom object

Custom objects are managed in Admin Settings → Objects. This page lists both standard and custom objects, labeled as such. All custom fields for any object are also managed here.

A. Defining the object

When you create a new custom object, you set:

1. Name — singular form, e.g. "Carrier."
2. Plural name — used wherever a list of records is shown, e.g. "Carriers."
3. Icon — a visual identifier shown in nav and list views.
4. Primary Field name — the unique identifier of your object, and its first column.
5. Primary Field type — the field type for the unique identifier.

B. Adding fields

After the object exists, add fields one at a time. For each field you set:

1. Name — what shows on the form and in the table view.
2. Type — one of the types listed above.
3. Required — whether a value must be supplied when a record is created.
4. Unique — whether the value must be unique across all records of this object.
5. Primary display — exactly one field per object is the primary display; that value is shown when a record is referenced from elsewhere in gaiia.

For Single reference and Multi reference fields, you also pick the target object — any standard object or any of your custom objects.

Input form customization

When creating an object and editing its settings, you can preview the input form users see when adding a new record. Select the Actions dropdown on the Object settings page and choose Preview creation form.

To customize the layout, select Configure form layout from the Actions dropdown. This opens an editor where fields can be grouped into sections and reordered. The editor supports drag-and-drop section assignment and field reordering, so the form can be restructured to suit your needs.

Once editing is complete, use the Preview option to review how the form will appear to users before publishing the changes.

Forms on tickets

The input form customization for custom objects can be used to create custom forms on tickets. See the Forms on Tickets article for details on how this can be leveraged in the Tickets module in gaiia.

Working with records

Once an object is defined, you can create records. Records appear in a table-style list view named with the object's plural name.

Creating, editing, and archiving

Click the + New [Object] button to open the new record form. The form is generated from the object's field definitions and section layout. Every required field must have a value before the record can be saved.

Edit a record by opening it from the table view. Edits respect the object's permission model — if you don't have edit permission on records, the form is read-only.

Archive a record (and unarchive it later) using the record's Ellipsis menu. Archived records are hidden from the default list view but remain in the data model — they're recoverable and still referenceable by ID for historical record-keeping.

Searching

The record table view supports keyword search across the record's primary display field and other text-bearing fields.

Drafts

Custom object records support drafts — useful when records have many required fields, data is gathered over multiple sessions, or long-form data can't reasonably be completed in a single interaction. A draft is an in-progress version of a record that doesn't appear in the main table view, isn't included in reports, and doesn't fire workflow events until it's published.

Select Save as draft when creating any record to save it as a draft. Required field validation is not enforced on drafts, so there are no minimum field requirements to save.

To find existing drafts, select the Drafts option near the Archive button when viewing an object's records page.

A draft can be edited, deleted, or published. Selecting Create on a draft turns it into a normal record — it appears in the table view, becomes reportable, and triggers any workflows set up on creation events.

Locking records

Records can be locked to prevent edits — useful when a record represents a state that shouldn't be modified, or when an integration is synchronizing data and you don't want a human writing over it.

Records can be locked individually, or an entire object can be configured so all new entries are read-only by default. The object-level setting is useful for time-series data, logs, or audit tables that must not be modified after creation.

• To lock a single record, open the record's Ellipsis menu and select the lock action.
   

  

• To set all new records of an object to read-only, open the Ellipsis menu on the object in Object Settings and select Set read-only.

Users without lock/unlock permission will receive a blocking notice if they attempt to edit a locked record and will be prevented from making changes. Users with lock/unlock permission will see a reminder that they're interacting with a locked record, but can proceed with editing.

Lock/unlock permissions are found under Roles → Role permissions → Custom objects → Records → Lock/Unlock.

CSV import and export

Every custom object supports CSV import and export — useful for bulk-loading initial data, syncing from a spreadsheet, or exporting for external analysis.

Exporting

Export from the object's table view. The export contains every record, with one row per record and one column per field.

Reference-type fields are exported with their unique gaiia ID. If you need the IDs of another object for matching references in an import, export that object's table first.

Importing

Imports support both creating new records and updating existing ones.

1. Download the CSV template for the object. gaiia generates one with the correct column headers. Alternatively, if you already have records, export and then edit that CSV to ensure formatting continuity.
2. Fill in the rows you need changed. The import performs an "upsert" — it updates existing rows and adds new ones that don't yet exist, as long as the required fields are filled in.
3. Browse for or drag CSV files into the import flow using Add File.
4. Correct any flagged errors and delete any unneeded rows.
5. Click Confirm Import once all issues are resolved.

You can track the status of each import job — created, updated, and failed counts surface as the job runs.

Permissions

Custom Object permissions are off by default for all roles. They must be turned on manually for any role that needs to interact with custom objects.

Custom objects have two layers of role permissions.

Settings-level permissions

Two permissions control configuration of custom objects in Settings:

• admin.customFields.customObjects.view — see the Custom Objects page and existing object and field definitions on it.
• admin.customFields.customObjects.edit — create, modify, reorder, archive, and unarchive custom object definitions, fields, and field sections.

Records-level permissions

Three permissions cover the data inside custom objects, applying across all custom objects in your tenant:

• customObjects.records.view — read access to records, including via search and CSV export.
• customObjects.records.edit — create, modify, archive, unarchive, and import records (including drafts).
• customObjects.records.lock — toggle the lock state on records.

Both layers slot into your tenant's existing role system. Assign permissions on roles, and assign roles to users.

Where custom objects fit in the rest of gaiia

Custom objects are first-class data in your tenant. They flow into the same systems as your standard object data.

Reporting

Custom object records replicate to Snowflake alongside your other gaiia data, in the GAIIA_DATABASE.CUSTOM_OBJECT schema:

Building a report on a single custom object means joining records to their field values and filtering by the relevant object definition.

Workflows

Custom objects participate in gaiia workflows in two ways.

Triggers — workflow events fire when:

• A custom object definition is created, updated, or archived.
• A field on a definition is created, updated, or archived.
• A record of a definition is created, updated, or archived.

Actions — workflow nodes can:

• Create, update, read, or archive a record of a custom object.

Public API

Every custom object operation available in the UI is also available via the gaiia public API. Definitions and records are addressed by your object's API name:

• Custom object definitions — list, get, create, update, archive, unarchive.
• Fields — list, get, create, update, archive, unarchive.
• Records — list, get, create, update, archive, unarchive.

Use the API for integrations with external systems, server-side bulk operations, or anything beyond the table-view UI and import/export controls.