I know I've been promising an SDK for some time now, but we've finally had some movement on that front. Some of you may have received an email announcing the first release. We've started a new web site to host all-things-SDK. Check out DevHero.com for everything you need to know to get started.

We plan to release the SDK in small pieces as beta downloads. We want to crawl before we run and we want your feedback all along the way. At some point, when the small pieces become mature and stable enough, we will add them to the release version of the grand SDK.  The first download is some code and examples to create your own reports inside of GiftWorks. A recent survey of our customers indicated that reporting was a big part of what you'd like to customize. This should get you started. Please let us know what you think via the DevHero forums. Thanks.

In November, the Fundraising Effectiveness Project (FEP) launched their annual Fundraising Effectiveness Survey. This survey asks charities to compare their 2004 and 2005 fundraising results. The results of the survey are intended to enable non-profits "to compare their growth-in-giving results across a variety of measures with the performance of similar organizations." Russ Burke has published an article about how this helps your organization.

FEP partnered with over one dozen software firms in assisting their clients with the survey. Here at Mission Research, Chris Walker, a Product Manager donated some time to building a GiftWorks add-in that would automatically gather and send the survey data for GiftWorks users. This is a great example of how GiftWorks can be extended to support additional functionality. And truly it's not very difficult to do given the proper documentation (which is only available internally right now).

I'm very curious how the FEP survey was exposed by the other partnering software makers. If any readers have used the software by the other partners, please let me know your experiences.

In a lot of organizations, the fundraising is at a very personal level. In those cases you might find it useful to keep photos of your donors in your records. A new GiftWorks add-in will now enable you to do that for your donors.

Steve Fafel has created a sample add-in to demonstrate some of the extensibility of GiftWorks and it has turned out to be a very popular add-in. Please download and try it out. The source code comes with it, so check that out too.

In this post I present an example add-in that adds a new report category and one new report to GiftWorks. Unfortunately there is way too much stuff going on here to explain everything, but the ambitious user should be able to make some headway with adding custom reports to GiftWorks. There are two files that are necessary to add a new report. You need to write an add-in file (newreport.xml) that defines the add-in and tells GiftWorks about the new report category and the new report. The other file (GRDF-donors-by-number.xml) tells GiftWorks what to display in the report. For this example to work, both files need to reside in the same directory.

newreport.xml 

   1:  <gmlid="missionresearch_newreport">

   2:  <info>

   3:  <title>New Report</title>

   4:  <versions>

   5:  <versionmatch="2.0"module="version2"/>

   6:  </versions>

   7:  </info>

   8:  <moduleid="version2">

   9:  <objects>

  10:  <objectid="Handler"type="vbscript">

  11:  <![CDATA[

  12:                      Const CategoryKey = "my-reports"

  13:                      Sub AddNewReportCategory()

  14:                          Dim oCat

  15:                          Set oCat = App.Modules.GiftWorks.Reports.GetNewCategory

  16:                          oCat.Key = CategoryKey

  17:                          oCat.Name = "My Reports"

  18:                          oCat.Description = "These are my reports that I have built."

  19:                          App.Modules.GiftWorks.Reports.Categories.Add oCat

  20:                      End Sub

  21:                      Sub AddNewReport()

  22:                          Dim oReport, oCat

  23:                          For Each oCat In App.Modules.GiftWorks.Reports.Categories

  24:                              If oCat.Key = CategoryKey Then

  25:                                  Set oReport = App.Modules.GiftWorks.Reports.GetNewReport

  26:                                  oReport.Key = "donors-by-number"

  27:                                  oReport.Name = "Donors By Number Of Donations"

  28:                                  oReport.Description = "This report let's me filter my donors by the number of gifts they have given."

  29:                                  oReport.Path = App.Modules.missionresearch_newreport.Path

  30:                                  oCat.Reports.Add oReport

  31:                              End If

  32:                          Next

  33:                      End Sub

  34:                      Sub EventHandler(Ev)

  35:                          Select Case Ev.Key

  36:                              Case "reports-categories"

  37:                                  AddNewReportCategory

  38:                              Case "reports-categories-reports"

  39:                                  AddNewReport

  40:                          End Select

  41:                      End Sub

  42:                  ]]>

  43:  </object>

  44:  </objects>

  45:  <taskmenu/>

  46:  <handlers>

  47:  <handlerid="reports-categories"object="Handler"/>

  48:  <handlerid="reports-categories-reports"object="Handler"/>

  49:  </handlers>

  50:  </module>

  51:  </gml>

