Users¶

Subscription Status¶

The records show whether or not each user is mailable. You can see a user's subscription status in the core_user table. The options are:

• subscribed: The user is mailable. You'll see a "Subscribed since" row with an unsubscribe link below it.
• unsubscribed: The user clicked submit on an unsubscribe page or marked your email as spam. If a user marks your email as spam, they will have a source of 'mailing' in core_action for the unsubscribe and the mailing_id will be recorded. See below for how we deal with spam markers.
• bounced: The user's internet service provider sent a message in response to your email saying this user's email is permanently unusable. We don't record "soft bounces" where the ISP indicates the email address is temporarily unavailable.
• never: Only relevant for users who have been imported. If you set an import page to leave each user's subscription status alone, ActionKit will still create users for email addresses in your file that don't yet exist in ActionKit -- these users will get a subscription status of "never".
• blocked: The user has subscriptions, but their email domain or address is blocked via the email blackhole feature. Often, these blocks are of emails at typo domains, done to improve deliverability. If you unblock their domain or address, their status will change to 'subscribed'.

Basic Search¶

You can perform a quick search from the Users Tab. Enter the relevant information for any of the following fields in the search box in the top right of the screen:

• Name - Enter the user's first name, last name or both. Searching by both is fastest. The results only include exact matches. For example, searching for Jen won't return any Jennifers.
• Email - Enter the complete email address. Results only include exact matches.
• User id - Enter the complete user id. Results only include exact matches.
• Zip code - Put the zip in quotes. Otherwise you'll also find any email address that happens to include the digits in the zip code.
• User field value - Enter the custom user field name and the value you want to find. For example, if you have a custom user field called occupation, you can enter occupation=doctor to find all users with that as their occupation. You don't need to use quotes around the field name or the value.

Click Search. You'll land on the search results screen where a list of matching users is displayed.

Advanced Search¶

Advanced search provides considerably more options than a basic user search.

To perform an advanced search:

Click the Advanced Search button at the top of the Users column on the left.

The default is All records which will show you all the users in your database. To limit this Add a Filter by selecting from the dropdown. You can set a sort order if you'd like. Then click Search. Your results are returned on the search results screen.

Filter Options

The filter options are taken from those found in the Users query builder. All filters include some common controls:

• Click on the × icon to remove a filter.
• Click and drag the ≡ to change the order in which the filters appear.
• To exclude rows based on a filter, click on the green Required button to toggle it to Excluded.

Many filters include variables that you can adjust. You'll see these as soon as you select the display.

For example, if you select the display type Number of Actions, you'll see a dropdown with All Actions selected by default. You can change this to:

• Completed Actions - only those with a "completed" status in core_action.
• Non-Spam Actions - only those not designed status="spam" in core_action; only relevant if you've enabled spam checks.
• Spam Actions - only those with a "spam" status in core_action, only relevant if you've enabled spam checks.
• Advocacy Actions - status completed and action on one of the following page types: LTE, call, petition, letter, whipcount.
• Non-Import Actions - status completed and action on any page type except Import.
• Also Told A Friend - action on any page where the user sent at least one TAF email through the TAF widget. Does not include social media sharing.

You'll also see options for restricting the time period of the actions (e.g. today, last year, custom range, etc.) and specifying the action count.

To see a list of the choices and the corresponding SQL for any of the available filters, view the Query Builder SQL Reference.

There are some filter options in the query builder that aren't here (e.g. SQL expressions and row limits). Also, blank fields are treated as empty values instead of as parameters.

Custom Search Queries¶

On the Pages, Mailings and Users Tabs, you can define and save searches that will return a matching list of pages, mailings and users, respectively, in the Tab's list layout.

Custom Search Queries are query reports saved with the relevant tag. You may want to create one to save time if you often use the same criteria under Advanced Search. Or, if your Advanced Search times out, you may be able to write more efficient SQL that will complete. Advanced Search uses the query builder, which is designed to accomodate many possible combinations and therefore writes inefficient SQL.

Defining one or more custom search queries will cause a new section to appear in the navigation links on the right hand side of the tab. Toggle open the Search Queries list to see a list of the defined search queries, then click one to run that query.

