Skip to content

uSync

UmbSocial.uSync is a free package that lets uSync move UmbSocial’s setup between sites as files, alongside your document types and content. Set a site up once, export, and import on the others.

dotnet add package UmbSocial.uSync

It needs UmbSocial and uSync 17.6.2 or later (before 18). There is nothing to configure: uSync finds its three handlers, which appear on two cards on the uSync dashboard: UmbSocial Setup and UmbSocial Library.

Item Handler alias Folder uSync card Priority
Channels umbSocialChannels uSync/v17/UmbSocial/Channels UmbSocial Setup 2100
UmbSocial’s settings umbSocialSettings uSync/v17/UmbSocial/Settings UmbSocial Setup 2110
Campaigns umbSocialCampaigns uSync/v17/UmbSocial/Campaigns UmbSocial Library 2300

Channels and settings sit on the UmbSocial Setup card, and campaigns on the UmbSocial Library card. Each card has its own Report, Import and Export, separate from uSync’s own Settings and Content cards. When UmbSocial.Pro.uSync is installed, Pro’s items join the same two cards.

Campaigns and channels are one file each, named after the item (a channel’s file is named <network>-<name>). The settings are one file, social-settings.config.

The order of the priorities is the order of an import: channels, then settings, then campaigns, so the Settings card’s items always come before the Content card’s. Campaigns can point at channels.

Import All runs these after uSync’s own handlers, so the document types are on the site by then. 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, the page fields for document types that aren’t there yet are skipped (transfer.page_field_skipped). Import uSync’s Settings card first, or the UmbSocial Setup card again afterwards. On a new site the simplest first run is Import All.

The two cards are the defaults. 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 Campaigns to the UmbSocial Setup card (use "Content" for uSync’s own Content card): Choose a card name that doesn’t contain another uSync group’s name, such as Content or Settings: uSync runs every handler whose group appears in the card’s name, so a card called “UmbSocial Content” would also run Umbraco’s own content handlers.

{
"uSync": {
"Sets": {
"Default": {
"Handlers": {
"umbSocialCampaigns": {
"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 channel’s connection to its network lives in Umbraco Automate, and connections don’t travel between sites. An imported channel that isn’t on the target yet therefore arrives without a connection and switched off. Settings › UmbSocial › Connections shows it as Needs connecting, with a Connect action. Until it is connected it can’t be chosen for a post. If the file has the channel switched on, it is kept off, with a warning (transfer.kept_off): connect it, then switch it on.

A file whose key belongs to a channel that was removed from the target brings that channel back (transfer.restored), with the connection and history it had. Its automations, which were unpublished when it was removed, are published again, and it is switched on if the file says so and it is connected.

The free edition’s channel limit is checked when a channel is connected, not when it is imported, so an import never fails for being over the limit.

Every item keeps its key on every site, so a post, a page field or a link that points at a campaign or channel still does after an import.

An item that already exists on the target only by name (a site that was 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) so that you can see it happened.

The settings file describes the whole of what it covers, so an import replaces it:

  • the posting schedule (its slots and time zone),
  • the settings: the time zone, the webhook opt-ins, whether drafts are saved as they are written and whether X’s metrics are read, and
  • the page fields for each document type (the description and image properties, and the starting campaign).

Take care with a site whose settings differ: whatever the file leaves out is removed from the target. A page field whose document type (or property) isn’t on the target is skipped, with a warning (transfer.page_field_skipped). A page field whose campaign isn’t on the target is kept without the campaign, with a warning (transfer.campaign_missing).

The settings can’t be deleted through uSync: a delete action for them is refused (settings.cannot_be_deleted) and nothing changes.

Files are written when an item is saved, as uSync does for Umbraco’s own items. The settings file is rewritten whenever the settings, the posting schedule or a page field is saved or removed (see SocialContentMappingSavedNotification).

  • Automate connections and automation ids.
  • The short-link base URL.
  • The licence.
  • Posts, and everything else created while the site runs (history, results, views and interactions).
  • AI settings.
  • “Post automatically” rules, which live in Umbraco Automate.