This file should look familiar to those that have been following along with my blog. You can view previous posts to see how to install add-ins with GiftWorks. There are two lines that I'll explain. Line 26 assigns a key to the new report. This key corresponds to the filename of the GRDF report. Line 29 tells GiftWorks where to look for the report definition file. In this case it uses the Path property for the current module. "missionresearch_newreport" is the Id of this module as identified on Line 1.

download files

You can download both files: newreport.xml, GRDF-donors-by-number.xml

what's next

Like I said, I don't go into a lot of detail. The GRDF file can be very confusing so I'll wait for interest and/or feedback before I spend too much time describing its functionality. Please let me know if you want to see more about either file.

I've seen a couple request from customers wanting the ability to keep some of their users out of certain areas in GiftWorks. Below is a small addin that attempts to solve that problem by removing the toolbar buttons at the top of the window. In this example I remove every application button except the Donors button (see the picture to the right).

See my HelloWorld post and my What's In A GiftWorks Addin post for more details on using the following addin file. This post will skim through the details and assume you've already created and used an addin file. 

   1:  <gmlid="MissionResearch_DisableExample">

   2:  <info>

   3:  <title>Disable Addin Example</title>

   4:  <versions>

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

   6:  </versions>

   7:  </info>

   8:  <moduleid="version2">

   9:  <objects>

  10:  <objectid="MyObject"type="vbscript"url=""cache=""><![CDATA[

  11:                  Sub EventHandler(Ev)

  12:                      If Ev.Data.Url = "toolbar" Then

  13:                          For Each button In App.Shell.Toolbar.Buttons

  14:                              If button.Title <> "Donors" Then

  15:                                  App.Shell.Toolbar.Buttons.Remove button.Title

  16:                              End If

  17:                          Next

  18:                      End If

  19:                  End Sub

  20:              ]]></object>

  21:  </objects>

  22:  <handlers>

  23:  <handlerid="module-execute"object="MyObject"/>

  24:  </handlers>

  25:  </module>

  26:  </gml>

toolbar buttons

The toolbar buttons at the top of GiftWorks are the main navigation elements for the application. GiftWorks inserts several by default and addins can modify those buttons or add their own. This post just concentrates on removing existing buttons. GiftWorks gives you access to these buttons through a Buttons collection.

App.Shell.Toolbar.Buttons

Each button has several properties that you can modify with code.

Button.Order - a number indicating the sort order the buttons should use for display
Button.Action - the action a button executes when clicked
Button.Title - the title of the button displayed
Button.ImageUp - the image file used when the button is in normal state
Button.ImageDown - the image file used when the button is in clicked state
Button.ImageOver - the image file used when the button has a mouse over it
Button.ImageDisabled - the image file used when the button is disabled

event handlers

You can embed event handlers in the addin file to handle events raised by GiftWorks. Event handlers are the primary means for addins to integrate with existing GiftWorks elements. This addin handles a general framework event called 'module-execute' which is fired whenever the framework needs to initialize the toolbar. GiftWorks fills the toolbar first with it's buttons then fires the event so addins can handle it as well. An addin can add toolbar buttons using a simpler interface which will be shown at a later time. This event enables an addin to modify buttons that have already been added. You could rename buttons or other things. This addin just checks for the Donors button and removes everything else. The <handler> element simply tells GiftWorks your addin wants to be called when the 'module-execute' event is raised. It then calls the EventHandler subroutine in the 'MyObject' script.

Try this our and let me know what you think. In later posts I will try to expose some more of the many GiftWorks events.

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.

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.

We have two interns working at Mission Research this summer. Jon Hollinger and Rob Payeur are students of Millersville University. They will be working with us for 10 weeks and are tasked with researching, designing and building some software using the addin functionality built into GiftWorks. They are already starting their 4th week and are in the process of deciding which of three projects they are going to move on.

