Issuu on Google+

Springbaud™ for The Raiser’s Edge 7 and Campaign Monitor Documentation and Release Notes April 23, 2014 1. 2. 3. 4. 5. 6. 7. 8. 9.

Introduction Licensing and Registration System Requirements Installing and Uninstalling Initial Configuration User Documentation Product Support and Feedback Product Release Notes Appendices

1. Introduction Firstly, thank you for trying, buying or using Springbaud™ for The Raiser’s Edge 7 and Campaign Monitor. Springbaud is designed to save you time and effort managing your email campaign lists and results. It is designed to be a common campaign management platform for The Raiser’s Edge 7. Future versions of Springbaud will integrate with other popular email marketing service providers, such as MailChimp and Constant Contact. This means that if you change email marketing service provider, you won’t have to change the way you manage your lists and campaign results. This document is intended to provide you with everything you need to get the most out of Springbaud and, in turn, out of The Raiser’s Edge 7 and your email marketing service provider. For the latest updates and documentation, please visit the Springbaud Support page.

1.1 What does Springbaud for The Raiser’s Edge and Campaign Monitor do? o

o

o o

Springbaud for The Raiser’s Edge and Campaign Monitor is a Raiser’s Edge plug-in which uploads email lists directly from The Raiser’s Edge to Campaign Monitor and adds campaign results from Campaign Monitor directly to The Raiser’s Edge. No more manual imports or exports. With Springbaud, you create specially-named queries which are selected in Springbaud for upload to Campaign Monitor. List records are tagged with a unique record ID which allows results to be added directly to The Raiser’s Edge. Install as many copies as you wish. Springbaud is licensed on a per-database basis, not a per-installation or per-user basis so you can install it on as many workstations as you like. Change email marketing providers without changing your work flow. Springbaud provides a virtually identical user experience no matter which email marketing service provider you use. More service providers will be added in the future.

1.2 Which email marketing service providers does Springbaud currently support? Springbaud is currently available with support for: o o

Campaign Monitor Campaign Master

1.3 Which new email marketing service providers will be added in the near future? It is expected that Springbaud will soon be available with support for: o o

MailChimp Constant Contact

Contact us to ask about support for your email marketing service provider.


2. Licensing and Registration 2.1 License Agreement Springbaud is licensed on a per-database basis, not a per-installation or per-user basis. That is, it may be installed on as many workstations and for as many users as you wish provided that the Raiser’s Edge production database to which each workstation is connected is licensed. Springbaud may also be used with the Raiser’s Edge sample database without limitation. To try Springbaud with your sample database, all you need is the generic demonstration installer available from our website. If you wish to try Springbaud with your production database, all we require is your Raiser’s Edge database serial number. We then provide you with a customized Springbaud installer you which you may use for a full month free of charge. One month trial and fully licensed copies of Springbaud have your Raiser’s Edge production database serial number embedded within the application. This helps prevent unauthorized use of the software. The generic demonstration version can only be used with the sample database; it cannot be used with a production database. Springbaud licenses are perpetual and therefore do not expire; once you purchase Springbaud, it’s yours forever. It’s provided with a free one-month, unlimited-use trial period after which a license key is required. Without a license key, Springbaud may still be used with the Raiser’s Edge sample database but will no longer function with the production database.

2.2 Product Registration Please refer to the above section ‘License Agreement’ which explains how to obtain a licensable version of Springbaud. Once installed and configured, Springbaud is registered for use after the initial one-month trial period by entering a product license key obtained on payment of the license fee. NOTE: If the Product Registration section described below is not visible, it is because Springbaud has either already been registered or because the installed version is the demonstration version linked to the Raiser’s Edge sample database. Please obtain a licensable version of Springbaud from the vendor. To enter a license key, proceed as follows: 1. 2. 3. 4. 5. 6.

Start and log in to The Raiser’s Edge with an account with supervisor privileges. Start Springbaud from the Plug-Ins window (Raiser’s Edge Bar/Plug-Ins). Press Ctrl-A to reveal the administration password text box. Enter your administration password (provided with your license key documentation) and click Enter. At the bottom of the Admin/Connections tab, in the Product Registration section, enter your license key and click Register. A message will be displayed indicating the license conditions. Check the I Agree checkbox and click Proceed to complete product registration. (The Product Registration section will then disappear from the Connections tab.)

If you require further information or have any questions about registering Springbaud, please contact us by email at support@protege.com.au or fill in the support request form available from our website support page.

Page 2 of 21


3. System Requirements Below are details of the system specifications Springbaud requires to be installed, configured and used.

3.1 Workstation requirements Springbaud is designed to run alongside The Raiser’s Edge, so any workstation suitable for The Raiser’s Edge will generally meet Springbaud’s requirements as well, the only caveat being that there is adequate disk-space and memory and that the user installing Springbaud has sufficient rights to do so.

3.2 Supported Raiser’s Edge versions At the time of writing, Springbaud has been tested with The Raiser’s Edge 7 versions 7.91 to 7.93 (all patch levels). It will be tested with the latest versions and patches of The Raiser’s Edge as Blackbaud releases them. You will be notified of any required updates to Springbaud provided we have your current contact details. However, it would be prudent to check with us before upgrading or patching The Raiser’s Edge if Springbaud is installed in any client workstations. Although not yet tested on earlier versions of The Raiser’s Edge 7, it is highly likely that Springbaud will integrate with versions as far back as 7.85 without any compatibility issues.

