Thursday, May 14, 2009 - 08:33
Written by
The current way to track Households (HH) in CiviCRM is not easy. Over the last few weeks DharmaTech has been brainstorming how to better manage HH's and we had a chance at the CiviCRM developer camp to bounce ideas off of the core team as well as other developers in the community which was really helpful. What follows are our ideas to start the discussion.
Here's a simple scenario to illustrate some of the current issues with managing households: ABC Organization wants to track and outreach (email and snail mail) to a husband and wife that are both active with the organization. To do this in CiviCRM, you must create 3 records: a HH record and 2 individual records each with a relationship to that HH record and each using the HH's address.  On the face of it, that isn't a big deal - until you begin to outreach to these people.  With three records you have to be very careful how you snail mail the household and in many cases you have to use different workflows because, without care, they can easily receive three snail mailings. Also, it is difficult to track money coming from a HH without a custom report that can aggregate contributions from all members of a HH.
Now let's say you just want to have one HH record without individuals related to it for simplicity. Once you begin to accept online donations or event registrations from the HH's members, new individuals are created forcing you to either manually move data from the individual to the HH record or create relationships between the individuals and HH's.  Thereby leading to the same problems noted above. 
Because it is always an individual that performs actions (attends events, donates, receives emails, volunteers, etc.) we are proposing some improvements for how to manage households within CiviCRM that involve not using the HH contact type. The goal of this proposal is to streamline the various workflows that fall under HH management as well as improve the greeting & salutation features of CiviCRM.

Greetings and Salutations

We are proposing that we eliminate the current "greeting type" core field. It does not work and, even if it did, it is confusing since the customized greeting option allows you to enter an actual greeting whereas the other default options are greeting types.
Instead, we propose two new and separate greeting fields: postal greeting and email greeting. Each of these fields would default to first name. Two greetings you ask? Here's why: say there is a HH with two active people. Let's call them George and Jane Jetson. They have their own individual records in the database (no HH record) and unique email addresses. For CiviMail, you want to greet them individually with "Dear Jane" & "Dear George" respectively, but for postal mail purposes, you want to greet them as a couple i.e. "Dear Jane and George." Two greetings allows you to do this.  Here's how: mark George's record as do not mail and in Jane's record, enter "Jane and George" for her postal greeting. Jane will receive the snail mailing and when she does, the snail mailing letter will say "Dear Jane and George" because the organization will always mail merge off of that field. These fields also work for regular individuals since you may want to include a special greeting for some individuals like "The Honorable Tony Guzman." And it works in the still common scenario where two people share the same email address. In that case, for George, you would also mark him as do not email but in Jane's email greeting field you would enter "Jane and George." If your use case requires that each member of a HH receives their own individual mailing, then you don't have to do anything to George's record.


Addressee is what will appear on the actual mailing label/envelope address block.  We propose to create a core addressee field that defaults to first & last name. Similar to greeting, the addressee could be used to cover both members of a HH but work fine for all individuals as well.  There would only be one workflow here because the organization would create the mailing label merging off of the addressee field.
To summarize, we propose adding:
  • Core fields for individuals called email greeting and postal greeting. They should default to first name since for most people that is adequate.
  • A token for CiviMail called something like {contact.greeting} that would merge the email greeting field.
  • A core addressee field that would default to first and last name.
  • An addressee token to be used for mailing labels called something like {contact.addressee}

Shared Addresses

We are proposing that the "use HH address" functionality is extended to cover all contacts - individuals, HH, and organizations. Clearly this isn't trivial so this may be a phase 2 item but this would allow organizations to ensure that two records have the same exact address. The scenario here is that you first add Jane Jetson as an individual then next enter George. It would simplify things if under George, you can have him "share" an address with Jane just like it is currently done with "use HH address." So when/if you change Jane's address, it would update in George's record as well.  This would help with other scenarios where, for example, individuals want to share an address with their employer and also increases usability since the field would just be called "share address with."

Tracking Contributions

The new soft-credit feature in 2.2 solves a lot of the issues in tracking money coming from an entire HH. When Jane gives, you can provide a soft-credit to George and see that in his record. Search options that will be needed in the future include the ability to exclude those with soft-credits from a search so you don't appeal to them if they just gave/supported via soft credit and an option to find all those with soft-credits.

HH Contact Type

