How can I custom implement the web-based TntConnect DataSync protocol?: Revision #40

This document describes how you can make your organization's online donation system compatible with TntConnect.  The technical details are spelled out so that you can provide your own custom solution.  It requires a knowledge of computer programming. 

You may want to consider DonorHub Online instead of creating, maintaining and hosting your own custom solution.  DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own custom solution.  DonorHub Online is a cloud-based service fully managed by TntWare that makes this process seamless, both for the staff on the field and the accounting team back in the office.  Plus, DonorHub Online can deliver donation data to many other support raising tools as well, such as MPDX, Karani or DonorElf.

If you'd like to learn more about how DonorHub Online can help you become compatible more quickly:
  Ask us about DonorHub Online.  

Once you are TntConnect-compatible, your staff will be able to use TntConnect to connect to your system to:

• Download contribution details
• Download names and addresses of donors
• Be notified of their staff account balance

Not only will your staff be able to use these features, but their application will be branded with your organization's logo.  Also, while they are using the "Web Input" 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:

What it takes...

• Query INI file
• Account Balance Query
• Donations Query
• Addresses Query
• Addresses By IDs Query
• Profiles Query (Optional) <new for TntConnect 2.0>
• Designations Query (Optional) <future: TntConnect 3.2>

Query INI File

You need to provide a Query INI File.  This file will provide the web address and parameter template needed to download the results of the query.  Below is an example.  Notice it is based on a standard Windows INI file format.

The benefit of keeping the instructions in this file is that if you later change the URL or POST template of your query, you can just edit the Query INI File and make a seamless transition.  The staff using the program will never know it changed.

TntConnect-version specific sections  <new for TntConnect 2.0>

TntConnect 2.0 and newer support version specific sections.  For example a client running TntConnect 3.0 will search for the "DONATION" section by using the first out of this list that it finds first with the requested value:

The Queries

--Placeholders--
Each query has a URL and a POST.  The URL specifies your online donation server object (CGI object, for example).  The POST specifies the data to send with the HTTP POST transaction.  The POST is in a template form.  These placeholders are key words that will be substituted by the appropriate string based on the user's input in TntConnect:

So for example, if I defined my Post value by:

Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$

And if my user name was "JohnDoe", and my password was "abc123" then the following data would be send with the HTTP POST transaction:

Action=TntBalance&Username=JohnDoe&Password=abc123

--Standard Response--
Each query should return its results as CSV text.  I will describe the
field names expected for each query.

--Error Response--
Each query should handle invalid conditions (such as an invalid username) by
returning two lines of text.  The first line of text should be "ERROR". 
The second line of text is the error description.  Here are a couple of
examples to give you the general idea.

Note for anyone consuming this api, some existing legacy servers may return errors using a different format, such as BAD_PASSWORD instead of ERROR, with a multi-line error description.

Account Balance Query

The purpose of this query is to simply return the staff account balance of the staff member submitting the request.  It only uses the $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders.

Example result:

Result in it's raw form just in case you are not familiar with the CSV format:

Field Descriptions:

Donations Query

The purpose of this query is to return all donation detail data for the staff member within a certain date range.  In addition to the usual $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders, it also uses $DATEFROM$ and $DATETO$.  Keep in mind that these placeholders come in the (M/D/YYYY) format.  The $DATEFROM$ and $DATETO$ placeholders describe the beginning and ending dates of the query.  You should include donation data for all dates between and including these dates.  The beginning date will be limited by the "MinimumWebGiftDate" value in the Query INI file.

Here's an example result:

Field Descriptions:

Addresses Query

The purpose of this query is to return detailed name, address and phone data for the staff member's donors.  In addition to the usual $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders, it also uses $DATEFROM$.  Keep in mind that this parameter comes in the (M/D/YYYY) format.  The $DATEFROM$ placeholder limits the address list to only those that have changed since the given date.  If the given date is blank, the user is requesting ALL addresses. 

Note: You may simply ignore the $DATEFROM$ parameter and return all addresses every time if you wish.  But keep in mind that this will generally increase the download time for the user.

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:

Addresses By IDs Query

This Query only differs from the Addresses Query in that it uses the $PERSONIDS$ parameter instead of the $DATEFROM$ parameter.  The $PERSONID$ parameter is substituted by a comma separated list of donor IDs.  These donor IDs are obtained from donations in the Donations Query.  TntConnect will never submit a request with more than 200 donor IDs.

Note: You may simply ignore the $PERSONIDS$ parameter and return all addresses every time if you wish.  But keep in mind that this will generally increase the download time for the user.

Profiles Query (Optional)   <new for TntConnect 2.0>

The purpose of this query is to return a list of different profiles associated with the user.  This allows a user to have different "modes" for downloading information, without having to setup different username/passwords for each mode.  This works especially well in a Single Sign On (SSO) environment.

Example result:

Field Descriptions:

Designations Query (Optional)   <future: TntConnect 3.2>

The purpose of this query is to simply return the designations of the staff member submitting the request.  It only uses the $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders.

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.

Testing your compatibility with TntConnect

To test your online donation system's compatibility with TntConnect, pull up the "Gift Input from Web" screen.  Where it has you choose your Organization, hold the "Shift" key down while you drop down the list and then choose "Custom".  Then you can simply type in the URL of your Query INI File.  That is all there is to it!

Making it easy for your staff to connect...

If you want to include your organization in the drop down list where you choose the Organization, just send me an email. (troy@tntware.com)  Be sure to include your organization's name, and the URL of your Query INI File.  I can update the list on my website, and your organization will automatically appear in the list.

Then when your staff member tries to do "Gift Input from Web" for the first time, they can just select your organization's name in the list.  It couldn't be much easier!