Posting Automatically
With UmbSocial Pro licensed, pages can post to social on their own. Choose a document type, such as your blog post or news article type, and each time a page of that type is published, UmbSocial makes a post about it: the page’s name or a template’s text, the page’s address, and its link card. It makes one post for each page and language, however often the page is published again, and an editor can turn it off for any page.
It is set up as an ordinary automation in Umbraco Automate, so you can change it, turn it off or delete it there, or build your own from the same action.
Set it up
Section titled “Set it up”Under UmbSocial › Templates, select Post automatically for a document type…. You need UmbSocial’s Manage settings permission to use it, and Write to see the Templates page at all. Administrators have both.
The dialog first lists the document types that already post automatically, each with On or Turned off in Umbraco Automate, the Automate workspace it is in, and Open in Automate. Below that, choose:
| Field | Use |
|---|---|
| Document type | Pages of this type get a post when they’re published. An element type has no pages, so it can’t be chosen. |
| Channels | The channels the post goes to. Choose none to use the template’s channels, or every channel that’s switched on if there’s no template. |
| Template | Optional. The post starts from this template’s text, campaign and channels, with the page’s address added. Without one, the post is the page’s name and its address. The list shows the first 100 templates by name: to use another, choose none here and set the template’s key on the step in Automate afterwards. |
| Post as | Awaiting approval (the default), Draft or Queue. See How the post is left. |
| A post for each language | On a site with more than one language, turn this on to make a post for each language that’s published. Otherwise only the site’s default language gets a post. |
Select Post automatically. UmbSocial makes the automation, publishes it and tells you which Automate workspace it is in. From then on, publishing a page of that type makes a post.
What it makes
Section titled “What it makes”An automation in Umbraco Automate, which you can open with Open in Automate:
| Part | Value |
|---|---|
| Name | UmbSocial: every <document type> |
| Alias | umbSocialContent<document type key>, the key as 32 hex digits without dashes |
| Trigger | Content Published, for that document type only |
| Step | Create social post for a page, with Page ${ trigger.contentKey } and Published cultures ${ trigger.cultures | json }, and the channels, template, mode and languages you chose as fixed values |
It never binds the post’s text to anything: the text comes from the template or the page.
The workspace
Section titled “The workspace”Automate keeps every automation in a workspace, and publishing one needs the workspace’s service account. UmbSocial puts the automation in the first workspace, by alias, that has a service account. If there is none, nothing is made (automation.no_workspace): add one under Automate › Workspaces and try again. If Automate won’t publish the automation, for example because that workspace’s service account can’t use the Content section, nothing is left behind (automation.invalid): give the account access, or make another workspace come first, and try again.
One for each document type
Section titled “One for each document type”A document type can have one ready-made automation. Choosing a type that already has one is refused (automation.exists), even when it is turned off in Automate: turn it back on there instead. Deleting it in Automate frees the type.
Making it again after deleting it doesn’t post again for pages it already posted for: the new automation has the same alias, umbSocialContent<document type key>, and UmbSocial remembers what was posted by alias. Pages it never posted for get their post at their next publish.
On a load-balanced site, two people choosing the same type on different servers at the same instant could each make one. Both have the same alias, so each page still gets one post: delete one of the automations in Automate.
How the post is left
Section titled “How the post is left”| Post as | Approvals on | Approvals off |
|---|---|---|
| Awaiting approval | Awaiting approval | A draft |
| Draft | A draft | A draft |
| Queue | Awaiting approval | In the queue’s next free slot |
No post is ever published straight away. Only Queue with approvals off puts a post on the calendar without a person seeing it first: it goes out in the queue’s next free slot. A post awaiting approval is announced to approvers as any submission is (the Submitted notification and webhook, from the system). It has no author, so any approver may approve it.
A template written with AI makes a post written with AI. Such a post always waits for review, as Awaiting approval (or a draft with Draft), whatever Post as says and whether approvals are on or off: it never goes in the queue unreviewed. Its History tab shows AI used, from the system.
What the post says
Section titled “What the post says”Each post is built as Share on social… builds one, from the page as it was published (a change saved since, but not yet published, is left out):
| Part | Comes from |
|---|---|
| Text | The step’s text, if you set one in Automate; otherwise the template’s text; otherwise the page’s name. The page’s address is added after a blank line, unless the text already contains it. |
| Link card | The page’s name, its description and its image, read from the properties chosen under Pages on social. |
| Campaign | The template’s campaign, if it still exists; otherwise the campaign chosen for the document type under Pages on social. |
| Channels | The step’s channels; otherwise the template’s channels that are still there and switched on; otherwise every channel that’s switched on. |
| Page | The page and its language, so the post shows on the page’s UmbSocial tab. |
The page is already live when the post is made, so the post isn’t timed to the page: a post left in the queue keeps its slot. If the page is unpublished before the post goes out, that channel fails with link.content_unavailable, as for any queued post with a page, and you can retry it once the page is published again.
Once for each page and language
Section titled “Once for each page and language”Publishing the page again, renaming it or moving it never makes a second post: each automation posts once for each page and language. UmbSocial remembers this by the automation’s alias, not the automation itself, so an automation deleted and made again with the same alias remembers what it posted, and two automations with the same alias share one memory. Another automation, with another alias, makes its own post.
| The page | Gets |
|---|---|
| Doesn’t vary by language | One post. |
| Varies by language | One post for the site’s default language, when that language is among those just published. Publishing only another language makes no post. |
| Varies by language, with A post for each language on | One post for each language just published. A language published later gets its post then. |
If making a post fails, the page and language are let go, so the run’s retry, or the next publish, tries again. They stay taken in two cases:
- The post was saved but something after the save failed (for example, a handler of UmbSocial’s notifications): the post is kept, the step succeeds, and nothing tries again.
- The page is published but this server doesn’t have its address yet: the run keeps the page and language while Automate retries it, and another publish meanwhile is skipped as
already posted. If there is still no address 10 minutes after the first try, the run fails and lets them go, so the next publish tries again. A run that stopped without letting them go is taken over by the next publish once those 10 minutes are up.
Don’t post automatically
Section titled “Don’t post automatically”An editor can turn automatic posts off for a single page, from the page’s UmbSocial tab. The switch, Don’t post automatically, is shown only while a published automation posts for the page’s document type. Other pages of the type still post.
- Changing it needs UmbSocial’s Write permission and Umbraco’s Update permission on the page, because it changes what happens when the page is published. Someone without them who can see the tab sees “Automatic posts are turned off for this page.” when it is off.
- Each change is written to the page’s own History in the Content section, as “UmbSocial: automatic posts turned off” or “UmbSocial: automatic posts turned back on”, with who changed it.
- It stops automatic posts only. Posts written by hand from the page still go out.
Build your own
Section titled “Build your own”The ready-made automation is a starting point. Open it in Automate to add steps, such as a notification to your team, or build your own around the Create social post for a page action (umbsocial.createPostForContent, in the UmbSocial group).
| Setting | Use |
|---|---|
Page (contentKey) |
The key of the page that was published. Bind it to ${ trigger.contentKey }. Required. |
Published cultures (cultures) |
The languages the trigger published, as a JSON list or separated by commas. Bind it to ${ trigger.cultures | json }. Empty for a page that doesn’t vary by language. |
A post per published culture (allCultures) |
A switch: on makes a post for each language published, off only for the default language. |
Post as (mode) |
Draft, AwaitingApproval (the default) or Queue, as in How the post is left. |
Template (templateKey) |
Optional. A template’s key. |
Channels (channels) |
Optional. Channel keys, separated by commas. |
Text (text) |
Optional. The post’s text, in place of the template’s or the page’s name. |
Output: postKeys, the posts made, and skipped, why none was made, when none was: opted out, already posted, no culture was published, the default culture isn't published or the page isn't published any more. A step that skips still succeeds.
The action has no setting for an author, an approver, a time or where the text came from: an automation can’t schedule a post for a time, approve it or say a person wrote it.
Set the step’s retries. While a load-balanced server doesn’t have the page’s address yet, the step fails as Service unavailable for up to 10 minutes, and Automate retries it. Automate’s default retry budget (10 retries, 30 seconds apart) runs out after about 5 minutes, so give the step its own: the ready-made automation sets Max retries to 22 and Retry interval to 30 seconds, with the error behaviour left at Retry. Set the same on your own step, or any budget longer than 10 minutes.
The alias is the memory. What the step has posted is remembered by the automation’s alias. Keep the alias if you rebuild the automation and want it to remember; give a copy a new alias if it should post again for every page.
If you bind Text to AI-written text, for example the answer of Umbraco.AI’s Run AI Agent, set Post as to Draft or Awaiting approval, so that a person reviews it before it goes out. The action can’t tell where bound text came from, so with Queue and approvals off it would go in the queue unreviewed. To have AI’s text marked and always reviewed, use Create social draft with Written by AI on instead.
When it fails
Section titled “When it fails”| Why | Category | What to do |
|---|---|---|
| UmbSocial Pro isn’t licensed. Nothing is made. | Configuration error | Activate the licence. |
Page isn’t a page’s key, Post as isn’t one of the three, the template or a channel doesn’t exist, a language is over 20 characters, or the post itself is refused (the error lists the codes, such as text.too_long). |
Validation | Fix the step’s settings in Automate. A Validation failure isn’t retried. |
| Umbraco can’t build an address for the page: the site has no application URL and the page no domain. | Configuration error | Set Umbraco:CMS:WebRouting:UmbracoApplicationUrl, or give the page a domain. |
| The page is published but this server doesn’t have its address yet (on a load-balanced site, a moment after the publish on another server). | Service unavailable | Nothing: Automate retries the step (see Set the step’s retries). After 10 minutes it gives up as a configuration error, and the next publish tries again. |
| The automation can’t be read, or its alias is empty or over 255 characters. | Configuration error | Give the automation an alias of at most 255 characters. |
With A post per published culture on, a failure in one language stops the step: the languages already posted keep their posts, and the failure names the languages not tried, so the retry posts only those.
Without a licence
Section titled “Without a licence”While UmbSocial isn’t licensed, the automations stay in Automate, but their step fails as a configuration error and makes nothing. Post automatically for a document type… and Don’t post automatically are hidden, and the API refuses them with licence.pro_required. The pages’ settings are kept, and apply again when the licence is active.
For developers
Section titled “For developers”Served by the management API under /umbraco/management/api/v1/umbsocial/pro:
| Request | Permission | What it does |
|---|---|---|
GET /content-automations |
Manage settings | Lists the ready-made automations: automationId, documentTypeKey, documentTypeName, name, enabled (published in Automate) and workspaceName. |
POST /content-automations |
Manage settings | Makes one from documentTypeKey, channelKeys, mode (AwaitingApproval by default), templateKey and allCultures. Answers automationId and workspaceName. |
GET /content/{key}/auto-post |
View or Write, and Browse on the page | Answers optedOut, automated (an automation posts for the page’s type) and canChange (Write and Update on the page). |
PUT /content/{key}/auto-post |
Write, and Update on the page | Sets optedOut, and answers as GET does. |
From code, the same are IContentAutomationService (UmbSocial.Pro.Automate) and IPageOptOutService (UmbSocial.Pro.Content). They check the licence themselves but not the person’s permissions, apart from the opt-out’s Update check: your code decides who may call them.
A refused request returns these codes: automation.exists, automation.mode_invalid, automation.no_workspace, automation.invalid, mapping.type_unknown, template.unknown, channel.unknown, page.not_found, page.no_access and licence.pro_required.