Skip to content

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
  1. Create a new workflow
  2. Add a CRM Trigger as the first task
  3. Select the trigger type, then what it watches (the field, column, event or table)
  4. Save and switch the workflow on
  5. The workflow runs automatically when the event occurs

The CRM Trigger task opened to its settings: the trigger banner, Trigger Type set to Client Field Change and Target Field set to Client Status

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

The Custom Fields section of a client panel, with a count of 15, the pencil, Hide Empty, a search box and Add Field. The first fields are Property Type: Single-family home, Service Area: North Shore, Lead Source: Website Form, Maintenance Plan: None, Water Heater Age (yrs): 11 and Next Service Due: 2026-11-03

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.

Settings, Client Statuses: eight statuses from New Lead to Lost, each with a handle to drag it by, its ID, a preview of its coloured badge, a colour swatch and an on/off switch, and Add Status

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 up amount where method_code is card.
  • 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

CRM Trigger  (client created)
  └─ Email   send the welcome message to {{task_47001_company_name}}

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

CRM Trigger  (Contact Field Change)
  └─ Webhook Out   post the change to the other system

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_actioned is the person who made it; a change made by a workflow is recorded against the automation user. An If on user_actioned can 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:

  1. Check workflow toggle is ON
  2. Review trigger configuration and filters
  3. Test by manually performing the CRM action
  4. 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:

  1. Add more specific filters
  2. Check if workflow updates trigger additional events
  3. Use "Changed Field" filters
  4. Add processing flag to prevent duplicates

Missing Contact Data

Possible Causes:

  • Custom field not populated yet
  • Contact still being created when workflow runs

Solutions:

  1. Add small delay (5-10 seconds) after trigger
  2. Use If tasks to check if required fields exist
  3. 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:

  1. CRM Trigger - Client Created
  2. Delay - Wait 1 day
  3. Email - Send day 1 email
  4. Delay - Wait 2 days
  5. Email - Send day 3 email
  6. Delay - Wait 4 days
  7. Email - Send day 7 email

Conditional Multi-Path Workflows

Route based on contact properties:

  1. CRM Trigger - Client Field Change (Industry)
  2. If Task - Check industry
  3. Technology → Tech sales flow
  4. Healthcare → Healthcare sales flow
  5. Other → General flow

Lead Scoring Automation

Automatically update lead scores:

  1. CRM Trigger - Contact Field Change
  2. Code Task - Calculate lead score based on actions
  3. Edit Client - Update lead_score field
  4. If Task - If score >= 80
  5. 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?

  1. Create a test contact
  2. Use "Run Test" button if available
  3. Check execution history to see what would happen
  4. 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:

  1. Timer Trigger - Daily
  2. Google Sheets - get_rows from a list of accounts to review
  3. Loop through results
  4. 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:

Condition: {{task_47123_triggered_by}} is not "admin@yourcompany.com"

Next Steps: