ProPeace/contactcats
6
0
Fork 0
mirror of https://codeberg.org/artfulrobot/contactcats.git synced 2025-06-25 18:28:05 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
contactcats/README.md
Rich Lott / Artful Robot d4f02e388a Update README, add screenshots
2025-04-02 11:43:15 +01:00

7.3 KiB
Raw Blame History

Contact Categories

This is an extension for CiviCRM, licensed under AGPL-3.0.

It provides a way to categorise contacts by priority group; a contact only ever has one category, which is the most important one that applies.

How categories are defined will depend on your organisation's needs. A real world example of categories:

  1. VIPs (manually curated)
  2. "Buzzing" - people who recently gave a one-off, started giving regularly, or increased their regular giving
  3. "Amazing" - high value regular donors
  4. "Loyal" - other regular donors
  5. "Cooling" - people who recently cancelled regular giving
  6. "Interested" - donated within last 3 months.
  7. "Missed" 2+ donations over 3 months ago.
  8. "Drifting" gave once over 3 months ago.
  9. "Active" never given money, but done some other action recently.
  10. "Dormant" never given money and not done anything else for a while.
  11. "Unreachable" others, typically without consent for marketing/emails.

A contact gets placed in to the first of these that they match. They only get one category. When people change category, the change is logged as an activity. Categories are updated nightly, so they remain stable during one day.

Each category is defined by a saved search - so you have complete control over how you categorise people.

As well as giving you the opportunity for oversight metrics, this makes it really simple to do segmented mailings, without risk of overlap.

Example useful things you can do with this approach:

  • avoid asking for money too soon after it's been given!
  • contact all regulars (Amazing, Loyal) to ask for increased donations, notably excluding "buzzing" (would be rude) and "VIPs" (personal approach).
  • ask those who gave before to start regular giving etc.
  • send urgent actions to those most likely to respond urgently.
  • follow up cancelled regulars to see if they can be rescued.

Features:

Some of the screenshots use numeric codes for the category labels, but these could be your own labels (e.g. Amazing, Loyal...) if your organisation does not want to use the codes.

Search » Contacts By Category

Screenshot shows a page titled Contacts by Category. There's a selector for the Category, an Action button and a table listing contact name, type, category, email

This search form gives a quick way to select contacts in one or more categories either to browse, or to do bulk operations like starting a mailing.

Dashlet / Reports » Contact Category Counts

Screenshot shows title: Contact Category Counts. Shows a list of all categories and how many contacts are in each one. A table has two columns, Category and Count. A few sample rows are listed.

This report/dashlet gives you a top-level overview of your categories. The category icon/names are links that take you through to the Contacts by Category search page for that category.

Reports » Contact Category Flows

![Screenshot shows: Category Flows title. There's a start and end date field and a checkbox for "Show changes only" and a button named Calculate flows. There's a Sankey diagram which shows how many contacts moved between which categories between the two selected dates.]

This report allows you to inspect flows of contacts between categories between two given dates. Leaving the end date blank means use the current category.

There's a Show changes only checkbox. This may be useful to focus in on only the contacts who have changed category; e.g. if between two dates 1000 contacts have not changed category then it can be hard to see that 20 have changed when the diagram has to represent 1020 contacts.

Contacts » Categories set-up/configuration screen

screenshot: Contact Category Settings. Each contact is assigned the first category that matches, using the assignment order. When categories are listed, the presentation order is used. There are radio-button controls to switch between assignment and presentation order. Below are listed the categories in the selected order. There's a button to copy the order from the other order. Each category listed has an icon, a colour, a label and a description. They also have buttons: Edit, Delete, Move. A few sample categories are shown for things like: Multiple time major donors; Major donor: new; Regular donor: active etc.

This screen is where you define your categories, based on your SearchKit searches and/or groups.

Assignment order shows the categories in the order in which they will be evaluated per contact. If the first category matches for a contact, that is assigned. If not, the 2nd category is tested and assigned if possible etc.

Presentation order is purely cosmetic and has no baring on who gets what category. It's common for this to be the same as Assignment order, but there are times when you might want to present the list in a different order, e.g. if you wanted to identify all contacts without marketing consent first it might make the searches for the more interesting categories simpler and easier to manage, but when presenting them, this group is of less interest/value and you want to see it last.

Editing each category looks like this:

Screenshot shows form called Contact Category Settings. Fields are: Category label, Color, Icon, Description (example is: Multiple time major donors.), How are contacts identified (example shows SearchKit search), SearchKit Search (example has "ContactCategories Locus 3.5" selected). There's buttons for Cancel and Done.

  • The category label is the primary way the category is shown in most places. Keep it short. You might use codes like 3.x for major, 2.x for regular, 1.x for occasional donors; or words like Amazing, Loyal, Drifting...
  • Colour and icon: the icon is used commonly; colour a bit less so due to SearchKit limitations.
  • Description: explain in human terms what this does.
  • How are contacts identified? one of:
    • Search Kit search
    • Group
    • There's also a special 'default' one required, but you can't select that. It's used for the default category that gets applied if none of the others match.

Scheduled job: ContactCategory.sync

This job should be configured to run hourly, but it will only actually make a change daily after 3am (server timezone).

You could set it to run daily, but CiviCRM does not give you a choice of when it runs daily, and it is better that it runs outside of working hours so the catgories stay stable during the day when they might be being queried.

Getting Started

Once installed, you'll find a Contact » Categories page that lets you specify your prioritised SearchKit searches to identify your contacts. A scheduled job needs to run to do the categorisation, so wait a day for that or run it manually.

You can also use SearchKit/FormBuilder to summarise people by categories, e.g. counts.

Technical notes

This uses a settings keys to record unix timestamps as to when the last and previous assignment run happened.

  • contactcats_next_run
  • contactcats_last_run

It uses ContactCategoryDefinition entity to hold data about each configured category and ContactCategory entities join a Contact and a ContactCategoryDefinition.