Our offices will be closed Monday, May 28 in honor of Memorial Day
as we recognize and remember the sacrifice of those who lost their lives while serving in the United States Armed Forces.
With unending gratitude - Tendenci


How to set up entities on your site

Register or login to post to the forum.
10 Feb, 2016 15:35

A Tendenci user was inquiring about entities so starting this thread to get the conversation going.

Edited 10 Feb, 2016 16:29
10 Feb, 2016 16:28

I have a basic level of understanding so please chime in if you have corrections or additions to the below.

Entities and Groups are ways to create clusters on your website.

Entities are related to the business logic of your site.

Groups (subclass of entities) are related to user permissions and outgoing communications

To Edit Entities on Your Site:

Edit entities via the admin backend or via direct link at www.example.com/admin/entities/entity/.

Edit groups via set up on the admin backend of via www.example.com/admin/user_groups/group/

Identifying your groups and entities

To identify what entities and groups to set up on your Tendenci site you'll want to ask yourself the following questions:

Groups: Which clusters of users need to have specialized site permissions? Which clusters of users will I want to send communication to?

Entities: Which clusters are driving in revenue that I would want to examine for reporting and analysis? Which cluster would I want to track for general reporting?

Python website resource on entities: https://pypi.python.org/pypi/django-entity

Edited 10 Feb, 2016 16:36
11 Feb, 2016 10:42

Quoting below description sent to me by user eschipul on groups and entity. (Minor formatting changes by bleven)


EAV, Entities and User Groups in Tendenci


Entities are pointers and used to take a snapshot of a transaction at the time it occurred. This is for financial reporting primarily.

Usergroups are more amorphous and used to organize people within an association or online community for things like special interest groups, newsletters, notification opt-in or opt-out, etc.

Factors and Uses of Usergroups

Opt-In or Opt-Out Users can typically control if they choose to join a group or not. They can unsubscribe from a committee's notifications for example. Or join a group that receives notifications of new job listings, and logically they might unsubscribe from that group once they obtained employment.

Filtering more efficiently than tags Usergroups are for organizing data and are much faster than tags. So you can filter|usergroup=1 on the right hand column of a template for example. Searching for a pk id is faster than searching for indexed tags and works immediately as opposed to waiting for the next chron job to index the content.

Relationship to Entities usergroups are required to be tied to an entity, although technically a site can have one and only one top level entity of 1 which is the site name. a more typical setup is shown below.

Technically from a computer science perspective Entities are just pointers that follow the EAV design pattern. Usergroups then are tied to entities.

Examples of entities and groups on a site

A super simple site would be: Entities - www.example.com/admin/entities/entity/ 1) The Association - (entity 1, parent entity 0)

Groups - www.example.com/admin/user_groups/group/ 1) The Association (group 1, entity 1, type REPORTING)

A more realistic organization would look like this:

Entities - www.example.com/admin/entities/entity/

  1. The Association (entity 1, parent entity 0)
  2. Committees (entity 2, parent entity 1, type REPORTING)
  3. Membership committee (entity 3, parent entity 2, type COMMITTEE)
  4. Gala committee (entity 4, parent entity 2, type COMMITTEE)
  5. Meetups (entity 5, parent entity 1, type REPORTING)
  6. Netsquared (entity 6, parent entity 5, type STUDYGROUP)
  7. Startups (entity 7, parent entity 5, type STUDYGROUP)
  8. Certifications (entity 8, parent entity 1, type REPORTING)
  9. Six Sigma Brown Belt (entity 9, parent entity 8, type CERTIFICATION)
  10. Six Sigma Black Belt (entity 10, parent entity 8, type CERTIFICATION)
  11. CPR Certified (entity 11, parent entity 8, type CERTIFICATION)

In this scenario, because a person can join or leave a usergroup mid year, you need a constant to track invoices which is what entities are for.

It answers questions like "How much income did our Study Groups bring in last year?"

You can't use usergroups for that.

The reason is if someone left the usergroup in November that studygroups budget for the following year would be based off of incorrect data. The invoices reports are tied to entities so suddenly all of those invoices (if it were allowed) would be credited to the parent association instead of a child entity of the parent association.

For many clients who do high dollar sales, how to allocate 1M in budgets to the various committees, study groups and scholarship committees, becomes a really big deal.

You have to know that the "Golf Committee" brought in 200k for the scholarship fund, but they will need a 50k budget in the first quarter to make a down payment for the golf course to reserve it for a tournament in the third quarter.

So why not just use entities and skip requiring usergroups?

Because we still need flexibility. Usually usergroups are usually tied one to one with entities that relate. Some organizations just make the top entity the same regardless if they aren't worried about allocating funds or do it through a different system.

A typical organization, again using the example above this would look like something like this:

Groups - www.example.com/admin/user_groups/group/

  1. The Association (group 1, entity 1)
  2. Membership Committee (group 3, entity 3)
  3. Gala Committee (group 3, entity 4)
  4. Netsquared (group 4, entity 6) (note entity skipped 1 because we don't need group for a reporting entity)
  5. Startup Activists (group 5, entity 7)
  6. Six Sigma Brown Belt Champs (group 6, entity 9)
  7. Sigma Black Belt Rock Stars! (group 7, entity 10)
  8. Safety Team (group 8, entity 11)
  9. Newsletters Weekly (group 9, entity 1)
  10. Job Notifications (group 10, entity 1)
  11. SECRET Anonymous Committee (group 11, entity 1)

Take the "SECRET Anonymous" group. They don't consider themselves a committee and don't want to be reported as such (human issue, not software). So they just go under the parent entity 1 by choice. Remember, these are humans and the software should bend to their needs while subtly not letting you break reporting needed by the AE or CEO.

Note a few things about this.

  • First the group name doesn't need to correlate with the entity name.
  • Second there are no groups for the reporting entities, they are just used to organize entities
  • Third there are numerous groups that might all be under one entity as they are simply to organize data.
  • Fourth the system accommodates clients who just have one entity and one group, but those are rare. Usually they at least have a generic group and a newsletter group.
  • Fifth given the importance of reporting when it comes to the distribution of funds and the budget, it lets people unsubscribe from the newsletter but still properly allocates invoices to the committee that hosted the event.


We can't quite accommodate everything.

Joint events cohosted by two committees. The pointer model doesn't support this so sometimes a client will make a special group called "Committee A and Committee B Special Events" and put it under the reporting entity COMMITTEES and make an adjustment in their accounting system.

So it isn't a perfect system, but it is WAY faster when it comes to displaying filtered data on a web site, handles the flexibility of letting people leave or join a group whenever they want (if the client has it set up that way in global settings) and still keeps track of the money.

The structure has been in place since 2001 so it really has stood the test of time. There are other one-offs that have come up but they are extremely rare and I can tell you how we handle those for the larger associations on Tendenci (over 100k users on one site for example."

-Ed Schipul

Edited 11 Feb, 2016 10:45