How can I make my organization's online donation system compatible with TntMPD?: Revision #14

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.

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:

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:

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

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

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

Action=TntBalance&Username=JohnDoe&Password=abc123

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

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

Note for anyone 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:

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

Field Descriptions:

Donations Query

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

Here's an example result:

Field Descriptions:

Addresses Query

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

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

Here's an example result:

Field Descriptions:

Addresses By IDs Query

This Query only differs from the Addresses Query in that it uses the $PERSONIDS$ parameter instead of the $DATEFROM$ parameter.  The $PERSONID$ parameter is substituted by a comma separated list of donor IDs.  These donor IDs are obtained from donations in the Donations Query.  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:

Field Descriptions:

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:

Field Descriptions:

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

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.