Custom search queries can support one or more query parameters to allow search values to be entered. Simply define your parameters as you would for any other query report. When you run a search query, you will be prompted to enter values for any parameters it contains.

The order of objects returned by your query will define the order of the search results, so include an ORDER BY clause to specify your desired sorting.

To create a user custom search query, create a query report and assign the user search tag to it. Use the query builder or write your own SQL. Regardless, the query can only contain SELECT statements. Only the first column returned will be used by the search function, and that first column must be named id or user_id and contain the IDs of the user who match your search.

Search Results¶

The search results screen displays a list of all users who met the search criteria.

For basic or advanced search results, you can sort your list by any of the criteria in the drop down menu next to Order by. Select Ascending or Descending and click Search.

Shown above the search results are links to display a list of all users in your instance by clicking on the total, or to start a new search by clicking on Advanced Search.

To view an individual user record click on the user email or the Edit link in the Actions column.

Action History¶

You can view the user's complete action history by clicking the Action History link. Every action the user has taken is shown, most recent first, with the date, page ID and name, and page type.

If you click on the name for any action, you'll see the action source, including the mailing_id where relevant, and the values entered for any actionfield associated with the page. If the action subscribed or unsubscribed the user, the list_id (s) will also be shown. Click the Expand All link above the action history table to show the details for all actions.

Since February 2019, you'll have the option of re-sending the confirmation email for recent donation and event creation actions.

Click Event Page in the Info column to open the host page of this user's event.

You can also use the links in the Info column for managing donations or past actions.

Donation History¶

You can view the user's complete donation history by clicking the Donation History link. Every donation, attempted donation, and recurring payment for the user is shown, most recent first, with the date, order ID, activity type, status, amount, any additional information for the transaction, and action links.

If you click on the row for any transaction, depending on the type of payment (one-time vs recurring) you will see additional information about the transaction, including:

• Payment processor
• Recurring profile ID
• Recurring profile start date
• Recurring profile status
• Recurring profile total paid
• Transaction ID
• Action ID
• Page title and ID
• Action field(s)
• Candidate(s)
• Source

You will also have the option to re-send a confirmation mailing for that donation if a donor has misplaced their original confirmation mailing receipt. Confirmation mailings can only be re-sent for a limited time, and are only available since February 2019.

Click the Expand All link above the donation history table to show the details for all donations.

You can also use the links in the Actions column for managing donations.

Mailing History¶

You can view the user's complete mailing history by clicking the Mailing History link.

This screen displays a mailing contact summary table as well as the most recent 100 mailings that have been sent to this user and shows total opens, clicks, actions, gifts and TAF sends from these mailings. Click the Expand All link above the mailing history table to show the details for all mailings.

Scroll to the bottom of the list for a link to see the full mail history for this user.

Manage Subscriptions¶

You can view the user's subscription history and add and remove them from specific mailing lists by clicking the Manage Subscriptions link.

The first portion of this screen shows the mailing lists the user is currently subscribed to, with an unsubscribe link for each.

If there are mailing lists to which the user is not subscribed, you will see an option to add the user to that list.

Below that is a list of the user's mailing list subscription history, showing the dates on which the user was added or removed from mailing lists, and what prompted the change.

The following is a list of all available options for the subscription status change:

• Subscribe
• Subscribed by Admin
• Subscribed by API
• Subscribed by Import
• Subscribed by Uploader
• Subscribed by User Merge
• Unsubscribe
• Unsubscribe Admin
• Unsubscribe Bounce
• Unsubscribed by Feedback Loop (Clicked Spam)
• Unsubscribed by Import
• Unsubscribed by Re-Engagement
• Unsubscribed by Spam Check for Actions
• Unsubscribed by User Merge
• Re-Subscribed by Admin, undo Spam Check
• Put on Re-Engagement List
• Engaged, so Moved off Re-Engagement List

Partial refunds¶

ActionKit currently only supports partial refunds for the Braintree payment processor, and only after the initial charge settles, which normally happens overnight. (ACH Direct Debit donations can take three days to settle.) From the user’s Donation or Action History screen click the "Reverse Payment" link, this brings you to the "Reverse Donation" screen and if the donation has settled, you’ll see a link at the bottom to "issue a partial refund".

