In 1992, there was a little known new thing called the world wide web. By 1995, it was a "thing". Now, what exactly do those quotes do to the word "thing"? And what does this have to do with "entities"?  Queue my favorite programming joke.

Q: What are the two hardest problems in computer programming?

A: Naming things, garbage collection, and off-by-one calculations.

All of that joke is true, but it's the first problem that is the point of this blog post. Because "entity" is just a fancy word for "thing", i.e. coders have the same problem naming some "things" as everyone else does.

What is an Entity?

Just as in our vernacular usage, an "entity" is a "thing with something extra", and it's the "extra" that makes it an entity. To make it more concrete: lots of things can be entities, and in CiviCRM, all contacts, contributions, and events are entities. It's not to hard to think of a contact as a "thing", but in fact, a lot more things in CiviCRM are entities: even such abstract notions as relationships, memberships, and participants to an event. You might get carried away and guess that everything is an entity, and it's a reasonable guess, but not quite. For example, an option in a list of options is usually not an entity. You might also be getting confused at this stage about whether a specific contact is an entity or whether "Individuals" is an entity: the answer is that we use "Entity type" for "Individual", whereas a specific contact is an "entity" (of type "Individual").

Who Cares?

And here's why you should care, even if you're not a programmer. In CiviCRM, entities are a core part of the codebase, and that means that what you can do with one entity, you can often do with other entities. So understanding what is an entity, and what you can do with any entity, makes you a better user of CiviCRM.

Again, what is an entity?

If you look up the definition of entity on Wikipedia, there's a good chance you will be no further ahead than I was after reading it. Because "entities" aren't a specific thing, they are an abstraction. Just like our vernacular use of "thing", a thing becomse a "thing" when it acquires special properties, and those special properties allow us to treat them with a very useful level of abstraction that doesn't need to worry about other details. And now you know why parents often haven't a clue what their children are talking about.

For example, when the web became a "thing", we no longer had to explain what it was, it was a self-explanatory word. Analogously, an entity is a "thing" with certain properties that allows us write code about it without knowing the specifics of the entity - the entity is self-explanatory enough that we can handle it in an abstract manner.

Again, why should I care?

The best I can do is to provide some examples. Here are three that illustrate the power of the entity in civicrm.

1. Custom Fields

You probably know that you can add custom fields to contacts via the web interface in CiviCRM. But that same code works for any entity. So you can add custom fields to things like Relationships, or Recurring Contributions, or ... a surprising number of things you might not even be able to imagine uses for. Go ahead and look at the form where you add a new custom fieldset, and you'll see a long list of things that you can apply it to: those are CiviCRM's entities.

2. CSV entity importer 

Eileen's excellent extension allows you to import data into your civicrm for anything that is an entity. So for your highly customized CiviCRM for which you had to add all kinds of custom fields, you can import that content from your old CRM without even writing any custom code. My example of this, and why I'm such a big fan of this extension, was when our clients needed to import recurring contribution data from their old CRM.

3. The API and browser

CiviCRM has an API that leverages the properties of underlying entities. That means if your site has some kind of custom entity, it's automatically exposed via the API and the API browser, even if you didn't know about it, and even though that code was written before you invented your entity.

3. CiviCRM Entity in Drupal

The Drupal module "CiviCRM Entity" exposes CiviCRM's entities as Drupal entities. Drupal has it's own concept of entity, and it's compatible in concept to a CiviCRM entity. So this module provides some magic glue function allowing all of CiviCRM's entities to also be Drupal entities. And that means you get (for example), Drupal Views of any CiviCRM entity.

But we're still stuck with the hardest problems, including naming things. And off-by-one calculations.

ToolsAPIArchitectureDocumentationDrupalDrupal 8ExtensionsTips