README

A Craft CMS plugin that adds Beacon CRM as a CRM integration for Formie, letting form submissions create or update records in your Beacon database.

📖 Read the documentation

Features

Works with any Beacon account. The plugin reads your account's schema from Beacon's API at runtime, so nothing is hard-coded. Your custom record types and custom c_* fields appear in the mapping UI automatically.
Any record type. Map to Person, Organisation, Payment, or any custom record type you've created.
Exact drop-down values. Options for drop-down fields are read from your account, so you pick from the configured values rather than typing them and hoping.
Create or update. Optionally upsert on a field of your choice to avoid creating duplicate records from repeat submissions.
Fixed values. Send a constant value for any field, such as a Source of "Website", without needing a form field for it.
Records linked by name. A form collects a church name; Beacon's link fields want a record ID. The plugin looks the record up — optionally creating it — and can also add the new record to a list on the other side without dropping what is already there.
Useful logging. Successful writes log their Beacon record ID. Failures log Beacon's actual validation message rather than its generic error.

Requirements

Craft CMS 5.0.0+
PHP 8.2+
Formie 3.0+

The Beacon API work (reading your account schema, shaping values, unpacking Beacon's errors) is done by coyshdigital/beaconcrm-php, which Composer installs alongside the plugin. Use that library directly if you need to talk to Beacon from elsewhere in your project.

Installation

composer require coyshdigital/craft-formie-beacon
php craft plugin/install formie-beacon-crm

Setup

In Beacon, go to Settings > API keys and create a key. It is shown once, so copy it immediately. Only an administrator can create one.

Add the key to your .env:

BEACON_ACCOUNT_ID=12345
BEACON_API_KEY=your-secret-key

In Craft, go to Formie > Settings > CRM and add a Beacon integration.
Set Account ID to $BEACON_ACCOUNT_ID and API Key to $BEACON_API_KEY. Your account ID is the number in your Beacon API URL: https://api.beaconcrm.org/v1/account/12345.
Save, then hit Refresh to verify the connection.

Storing credentials as environment variables keeps the API key out of your project config and out of version control.

Per-form configuration

On a form, go to Integrations > Beacon and enable it. Then:

Record Type. Which Beacon record to create. The list is read from your account.
Update Existing Records. When on, the plugin upserts instead of always creating. Pick a Match On field that holds a genuinely unique value. Email is the usual choice for people. That field must also be mapped.
Field Mapping. Map your form fields to Beacon fields.
Fixed values. Send a constant value for a field on every submission. Drop-downs offer their configured options, everything else takes free text. If a field is both mapped and fixed, the submitted value wins.
Linked Records. For each field that points at another record, choose the form value that identifies it, the field to match it against, and whether to create it when nothing matches. See the documentation.

Use Opt-In Field if you only want to send data when a user consents, typically an Agree field.

How values are converted

Beacon expects specific shapes per field type, which the plugin handles for you via the shared beaconcrm-php library:

Beacon field type	What gets sent
Person name	An object. Each name part is a separate mapping row, and `Full` is derived if you only map the parts
Email	`[{ "email": "...", "is_primary": true }]`
Phone	`[{ "number": "...", "is_primary": true }]`
Drop-down	An array, even for single-select fields
Record link	An array of integer Beacon record IDs
Checkbox	A JSON boolean
Currency	`{ "value": 25.5 }` in major units, using your account's default currency. Beacon silently discards bare numbers here
Number, percent, rating	A JSON number

Empty values are skipped rather than sent, so a blank optional field on your form will not overwrite data already held in Beacon. 0 and false are real values and are sent.

Known limitations

File upload fields are not supported. Beacon requires a separate signed-upload handshake that cannot be performed inside the entity payload, so file fields are omitted from the mapping UI.
Read-only fields are omitted. Smart fields, rollup fields, and auto-increment fields are computed by Beacon and rejected on write.
Only one address per record can be mapped. Address fields appear in the mapping UI one part at a time and fill in the record's first address. A write replaces the whole address list rather than adding to it.
Record links need Beacon record IDs. To populate one, your form must supply the numeric ID of an existing Beacon record. The plugin does not look records up by name.
Beacon workflows can fire on API writes. Before going live, check whether any active workflow will send communications or create tasks in response to records the form creates.

Troubleshooting

Failed sends are logged with Beacon's own error message. Check Formie > Submissions > (a submission) > Integrations, or storage/logs/formie.log.

invalid_api_key means the key was revoked or mistyped.
A validation error naming a field usually means a drop-down value is not configured in Beacon, or a record link was given something other than a record ID. Beacon reports these with a 500 status and a generic message, so the plugin digs out the specific cause and logs that instead.
429 means you have hit Beacon's rate limit: 300 requests per minute, or 60 for bulk operations.

Documentation

Full documentation is at coysh.digital/plugins/craft-formie-beacon/docs.

License

MIT

coyshdigital / craft-formie-beacon

Maintainers

Package info

Statistics

Security