Custom Objects

Custom Objects let workspace admins connect external data catalogs — HR systems, tenant lists, CMDB tables, REST APIs — and use them as reference fields in ticket forms. Agents and employees pick values from a searchable list instead of typing free text.

Plan: Enterprise only (integrations.external_objects). Basic and Pro workspaces see an upgrade prompt in Studio.

Where to find it

Studio → Custom Objects (/admin/studio/external-objects)

Three tabs:

Tab	Purpose
Data sources	REST API or PostgreSQL connectors (credentials, cache interval, test connection)
Object types	A catalog definition: query, ID template, display template, sync/cache
Connected fields	Custom fields of type Object linked to an object type (active/inactive)

How it works (overview)

Data source (REST / PostgreSQL)
        ↓
Object type (query + templates + cache)
        ↓
Synced records in workspace cache (object_records)
        ↓
Custom field (Object) on ticket form → picker in create/edit/detail

Create a data source — e.g. REST endpoint with API key, or read-only PostgreSQL (SSL optional per host).
Create an object type — name, description, then Configure to attach the data source, build the query, and set templates.
Test the query — preview sample rows (5/10/20/50), drag columns into ID and Display templates.
Sync — records are cached in the workspace for the configured duration (3 / 6 / 12 / 24 hours).
Link a custom field — Studio → Custom Fields → type Object → pick the object type and single/multi selection.
Use in tickets — employees and agents search the picker; stored value is { externalId, displayLabel } (denormalized for fast display).

Data sources

REST API

GET request with optional headers (API key, Bearer token).
Response must be JSON (array or object with a records array).
Map JSON paths in the object type query step.

PostgreSQL (read-only)

SELECT-only queries for security.
Show tables helps pick schema/table on the configure page.
SSL is opt-in — enable only when the host requires it (e.g. Supabase, Neon). Some public databases (e.g. EBI RNAcentral) do not use SSL.

Cache duration

Set per data source or per object type (3h, 6h, 12h, 24h). While cache is valid, ticket pickers use cached records even if the external source is temporarily unavailable.

Object type configuration

On Configure for an object type:

Step	What you set
General	Name, description, cache duration
Query	SQL or REST mapping, filters, column selection
Templates	ID template — stable key per record; Display template — label shown in tickets (e.g. `{name} ({code})`)
Preview	Run query, inspect sample rows, verify templates

Changing the ID template

If tickets already store values and you change the ID template, Studio warns you and offers:

Remap — update ticket values where a match exists in the new cache
Clear — remove values that cannot be remapped (useful for required fields when you accept data loss)

Ticket forms & runtime

Object fields appear as a searchable picker (single or multi).
Connected fields tab can deactivate a link without deleting the custom field definition.
Values are validated server-side: externalId must exist for the workspace object type (or match a stored snapshot during cache gaps).
Employee view and agent view both respect field visibility rules.

Resilience & cache behavior

Situation	Behavior
Sync succeeds	Picker shows current cached records
Source down, cache valid	Picker keeps working from cache
Source down, cache expired	Existing ticket values remain; picker may not find new records until sync succeeds
Empty sync / API error	Cache is not wiped — protects multi-day outages

Flaky upstreams (slow scripts, cold starts, occasional timeouts — e.g. Google Apps Script): FlowMingo retries transient REST failures, uses a longer per-attempt sync timeout (60s), and only alerts workspace admins after repeated sync failures (not a single blip). End users continue to see the last good cache whenever possible.

Security notes

Connectors and object types are workspace-scoped; mutations require Studio manager access.
Connector secrets are not exposed in the browser after save.
PostgreSQL connectors are restricted to SELECT statements.

Production hardening is done (#226 B1–B7): secrets are redacted from API responses, object_connectors RLS is locked down, REST/DB SSRF allowlists block private hosts, PostgreSQL stays SELECT-only, and connector probes / member search are rate-limited. Follow-up (secrets at rest, audit log): #264.

Tickets — custom fields on forms
Team & roles — Studio access and Enterprise features
Public REST API — separate integration surface for ticket CRUD

Internal engineering notes: docs/18-external-objects-phase1.md in the application repository.