Now for the most radical part. :) We are proposing the HH contact type be made optional through the interface. If the HH contact type is not enabled by the admin, then all the references to the HH contact type are hidden (under find contacts/adv. search, CiviCRM menus, etc.)
We would actually be fine with eliminating the HH contact type altogether! We can't think of any use cases where a HH contact type is useful but I have heard that it is useful for some organizations.  This should definitely be up for discussion.


We really believe these changes to core will greatly benefit organizations that need to manage a large number of HH's but maintain a simplified and consistent workflow. It may not be perfect but, with these changes, an organization can better avoid duplicate mailings, greet their supporters appropriately in different contexts, and know how much money is coming from a certain HH.

If you have any comments, big or small, please leave them below. Thanks!
-- Tony Guzman, DharmaTech
Filed under


Good work Tony - not sure I yet agree with all the options but it would be great to find a more thorough solution for this. The areas we have had issues with is when an individual registers or donates - and they are using a shared household address - then there is no easy route for them to know that they are using a Household Address, so if they update their address, there is not way that I know of, to have them presented with a 'your address is a shared address with the following people' - so that any updates can either be applied to them individually, or to the household.

And I agree that any schema change should aim to having the same logic applied to when a person wants to have their 'work address' used as their 'shared address' - though not sure what happens when you have one individual in a household specifying their work address, and the other specifying a shared household with the other individual (cross eyed emoticon).

And what about if one person at HH is already in database, and other then signs up via donate or whatever, and fills in their address - would be damn handy if a 'this address already exists, do you want to receive shared postal communications' (i guess privacy issues stop us exposing the name of the other people at same address - after all the address may be in system for someone who has since moved - life just gets complicated sometimes!)

Good points on the shared address issue. I agree there is a lot to work through with how to handle it and probably should be a "phase 2" item with this proposal. Nevertheless, I really believe the phase I changes will greatly improve the HH issue. From our perspective, eliminating or at least not using the HH contact type is a good first step.

How do you propose dealing with the situation where there are children and parents in the system? Depending on the age of the kid, I may want to communicate just with the parents ( such as a 4 or 5 year old), but other times I will be directly dealing with the kid ( such as a 14 year old). So if I want to send a postal mail or email to all the parents of the kindergartners, I want the message to be "Dear George and Jane, your boy Elroy is going to graduate from kindergarten on June 5 at 11 am. We look forward to seeing you there for this special occasion."

There are also the issues that arise with divorced parents. Lets pretend George and Jane Jetson are divorced and both are remarried. Jane's new name is Jane Jetson-Jones. They have shared custody of the kids, Elroy and Judy. So now I need to send 2 messages for 1 kid:

"Dear Jane, your boy Elroy is going to graduate from kindergarten on June 5. We look forward to seeing you there. "


"Dear George, your boy Elroy is going to graduate from kindergarten on June 5. We look forward to seeing you there. "

I currently handle this situation by making the kids members of 2 households and sending messages to both households. Even with the current version of CiviCRM, this requires writing custom searches/reports.

Let me preface by clarifying that our clients are mostly grassroots community organizing groups so tracking children and their parents doesn't come up for us. This is why i admit there may be use cases where using the HH contact type is useful. I think we can agree that, at the end of the day, all we're trying to accomplish is communicating to our constituents in an appropriate way in different contexts. And in a way that requires as few workflows as possible. So the first step with our proposal is improving the way CiviCRM handles greetings to set the foundation for a more logical HH management system. That being said, I still don't think you need to use the HH contact type. You're working with individuals (children & parents). Elroy (individual record) can have a "child of" relationship with Jane (individual record) and another one with George (individual record). Sometimes you're outreaching to both Jane and George together (make the postal greeting include both people like in my example) and sometimes you are greeting George & Jane individually (if they have divorced) and sometimes you are communicating directly with Elroy. Our proposal can handle that but the issue, i admit, is the reporting of this data. But I just don't see what role the HH contact type plays in all of this. With the exception of organizations, nonprofits always communicate and interact with people. So if we improve greetings and reporting, we will soon be able to make the HH contact type obsolete.

The household is the nearest thing Civi has to a team.

For us a team is a number of people who meet. The fact that they are meeting together is a way in which our organisational goals are realised.

Groups don't cut it as you can't add custom data to a relationship. We use custom data to add quality information about these relationships, which are quite important to us.

I would hate to see households removed, unless (say) a Group becomes more like a Team (relationships rather than 'in group' markers).

