WhipIT orientation pack · generated from markdown

WhipIT — API handover (read only / development)

For: Simon (WhipLash Developer)

From: Sam McCormick (previous WhipIT developer)

Date: June 2026

1. Context (brief)

WhipIT is a large, long-lived FileMaker solution (~110 tables, 1,100+ scripts). In my opinion a hard cutover is a high-risk path; incremental parallel crossover is the safer general direction. Once you've settled on your approach I can help shape access methods to suit.
External access for your build: OData (table reads) and FileMaker Data API (layout reads; scripts when writes are agreed later). ODBC is excluded from this handover.
Initially read-only on the account supplied below. Write-back, when needed, is a separate agreement — same access methods, tighter surfaces.
This handover covers WhipIT 3 only. WhipITApp holds no data of consequence; WhipIT_Files is unlikely to add much in early stages.
Layout access (Data API): api_read can view all layouts — for exploration and familiarisation. When requirements are clear, I'll curate layouts (or add API_* layouts) and grant them to api_integration, the account intended for your application.
Table access (OData): same pattern — api_read can view all tables for now; api_integration gets a curated table list when we've clarified what the application needs.

2. Development host

Item	Value
Host	`sage.teamdf.cloud`
File	`WhipIT 3.fmp12`
Scope	This file only (not WhipITApp / WhipIT_Files in this handover)
Environment	Development copy — not production (`fm.xzibit.com.au`)

Database name for API URLs: WhipIT 3 — use WhipIT%203 in URLs (space URL-encoded). Verified on dev June 2026.

3. Account supplied

Account	Privilege set	Role	Shared?
`api_read`	`APIClient_Read`	Exploration — broad read access to map the system	Yes — credentials below
`api_integration`	Copy of `APIClient_Read`, refined later (e.g. `APIClient_Integration`)	Operational account for your application — curated layouts/tables when requirements are clear; writes later if agreed	No — not issued in this handover

Credentials:

Host:     sage.teamdf.cloud
Account:  api_read
Password: [ supplied separately ]

Please: HTTPS only; do not commit credentials; do not log session tokens.

4. Two ways to read data

	FileMaker Data API	OData
Use for	Layout-based reads; related records via portals; later: run FM scripts on write	Table/entity reads; schema discovery; `$filter` / `$select`
Extended privilege	`fmrest`	`fmodata`
Claris guide	Data API	OData
LLM Doc index	help.claris.com/llms.txt	same

Read-only with api_read: no record create/edit/delete via API; no script execution. api_integration will be configured for application use when surfaces are agreed (writes and scripts only if explicitly enabled on that account).

5. Quick start — Data API

Base path (typical):

https://sage.teamdf.cloud/fmi/data/vLatest/databases/WhipIT%203/

1. Open session (returns token in X-FM-Data-Access-Token response header):

curl -s -D - -X POST \
  "https://sage.teamdf.cloud/fmi/data/vLatest/databases/WhipIT%203/sessions" \
  -H "Content-Type: application/json" \
  -u "api_read:YOUR_PASSWORD" \
  -d '{}'

2. Layout metadata (discover layouts and fields):

curl -s -X GET \
  "https://sage.teamdf.cloud/fmi/data/vLatest/databases/WhipIT%203/layouts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

3. Get records (example — replace layout name):

curl -s -X GET \
  "https://sage.teamdf.cloud/fmi/data/vLatest/databases/WhipIT%203/layouts/{layout-name}/records?_limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

4. End session when finished:

curl -s -X DELETE \
  "https://sage.teamdf.cloud/fmi/data/vLatest/databases/WhipIT%203/sessions/YOUR_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN"

Use existing User layouts for exploration — the account can read any layout the privilege set allows. Start with /layouts metadata and sample GET/find calls on layouts that match the domains you care about (jobs, clients, quotes, etc.).

Layout access policy (dev): APIClient_Read → Layouts → Custom privileges → All layouts: View only. After you’ve mapped what you need, curated layouts (including dedicated *API_ layouts if useful) go on api_integration**.

