Automate Integration

UmbSocial adds one trigger and one action to Umbraco Automate, both in the Social group. Each channel publishes through a managed automation that uses them.

The “Social post due” trigger

Alias	Name
umbsocial.postDue	Social post due

It fires when a post is due on a channel. Social sends each due post directly to the channel’s managed automation, so other automations using this trigger don’t run for it.

Setting

Setting	Use
Channel (channelKey)	The channel key the automation publishes for. Social sets it on the automations it manages. Left empty, the trigger accepts any channel.

Output (bind with ${ trigger.<field> })

Field	Type	Use
targetId	int	The post’s target on this channel. Pass it to the record step.
channelKey	Guid	The channel.
network	string	The channel’s network id, for example linkedin.
text	string	The text to post: the channel’s own text or the main text, with the link added at the end for networks that take it in the text.
linkUrl	string?	The link.
linkTitle	string?	The link’s title.
linkDescription	string?	The link’s description.
linkImageUrl	string?	The link card’s image, read from the page (absolute https).
imageUrl	string?	The image’s absolute public URL, cut to the network’s shape by its framing (always a JPEG for Instagram).
imageAltText	string?	The image’s alt text.
attempt	int	The attempt number (0 for the first; each retry adds 1). Pass it to the record step.

Every field is data. Text that looks like a binding (${ … }) is passed through as plain text, never evaluated.

Each run is started with the correlation id and idempotency key social:<targetId>:<attempt>, so the same attempt never runs twice, whatever replays it.

The “Record social post result” action

Alias	Name
umbsocial.recordResult	Record social post result

The last step of a channel’s automation: it marks the post as published on the channel, with its URL.

Settings (all take bindings)

Setting	Usually	Use
Target (targetId)	${ trigger.targetId }	Which target to record.
Attempt (attempt)	${ trigger.attempt }	Which attempt this run is for. A result for any other attempt is ignored.
Post URL (postUrl)	${ steps.post.postUrl }	The live post’s URL. Only an absolute https URL is kept.
External ID (externalId)	optional	The network’s id for the post. Up to 500 characters are kept.

Output: targetId.

It changes nothing (the step is skipped) when:

• the attempt isn’t the target’s current attempt;
• the target isn’t being published. The one exception is a target the 15-minute check marked Unknown: a late success still settles it as Published.

It fails (a validation error) when the target doesn’t exist, or the run isn’t the channel’s own managed automation. Only a channel’s own automation can record its results.

The managed automation

When a channel is added, Social creates and publishes this automation in a workspace that allows the channel’s connection:

Part	Value
Alias	umbSocial<channel key>, the key as 32 hex digits without dashes
Name	Publish to <channel name>
Description	Managed by UmbSocial. Publishes this channel’s posts when they are due.
Trigger	Social post due, with Channel set to the channel’s key
Step post	The network’s post action, on the channel’s connection, with its settings bound from the trigger (for example text → ${ trigger.text }) and the channel’s options as fixed values. No retries; stops the run on error.
Step recordResult	Record social post result, with Target ${ trigger.targetId }, Attempt ${ trigger.attempt } and Post URL ${ steps.post.postUrl }

When the run finishes, Social reads the post step to decide the outcome (see Publishing lifecycle). The record step is the run’s own report of success; if it records nothing, the outcome is still decided from the post step when the run finishes.

Extending a channel’s automation

The managed automation is an ordinary automation: open it on the Automate canvas and add steps, such as a notification to your team after the post, or an approval before it. To keep publishing safe:

• Keep the post step’s alias and action. Social finds it by its action to decide the outcome, and copies changed channel options into the step with the alias post.
• Keep its retries at 0 and its error behaviour at stop. Most networks have no idempotency key: a retry after an unclear failure can post twice.
• Keep the record step after the post step, with Target bound to ${ trigger.targetId } and Attempt to ${ trigger.attempt }.
• Steps before the post step: if one fails or stops the run, the post step never runs, and the target is Failed (nothing was sent).
• Steps after the post step don’t change the outcome: once the post step completed, the post is Published, even if a later step fails.
• Don’t add a second step with the same post action. Social reads the last one.
• Keep the trigger’s Channel setting and keep the automation published. Social doesn’t check that the automation is published before sending a post to it.
• Changing the channel’s options in Social overwrites those settings on the post step and republishes the automation. Nothing else you changed is touched.

When UmbSocial adds a binding

A newer version of UmbSocial can bind more of the trigger’s fields into a network’s post step (for example the link card’s title, description and image for Bluesky). Once the site has started, the server that sends posts checks each channel’s managed automation in the background and adds any binding its network’s template now has that the post step lacks, then republishes it. It only adds settings that are missing: a setting you changed is kept as you made it, and nothing else in the automation is touched. A channel whose automation can’t be updated is logged and tried again at the next start.

If the automation is missing

If the channel’s automation has been deleted, ask Social to create it again: IChannelService.EnsureAutomationAsync, or POST …/channels/{key}/automation in the management API.

To use an automation you built yourself, give it the alias umbSocial<channel key> (the key as 32 hex digits without dashes) before asking Social to create the automation. Social adopts an automation with that alias instead of creating a new one, and publishes it. It must follow the rules above: in particular, the record step’s Attempt must be bound to ${ trigger.attempt }, or every result it reports is ignored. Social adopts it only when the channel’s recorded automation no longer exists.

Run history

Every post is a run in Automate’s run history, with its correlation id social:<targetId>:<attempt>. That’s the place to see exactly what a network answered.