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

Troy Wolbrink — Wed, 01 Feb 2012 19:09:03 GMT

Current revision posted to Frequently Asked Questions (English) by Troy Wolbrink on 2/1/2012 2:09:03 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 2.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-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=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$&DateFrom=$DATEFROM$

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

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

[DESIGNATIONS.2.2]
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]
// You can require a minimum version of TntMPD for Web Input features.
MinimumVersion=1.5.0
// You can recommend a minimum version of TntMPD for Web Input features if you wish.
RecommendedVersion=1.5.0

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$  // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder
                                                                                               // included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[DESIGNATIONS.2.2]   <future: TntMPD 2.2>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

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 will support version specific sections. For example a client running TntMPD 2.2 will search for the "DONATION" section by using the first out of this list that it finds first:

[DONATIONS.2.2]
[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 writing a front-end: 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	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

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	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor deceased
LAST_NAME_ORG	Last Name or Organization Name
ORG_CONTACT_PERSON	<future: TntMPD 2.2> When it's an organization (PERSON_TYPE="O"), who is the contact person for this organization?
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MOBILE_PHONE	<future: TntMPD 2.2> Mobile phone number.
MOBILE_PHONE_CHANGED	<future: TntMPD 2.2> (M/D/YYYY) When the mobile phone was last changed.
MOBILE_PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
SPOUSE_MOBILE_PHONE	<future: TntMPD 2.2> Spouse mobile phone number.
SPOUSE_MOBILE_PHONE_CHANGED	<future: TntMPD 2.2> (M/D/YYYY) When the spouse mobile phone was last changed.
SPOUSE_MOBILE_PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
SPOUSE_EMAIL	<future: TntMPD 2.2> Email address.
SPOUSE_EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
SPOUSE_EMAIL_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

[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 2.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.

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". (Note: You must hold down the Shift key when you drop down the list.) 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. (wolbrink@ccci.org) 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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Tue, 24 Jan 2012 20:08:23 GMT

Revision 18 posted to Frequently Asked Questions (English) by Troy Wolbrink on 1/24/2012 3:08:23 PM

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

Filed under: Developer Guides

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

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

Query INI File

[DESIGNATIONS.2.2]
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...

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE
ADDR_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL
PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MOBILE_PHONE	<future: TntMPD 2.2> Mobile phone number.
MOBILE_PHONE_CHANGED	<future: TntMPD 2.2> (M/D/YYYY) When the mobile phone was last changed.
MOBILE_PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
SPOUSE_MOBILE_PHONE	<future: TntMPD 2.2> Spouse mobile phone number.
SPOUSE_MOBILE_PHONE_CHANGED	<future: TntMPD 2.2> (M/D/YYYY) When the spouse mobile phone was last changed.
SPOUSE_MOBILE_PHONE_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL
EMAIL_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO
SPOUSE_EMAIL	<future: TntMPD 2.2> Email address.
SPOUSE_EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
SPOUSE_EMAIL_VALID	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 21:35:22 GMT

Revision 17 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 5:35:22 PM

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

Filed under: Developer Guides

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

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

Query INI File

[DESIGNATIONS.2.2]
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...

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 21:24:38 GMT

Revision 16 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 5:24:38 PM

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

Filed under: Developer Guides

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

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

Query INI File

[DESIGNATIONS.2.2]
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...

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 21:10:06 GMT

Revision 15 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 5:10:06 PM

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

Filed under: Developer Guides

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

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

Query INI File

[DESIGNATIONS.2.2]
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...

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

TntMPD will store designation ids, donor ids and donation ids exactly as it is received. 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

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 21:09:33 GMT

Revision 14 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 5:09:33 PM

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

Filed under: Developer Guides

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

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

Query INI File

[DESIGNATIONS.2.2]
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...

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your
// Donations Query.
BaseCurrencyCode=USD
// <new for TntMPD 2.1.68> indicates if TntMPD is allowed to attempt logging in while user types password.
AllowPassiveAuth=True
[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$  // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder
                                                                                               // included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[DESIGNATIONS.2.2]   <future: TntMPD 2.2>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 20:13:45 GMT

Revision 13 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 4:13:45 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=USD

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

[DESIGNATIONS.2.2]
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...

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old Old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// 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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your
// Donations Query.
BaseCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$   &Username=$ACCOUNT$&Password=$PASSWORD$  // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder
                                                                                               // included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[DESIGNATIONS.2.2]   <future: TntMPD 2.2>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 03 Oct 2011 20:06:02 GMT

Revision 12 posted to Frequently Asked Questions (English) by Troy Wolbrink on 10/3/2011 4:06:02 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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
BaseCurrencyCode=USD

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

[SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/ssoDESIGNATIONS.2.2]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Username=$ACCOUNT$&Password=$PASSWORD$
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD
BaseCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.2] DESIGNATIONS.2.2]   <future: TntMPD 2.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Username=$ACCOUNT$&Password=$PASSWORD$
Post=Action=TntDesigs&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

Note for anyone writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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" "BaseCurrencyCode" should be defined once in the [Organization] section.
PERSONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
MEMO	<future: TntMPD 2.2> A note regarding the donor.
MAGAZINE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Does the donor subscribe to the organization's news magazine?
DECEASED	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "FALSE". Is the donor decease?
REMINDER	<future: TntMPD 2.2> (A18) How often is the donor reminded by the organization to make a donation?
RELATED_IDS	<future: TntMPD 2.2> A comma seperated list of related donor ids (used by TntMPD to help with matching contacts to donor ids).

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.

Profiles Query (Optional) <new for TntMPD 2.0>

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.

SingleSignOn

Designations Query (Optional) <future: TntMPD 2.2>

The purpose of this query is to simply return a one-time-use authentication ticket that can be used in one (and only one) querythe designations of the staff member submitting the request. It receives only uses the $ACCOUNT$ ACCOUNT$, $PASSWORD$ and $PASSWORD$. It should return one rowPROFILE$ placeholders.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

DESIG_ID	DESIG_NAME	ORG_PATH
12345678	Doe, John & Jane	/CAMPUS/STAFF/

Field Descriptions:

FieldName	Description
SSO_TICKET
DESIG_ID	(A18) Designation id associated with this user/profile.
DESIG_NAME	(A50) Designation account name associated with this user.
ORG_PATH	(Text) An authentication "service" ticket than can be passed into another query for one-time useWhere this designation fits in the organizational tree.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Fri, 02 Sep 2011 18:42:20 GMT

Revision 11 posted to Frequently Asked Questions (English) by Troy Wolbrink on 9/2/2011 2:42:20 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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

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

[SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.2] <future: TntMPD 2.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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:

<divre></divre>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:

<divre></divre>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 writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC	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.

SingleSignOn Query (Optional) <future: TntMPD 2.2>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 14 Mar 2011 14:50:37 GMT

Revision 10 posted to Frequently Asked Questions (English) by Troy Wolbrink on 3/14/2011 10:50:37 AM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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

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

[SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.2] <future: TntMPD 2.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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:

<divre></divre>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:

<divre></divre>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 writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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	<future: TntMPD 2.2> "TRUE" or "FALSE". 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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC
	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.

SingleSignOn Query (Optional) <future: TntMPD 2.2>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Steve Simms — Mon, 15 Mar 2010 21:47:14 GMT

Revision 9 posted to Frequently Asked Questions (English) by Steve Simms on 3/15/2010 5:47:14 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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

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

[SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.2] <future: TntMPD 2.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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:

<divre></divre>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:

<divre></divre>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 writing a front-end: 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

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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.

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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC
	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.

SingleSignOn Query (Optional) <future: TntMPD 2.2>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Tue, 23 Feb 2010 18:35:37 GMT

Revision 8 posted to Frequently Asked Questions (English) by Troy Wolbrink on 2/23/2010 1:35:37 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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

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

[SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.1.16> Specify an email address where users can report errors with your download process.
OrgHelpEmail=help@myorg.org
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.2] <future: TntMPD 2.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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:

<divre></divre>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:

<divre></divre>Action=TntBalance&Username=JohnDoe&Password=abc123

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.2> (Float) (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	<future: TntMPD 2.2> (A3) (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.
MEMO	<future: TntMPD 2.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.2> (A3) 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.

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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.2> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC
	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.

SingleSignOn Query (Optional) <future: TntMPD 2.2>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Sat, 30 May 2009 01:48:35 GMT

Revision 7 posted to Frequently Asked Questions (English) by Troy Wolbrink on 5/29/2009 9:48:35 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=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

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

[SingleSignOn.2.1]SingleSignOn.2.2]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.12.2> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.1] SingleSignOn.2.2] <future: TntMPD 2.12.2>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.12.2> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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:

