1. Create two new databases. One for WP and a separate one for CiviCRM. I used the same user for both, but it might be better to use different users. You don’t have to separate your CMS and CRM databases, but I am increasingly of the opinion that the minor inconvenience of separating them at the start makes for easier maintenance down the road, especially if/when you have to move or attempt repair.
2. Set up the new WordPress server. In this case I used a new subdomain, but that may not be desirable. If re-using a subdomain, you’ll have to play some more games with hosts files and maybe ssl certificates to smooth the process, or take the old one offline to avoid conflicts. Definitely solvable, but outside the scope of this document.
   1. create the web server directory and download the latest WordPress code. I used wp-cli to download the latest en-CA version: ‘wp core download --locale=en_CA‘
   2. create the appropriate vhosts file in /etc/apache/sites-available and symlink to sites-enabled.
   3. Run the WordPress web install to get the DB credentials set or do it manually in wp-config.php.
   4. use ‘certbot --apache -d site.name‘ to get ssl running. Or you can copy certificates, keys and manually sort out your vhosts files if you are keeping the same domain.
   5. You may wish to use a WP plugin like ‘Customizer import and export’ to migrate some look and feel items from the old site to the new one.
3. Setup CiviCRM on the new server.
   1. Download the CiviCRM plugin for WordPress. Do not simply use the latest CiviCRM, download the version that matches your existing database. E.g. ‘wget https://download.civicrm.org/civicrm-VERSION-wordpress.zip‘
   2. Optionally, download the matching localisation files if your CiviCRM install is multilingual. 'wget https://download.civicrm.org/civicrm-VERSION-l10n.tar.gz'.
   3. Unzip civicrm-VERSION-wordpress.zip to the WP plugins directory (and localisation files in plugins/civicrm)
   4. Activate CiviCRM from the WP plugins page.
   5. When answering the questions on the CiviCRM setup, read carefully and provide the database credentials for the CiviCRM database to ensure it doesn’t get mixed with WP.
   6. Review the settings from the old site, but DO NOT migrate the civicrm.settings.php file. You may need to transfer a value or two, but don’t bring the whole thing over. Sometimes I don’t need to copy anything.
   7. Add CiviCRM modules and extensions to match the old database.
   8. Confirm the the new site is behaving well.
4. Make code and database backups of this new server. This ensures we can get back to this ‘clean’ state if things go sideways.
5. Clean the old database to prepare for import
   1. Export the database of the old CiviCRM installation using 'mysqldump --skip-triggers' (CiviCRM will rebuild triggers, which is preferable to having to clean up triggers that don’t work because of new locations, etc.)
   2. Create a temporary database for cleaning the old database.
   3. Tweak the dumpfile you are about to import and clean. In spite of my note above and below about --skip-triggers I discovered a problem during the dump of the cleaned data below. I was getting ‘DEFINER’ errors because that was attached to some views in the dump file. Maybe these can be removed and rebuilt somehow, but I decided to do a search and replace before the import in the next step so that the old username that was listed as the DEFINER was replaced by the new username. I foolishly used vim this time, but my dumpfile was very large and it was annoying. Better to use sed next time: sed -i 's/Old_Username/NEWUSER/g' dumpfile.sql > NEWUSER_dumpfile.sql
   4. Import the dump file into your temporary database.
   5. Drop extraneous tables from the temporary database.
      1. Some will always be worth deleting:
         • civicrm_db_name.civicrm_acl_cache, civicrm_db_name.civicrm_acl_contact_cache, civicrm_db_name.civicrm_cache,
civicrm_db_name.civicrm_domain,
civicrm_db_name.civicrm_group_contact_cache
      2. Others drops will be more discretionary. I deleted all the 'log_%' tables. I also dropped tables that were clearly for modules and extensions that I had removed, but left crap in the database. I was presuming that these tables were part of my problem. However, this is a dangerous game, so be careful. Go slowly and consider each removal. Because this is a backup and not the live DB, it’s not disastrous, but could set you back several steps if you guess badly. Dropping large numbers of tables can be tedious as you can’t use a wildcard, but the following code will create a script that you can then feed back in to drop the tables. I used Adminer to do this, but it should work ok in the command-line client too.
         • SELECT CONCAT(‘DROP TABLE ‘, TABLE_SCHEMA, ‘.’, TABLE_NAME, ‘;’)
           FROM INFORMATION_SCHEMA.TABLES
           WHERE TABLE_NAME LIKE ‘log_%’
           AND TABLE_SCHEMA = ‘civicrm_db_name‘;
