Freephile Wiki

CiviCRM: Difference between revisions

Browse history interactively
← Older edit
VisualWikitext
adds documentation section
use Subpages template
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Meta ==
<!-- embed a video -->
For things specific to CiviCRM on WordPress, see the [[CiviCRM/WordPress]] article.
{{#ev:vimeo|192125770}}


For debugging, specifically in CiviCRM, see the [[CiviCRM/debugging]] article.
{{Subpages|}}
 
Here we'll deal with the general plus Drupal-specific info (I think it's installed more with Drupal)


== Documentation ==
== Documentation ==
Line 31: Line 29:
After installation, there is a checklist that you should complete (e.g. http://example.org/civicrm/admin/configtask)
After installation, there is a checklist that you should complete (e.g. http://example.org/civicrm/admin/configtask)


Some of the things needed for a first-time setup:
Installation Checklist<ref>See also: https://hq.palantetech.coop/projects/commons/wiki/CiviCRM_launch_checklist</ref>:
<ol>
<ol>
<li>Enable the CiviBartik theme, for Civi admin, and then immediately configure various blocks to NOT appear in that theme (remove everything from column two, so that you get a wide display)
<li>Enable the CiviBartik theme, for Civi admin, and then immediately configure various blocks to NOT appear in that theme (remove everything from column two, so that you get a wide display)
<li>enable the [http://book.civicrm.org/user/current/introduction/components/ components]
<li>enable the [http://book.civicrm.org/user/current/introduction/components/ components]
<li>check/enable permissions (Drupal)
<li>check/enable permissions (Drupal)
<li>set the headers and footers for mailings
<li>disable the headers and footers for mailings (place mandatory tokens in your templates instead)
<li>set the message template for mailings (note that you'll want to design, and create all assets for your mail [[templates]], and host them)
<li>set the message template for mailings (note that you'll want to design, and create all assets for your mail [[templates]], and host them)
<li>setup custom fieldsets and data fields.  Before you do this, learn about Option Groups
<li>setup custom fieldsets and data fields.  Before you do this, learn about Option Groups
Line 43: Line 41:
<li>Option Groups.  There are many things in CiviCRM that are already configured as "Option Groups".  "Website" is one example.  When adding an Organization or Contact, and you want to enter data about their website, it could be one of many types: main, work, personal, facebook, twitter, pinterest, github etc.  These are defined in the option group for "website".  You can modify these to suit your data and your needs.  As another example, "Campaign Type" comes defined as 'Direct Mail', 'Referral Program', and 'Customer Engangement'.  I added 'Marketing' so that I can do a generic (email/web) marketing campaign.
<li>Option Groups.  There are many things in CiviCRM that are already configured as "Option Groups".  "Website" is one example.  When adding an Organization or Contact, and you want to enter data about their website, it could be one of many types: main, work, personal, facebook, twitter, pinterest, github etc.  These are defined in the option group for "website".  You can modify these to suit your data and your needs.  As another example, "Campaign Type" comes defined as 'Direct Mail', 'Referral Program', and 'Customer Engangement'.  I added 'Marketing' so that I can do a generic (email/web) marketing campaign.
<li>If you plan to use the CiviCase component to manage the common constituent "projects" or "workflows" and their associated timelines, then you'll need to create your own "Case Types". Look at the existing "Case Types" for reference.
<li>If you plan to use the CiviCase component to manage the common constituent "projects" or "workflows" and their associated timelines, then you'll need to create your own "Case Types". Look at the existing "Case Types" for reference.
<li>{{@todo}} review [http://wiki.civicrm.org/confluence/display/CRMDOC/Managing+Scheduled+Jobs docs] and setup cron to do things like geocoding.  '''Your mail campaigns will not send without cron'''
<li>{{@todo}} review [http://wiki.civicrm.org/confluence/display/CRMDOC/Managing+Scheduled+Jobs docs] and setup cron to do things like geocoding.  '''Your mail campaigns will not send without cron''' Drupal cron is best managed with drush
<li>Test and set your SPF record for your domain so that you can use Mailer, and review the docs for [http://book.civicrm.org/user/current/advanced-configuration/email-system-configuration/ email system configuration]  I was unable to get CiviCRM to use Google's smtp.gmail.com server, nor relay-smtp.gmail.com, even with an IP address whitelisted.  This is because Digital Ocean is still dropping all outbound SMTP traffic at their firewall (telnet doesn't even connect).  Somehow, if I smarthost it through [[Postfix]] it actually works.  I want to use Google for delivery because using <code>mail()</code> from an IP at Digital Ocean will result in mail being flagged as spam or silently dropped by several major providers (e.g. Yahoo, Microsoft).  Besides, if I'm '''paying''' for GAFYD, then I want to actually '''use''' it!  Google IS pretty well known for their email delivery capability!
<li>Test and set your SPF record for your domain so that you can use Mailer, and review the docs for [http://book.civicrm.org/user/current/advanced-configuration/email-system-configuration/ email system configuration]  I was unable to get CiviCRM to use Google's smtp.gmail.com server, nor relay-smtp.gmail.com, even with an IP address whitelisted.  This is because Digital Ocean is still dropping all outbound SMTP traffic at their firewall (telnet doesn't even connect).  Somehow, if I smarthost it through [[Postfix]] it actually works.  I want to use Google for delivery because using <code>mail()</code> from an IP at Digital Ocean will result in mail being flagged as spam or silently dropped by several major providers (e.g. Yahoo, Microsoft).  Besides, if I'm '''paying''' for GAFYD, then I want to actually '''use''' it!  Google IS pretty well known for their email delivery capability! Ultimately, Google is not a good choice for delivery.  Use a vendor. (See [[CiviCRM/CiviMail]] and [[Email Marketing]]
<li>Turn on logging in the Administration console, otherwise each record has a changelog, but there is no detail in the log!
<li>Turn on logging in the Administration console, otherwise each record has a changelog, but there is no detail in the log!
<li>Synchronize Users to Contacts
<li>Create a BOD group, and put each member into the group
</ol>
</ol>


Line 53: Line 53:


== Upgrading ==
== Upgrading ==
There is a long guide on [http://wiki.civicrm.org/confluence/display/CRMDOC/Upgrading+CiviCRM+for+Drupal+7 how to upgrade CiviCRM for drupal]  
[[{{PAGENAMEE}}/upgrade]]
 
== Debugging and the CV command-line ==
 
If you have your CiviCRM sending errors to the Drupal Watchdog Log (CiviCRM Administer > System Settings > [https://equality-tech.com/civicrm/admin/setting/debug?reset=1 Debugging and Error Handling]), you can simply navigate to it in the Drupal Admin (Reports > [https://equality-tech.com/admin/reports/dblog Recent log messages])


You should be familiar with all the steps described in the manual, and understand how the particular steps impact/affect your installation. The short version below is known to work with our setup, and with 'routine' upgrades.
There are many tools you can use to debug your CiviCRM instance.
One of these is the <code>cv</code> tool [https://github.com/civicrm/cv available on Github].
<pre>
cv version v0.1.27


Here is the short version:
Usage:
# backup your database(s) <code>sudo ~/bin/backup.db.sh drupal</code> <code>sudo ~/bin/backup.db.sh civicrm</code> <ref>[[Mysqldump]]</ref>
  command [options] [arguments]
# download the code <code> wget https://download.civicrm.org/civicrm-4.6.5-drupal.tar.gz</code>
# put site in maintenance mode<code>drush vset maintenance_mode 1</code> (Make sure you are also logged in as Admin)
# move old code, and unpack new code <code>mv civicrm /tmp/ && tar xvzf civicrm-4.6.5-drupal.tar.gz</code>
# run the upgrade script <code>/civicrm/upgrade?reset=1</code>
# put site in operation mode<code>drush vset maintenance_mode 0</code>
# toast


Options:
  -h, --help            Display this help message
  -q, --quiet          Do not output any message
  -V, --version        Display this application version
      --ansi            Force ANSI output
      --no-ansi        Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
  api                    Call an API
  cli                    Load interactive command line
  dis                    Disable an extension
  dl                      Download and enable an extension
  en                      Enable an extension
  ev                      Evaluate a snippet of PHP code
  flush                  Flush system caches
  help                    Displays help for a command
  list                    Lists commands
  path                    Look up the path to a file or directory
  scr                    Execute a PHP script
  url                    Compose a URL to a CiviCRM page
ang
  ang:html:list          List Angular HTML files
  ang:html:show          Show an Angular HTML file
  ang:module:list        List Angular modules
api
  api:batch              Call an API (batch mode)
debug
  debug:container        Dump the container configuration
  debug:event-dispatcher  Dump the list of event listeners
ext
  ext:disable            Disable an extension
  ext:download            Download and enable an extension
  ext:enable              Enable an extension
  ext:list                List extensions
  ext:uninstall          Uninstall an extension and purge its data
  ext:upgrade-db          Apply DB upgrades for any extensions
php
  php:boot                Generate PHP bootstrap code
  php:eval                Evaluate a snippet of PHP code
  php:script              Execute a PHP script
vars
  vars:fill              Generate a configuration file for any missing site data
  vars:show              Show the configuration of the local CiviCRM installation
</pre>
Also, don't forget to use [[Drush]] if you're on [[Drupal]]; the CiviCRM API; and the ConfigAndLog directory log.  The ConfigAndLog directory is in a path like <code>./sites/default/files/civicrm/ConfigAndLog</code>


== Profiles ==
== Profiles ==
Line 79: Line 128:


<blockquote>
<blockquote>
Custom tokens (based on custom data) can be added for organizations as well. These tokens will not be displayed in the list of available tokens, but can be added manually. The format is {contact.custom_12} where 12 is the ID of the custom data field. To find the custom data field ID, go Administer > Customize Data & Screens > Custom Fields and click on the field you want to use. Look at the URL. The last part of the URL will be an equal sign and a number (=12). The number (12 in this example) is the id of that custom field.
Custom tokens (based on custom data) can be added for organizations as well. These tokens will not be displayed in the list of available tokens, but can be added manually. The format is {contact.custom_12} � where 12 is the ID of the custom data field. To find the custom data field ID, go Administer > Customize Data & Screens > Custom Fields and click �edit� on the field you want to use. Look at the URL. The last part of the URL will be an equal sign and a number (=12). The number (12 in this example) is the id of that custom field.
</blockquote>
</blockquote>


You can create your own tokens by implementing <code>hook_civicrm_tokens()</code> and  <code>hook_civicrm_tokenValues()</code>.  See  
You can create your own tokens by implementing <code>hook_civicrm_tokens()</code> and  <code>hook_civicrm_tokenValues()</code>.  See  
<source lang="php">
<syntaxhighlight lang="php">
<?php
<?php
/**
/**
Line 241: Line 290:
     }
     }
}
}
</source>
</syntaxhighlight>


* [https://civicrm.stackexchange.com/questions/2558/tokens-for-custom-field-set-with-multiple-records?rq=1 Stack Exchange]
* [https://civicrm.stackexchange.com/questions/2558/tokens-for-custom-field-set-with-multiple-records?rq=1 Stack Exchange]
Line 263: Line 312:
== Extensions ==
== Extensions ==
* See [https://civicrm.org/extensions/drupal listing of CiviCRM extensions for Drupal]
* See [https://civicrm.org/extensions/drupal listing of CiviCRM extensions for Drupal]
* [http://wiki.civicrm.org/confluence/display/CRMDOC/Extensions Extensions documentation in the wiki]
* [https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/#installing-a-new-extension  Installing extensions]
* [http://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Custom-Search+Extension Create a Custom Search extension]
There are multiple ways to use the <code>cv</code> command to download and install extensions:
;Download a published extension from the directory (long name).
:<code>cv dl org.example.foobar</code>
;Download a published extension from the directory (short name).
:<code>cv dl foobar</code>
;Download an unpublished extension (long name and zip URL)
:<code>cv dl org.example.foobar@http://example.org/files/foobar-1.2.zip</code>
;Download a pre-release (alpha/beta) from the directory.
:<code>cv dl --dev foobar</code>
 
 


== Developing Extensions ==
== Developing Extensions ==
Line 286: Line 345:
== Database ==
== Database ==
The database code in CiviCRM is divided into two logical sections: the DAO and the BAO.  The BAO holds the "business logic" for objects and extends the DAO.  The DAO is concerned with data to/from the database backend and it's definition (object to relational database mapping, aka "[[wp:Object-relational mapping|ORM]]").  Both are an extension of the [https://pear.php.net/manual/en/package.database.db-dataobject.php PEAR DB DataObject] class.  As of August 2015, this is true and [https://civicrm.org/node/95 this blog post from 2006] gives some more (early) background.
The database code in CiviCRM is divided into two logical sections: the DAO and the BAO.  The BAO holds the "business logic" for objects and extends the DAO.  The DAO is concerned with data to/from the database backend and it's definition (object to relational database mapping, aka "[[wp:Object-relational mapping|ORM]]").  Both are an extension of the [https://pear.php.net/manual/en/package.database.db-dataobject.php PEAR DB DataObject] class.  As of August 2015, this is true and [https://civicrm.org/node/95 this blog post from 2006] gives some more (early) background.
<source lang="php">
<syntaxhighlight lang="php">
// from CRM/core/DAO.php
// from CRM/core/DAO.php


Line 292: Line 351:
require_once 'DB/DataObject.php'
require_once 'DB/DataObject.php'
class CRM_Core_DAO extends DB_DataObject
class CRM_Core_DAO extends DB_DataObject
</source>
</syntaxhighlight>
In 2009, [https://civicrm.org/node/597 Doctrine was proposed] as a OODB approach instead of an ORM.  There are [https://civicrm.org/blogs/dharmatech/data-mapper-pattern-civicrm-architecture-proposal other discussions too] in the "Architecture Series" that are worth reviewing if you want to know more about database development in CiviCRM.
In 2009, [https://civicrm.org/node/597 Doctrine was proposed] as a OODB approach instead of an ORM.  There are [https://civicrm.org/blogs/dharmatech/data-mapper-pattern-civicrm-architecture-proposal other discussions too] in the "Architecture Series" that are worth reviewing if you want to know more about database development in CiviCRM.


Retrieved from "https://wiki.freephile.org/wiki/CiviCRM"