3.3 Raiser’s Edge security privileges Springbaud requires different Raiser’s Edge security privileges for installation and configuration than for normal use. For normal use – uploading lists and retrieving results – the standard privileges of the General User security group in the sample database are sufficient. Please ensure that Raiser’s Edge users who will be using Springbaud have at least the same privileges as this example security group. When Springbaud is being installed or configured, higher-level security privileges are required because changes to The Raiser’s Edge code tables and attributes are sometimes required. To that end, Springbaud can only be configured by a user with supervisor privileges; ie, the Supervisor account as well as any other user accounts with the Supervisor Rights option selected. This is also a requirement for the preliminary installation configuration (refer below). NOTE: A dedicated Springbaud user account on The Raiser’s Edge is not required for the plug-in version as the user’s Raiser’s Edge connection to the server is used. (The stand-alone version does require a dedicated user account and more details about how to set up and manage this account are available with the stand-alone version’s documentation.)

Page 3 of 21


4. Installing and Uninstalling Springbaud Springbaud installs in a similar fashion to most other software; a Windows installer is run on a compliant workstation and thereafter is available in the plug-ins tab of The Raiser’s Edge. Please refer below for system requirements before attempting to install Springbaud.

4.1 Installing Springbaud Springbaud comes in two plug-in versions (as well as stand-alone versions, not discussed here): A generic demonstration version useable only with The Raiser’s Edge sample database, and a production version which is created especially for each customer to integrate exclusively with their Raiser’s Edge database serial number. Installation of each version is virtually identical though some configuration steps are omitted for the generic demonstration version. To install Springbaud, first ensure that the workstation and the version of The Raiser’s Edge both conform to the system requirements mentioned above and that the user performing the installation has sufficient workstation rights. (Generally, Windows Administrator-level permissions are required.) Re-booting the workstation prior to installation is recommended as is closing any running applications, especially anti-virus software. To begin installation, simply run setup.exe, ensuring that the file Springbaud.msi is present in the same folder. You will be guided through the installation procedure and, thereafter, the configuration procedure. Refer below to ‘Initial Configuration’ for more information about setting up Springbaud. NOTE: If you would like to add a Springbaud icon in the Raiser’s Edge Bar, this can be achieved by modifying the RE_System_Object_Code code module of the System VBA Project. Please refer to Appendix 9.1 for instructions. IMPORTANT Modifications to The Raiser Edge user interface code should only be attempted by someone with Raiser’s Edge VBA programming experience. Modifications should be fully tested before being deployed to a live/production server.

4.2 Uninstalling Springbaud To uninstall Springbaud open Programs & Features (Windows 7, Vista, Windows Server 2008, etc) or Add or Remove Programs (Windows XP) from Windows Control Panel. Right click on the Springbaud entry then click Uninstall. Allow the uninstallation process to complete. NOTE: When Springbaud is uninstalled, the application data file is not deleted. This is because this file is often shared between several installations and because it contains important information such as settings and results retrieval history which may be useful for a subsequent re-installation. If it is necessary to delete, move or archive the file, you can find it in the Program Data folder on most Windows workstations.

Page 4 of 21


5. Initial Configuration Because multiple installations of Springbaud may exist on a network, when Springbaud is installed, two options are available for managing settings and other administration data: Shared (recommended for multiple installations) or Local. This option determines whether a single application data file is shared between Springbaud installations or whether each installation maintains its own data file. The application data file contains settings, results retrieval history, logs and the like.

5.1 Shared application data Where installations of Springbaud on multiple workstations will be used with the same Raiser’s Edge database, shared application data management is preferable. Sharing application data means that all installations of Springbaud are linked to the same application data file and therefore use the same settings, work with the same results retrieval schedule and contribute to the same log files. This means that a user – or users – can use Springbaud from any workstation where it is installed and experience the same application environment. Administration is also simpler because any workstation can be used to globally change settings, review logs, etc for all installations. For shared application data management to function, the application data file must reside in a location accessible to each Springbaud installation, usually a network folder.

5.2 Local application data In contrast to the shared application data scenario described above, local application data management means that each installation of Springbaud functions independently, without any interaction with other installations; settings, results retrieval schedules and logs will apply only to that installation. This configuration method can have undesirable repercussions if changes are made, for example, to one Springbaud installation or to The Raiser’s Edge; the changes would have to be replicated manually on other Springbaud installations in order to avoid any errors or inconsistencies between Springbaud installations. Obviously, where there is only one installation, a single application data file is the only option. But where there are multiple installations, each one will maintain its own application data rather than sharing common settings, etc.

5.3 The configuration process During installation, the user has the option to either link to an existing application data file or to create a new one. Linking to an existing data file is simply a matter of browsing to an existing data file from the configuration wizard and, provided it is accessible and of the correct version, clicking OK to complete the configuration process. Creating a new, local application data file requires that you enter various credentials associated with both your Campaign Monitor account and your Raiser’s Edge installation. Refer below to ‘A single installation or the first of several shared installations’ for complete instructions. NOTE: It is possible – and quite easy – to change a local installation to a shared one if, for example, Springbaud is subsequently installed on a second workstation. The opposite is also possible, though probably less beneficial. These migration processes are described in ‘Changing installation type’ below.

5.4 A single installation or the first of several shared installations The very first installation of Springbaud is, by necessity, unique because there is no existing application data file to link to. So the first installation must always create a new application data file. (It would be possible to utilize a data file from a previous installation provided that the file version is compatible, that user credentials are still valid etc but for the purposes of this document, we shall assume that no such file is used.) To proceed with local application data file installation, you must click Next from the initial configuration pane to enter the Campaign Monitor API pane. Here you enter your Campaign Monitor API key and test the connection to Campaign Monitor. After a successful connection, the Client Name selector field will be populated with one or more client names retrieved from your Campaign Monitor account. (Most accounts only have a single client.) If

Page 5 of 21