6. Dump this cleaned temporary database for importing into the new site database.
7. Disable the CiviCRM plugin on the new site. The first migration I did, I didn’t do this and it turned out ok, but it makes sense.
8. Import the cleaned sql dump file into your newly setup CiviCRM database: 'mysql -u mysql_username -p civicrm_db_name < civi_dump_file_name_of_your_choice.sql'
9. Clear CiviCRM cache: 'rm -rf /var/www/civi.site/wordpress/wp-content/uploads/civicrm/templates_c/*'
10. Re-enable the CiviCRM plugin.
11. Use the following URLs in your browser to review and update directory paths and base URLs.
    See CiviCRM Menu: Administer >> System Settings >> Cleanup Caches and Update Paths
    • http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/admin/setting/updateConfigBackend&reset=1
    • Review paths: http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/admin/setting/path?reset=1
    • Rebuild menus: http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/menu/rebuild&reset=1
    • Rebuild database triggers: http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/menu/rebuild&reset=1&triggerRebuild=1

Once you have Smarty enabled, choose Contributions->Find Contributions. If you do not see the Contributions menu, you do not have access to contribution data and will need to contact your system administrator.

On the “find contributions” page, choose the period for which you wish to generate the summary:

You may wish to set other limitations as well. For example, if you are testing the process, you may wish to put a partial name in the “Contributor Name or Email” field so that you are only doing this for one person (presumably yourself) as a test.

Press the “Search” button and you will receive a result set. (hopefully what you wanted, but you may need to tweak a little–that is a subject for another post).

Once you have the result set you want, you should choose the “All xx records” radio button and then select “thank-you letters – print or email” from the Actions drop-down:

Once you select that action, you will be taken to the “Printer/Merge Document” page for “Thank-you Letter for Contributions”.

On this page you have quite a few options, but the critical ones you will want to be sure you get right to email a year end summary are “Group contributions by” and “Print and email options”.

For the grouping, choose “Contact”. This will ensure that each contact only receives one letter. We will put some code in to summarize them in a minute.

For print and email options, you will probably want to choose “Send emails where possible, Generate Printable PDFs for contacts who cannot receive email”. This will send emails to anyone you have an email for and save you postage. In addition, it will generate pdfs for those with no emails so that you can send them via regular mail without sorting again to figure out who didn’t get an email. If there’s a pdf, then they didn’t get an email.

For the other options, I typically build a template beforehand using Mailings->Message Templates, but you can build your message right here as well. To save it for future use, just choose “Save as New Template” from the checkboxes below the message. If you tweaked the content and want to update your template, choose “Update Template” instead.

Don’t forget to set the “Activity Subject” as this is the subject line of your email and also of the email activity entry in the contact record.

You can put whatever you want in your email, but I recommend that you include a pleasing and relevant photo as part of the message. It’s more likely to be read. In addition, a subject line that is personal and engaging is helpful.

For the summary, we will use some Smarty template code. It will loop through the contributions that come from the list and put them into a table:

