How can I custom implement the web-based TntConnect DataSync protocol?

TntWare — Tue, 04 Feb 2020 22:42:54 GMT

Current revision posted to Frequently Asked Questions by TntWare on 2/4/2020 10:42:54 PM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

If you're building an app to download donation information, then you're at the wrong place.
Instead, you should visit the Donor Hub API Developers Group.
It has documentation on how to write an app that downloads donation information.

Make your life easier! Instead of building it all yourself, take advantage of DonorHub Online DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own 4.0 no longer supports custom solution. TntWare makes this process seamless, both for the staff on the field and the accounting team back in the office.:
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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpUrl=mailto:test@test.com
OrgHelpUrlDescription=Click here to report this issue!
OrgHelpOther=You may also reach the Call Center at 111-222-3333.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[PROFILES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Where users can report errors with your download process.
OrgHelpUrl=mailto:test@test.com
OrgHelpUrlDescription=Click here to report this issue!
OrgHelpOther=You may also reach the Call Center at 111-222-3333.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

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.

The Queries

--Placeholders--
Each query has a URL and a POST. The URL specifies your online implemented 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:

$ACCOUNT$	The user name of the staff logging in to the system.
$PASSWORD$	The password of the staff logging in to the system.
$PROFILE$	The profile code of the staff logging in to the system. This comes from the Profiles query.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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

Profiles Query

The purpose of this query is to return a list of profiles associated with the user. A user might 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:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName	Type TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated 4.0 requires DonorHub for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) ongoing electronic inflow of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

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.

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 something your organization will automatically appear in the list.

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

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Sat, 16 Sep 2017 20:59:19 GMT

Revision 46 posted to Frequently Asked Questions by Troy Wolbrink on 9/16/2017 8:59:19 PM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

Note:

If you're building an app to help missionaries, and you want to download donor/gift donation information, then you're at the wrong place. You
Instead, you should visit the Donor Hub API Developers Group instead.
It has better documentation written from your perspectiveon how to write an app that downloads donation information.

Make your life easier! Instead of building it all yourself, take advantage of DonorHub Online DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own custom solution. TntWare makes this process seamless, both for the staff on the field and the accounting team back in the office.:
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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

Query INI File

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

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:

$ACCOUNT$	The user name of the staff logging in to the system.
$PASSWORD$	The password of the staff logging in to the system.
$PROFILE$	The profile code of the staff logging in to the system. This comes from the Profiles query.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

Example result:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

Donations Query

Here's an example result:

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync filewithout an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

Addresses Query

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:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

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.

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

Testing your compatibility with TntConnect

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Fri, 15 Sep 2017 01:06:23 GMT

Revision 45 posted to Frequently Asked Questions by Troy Wolbrink on 9/15/2017 1:06:23 AM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

Note: If you're building an app to help missionaries, and you want to download donor/gift information, you're at the wrong place. You should visit the Donor Hub API Developers Group instead. It has better documentation written from your perspective.

Make your life easier! Instead of building it all yourself, take advantage of DonorHub Online DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own custom solution. TntWare makes this process seamless, both for the staff on the field and the accounting team back in the office.:
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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

Query INI File

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

The Queries

$ACCOUNT$	The user name of the staff logging in to the system.
$PASSWORD$	The password of the staff logging in to the system.
$PROFILE$	The profile code of the staff logging in to the system. This comes from the Profiles query.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

Example result:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

Donations Query

