CiviMail Multi-Org Support

This page describes how the new multi-org support proposal impacts CiviMail, especially w/ regards to token substitution.

U.S. PIRG Use Case

One of the most important features that U.S. PIRG needs in terms of multi-organization support is the ability for CiviMail to do token substitution based on attributes of the organization that owns the group(s) it's sending a mailing to. An example would be: Let's say I'm sending a mailing to the action alert subscribers of all our State PIRGs on the west coast. I would pick the following groups to include in the mailing:

1. CalPIRG action alert subscribers
2. OSPIRG action alert subscribers
3. WashPIRG action alert subscribers

In the mailing itself, I would want the from name, from address, group name, group mailing address, domain name in the link URLs (action links, opt-out, & unsubscribe links), header, and footer to all be tokenized and replaced as appropriate depending on which group a particular recipient belongs to (this should be optimized as much as possible rather than do substitutions on a per message basis--though that may not be that costly, will have to test). So if I'm on CalPIRG's list and I get the email, it should
be CalPIRG branded throughout. But my cousin in Oregon should get the same email from the same job, but with OSPIRG branding throughout.

Implementation ideas

This should be achievable by adding organization-specific tokens (and making CiviMail default to their use rather than asking for mailing-wide values as it currently does) and having those tokens reference the organization contact affiliated with the group that the mailing is being sent to. That last part is a little tricky, so I'll go into some more detail.

Knowing which organization contact to use

The "XXPIRG action alert subscribers" groups above (in the use case) are not the organization groups (in this proposed multi-org implementation, internal organizations are represented by groups paired with organization contacts, which I refer to as "organization groups" in this document), but merely children of them. Here's what that means:

1. CalPIRG action alert subscribers is a sub-group of CalPIRG and CalPIRG is the organization group (so it's affiliated w/ an organization contact that has all its attributes that token substitution should be grabbing)
2. (same for the other two groups, just substitute OSPIRG or WashPIRG for CalPIRG in the example)

So CiviMail needs to determine which organization contact to use for token substitution. It could just ascend the parent group relationships until it found an organization group, but since multi-parent group nesting relationships are allowed, it's possible that there will be more than one ancestor group that is an organization group. Most likely this won't happen often, but we need to either handle it gracefully or prevent it from occurring somehow (which may be bad because it would probably be useful to at least some folks out there trying to model complex organizational structures).

Implementation idea #1:

Same as the existing mailing job setup process, but in step 3 (after you pick the group(s) to send to), do the following:

1. For each group you're sending to, test each of these in order and present the simplest form that will accommodate the job
   1. Group is not an organization (and neither are any of its parents)
      1. current CiviMail job setup process
   2. Group is an organization or it's not and only one of its ancestors is an organization
      1. default to using organization tokens wherever possible, but allow user to override w/ job-wide hardcoded values
   3. Two or more groups in the hierarchy (including sending group itself and all ancestor groups) are organizations
      1. present a list of organizations and ask which one should be used for token substitution, allow job-wide overrides w/ hard-coded values
2. If a group is not selected in step 2 (i.e. you're sending based on which other mailing(s) people did/did not receive), then continue with the current job setup process

Implementation idea #2:

Instead of showing a list of every group in step 2, only show groups that are organizations (w/ a none option so you can still send email to groups that aren't part of an organization):

• Once the organization(s) to send to are selected, allow the selection of subgroups to include and exclude
  • perhaps via a dojo collapsable list widget?
• Default to doing token substitution based on the organization(s) you're sending to, but allow job-wide hard-coded overrides
  • How do you determine which organization to use in the event that a person is in the recipient list via affiliation w/ more than one organization?
    • Could provide a re-ordering list widget so you can set the priority the token substitution should use