OData does not use layouts; which tables appear is controlled by record privileges on the privilege set (see section 6).

6. Quick start — OData

Base path:

https://sage.teamdf.cloud/fmi/odata/v4/WhipIT%203/

Authentication

Unlike the Data API, OData does not use a session token. Each request is authenticated with HTTP Basic Auth — the same account and password as above, sent in the Authorization header (Basic + base64 of account:password). There is no separate login step.

Claris references: Creating an authenticated connection, Enable OData access.

Metadata and discovery

1. Full schema ($metadata — tables, fields, types; large response):

curl -s -u "api_read:YOUR_PASSWORD" \
  "https://sage.teamdf.cloud/fmi/odata/v4/WhipIT%203/\$metadata"

2. Entity list (lighter — confirms database name and available tables):

curl -s -u "api_read:YOUR_PASSWORD" \
  "https://sage.teamdf.cloud/fmi/odata/v4/WhipIT%203/"

Entity names match base table names (e.g. ClientSupplier, Job). Use $metadata or the entity list to confirm exact names before querying.

3. Sample records (replace table name; add $top, $filter, $select as needed):

curl -s -u "api_read:YOUR_PASSWORD" \
  "https://sage.teamdf.cloud/fmi/odata/v4/WhipIT%203/ClientSupplier?\$top=5"

curl -s -u "api_read:YOUR_PASSWORD" \
  "https://sage.teamdf.cloud/fmi/odata/v4/WhipIT%203/Job?\$top=10&\$select=zzrec_id,Job_Name"

See Get metadata, Get list of tables, Request records from a table.

Tips: paginate with $top / $skip (max 10,000 records per response); filter by modification timestamp where possible; avoid full-table pulls on large tables (e.g. quote line details, time entries, messages).

7. Sensible first reads (mapping)

For schema mapping, these WhipIT areas are useful starting points (table names from DDR — verify on dev):

Area	Base tables (indicative)
Clients / suppliers	`ClientSupplier`, `ClientSupplierDetails`
Products	`Products`, `Product_Rates`
Staff (FM accounts)	`UserAccounts` — separate from client contacts
Jobs	`Job`
Quotes (headers)	`Quotes`

Large / sensitive tables — use filters, not bulk export in dev without coordination: QuoteLineItemDetails, TimeEntries, MessagesMerged.

Primary keys often include zzrec_id — confirm on layouts or OData metadata.

8. What’s not included

Production host access (fm.xzibit.com.au)
api_integration credentials (operational account — issued when curated access is agreed)
Pre-built *API_** integration layouts (added after exploration — once required fields and relationships are clear)
ODBC / JDBC drivers
Ownership of migration phasing or sync design

9. Next steps

Explore metadata and layouts (sections 5–6). OData entity list is confirmed on dev; open a Data API session when you need layout/portal reads.
Explore metadata; map entities and layouts you need for read-only reports/UI.
Agree with Xzibit how parallel running and crossover will work.
When you’re ready to wire the application account or need write-back / production access, contact Sam — we’ll configure api_integration and FM-side surfaces to match.

Questions on how WhipIT behaves today: Sam (within Whiplash / maintenance scope).

Questions on replacement architecture: your programme with Xzibit.

10. Server-side checklist (Sam — internal)

Data API enabled for WhipIT 3 on sage.teamdf.cloud
OData enabled on server; APIClient_Read has fmodata + record view on all tables (api_read); curate per-table access on api_integration later
Privilege set APIClient_Read: Records View only; Extended fmrest + fmodata; Scripts All no access; no fmapp / fmxdbc
Layout custom privileges (APIClient_Read): All layouts → View only (api_read explores; curate for api_integration later)
Account api_read → privilege set APIClient_Read
Account api_integration + duplicate privilege set created; not shared until application access is curated
OData entity list verified (WhipIT%203) — June 2026