multiple clients are retrieved, select your preferred client name and enter your default Confirmation and Unsubscribe web landing pages. Then click Next to move to the Raiser’s Edge query filter pane. Select a Query Type filter and enter at least two characters (alphanumeric characters, underscore, hyphen and period/full-stop only) in the Query Prefix field. Then click Next to move to the configuration confirmation pane. When you click OK, configuration of Springbaud will be completed, an application data file will be created on the workstation and Springbaud will start. NOTE: New application data files are installed in a sub-folder of the workstation’s Program Data folder (Protege Solutions\Springbaud). If the application data file is to be shared with other Springbaud installations, it must be accessible to those installations. It is likely, then, that the data file will need to be moved to a more central location, for example, to a network folder. Its actual location is unimportant provided that it is reliably accessible to all Springbaud installations with which it is to be shared.

5.5 Subsequent shared installations Where subsequent installations of Springbaud are to share application data, they can now be pointed to the existing application data file during initial configuration as described in ‘The configuration process’ above.

5.6 Changing installation type Installations of Springbaud can be changed between Shared and Local quite easily. Converting from Shared to Local Data To change from shared to local data installations, copy the existing shared application data file to separate folders accessible by each installation, generally in the Program Data folder on the workstation. Then – importantly – move, rename or delete the original shared file. The last step will trigger Springbaud to prompt for the location of an application data file when it is next started. (If fresh configurations will be made for each installation, the original application data file may simply be archived or deleted, though the latter is not recommended due to the historical information contained in the file.) When each installation of Springbaud is next started and you are prompted for the missing application data file, browse to the new local file, test the connection and click OK. Springbaud will then be working with its own local application data while retaining all the settings and history from the previously-shared file. Please note that from then on, each installation will be completely independent of the others and that no common settings or logs will exist. Converting from Local to Shared Data To change from local to shared data installations, you must either choose one of the existing local application data files to be the shared data file or else create a new data file (as described above under ‘A single installation or the first of several shared installations’) which will then be shared. Importantly, you must move, rename or delete the existing local data files. This step will trigger Springbaud to prompt for the location of an application data file when it is next started. Put the new shared data file in a location accessible to all Springbaud installations, generally on a network drive. When each installation of Springbaud is next started and you are prompted for the missing application data file, browse to the new shared file, test the connection and click OK . Springbaud will then be working with a single, shared application data file with common settings, retrieval schedule, log files, etc.

Page 6 of 21


6. User Documentation Below is a summary of the User Help documentation, available from the Springbaud application by pressing the F1 key. Generally, this version will be more up-to-date than the application’s User Help.

6.0 Welcome to Springbaud Springbaud is a Raiser’s Edge plug-in which provides you with the tools to upload email subscriber lists directly from The Raiser’s Edge to Campaign Monitor and to add campaign results directly from Campaign Monitor to The Raiser’s Edge. Using Springbaud is easy: To upload a subscriber list from The Raiser’s Edge, simply create a Raiser’s Edge query which includes four required fields and with a name beginning with at least two identifying characters (for example, “SB”). Then start Springbaud, select the query from the queries list and click Upload and your list will be uploaded to your Campaign Monitor account. You can choose to automatically name your list from a field in the list query, to change your subscribe and unsubscribe options and to upload to alternate Campaign Monitor client sub-accounts. Retrieving results is even easier: simply start Springbaud and click the Retrieve button on the Results Retrieval tab. Results for your sent campaigns will be retrieved from Campaign Monitor and updated on The Raiser’s Edge. And you have the option to retrieve results for all of your campaigns, for only campaigns sent since a specific date, or for a single campaign. To get the most out of Springbaud, we suggest that you read this product documentation thoroughly. NOTE: All of our documentation assumes that you have a working knowledge of The Raiser’s Edge 7. Please consult its documentation before using Springbaud if this is not the case.

6.1 List upload tab The List Upload tab is where you upload email subscriber lists to Campaign Monitor. Tip: Check these two help sections if the List Queries selector on the List Upload tab is empty: ‘List Upload Settings’, and ‘Creating List Queries’. Upload Process To upload a subscriber list to Campaign Monitor, select a query from the queries list, ensure that the list has a valid list name and click Upload. (You can also alter any of the default list upload options described below before uploading.) The subscriber list will be uploaded to Campaign Monitor and a session log generated. Should any exceptions occur you will be notified and prompted to view the log which will contain the exception details. If a list with the same name already exists in your account - or your client sub-account - it will have a suffix appended such as “-A”. Refer to the note at the end of this section for more information. Below are descriptions of the various fields on the List Upload tab. CRM List Queries The queries list is derived from the collection of Raiser’s Edge queries which match both the Query Type and Query Prefix setting. For example, Action queries which start with the letters “SB”. Below List Queries is a section entitled List Upload Options. This section allows you to modify default upload settings, on a per-upload basis, such as Client Name and Unsubscribe URL as well as how the list is named on Campaign Monitor. EMS Client Name Most Campaign Monitor users will only have a single client, usually named after their organization. If this is the case, the Client Name selector is fixed to this sole client name. However, if the account contains more than one client, the selector shows the names of all clients found under the Campaign Monitor main account. The Campaign Monitor website has more information about clients and how to use them.

Page 7 of 21


EMS List Name Source and EMS List Name Your uploaded list may be named either by entering it manually, or automatically from a field in your list query’s data. If you choose automatic list naming, by selecting Set from the query’s ‘{Your List Naming Field}’ field, Springbaud looks for the field name specified in your List Naming Field setting within the query fields. If the field exists and the data in the field is identical for all records then the data is used to name the list. Otherwise, one of two warnings is displayed: “** Field not present in query **” or “** Field contains inconsistent data **”. In either case you can select I’ll enter it manually below and enter a name in the List Name box below. EMS Confirmation and EMS Unsubscribe URLs Campaign Monitor supports the use of customized web landing pages for subscription confirmation and unsubscription. In these fields you can override your default settings. Confirmed Opt-In You can override your default setting for whether a subscriber must confirm their subscription to a list or not. Checking Confirmed Opt-In requires that the subscriber reply to a confirmation email before they are subscribed; unchecking this option means that no confirmation email is required and the subscriber is immediately subscribed to the list. Unsubscribe Action Two unsubscribe actions are supported by Campaign Monitor when a subscriber unsubscribes from a specific campaign email: the subscriber can either unsubscribe from only the list used to send the specific campaign or they can be unsubscribed from all campaigns. NOTE: Because Campaign Monitor list names must be unique within a client-level account, if the name of a subscriber list already exists, the newly uploaded list will have a suffix such as “-A” appended to it. For example, “General Appeal” might be renamed “General Appeal-B” if subscriber lists “General Appeal” and “General AppealA” already exist. Note however that lists with the same name can exist if they belong to different client-level accounts. Refer to the Campaign Monitor website for more information.

6.2 Result retrieval tab The Results Retrieval tab is where you initiate campaign results retrieval from Campaign Monitor to The Raiser’s Edge. There are three results retrieval options: 1. 2. 3.

Retrieve all campaign results Retrieve results only for campaigns sent since a specific date Retrieve results only for a specified campaign

Simply select a retrieval option and click Retrieve. Sent campaign results will be retrieved from Campaign Master and added to the corresponding Raiser’s Edge records. If you choose to retrieve results for a single specified campaign, when you choose the campaign from the selector, information about the campaign will be displayed. This is useful when similarly-named campaigns have been sent on different dates or from different account clients. Not all campaign results are retrieved every time you click Retrieve; campaign results retrieval is scheduled according to how long ago the campaign was sent and when the last successful results retrieval occurred. This is to save time and unnecessary demand on the Raiser’s Edge and Campaign Monitor servers and networks. However, if you choose to retrieve results for a single campaign, the above criteria will be overridden. NOTE: Only campaigns which use lists which have been uploaded using Springbaud can be retrieved by Springbaud. This is because lists uploaded by Springbaud include an RE Record ID field which is used to identify the record to which to add results. Usually, this is the Action Import ID of an Action record associated with a Constituent.

Page 8 of 21


IMPORTANT You will not be able to use The Raiser’s Edge during results retrieval because it is important that Springbaud has exclusive access to those Raiser’s Edge records which have results pending. You should also try to ensure that other Raiser’s Edge users do not have records open during retrieval. There will undoubtedly be times, however, when a record is open to which Springbaud needs to add a result. Should this occur, you will be notified and a subsequent retrieval of the affected campaign will be scheduled. The affected record or records will also appear in the session log.

6.3 Creating list queries The list queries that appear in Springbaud are derived from existing Raiser’s Edge queries. Only Raiser’s Edge queries which match your upload settings Query Type and Query Prefix will appear in Springbaud. You can read more about these settings here. For example, if you want to display Action queries beginning with the letters “SB_”, you would create and save a new Action query with a name like “SB_Christmas Appeal 2013”. Springbaud displays this query if the upload settings Query Type and Query Prefix are set to “Action” (or “All”) and “SB_” respectively. Springbaud supports Action, Appeal, Campaign, Constituent, Fund and Gift query types. However, no matter which query type you choose, please be aware that Springbaud currently requires that it contain an Action Import ID field as one of the four required fields. Future release of Springbaud will likely provide additional flexibility in this respect. Creating a New List Query from the Query Template To create a list query, start The Raiser’s Edge and, if it exists on your installation, open the Springbaud query template, “_Springbaud_Query_Template”, in the query category Springbaud. Save it as a new query with a name which matches your Query Prefix setting. The template is an Action query so your Query Type setting must be “Action” or “All”. Creating a new query using the Springbaud query template ensures that the required query fields are included. Refer here for more information about list query fields. You may add custom fields as required, for example, Last Gift Date, Age or Gender. Refer here for more information about custom fields. Tip: If the query template doesn’t exist or you can’t find it, please consult your Raiser’s Edge administrator who should be able to find it or create one for future use. Refer to instructions to create both a query category and query template here. Otherwise follow the directions for ‘Creating list queries from scratch’. Use of the query template is highly recommended. NOTE: You may create a query using any basic query type, though you must ensure that it includes in its output at least these four required fields: 1) an Action Import ID, 2) an email address, 3) a name and 4) a salutation. Springbaud can currently record campaign results only to Action records, though this restriction will likely be relaxed in future releases. Tip: Run a new Springbaud query directly in The Raiser’s Edge before using it to upload a subscriber list to Campaign Monitor to ensure that the results are as you expect. Tip: Create a Query Category for your Springbaud list queries - for example, “Springbaud” or “Email Campaign Lists” - to more easily keep track of them. Refer to The Raiser’s Edge documentation for more information about query categories.

6.4 Creating list queries from scratch If you’d prefer not to use the Springbaud query template to create list queries, please carefully adhere to the following directions to create list queries “from scratch”. Otherwise your list may not be uploadable or the results of campaigns sent using it may not be able to be added to The Raiser’s Edge. Use of the query template is highly recommended.

Page 9 of 21


Creating a New List Query from Scratch Currently, Springbaud supports queries of type Action, Appeal, Campaign, Constituent, Fund and Gift. However, no matter which type of query you choose, please be aware that Springbaud currently requires that it contain an Action Import ID field - as one of the four required fields - which will generally be associated with a Constituent record. Future release will likely provide additional flexibility in this regard. Refer to ‘Creating List Queries’ for more information about required fields. Follow The Raiser’s Edge guidelines for creating a dynamic query of your chosen type. Select output fields which include all four of Springbaud’s required fields. You may rename the output columns in the Raiser’s Edge to your liking (eg Preferred Email Number to Email address). Note that Springbaud will check for the four required fields using the settings under Upload Settings/Required Field Mappings. The default mappings use the default field names of the most common output fields, eg Primary Salutation, but these may be customized as required. Finally, save your new query with a name which meets your Query Prefix setting criterion. Optionally, save it in a dedicated query category such as Springbaud for easy future reference. Tip: Run your new query directly in The Raiser’s Edge to ensure that its results are as you expect before using it in Springbaud to upload a list.

6.5 List query fields The image below shows the complement of fields in a sample list query:

There are two types of fields: Required Fields and Custom Fields. o

o

Required Fields must be named exactly as per your Required Field Mappings settings. (This alone is a good reason to always create new queries from the Springbaud query template which includes the required fields.) Custom Fields can be any additional fields you might wish to use for email content such as Age, State or Gender, or for reporting, reference, etc.

Tip: Right click on an output field of the query’s Output tab in The Raiser’s Edge and click Column Heading… to customize the name of a field. If the field is intended to be a required field, its name must match one of your Required Field Mapping settings. List Naming Fields Springbaud can automatically name your uploaded list with data from a custom field. For example, if you include a custom field called Campaign Name and the data in that field is “Christmas Appeal 2013”, you can direct Springbaud to use that information to name the list on Campaign Monitor. NOTE: To use the automatic list naming feature, the data in the custom field must be consistent. That is, it must be identical for all query records. For example, the Campaign Name field for every record must contain ���Christmas Appeal 2013” otherwise you will be asked to name the list manually.

Page 10 of 21


6.6 List query custom fields You may include up to 10 custom fields per list query in addition to the four required fields. Springbaud assumes that any fields which do not match the names of the four required fields are custom fields and will upload the data in these fields if they are provided. For example, custom list field such as Last Gift Date, Age or Gender may be added to campaign content, used for reporting or any other use you can think of. NOTE: Campaign Monitor places a limit of 30 characters on all field names including custom fields. Field names longer than 30 characters will be truncated by Springbaud on upload.

6.7 Query categories and templates It is recommended that you create both a query category in which to save Springbaud queries, and a Springbaud query template from which to create new Springbaud queries. Neither of these procedures can currently be carried out automatically by an application like Springbaud so they must be done manually. A Springbaud query template can be opened and “Saved As ...” to create a new query. If set up correctly, it cannot be changed by users so its integrity as a template will be maintained and queries created from it will conform to Springbaud’s minimum query specifications. Create a Query Category To create a query category in The Raiser’s Edge: 1. 2. 3.

Click on Queries in the Raiser’s Edge Bar or from the Go menu. Click Organize Categories below the Query window title. Click New Category and enter a suitable name, such as “Springbaud” then click OK, then OK.

Your new query category should then be visible in the query categories list to the left of the Query window. Create a Query Template The create a Springbaud query template: 1. 2. 3. 4. 5. 6. 7. 8.

Start and log in to The Raiser’s Edge with an account with supervisor privileges. Click on Queries in the Raiser’s Edge Bar or from the Go menu. Click New Query below the Query window title. Choose Query type = “Action” and Query format = “Dynamic”, then click OK. In Available Fields expand Action Information and double-click ImportID. Select Operator = “not blank”, then click OK to add it to Filters. In Available Fields expand Constituent/Addresses/Preferred Address/Preferred Phones/Preferred Specific Phones/Email and double-click Email Number. Select Operator = “not blank”, then click OK to add it to Filters.

Page 11 of 21


9.

Select the Output tab, in Available Fields, expand Query Fields and double-click on both Import ID and Email Number to add them to Output. 10. In Available Fields, expand Constituent and double-click Name to add it to Output. 11. In Available Fields, under Constituent, expand Addressee/Salutations and double-click Primary Salutation to add it to Output.

12. 13. 14. 15. 16. 17. 18. 19. 20.

In the main menu bar, click Tools/Query Options. Uncheck Other users may modify this query. In Query Name, enter “_Springbaud_Query_Template” (with an underscore prefix). In Query Category select the name of your new query category (eg, “Springbaud”). In Description, enter something like “This is a query template which should be used to create new Springbaud list queries. Don’t alter this query; use ‘Save As’ instead.”. Click OK, then save and close the new query template. Log out of The Raiser’s Edge and then log back in with a non-Supervisor (ie, general user) account. Open the query template. You should be warned that you may not save it. Save the query as a new query in the new query category you created and run it – preferably with some additional filter criteria to restrict the number of returned records – to ensure that it behaves as expected.

6.8 Administration The Admin tab is where you can change Springbaud settings and review installation information. This tab is only accessibly by Raiser’s Edge users with supervisor privileges via an administration password. Settings are divided into five sections each with its own tab. Please click on one of the links below for more information. o o o o o

Connection settings CRM settings List upload settings Results retrieval settings Data and log settings

NOTE: Changes to settings are validated as they are made and saved when you leave the Admin tab; there is no Save button to click. 6.81 Connection settings There are two “connections” which Springbaud must create in order to function: a connection to the CRM database, ie The Raiser’s Edge, and a connection to the email marketing system, or EMS, ie Campaign Monitor. (CRM and EMS abbreviations are used because future implementations of Springbaud are expected to support other Blackbaud products and additional email marketing systems.) EMS Connection Connection to Campaign Monitor requires the use of an API key. This key is unique to your Campaign Monitor account. Please note that it is different to a Client Id though the two appear similar. CRM Connection (** Not required for plug-in version) If you are using the stand-alone version of Springbaud, Raiser’s Edge requires that database connection credentials below are provided. The plug-in version, however, uses the current Raiser’s Edge session credentials so separate credentials are not required.)

