CRM

The CRM holds the businesses and bodies a destination deals with (organisations) and the people it deals with (people). A person is linked to an organisation as one of its contacts, with a job title and a partner role. Everything partner-facing in engine-dmo is built on these records: memberships are an organisation’s, portal accounts are a person’s, listings belong to an organisation, and reports and broadcasts go to contacts.

CRM records are not documents: they are not localised, have no revisions and no publish state, and never appear on the public site. Staff work with them in the admin under CRM, and through the commands below.

OrganisationsCopy Anchor Link

An organisation also carries its memberships (one per site, see Partners and the portal), its contacts, its tags, its timeline and the documents it owns.

Create one from the command line, for example in a script that sets up a project:

engine-dmo crm organisation create '{"name": "Hook Norton Brewery", "status": "active", "email": "tours@hooknorton.example", "website": "https://www.hooknorton.example"}'

--data - reads the JSON object from standard input. Unknown keys are refused. The keys are name, legal_name, status, email, website, address, phone, social, hours, custom, lat, lon and network (a network key).

PeopleCopy Anchor Link

Contacts: linking people to organisationsCopy Anchor Link

A contact is a person linked to an organisation. The link survives a change of job: when someone leaves, the link is ended rather than deleted. Each link has:

Staff add and edit contacts on the organisation’s page. A contact becomes a portal user by accepting an invitation, which staff send from the organisation’s page or with engine-dmo crm invite, or by an approved claim.

Custom fieldsCopy Anchor Link

Declare the extra fields of organisations and people in config/crm/organisation.yaml and config/crm/person.yaml, with the ordinary field grammar. The admin’s record pages show them in their own group, smart lists filter on them, the import maps columns to them, and portal actions can let members fill them in.

fields:
  - name: coachParking
    type: boolean
    label: { en-GB: Coach parking }
  - name: preferredContactTime
    type: select
    label: { en-GB: Preferred contact time }
    options:
      - { value: morning }
      - { value: afternoon }

fields:
  - name: dietaryNeeds
    type: text
    personal: true
    label: { en-GB: Dietary needs }

Run engine-dmo check --fix to write the ids, then schema plan and schema apply. engine-dmo dev field add organisation coachParking --type boolean does the same in one step.

Values are stored by field id (a select’s by option id), so renaming a field or an option moves nothing.

engine-dmo config schema --file crm prints the file’s JSON Schema.

The timelineCopy Anchor Link

Every organisation and person has a timeline in the admin: entries the engine records about the record (for example a message the business sent the team from the portal, or a report digest that could not be delivered because the contact’s address is suppressed) and staff notes. A note has a body with mentions, can be pinned, and is either internal (staff only, the default) or member_visible, in which case the organisation’s people see it in the portal and the member API’s activity feed. Mentions notify the staff mentioned.

TagsCopy Anchor Link

Organisations, people and documents share the install’s tag vocabulary (config/tags/vocabulary.yaml, loaded once by engine-dmo tags import and then owned by the admin). Staff with crm.tag.manage tag records on their pages. See engine-dmo tags for the vocabulary, candidates and the tags commands.

Smart lists of organisations and peopleCopy Anchor Link

A smart list is a saved query that keeps itself up to date. Lists of documents are a core feature (see smartList() and engine-dmo lists); engine-dmo adds lists whose subject is organisation or person. They are used as working lists in the admin, as a broadcast’s audience, and from the command line. They are never public: public: true is refused for them.

Seed lists live in config/tags/smartlists.yaml, which the seed and engine-dmo tags import load once; after that the admin owns them.

smart_lists:
  - key: renewal-risk-90
    name: { en-GB: "Renewals due, low engagement" }
    subject: organisation
    query:
      membership: { status: [active], renews_within_days: 90 }
      analytics: { metric: portal_login, period: 180d, lt: 1 }
  - key: coach-friendly
    name: { en-GB: Coach friendly members }
    subject: organisation
    query:
      membership: { tier: [gold] }
      where:
        - { field: custom.coachParking, eq: true }

Query keys that apply to organisation and person lists:

membership keys:

A list has at most 50 clauses. Organisations and people are always read within the networks the list’s site and its reader can see.

All three need the database. engine-dmo check does not read config/tags/smartlists.yaml at all, so a seeded list cannot be verified without one: after engine-dmo seed apply (or tags import), run engine-dmo lists check against the database to find a bad key, field or tier.

BroadcastsCopy Anchor Link

A broadcast is a message from staff to the contacts a smart list of organisations or people names, such as every member renewing this quarter. It is sent as marketing mail: a person receives it only with recorded marketing consent, and every message carries an unsubscribe link that cannot be removed.

Staff need broadcast.draft on the site to compose one and broadcast.send to schedule, send or cancel it. The admin’s Broadcasts screen (under Members) shows, before anything is sent, how many people the list reaches and how many it leaves out and why.

Who receives itCopy Anchor Link

The recipients are taken in one step when sending starts. A person the list names is left out, and counted against the reason, when they:

An address shared by two recipients receives the message once.

Writing oneCopy Anchor Link

The body is Markdown (the public site’s safe subset) or Portable Text. Merge fields are written {{ person.given_name }} and filled in as text, never as markup:

A merge field outside this list is refused. Links in the body go through the first-party redirect /_b/c/, so clicks are counted; the unsubscribe link is /_b/u/; and an open is recorded through /_b/o/ only when mail.broadcast.open_tracking is on. The message is rendered with the emails/broadcast.html template, which a project can override in its template root (engine-dmo mail templates shows which file is used).

From the command line, a draft is a YAML or JSON file:

subject: Your membership renews soon
preheader: Three things to check before it does
format: markdown
list: renewal-risk-90
body: |
  Hello {{ person.given_name }},

  {{ organisation.name }}'s {{ membership.tier }} membership renews on {{ membership.renews_on }}.

engine-dmo broadcast draft --file renewals.yaml --site main
engine-dmo broadcast show --id <id>
engine-dmo broadcast test-send --id <id> --to you@example.org
engine-dmo broadcast schedule --id <id> --at 2026-12-01T09:00 --confirm

format is markdown (the default) or portabletext, whose body is the blocks as a value or a JSON string. list names a smart list by key or id. draft --id <id> updates that draft.

A broadcast’s statuses are draft, scheduled, sending, sent and cancelled.

Sending settingsCopy Anchor Link

Mail delivery itself (the driver, the sender, bounces and the suppression list) is configured under mail:; see Mail.

Importing organisations, people and membershipsCopy Anchor Link

The import reads a CSV or XLSX file through a column mapping, matches each row against the records already held, plans every row as a dry run, and writes through the same rules as the admin. Staff with crm.import run it from the admin’s Imports screen (under Members), which saves each source’s mapping so the next file from it maps itself, or from the command line:

engine-dmo crm import --source chamber-2026 --name "Chamber of commerce list" --file members.csv --map mapping.yaml --dry-run
engine-dmo crm import --source chamber-2026 --file members.csv

columns:
  Business: organisation.name
  "Trading email": organisation.email
  Postcode: organisation.address.postal_code
  Contact: person.display_name
  "Contact email": person.email
  "Opted in": person.marketing_consent
  Level: membership.tier
  "Renewal date": membership.renews_on
match: [external_id, email, name_postcode]
country: GB
date_order: dmy
site: main
currency: GBP
consent:
  basis: consent
  evidence: The opt-in box on the 2025 membership renewal form

Targets:

--source names the source by key and creates it when new (--name and --network set a new source’s name and network). --map is saved on the source for its next file. --dry-run prints what would be created, updated, skipped and rejected, and writes nothing.

Duplicates, merging and the trashCopy Anchor Link

CommandsCopy Anchor Link

Every one needs the database, and every one accepts --json. Run engine-dmo crm <command> --help for the details.

PermissionsCopy Anchor Link

The built-in partnership-manager role holds the CRM permissions apart from delete and purge; administrator holds them apart from purge. See What engine-dmo adds.