How would I send our staff a monthly TntConnect DataSync file?: Revision #41

Sometimes an example is worth a thousand words.  So, real quick, open these sample files in Excel, then keep reading:

Here's a sample of a Donors-Only csv file:
http://download.tntware.com/TntConnect/sample_data_sync_file/sample-donors.csv 

Here's a sample of a Gifts-Only csv file:
http://download.tntware.com/TntConnect/sample_data_sync_file/sample-gifts.csv

Here's a sample of a comprehensive DataSync file (with the ".tntdatasync" file name extension):
http://download.tntware.com/sample_data_sync_file/sample.TntConnect

This document describes how you can take data from your organization's donation system and package it in a way that is compatible with TntConnect.  The file you create is called a TntConnect DataSync file.  Once you make this file available to your individual staff member (such as via an email attachment) your staff will be able to bring their donation data into TntConnect.  The type of data you can put into a DataSync file includes:

• Download contribution details
• Download names and addresses of donors

Not only will your staff be able to use these features, but their application will be branded with your organization's logo and name.  Also, while they are using the "Gift and Address Input from File" features of TntConnect, you can display your own advertisement/announcement banner.

This is an example of the logo you can provide:

This is an example of the advertising banner you can provide:

Technical Details

A TntConnect DataSync file has the file name extension *.tntdatasync.  So for example you may send your staff a file called "January2002.tntdatasync".  TntConnect recognizes this file format which makes it incredibly easy for your staff to get started.  All they need to do is double-click the file and open it.  Since *.tntdatasyncis a registered filename extension, Windows will tell TntConnect to open it.

The DataSync file is synchronized with the currently opened database.  Because the data is synchronized, you can input the file several times into the same database without duplicating data in the database.

The DataSync file has up to three sections.  The sections are:

• [ORGANIZATION]
• [DONORS]
• [GIFTS]. 

<future: TntConnect 3.2> Supported sections will also include (to be described later): 

• [APPLICATION]
• [FILE]
• [DESIGNATIONS]
• [GIFTS_BY_DONORS].

An example is listed below.  (The complete version is available here.)

[ORGANIZATION]

The organization section has information about your organization.  Here you can specify your organization's name, abbreviation and logo (JPEG only).  In addition you can specify an announcement banner that the user sees while they import the file.  The last item is code.  Try to think of a unique code to represent your ministry (25 chars max).

<new in TntConnect 3.1> DefaultCurrencyCode specifies the base currency code (ISO 4217 3-char) for donations represented in the [GIFTS] section.

[DONORS]

The donors section has name, address and phone information about donors.  All fields are optional (column header must exist, but data can be blank) except PEOPLE_ID and ACCT_NAME.

Here's an example result:

Field Descriptions:

[GIFTS]

The gifts section has detailed contribution information over a particular date range.

Here's an example result:

Field Descriptions:

Data Types Explained

• A25, a text column with a maximum of 25 characters

• MEMO, a text column with no predefined length limits

• DATE, a date formatted as M/D/YYYY (or  <new in TntConnect 3.1> the YYYY-MM-DD format).

• BOOL, a boolean as "TRUE" or "FALSE"

• FLOAT, a floating point number.  Currency symbols or thousands separators are not allowed.  The decimal separator must be a period.

(Note: for all types, leading and trailing spaces are removed from the value.  So "  ABC  " is always trimmed down to just "ABC".)

Really Simple Option

One way to make this work is to provide just the [DONORS] or [GIFTS] section in a file (minus the section header).  TntConnect will recognize that a single section is being provided.

For example, TntConnect would recognize this as being a [DONORS] section:

And for another example, TntConnect would recognize this as being a [GIFTS] section:

Here's a sample of a Donors-Only csv file:
http://download.tntware.com/TntConnect/sample_data_sync_file/sample-donors.csv 

Here's a sample of a Gifts-Only csv file:
http://download.tntware.com/TntConnect/sample_data_sync_file/sample-gifts.csv

Case Insensitivity

TntConnect will store designation ids, donor ids and donation ids exactly as it is received.  (Leading zeros will be removed from numeric donor ids.)  But internally when TntConnect is syncing incoming data, it will match up these ids in a case insensitive way.  So a donation id of "ABC" and "abc" are the same from TntConnect's perspective.  Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntConnect or it will overwrite the one donation with the other.