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:
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.
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.
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.
5 Check the desired Options.
Click Save to save the 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.
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.
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|
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.
A .csv file contains the the following row:
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.
The import process can be used to add, update, or delete records - or any combination of the three.
A .csv file containing the following rows is imported to Brick River - matching on External Source Id and performing both ADD and UPDATE actions:
An edited .csv is imported using the same settings:
|1||J. Mesquite||Banderlapaunch||Titoemail@example.com||no change|
|2||Pikpo||Chaucheegee||Clarencefirstname.lastname@example.org||PreferredName is updated|
|4||Craggletoes||Crump||Wolfemail@example.com||this record would be added|