Provides tokens for any related contact, for all available contact tokens. E.g., to get the spouse's first name, or parent's marriage date.
Upon installation, this extension will create a custom field, Generate tokens for this relationship type, on each relationship type (see screenshot):
This field defaults to Yes; set this field to No on any relationship types for which you don't want this extension to provide tokens.
- This extension will add to CiviCRM's list one token
for each existing contact token, for each enabled relationship type. For example,
on a site with relationship types "Spouse" and "Parent / Child", additional
"First Name" tokens will be added, like so:
- Related (Spouse)::First Name
- Related (Parent)::First Name
- Related (Child)::First Name
- Note that only one First Name token is added for the "Spouse" relationship type, whereas two are added for the "Parent / Child" relationship type. This is because "Spouse" relationships are reciprocal, where as "Parent / Child" relationships are directional. Reciprocal relationship types, such as "Partner" or "Sibling" are detected by virtue of having the same label for both contacts, and are treated in the same way.
- Use these tokens as any other token. From the above example, the tokens will
provide the following values:
- Related (Spouse)::First Name: first name of spouse
- Related (Parent)::First Name: first name of parent
- Related (Child)::First Name: first name of child
- If the contact has more than one relationship of the given type, the relationship with the highest internal ID (typically the one most recently created) is used.
Whereas "Related Tokens" adds all available tokens -- including all custom fields and other fields, as explained above -- for each relationship type, the "CiviToken" extension adds only 6 tokens (Display Name, First Name, Last Name, Phone, Email, Contact ID) for each relationship type, along with a variety of other customized tokens not derived from relationships.
- Token strings are built from the values of
civicrm_relationship_type.name_a_bandcivicrm_relationship_type.name_b_a. These values are normally fairly stable, and this approach aims to avoid problems in dev/stage/prod environments where relationship type IDs could differ from system to system.
This extension could be improved in many ways; here are some I've thought of but not yet implemented:
- Provide more control or better defaults for what happens when a contact has more than one relationship of a given type. For example, many contacts may have more than one "Parent/Child", and the Related (Child)::First Name token obviously falls short here; at present it will use the relationship with the highest internal ID (typically the one most recently created), but it could be more desirable in various situations to use the one with the newest start date, or to concatenate them all into a comma-separated string, or any number of other things.
- Perhaps there are other tokens that should be supported as well; suggestions are welcome.
Joinery provides services for CiviCRM including custom extension development, training, data migrations, and more. We aim to keep this extension in good working order, and will do our best to respond appropriately to issues reported on its github issue queue. In addition, if you require urgent or highly customized improvements to this extension, we may suggest conducting a fee-based project under our standard commercial terms. In any case, the place to start is the github issue queue -- let us hear what you need and we'll be glad to help however we can.
And, if you need help with any other aspect of CiviCRM -- from hosting to custom development to strategic consultation and more -- please contact us directly via https://joineryhq.com