<divre></divre>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:

<divre></divre>Action=TntBalance&Username=JohnDoe&Password=abc123

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.12.2> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.12.2> (Float) (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	<future: TntMPD 2.12.2> (A3) (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.
MEMO	<future: TntMPD 2.12.2> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.12.2> (A3) 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.

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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.12.2> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.12.2> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.12.2> Email address.
EMAIL_CHANGED	<future: TntMPD 2.12.2>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.12.2> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC
	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.

SingleSignOn Query (Optional) <future: TntMPD 2.12.2>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 02 Mar 2009 16:08:18 GMT

Revision 6 posted to Frequently Asked Questions (English) by Troy Wolbrink on 3/2/2009 11:08:18 AM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=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

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

[SingleSignOn.2.1]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.1> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.1] <future: TntMPD 2.1>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.1> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
DISPLAY_DATE	(M/D/YYYY) Date of contribution
AMOUNT	(Float) Amount of contribution
DONATION_ID	(A18) Donation 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	<future: TntMPD 2.1> (A18) (Optional) Payment method of this donation.
TENDERED_AMOUNT	<future: TntMPD 2.1> (Float) (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	<future: TntMPD 2.1> (A3) (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.
MEMO	<future: TntMPD 2.1> (A) Any comments (no length limit) associated with this gift.
BASE_CURRENCY	<future: TntMPD 2.1> (A3) 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.

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.

Here's an example result:

Field Descriptions:

FieldName	Description
PEOPLE_ID	(A18) Donor ID
ACCT_NAME	Donor full name
PERSON_TYPE	"O" or "P" (Organization or Person)
LAST_NAME_ORG	Last Name or Organization Name
FIRST_NAME	First Name
MIDDLE_NAME	Middle Name
TITLE	Title (Mr., Mrs.)
SUFFIX	Suffix (Jr., Sr.)
SP_LAST_NAME	for spouse
SP_FIRST_NAME	for spouse
SP_MIDDLE_NAME	for spouse
SP_TITLE	for spouse
SP_SUFFIX	for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.
ADDR1	Street Address (Line 1)
ADDR2	Street Address (Line 2)
ADDR3	Street Address (Line 3)
ADDR4	Street Address (Line 4)
CITY	City
STATE	State
ZIP	Postal Code
COUNTRY	(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	Name of country.
ADDR_CHANGED	(M/D/YYYY) When the addres was last changed.
ADDR_DELIVERABLE	<future: TntMPD 2.1> "TRUE" or "FALSE". Blank implies "TRUE".
PHONE	Phone number.
PHONE_CHANGED	(M/D/YYYY) When the phone was last changed.
PHONE_OPERATIONAL	<future: TntMPD 2.1> "TRUE" or "FALSE". Blank implies "TRUE".
EMAIL	<future: TntMPD 2.1> Email address.
EMAIL_CHANGED	<future: TntMPD 2.1>(M/D/YYYY) When the email was last changed.
EMAIL_OPERATIONAL	<future: TntMPD 2.1> "TRUE" or "FALSE". Blank implies "TRUE".

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.

Profiles Query (Optional) <new for TntMPD 2.0>

Example result:

PROFILE_CODE	PROFILE_DESC
	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.

SingleSignOn Query (Optional) <future: TntMPD 2.1>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName	Description
SSO_TICKET	(Text) An authentication "service" ticket than can be passed into another query for one-time use.

Case Insensitivity

Testing your compatibility with TntMPD

Making it easy for your staff to connect...

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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org I would be glad to help you.

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

Troy Wolbrink — Mon, 29 Sep 2008 19:06:25 GMT

Revision 5 posted to Frequently Asked Questions (English) by Troy Wolbrink on 9/29/2008 3:06:25 PM

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

Filed under: Developer Guides

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

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

Query INI File

[APPLICATION]
MinimumVersion=1.5.0
RecommendedVersion=1.5.0

[ORGANIZATION]
RedirectQueryIni=
Name=Your Organization Name
Abbreviation=MyOrg
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=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

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

[SingleSignOn.2.1]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.1> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.1] <future: TntMPD 2.1>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

TntMPD-version specific sections <new for TntMPD 2.0>

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

[DONATIONS.2.2]
[DONATIONS.2.1]
[DONATIONS.2.0]
[DONATIONS.2]
[DONATIONS]

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.
$SSO_TICKET$	<future: TntMPD 2.1> The service ticket returned by the SingleSignOn Query. Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only accepts $ACCOUNT$ and $PASSWORD$.
$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

ERROR
Invalid password.

ERROR
Invalid user name.

ERROR
Server is down for maintenance.

ERROR
Invalid date range.

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:

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"
"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",...","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Description

PEOPLE_ID (A18) Donor ID

ACCT_NAME Donor full name

DISPLAY_DATE (M/D/YYYY) Date of contribution

AMOUNT (Float) Amount of contribution

DONATION_ID (A18) Donation 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 <future: TntMPD 2.1> (A18) (Optional) Payment method of this donation.

TENDERED_AMOUNT <future: TntMPD 2.1> (Float) (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 <future: TntMPD 2.1> (A3) (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.

MEMO <future: TntMPD 2.1> (A) Any comments (no length limit) associated with this gift.

BASE_CURRENCY <future: TntMPD 2.1> (A3) 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.

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.

Here's an example result:

"PEOPLE_ID","ACCT_NAME","DISPLAY_DATE","AMOUNT","DONATION_ID","DESIGNATION","MOTIVATION"

"PEOPLE_ID","ACCT_NAME","ADDR1","ADDR2","ADDR3","ADDR4","CITY","STATE","ZIP",...
"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"","630 Pine St",,,,"Hickleman","SD","18372-2637",...
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"","1212 Elm Cir",,,,"Orlando","FL","32828-1868",...
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ...

Field Descriptions:

FieldName Description

PEOPLE_ID (A18) Donor ID

ACCT_NAME Donor full name

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

LAST_NAME_ORG Last Name or Organization Name

FIRST_NAME First Name

MIDDLE_NAME Middle Name

TITLE Title (Mr., Mrs.)

SUFFIX Suffix (Jr., Sr.)

SP_LAST_NAME for spouse

SP_FIRST_NAME for spouse

SP_MIDDLE_NAME for spouse

SP_TITLE for spouse

SP_SUFFIX for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.

ADDR1 Street Address (Line 1)

ADDR2 Street Address (Line 2)

ADDR3 Street Address (Line 3)

ADDR4 Street Address (Line 4)

CITY City

STATE State

ZIP Postal Code

COUNTRY (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 Name of country.

ADDR_CHANGED (M/D/YYYY) When the addres was last changed.

ADDR_DELIVERABLE <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

PHONE Phone number.

PHONE_CHANGED (M/D/YYYY) When the phone was last changed.

PHONE_OPERATIONAL <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

EMAIL <future: TntMPD 2.1> Email address.

EMAIL_CHANGED <future: TntMPD 2.1>(M/D/YYYY) When the email was last changed.

EMAIL_OPERATIONAL <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

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_DESC

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.

SingleSignOn Query (Optional)   <future: TntMPD 2.1>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName Description

SSO_TICKET (Text) An authentication "service" ticket than can be passed into another query for one-time use.

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". (Note: You must hold down the Shift key when you drop down the list.) 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. (wolbrink@ccci.org) 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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org   I would be glad to help you.

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

Troy Wolbrink — Mon, 29 Sep 2008 18:53:24 GMT
Revision 4 posted to Frequently Asked Questions (English) by Troy Wolbrink on 9/29/2008 2:53:24 PM

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

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>

SingleSignOn Query (Optional) <future: TntMPD 2.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-476x100=http://www.myorg.org/WebLogo.jpg
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
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=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

[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$&DateFrom=$DATEFROM$

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

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

[SingleSignOn.2.1]
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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

[APPLICATION]
// You can require a minimum version of TntMPD for Web Input features.
MinimumVersion=1.5.0
// You can recommend a minimum version of TntMPD for Web Input features if you wish.
RecommendedVersion=1.5.0

[ORGANIZATION]
// If you move your Query INI File, you can permanently redirect users to the 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
// Really old versions of TntMPD may use this. This has been deprecated. Use "WebLogo-JPEG-470x120" on new work.
WebLogo-JPEG-476x100=http://www.myorg.org/WebLogo.jpg
// URL of where your logo can be downloaded (JPEG only).
WebLogo-JPEG-470x120=http://www.myorg.org/WebLogo.jpg
// URL of a mini portal into your website
WebPortalUrl-470x120=http://www.myorg.org/miniportal?Username=$ACCOUNT$&Password=$PASSWORD$
// 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. (M/D/YYYY)
MinimumWebGiftDate=1/1/1990
// Unique code to represent your ministry internally to TntMPD. (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
// <new for TntMPD 2.0> Specify a url where users can report errors with your download process.
OrgHelpUrl=https://www.myorg.org/help.htm
// <new for TntMPD 2.0> Specify the text users will see for OrgHelpUrl.
OrgHelpUrlDescription=Click here to report this issue over the Web!
// <new for TntMPD 2.0> Specify alternative text for how users can get help with downloading information.
OrgHelpOther=You may also reach the us at 123-456-7890.
// <new for TntMPD 2.0> Specify the url where users can request new download profiles.
RequestProfileUrl=https://www.myorg.org/requestprofile.htm
// <new for TntMPD 2.0.44> Specify the url where users can view a staff portal.
StaffPortalUrl=http://myorg.org/staffportal.html
// <future: TntMPD 2.1> Specify the base currency code (ISO 4217 3-char) for gifts returning from your Donations Query.
DefaultCurrencyCode=USD

[ACCOUNT_BALANCE]
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/    // URL of your online donation system.
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$    // Your POST template. (described later)

[ACCOUNT_BALANCE.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntBalance&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$

[DONATIONS]    // URL and POST have same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&DateFrom=$DATEFROM$&DateTo=$DATETO$

[DONATIONS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntDonList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$&DateTo=$DATETO$

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

[ADDRESSES.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[ADDRESSES_BY_PERSONIDS]    // same comments as for ACCOUNT_BALANCE section
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&PID=$PERSONIDS$

[ADDRESSES_BY_PERSONIDS.2]   <new for TntMPD 2.0> // A version specific section with the new $PROFILE$ placeholder included
Post=Action=TntAddrList&Username=$ACCOUNT$&Password=$PASSWORD$&ProfileCode=$PROFILE$&DateFrom=$DATEFROM$

[PROFILES.2] <new for TntMPD 2.0>
Url=https://www.myorg.org/cgi-bin/StaffAccountApp/
Post=Action=Profiles&Username=$ACCOUNT$&Password=$PASSWORD$

[SingleSignOn.2.1] <future: TntMPD 2.1>
// Note: If this query were actually used, credentials would not be
//   passed in to the other queries. But $SSO_TICKET$ would be used instead.
Url=https://www.myorg.org/cg-bin/sso/
Post=Username=$ACCOUNT$&Password=$PASSWORD$

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 will support version specific sections. For example a client running TntMPD 2.2 will search for the "DONATION" section by using the first out of this list that it finds first:

[DONATIONS.2.2]

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

$SSO_TICKET$ <future: TntMPD 2.1> The service ticket returned by the SingleSignOn Query.
Generally you would use this in lieu of $ACCOUNT$ and $PASSWORD$. Note: The
SingleSignOn query never receives the $SSO_TICKET$ placeholder, but only
accepts $ACCOUNT$ and $PASSWORD$.

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

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.

Click here To see

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 Description

PEOPLE_ID (A18) Donor ID

ACCT_NAME Donor full name

DISPLAY_DATE (M/D/YYYY) Date of contribution

AMOUNT (Float) Amount of contribution

DONATION_ID (A18) Donation 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 <future: TntMPD 2.1> (A18) (Optional) Payment method of this donation.

TENDERED_AMOUNT <future: TntMPD 2.1> (Float) (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 <future: TntMPD 2.1> (A3) (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.

MEMO <future: TntMPD 2.1> (A) Any comments (no length limit) associated with this gift.

BASE_CURRENCY <future: TntMPD 2.1> (A3) 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.

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.

Click here To see

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 Description

PEOPLE_ID (A18) Donor ID

ACCT_NAME Donor full name

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

LAST_NAME_ORG Last Name or Organization Name

FIRST_NAME First Name

MIDDLE_NAME Middle Name

TITLE Title (Mr., Mrs.)

SUFFIX Suffix (Jr., Sr.)

SP_LAST_NAME for spouse

SP_FIRST_NAME for spouse

SP_MIDDLE_NAME for spouse

SP_TITLE for spouse

SP_SUFFIX for spouse Note: If this is not blank, it is just concatenated with a space to SP_LAST_NAME.

ADDR1 Street Address (Line 1)

ADDR2 Street Address (Line 2)

ADDR3 Street Address (Line 3)

ADDR4 Street Address (Line 4)

CITY City

STATE State

ZIP Postal Code

COUNTRY (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 Name of country.

ADDR_CHANGED (M/D/YYYY) When the addres was last changed.

ADDR_DELIVERABLE <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

PHONE Phone number.

PHONE_CHANGED (M/D/YYYY) When the phone was last changed.

PHONE_OPERATIONAL <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

EMAIL <future: TntMPD 2.1> Email address.

EMAIL_CHANGED <future: TntMPD 2.1>(M/D/YYYY) When the email was last changed.

EMAIL_OPERATIONAL <future: TntMPD 2.1>
"TRUE" or "FALSE". Blank implies "TRUE".

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_DESC

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.

SingleSignOn Query (Optional)   <future: TntMPD 2.1>

The purpose of this query is to return a one-time-use authentication ticket that can be used in one (and only one) query. It receives $ACCOUNT$ and $PASSWORD$. It should return one row.

Example result:

SSO_TICKET

ST-gjdhgvyudmfnbgbyf

Field Descriptions:

FieldName Description

SSO_TICKET (Text) An authentication "service" ticket than can be passed into another query for one-time use.

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". (Note: You must hold down the Shift key when you drop down the list.) 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. (wolbrink@ccci.org) 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 to contact me

If you have any questions regarding this document, please don't hesitate to contact me at my email address: wolbrink@ccci.org   I would be glad to help you.