Importing Content and Contacts

Content and Contacts can be imported to Brick River from any correctly formatted .csv (comma separated values) file. 

The process requires:

  1. a file to be imported, and
  2. a Brick River Import Definition document to store settings for the import.

Once the Import Definition document has been created,  an import is performed immediately upon transfer of the .csv file to the designated location on the Brick River server. 

This file transfer can be performed on demand from the Web Console - or using an external tool such as cURL. Using an external transfer tool allows you to schedule regular automatic updates to Brick River Content and Contacts.  This process is described further in the Brick River Developer's Guide - here.

Preparing a .csv File for Import

Think of a .csv file as a simple spreadsheet which stores data in rows and columns.  These files can easily be opened and edited using Microsoft Excel and other applications.

Records to be imported are always directed to a Brick River Table / View.  For example, an import file containing 1000 new names to include in email campaigns may be directed to the Contacts - People View.

For a Brick River import the .csv file must include a header row with the name of each column exactly matching the Field Id used in Brick River.

The best way to ensure that the header row contains valid Field Ids is to review the Field List using the View fields and information link provided on the Import Definition form - described further below.

It is also possible to perform an Export from Brick River for comparison.  For example, if you plan to import records using the People View - first perform an export from the People View - choosing .csv as the file type.  The resulting file will contain a header row with the Field Id for each field.

If you are using an Id for the matching mode (more on that below) you will need to have a field called Id. It's case sensitive (not 'ID').

The importer will only add/update the fields that you specify in your .csv file. 

Create the Import Definition

This process requires Administrator permission.

From the Web Console, click Admin.  Click the 'Import' link, click New to create a new Import.

 

On the Import screen:

1  Give the importer a Name. This is only for you to identify it.

2  Choose the Table - View which the records will import to.

3  Select a RunAs name - always select a User with Administrator permission.

4  Select a Matching Mode  - this determines how existing import records will be compared to existing records.  If the import process locates a 'match' - the existing record can be updated by the import file record. When there is no matching record a new record can be created.

There are three matching modes.

  • Brick River Id.  Each record in a Brick River table has a unique record Id.  These Ids are rarely displayed to Users.  You can export a .csv file from any View - choosing the option 'Include Brick River Id'.  The resulting file includes a column with the Field Name - 'Id'.   If you run an import using this matching method - the .csv file to be imported must include an Id field.  This option is useful when you want to export a View - edit the resulting .csv in another application - and then import the updated .csv back in to Brick River.
     
  • External Source.  Each record in Brick River can optionally store a SourceName and SourceId.  These fields can be used to match Brick River records to records in an external system. If you select this option you will be prompted for a Source Name.  The file to be imported must have a column named 'Id'.  The import process will match records base on matching both SourceName and Id. This option is useful when you need to regularly sync records between Brick River and external applications.  See additional information and an example below.
     
  • Use deduping fields. Each Brick River View defines 'Deduplication Fields'.  If two records are found with matching values in all fields, the system identifies them as matching records.  Each View can have a unique set of Deduplication Fields.  It is common for Contacts Views to use:  Title and PubDate .  Documentation for customizing a View's Deduplication Fields is here in the Brick River Developer's Guide.

5   Check the desired Options.

  • Add -  The matching mode will be used and any record determined to be new will be added to Brick River.
  • Update - The matching mode will be used and existing records in Brick River will be updated.
  • Delete - BE VERY CAREFUL HERE - Any records in Brick River that do not match a record in the import file will be deleted.
  • Aggregate Relations. BE VERY CAREFUL HERE TOO -  This setting applies to fields which may store multiple values (Category and Relationship Fields).  Check to have any values in the import file  ADD TO existing values in fields.  Uncheck to have current values in fields DELETED AND REPLACED by values in the import file.  You almost always WANT to check this if you are importing Contacts with a SubscriptionList field.  If unchecked - Contacts may be removed from subscription lists they are currently on.  It is most often the case that you want Contacts left on current lists - and added to any additional lists included in the import file.

Click Save to save the document.


Using the Import Definition Document

Once you have saved the Import definition - you can open it to:

