CiviCRM Guide
From openmichigan
Note: The CiviCRM database is backed up daily at 4 am.
[edit]
User permissions
There are 3 levels of admin access: OERbit admin (non-CiviCRM related); Drupal CiviCRM admin; CiviCRM admin. All are connected to co-sign. Not all of us have all three admins. CiviCRM admin: Kevin, Bob, Piet, Emily, Dave, Kathleen. Dave will manage the CiviCRM permissions. If you want to add users, email Dave.
[edit]
Naming Convention: Organizations/Employers
The Organization should be the institution name, and not include any of the department names. For example, we would all be employees of “University of Michigan” not “University of Michigan Office of Enabling Technologies.”
When to Use: Groups
Pro: used for mailings, organizing imports, and synchronizing with Drupal’s organic groups module. There are also “smart groups” that can group data automatically based on set attributes (whatever term or condition you are searching for).
Con: Because groups are so versatile and used by so many features, there may be a lot of them.
Suggestions for managing groups:
1) If it’s a stable grouping that you think you’ll refer to often, consider using a custom field or a tag.
2) Each individual who creates a group based on a need is responsible for managing that group (i.e. deleting groups as necessary).
[edit]
Naming Convention: Groups
- Add “Mailing-” to front of groups to separate mailing groups from other groups
- Add “Project-” to front of project groups
- Add “Partner-” in front of existing networks, associations, or cross-organization initiatives
- Add “Event-” in front of mailing groups or organizing imports from an event
[edit]
When to Use: Tags
Pro: Prominent display of groupings both in contact record and in separate tab.
Con: Limited customization. Easy information overload -- if tags aren’t used sparingly they may be confusing and not be used at all.
Suggested use: tag with information that needs to be most prominently displayed like name of primary contact or name of project. Use for stable, broad affiliations across projects: making tags much more general use. Keep tags really broad: faculty, staff, students, Non-UM, UM, etc
[edit] When to Use: Households
Households: Use for temporal groupings within an organization due to affiliation with an event, a project, or an initiative on campus. Allows to show join date and end date, separate middle level distinct from organizations. It may be cross-departmental and cross-organizational. Similar to groups - only difference is start/end date and ability to add notes about role in household. e.g. Core OER, OER Policy groups, MERLOT, eTextbook Committee, dScribe cohorts.
- Household are similar to groups - Difference in use: If you look at a listing of potential mailing lists/groups overall, households don’t come up
- Households composed of loosely connected people by interest, an event, etc. (Usually people you wouldn’t contact all at the same time.)
- Household naming convention
Events: contacts-[Name of event]
Households are co-ops and projects are places people have a mortgage on. Less commitment to Households, projects are more committed. Projects are households that you would contact all at once.
See also: http://wiki.civicrm.org/confluence/display/CRMDOC40/Relationship+Types
[edit]
When to Use: Custom Fields for Individuals
Pro: Displayed inline in a record’s profile or in a tab. Can be customized to handle a large variety of data. Information from custom fields can be displayed by the Drupal Views Module or in CiviReport.
Con: Inline fields are usually displayed at the bottom. Custom tabs are usually displayed at the very right.
[edit]
When to Use Events (vs. Activities)
Events: For more formal events with large groups with agendas and/or invitations. Use for cross-institutions.
[edit]
When to Use: Custom Fields for Events (ADD)
??
Event Tags(s): Custom. Not searchable/exportable.
[edit]
How to Use: civiCRM Search (ADD)
Search via interface in civiCRM can be tricky: Not all possible auto-completions will immediately appear. [Need more info from search documentation..]
[[|Other rules may be created for other use cases/different things we want to match as duplicate...]]
[edit] How to Create civiCRM Relationships
You can create and edit relationship types at Administer > Option List > Relationship Types
(can also specify which sort of contact/org/whatever is either node A or node B of a binary relationship)
You can define a type of relationship as being between an individual and an organization, or org-org, indiv-indiv, etc.
If you define a relationship and then REdefine it under the same name (say, change a relationship from org-org to org-indiv), looking at views of one of the related individuals (say, the second organization in the pair) will show the second org as an individual (even if it is an organization), because civiCRM is looking up the current status of the relationship. Overall, better to create new relationships than to redefine old ones (and disable or delete old ones if necessary that they no longer be used).
[edit] How to Import Contacts
In the top menu, go to Contacts > Import Contacts.
Contacts can be imported from a .csv file. The first page after Import Contacts allows you to import a .csv data source and choose several options (which dedupe rule will be used for determining duplicates, whether there are column headings, etc).
Normally you would:
- check “First row contains column headers” (“First Name”, “Current Employer”, etc)
- choose “Update” for duplicate contacts (Important; otherwise if a duplicate is detected, only the information about that contact from this import will replace all previous information about the contact in civiCRM)
- Other options can generally be left alone
On the next screen, you will see “Merge Fields”, and examples of what will be imported (usually the information from the first two rows of the .csv). If a field appears to have the wrong information, you know something in the .csv must be altered. After importing, a message will be displayed explaining how many rows of the rows in the .csv file were successfully imported and how many encountered errors. (This includes blank lines in the .csv, so if you have 15 lines in the .csv, 5 of which are blank, it will say that 10 of 15 lines were imported, 5 had errors.)
For the fewest errors, it’s best to have the column headers precisely match the titles that civiCRM generates. The easiest way to find these is to do a test export (see below in this Guide). When you export, say, “First Name”, “Last Name”, “Display Name”, “Current Employer”, “Job Title”... (or whatever fields of information you wish to import) you will get a .csv file with column headings off which you can base a new .csv for importing.
If you want to import household membership, for example, a text export will help especially -- the header should be something like “Household Member of--Household Name”, and civiCRM is fairly picky about the naming of such columns.
If you wish to add all imported contacts to a group or multiple groups, that is done immediately after importing. You do not need to encode that information in the .csv file, although it’s easiest if you wish everyone in a single import to be in the same group(s). Otherwise, in order to put people in the groups you want, you’ll have to perform a new search.
When importing, it’s best to include as much of the first and last name as possible (individually, not just the “Display Name”), AND email, since those fields are what primarily determine contact duplicates.
[edit] How to Export Contacts
1. Perform a search (usually from Search > Advanced Search to ensure it’s accurate/what you want)
2. Select the radio button for all the records, or select the contact records you want and select “selected records only”
3. Choose “Export Contacts” from the drop-down menu near the top of the screen, just below the radio button you’ve clicked
4. Supposing you want to export specific information, choose “Select fields for export”
5. If you have a field mapping (a set of fields to export) that you’ve already saved under some name, you can choose it from the provided drop-down menu. Otherwise, Continue.
6. You’ll be presented with a list of drop-down menus. In each, you can choose Individual, Organization, or Household (contact type you’d like to export. Often all of these will be the same per import).
7. After choosing, another drop-down menu will appear on the right. That one is a list of all possible fields of information about that contact type (First Name, Last Name, Display Name, Current Employer, Job Title, Household memberships, Internal Contact ID...). Do the same for each information field you want to export.
8. Once you’ve chosen all the fields you want to export, hit “Export”, and you will automatically download a .csv file with the exported contact information.
[edit]
How to Export Events
Do a search for events. Follow process similar to exporting contacts:
https://civicrm.umms.med.umich.edu/civicrm/event/search?_qf_Search_display=true
[edit]
How to Browse All Households
Go to Search menu. Select Custom Search... Click Household Name and State. Leave Household name blank. Keep default of any state/province. Click Search.
[edit]
How to Detect Duplicates
Duplicate detection is managed under Administer > Administration Console > Find and Merge Duplicate Contacts (Dedupe Exceptions is where the list of similar contacts which are NOT duplicates are saved).
There, there is a list of Dedupe Rules -- rules which handle whether contacts are duplicates. When importing, you can choose which Dedupe Rule will handle whether the imported contacts are duplicates, but the default Dedupe Rule is the Strict_Individual rule.
Anyone with access to this page can edit any of the rules and/or add more.
Within a rule, you can choose the information fields for a given contact, length, and weight. “Length” is the length of that field which will be compared. For example, “First Name”, “7” for field and length means that if two contacts’ first names have 7 letters in common, the “Weight” score will be added to their total weight.
At the bottom, there is a box for “Weight Threshold to consider Contacts Matching”. If two contacts have a weight equal or greater to that, given the comparing of the information fields listed just above, those two contacts will be determined duplicates.
So far, it seems that Email, Last Name, and First Name are the best fields for these comparisons. Previously, we were comparing only email. That often worked, but did not handle gmail/umich or umich/med.umich differences.
Ideally, the strictest individual rule should handle people with the same last name and email differences (re: emails from different providers). The current strict individual rule seems to be working decently (03/05/2012) but edits may be needed/needed in future.
Other rules may be created for other use cases/different things we want to match as duplicate...
[edit] How to Merge Contacts
In order to use a Dedupe Rule, click “Use Rule” next to any rule on https://civicrm.umms.med.umich.edu/civicrm/contact/deduperules
and choose whether you want to run the rule on All Contacts in civiCRM or only a specific set of contacts (a given group).
You will then see a list of all potential duplicate contacts. (If it seems like there are six or so identical contacts, don’t worry -- that’s probably civiCRM matching the same contact to a lot of different ones.) Individually, you can click on the pair to see the their information side-by-side and choose whether to merge them.
When you merge, the default for most information fields is that they are ADDED, not overwritten (relationships, group memberships, etc). Except where noted! (Email, and name, for example, you must specify “add new” or else it will be overwritten.)
There is no clearly defined way (04/09/12) to merge two specific individuals/groups/contacts in civiCRM by specifying their unique IDs/profiles. The quickest way to merge is to run another search (as described above) for duplicate contacts and see if the two contacts you wish to merge appear in the possible duplicate list. If they do not, adjust the rule being used (or edit/change/use a different dedupe rule) and run another search until the desired contacts-to-merge appear in the potential duplicate contacts list. Then merge them as described above.
[Is there a way to specifically merge two contacts given specific profiles/IDs? Looking...]
If two contacts which appear on the potential duplicates list are NOT duplicates, you can mark them as a duplicate exception (by clicking mark exception on the screen where the contacts’ information is displayed side-by-side), and these contacts will no longer appear as a potential duplicate pair.
You can see these marked exceptions in Administer > Administration Console > Dedupe Exceptions.
[edit]
How to Use Events for RSVPs (ADD)
??
[edit] How to Populate Past Events (ADD)
Even if an event is in the past, in order to connect contacts who were in some participant roles (e.g. attendee or staff) is by registering the participants:
Manage Events > Event > Event Links > Register Participants
“Find Participants” works to find contacts who are already registered for an event.
Registering a participant sends a confirmation email to their email address per their primary email in civiCRM. To avoid this email being sent, as usual when the event is in the past and just now being captured in civiCRM, you must disable auto-notifications for event participants (see below).
[edit]
How to Disable auto-notifications for Event Participants
When adding participants to an event, you can turn off the auto-notification email by accessing Administer > civiMAIL > From email addresses. If open.michigan is crossed out, then it is turned off. This will generate an ugly error message, but the data will be saved, and an email will not be sent out to the added participant.
[edit]
How to Create a Mailing
1. Go to Mailings > New Mailing
2. Title the mailing. Select recipients and groups excluded from the receiving of the mailing, and click Next
3. Choose tracking/responding/visibility options and click Next
4. Compose mailing
- using syntax such as Dear {contact.first_name} will pull in the first name (from civiCRM record) of every contact to whom the mailing is sent
- this syntax can be used for any other pieces of info associated with a contact
5. Test mailing appearance (can see if the civicrm contact syntax worked as planned), and usually, send to a test mailing group
6. Send mailing, or save mailing for later sending
- Do mailings send duplicate emails to contacts within multiple groups? NO, and it lists “Intended Recipients” in the mailing so that you can double check it if you would like.
- N.B. Mailings only list the given recipient in the “to” field, not all recipients.
[edit] How to Restore a Deleted Contact
- From the top navigation, select Search > Advanced Search
- If the above doesn’t work:
a. Login as someone with admin rights
b. Go to https://civicrm.umms.med.umich.edu/admin/user/permissions
3. For administrator and civicrm_user, enable the checkboxes for “access deleted contacts”
4. Click the Save Permission button
5. Repeat the Advanced Search above
6. In the basic criteria section, enable the search option for Search in Trash (deleted contacts)
7. Add any other search criteria
8. Click the Search button
9. Select the Desired Contact
10. Click the Restore button
If you accidentally delete a contact who is also a user, and the user’s profile no longer matches their original contact (i.e. activities, relationships, etc. are wrong):
- Login as admin
- Restore contact as above
- Note the contact id (cid in URL) of the original contact file and the new one
- Go to mysql table manager
- Make backup copy of the civicrm_email table
- In the civicrm_email table, go to the row for the specified user. Update the contact_id from the new id to the old one.
[edit] Lingering Questions/Action Items
- How best can we connect our meeting notes to contacts? Used the notes field or if it is a meeting add it as an activity. Action: need process for handing off contact and notes information from people who are not using database, such as Erik and open advocates.
- create custom search to search for custom event tags field (currently the custom event tags are not searchable)
- have Bob to look into whether LDAP can be used to auto-update CiviCRM?
- create custom search: individuals in African Health OER Network group, list name, org, date of first event, date of most recent event, number of events. This should also be exportable as a CSV or XSL file.
- When a person clicks unsubscribe, they are removed from mailing list but not from associated group (e.g. open.community.) Can Bob make that synced?
- It’s not clear to user in bulk mailings that the Unsubscribe text in emails removes that person from ALL future mailings from Open.Michigan CiviCRM, not just a particular thread or topic.
