Entities, pointers and groups as implemented in Tendenci

ENTITIES OVERVIEW  #DRAFT

Note - Entities in Tendenci are not strictly implemented using the EAV model but are very close. The only major changes are 1) they have parent entities (pointer model) and they parallel loosely coupled with groups for organizational purposes.

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.

Using the demo site as an example (login admin/admin just remember it resets every hour) the URLs are:

Entities: https://demo.tendenci.com/admin/entities/entity/?o=1.2

Groups: https://demo.tendenci.com/admin/user_groups/group/?o=1.4 

EAV model on wikipedia: https://en.wikipedia.org/wiki/Entity%E2%80%93attribute%E2%80%93value_model 

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.

ONE-OFFS

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 18:45

- See more at: https://www.tendenci.com/forums/c/support/build-your-tendenci-site/how-to-set-up-entities-on-your-site/?page=1#post-728