CRM Trigger¶
Overview¶
The CRM Trigger automatically starts workflows when specific events occur in your BaseCloud CRM. This creates powerful automation based on contact behavior, data changes, and CRM activities without any manual intervention.
When to use this trigger:
- Send welcome emails when new contacts are created
- Notify team members when contact data changes
- Trigger follow-ups based on contact status changes
- Automate actions when custom field values change
Quick Start¶
Builder fields¶
The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.
| Field | Key | Type | Default | Notes |
|---|---|---|---|---|
| Trigger Type | trigger_type |
select | 1 |
Options: Client Created · Client Field Change · Client Field Button Click · Contact Field Change · Quote / Invoice Change · Workflow Note Change · Custom Table: Row Added · Custom Table: Row Deleted · Custom Table: Cell Change · Custom Table: Cell Button Click |
| Target Field | var_id |
select | – | Options: Client/Company Name · Client Status · Responsible Manager. Only shown when trigger_type is 1 |
| Target Column | var_id |
select | – | Only shown when trigger_type is 2 |
| Only when the new value is one of | value_in |
select | – | Only shown when trigger_type is 1, 2 and the field is the status, the Responsible Manager, or a dropdown or user field or column |
| Only when it changes to | value_in |
select | – | Options: Any change · Yes · No. Only shown when trigger_type is 1, 2 and the field is a Yes/No field or column |
| Only when the new number is | value_in |
number | – | Only shown when trigger_type is 1, 2 and the field is a number or currency field or column |
| Only when the new date is | value_in |
date | – | Only shown when trigger_type is 1, 2 and the field is a date field or column |
| Only when the new time is | value_in |
time | – | Only shown when trigger_type is 1, 2 and the field is a time field or column |
| Only when the new text is | value_in |
text | – | Only shown when trigger_type is 1, 2 and the field is the company name or a text or location field or column |
| Invoice Event | var_id |
select | – | Options: Quote/Invoice Created · Quote/Invoice Edited · Quote/Invoice Deleted · Quote/Invoice Marked as paid · Quote/Invoice Marked as unpaid · Payment received · Payment refunded · Credit note created · Quote accepted online. Only shown when trigger_type is 3 |
| Target Contact Field | var_id |
select | – | Only shown when trigger_type is 5 |
| Target Table | var_id |
select | – | Only shown when trigger_type is 6, 10 |
| Note Event | var_id |
select | – | Options: Workflow Note Created · Workflow Note Marked as done. Only shown when trigger_type is 7 |
| Button Field | var_id |
select | – | Only shown when trigger_type is 8 |
| Button Column | var_id |
select | – | Only shown when trigger_type is 9 |
- Create a new workflow
- Add a CRM Trigger as the first task
- Select the trigger type, then what it watches (the field, column, event or table)
- Save and switch the workflow on
- The workflow runs automatically when the event occurs

Trigger Types¶
| Trigger type | Starts the workflow when | Then choose |
|---|---|---|
| Client Created | a client is created — by hand, by a form or by another workflow | – |
| Client Field Change | the chosen client field changes (name, status, manager, address, billing address, or a custom field) | the field |
| Client Field Button Click | someone clicks a button custom field on a client | the button field |
| Contact Field Change | the chosen contact field changes | the contact field |
| Quote / Invoice Change | a quote or invoice is created, edited, deleted (voided), marked paid or marked unpaid; a payment is received or refunded; a credit note is made; a client accepts a quote online. See Invoice and payment events | the event |
| Workflow Note Change | a workflow note is created or marked done | the event |
| Custom Table: Row Added | a row is added to the chosen custom table | the table |
| Custom Table: Row Deleted | a row is deleted from the chosen custom table — by hand, in bulk or by a workflow. Hands on what the row held — see The row | the table |
| Custom Table: Cell Change | the chosen column changes in any row | the column |
| Custom Table: Cell Button Click | someone clicks a button column in a row | the button column |
Workflow Note Created doesn't fire for older email BaseCloud reads back when a mailbox is connected, or when it reads further back — that email is filed as history (see Email cleanup). Email that arrives after that fires it as usual.
Client Field Change also fires for each custom field someone fills in while they create a client — in the Create New Client window, or through a connected AI app — just after Client Created, as a change from blank. A client made by a workflow's New Client task doesn't fire it, so a workflow can't set itself off again by creating a client.
The trigger fires on the change itself. A Client Field Change or a Custom Table: Cell Change can be narrowed to the new values you care about — a status, a manager, a dropdown option, a person, Yes or No, a number, a date, a time or a text — see Acting only on some changes. Anything else ("contains", "greater than", the old value) is an If after the trigger.
Changing the trigger type clears the choice below it (the field, event or table, and the values chosen), because a field picked for one type means nothing to another — pick it again. Changing the field or column clears the values chosen too.
Each type is something people do in the CRM. These pages show what that looks like on screen:
| Trigger type | Where it happens in the CRM |
|---|---|
| Client Created | Add a client |
| Client Field Change | Edit clients — including changing a status — fill in custom fields, and the fields filled in when you add a client |
| Client Field Button Click | Button fields |
| Contact Field Change | Edit a contact and contact custom fields |
| Quote / Invoice Change | Make a quote or invoice, turn a quote into an invoice, record a payment, make a credit note or void it |
| Workflow Note Change | Add a note and mark notes done |
| Custom Table: Row Added | Add a row |
| Custom Table: Row Deleted | Work with table rows |
| Custom Table: Cell Change | Change a value |
| Custom Table: Cell Button Click | Work with table rows |

