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

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.  It might require technical skills to create this file.  This a file you could securely deliver to your staff.  But we recommended that you NOT send sensitive donor data over email!

Security Warning:  Sending donor and giving information over email is not secure.  You risk exposing your donor's private information and subjecting them to identity theft and loss of privacy.

Usability Warning:  Sending your staff DataSync files is less than ideal.  A much better approach is to use DonorHub Online.  DonorHub is a secure, cloud-based service that allows your staff to simply push a button to download their latest giving information.  TntWare does all the difficult technical part of making this work!  If you'd like to learn more about how DonorHub Online can help you: 
  Ask us about DonorHub Online

Technical Details

A TntConnect DataSync file has the file name extension *.tntdatasync.  So for example you may send your staff a file called "January2017.tntdatasync".  TntConnect only recognizes this file extension. 

Note that as of TntConnect 3.4, TntConnect only recognizes the .tntdatasync extension.  TntConnect 3.4 and newer no longer recognizes .tnt or .tntmpd.  Also TntConnect 3.4 requires the [ORGANIZATION] section.

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]. 

The [ORGANIZATION] section is required.  You must also provide the [GIFTS] section and/or the [DONORS] section.

Here's a sample of a DataSync file:
https://download.tntware.com/tntconnect/sample_data_sync_file/sample.tntdatasync

[ORGANIZATION]

The organization section is required and it 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).

If you are using the sample file for inspiration, you must change the Code from "Sample-Organization-USA" to something else!  This should be a unique code that identifies your organization.  25 characters max.

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

[FILE]

The file section has information specific to this file. 

<new in TntConnect 3.5.15> GiftsDateFrom and GiftsDateTo represent the date range TntConnect uses when synchronizing gifts in the [GIFTS] section.  The [GIFTS] section is expected to include all gifts for this user within the date range.  If TntConnect has gifts within this data range, but they are not included in the file, TntConnect might prompt the user to delete them, so as to stay in sync with the organization.

[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".)

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.

Staying Informed of Changes 

Announcements are made to the Beta Testers group when new versions of TntConnect are released to the beta testing phase.  If there are any changes to the DataSync protocol you must know of to remain compatible, these changes will be announced here.  If you'd like to receive an email when an announcement is made, you need to "Subscribe to this group" by clicking the link on the left side.  Here's a screenshot: