Overview
This documentation describes how the online donations module in the Officer Portal and Member Portal applications -- function along with the administration module within Patriot. The online donations module is a configurable module that allows flexibility for receiving donations.
Patriot
When administering an online donation, Patriot allows the addition, modification and deletion of each online donation. The screen provides the ability to enter a friendly display name for the online donation, which will appear on the online donations screen. Select the campaign, appeal and fund that the donation should be applied to and an optional chapter that can be associated with the fund. Select the type from an existing type or add a new donation type. The donation types may be used for reporting purposes or could have programmatic implications of the processing of the donation within the utility. The online donation page can display text or HTML custom to the online donation in the sidebar of the page. If no HTML is provided, the default graphic (setting is maintained in in the OP System Settings > OnlineDonationDefaultGraphic) will be displayed.
When a donation is made, the system can optionally send an acknowledgement email to the donor. If an online donation has a donor acknowledgement email subject and donor acknowledgement email body present on the donation, the system will send an email to the email address that was entered on the donation form with that subject and body. The body text has merge fields available to customize the email. Those fields are located in a drop down list control in the editor of the body text. For reference, the merge fields are: [FirstName], [Lastname], [GiftDate], [GiftAmount], [OnlineDonationDisplayName]
Officer Portal & Member Portal
Currently, most of these features are present in the OP module as well as the MP module, however some features may be present in one and not the other. If there is a feature contained within this document is one that your organization is interested in using but is not present in your version of this utility, please contact Patriot Software for further support.
Configuration
The OP contains several system settings used in the online donations module. Most of these are within the Officer Portal system settings. They are as follows:
· DonationDisclosureText: If there is a value in this setting, the text (HTML or plain text) will be displayed just above the submit button. This allows custom disclosure text for each organization and the ability to update it as needed.
· OnlineDonationAckLtrCode: If a value is entered here that corresponds to acknowledgement letter codes in Patriot and appear as the Acknowledgement in the Fund Distribution Information grid on the gift entry/edit screen in Patriot.
· OnlineDonationHMAckLtrCode: If a value is entered here that corresponds to acknowledgement letter codes in Patriot, that will be used if an honor/memorial gift is made.
· OnlineDonationBannerImage: If a value of a location path to an image is entered here, a custom banner (masthead) image can be used on the page.
· OnlineDonationDefaultGraphic: If no custom HTML is found for a selected online donation, the default graphic found at the location entered in this value will be displayed.
The following features are not on by default. If your organization has the following features configured, the following settings should be referenced.
· OnlineDonation_SoftChapterAckEmailSubject: If a “SoftChapterID” value is passed in as a url token creating a soft credit for the chapter that is passed in, and if this setting has a value, an acknowledgement letter will be sent to the email address of this chapter. This line is the subject that is used.
· OnlineDonation_SoftChapterAckEmailBody: If a
soft chapter email is sent (above), the body of the email will be populated
with the value of this setting. This text has available merge fields that can
be used to customize the letter. Those merge fields are (please include
brackets and maintain case sensitivity):
[FirstName] (of donor), [LastName] (of donor), [GiftDate], [GiftAmount],
[OnlineDonationDisplayName], [SoftChapterName]
· OnlineDonation_SoftPersonAckEmailSubject: If a “SoftPersonID” value is passed in as a url token creating a soft credit for the person that is passed in, and if this setting has a value, an acknowledgement letter will be sent to the preferred email address of this person. This line is the subject that is used.
· OnlineDonation_SoftPersonAckEmailBody: If a soft
person email is sent (above), the body of the email will be populated with the
value of this setting. This text has available merge fields that can be used to
customize the letter. Those merge fields are (please include brackets and
maintain case sensitivity):
[FirstName] (of donor), [LastName] (of donor), [GiftDate], [GiftAmount],
[OnlineDonationDisplayName], [SoftPersonCompleteName]
· OnlineDonationStaffEmailTo_AddressList: If this is configured, once a donation is successfully made, a summary email will be sent to each email address in this setting with the details of the donation. If this feature is configured and this setting is empty, the default general error email address in the system settings will be used. If this setting has a value, the system will loop through each email address in a comma-separated list and send on email to each. To have multiple email addresses in this value, enter them in a comma-separated list, such as: [email protected], [email protected], [email protected]
· OnlineDonation_DonorThanks_EmailFromAddress,
OnlineDonation_DonorThanks_EmailFromName, SoftPersonThanks_EmailFromAddress,
SoftPersonThanks_FromName, SoftChapterThanks_FromEmailAddress,
SoftChapterThanks_FromName, StaffNotification_EmailFromAddress, StaffNotification_EmailFromName:
If the utility is configured to send acknowledgment emails to donors, soft
person donors, soft chapter donors, and staff notifications, then each of the
“from address” and “from name” values can be configured independently. If none
exist for these values, the default will be used, which is in the system
settings OPBatchEmailFromAddress and OPBatchEmailFromName. This configuration
is currently only available in the Officer Portal.
· ShowDonationHistoryOnDonationsTab: If this is configured as a valid Boolean value (true, 1) then the page will show the top 10 most recent donations for a person who is found by the system either by authentication or PersonGUID identifier in the query string.
· OnlineDonation_SuccessDisplayText: If a value is entered here, the text displayed for a successful donation will be populated with this value. If no value is present, default text will be used.
· OnlineDonation_DefaultOnlineDonationID: If a default online donation is to be selected by default for the page without the need for providing the value in query string, this online donation will be used for the gift.
· OnlineDonation_AllowAnonymousDonations: The module is configured by default to allow anonymous donations. If anonymous donations should not be allowed, a valid negative Boolean value in this setting (false, 0) will suppress the display of the option to allow the donation to be anonymous.
URL Query String parameters
The online donations page may be pre-populated/pre-configured with some data or settings by passing in certain parameters into the URL. Sometimes this page might be accessed from an outside website or other origin and certain pre-configuration may be required. The syntax of the URL will be
Base URL à https://yourdomain.org/donations/donations.aspx?
First parameter à
=
Remaining parameters require an ampersand (&) preceeding them.
Example: https://yourdomain.org/donations/donations.aspx?onlinedonationid=5&softchapterid=1093
The following parameters may be used:
|
Query String Parameter |
Value/Format |
Description |
|
PersonGUID |
GUID |
Each person found in Patriot now has a global unique identifier (GUID). This value is used to prepopulate information within the form and/or link a donation to the donor’s record. |
|
SoftPersonID |
Positive Integer |
If a donation is to have a matching gift attributed to a person, that PersonID can be passed in and the matching gift will be made. |
|
SoftChapterID |
Positive Integer |
If a donation is to have a matching gift attributed to a chapter, that ChapterID can be passed in and the matching gift will be made. |
|
OnlineDonationID
|
Positive Integer |
If the form should be configured so no selection of the online donation should be made, passing in the online donation id (found in Patriot) will pre-configure the form for that online donation. |
|
AudienceCode |
Text string (10 character limit) |
If the donation should be configured with a specified audience code, passing in the audience code (found in Patriot) will achieve that. |
|
GiftAmount |
Whole or decimal number |
If the form should be pre-populated with a specified gift amount, passing that amount in as a whole number or decimal number will populate the form with that amount and disable the amount from being changed within the form. |
|
GiftRecurrence |
Text string. One of the following values: onetime, monthly, quarterly, annually |
If a value is passed in, a recurring gift will be configured. The default is one time. Note: if setting a gift recurrence, the number of payments must also be set. |
|
NumberOfPayments |
Positive integer |
If a value is passed in and a gift recurrence is configured, the form will be configured with the recurrence and number of payments. Note: this requires a GiftRecurrence value. |
|
GiftAmountDisplay |
Boolean text string. Either “false” or “0” |
If a valid gift amount is passed in, then this query string parameter can be used to suppress the display of the gift amount controls on the screen. |
|
GiftRecurrenceDisplay |
Boolean text string. Either “false” or “0” |
If a valid gift recurrence is passed in, then this query string parameter can be used to suppress the display of the gift recurrence controls on the screen. |
|
NumberOfPaymentsDisplay |
Boolean text string. Either “false” or “0” |
If a valid number of payments is passed in, then this query string parameter can be used to suppress the display of the number of payments controls on the screen |
|
OnlineDonationType |
Test string. Must match one of the values in Patriot for the Online Donation Type. |
If a value is passed in, it will configure the “Investing In” Online Donation drop down list to display only values of this type. |
|
OnlineDonationTypeDisplay |
Boolean text string. Either “false” or “0” |
If value is passed in AND valid OnlineDonationType value is present, the row displaying the selection of the online donation type will not be displayed. |
|
NoBackground |
“true” |
If your implementation has a default background image that is coded into the page, providing this value will suppress its display. Useful when embedding the page in iframe element. |
|
Stylesheet_href |
Fully-qualified URI to a css file |
If this value is provided, an external stylesheet will be loaded and styles contained within that sheet will override the current page styles. Useful when embedding if custom styling/branding is needed. |
|
AppealID |
Positive integer |
If value is present, this value will be used as the Appeal and override any appeals connected to user selection. |
Additional Features
Split Distribution
If this feature is enabled, it allows custom logic to be put in place to split the fund distribution of the gift between the selected fund and a specified fund in the logic. For example, if a fund is selected but the organization would like to recover the 2.5% payment processing fee in the general fund, this could be configured so that if any fund except the general fund is selected to donate to, the utility will automatically distribute the gift in Patriot 97.5% to go to the selected fund and 2.5% to go to the general fund. This feature is off by default. If your organization is interested in this feature, please contact Patriot for configuration.
Responsive design for friendly view on desktop/tablet/mobile devices
This module has been re-designed to provide a responsive design to optimize the screen and user experience for desktop, tablet and mobile devices.
Embedding in external website
This module has been developed to be able to be embedded within an <iframe> html element in an external website. This allows for portability without sacrificing functionality. The only restriction in the embedded implementation is that both the embedded page and the parent page which contains the <iframe> element must be served over a secure https connection for security and compliance.
A sample, very simple implementation of this can be achieved with the following code:
<iframe src=”https://your-OP-or-MP-website.org/Donations/Donations.aspx” id=”donationIFrame”></iframe>
Patriot can help provide more complex implementation upon request.
Custom Theming
This module has been re-designed to take advantage of the Bootstrap CSS framework. By taking advantage of the external stylesheet query string parameter, your organization can quickly and easily theme and brand this module to match your embedded implementation. It supports overriding of any Bootstrap styles or rules as well as adding a Bootstrap theme or custom theme.
Custom Configuration
This module has grown to have some organizational-specific customizations which may not be documented here. If you have any questions or concerns about any of your customized components/functionality or would like to explore more options, please contact Patriot Software Solutions, Inc.