Maintaining Tags

Tags are often maintained in sync with some external data source by API clients. For example a Tag could be used to represent a Distribution List from your organisation's Active Directory.

A challenge for API clients is that it is quite easy to add Subscribers to Tags, for example via an Import Job, it is more difficult to determine who to remove after a sync.

How to maintain Tags when membership changes are known

In an ideal world, the API client would know exactly which membership changes to apply.

For example, if it is possible to add a scripted "hook" to run when the membership changes, or if it is possible to ask the data source for a delta of membership changes since the previous sync.

In such cases, the calls to add Tag to Subscriber and remove Tag from Subscriber can be used to update Poppulo to reflect the membership in your data source.

How to maintain Tags when membership changes are not available

Sometimes information about membership changes is not available. In this case, Poppulo has an API feature designed to update your Tags from a given Import Job In order to use this, you must be able to specify all the current members of the Tags in a single Import.

The set of Tags you want to synchronise must be specified in the replace_tags XML element of the subscriber_import_job.

You must then specify the membership. The two ways to do this are:

• using the tags XML element in the subscriber_import_job to ensure a particular set of Tags will be present on every record
• Including a "tags" column in the Import data to control the set of Tags per record

The Tags included in replace_tags will be "cleaned" during the Import. Anyone who used to be in the Tag, either from a previous API sync or due to a User add them, and who was not specified to be added or remain a member during the current Import will be remove as a member.

Example integration

Let us imagine we are synchronising Employees from Active Directory. We want to maintain a Tag representing "All Employees", and another Tag representing the "Sports and Social" and "Environment Committee" Distribution Lists (which do not contain everyone).

The following integration should allow this:

<subscriber_import_job>
  <accept_terms>true</accept_terms>
  <tags>
    <tag name="All Employees"/>
  </tags>
  <replace_tags>
    <tag name="All Employees"/>
    <tag name="Sports and Social"/>
    <tag name="Environment Committee"/>
  </replace_tags>
  <subscriber_data>
    <columns>"email","tags"</columns>
    <skip_first_line>false</skip_first_line>
    <data>"employee1@example.com",
"employee2@example.com","Sports and Social"
"employee3@example.com","Sports and Social"
"employee4@example.com","Environment Committee"
"employee5@example.com","Sports and Social,Environment Committee"
"employee6@example.com","Sports and Social,Environment Committee"
</data>
  </subscriber_data>
</subscriber_import_job>

All 6 records in the file should be present and tagged with "All Employees". There should also be 4 members of the "Sports and Social" Tag, and 3 in the "Environment Committee" Tag.

How not to maintain Tags

One approach that is not recommended is to issue calls to delete the Tags, and then re-create them.

This might appear to achieve the goal, but as the Tag is missing until the integration completes it has drawbacks:

• The Tag may be unavailable in the UI for use (without explanation)
• The Tag membership will be in flux, going from empty to full during the Integration
• Scheduled Sends to this Tag might not go to the expected Subscribers
• Saved Searches referencing this Tag might return unexpected results
• Custom Reports that use the Tag might return unexpected results
• Content readers viewing Microsites may not see all the Articles (due to Dynamic Content)

Even if the sync is done out of office hours, e.g. overnight or at the weekend, there is a risk that if the API client crashes then the UI Users are left without tags until this is rectified.

This could also happen if there was maintenance or an outage in Poppulo's API during the time the integration runs and the client does not retry.

Another thing to be mindful of is that there may be other Tags in the system that Poppulo Users have created for their own purposes. Be wary about programatically listing Tags, for example to try and implement some kind of "cleanup" operation by comparing with your external data source.

This also applies to the use of the wildcard * in the "removetags" column in the Import data