Page 12 of 21


CRM Serial Number Your installation of Springbaud is locked to your production Raiser’s Edge database (or to the sample database if you are using the demo version). This field is for information only. CRM Username and Password If you are unsure of these credentials, please check with your database administrator who must create a Raiser’s Edge user account for Springbaud to use. This can be an existing account but it is recommended that a dedicated user account be created for Springbaud. CRM Database Number Generally, there is only one Raiser’s Edge production database and it is usually numbered “1”. If you have more than one production database please check with your database administrator to find out which number to enter. For reference, The Raiser’s Edge sample database is usually numbered “50”. Use Sample Database This option allows you to use Springbaud with the Raiser’s Edge sample database for testing and training purposes. The demo version of Springbaud is locked to the sample database so the settings for CRM Database Number and Use Sample Database are pre-set in this version. Please ensure that both your API key and, if required, your CRM credentials are entered correctly otherwise you will not be able to upload lists or retrieve campaign results. 6.82 CRM settings Many aspects of The Raiser’s Edge are user-configurable and specific to your organization, such as how invalid email addresses and bounce information are recorded. You can customize many of Springbaud’s CRM settings to match your current Raiser’s Edge configuration. The settings on this tab correspond to Raiser’s Edge Action Attribute settings for Phone Type, Action Status, Email Status, etc, and must match your Raiser’s Edge settings. Springbaud creates the default Attribute and code table entries when it is initially configured. They can be modified directly from the CRM Settings tab and Springbaud will propagate the changes to The Raiser's Edge; the previous Raiser's Edge Attributes and table entries will not be changed nor deleted. Phone Type Invalid Email Springbaud can automatically change a Raiser’s Edge Phone Type for an email address used in a list to represent an invalid email. To take advantage of this feature, the entered string must match an entry in the Phone Types table (under Config/Tables in The Raiser’s Edge). Leave this setting blank to turn off this functionality. Action Status Sent Raiser’s Edge Actions have a Status field which reflects the current status of the Action, for example, “Open”, “Completed” or “Closed”. Springbaud can automatically set the Action Status field provided that it matches an Action Status table entry (under Config/Tables in The Raiser’s Edge). Leave this setting blank to turn off this functionality. The next section, entitled Action Attribute Categories and Descriptions, allows you to customize how Action Attributes record the progress of campaign emails. There are three Attribute Categories - Status, Link Clicked and Social Media Linked - along with their associated Attribute Description settings. Email Status Category and Descriptions Together, these settings provide for the recording of the current status of email campaigns on the Action Attributes tab. The Description field of the Attribute must be of type “Table”. The code table must have the same name as the Attribute Category and contain entries for all of the Description settings. Springbaud installs with a suggested Category setting of “Email Status” and suggested Description settings of “Sent”, “Hard Bounce”, “Soft Bounce”, “Opened”, “Clicked”, “Complained” and “Unsubscribed”.

Page 13 of 21


Link Clicked Category and Descriptions These settings are used to record how subscribers interact with a campaign email’s links. The Description field of the Attribute must be of type “Text”. Springbaud installs with a suggested Category setting of “Link Clicked”. Clicked links are recorded as URLs in the Action Description field along with geo-location (if available) in the Action Comment field. Social Media Linked Category and Descriptions (** Not yet implemented by Campaign Monitor) These settings are used to record how subscribers interact with a campaign email’s social media content. The Description field of the Attribute must be of type “Table”. The code table must have the same name as the Attribute Category and contain entries for all of the Description settings. Springbaud installs with a suggested Category setting of “Social Media Linked” and suggested Description settings of “Facebook”, “Twitter”. Below are some examples of settings from the Raiser’s Edge Sample Database augmented with default Springbaud settings followed by some example Actions. Example Phone Type Invalid Email Setting

Example Action Status Settings

Example Email Status Settings

Page 14 of 21


Example Action - General Tab

Example Action - Attributes Tab

6.83 List upload settings The settings in this section allow you to customize various aspects of the list upload process between The Raiser’s Edge and Campaign Monitor. Many of these settings provide a default upload setting which can be changed on a per-upload basis on the List Upload tab. Default Client Name If your Campaign Monitor account has more than one client sub-account associated with it, you can select a default client sub-account to upload lists to. If your account doesn’t contain any sub-accounts, this field displays the account name. Default Confirmation URL This is the default web landing page for subscribers who subscribe via a campaign email. Default Unsubscribe URL This is the default web landing page for subscribers who unsubscribe via a campaign email. Page 15 of 21


