====== 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 =====

  - **Define the data model** — what fields does each record need?
  - **Define the actions** — what lifecycle states can a record move through?
  - **Define the views** — who sees which records, and with which fields?
  - **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 =====

<code>
# 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
</code>

===== 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''