Custom fields are defined per tenant on the client record itself — the pencil edits the set, Add Field creates one (see Manage custom fields). You pick a field by its name in the task, but the task stores its ID, so renaming the field later doesn't break the workflow; deleting it does.
The custom table events watch tables and columns that are also set up on the client — see Custom tables in automations.

Statuses are defined per tenant in Settings → Client Statuses, so the list differs between accounts — a status that exists in one tenant may not exist in another. Each carries a numeric ID, and that ID is what a task reads and writes; the label is only what people see. Deactivating a status hides it from dropdowns without removing it from records that already hold it.
Outputs¶
The CRM Trigger outputs the change-log entry that fired it, joined to the client and the users
involved. Reference fields as {{task_<ID>_<field>}}.
The change¶
| Field | Type | Notes |
|---|---|---|
id |
number | The change-log entry's ID. |
var_id |
string | Which field changed — e.g. client_status, client_field_updated, contact_created. |
var_val |
string | The new value. |
var_val_from |
string | The previous value. |
date_created |
string | When the change happened, DD/MM/YYYY HH:mm. |
custom_field_id |
number | Set when the change was to a custom field. |
table_id, row_id, column_id |
number | Set for table-row changes. |
wfn_id |
number | Set for workflow-note changes. |
inv_id |
number | Set for quote/invoice changes. |
channel_id, task_id |
number | The workflow and task that fired. |
The client¶
| Field | Type | Notes |
|---|---|---|
client_id |
number | The client the change belongs to. |
company_name |
string | The client's name. |
origin |
string | The client's origin (first_contact). |
owner_id |
number | Account ID. |
user_created |
number | Who created the client. |
contact_id |
number | Set when the change concerns a contact. |
Who made the change, and who owns the client¶
| Field | Type | Notes |
|---|---|---|
user_actioned |
number | ID of the user who made the change. |
user_actioned_name, user_actioned_surname |
string | Their name. |
user_actioned_email, user_actioned_number |
string | Their contact details. |
admin_responsible |
number | ID of the client's responsible user. |
admin_responsible_name, admin_responsible_surname |
string | Their name. |
admin_responsible_email, admin_responsible_number |
string | Their contact details. |
Resolved labels, on field-change triggers¶
| Field | Type | Notes |
|---|---|---|
status_changed_to |
string | Status label, when var_id is client_status. |
status_changed_from |
string | The previous status label. |
custom_field_changed_to |
string | Readable new value, when a custom field changed. Falls back to the raw value if the field has since been deleted. |
custom_field_changed_from |
string | Readable previous value. |
The row, on custom table triggers¶
Row Added, Row Deleted, Cell Change and Cell Button Click also output the row as table: one entry
per column under table.row_data, named by the column's field ID — its number in the table. Pick a cell from the
variable picker, or write it yourself: {{task_<ID>_table_row_data_<field_id>_value}}, or
{{task_<ID>.JSON.table.row_data.<field_id>.value}}. For example, the third column's readable value is
{{task_<ID>_table_row_data_3_text_value}}.
| Field in each cell | Notes |
|---|---|
value |
What the cell holds — for a dropdown, the option's ID; for a user column, the user's ID. |
text_value |
The readable value — a dropdown's option name, or every option chosen in a multi-select. |
column_label |
The column's name. |
user_name, user_surname |
On a user column: the person named in the cell. |
file_name, file_url |
On a file column — file_names and file_urls when the column holds several files. |
On Row Deleted the row is already gone, so table is the row as it was just before it was deleted — whether
it was deleted by hand, in bulk or by a workflow. That lets a workflow finish what the row started: cancel the
calendar event whose ID it held, or tell the person it was assigned to. You don't need a second table to remember a
row's values for when it is deleted. The row's attached files are deleted with it, so a file_url no longer opens.
The row is kept only while a Row Deleted trigger is switched on for that table: a row deleted before you set one
up, or while its workflow was off, comes through with an empty table. To see the fields in the variable picker,
delete a test row once the trigger is on.
Always¶
| Field | Type | Notes |
|---|---|---|
run |
boolean | Whether the task succeeded. |
run_text |
string | A human-readable account of what happened, including any reason it failed. |
Invoice and payment events¶
A Quote / Invoice Change trigger starts on one of these events:
| Event | var_id |
Fires |
|---|---|---|
| Quote/Invoice Created | invoice_created |
When a quote or invoice is made. |
| Quote/Invoice Edited | invoice_edited |
When one is changed, or a quote becomes an invoice. |
| Quote/Invoice Deleted | invoice_deleted |
When one is voided. |
| Quote/Invoice Marked as paid | invoice_paid |
Once, when an invoice becomes paid in full and money was received on it: by payments, by the client's credit from a payment, or by a credit note or short payment that settles the rest of an invoice the client paid part of. Not for a part payment, a write-off, or a credit note that settles an invoice nothing was paid on. |
| Quote/Invoice Marked as unpaid | invoice_unpaid |
When an invoice that was paid in full owes money again: a payment removed, or credit taken off. |
| Payment received | payment_received |
For every payment in: full, part, an overpayment, or a prepayment with no invoice. A payment the gateway reports twice fires once. |
| Payment refunded | payment_refunded |
For every refund recorded. |
| Credit note created | credit_note_created |
For every credit note: credited invoices, goodwill credit, write-offs, short payments and refunds of a sale. |
| Quote accepted online | quote_accepted |
When a client accepts a quote on its payment page by typing their name. The Accept button shows only when your Online payments are set to Accept it only, without paying, or when the quote can't be paid online. The document outputs describe the quote. |
Marked as paid means money arrived
Marked as paid fires only when money was received on the invoice. A write-off, or a credit note that takes back
a sale nothing was paid on, fires Credit note created instead. A thank-you or receipt workflow on Marked as
paid can still check quote_invoice_payment_status: Paid means it was paid with money (some of it may have been
credited). See Payment received: thank you and update.
Records brought over from an old system with the Accounting task's Old document setting start none of these events.
The document's outputs¶
On every invoice event, the document the event is about:
| Field | Notes |
|---|---|
quote_invoice_id |
BaseCloud's ID for the document. |
quote_invoice_o_id, quote_invoice_o_id_full |
Its number, and with its prefix: QU1024, INV1025, CN1026. |
quote_invoice |
Quote, Invoice or Credit Note. |
quote_invoice_paid |
Yes when it's paid in full, otherwise No. A void or part-paid invoice is No. |
quote_invoice_status |
Unpaid, Paid or Void. A part-paid invoice reads Unpaid, as money is still owed, so workflows that branch on it keep working. |
quote_invoice_payment_status |
Unpaid, Part Paid, Paid, Credited or Void. On a credit note: Unused, Part Used, Used or Void. |
quote_invoice_amount_paid |
What has been paid on it. |
quote_invoice_balance_due |
What it still owes. Empty on a quote; on a credit note, the credit still unused. |
quote_invoice_date_paid |
The day it was paid in full. Only when it is. |
quote_invoice_field_<id>, quote_invoice_field_<id>_value |
Each of your quote and invoice fields on the document: as a person reads it (an option's name, a user's name, Yes/No), and as stored (an option's or user's ID, 1/0). Empty when the field is. |
Plus its lines (item_description, item_code, item_quantity and the rest) and totals.
How the invoice was paid¶
On every invoice event, every payment on the invoice, so a workflow can work out by how it was paid: an invoice paid in two parts was paid two ways.
| Field | Notes |
|---|---|
payments |
A list, one entry per payment: payment_id, amount (the part of the payment on this invoice; one payment can pay several invoices), date (YYYY-MM-DD), method (worded as on the invoice: ACH, Card, your own Venmo…), method_code, gateway (stripe, paystack, or empty), reference and currency. Oldest first. Empty on a quote, a credit note, or an invoice nothing was paid on. |
payment_count |
How many payments, e.g. 2. |
payments_total |
What they come to, e.g. 750.10. |
Only money is listed. Credit from a credit note isn't a payment, so an invoice settled partly by one lists only what was paid. Credit kept from an earlier overpayment is that payment, with its own date and method. A payment that was taken off isn't listed.
To work out by method, compare method_code, not method: it stays the same when you rename a payment method in
Settings. It is ach, wire, eft (a bank transfer), cheque (a check), cash, card, card_machine,
gateway (paid online), other, or custom_ and a number for a method you added yourself.
- Loop over them: a Loop set to For each item in a JSON array, over
{{task_<ID>.JSON.payments}}. Each one's fields are then{{task_<loop ID>_loop_value_method}},{{task_<loop ID>_loop_value_amount}}and so on. - Work them out in one step: a Code task given
{{task_<ID>.JSON.payments}}, for example adding upamountwheremethod_codeiscard. - Just one:
{{task_<ID>_payments_0_method}}is the first payment's method,{{task_<ID>_payments_1_amount}}the second's amount.
The Accounting task's Fetch and Mark Paid give the same three fields,
for a workflow that doesn't start on an invoice event. On Payment received, payment_method and
payment_reference describe the one payment that just arrived; payments lists every payment on the invoice,
that one included.
A Payment received event is about the first invoice the payment paid. A payment that paid no invoice (a prepayment) and every Payment refunded event have no document outputs, only the payment's and the client's.
The payment's outputs¶
On Payment received and Payment refunded:
| Field | Notes |
|---|---|
payment_id |
BaseCloud's ID for the payment. |
payment_amount |
How much, e.g. 150.00. |
payment_currency |
The currency, e.g. USD. |
payment_date |
The day it was paid, YYYY-MM-DD. |
payment_method |
How, in your currency's words: ACH, Check, Wire transfer, Bank transfer (US) or EFT, Cheque (South Africa), and Cash, Card, Card machine, Online payment (Stripe), Other… |
payment_reference |
The reference, or the gateway's transaction ID. |
payment_credit |
The part of a payment in that is kept as credit (not on an invoice). 0.00 on a refund. |
The credit note's outputs¶
On Credit note created, the document outputs describe the credit note, plus:
| Field | Notes |
|---|---|
credit_note_kind |
Credit, Write-off or Short payment. |
credit_note_reason |
The reason given. |
credit_note_for_invoice |
The invoice it was made from, e.g. INV1025. Empty for a credit note with no invoice. |
credit_note_credit_remaining |
Its credit not yet applied or refunded. |
Real-World Examples¶
Welcome a newly created client¶
Act on a status change¶
CRM Trigger (field change, client_status — only when the new value is one of: Won)
└─ BaseCloud Accounting raise the invoice
The workflow starts only when a client's status changes to Won, so there is nothing to throw away. Choose several
statuses ("Won" or "Lost") to cover the cases one If with OR used to. status_changed_to and status_changed_from
still give you the readable labels for the tasks after it.
Tell the new owner when a client is reassigned¶
CRM Trigger (field change, admin_responsible)
└─ Email notify {{task_47001_admin_responsible_email}}
Keep another system in step¶
Acting only on some changes¶
Use the trigger's own value filter rather than an If. With Client Field Change and a field chosen, or Custom Table: Cell Change and a column chosen, a setting under it asks which new values start the workflow. What it offers follows the field or column:
| Field | The filter | It starts the workflow when |
|---|---|---|
| Client Status | Only when the new value is one of — your statuses, by name | the status changes to one you picked |
| Responsible Manager, a Single User field | Only when the new value is one of — your users, by name | the client is given to one you picked |
| a Single Choice dropdown | Only when the new value is one of — the field's options, by name | the field changes to one you picked |
| a Multiple Choice dropdown, a Multiple Users field | Only when the new value is one of — its options or users, by name | one you picked is added |
| a Checkbox (Yes/No) | Only when it changes to — Yes or No | the box is ticked (Yes) or unticked (No) |
| a Number or Currency field | Only when the new number is — one number | the field changes to that number |
| a Date field | Only when the new date is — one date | the field changes to that date |
| a Time field | Only when the new time is — one time of day | the field changes to that time |
| Client/Company Name, a Single-Line Text, Multi-Line Text or Location field | Only when the new text is — one text | the field changes to that text |
A table column offers the same filter as a client field of its kind: a Single Choice or Multiple Choice column its own options, a user column the people it offers, and a Checkbox, Number, Currency, Date, Time, Text or Location column as above. For example, a Jobs table's Status column with Only when the new value is one of: On the way starts a workflow that texts the customer that the tech is coming — and only then. There is no filter on attachment or button columns.
Pick one value or several from a list; a number, date, time or text takes one. However the field or cell was changed — the client page or the table, Bulk Edit, an Edit a Client or Table task, the New Client form or the AI connection — the same change passes the same way:
- a change to any other value starts nothing — no run at all, so nothing shows in the workflow's runs;
- saving a client or a row with the value it already has starts nothing either, from the client page or Bulk Edit alike;
- leave it empty to start on every change of the field or column, as before;
- the client's history records every change, whether or not it started the workflow.
How each kind of field is compared:
- Multiple choice and multiple users: "was added". The workflow starts when one of your picks is in the new value and was not in the old one. Ticking another option beside one that was already there starts nothing, and neither does unticking one; ticking yours starts it, whatever else is ticked.
- Yes/No. A tick saved as "1", "true" or "Yes" is the same Yes. A box never ticked counts as No: on screen it is unticked already, so saving it unticked changes nothing you can see, and a filter on No does not start for it. Filtering on No starts the workflow when a tick is taken off.
- Numbers are compared as numbers: 10, "10" and 10.00 are the same, and 1,000 is one thousand.
- Dates are compared as the day, however it was written (2026-11-01 or 01/11/2026).
- Times are compared as the time of day: 9:30 am and 09:30 are the same.
- Text is one value, matched whole, ignoring capitals and spaces at either end: "ACME " matches Acme, but "Acme Ltd" does not. A comma is part of the text, not a separator.
There is no filter on attachment, button or client fields: their values are files, presses and client links, nothing to pick from.
This is cheaper than starting the workflow and stopping it in an If straight away: a run thrown away by an If is a whole run, and a bulk status change of thousands of clients starts thousands of them. Picking a test record runs the trigger on it only when its change passes the filter, so a test shows what would really happen.
For anything the filter does not cover — a condition on the old value, "contains", "greater than", a date range, or
"is not one of" — put an If right after the trigger and test the outputs: for example
{{task_<ID>_var_val_from}} is empty (a field filled in for the first time).
Preventing Workflow Loops¶
A workflow that changes the very field its trigger watches starts itself again: Client Field Change on Status, then an Edit a Client that sets the status, runs again on its own change.
- Filter on the values you start for. A trigger with a value filter set is not started by its own workflow writing any other value, so a workflow that moves a client from "New" to "Contacted" no longer starts itself again.
- Watch a different field from the one the workflow writes.
- Know when a re-save counts. Without a filter, saving a client with the value it already has — from the client page or Bulk Edit — does start the workflow, once per client. With a filter, it never does. Edit a Client is the exception either way: it does not write, or announce, a value equal to what the client already holds.
- Check who made the change.
user_actionedis the person who made it; a change made by a workflow is recorded against the automation user. An If onuser_actionedcan skip changes a workflow made.
Best Practices¶
✅ Do's¶
- Be specific with triggers: Use filters to avoid unnecessary executions
- Add If tasks for validation: Double-check conditions even if trigger has filters
- Test thoroughly: Test with real CRM data before enabling
- Add error notifications: Alert yourself when critical workflows fail
- Document your workflows: Add clear descriptions of what each workflow does
- Use tags for tracking: Add tags to show workflow has processed a contact
- Monitor execution history: Check regularly that workflows are running correctly
❌ Don'ts¶
- Don't create loops: Always check if your workflow updates trigger new events
- Don't trigger on every update: Use specific field monitoring
- Don't skip error handling: Add If tasks to handle missing data
- Don't forget timezone issues: Be aware when using time-based conditions
- Don't over-automate: Not every CRM change needs a workflow
Troubleshooting¶
Workflow Not Triggering¶
Possible Causes:
- Workflow is disabled
- Trigger conditions too restrictive
- Event type doesn't match actual CRM action
- CRM trigger not saved properly
Solutions:
- Check workflow toggle is ON
- Review trigger configuration and filters
- Test by manually performing the CRM action
- Check execution history for error messages
Workflow Triggering Too Often¶
Possible Causes:
- Trigger conditions too broad
- Multiple users editing same contacts
- Workflow creating loop by updating contacts
Solutions:
- Add more specific filters
- Check if workflow updates trigger additional events
- Use "Changed Field" filters
- Add processing flag to prevent duplicates
Missing Contact Data¶
Possible Causes:
- Custom field not populated yet
- Contact still being created when workflow runs
Solutions:
- Add small delay (5-10 seconds) after trigger
- Use If tasks to check if required fields exist
- Handle missing data gracefully
Workflow Running Multiple Times¶
Cause: Multiple CRM updates in quick succession
Solution: each change is its own run, by design. To act once on a burst of changes, have the workflow set a field (for example "Synced at") and check it with an If before acting.
Advanced Patterns¶
Sequential Contact Updates¶
Update contact in stages with delays:
- CRM Trigger - Client Created
- Delay - Wait 1 day
- Email - Send day 1 email
- Delay - Wait 2 days
- Email - Send day 3 email
- Delay - Wait 4 days
- Email - Send day 7 email
Conditional Multi-Path Workflows¶
Route based on contact properties:
- CRM Trigger - Client Field Change (Industry)
- If Task - Check industry
- Technology → Tech sales flow
- Healthcare → Healthcare sales flow
- Other → General flow
Lead Scoring Automation¶
Automatically update lead scores:
- CRM Trigger - Contact Field Change
- Code Task - Calculate lead score based on actions
- Edit Client - Update lead_score field
- If Task - If score >= 80
- Email - Notify sales team
Frequently Asked Questions¶
Can I have multiple CRM Triggers in one workflow?¶
Yes — a workflow can have several triggers, each starting the tasks linked under it. One workflow per purpose is usually easier to follow.
What's the delay between CRM change and workflow execution?¶
Usually immediate (within seconds). Very complex workflows may take longer.
Can I trigger on custom field changes?¶
Yes — choose Client Field Change (or Contact Field Change) and pick the custom field. On a client field you can also say which new values start it — see Acting only on some changes.
Will this trigger if I bulk import contacts?¶
Yes — Client Created fires for each imported client. Switch the workflow off during a large import if it should not run for them. - Adding batch processing logic
Can I undo a workflow action?¶
No, workflows execute automatically and cannot be undone. Always test thoroughly before enabling.
How do I test without affecting real contacts?¶
- Create a test contact
- Use "Run Test" button if available
- Check execution history to see what would happen
- Use a test workflow (disabled for real contacts)
Can I trigger based on inactivity?¶
Not directly. Instead, use a Schedule Trigger to check for inactive contacts periodically:
- Timer Trigger - Daily
- Google Sheets - get_rows from a list of accounts to review
- Loop through results
- Send re-engagement email
What happens if the workflow fails?¶
The system logs the error in execution history. The CRM event still occurred, but the workflow didn't complete. Consider:
- Adding error notification emails
- Implementing retry logic
- Monitoring execution history regularly
Can I prevent certain users from triggering workflows?¶
Yes, add an If task checking triggered_by:
Next Steps:
- Edit Client Task - Update contact data
- If Task - Add conditional logic
- Inbound Email - Trigger from incoming emails