Product User Guide
Hey! If you’re here, it probably means you purchased a license to the PCO Giving Import Tool. First and foremost, thanks for the support! I believe in this tool, but I wouldn’t believe in it without the great feedback you guys send me.
If you purchased our premium option, you need to go look at the premium page for what your next steps are.
Before you begin
Let’s do it
The PCO Giving Import Tool implements Planning Center’s required implementation on OAuth 2.0. This means you’ll log in similarly to the way to log into your PCO account any other day. Once you’ve connected your account, you’re good to go. You can revoke access anytime you wish here.
After you’ve authentication with Planning Center, you’ll need to punch in your license key. Your license key should have already been provided to you upon purchase confirmation. If you don’t have a license key, you can purchase one here. Once your license key has been issued, you have 30 days to complete your migration. If you need longer, please let us know. If you need longer than 60 days, there may be additional monthly charges, or we can disabled the license until you’re ready to complete your import.
Configure the main options before starting the import:
- Create New People – this will create a new person if the app can’t find them in the planning center database. For more info on how the app searches for existing people, check out the “how it works” section below. First Name, Last Name, and remote_id column mappings are required if you have this enabled.
- Time Zone – By default this is set to “local time”. You should only change this if the time zone you’re importing to, is different than the time zone you are in. This setting is important for donations that occur at the beginning or end of the current year.
- Default Payment Source – Every contribution/donation in PCO comes from “somewhere”. If someone donates directly through ChurchCenter, the payment source is defined as “Planning Center”, so we just need to know where these donations are coming from. We recommend you create a new payment source inside the giving app with the name of your old system (e.g. CCB, Arena, F1, etc…). (required field)
- Default Fund – The default fund is used when we can’t find the appropriate fund in the fund mappings section. If a default fund is specified, we’ll use this one. If it’s not specified, we’ll skip the donation.
Map your old funds to the new funds in planning center before running your import. We do a simple string comparison of the fund names in the CSV import file and map those to the actual funds in Planning Center. The easiest way to do this, is to compile a list of all the unique fund names in the CSV file, and add them one by one here. We require at least 1 fund be mapped before running the import.
If the funds are not visible in the drop down, they must be active. You can make them “admin only” to hide them from ChurchCenter if you want, but if they are not active and open when importing, we can’t import the donations to those funds.
Templates allow you to save column mappings for future use down the road. While we are constantly trying to provide more templates out-of-box, we may not have one defined for your system. You can create one once, and save it for future use.
A column mapping just tells the system what column name from your exported CSV file is the field needed to perform the import. As an example, if you export data from Fellowship One, they might label the “contribution date” as “received date”. With templates, you don’t have to tell the app which column is which every time.
Knowing which fields you need from the exported data is important. As a general rule, you should do your best to capture all of the fields below. However, depending on the options you’ve selected, not all are required.
We use these columns to identify who the donation should be attributed to. At least 1 is required, but we recommend you specify all of them if possible.
- RemoteId – If you imported your people into PCO already and used the remoteId column, your donation import will practically 100% accurate if you include this column name. If you’re not sure what I’m talking about, refer to this planning center article or reach out to the person that performed your people import as that step is recommended BEFORE doing this.
- Email – The email address column name.
- Phone Number – The phone number column name.
- First Name – First name column name. This is required if you’ve enabled the create new people option.
- Last Name – Last name column name. This is required if you’ve enabled the create new people option.
- Fund – Fund column name.
- Amount – Amount column name. This can be formatted with a dollar sign ($), whole numbers (12000), or with decimals (101.65).
- Contribution Type – Contribution type column name. This is the type of contribution (e.g. online, card, ACH, check, etc…). These are pretty standard across all platforms, but if you find your import is attributing them improperly, please let me know.
- Contribution Date – Contribution date column name. This is the date of the actual contribution. This is important for tax purposes so that the donor gets credit for the donations they made in the correct year and will also be important if you run reports with a time parameter.
- Check Number – Check number column name. This the only optional field. If you specify a check number column name and the contribution type is ‘check’ we’ll be sure to import the check number as well as it is printed on statements at the end of the year.
IT IS HIGHLY ADVISED that you include as many column names that you have access to. It is not always required, but to get the most accurate import, this is best practice.
Once you have saved everything on the configuration screen, the app will let you perform your import. You need select the template, the batch group and the batch before selecting the file. We require these for better organization down the road. A good practice is to name your batch group “ Import” and your batch the year or the month – “2017”. This allows for an easier reconciling process.
Select your file and the import should start automatically. If any of the column headers don’t match with the template you’ve selected, the app will let you know.
The import itself is fairly trivial – add each donation to the batch, However, it may be helpful to understand how it actually does this.
Checking Column Names
The first thing the app will do is ensure the column names you have given us exist in the file you are uploading. If it doesn’t, the app will stop and tell you which column it couldn’t find. You’ll need to correct the column names before proceeding.
Reading Column Values
We’ll read each column value. If we have an issue converting a value, we’ll stop and let you know. For example, “Five hundred dollars and no cents” is not a valid value for Amount.
If the Amount is less than or equal to 0, the donation will immediately be skipped.
Finding The Donor
The most crucial part of the import happens here. First, we’ll attempt to find the donor by RemoteId if you provided one. If we can’t find a person or you did not provide that column, we’ll use Email, and then Phone Number. If we find more than one person using email or phone, we’ll select the best match based on name, age, and gender (head of household).
If we still can’t find the person, we will either skip the donation or create that person (if you have this enabled).
We will check the fund name against your mappings. If we can’t find the correct fund, and no default fund was specified, we’ll skip the donation.
Real Time Analytics
While the import file is running, you’ll notice we will tell you how many people we’ve created, donations processed, and the number of errors.
You may notice the app “freezes” at times. It’s not actually frozen, we’re just waiting for the Planning Center API to let us continue. The Planning Center API has a rate limit of 100 request per 20 seconds. This means, at best, we can only import 150 donations per minute – 1 requests for finding the donor, and 1 requests for uploading it.
An error occurs anytime a donation is skipped for any reason even if it was intentional. At the end of the import, we’ll output all errors to a file for you to look over and in some cases, attempt to re-upload.
Possible errors include:
- Amount must be greater than 0.
- Couldn’t find person and ‘Create New People’ has been disabled.
- API rejected person creation. Try this row again.
- Must have a valid remoteId, first name, and last name to create a new person.
- We attempted to create the person with valid information, but couldn’t find them afterwards. Try this record again.
- No fund mapping found. Try specifying a default fund Id in the configuration settings.
- API rejected the import. Try this one again.
When the import has completed, we will write all of these errors to another CSV file in the same location as your original with the same name and “_errors” appended to it. Larger files that create new people tend to experience the most errors.
Process The Error File
If you need to retry rows from the error file, just select the “Error File” template on the upload screen and select the error file. Keep in mind, this might produce an additional error file.
Great! You made it this far. All you have to do now is double check the numbers for your own comfort and commit the batch.
There’s a blue commit button in the bottom right of the upload screen that says ‘commit’ if you hover over it. Just click the button and we’ll tell Planning Center to commit the batch.