SIGNALS Docs
Exit Reader View
100%
Theme

Plugin data models

Entity catalogue and field reference for plugin data_access — the supported entities and their readable fields, custom_fields semantics, and how to read/write via the guarded facade.

Purpose

Use this page for domain meanings; the data access tables define the exact supported fields, filters, sorting and operations. Cross-links:

Entity catalogue (PluginEntityMap)

Entity key Eloquent model Domain meaning
accounts App\Models\Account Universal CRM entity — contacts, companies, venues, and users differentiated by account_type
rentals App\Models\Rental Quotes and orders (rental job lifecycle)
invoices App\Models\Invoice Invoices and related billing documents in the invoice model
catalogue_items App\Models\CatalogueItem Catalogue items (rental, sale, service, etc.)

The SDK 2.1 read-only entity keys include credit_notes (credit documents with lines and taxes), payments (invoice payments and refunds), purchase_orders (supplier orders with guarded cost lines), vehicles (fleet records and warehouse assignments), assets, activities, warehouses, users and custom_field_definitions. The users projection is limited to id, name, email and is_active. Unknown entity declarations are structurally valid but grant no runtime access.

Accounts as the universal entity

In Signals, people, companies, venues, and login-capable users are all rows in accounts. Plugins that sync “contacts” or “customers” almost always target accounts, not a separate contact table.

Field naming across surfaces

Surface Naming
REST API resource attributes Flat rental attributes such as billing_period_starts_at, billable_days and subtotal
SchemaRegistry / import-export field names Flat rental attributes such as billing_period_starts_at, billable_days and subtotal
Plugin data_access field lists The same flat attributes as the model and import/export registry

Rental database columns, REST requests and responses, MCP, plugin fields, imports, exports, reports and merge fields all share the same flat names. uses_billable_days, customer_collects and customer_returns are booleans on every surface. Money responses use decimal strings with currency_code, matching invoices.

Plugin access is narrower: use only the readable-field allowlists. SchemaRegistry and REST metadata describe more fields than a plugin can request; they do not grant plugin access.

Custom fields differ: API and facade expose them as a nested flat map custom_fields: { name: value }. In the manifest, declare custom_fields (wholesale) or custom_fields.{name}. Custom field definitions live in the custom_fields table and appear in SchemaRegistry with source = custom — they are installation-specific, so consult your install rather than any static list.

Virtual facade field: accounts + email (primary email sync) is supported by PluginDataAccess but is not a SchemaRegistry core column — declare it explicitly when needed.

How to access

$context->read('accounts', $id);
$context->update('invoices', $id, [
    'custom_fields' => ['external_invoice_id' => $externalId],
]);
$context->operation('rentals.change_status', ['rental_id' => $rentalId, 'status' => $statusCode]);

In hooks, use PluginContext::read() / update() / setting().

Cannot: arbitrary query builders or direct Eloquent on core models. PluginContext::list() supports declared filters and signed pagination — see Plugin data access.

OpenAPI reference: /docs/api/reference. Markdown references:

Entity API docs
Accounts Accounts API
Rentals Rentals API
Invoices Invoices API
Catalogue items Catalogue items API

Schema introspection: GET /api/v1/schemas/{accounts\|rentals\|invoices\|catalogue_items} (when enabled in your install).

Field reference

The data access tables are the plugin field reference. REST attributes, import/export metadata and tenant custom fields provide domain context, but only the SDK allowlists and your stored manifest determine access.

Invoice reads can include lines and taxes. The finance collection and money contract defines their closed fields, currency units, ordering, redaction and limits. Declare the whole collection rather than individual dotted line fields.

SDK 2.2 payment reads add original_payment_id (null for positive payments), correction_kind (refund, reversal, or null), posting_date and value_date. Payment page reads batch receipt lookups. PO reads add is_billed, billed_reference, billed_at, billed_amount (requires costs access), and billed_currency_code. These are read-only; use the external billing-marker operations to mutate them.

Rental header totals use subtotal for the final net amount, including any agreed-price override, tax_total for tax, and total for their sum. subtotal_base records the converted net amount when base-currency evidence is available; verified_subtotal_base records its verified dashboard amount. REST and MCP use subtotal and total. Each flat net field appears once.