<table align="left" border="1" cellpadding="5" cellspacing="0" class="table" style="margin-top:15px;">
	<tbody>
		<tr>
			<th>Date</th>
			<th style="text-align:right;">Amount</th>
			<th>Method</th>
			<th>Campaign</th>
			<th>Note</th>
		</tr>
		<!--
    {foreach from=$contributions item=contribution} 
        {assign var="date" value=$contribution.receive_date|date_format:"%d %b %Y"}
        {assign var="year" value=$contribution.receive_date|date_format:"%Y"}
       -->
		<tr>
			<td>{$date}</td>
			<td style="text-align:right;">${$contribution.total_amount|crmNumberFormat:2:".":","}</td>
			<td>{$contribution.payment_instrument}{if $contribution.check_number neq""} - #{$contribution.check_number}{/if}</td>
			<td>{$contribution.campaign}</td>
			<td>{$contribution.contribution_source}</td>
		</tr>
		<!--
    {/foreach}

        -->
		<tr>
			<th>{$year} TOTAL</th>
			<th style="text-align:right;">${$contribution_aggregate|crmNumberFormat:2:".":","}</th>
			<th> </th>
			<th> </th>
			<th> </th>
		</tr>
	</tbody>
</table>

/**
 * Enable this constant if you want to send your email
 * through the smarty templating engine (allows you to do 
 * conditional and more complex logic)
 **/
if (!defined('CIVICRM_MAIL_SMARTY')) {
  define( 'CIVICRM_MAIL_SMARTY', 1 );
}

In addition, you should disable entities in CK editor. You can do that at Administer->Customize Data & Screens->Display Preferences. Then scroll down and click the “Configure CKEditor” button.

On the subsequent page, you will need to set entities to false.

• Contribution: [civicrm component="contribution" id="x"] shows a contribution page specified by the id attribute.
• Event: [civicrm component="event" action="register" id="x"] and [civicrm component="event" action="info" id="x"] shows either a registration or information page for the event specified by the id attribute.
• User dashboard: [civicrm component="user-dashboard"] shows the current user’s dashboard page. There are no additional options. To identify what related information you have setup to be displayed within the user dashboard i.e. contributions, memberships, etc. navigate to Administer > Customize Data and Screens > Display Preferences and select all of the information you would like to have visible to the user.
• Profile: [civicrm component="profile" mode="y" gid="x"] shows a page for displaying a user’s profile. This can be one of 4 modes – edit, view, create or search. The default is create. The gid attribute selects which profile group is displayed.
• Petition: [civicrm component="petition" id="x"] displays a petition form specified by the id attribute.
• Form Builder: [civicrm component="afform" name="x"] displays a Form Builder form (afform) page. Where x is the name given to the page, for example: afsearchMemberDirectory

Contribution and Event components can be put in test mode with mode="test"

In addition, any of these can specify a hijack option and they will replace all other content on that page rather than being display inline. This looks like hijack="1".

Force: A force attribute is mentioned in the code but I’m not clear what it does and have not tested it myself: force=1 means it will display the table, force=0 means it will display the search box for the table and you will see the results of the search for the table after you search.

I think force probably only relates to profiles which could have search results and have default values.

Mostly taken from drkane’s answer on civicrm.stackexchange.com with some bits from the official documentation: Using shortcodes to publish CiviCRM content in WordPress.

1. ssh to server
2. ensure everything is backed up right now, not last night. This is normally handled automatically on a daily basis by ManageWP and also by a local msqldump process.
3. Disable CiviCRM logging because of DB upgrade issues. Administer->System Settings->Misc
4. Disable InnoDB full text search because of DB upgrade issues. Administer->Customize Data->Search Prefs
5. cd to /var/www
6. visit https://civicrm.org/download in a browser and get the download links
7. download civicrm-….zip (and if needed, the localisation files.tar.gz) to somewhere convenient using wget
8. cd to wp-content/plugins directory of site
9. mv civicrm directory to /var/www/sitename/civicrm.bak (This is to backup what we have just in case of trouble and to get the existing one out of the way for the new code.)
10. unzip civicrm-….zip to plugins directory
11. IF NEEDED: cd to civicrm directory and tar xvzf civicrm…_l10n.tar.gz
12. cd to wp-content/uploads/civicrm/templates_c and delete everything inside templates_c
13. upgrade the database by visiting /wp-admin/admin.php?page=CiviCRM&q=civicrm/upgrade&reset=1
14. re-enable logging if needed
15. re-enable InnoDB full text search if needed
16. may need to www-unlock and www-lockdown once or twice to correct permissions.
17. confirm site function
    1. test a contribution form
    2. test a mailing
    3. test public pages