(Now this next remark is way off topic - can we call Groups something more like "channels" - the term "group" suggests people getting together, while "channel" is more suggestive of the information-stream idea that Groups implement)


Hi Ken. Out of curiosity, why don't you use organizations to represent teams? What does the HH contact type do that organizations do not? Is it the shared address issue? If so, part of my proposal is to extend the shared address functionality to organizational records as well (as Peter points out, there are issues to work out though).

Organizations can have relationships with individuals, custom data, activities, and more. Also, relationships can have custom fields that are searchable and can apply to all or specific relationship types. Groups can also have custom fields.. Will that help you in your use cases?


We have "translated" HH into 'entity', and we use it when you have more complex relationship than the single "belong to" for the group.

Eg you can belong to a committee/team, but you need to track who's the president, who are the full members or associate members...

We probably wouldn't need it if member relationship could be typed, but that's the best we've found so far.


These are definitely huge improvements over the existing interface, but there are two things that come to mind.

1) Eliminating households outright is bound to cause trouble. There are a number of organizations that use them for a variety of reasons. Snail mail is probably the best reason, but there are others.

2) Aside from these issues, the biggest problem between these too is how tedious it is to add people to a household. It's easy to add people, but the current interface requires too many clicks per contact addition. You have to use the lookup field which selects the right contact and then search. Then you have to select the exact same contact you selected out of the first list to add in. But what if you want to add that contact and his five brothers that all show up in the list when you do that search? That's not currently possible. You have to add them one by one.

If you could improve these things that you've suggested here AND clean up the add-to-household functionality so that it allows you to easily add multiple contacts to a household, I think that would mostly solve this.

Thanks for all of your initiative with this.

Thanks Vrazer. I agree that eliminating the HH contact type outright would create major headaches for those already using them which is why we (DharmaTech) propose it first be made optional.

As far as adding contacts to HH's, I also agree it's a hassle. It should probably work something like adding an activity where you can add multiple contacts to an activity under "With Contact." Not sure how difficult that would be to implement, though.


Just want to add a couple of items:

We decided to create households to 1. avoid sending duplicate snail mail, and 2. to avoid having to enter one address update in multiple contacts. The recent addition of a "merge same address" check box to the mailing label setup resolves the first issue but not the second. The proposal here to have a "use same address as" option would take care of the second issue. Together they would allow us to abandon use of household records, which would be a time saver.

However, I hope you think about a transition path for those of us with an investment in household records. A routine which converts "use household address" to "use same address as" pointing to another household member would be ideal. Thanks!

so this makes some sense.
Though I see the need for it in some of the workflows stated above.
It makes sense that this is an optional part of civicrm.

Seems to if someone could write a script to related HH info back to a head of household the transition would be less difficult.


I had another idea that would simplify use of soft-credits. When creating/editing a relationship, have a check-box labeled "This relationship allows each side to get a soft-credit from donations made by the other side." ( ie if A donates, B gets a soft credit. If B donates, A gets a soft credit.)

That way I can check this box for the "spouse" relationship and then any donations made by George Jetson are automatically soft-credited to Jane, and vice versa. Or I can use this feature for any relationship that makes sense for my organization.

That is a great idea! It would definitely simplify things and is very logical from the end-user perspective. I like it! It may be a phase 2 feature since it may be pretty difficult to implement but I'll keep it on the radar.


I think some of these changes look great. Thanks for putting all this thought into them!

What comes up for me when I read about your proposal is whether address-sharing is a relationship type (and could be added and administered that way) or whether it's a property of certain relationships. If it's a property, then it makes sense to just put it as a field on the relationship record. Then, when you add any relationship, you could say whether to use address data from the other end of the relationship. We'd have to think carefully about the implications of bidirectionality on this, but I think it might be the cleanest way to implement this.

What are your thoughts on the joint greetings approach ( and code ) described at:

An implementation that follows some elements of this new model available here:,11265.0.html

I really like this thread - it seems we are getting toward the essence of what a household is. A few other little improvements that will no doubt become acheivable soon.

As an aside, I'd like to apply a similar train of thought to organisations at some point also.


Has anything changed on this issue in the 3.2 release or does this post remain a pretty accurate accounting of how things are right now? Either way, are there any updates/new thoughts on how to handle this? Thanks for any update!

No major changes to this in 3.2. The forums are a better place to continue this discussion