meta data for this page

Building Collections

Overview

A Collection is a configurable data layer — part database table, part workflow engine. This guide walks through designing and deploying a custom collection.

Design Process

  1. Define the data model — what fields does each record need?
  2. Define the actions — what lifecycle states can a record move through?
  3. Define the views — who sees which records, and with which fields?
  4. Enable API — which views should external callers read/write?

Field Types

Type Stored as Notes
text VARCHAR Single-line text
textarea TEXT Multi-line text
select VARCHAR One option from a list
boolean VARCHAR True / False
yesno VARCHAR Yes / No
number VARCHAR Numeric — stored as text; compare as string
date VARCHAR Store as YYYY-MM-DD for reliable sorting
url VARCHAR URL with launch button
email VARCHAR Email address
multiselect VARCHAR Comma-separated values; query with FIND_IN_SET
currency VARCHAR Monetary amount
rating VARCHAR Button-group rating; supply option labels
color VARCHAR 6-digit hex (#rrggbb)
lookup VARCHAR Reference to another entity (ID or ref)

All field values are stored as text/VARCHAR regardless of type — type validation happens at the API layer.

Creating via API

# 1. Create the collection (admin credentials required, no r/g params)
POST /api/apic.php
  u=admin&k=adminkey&f=createcollection
  collection_name=My+Tracker&collection_ref=MyTracker123

# 2. Add fields
POST /api/apic.php
  u=admin&k=adminkey&r=MyTracker123&g={admin_view_id}&f=addfield
  fxLabel=Title&fxType=text

POST /api/apic.php
  ...&f=addfield&fxLabel=Status&fxType=select
  fxOptions=New,In+Progress,Closed

Views (GX Groups)

Views are the API's security gate. Every API call must go through a view. Views control:

  • Which records are visible (SQL WHERE clause)
  • Which fields are returned
  • Whether the view is read-only or read/write
  • Which action is used for write operations

Configure views in the collection admin UI, or use the applytemplate API function for standard schemas.

Row-Level Security

Enable per-owner record visibility with f=enablerls, then f=setrls&rlsMode=Owner on the relevant view. Users can only see records they own. Admins bypass RLS.

Swim Lanes

Convert a flat record list to Kanban-style lanes with f=enableswimlanes. Create lanes with f=createitemgroup, then move records with f=movetogroup.

Best Practices

  • Call f=meta first whenever working with an unfamiliar collection
  • Use dedicated views for each integration — don't share views between callers
  • Keep GX SQL queries indexed for performance
  • Use bulkcreate for batch inserts — it's far faster than looping create