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 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
To use a report with a user updater, there are a few requirements. Your report must:
- have exactly one display column for
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
employercustom user field, your column must be named
- have no extra columns besides the user-identifying columns (
akid) and the custom user field columns
- have the
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:
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."
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.
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.
- 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.
- You cannot update any fields except for custom user fields with user updaters. For example, you cannot update
address1with 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:
- The user's
updated_attimestamp is not modified.
Adding / Removing Users to/from User Groups¶
To add a user to a user group, you can use either the
group_id column (not both). Groups must be created in advance before adding users to them.
groupneeds to match the name of a user group.
group_idneeds to match the ID of a user group.
To remove a user from a user group, you can use either the
group_id_remove column (not both).
group_removeneeds to match the name of a user group.
group_id_removeneeds to match the ID of a user group.
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_updaterjob that ran
- created_at -- timestamp of when the job ran
- user_updater_status -- whether the
report_user_updaterjob successfully ran. If this fails, we won't even try to start the upload.
- upload_status -- whether the
report_user_updater_uploadjob successfully ran. Most commonly, this will fail with
header_failedif you are missing an Allowed User Field or if your column names don't meet the rules.
- upload_id -- the ID of the
- 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_failederror, 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.
If you're using a user updater with a custom user field that allows multiple values, be warned that using a user updater will delete that user's existing entries for that field, if they exist.