Activity records are an incredibly useful and flexible tool for tracking engagement with constituents. The ability to create new activity types and extend them with custom fields provides an easy way to store information about your constituent's involvement and interaction with your organization in a customized way.

Quite often those points of interaction will happen outside of the database, and may be collected in spreadsheets or other data export formats which must be imported into CiviCRM. In this article, we'll walk through the steps and considerations when importing activity records. This article is not exhaustive; it's goal is to touch on key matters to consider when doing an activity import.

Initial Considerations

Activity imports have one important restriction you must consider: the contact you will attach the activity to must already exist in the system. You cannot simply import activities and have the contacts auto-created during import. For this reason, we'll briefly address the process of importing contacts below. But before that, we need to consider how we will match the activity records with the contact records they should be attached to.

It's critical that we ensure our activity records are attached to the correct contact during import. CiviCRM allows you to match on several fields when importing:

• contact ID
• external ID
• email

Importing to contact ID and external ID are the most reliable, as the values are unique. Email is vulnerable to a mismatch, as more than one contact may have the same email address. As you review your activity import file and decide how to first import contacts, keep this in mind. For example, you may want to construct an external ID value in your import file. After importing your contact records with that value included, you can import the activity records and reliably match them to those recently imported contact records. This generally proves to be the most reliable way to handle the import process.

Importing Contacts

When importing your contacts, you must also consider your matching rules. As you import the records, you typically want the system to see if a matching contact already exists, and if so, either update or fill in the details from your import file to those existing records. This is preferable to conducting no matches, which will introduce duplicates into your database. From the contact import screen you have two sets of options to consider: how duplicates will be handled, and what dedupe rule will be used. 

Skip indicates if a match is found, the importer will skip that row in your file. Update will overwrite the existing contact with data from your file. Fill will only fill in data from your file if it does not already exist in the contact record. And No duplicate checking will import all records with no matching or merging. The first three options require you select a duplicate matching rule. These rules are configured in the Contacts > Find and Merge Duplicate Contacts menu.

It's outside the scope of this article to discuss how those rules are created. But it's worth taking some time to understand them, as they are important for safely matching your contacts during import (see http://book.civicrm.org/user/current/common-workflows/deduping-and-merging/).

If you have constructed an external ID field in your import file, as suggested earlier, you will want to use the Update or Fill options so that existing contacts have that value filled in and your activity import will match them. Alternatively, you may use the Skip option. That will import new contacts, and provide you a log file of all contacts that were not imported because they already existed in the system. That is useful if you want to get a sense of how many would be merged and who the contacts are. For example, if your import file is small, you may want to review those matched contacts manually rather than import and update them through this tool.

Importing Activities

Once you've imported your contacts, you can import your activity records. CiviCRM requires the presence of several fields in order to import activities:

• activity date: note that the date format must be consistent and you must select the correct format of your data in the first step of the import wizard
• activity type ID or activity type label: visit Administer > Customize Data and Screens > Activity Types to review existing types. Depending on your purposes for the import, you may want to create a new type, which can be done through this interface. Also not that only Contact activity types may be used during your import.
• subject
• at least one of the contact matching fields noted earlier

You should also consider including a column for the activity status ID. By default, they will be imported with ID 1 (scheduled). You may want them imported with ID 2 (completed).

Walk through the import wizard, which will let you upload your file (you likely will want to check the "first row contains column headers" option) and select the date format. In the second step, you will match the columns in your file with activity fields. Take time to walk through this step carefully. You do not need to import every column from your file; just make sure that you are careful and accurate with your matching. Lastly preview the import and begin it.

In the final step, CiviCRM will return any records that were not imported. This may be caused by an unmatched record (unable to find a contact to attach the activity to) or because of malformed data (a date column that was not formatted correctly). Whatever it is, CiviCRM generally provides sufficient details for you to investigate and resolve the issue. The file will contain the entire records for which there were problems. You can typically delete the first few columns that have the error information and simply use that file for your reimport.