Click the "issue a partial refund" link and a box with the amount available for refund will display. We subtract any previous partial refunds so you can’t refund more than was donated.

If you can't issue a partial refund, there should be a sentence in the same place explaining why.

For reporting purposes, ActionKit will reduce the amount in core_order by the amount refunded, and add a row to core_transaction with type='credit' and the amount refunded as a negative value. Starting February 2018, query builder reports and ActionKit built-in reports that calculate payment totals using core_transaction factor in credits as needed. To update any older query builder reports, just open them for editing and press Save.

For custom reports, or modified versions of ActionKit reports, you might need to make changes by hand if you want to correctly count partial refunds. If the report uses core_transaction to generate totals, make sure it uses type in ('sale', 'credit') instead of just type='sale', and use amount != 0 to replace any instances of amount > 0. Some donation reports don't need changes, like reports that count donors without looking at payment amounts, or reports that only access core_order and never core_transaction.

Recurring Profile¶

You can reach the Recurring Profile screen by clicking on Manage Profile from the Recurring Donations section of the user record, or by clicking on View Payments from the user's Donation History screen.

The Recurring Profile screen displays information about the recurring profile including start date, number of payments, sum of payments, current charge amount and the date of the next charge.

You can change the amount, credit card, bank information, or billing address for future payments except for PayPal profiles. The billing address is prefilled from the last saved billing address for this profile, and changes to the billing address are only available for Braintree, Authorize.net, and PayFlowPro accounts.

Note

PayPal does not support changing the amount, credit card, or billing address for future payments. To make any changes to PayPal recurring profiles, cancel the old recurring payment and start a new one.

You can also refund past payments and cancel future payments.

Any changes made will be tracked in the Donation Change Log which notes who made the change and whether it was a staff or the user.

It's best to manage all of these options through ActionKit, not directly through your merchant vendor account, so the changes are captured in ActionKit and transmitted to the vendor.

Any changes you make from this screen are processed through a page called admin_update_recurring that has the confirmation email unselected. If you want users to receive an email after staff make changes to their recurring profile, you can edit this page and select the confirmation email.

Adding User Field Values¶

In addition to using the API, you have several choices for adding values to a user field:

• You can ask users to enter values by including the field in your user form on any page. To do this, you'll need to customize the fields used on the page, see User Form Fields. Validation and defaults are not applied to custom field values entered by users.
• You can enter values yourself through the user record.
• You can also import custom user field values from a CSV or TSV file using the uploader. Validation and default values are not applied to imported custom user fields.

The field name, the user response and the user_id (parent_id) are saved to core_userfield, along with a timestamp (updated_at).

Here's an example of the query you'd use to find each user's id and response:

select parent_id as 'user_id', value as 'pets'
from core_userfield
where name='pet_name'

Join to the core_user table on parent_id=core_user.id to get user's name or email.

Targeting By Custom User Fields¶

You can select recipients for a mailing based on the value in a custom user field. There's a query for this in the query library. Or write your own query to target recipients based on whether they have a response at all.

Related Action and Last Updated¶

Custom User Fields now store the related action that created them (if any) and when they were last updated.

Permanent User Merge¶

Permanent user merge allows you to set and forget your user merges: we'll re-merge users after an action so you don't have to. The re-merge happens automatically shortly after a user takes action using the email address that you didn't want to keep.

For example, if you've merged DontUseThisEmail@example.com into GoodEmail@example.com, and afterwards DontUseThisEmail@example.com is used for another action, then permanent merge ensures that this unwanted second user quickly and automatically gets merged back into GoodEmail@example.com.

When enabled, all user merges automatically become permanent merges, including those that occurred before permanent merge was enabled in your instance.

Individual users can be removed from the permanent merge by clicking the "Stop Merging" button on the user profile.

Stopping a permanent merge for a user does not reverse previous merges or re-subscribe the user.

Repeat merges are triggered by actions. Changes that don't originate from an action won't trigger a merge. That includes staff changing the user's details e.g. name or subscriptions from the user profile page.

Permanent merge is enabled from the Site Configuration page.