Default Confirmed Opt-In Check this setting to have subscribers receive a confirmation email when they subscribe to a list via a campaign email. Uncheck it to immediately subscribe subscribers without sending an email. Default Unsubscribe Action Select All lists to unsubscribe subscribers from all lists when they unsubscribe from a single list. Select Only this list to unsubscribe subscribers from only the list from which they choose to unsubscribe. CRM Query Prefix Springbaud filters Raiser’s Edge queries according to the characters in this setting. At least two characters are required and only alphanumeric characters, underscore, hyphen and period/full-stop are allowed. Characters are case-sensitive. For example, “SB_” will select queries such as “SB_Christmas Appeal 2013” and “SB_High-value Donors” but not “eM_Christmas Appeal 2013” or “SB High-value Donors”. CRM Query Type Springbaud can accept most Raiser’s Edge query types including Action, Appeal, Campaign, Constituent, Fund and Gift. Selecting one of these will exclude other types while selecting All will include all supported query types. Please refer to ‘Creating List Queries’ for more information about query types. CRM List Naming Field Springbaud can automatically name lists uploaded to Campaign Monitor by extracting data from a specified custom field. If the field name in this setting corresponds with a field in the query data and the data in the field is consistent for each record, it can be used to name the list. If the field either doesn’t exist or it contains inconsistent data, the list must be named manually. Required Field Mappings This section specifies the relationship between the required field names in the Raiser’s Edge query and the uploaded Campaign Monitor list. For example, the Raiser’s Edge query might contain two fields named “New Email Address” and “Old Email Address”. In this case you would enter “New Email Address” in the Email Address row of the CRM Field column to upload the correct field data to the Campaign Monitor Email field. Minimum Salutation Length and Substitute Salutation These two settings are used to replace invalid or missing salutation data in list query records. For example, if a salutation name contains only a single character, it is likely to be just an initial rather a valid salutation. So rather than address a recipient as “Dear J”, the value in Substitute Salutation would replace the single letter and the correspondence would read, say, “Dear Supporter” instead. Be aware that this feature should be used with caution as names such as “Al” or “Jo” are probably valid salutations whereas “AA” and “CJ” are probably not. 6.84 Result retrieval settings Springbaud utilizes intelligent results retrieval wherein campaign results are retrieved on a schedule according to the age of the campaign (when it was sent) and when the last successful retrieval occurred. This means that only incremental results are retrieved and that results are retrieved less often for older campaigns than for newer ones. The settings in this section allow you to customize the criteria for retrieving campaign results. Retrieval Start Date and Retrieval Range These two settings allow you to define a moving window of campaign sent dates for results retrieval along with a “hard” start date. For example, if you wanted to retrieve campaign results for campaigns sent no earlier than January 1st, 2013 and never more than 1 year ago, you would enter “01/01/2013” in Retrieval Start Date and “365” in Retrieval Range. In this example, for the first year, the window would gradually expand until on January 1st, 2014, the earliest date for retrieving results would advance and the retrieval windows would remain at 1 year thereafter.

Page 16 of 21


Retrieval Schedule This section defines five “bands” of campaign age and the frequency with which results are retrieved. The lefthand column defines five cut-off ages in days while the right-hand column defines five retrieval frequencies, also in days. For example, if Group One Age is set to “2” and Group One Retrieval Interval is set to “0.5” then campaigns sent within two days of the current date would have their results scheduled for retrieval every 12 hours (0.5 days). And if, in addition, Group Two Age is set to “7” and Group Two Retrieval Interval is set to “2” then campaigns sent between two and seven days ago would have their results scheduled for retrieval every second day. NOTE: These settings do not define an automatic retrieval of results, they merely define a scheduling mechanism for the manual retrieval process. Automatic results retrieval is available using the Springbaud Results Windows Service, which is a separate product and which requires the Raiser’s Edge optional API module. Auto Retrieval These settings are available only in the above-mentioned Springbaud Results Windows Service. For more information, please contact the vendor. 6.85 Data and log settings Data management and log settings as well as product information are contained in this section. Data Management Springbaud stores campaign result data and, optionally, log data in a settings file. Over time, the size of the settings file can grow and potentially slow the application down. This section provides settings for enabling event and error logging and enabling the purging of logs and data. By default, both event and error logging and log purging are enabled and data purging is disabled. The default log purge age is for logs older than 90 days. Information This section displays version information for Springbaud, The Raiser’s Edge and Campaign Monitor. Logs This section is not yet implemented.

Page 17 of 21


6.9 Configuration Springbaud requires details of both your Raiser’s Edge installation and Campaign Monitor account before it can upload email subscriber lists or retrieve campaign results. When configuring Springbaud, you can either manually enter the required credentials and preferences and create a local application data file or, alternatively, you can connect Springbaud to an existing or shared application data file. Shared Application Data Where there are several installations of Springbaud on different computers, the preferred configuration is to share a single application data file. This allows all Springbaud installations to share common settings and to synchronize their results retrieval schedules. (Similarly, where Springbaud is being reinstalled and it is desirable to retain the settings of the previous installation, connection to an existing settings file is required, whether it be local or shared.) Local Application Data When there is only a single installation of Springbaud – or the installation is the first of several – a new settings file must be created. (It may later be shared with subsequent installations if necessary.) 6.91 Shared or existing application data To configure Springbaud to connect to an existing or shared application data file: 1.

2.

3.

Click the Browse button on the first pane of the configuration wizard and browse to the folder containing the application data file to which you want to connect (usually named “ApplicationData.dat”). Use of network folders and mapped drives is supported so shared settings files may be located on servers and computers other than the installation computer. Select the settings file and click Open then click Test Connection. If the settings file is valid and of the correct version, the Test Connection button text will change to “Connected!”. Otherwise you will receive an error explaining why the file cannot be used, eg “Incorrect data file version. (File is version 3 but version 4 is required.)”. After you have connected to a valid settings file, click OK and Springbaud configuration will be complete.

6.92 New local application data To configure Springbaud with a new local application data file: 1.