They are maintaining a web site to document their progress and showcase some of their work. Feel free to send them email asking questions or making suggestions. They would really like to get some feedback.

As I mentioned earlier, this post will show how to create and use a GiftWorks Addin of your own. I will not go into too much detail about how an addin is written in this post. I will describe the internal of an addin with the next post.

what is a giftworks addin

Strictly speaking, an addin can be as simple as a text file written in Notepad. This file contains instructions that GiftWorks reads to expose custom functionality. The addin file can be located on your computer or it can be located on a remote server somewhere on the internet. GiftWorks doesn't care. The only constraint about using an addin that is located on a remote server is that you need to be connected to the internet in order to load that addin.

the helloworld addin

For this discussion I will use an extremely simple addin. In fact, this addin is so simple it doesn't do anything useful (besides demonstrating how to work with GiftWorks Addins). Most programming examples start with a "HelloWorld" example, which is what I will show here. This example just inserts a menu item called "Hello World" on the start page of GiftWorks. When you click on the menu item, it pops up a message. You can probably guess what that message says.

You can download the HelloWorld addin here: http://daveweaver.net/media/downloads/HelloWorld.xml. If you click on this link it will open up in your browser. Most browsers will show the contents of the addin file. Like I said, I will explain this stuff in a later post.

let's install it already

If you have GiftWorks with Update 3 installed (requires version 2.0.80.00 which will be publicly released at the end of February) you will have an Addin Manager which can be launched from the Help menu. Launch that now.



The Addin manager shows what addins you have installed. You should see nothing installed at this point. To install the HelloWorld addin, simply copy the URL above and paste it into the top text box. Click the Install button and you should see the addin show up in the list.



The checkbox next to the addin name just indicates the addin is loaded. You can have addins installed but disabled which effectively turns them off. Once you see the HelloWorld addin installed and loaded, click the Done button. That's all that is involved with installing a remote GiftWorks Addin. To install an addin that is located on your computer, simply enter the filename of the addin and click the Install button.

make it do something

Now that the addin is installed you can use it. Don't get too excited, this addin doesn't do too much. In GiftWorks, make sure you are signed in, then click on the Home button at the top-left to go to the start page. On the start page you should see Hello World listed on the left menu like below. Click the menu and you will see the message.



what's next

Like I said, not very exciting, but this is very powerful functionality we are exposing to our customers. The addin we've just installed is simple, but is only the tip of the iceburg as to what it is capable of doing. Please stay tuned as I go deeper with my examples. Go back into the Addin manager to uninstall the addin. Or if you are familiar with programming and would like to try some stuff on your own, download the HelloWorld addin and try your hand at coding your own. I haven't given you much information to go on at this point, but that is coming.

We just had a release meeting to review an important update to GiftWorks that will be gradually released over the next couple weeks. This is our 3rd update to GiftWorks since our release of GiftWorks 2006 in September 05.

We are constantly trying to improve our products to better meet customer needs and expectations. This update will not change much functionality you are used to, but it does add some features you requested and fixes several bugs. I'll leave it to Sarah and Steve to go over the hightlights of the update. Sarah is our new Product Manager and Steve is our Lead Developer for GiftWorks.

I would like to describe some additions coming in Update 3 that will be important to developers. It is a goal of ours to give customers the ability to build customized addins that can help better integrate GiftWorks into their organization. We do our best by building useful features into GiftWorks off the shelf, but a lot of our customers have unique needs that can't be handled by GiftWorks without customization. Starting with Update 3, we will gradually be rolling out samples and documentation to customize GiftWorks yourself.

Some examples of customizations would be adding a new screen, or inserting a new menu item into an existing screen. We will give you examples of writing little programs that work with your SmartLists or are used to add and edit donors. The possibilities are really endless.

Update 3 also incorporates an Addin Manager which will allow you to easily install and remove your addins. It will even enable you to use addins created by other companies or organizations. We will be putting an effort into getting other companies to create addins for GiftWorks that will be made available to you.

In the next post I will show you how to create a very simple addin that you can try when you get the GiftWorks update.