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.
Installing
Section titled “Installing”dotnet add package UmbSocial.uSyncIt 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.
What syncs
Section titled “What syncs”| 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.
Moving a handler to another card
Section titled “Moving a handler to another card”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.
Channels arrive unconnected
Section titled “Channels arrive unconnected”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.
Keys are kept
Section titled “Keys are kept”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.
Settings are a snapshot
Section titled “Settings are a snapshot”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).
What never syncs
Section titled “What never syncs”- 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.