Changes to export templates: Donation and Recurring Status fields
As part of an upcoming feature update, organizations will need to adjust their export templates, specifically the Donation, Advanced Donation, and Recurring Status fields. This update introduces new fields to replace existing status fields, ensuring a smoother transition to enhanced functionality. If your organization relies on specific values in the status fields for integrations with exported files, these changes will be especially relevant to you. To ensure a seamless transition, we are adopting a phased approach consisting of three stages.
New status fields overview
The current Donation Status field will be replaced by a new, enhanced version of the same name: Donation Status. Similarly, the existing Recurring Status field will be replaced by an enhanced Recurring Status field. The Advanced Donation Status field will be fully deprecated, with its functionality now consolidated into the enhanced Donation Status field. The following tables illustrate the differences between the deprecated fields' values and their replacements. Changed, removed, and added values are highlighted in bold:
Donation Status
| Value of the deprecated field | Value of the new field |
|---|---|
| • success | • succeeded |
| • pending | • pending • scheduled • retrying |
| • refunded | • refunded |
| • failed | • failed |
Advanced Donation Status
| Value of the deprecated Advanced Donation Status field | Value of the new Donation Status field |
|---|---|
| • success | • succeeded |
| • scheduled • pending • retrying | • scheduled • pending • retrying |
| • refunded • disputed | • refunded |
| • failed | • failed |
Recurring Status
| Value of the deprecated field | Value of the new field |
|---|---|
| • active | • active • scheduled • retrying • paused |
| • failed | • failed |
| • cancelled | • canceled • completed |
Both fields will be available in all existing and new export templates. For new templates, these fields will be added to the "Fields for export" list by default, positioned after the Donation ID and Recurring ID fields, respectively.
Steps for organizations
First, it's crucial to identify if you have exports that are regularly sent to you which are relevant to these changes and could potentially disrupt your processes if not updated.
1. Assess your current setup
In this initial stage, identify affected templates and focus on them for the subsequent steps. By the end of this assessment, you should have a list of templates that you'll be working with. To conduct a comprehensive review of your export templates and schedules, follow these steps:
- Begin by accessing the Exports Templates page to get an overview of your current setup
- Carefully examine your templates for the following export types and fields:
Export type Field • New donations • Successful donations • Refunded donations • Failed donations • Shared tributes • Donation Status • Advanced Donation Status • New recurring plans • Cancelled recurring plans • Failed recurring plans • Recurring Status - Review the Frequency column for each relevant template, noting those with scheduled exports
- Investigate your active Deliveries and Destinations to understand the full scope of your export processes and identify any potential areas that may be affected by the upcoming changes
- After completing this review, assess which templates and processes may need updates to accommodate the new status fields and ensure uninterrupted data flow
2. Determine necessary actions
Based on your assessment, identify which scenario applies to your organization:
Scenario 1: No saved templates with listed export types
No action required: New enhanced fields are available for future use.
Scenario 2: Saved templates without scheduled generations
Recommendation: Replace deprecated fields with new ones before Phase 1 ends to avoid static messages in status values.
Scenario 3: Templates with scheduled generations and/or deliveries
Required action: Before Phase 1 ends, replace existing status fields with new ones to prevent static messages in generated files.
Scenario 4: Templates with integrations/automations based on scheduled deliveries
Critical actions required: To ensure uninterrupted functionality and data accuracy, please complete the following steps before the conclusion of Phase 1:
- Thoroughly review and update all affected export templates, incorporating the newly introduced status fields to replace the deprecated ones. This step is crucial for maintaining data consistency and avoiding potential disruptions in your export processes.
- Conduct a review and modification of your existing automations and integrations to accommodate the expanded range of status values:
- For Recurring Status: Implement logic to handle the additional statuses of
scheduled,retrying,paused, andcompleted. Update your systems to recognize the revised spelling ofcanceled(previously "cancelled"). - For Donation Status: Enhance your automation workflows to process the new statuses
scheduledandretrying. Ensure that all dependencies on thesuccessvalue are updated to usesucceeded, aligning with the revised terminology. If you previously relied on the Advanced Donation Status field, you should now consolidate that logic into the enhanced Donation Status field, as Advanced Donation Status well be deprecated.
- For Recurring Status: Implement logic to handle the additional statuses of
3. Implement changes
To update affected templates:
- Review existing templates and identify those with deprecated status fields
- Remove fields labeled with "(deprecated)"
- Add new Donation Status and Recurring Status columns from "Available fields"
- Save changes
Transition process
To ensure a smooth transition, we are implementing a planned three-stage approach. Our implementation consists of the following phases:
Phase 1: Dual field usage
During this period, both the old and new status fields will be available.
End Date: November 5, 2024
Changes to existing export templates
The existing names and values of the soon-to-be-deprecated fields will remain unchanged in the exported data. However, within the Exports interface, the labels Donation Status (Deprecated), Advanced Donation Status (Deprecated), and Recurring Status (Deprecated) will be added.
Here are two examples to illustrate this change:
- If a field was originally named Donation Status, Advanced Donation Status, or Recurring Status and its name remained unchanged, it will retain this name in the export settings. In the File Columns tab of the template, an additional label will be appended beneath the field name (e.g., Donation Status will display as Donation Status with the additional label Donation Status (Deprecated)).
- If any of these fields were renamed—for instance, if Donation Status was renamed to Opportunity Stage—it will retain this custom name. In the File Columns tab of the template, an additional label will be appended beneath the field name to indicate the field’s original function (e.g., Opportunity Stage will display as Opportunity Stage with the additional label Donation Status (Deprecated)).
The new enhanced Donation Status and Recurring Status fields can be added to the existing template columns from the Available fields section.
Changes to new export templates
The old Donation Status, Advanced Donation Status, and Recurring Status fields are renamed with the “(Deprecated)” label added. The values for these fields remain unchanged. The new enhanced Donation Status and Recurring Status fields can be added to new templates’ columns from the Available fields section and will be preset by default.
Donation Status (Deprecated), Advanced Donation Status (Deprecated), and Recurring Status (Deprecated) fields are available only to organizations that have used these fields in active (non-deleted) export templates. These fields are not available for addition or editing in new export templates for organizations that have not previously used them.
Phase 2: Transition to new fields only
Start Date: November 5, 2024
Changes for all organizations
The Donation Status (Deprecated), Advanced Donation Status (Deprecated), and Recurring Status (Deprecated) fields will no longer be available for addition to export templates for any organization.
Changes for organizations using deprecated fields
In templates using deprecated fields, their values will be replaced with static messages. These messages will indicate that the field is outdated and direct users to the new Donation Status or Recurring Status fields. When an export template is cloned, the deprecated fields will also be cloned as static fields containing these messages.
Phase 3: Removal of deprecated fields
Start Date: To Be Determined
The static Donation Status (Deprecated), Advanced Donation Status (Deprecated), and Recurring Status (Deprecated) fields will be removed from all export templates.