Updated 8/29/2006

In a previous post, I showed how to use a GiftWorks Addin. In this post I will expand on that same HelloWorld example by explaining the contents of the addin file. The HelloWorld Addin is simply an xml file with a specific structure recognized by GiftWorks. There are several more elements that can be included in an addin file, but for this example we will only focus on the <taskmenu> element.

Here is the HelloWorld Addin file:

   1:  <gml id="MissionResearch_HelloWorld">

   2:      <info>

   3:          <title>HellowWorld Addin</title>

   4:          <versions>

   5:              <version match="2.0.*.*" module="version2" />

   6:          </versions>

   7:      </info>

   8:      <module id="version2">

   9:          <taskmenu>

  10:              <menu task="graphite://provider/startpage">

  11:                  <item section="RELATED TASKS" type="script" text="Hello World" before="Add a Donor">

  12:                  <![CDATA[App.Shell.MsgBox("HelloWorld!")]]>

  13:                  </item>

  14:              </menu>

  15:          </taskmenu>

  16:      </module>

  17:  </gml>

identify your addins

Lines 1 and 3 are used to identify your addin. The id attribute in line 1 is a key that uniquely identifies your addin. The contents of this attribute are up to you. It just has to be unique among other addins used within your copy of GiftWorks. It can only contain alpha-numeric characters and underscores. I will typically use something prepended with my companies name. This should be unique enough as long as someone else in my company doesn't have the same idea. The id in Line 1 is not something seen by GiftWorks users. Line 3 is the <title> element. This title will show up in the GiftWorks Addin Manager and will identify your addin to the GiftWorks user. This example doesn't use them, but you can also include <publisher>, <description> and <website> elements to further identify your addin.

addin versioning

Supporting addins becomes very tricky as GiftWorks functionality is enhanced. For this reason our addins need to specify the version of GiftWorks that it will support. Depending on the functionality of your addin you may need to update it when a new version of GiftWorks will be released. A single addin file can target several versions of GiftWorks. When we officially release a software development kit (SDK) for building addins we will document the rules that we use when incrementing version numbers within GiftWorks. You will be able to use these rules to know when to provide updates to your addin. Along with the addin SDK we will support a developer community that will get notified of version changes and have the opportunity to test prerelease versions of the software.

Like I said, a single addin file can target multiple versions of GiftWorks. Minimally you need a single <version> element with a match attribute and a module attribute in every addin file. The match attribute is used to figure out what version should be selected and the module attribute points to the corresponding <module> section within the addin. If you need to support multiple version you can include more <version> elements and <module> sections within the file. The <version> elements will be processed from top to bottom in case there is any overlap.

For this example, I'll target a small range of GiftWorks' versions. GiftWorks will support addins starting from GiftWorks Update 3 (version 2.0.80.00), so by using '2.0.*.*' I've enabled the use of my addin for GiftWorks version 2 or higher. By specifying the match string like this it should allow future updates of GiftWorks 2006 to use this addin.

adding a menu item

This HelloWorld example just inserts a menu item on the start page in GiftWorks. When the user clicks on the new menu item a script is called which displays the message "HelloWorld" in a popup. Lines 9-15 defines where the menu item is inserted and what happens when you click the menu item. There are several options when defining new menu items, but to keep this post as short as possible I will only describe the ones used in this example.

Line 10 specifies the menu to modify. From a high level, GiftWorks is just a series "pages" that the user navigates thru (very similar to a website). Each page performs a unique function. Along the left side of each page you will typically find a menu--a list of links that the user can use to perform a function related to the current page. In development, the "pages" are called tasks and they are uniquely identified by a URL. At any point while using GiftWorks you can see the current task name by pressing SHIFT-F6. The "current task" line lists the task's URL. This is how we identify what menu we want to modify in our addin. We use 'graphite://provider/startpage' in line 10 of our example.

Each menu is divided into sections. On the start page we have two section: RELATED TASKS and DID YOU KNOW. The <item> element in line 11 of our example represents a single new menu item that gets placed in the RELATED TASKS section directly before the existing 'Add a Donor' menu item. The text attribute contains the name of the new menu item as seen by the GiftWorks user. The type attribute tells GiftWorks what should be done when the user clicks the menu item. In this case it executes a script which is included within the <item> element on line 12.

Line 12 contains the actual script that is executed when the user clicks the new menu item. I have enclosed the script within CDATA brackets so we can use characters that may not be recognized in xml. I recommend you that you just use them around all your addin scripts.

the script

Explaining everything that can be done with scripting is way beyond the scope of this post. GiftWorks Addins support Microsoft's ActiveX scripting. You may use any ActiveX scripting language by specifying a language attribute in the containing element tag. The default language in an addin script is VBScript (Microsoft Scripting).

The key thing to note in this example is the App reference. This single reference gives the addin developer access to the entire object model within GiftWorks. The same object model that the Mission Research developers use to create GiftWorks. I won't go into detail yet, but most Windows developers will know how to view the GiftWorks object model in an object browser. If you aren't familiar with object models or App references, you will need to wait a bit until I can go into more detail or find a resource that can help you figure it out.

