Skip to content

Writing History Entries

A post’s history is Umbraco’s audit log (IAuditService), not a table of UmbSocial’s own. A package can add entries to it, and they show up on the same tab, in the same list. UmbSocial’s paid packages write their approval entries this way.

Inject ISocialAudit (UmbSocial.Core.Audit):

public interface ISocialAudit
{
// userKey: who did it. Null is the signed-in backoffice user, or the system when there is none.
Task AddAsync(int postId, string action, string? comment = null, Guid? userKey = null, CancellationToken cancellationToken = default);
// actor: a person (SocialActor.User(key)) or the system (SocialActor.System).
Task AddAsync(int postId, string action, string? comment, SocialActor actor, CancellationToken cancellationToken = default);
}

When your code acts for the site rather than for a person (a background job, an Automate action, a webhook), write as SocialActor.System. Don’t pass SocialAudit.SystemUserKey as a user key: that key is Umbraco’s super user, which a site’s first administrator is too, so only SocialActor.System marks an entry as the system’s. IPostService.CreateAsync takes a SocialActor the same way, so a post your background process creates has its history written as the system’s:

await posts.CreateAsync(input, new Schedule(When.Draft, null), SocialActor.System, cancellationToken);

A post created as the system has no author (its CreatedByUserKey is empty), so no person’s own-drafts access reaches it and webhooks name no author. Its origin is PostOrigin.Automation unless you pass another with origin:. Pass awaitingApproval: true to create the draft as awaiting approval; it is refused with post.awaiting_needs_draft unless the schedule is a draft. All of this is set before the post is saved, so SocialPostSavedNotification handlers see the post as it is stored.

ApprovalHistory.cs
using UmbSocial.Core.Audit;
public sealed class ApprovalHistory(ISocialAudit audit)
{
public Task ReturnedAsync(SocialPost post, string note, Guid reviewer, CancellationToken cancellationToken)
=> audit.AddAsync(post.Id, "returned", note, reviewer, cancellationToken);
}

A failure to write is logged and swallowed: an audit entry never stops what it records.

SocialAudit (UmbSocial.Core.Audit) holds them, if you want to read or write the audit log yourself:

Entity type SocialAudit.EntityType: umbsocial-post, or SocialAudit.SystemEntityType: umbsocial-post-system for an entry written as SocialActor.System
Object id SocialAudit.ObjectId(post.Id): the post’s integer Id plus 1,000,000,000. Umbraco’s audit log is keyed by one integer shared with content, media and members, so UmbSocial’s ids start high and a post never shares an id with an Umbraco item
Action In the entry’s parameters: SocialAudit.Actions.Created, Edited, Scheduled, Rescheduled, Queued, PublishedNow, Deleted, Paused, Resumed, Published, Failed, Unknown, Retried, MarkedPublished, Sealed, Restored, CampaignRenamed, CampaignMerged, CampaignRemoved and CampaignMissing (a restored post’s campaign no longer exists; the comment is its old name), or your own string
Comment Optional detail, never the post’s text. For Scheduled, Rescheduled and Queued, the time: SocialAudit.Time(utc). For a channel’s result, SocialAudit.Channel(name, reason): the channel’s name, a line break, then the reason as one of UmbSocial’s codes. Umbraco’s audit log is kept for good and outlives sealing, so UmbSocial never writes a live post’s link there (the History tab adds it from the channel’s result while the post isn’t sealed) or a network’s own error message, which can quote the post; such a message is recorded as run.failed or run.outcome_unknown, or as run.sign_in_failed or run.rate_limited when Automate said the network refused the sign-in or was limiting requests. Keep your own entries to the same rule. For your own actions, free text (a reviewer’s note, for example), which the History tab shows as it is
Audit type Umbraco’s New, Save, Delete and Publish where one fits (created, edited, deleted, published), otherwise Custom. Never System or Open: Umbraco’s log scrubber deletes those once they are old
User The person who acted. When nobody did (the publishing job, Automate, sealing), SocialAudit.SystemUserKey: Umbraco’s super user (Constants.Security.SuperUserKey). A site’s first administrator is that same user, so the key alone doesn’t mean the system: an entry is the system’s when it was written as SocialActor.System (its entity type is SocialAudit.SystemEntityType). Entries written before that existed count as the system’s when they are one of the actions only the system takes (SocialAudit.SystemActions: published, failed, unknown, sealed, paused, resumed). The History tab shows System for those and the person’s name for everything else, and the history endpoint says which per entry (isSystem)

Entries for a sealed post keep their action, user and time, and their comments are dropped when the history is read, so a sealed post’s history never shows a channel, a link or a note.

PostHistoryReader (UmbSocial.Core.Audit) returns a page of a post’s entries, newest first, as PostHistoryPage. The backoffice reads it through GET /umbraco/management/api/v1/umbsocial/posts/{key}/history?skip=&take=, which needs the View permission and a post the person can see.

The History tab labels an action with the dictionary term umbSocial_history_action_<action>. Register terms for your own actions with your package’s localization (as you do for any backoffice extension); an action without a term is shown as it is written. @umbsocial/core exports historyHref(postKey), the link to a post’s History tab, HISTORY_ACTIONS (UmbSocial’s own) and SYSTEM_USER_KEY.