Virtuous Tag Sync

Tag sync pushes the tags on your BetterUnite contacts onto the matching contacts in Virtuous, so a segment you built here is a segment you can find over there. It runs on a schedule, and you can run it on demand.

One thing shapes everything else about how this works, so it is worth knowing before you turn it on: Virtuous does not allow tags to be created through its API. A BetterUnite tag reaches Virtuous only if Virtuous already has a tag with exactly the same name. Rather than invent a tag or silently drop the name, BetterUnite reports it back to you. The setup page gives you a tool for bringing Virtuous tag names into BetterUnite first, which is the way around this.

What the sync does

• It only adds. A tag you remove from a contact in BetterUnite stays on the Virtuous contact. If you need it gone there, remove it in Virtuous.
• It only touches linked contacts. A BetterUnite contact is linked to Virtuous when a gift or pledge syncs. The tag sync never creates a Virtuous constituent, because a tag is not reason enough to create a donor record.
• It never duplicates. Before writing anything it reads who already carries each tag in Virtuous, and skips those.
• It combines duplicates. If two BetterUnite contacts are linked to the same Virtuous contact, their tags are pooled and sent together.

Turning it on

Go to Settings, open the Virtuous integration, and find the Tags section.

About auto tags. Auto tags are rewritten in bulk every time your rules are reconciled, so including them can mean a great many writes. Virtuous also has Smart Tags of its own that may express the same thing natively. Start with hand-set tags, and turn auto tags on only if you actually need them in Virtuous.

Bringing tag names over from Virtuous

This is the step that makes the rest work. Click Bring Tags from Virtuous and BetterUnite reads your Virtuous tag catalog and lists it, grouped by tag group.

• Names BetterUnite does not have yet are checked for you.
• Names you already hold are labeled already in BetterUnite and left unchecked.
• A Virtuous tag whose name contains a comma is shown but cannot be selected. BetterUnite separates its own tags with commas, so a name containing one cannot round-trip. Rename it in Virtuous if you need it.

Add Selected to BetterUnite adds those names to your organization's tag list. That is all it does: no contact is tagged, nothing is renamed, and nothing is removed. From then on your staff are picking from names Virtuous will actually accept.

The tag list is cached for 30 minutes. If someone creates a tag in Virtuous and you want it now, click Refresh to read the catalog again.

Where tags are created in Virtuous: an administrator creates them there under Settings, then Data Management. There is no way to create one from BetterUnite.

Running the sync now

Sync Tags Now runs the push immediately instead of waiting for the schedule. It is capped at 250 additions so the page can come back with an answer; anything beyond that is picked up by the next scheduled run. The result panel tells you:

• How many tags were added, and across how many contacts.
• How many were left for the next run, if the cap was reached.
• Not in Virtuous, so not sent. These are the BetterUnite tag names that have no Virtuous tag. Create them in Virtuous to have them carry over.
• Skipped as ambiguous. Your Virtuous organization holds more than one tag with this name, differing only by capitalization, and there is no single exact match to break the tie. BetterUnite skips rather than guesses, because filing donors under a tag nobody chose is worse than filing them under none.
• Errors, if Virtuous rejected a particular write.

The scheduled run

The sync runs automatically every six hours for every organization that has it switched on, so once it is configured there is nothing to remember.

A scheduled run will make up to 2,000 additions. It also watches your Virtuous API budget and stops early, leaving headroom, if the remaining requests in the window get low. Either way the remainder is carried to the next run, and runs pick up in a predictable order, so a large first sync finishes over a few passes rather than spending your whole rate limit at once and starving your donation and activity syncs.

How tag names are matched

Matching ignores capitalization, since a name typed in BetterUnite is rarely capitalized the way the Virtuous tag is. So Major Donor in BetterUnite matches major donor in Virtuous.

If your Virtuous organization holds several tags that differ only by case, an exact match wins. Without one, the name is reported as ambiguous and skipped. Cleaning up near-duplicate tags in Virtuous is the fix.

Recommended order of operations

1. In Virtuous, create the tags you want to be able to set from BetterUnite.
2. In BetterUnite, click Bring Tags from Virtuous and add those names.
3. Tag your contacts using those names.
4. Turn on Send Contact Tags to Virtuous.
5. Click Sync Tags Now and read the result. An empty not in Virtuous list means every name you are using will carry over from here on.

Permissions

All of these controls, and the Virtuous integration page itself, require full access on the organization and the Virtuous integration entitlement.