1 Edit Import settings.

2  Upload a csv file now - this link will allow you to select your import file, upload it to Brick River and perform the import.  An option to 'run in test mode' will process the import document without making any changes to Brick River content.  It will report to you the number of additions, updates, deletes and failures will result from running an actual import.

3 View fields and instructions - this link provides the URL needed to upload an import file from outside Brick River and a Field list with the Field Id of each field that may be included in the import.  Additional details for these options are found below.

4  Review log files of imports performed to date.  Links here proved the times and changes made to Brick River content for imports performed in the past.

View fields and instructions

 The View fields and instructions link provides the following information:

1 Data Syncing - the URL provided can be used to post .csv files to the correct Brick River URL to perform an import.

2  Columns - this table provides list of each file defined by the View that is used in the import process.  The Column Id field displays the values that must be used in the .csv header row to match import fields to Brick River fields. Other columns display details about each field.  Additional instructions on this document provide details regarding quoted text strings and multi-value fields.


Understanding External Source Name and Id

Each Brick River record may store a SourceName and SourceId field.  These fields are useful for synchronizing data between Brick River and an outside application.

For example, in Brick River I have Views to define Volunteers and Programs.  For some reason I also use an Access Database with a Volunteers table and Programs table.

In Brick River - volunteer Eric Zheng is a Contact with a record Id of '123456'.  This id is not displayed to users and may not be edited.  It is used by the Brick River system for a variety of system tasks.

In the Access database - Eric Zheng is in the Volunteer table with a Volunteer Id of 'VOL-55567'

Volunteer ID First Name Last Name
VOL-55567 Eric Zheng

 

In Brick River, Eric's record displays the Source Name and Source Id in the External Source section:

 

We can now run imports to update Brick River using the External Source matching method. 

For Example:

A .csv file contains the the following row:

Id FirstName LastName Email
VOL-55567 Eric Zheng ezheng@fakemail.com

 

The import uses Match External Id and the Source Name: AccessDatabase:

This import will update the FirstName, LastName, and Email address of Eric Zheng in Brick River.

NOTE that the Source Name must be used consistently and should point to the external system - not tables or other entities in that system.

In our example - both Volunteers and Programs should use the External Source Name: AccessDatabase.

This allows Brick River to maintain relationships between Volunteers and Programs using their Access record Id's. 

If different Source Names are used - AccessDatabase-Volunteers and AccessDatabase-Programs - then Brick River can not maintain the relationship between Volunteers and Programs using the Access record Id's.


Understanding Adding and Updating

The import process can be used to add, update, or delete records - or any combination of the three.

  • Adding records -  When the match method determines that a record in the import file does not exist in Brick River - a new record is added and populated with whatever field values are supplied in the import. 
  • Updating records - When the match method identifies an existing Brick River record.  The field values in the import file overwrite corresponding field values that exist in Brick River.  Fields not included in the import file are not updated.  Choose 'Aggregate Relations' to have values for multi-value fields ADD TO current field values rather than OVERWRITE existing values.
  • Deleting Records - Any records in Brick River that do not match a record in the import file are deleted.

Example:

A .csv file containing the following rows is imported to Brick River - matching on External Source Id and performing both ADD and UPDATE actions:

Id FirstName LastName PreferredName Email
1 J. Mesquite Banderlapaunch Tito j@brickriver.com
2 Pilkpo Chaucheegee Mike p@brickriver.com
3 Rick Dowripple Ricardo rick@brickriver.com


An edited .csv  is imported using the same settings:

Id FirstName LastName PreferredName Email Outcome
1 J. Mesquite Banderlapaunch Tito j@brickriver.com no change
2 Pikpo Chaucheegee Clarence p@brickriver.com PreferredName is updated
3 Rick Dowripple Ricardo rick@brickriver.com no change
4 Craggletoes Crump Wolf thewolf@brickriver.com this record would be added

 

 

BRICTIONARY

.csv- A file that stores information as 'comma separated values'.  Data is stored as simple rows and columns with minimal formatting

 

Want to learn more?

Call 800-924-5220 or

Schedule a demo