Click the Next button on the first pane of the configuration wizard to begin the new application data file creation process. 2. Enter your Campaign Monitor API key and click Test Connection. If the connection to Campaign Monitor is successful, the Test Connection button text will change to “Connected!”. Otherwise, you will receive an error message explaining why the connection failed, eg “Supplied API Key is invalid”. 3. After your connection has been validated, click Next to proceed to the next pane. 4. NOTE: If you are using the plug-in version, this pane will not be displayed as Springbaud will use your current Raiser’s Edge session credentials. If you are using the stand-alone version of Springbaud, enter your Raiser’s Edge database credentials then click Test Connection. If a connection to your database is successful, the Test Connection button text will change to “Connected!”. Otherwise, you will receive an error message explaining why the connection failed, eg “Invalid User Name or Password”. 5. After you have entered your Raiser’s Edge database credentials, if required, and your connection has been validated, click Next to proceed to the Raiser’s Edge query filter pane. 6. Select a Query Type option and enter a Query Prefix to filter the Raiser’s Edge queries which Springbaud will display. 7. Click Next to proceed to the final configuration pane. 8. Click Back at any time to revise your entries or OK to complete Springbaud configuration. Refer to the configuration reference immediately below for detailed field information or to ‘Initial Configuration‘.

Page 18 of 21


6.93 Configuration reference Below are descriptions of the details required to create or edit Springbaud settings. Account API Key This is the API key of your Campaign Monitor account. Please note that although the API key and Client IDs appear similar, they are not interchangeable. Your API key is available from your Campaign Monitor account. Please refer to Campaign Monitor documentation for details about how to obtain your API key. Default Client Name Most Campaign Monitor accounts have only a single client name or ID. If your account has multiple client subaccounts, the names of the clients will be displayed in the Default Client Name selector where you can chose the one to use as your default. (Client Name can be changed on a per-upload basis when uploading lists.) Default Confirmation and Unsubscribe URLs Campaign Monitor supports custom web landing pages for subscription confirmation and unsubscribes. You should enter the URLs of your default web landing pages here. (The default URLs can be changed on a per-upload basis when uploading lists.) User Name and Password* User Name and Password are the credentials of a Raiser’s Edge user with which Springbaud logs in to The Raiser’s Edge. It is preferable to create a dedicated Raiser’s Edge user account rather than share an account. Database Number* Consult your Raiser’s Edge system administrator to obtain the number of your Raiser’s Edge production database. It is usually “1” where only a single production database is installed. Use Sample Database* If you wish to use Springbaud with the Raiser’s Edge sample database, check this box. You must have the sample database installed and connected. Check The Raiser’s Edge documentation or with your system administrator for more information about using the Raiser’s Edge sample database. Query Type and Query Prefix Springbaud filters Raiser’s Edge queries using these two criteria. You may select either all query types or a single query type to display in Springbaud. Similarly, Query Prefix will filter queries based on their name. At least two characters are required. Query Prefix is case-sensitive and only alphanumeric characters, underscore, hyphen and period/full-stop are allowed. * Required by the stand-alone version only; the plug-in version uses the current Raiser’s Edge session credentials.

Page 19 of 21


7. Product Support and Feedback Protégé Solutions aims to provide you with same-day support should you require assistance with any aspect of Springbaud. We also welcome your feedback, both positive and negative, as it assists us in improving our products and services.

7.1 Support Please email us at support@protege.com.au or fill in the support request form available from our website support page.

7.2 Feedback Please email us at contact@protege.com.au or fill in the contact form on our website contact page.

8. Product Release Notes The release notes for Springbaud below are provided for your reference. Date

Version

Comments

2014-04-22

1.0.1

Name changed to Springbaud and this documentation updated.

2014-01-10

1.0.1

Production demo version release. Not released to market.

2013-11-19

0.0.2

Second beta trial release to selected customers.

2013-10-31

0.0.1

Beta trial release to selected customers.

Springbaud is a trademark of Protégé Solutions Pty Ltd. Disclaimer: The Raiser’s Edge is a trademark of Blackbaud, Inc. Protégé Solutions Pty Ltd is not associated with Blackbaud, nor are its products supported or endorsed by Blackbaud.

Copyright ©2014 Protégé Solutions. All rights reserved. No part of this publication may be republished except in its original form.

Page 20 of 21


9. Appendices 9.1 Adding a Springbaud icon to the Raiser’s Edge Bar If you would like to add a Springbaud icon to the Raiser’s Edge Bar, some VBA code modifications are required. IMPORTANT This modification to The Raiser Edge user interface code should only be attempted by someone with Raiser’s Edge VBA programming experience. It should be fully tested before being deployed to a live/production server. Start and log in to The Raiser Edge using the Supervisor account. (You must use the actual Supervisor account, not just an account with supervisor privileges.) 1. 2. 3. 4. 5.

On the Raiser’s Edge main menu, click Tools/Visual Basic for Applications. Click the RE Code Wizard menu item. Check the CustomizeFrontEnd checkbox and then click OK. If it doesn’t open automatically, double-click System/Modules/RE_System_Object_Code. In procedure Public Sub CustomizeFrontEnd_CustomFrontEndItem modify the code as follows: Const MYNUMCUSTOMITEMS = 1 ' = actual number of custom items lCustomItem = lCustomItem - mlStartItemOffset If ((lCustomItem > 0) And (lCustomItem <= MYNUMCUSTOMITEMS)) Then Select Case lCustomItem Case 1 sPluginProgID = "Springbaud.Springbaud" 'Case 2 ' sPluginProgID = “MyNextPlugIn.MyNextPlugIn” End Select End If

6.

And in procedure Public Sub CustomizeFrontEnd_UseCustomFrontEnd modify the code as follows: Const MYNUMCUSTOMITEMS = 1 ' = actual number of custom items mlStartItemOffset = lNumCustomItems bUseCustomFrontEnd = True ' uncomment this line to customize the front end

7.

Lastly, compile and save the System VBA Project and close the Visual Basic for Applications window.

NOTE: Other users must re-start The Raiser’s Edge before they will see the icon.

Page 21 of 21


Springbaud For Campaign Monitor