We recently put out Update 4 for GiftWorks. The update was needed to support our recent release of GiftWorks Volunteers as well as fix some of the top bugs that our customers were experiencing. When updates are released the dev and support teams are on high alert. Dev watched the monitoring software for customers that install the update and have problems. Most of the updates go as planned, but there are some where things "just happen". I handled one of the early problems that came up. A customer had installed the update but it appeared a component had not been updated correctly by the installer and the customer was receiving errors. To make sure this was not a problem that was going to affect a lot of people, I looked up the gentleman's registration information and gave him a call. It's always awkward "cold-calling" a customer about issues we have detected, but this customer was thankful and more than willing to let me fix his problems. It turned out to be a fluke and a quick re-install of the update got him back on his way.

We have very detailed monitoring built into GiftWorks that let's us detect and get to the bottom of bugs before they cause too much of a problem. I only wish we had the resources to handle every customer's problems the same way--where we call them instead of the customer calling us. Who knows, maybe someday you'll have a problem with GiftWorks and we'll call you.

Users of GiftWorks can now purchase the GiftWorks Volunteers addin which seamlessly integrates volunteer management with existing donor and fundraising management. This is a big step for Mission Research in a couple ways. First, volunteer management was at the top of our customer's wishlists -- almost half of the customers surveyed had asked for it. I hope it meets their expectations (please let us know if it does). Second, it moves us one step closer to opening up third-party development of GiftWorks addins. GiftWorks Volunteers was built using publicly exposed (but as of yet, undocumented) APIs. In the near future we will make them open APIs so you (or others) can build your own addins. 

GiftWorks Volunteers can be downloaded as a 30-day trial and purchased for an introductory prices of $149 (regularly $199). Please stop by our website and give it a try.

Peter Campbell has published an N-TEN article called Seven Questions for Peter Campbell on Open APIs. The article tries to answer some common questions about software and their open APIs. It's a good read and provides a high level look at the subject.

In short, open APIs enable customers to extend their software to better meet the needs of their organization. To me, this is one of the most important features software can have. This is especially true if you're part of a growing organization, because you never know what your software needs will be in the future. Here are some examples of things that open APIs can provide:

Third-party development: Other software companies can build retail software that can extend or integrate with the APIs . For example, Quickbooks has an open API which allows other software to synchronize accounting records with it.

User-interface customization: Customize the way the software works. For example, with GiftWorks, if you want to install it for your data entry people and don't want them to use the Reports or Mailing section you can use the APIs to remove those sections. Or if you want to be able to store and display a picture of your donors within the software, good APIs would allow you to add that functionality.

Website integration: Give your web server the ability to present data that is stored in your donor database. For example, if your organization wants to allow their donors to change their information through your website, good APIs would give your website developers the ability to do that.

Data access: Move data into and out of your database using different sources. For example, if you have an Excel spreadsheet that you use to collect information in your laptop when you are on the road, good APIs would allow you to synchronize that spreadsheet with your database when you are back in the office.

Automation: Have certain functionility of your software happen automatically. For example, if you have a Membership Renewal field in your software, good APIs will enable you to have your software automatically send you an email of expired memberships at the end of every week.

Web service integration: Leverage other web sites or services to extend the functionality of your software. For example, you can use the Google Maps web service to plot a map with your top 100 donors.

Notice I used the term "good APIs" above. Not all APIs are created equal and they should be evaluated when deciding on which software to purchase. Also, most APIs require some programming knowledge. If this knowledge is not available within your organization, it is available outside using consultants.

A note about GiftWorks and open APIs... GiftWorks was designed and developed from the ground up with open APIs in mind. All the scenarios I listed above, and more can be done with GiftWorks *BUT* until we are able to release documentation and examples of using the APIs (also called a Software Development Kit (SDK)), it is still out of reach for our customers. Our SDK is a high priority for us and we are commited to supporting a development community around the GiftWorks SDK. Hopefully you won't have to wait too long.

Recently GiftWorks was reviewed by FundraisingKnowHow.com. Here are a couple exerpts from the review.

"...Mission Research's GiftWorks software catches our attention because of its $299 price tag--a bargain compared to other non-profit administrative packages that can cost up to $5,000 or even more."

It's very hard to beat our pricing, especially if you consider the amount you'll save in training costs with the rapid turnover in non-profits.

"The software has a short learning curve, so there's no training sessions required. The interface is quite intuitive, and it will be easy for anybody with a basic level of PC competence to teach them self how to operate the software."

Please check out the site to read the entire review.

On August 19th in San Francisco, Mission Research is sponsoring our second Nonprofit Boot Camp hosted by Craigslist Foundation. We sponsored our first one in New York back in June. It was a great event with lots of attendees and some good workshops. The one in San Fransisco looks like it will be a bigger event and there will be several Mission Research poeple there to speak to and demonstrate GiftWorks. I think our CEO, Charlie will also be leading a workshop. If you live in the area and are interested in using GiftWorks for fundraising, try to make the event.

We are coming to the end of another product cycle. This time for GiftWorks Volunteers, our first addition to GiftWorks. It is a new product that is released as an add-in for GiftWorks. There were a lot of challenges, both in architecture and design. For one thing, we needed to finalize our add-in API built into GiftWorks. This API enables us to deliver other products that integrate seamlessly into GiftWorks. Those changes required us to simultaneously deliver the volunteer add-in plus a major update to GiftWorks. Another major challenge was adding a considerable amount of functionality to GiftWorks without making the existing software more complex and harder to use. We've spent a lot of time and effort in getting things right. I know we've slipped our release dates a few times which is a hard thing for our customers and is equally painful for myself and my co-workers. I'm hoping you'll find it worth the wait.