Skip to content

uSync for Pro

UmbSocial.Pro.uSync is a paid add-on that lets uSync move UmbSocial Pro’s setup between sites as files, next to the free UmbSocial items. Set a site up once, export, and import on the others. It runs under your UmbSocial Pro or Agency licence.

dotnet add package UmbSocial.Pro.uSync

It brings in UmbSocial.uSync, and needs UmbSocial Pro and uSync 17.6.2 or later (before 18). There is nothing to configure: uSync finds the handlers, which appear on the same two cards on the uSync dashboard as the free ones (UmbSocial Setup and UmbSocial Library), with each card’s Report, Import and Export.

On a site without a Pro licence an import does nothing. Each file is reported as an error that says Pro is required (licence.pro_required), and nothing is written.

uSync can import by itself when a site starts: on its first boot (ImportOnFirstBoot) or at every start (ImportAtStartup). That import can run before UmbSocial has checked the Pro licence, so Pro’s items are refused, and the startup log shows a licence.pro_required error for each file. Your licence is not broken. The free UmbSocial items still import.

Once the site is up, open the uSync dashboard and run Import All, or Import on both the UmbSocial Setup and UmbSocial Library cards (Setup first), because Pro’s items are on both. By then the licence has been checked and Pro’s items come in. A site that was set up from files at first boot needs this one extra import.

Item Handler alias Folder uSync card Priority
Pro’s settings umbSocialProSettings uSync/v17/UmbSocialPro/Settings UmbSocial Setup 2200
Tags umbSocialProTags uSync/v17/UmbSocialPro/Tags UmbSocial Library 2310
Hashtag groups umbSocialProHashtags uSync/v17/UmbSocialPro/Hashtags UmbSocial Library 2320
Templates umbSocialProTemplates uSync/v17/UmbSocialPro/Templates UmbSocial Library 2330

Tags, hashtag groups and templates are one file each, named after the item. Pro’s settings are one file, pro-settings.config, which holds:

The priorities are the order of an import: the Settings card’s items first (the free channels and settings, then Pro’s settings), then the Content card’s (campaigns, tags, hashtag groups, templates), because templates and campaigns point at channels, which are by then on the site.

Import All runs all of these after uSync’s own handlers. Importing card by card does not: import UmbSocial Setup before UmbSocial Library. And on a fresh site, before uSync’s own Settings card has been imported, a template’s document types that aren’t there yet are dropped (transfer.reference_dropped), as are the free items’ page fields. Import uSync’s Settings card first, or the UmbSocial cards again afterwards.

Every item keeps its key on every site, so a post that carries a tag, or a template that names a channel, still does after an import. An item that already exists on the target only by name (a site set up by hand) is matched by name instead. It keeps the target’s own key, and uSync reports a warning (transfer.matched_by_name).

Files are written when an item is saved, as uSync does for Umbraco’s own items, and an item that is deleted leaves a delete action. Pro’s settings file is rewritten whenever a channel’s schedule, UTM tagging, short links or approvals are saved. The settings can’t be deleted through uSync: a delete action for them is refused (settings.cannot_be_deleted) and nothing changes.

Take care with the dashboard’s clean export: it empties uSync’s whole folder before it exports, so on a site without a Pro licence (where Pro’s items can’t be read) the SocialPro files are removed and not written again. An ordinary export never removes a file because of a missing licence.

The two cards are the defaults (the free handlers’ aliases are in the free package’s table). A site can put a handler on a different card by setting its Group in appsettings.json, in the shape uSync’s guide uses for Dictionary items. The key under Handlers is the handler alias from the table above. This moves Pro’s templates to the UmbSocial Setup card (use "Content" for uSync’s own Content card):

{
"uSync": {
"Sets": {
"Default": {
"Handlers": {
"umbSocialProTemplates": {
"Group": "UmbSocial Setup"
}
}
}
}
}
}

A group name that is neither one of UmbSocial’s two cards nor one of uSync’s own gets a card with the handler’s own icon.

A template that is imported has no owner. A template is normally changed or deleted by the person who made it, or by anyone with the Manage settings permission, so an imported one can only be changed by people who can manage UmbSocial’s settings. Everyone who can write posts can still use it and duplicate it.

A template that names a campaign, a channel or a document type that isn’t on the target is imported without it, with a warning that names what was left out (transfer.reference_dropped). A template that is already marked as written by AI on the target stays so.

The settings file lists every channel of the site it came from, each with its own posting slots, or with none when it uses the shared schedule. An import replaces the slots of each channel the file lists: a channel listed with no slots has its own slots cleared on the target, and falls back to the shared schedule. A channel that exists only on the target isn’t in the file, so it keeps its slots. A schedule for a channel the target doesn’t have is skipped, with a warning (transfer.schedule_skipped).

  • The short-link base URL, which is the address of one site. Each site keeps its own.
  • How many posts a tag or a hashtag group is on, and how often a group was used.
  • Who made a template, and when.
  • Posts, their UTM values, short links and their click counts, history, results, views and interactions.
  • Automate connections and automation ids.
  • The licence.
  • AI settings, and “Post automatically” rules, which live in Umbraco Automate.