Here's an example result:

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	BOOL	3.2	(Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

Addresses Query

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:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

Addresses By IDs Query

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.

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

Testing your compatibility with TntConnect

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Fri, 15 Sep 2017 01:05:18 GMT

Revision 44 posted to Frequently Asked Questions by Troy Wolbrink on 9/15/2017 1:05:18 AM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

Make your life easier! Instead of building it all yourself, take advantage of DonorHub Online DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own custom solution. TntWare makes this process seamless, both for the staff on the field and the accounting team back in the office.:
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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

Query INI File

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

The Queries

$ACCOUNT$	The user name of the staff logging in to the system.
$PASSWORD$	The password of the staff logging in to the system.
$PROFILE$	The profile code of the staff logging in to the system. This comes from the Profiles query.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

Example result:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

Donations Query

Here's an example result:

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	BOOL	3.2	(Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

Addresses Query

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:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

Addresses By IDs Query

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.

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

Testing your compatibility with TntConnect

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Fri, 15 Sep 2017 01:01:36 GMT

Revision 43 posted to Frequently Asked Questions by Troy Wolbrink on 9/15/2017 1:01:36 AM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

You may want to consider DonorHub Online instead

Make your life easier! Instead of creatingbuilding it all yourself, maintaining and hosting your own custom solution.take advantage of DonorHub Online 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.

If you'd like to learn more about how DonorHub Online can help you become compatible more quicklyoffice.:
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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

Query INI File

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

The Queries

$ACCOUNT$	The user name of the staff logging in to the donation system.
$PASSWORD$	The password of the staff logging in to the donation system.
$PROFILE$	<new for TntConnect 2.0>	The profile code of the staff logging in to the donation system. If This comes from the Profiles queryis not supported, this will always be blank. Note: The $PROFILE$ placeholder is never provided in the Profiles Query itself.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

Example result:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

Donations Query

Here's an example result:

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	BOOL	3.2	(Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

Addresses Query

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:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

Addresses By IDs Query

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.

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

Testing your compatibility with TntConnect

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Fri, 15 Sep 2017 00:58:29 GMT

Revision 42 posted to Frequently Asked Questions by Troy Wolbrink on 9/15/2017 12:58:29 AM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

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

What it takes...

Query INI file
Profiles Query
Account Balance Query
Donations Query
Addresses Query
Addresses By IDs Query

Query INI File

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

[PROFILES]
[ACCOUNT_BALANCE]
[DONATIONS]
[ADDRESSES]
[ADDRESSES_BY_PERSONIDS]

The Queries

$ACCOUNT$	The user name of the staff logging in to the donation system.
$PASSWORD$	The password of the staff logging in to the donation system.
$PROFILE$	<new for TntConnect 2.0> The profile code of the staff logging in to the donation system. If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$ placeholder is never provided in the Profiles Query itself.
$DATEFROM$	The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$	The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$	A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

The purpose of this query is to return a list of different profiles associated with the user. This allows a A user to might 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:

PROFILE_CODE	PROFILE_DESCRIPTION
	Staff Account (Default)
MIN1	Operating Account #1
MIN2	Operating Account #2

Field Descriptions:

FieldName	Description
PROFILE_CODE	(A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION	(A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID	ACCT_NAME	BALANCE
12345678	Doe, John & Jane	1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName	Description
EMPLID	Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME	List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE	(Text) Custom text that describes the user's account balance.

Donations Query

Here's an example result:

Field Descriptions:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	BOOL	3.2	(Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

Addresses Query

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:

FieldName	Type	TntConnect Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
INFO_URL	MEMO	3.0	URL to view/edit donor information.
RELATED_IDS	MEMO	3.0	A comma seperated list of related donor codes/ids.
DECEASED	BOOL	3.0	Blank implies "FALSE". Is the donor deceased?
PERSON_TYPE	A1		"O" or "P" (Organization or Person)
LAST_NAME_ORG	A50		Last Name or Organization Name
ORG_CONTACT_PERSON	A50	3.0	[PERSON_TYPE="O"] Contact person for this organization.
TITLE	A25		[PERSON_TYPE="P"] Title (Mr., Mrs.)
FIRST_NAME	A25		[PERSON_TYPE="P"] First Name
MIDDLE_NAME	A25		[PERSON_TYPE="P"] Middle Name
SUFFIX	A25		[PERSON_TYPE="P"] Suffix (Jr., Sr.)
SP_TITLE	A25		[PERSON_TYPE="P"] for spouse
SP_FIRST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_MIDDLE_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_LAST_NAME	A25		[PERSON_TYPE="P"] for spouse
SP_SUFFIX	A25		[PERSON_TYPE="P"] for spouse Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1	MEMO		Street Address (Line 1)
ADDR2	MEMO		Street Address (Line 2)
ADDR3	MEMO		Street Address (Line 3)
ADDR4	MEMO		Street Address (Line 4)
CITY	A50		City
STATE	A50		State
ZIP	A25		Postal Code
COUNTRY	A3		(A3) ISO 3166 Alpha 3 country code <new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR	A50		Name of country.
ADDR_CHANGED	DATE		When the address was last changed.
PHONE	A50		Phone number.
PHONE_CHANGED	DATE		When the phone was last changed.
MOBILE_PHONE	A50	3.0	Mobile phone number.
MOBILE_PHONE_CHANGED	DATE	3.0	When the mobile phone was last changed.
SP_MOBILE_PHONE	A50	3.0	Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED	DATE	3.0	When the spouse mobile phone was last changed.
EMAIL	MEMO	3.0	Email address.
EMAIL_CHANGED	DATE	3.0	When the email address was last changed.
SP_EMAIL	MEMO	3.0	Spouse email address.
SP_EMAIL_CHANGED	DATE	3.0	When the spouse email address was last changed.
MEMO	MEMO	3.0	A note regarding the donor.

Addresses By IDs Query

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.

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

Testing your compatibility with TntConnect

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Fri, 15 Sep 2017 00:57:03 GMT

Revision 41 posted to Frequently Asked Questions by Troy Wolbrink on 9/15/2017 12:57:03 AM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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
Profiles Query
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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpUrl=mailto:test@test.com
OrgHelpUrlDescription=Click here to report this issue!
OrgHelpOther=You may also reach the Call Center at 111-222-3333.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]PROFILES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalanceAction=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[ACCOUNT_BALANCE.2]ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify a url where Where users can report errors with your download process.
OrgHelpUrl=mailto:test@test.com

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the Call Center at 111-222-3333.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$PROFILES]
[ACCOUNT_BALANCE.2]ACCOUNT_BALANCE]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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.

Profiles Query

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:

PROFILE_CODE
PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time , but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the usersees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Thu, 14 Sep 2017 22:48:52 GMT
Revision 40 posted to Frequently Asked Questions by Troy Wolbrink on 9/14/2017 10:48:52 PM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htmmailto:test@test.com
OrgHelpUrlDescription=Click here to report this issueover the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948111-222-3333.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htmmailto:test@test.com

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issueover the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at407-826-2948 111-222-3333.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Thu, 14 Sep 2017 19:57:24 GMT
Revision 39 posted to Frequently Asked Questions by Troy Wolbrink on 9/14/2017 7:57:24 PM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Thu, 06 Oct 2016 17:37:03 GMT
Revision 38 posted to Frequently Asked Questions by Troy Wolbrink on 10/6/2016 5:37:03 PM

How can I custom implement the web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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 use an existing cloud service so that you learn more about how DonorHub Online can help you become TNT-compatible compatible more quickly:
[[en:How can my organization become "TNT-compatible"?|How can my organization become "TNT-compatible"?]]
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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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!

How can I custom implement the web-based TntConnect DataSync protocol?

Troy Wolbrink — Thu, 22 Sep 2016 05:02:51 GMT
Revision 37 posted to Frequently Asked Questions by Troy Wolbrink on 9/22/2016 5:02:51 AM

How can I custom implement the web-baesd web-based TntConnect DataSync protocol?

Filed under: Developer Guides

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.

If you'd like to use an existing cloud service so that you can become TNT-compatible more quickly:
[[en:How can my organization become "TNT-compatible"?|How can my organization become "TNT-compatible"?]]

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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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!

How can I custom implement the web-baesd TntConnect DataSync protocol?

Troy Wolbrink — Thu, 22 Sep 2016 05:02:41 GMT
Revision 36 posted to Frequently Asked Questions by Troy Wolbrink on 9/22/2016 5:02:41 AM

How can I custom implement the web-baesd TntConnect DataSync protocol?

Filed under: Developer Guides

This document describes how you can make your organization's online donation system compatible with TntMPDTntConnect. The technical details are spelled out so that you can provide your own custom solution. It requires a knowledge of computer programming. Keep in mind that the preferred and recommended way to provide a TntMPD-compatible download for your staff is to use TntMPD.DataServer. TntMPD.DataServer already includes pre-built integration templates for DonorWise, Raiser

If you's Edge and OPTIGEM. Tools and documentation are provided d like to allow use an existing cloud service so that you to integrate TntMPD.DataServer with your own donation system.can become TNT-compatible more quickly:
[[en:How can my organization become "TNT-compatible"?|How can my organization become "TNT-compatible"?]]

Once you are TntMPD-compatibleTntConnect-compatible, your staff will be able to use TntMPD TntConnect to connect to your system using the Web 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 TntMPDTntConnect, 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 TntMPD TntConnect 2.0>

Designations Query (Optional) <future: TntMPD 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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntMPDTntConnect
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntMPD TntConnect checks, allows for permanent redirection of TntMPD TntConnect to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntMPDTntConnect. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntMPD TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntMPD TntConnect will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntMPD TntConnect 2.1.68> indicates if TntMPD TntConnect can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntMPD TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntMPD TntConnect requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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.

TntMPD-version

TntConnect-version specific sections <new for TntMPD TntConnect 2.0>

TntMPD

TntConnect 2.0 and newer support version specific sections. For example a client running TntMPD 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:

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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 TntMPDTntConnect:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntMPD TntConnect 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntMPD TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntMPD TntConnect Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntMPD TntConnect 2.0> ISO 3166 Alpha 2 country codes are supported in TntMPD TntConnect 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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. TntMPD 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 TntMPD 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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Designations Query (Optional)   <future: TntMPD 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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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 TntMPD 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

TntMPD
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 TntMPD 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 TntMPDTntConnect's perspective. Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntMPD TntConnect or it will overwrite the one donation with the other.

Testing your compatibility with TntMPDTntConnect

To test your online donation system's compatibility with TntMPDTntConnect, 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 "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!

How can I custom implement the web-baesd TntConnect DataSync protocol?

Troy Wolbrink — Thu, 22 Sep 2016 04:54:32 GMT
Revision 35 posted to Frequently Asked Questions by Troy Wolbrink on 9/22/2016 4:54:32 AM

How can I make my organization's online donation system compatible with TntMPDcustom implement the web-baesd TntConnect DataSync protocol?

Filed under: Developer Guides

This document describes how you can make your organization's online donation system compatible with TntMPD. The technical details are spelled out so that you can provide your own custom solution. It requires a knowledge of computer programming. Keep in mind that the preferred and recommended way to provide a TntMPD-compatible download for your staff is to use TntMPD.DataServer. TntMPD.DataServer already includes pre-built integration templates for DonorWise, Raiser's Edge and OPTIGEM. Tools and documentation are provided to allow you to integrate TntMPD.DataServer with your own donation system.

Once you are TntMPD-compatible, your staff will be able to use TntMPD to connect to your system using the Web 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 TntMPD, 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 TntMPD 2.0>

Designations Query (Optional) <future: TntMPD 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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntMPD
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntMPD checks, allows for permanent redirection of TntMPD to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntMPD. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntMPD internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntMPD will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntMPD 2.1.68> indicates if TntMPD can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntMPD 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntMPD requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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.

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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 TntMPD:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntMPD 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntMPD 2.0> ISO 3166 Alpha 2 country codes are supported in TntMPD 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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. TntMPD 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 TntMPD 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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Designations Query (Optional)   <future: TntMPD 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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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 TntMPD 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

TntMPD 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 TntMPD 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 TntMPD's perspective. Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntMPD or it will overwrite the one donation with the other.

Testing your compatibility with TntMPD

To test your online donation system's compatibility with TntMPD, pull up the "Gift Input from Web" screen. Where it has you choose your Organization, 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!

How can I make my organization's online donation system compatible with TntMPD?

Troy Wolbrink — Fri, 13 Nov 2015 01:06:59 GMT
Revision 34 posted to Frequently Asked Questions by Troy Wolbrink on 11/13/2015 1:06:59 AM

How can I make my organization's online donation system compatible with TntMPD?

Filed under: Developer Guides

This document describes how you can make your organization's online donation system compatible with TntMPD. The technical details are spelled out so that you can provide your own custom solution. It requires a knowledge of computer programming. Keep in mind that the preferred and recommended way to provide a TntMPD-compatible download for your staff is to use TntMPD.DataServer. TntMPD.DataServer already includes pre-built integration templates for DonorWise, Raiser's Edge and OPTIGEM. Tools and documentation are provided to allow you to integrate TntMPD.DataServer with your own donation system.

Once you are TntMPD-compatible, your staff will be able to use TntMPD to connect to your system using the Web 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 TntMPD, 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 TntMPD 2.0>

Designations Query (Optional) <future: TntMPD 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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntMPD
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntMPD checks, allows for permanent redirection of TntMPD to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntMPD. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntMPD internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntMPD will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntMPD 2.1.68> indicates if TntMPD can attempt logging in while user types password.
AllowPassiveAuth=True

/// <new for TntMPD 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntMPD requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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.

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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 TntMPD:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntMPD 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

SSo

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.

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntMPD 2.0> ISO 3166 Alpha 2 country codes are supported in TntMPD 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

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. TntMPD 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 TntMPD 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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Designations Query (Optional)   <future: TntMPD 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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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 TntMPD 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

TntMPD 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 TntMPD 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 TntMPD's perspective. Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntMPD or it will overwrite the one donation with the other.

Testing your compatibility with TntMPD

To test your online donation system's compatibility with TntMPD, pull up the "Gift Input from Web" screen. Where it has you choose your Organization, 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@wolbrinkfamily.com 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!

How can I make my organization's online donation system compatible with TntMPD?

Troy Wolbrink — Fri, 13 Nov 2015 01:05:57 GMT
Revision 33 posted to Frequently Asked Questions by Troy Wolbrink on 11/13/2015 1:05:57 AM

How can I make my organization's online donation system compatible with TntMPD?

Filed under: Developer Guides

This document describes how you can make your organization's online donation system compatible with TntMPD. The technical details are spelled out so that you can provide your own custom solution. It requires a knowledge of computer programming. Keep in mind that the preferred and recommended way to provide a TntMPD-compatible download for your staff is to use TntMPD.DataServer. TntMPD.DataServer already includes pre-built integration templates for DonorWise, Raiser's Edge and OPTIGEM. Tools and documentation are provided to allow you to integrate TntMPD.DataServer with your own donation system.

Once you are TntMPD-compatible, your staff will be able to use TntMPD to connect to your system using the Web 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 TntMPD, 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 TntMPD 2.0>

Designations Query (Optional) <future: TntMPD 3.13.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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntMPD
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntMPD checks, allows for permanent redirection of TntMPD to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntMPD. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntMPD internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntMPD will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntMPD 2.1.68> indicates if TntMPD can attempt logging in while user types password.
AllowPassiveAuth=True

/// <future: <new for TntMPD 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntMPD requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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.

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.3.1]

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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 TntMPD:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntMPD 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.1 3.2 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntMPD 2.0> ISO 3166 Alpha 2 country codes are supported in TntMPD 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

[GIFTS]

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

Here's an example result:

[GIFTS]
"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

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. TntMPD 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 TntMPD 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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Designations Query (Optional)   <future: TntMPD 3.13.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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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 TntMPD 3.1also accepts > the YYYY-MM-DD formatformat).

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

TntMPD 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 TntMPD 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 TntMPD's perspective. Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntMPD or it will overwrite the one donation with the other.

Testing your compatibility with TntMPD

To test your online donation system's compatibility with TntMPD, pull up the "Gift Input from Web" screen. Where it has you choose your Organization, 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@wolbrinkfamily.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!

How can I make my organization's online donation system compatible with TntMPD?

Troy Wolbrink — Thu, 12 Nov 2015 18:23:23 GMT
Revision 32 posted to Frequently Asked Questions by Troy Wolbrink on 11/12/2015 6:23:23 PM

How can I make my organization's online donation system compatible with TntMPD?

Filed under: Developer Guides

This document describes how you can make your organization's online donation system compatible with TntMPD. The technical details are spelled out so that you can provide your own custom solution. It requires a knowledge of computer programming. Keep in mind that the preferred and recommended way to provide a TntMPD-compatible download for your staff is to use TntMPD.DataServer. TntMPD.DataServer already includes pre-built integration templates for DonorWise, Raiser's Edge and OPTIGEM. Tools and documentation are provided to allow you to integrate TntMPD.DataServer with your own donation system.

Once you are TntMPD-compatible, your staff will be able to use TntMPD to connect to your system using the Web 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 TntMPD, 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 TntMPD 2.0>

Designations Query (Optional) <future: TntMPD 3.1>

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.

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html
MinimumWebGiftDate=1/1/1990
Code=MyOrg-USA
QueryAuthentication=0
MinPidLength=0
OrgHelpEmail=help@myorg.org
OrgHelpUrl=https://www.myorg.org/help.htm
OrgHelpUrlDescription=Click here to report this issue over the Web!
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
StaffPortalUrl=http://myorg.org/staffportal.html
BaseCurrencyCode
DefaultCurrencyCode=USD
AllowPassiveAuth=True

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[ADDRESSES]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$

[ADDRESSES.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&Persons=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&Persons=$PERSONIDS$

[PROFILES.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$
[DESIGNATIONS.3]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

Now let me explain the meaning of each value...

[APPLICATION]
/// Minimum and recommended versions of TntMPD
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
/// Very first thing TntMPD checks, allows for permanent redirection of TntMPD to new query.ini url
RedirectQueryIni=

/// Specify the name of your organization here.
Name=Your Organization Name

/// Specify a short abbreviation of your organization here.
Abbreviation=MyOrg

/// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg

/// URL to help your staff get setup with an account.
AccountHelpUrl=http://www.myorg.org/staffaccounthelp.html

/// URL of your banner ad.
BannerAdUrl-468x60=http://www.myorg.org/bannerad.html

/// Boundary of how back your online donation system provides data for. (DATE)
MinimumWebGiftDate=1/1/1990

/// Unique code to represent your ministry internally to TntMPD. (25 chars max! User never sees this.)
Code=MyOrg-USA

/// Set this to "1" if you want the queries to use basic HTTP authentication
QueryAuthentication=0

/// TntMPD internally removes leading zeros from numeric donor account ids. Specify the minimum number
/// of digits a donor id should be, and TntMPD will add leading zeros when returning them back in the
/// "Addresses By IDs Query" query.
MinPidLength=0

/// Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org

/// Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm

/// Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!

/// Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the CCC Call Center at 407-826-2948.

/// Specify the url where users can request new user profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm

/// Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html

/// <new for TntMPD 2.1.68> indicates if TntMPD can attempt logging in while user types password.
AllowPassiveAuth=True

/// <future: TntMPD 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts
BaseCurrencyCode
DefaultCurrencyCode=USD

/// The rest of these sections describe Web Queries. A Web Query has a Url and a Post.
/// The Url is where TntMPD requests data.
/// The Post is a template of query encoded parameters that get POST-ed to the URL.
/// More information is provided below to describe the details.

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$
[ACCOUNT_BALANCE.2]
[DONATIONS]
[DONATIONS.2]
[ADDRESSES]
[ADDRESSES.2]
[ADDRESSES_BY_PERSONIDS]
[ADDRESSES_BY_PERSONIDS.2]
[PROFILES.2]
[DESIGNATIONS.3]

Some values in the query.ini are undocumented above becuase they have been deprecated. This means that they are no longer supported. Here's a list of these values:

[ORGANIZATION] WebLogo-JPEG-476x100

[ORGANIZATION] WebPortalUrl-470x120

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.

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.3]

[DONATIONS.2.1]

[DONATIONS.2.0]

[DONATIONS.2]

[[DONATIONS]

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 TntMPD:

$ACCOUNT$ The user name of the staff logging in to the donation system.

$PASSWORD$ The password of the staff logging in to the donation system.

$PROFILE$ <new for TntMPD 2.0> The profile code of the staff logging in to the donation system.
If the Profiles query is not supported, this will always be blank. Note: The $PROFILE$
placeholder is never provided in the Profiles Query itself.

$DATEFROM$ The specified beginning date. (M/D/YYYY) (I'll explain later where and how this is used.)

$DATETO$ The specified ending date. (M/D/YYYY) (I'll explain later where and how this is used.)

$PERSONIDS$ A comma separated list of donor IDs. (I'll explain later where and how this is used.)

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

EMPLID ACCT_NAME BALANCE

12345678 Doe, John & Jane 1225.30

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

EMPLID,ACCT_NAME,BALANCE
12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description

EMPLID Comma separated list of designation ids (A18) associated with this user/profile.

ACCT_NAME List of designation account names (A50) associated with this user. Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.

BALANCE (Text) Custom text that describes the user's account balance.

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:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

DISPLAY_DATE DATE Date of contribution

AMOUNT FLOAT Amount of contribution

DONATION_ID A18 Donation Code/ID

DESIGNATION A18 What account this donation is designated for (normally same as employee id)

MOTIVATION A18 (Optional) If you track this in your donation system you may include this code here.

PAYMENT_METHOD A18 3.0 (Optional) Payment method of this donation.

MEMO MEMO 3.0 (Optional) Any comments associated with this gift.

TENDERED_AMOUNT FLOAT 3.1 (Optional) Amount of donation as tendered by donor.
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.

TENDERED_CURRENCY A3 3.1 (Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.

BASE_CURRENCY A3 3.1 (Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "BaseCurrencyCode" "DefaultCurrencyCode" should be defined once in the [Organization] section.

PERSONAL BOOL 3.1 (Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Type TntMPD Version Description

PEOPLE_ID A18 Donor Code/ID

ACCT_NAME A50 Donor full name

INFO_URL MEMO 3.0 URL to view/edit donor information.

RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.

DECEASED BOOL 3.0 Blank implies "FALSE". Is the donor deceased?

PERSON_TYPE A1 "O" or "P" (Organization or Person)

LAST_NAME_ORG A50 Last Name or Organization Name

ORG_CONTACT_PERSON A50 3.0 [PERSON_TYPE="O"]
Contact person for this organization.

TITLE A25 [PERSON_TYPE="P"] Title (Mr., Mrs.)

FIRST_NAME A25 [PERSON_TYPE="P"] First Name

MIDDLE_NAME A25 [PERSON_TYPE="P"] Middle Name

SUFFIX A25 [PERSON_TYPE="P"] Suffix (Jr., Sr.)

SP_TITLE A25 [PERSON_TYPE="P"] for spouse

SP_FIRST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_MIDDLE_NAME A25 [PERSON_TYPE="P"] for spouse

SP_LAST_NAME A25 [PERSON_TYPE="P"] for spouse

SP_SUFFIX A25 [PERSON_TYPE="P"] for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.

ADDR1 MEMO Street Address (Line 1)

ADDR2 MEMO Street Address (Line 2)

ADDR3 MEMO Street Address (Line 3)

ADDR4 MEMO Street Address (Line 4)

CITY A50 City

STATE A50 State

ZIP A25 Postal Code

COUNTRY A3 (A3) ISO 3166 Alpha 3 country code
<new in TntMPD 2.0> ISO 3166 Alpha 2 country codes are supported in TntMPD 2.0.

CNTRY_DESCR A50 Name of country.

ADDR_CHANGED DATE When the address was last changed.

PHONE A50 Phone number.

PHONE_CHANGED DATE When the phone was last changed.

MOBILE_PHONE A50 3.0 Mobile phone number.

MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.

SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.

SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.

EMAIL MEMO 3.0 Email address.

EMAIL_CHANGED DATE 3.0 When the email address was last changed.

SP_EMAIL MEMO 3.0 Spouse email address.

SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.

MEMO MEMO 3.0 A note regarding the donor.

[GIFTS]

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

Here's an example result:

[GIFTS]
"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

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. TntMPD 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 TntMPD 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:

PROFILE_CODE PROFILE_DESCRIPTION

Staff Account (Default)

MIN1 Operating Account #1

MIN2 Operating Account #2

Field Descriptions:

FieldName Description

PROFILE_CODE (A18) A code to identify this profile. A blank profile code would be the default profile associated with the account. Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.

PROFILE_DESCRIPTION (A50) A description of the profile. This is what the user sees. Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Designations Query (Optional)   <future: TntMPD 3.1>

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:

DESIG_ID DESIG_NAME ORG_PATH

12345678 Doe, John & Jane /CAMPUS/STAFF/

Field Descriptions:

FieldName Description

DESIG_ID (A18) Designation id associated with this user/profile.

DESIG_NAME (A50) Designation account name associated with this user.

ORG_PATH (Text) Where this designation fits in the organizational tree.

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. TntMPD 3.1 also accepts 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

TntMPD 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 TntMPD 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 TntMPD's perspective. Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntMPD or it will overwrite the one donation with the other.

Testing your compatibility with TntMPD

To test your online donation system's compatibility with TntMPD, pull up the "Gift Input from Web" screen. Where it has you choose your Organization, 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@wolbrinkfamily.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!

DESIG_ID	DESIG_NAME	ORG_PATH
12345678	Doe, John & Jane	/CAMPUS/STAFF/

FieldName	Type	TntMPD Version	Description
PEOPLE_ID	A18		Donor Code/ID
ACCT_NAME	A50		Donor full name
DISPLAY_DATE	DATE		Date of contribution
AMOUNT	FLOAT		Amount of contribution
DONATION_ID	A18		Donation Code/ID
DESIGNATION	A18		What account this donation is designated for (normally same as employee id)
MOTIVATION	A18		(Optional) If you track this in your donation system you may include this code here.
PAYMENT_METHOD	A18	3.0	(Optional) Payment method of this donation.
MEMO	MEMO	3.0	(Optional) Any comments associated with this gift.
TENDERED_AMOUNT	FLOAT	3.1	(Optional) Amount of donation as tendered by donor. You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY	A3	3.1	(Optional) Currency code (ISO 4217 3-char) of donation as tendered by donor. You may leave this blank if it is the same as the default currency code from the query.ini file.
BASE_CURRENCY	A3	3.1	(Optional) Base currency code (ISO 4217 3-char) of donation as represented by AMOUNT. The only case where it is valid to provide a value for this field is when importing a DataSync file without an [Organization] section. Apart from this exception, this field is not to be used. Instead, "DefaultCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	BOOL	3.2	(Optional) Blank implies "FALSE". Indicates if the gift is intended to be a personal gift for the staff member (which usually means it's not tax deductible).

FieldName	Description
DESIG_ID	(A18) Designation id associated with this user/profile.
DESIG_NAME	(A50) Designation account name associated with this user.
ORG_PATH	(Text) Where this designation fits in the organizational tree.