User Updaters

User Updaters allow you to easily maintain your users' custom user field data, which is especially useful for targeting mailings by custom user field data.

Before this feature was introduced, it was common for clients to update custom user field data by:

1. Creating a report that would do a series of calculations, like determining a user's total giving for a calendar year, or how much money a user can give before they "max out"
2. Make sure that report can be used as an import
3. Running that report
4. Downloading the report results
5. Creating an import page
6. Uploading the report results to that import page
7. Repeating the process every time you wanted to update the results

This worked well enough, but doing this manually could be time-consuming, tedious, and error-prone.

User Updaters provide this exact functionality with much less work. You'll still create a report that you can use in an import as in the first few steps above, but you can then kick off that import with a few clicks -- or even automate the whole process on a schedule.

User Updaters are only used for updating custom user fields and user groups, and have several requirements and safety features to give you peace of mind.

How it works

First, create a report that you want to use to import into your users' custom user fields. Here are some examples to get you on the right track:

  • How much money a user gave in calendar year 2020
  • How much money a user can still give this calendar year (for candidates and parties)
  • Number of one-time donations in the last 180 days
  • Whether a user has an active recurring donation
  • What is this user's membership level?

Maybe you already have a report that can tell you these answers -- good! But they probably take a while to run, because they need to do many calculations across many large database tables. But accessing the data directly from a custom user field is very fast, and that's exactly what we want to do -- put this data into custom user fields.

A good way to think about this is like the summary_user table, which is a collection of summary statistics for users. Getting stats like the counts of actions in the last 365 days for every user on your list would take a long time, but looking them up from summary_user is very fast. This lets you treat custom user fields like your own summary_user table.

To use a report with a user updater, there are a few requirements. Your report must:

  • have exactly one display column for user_id, email, or akid, because this will be used to identify users to update
  • have at least one column for your custom user field(s) that will be updated, prefixed with user_, just as you would with an import. For example, to update a user's employer custom user field, your column must be named user_employer
  • have no extra columns besides the user-identifying columns (user_id, email, akid) and the custom user field columns
  • have the updater report category

For example, in this screenshot, we've created a report that shows the remaining amount of money a user can give to this candidate/political party in this calendar year:

https://s3.amazonaws.com/clientcon/images/user-updater-maxout-1.png

It's a good idea to run your report and double-check that the results are as you expect. For example, in the screenshot below, this shows that user id 1 still can give $1000.00 before they "max out."

https://s3.amazonaws.com/clientcon/images/user-updater-maxout-2.png

Note

This report doesn't reflect the current values of the custom user field user_donation_maxout -- it reflects the values you want to be in user_donation_maxout when you run the user updater.

Once you have your report created, create a user updater. From the Users or Reports tab, choose "User Updaters" from the sidebar menu, then add a user updater. Use the report you created in the previous step.

https://s3.amazonaws.com/clientcon/images/user-updater-maxout-3.png

If you want to run your user updater now, you can click "Save and Run Now" to begin. You can also schedule it to be run automatically at the time you specify.

When your user updater runs, it works just like an upload. Users who match your report will have their custom user fields updated with your report data.

https://s3.amazonaws.com/clientcon/images/user-updater-maxout-4.png

Requirements

  • Allowed User Fields must be created in advance, or your upload will fail. They will NOT be auto-created as needed.
  • Behind the scenes, user updaters run uploads on an internal import page, set to skip action creation. This is why your report's column names are so important -- they're how we know who should be updated and what data to put where.
  • Reports cannot have duplicate column names.
  • Reports can only be associated with one user updater at a time.
  • Reports that accept parameters can be used with user updaters, but only ones that are run manually. Scheduled user updaters cannot use parameters.
  • User updaters that are not on a schedule are only run when you run them manually.

Notes

  • You cannot update any fields except for custom user fields with user updaters. For example, you cannot update address1 with a user updater.
  • No users are created.
  • No actions are created.
  • Subscription status is not changed.
  • Language is not changed.
  • Tags will not be applied.
  • Users can be added to/removed from user groups, using any of the columns: group, group_id, group_remove, group_id_remove
  • The user's updated_at timestamp is not modified.

Adding / Removing Users to/from User Groups

To add a user to a user group, you can use either the group or group_id column (not both). Groups must be created in advance before adding users to them.

  • group needs to match the name of a user group.
  • group_id needs to match the ID of a user group.

To remove a user from a user group, you can use either the group_remove or group_id_remove column (not both).

  • group_remove needs to match the name of a user group.
  • group_id_remove needs to match the ID of a user group.

Troubleshooting

To make it easier to troubleshoot problems with user updaters, we have a built-in report Recent User Updater Status. Running it will show you the following columns:

  • job -- the ID of the report_user_updater job that ran
  • created_at -- timestamp of when the job ran
  • user_updater_status -- whether the report_user_updater job successfully ran. If this fails, we won't even try to start the upload.
  • upload_status -- whether the report_user_updater_upload job successfully ran. Most commonly, this will fail with header_failed if you are missing an Allowed User Field or if your column names don't meet the rules.
  • upload_id -- the ID of the Upload
  • line_count -- how many lines (including the header) were in the report results. Subtract 1 to get the number of users this affects.
  • upload_header -- which fields were used to identify and update users. This is especially important to check if your upload had the header_failed error, as it usually means that you have an invalid field here, haven't created an allowed user field, or are otherwise not adhering to the column name validation rules.

Warning

If you're using a user updater with a custom user field that allows multiple values, be warned that using a user updater will replace that user's existing entries for that field, if they exist.