CQRC Engage allows you to upload advocate data from other systems using a formatted CSV (or Comma Separated Value) file. Engage will look at the headers for your file and try to match the information against our existing database. You’ll have a choice regarding what to upload and what to exclude from the file.
Advocate Fields
The upload file will match data to existing advocates, or if an advocate does not already exist, it will create the advocate. The advocate will only be created once.
Existing Advocates are matched based on the following criteria:
- External ID. If match is found on External ID, the record is updated. If External ID is not found, then:
- Look for Email Address. If match is found on email address, the record is updated. If email address is not found, then:
- Look for match on First/Last/ZIP. If a match is found on First/Last/ZIP, update record. If match on First/Last/ZIP is not found then create a new advocate.
Note: This means that it is possible to update email addresses. Uploads finding a match on First/Last/ZIP or external ID, but not on Email Address, will treat the Email Address field as a text field.
Important Note About the Use of External ID: If you plan to use External IDs in your database be sure to upload them in your initial upload. After records are created the External ID field cannot be populated except if edited manually in the Engage admin.
*If an advocate does not already exist, the advocate must have either email address, external ID OR first name, last name and Zip Code data entered in the upload file.
Default Fields
| Field | Required | Additional Detail |
| prefix | No | We recommend the options below, though this is an open text area:
Unknown, Mrs., Mr., Miss, Mother, Father, Brother, Sister, Hon., Ms., Rev., Dr., Asm., Sen., Sr., Fr., Rev. Mr., Rabbi, Rt. Rev., Rev. Dr., Other, Bishop, Mr. & Mrs., Student Doctor, Br., Pastor, Prof., Cantor
|
| firstName | Yes* | Maximum 60 characters. |
| middleName | No | Maximum 60 characters. |
| lastName | Yes* | Maximum 60 characters. |
| suffix | No | Must be one of the provided options below:
II, III, IV, CPA, DDS, DO, DVM, E.Ed., Esq., JD, Jr., LLD, LPN, MD, PE, Ph.D., PT, Ret., RN, Sr., USAF, USCG, USMC, USN, Ed.D., Ed.S., M.A., M.Ed., M.S., Psy.D
These values are cases sensitive and must be entered as listed above. |
| address1 | No | Maximum 250 characters. |
| address2 | No | Maximum 250 characters. |
| city | No | Maximum 250 characters. |
| state | No | USPS 2-character abbreviation. (MD, VA, etc) |
| zip | Yes* | Can be either a 5-digit or 9-digit (zip-plus-4) Zip Code. |
| country | No | Maximum 2 characters. Example: US
Country codes should be two characters following the ISO 3166-1 alpha-2 protocol, which more information about can be found here: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. |
| phone | No | Maximum 50 characters. |
| Yes* | Email address for the advocate. Maximum 250 characters. | |
| externalId | No | Maximum 255 characters. The field is used to tie this record to an external data source via a unique ID. This external ID must be a unique value. |
| globalEmailOptout | No | Boolean true or false possible values.
true = The advocate record will not be included in communications sent from Engage.
false = The advocate record will be included in communications sent from Engage.
All emails sent from Engage include an Unsubscribe option. If an advocate clicks the Unsubscribe link in an email, their advocate record is set to true for the globalEmailOptout field. |
| tags | No | Space delimited.
Example entry for three separate tags: blue red green Example entry for a single, multi-word tag: NewAdvocate (this could also be entered as ‘newadvocate’)
An identifier for an Advocate record that is typically used across multiple Advocate records as a way to tie them together.
Tags are additive. If an Advocate already exists and has Tag entries, any values in an upload file will add the new Tags, and not overwrite the existing ones. |
| active | No | One (1) or zero (0) possible values.
1 = The advocate record is active; it is eligible to receive communications sent from Engage as well as count toward your organization’s Advocate Record Storage allowance limit.
0 = The advocate record is inactive; it is ineligible to receive communications sent from Engage nor will it count toward your organization’s Advocate Record Storage allowance limit.
If no active column is specified in the CSV, the uploaded advocates will be active. If the CSV has an active column and you want to leave an updated advocate’s active status unchanged, specify with a – (dash). For example: email,active John will be active. Jane will be inactive. If Mark does not exist, he will default to inactive. If Mark does exist, his active value will NOT be changed. |
| answer.xxx | No | Answers to Custom Questions that have been created in Engage. Maximum 2000 characters.
In the column header of the upload file, the ‘xxx’ as shown to the left is to be replaced by the System Name of the Custom Question for which an answer is being provided.
Example: Custom Question Label Name: What is your favorite color? Custom Question System Name: FavoriteColor External Activity Upload File Column Header: answer.FavoriteColor When uploading multiple answers to a custom question, separate answers by commas, with no spaces. Example: red,blue,green NOTE on Boolean logic question answers: · true, yes, on, 1, y = true · false, no, off, 0, n = false
|
Upload Instructions
To upload a file, you must first create a CSV (comma separated value) document containing your advocate and activity fields. Your file must have a .csv extension. If you are using a tool like Excel, make sure to save your document as type .csv before trying to upload it to Engage. The maximum file size is 20MB or 100,000 rows.
Once you have created your CSV file, you are ready to upload your file as follows:
- Go to Advocates -> Upload Advocate (on right column)
2. An Upload Advocates pop-up window will display as follows:
3. Email Notification: Enter an email address in Email Notification where a confirmation email will be sent once the upload has processed.
4. Upload CSV File: Select an existing CSV file to upload.
5. Click Submit.
6. The system will then try and match your file headers against our files.
If the system cannot find a match, it will give you two options. The first is to select a matching field from your current field set. The second is to ignore the column entirely.
You can then hit “Import List.”
7. Note that it may take a few minutes before the advocates can be searched in your Engage database depending on the size of your upload and on what other upload activity is occurring in Engage.
Please note: large uploads will generate large report emails. If you have not received a report, you may wish to check your bulk mail folder.
Upload Report:
When the upload is completed, you will receive a report like the one shown below. This will indicate how many records have been added, or updated, in our database.
But what does it all mean? Here’s a helpful guide:
Rows: “Rows” shows the number of records the system thinks you are uploading. Normally, one row equals one record to be added to the database. But, if you have blank rows with saved information – spaces, etc – this can fool the system into thinking you have more data than you do. Any time you see more rows than records, you’ll be getting an error message back.
Errors: “Errors” indicates the number of rows which could not be processed. There can be a number of causes, which we’ll discuss below. The important thing to note is these errors do not prevent the rest of the update from taking place.
New: “New” indicates the number of brand new records inserted into your database. Remember, a record is considered new if the system can’t match an external ID, email address or (if email isn’t available) first name/last name/ZIP combination against an existing record.
Updated: “Updated” shows the number of records which were changed in the Engage database based on this upload. This means a record was matched and an alteration was recorded. If no alterations are made, that’s handled in the next status:
Unchanged: The “Unchanged” status means the system matched the record you were importing against an existing record, but there was no difference between the information in the upload sheet, and what’s in Engage. Our system doesn’t count overwriting a record with the exact same information as an ‘update.’
The email will also show errors, such as duplicate rows or missing data. If you have questions about the errors, please contact your account executive.
