Skip to content

Templates and Tags

With UmbSocial Pro licensed, your team can save the posts it writes again and again as templates, and label posts with tags. A template is a starting point: its text, link, campaign and channels fill the composer, ready for you to finish the post. A tag is a coloured label, such as “Launch” or “Events”, that you can then filter the queue, the calendar and the Published page by.

Templates live under UmbSocial › Templates, in the UmbSocial section’s own sidebar. Anyone with the Write permission on their UmbSocial user group can see and use every template, create new ones, and change or delete the templates they made themselves. Someone with the Manage settings permission can also change or delete anyone’s template. When you open someone else’s template without that permission, its fields are read-only and there is no Save button, but you can still use it or duplicate it.

The list shows each template’s name, the start of its text, how many channels it has, whether it was written with AI, and when it was last changed. Type in the filter box to find a template by its name. Select a template’s name to open it. Each row’s actions menu has Delete, which asks you to confirm first, and Duplicate, which makes a copy named after the original with a number after it, such as “Weekly tip (2)”. The copy belongs to you, so you can change it however you like.

To add a template, select Create. Give it a name at the top, then fill in any of these, and select Save:

  • Text: the post’s text. Hashtags, mentions and links work just as they do in the composer.
  • Link: a full https address. If the text doesn’t already contain it, it is added to the end of the text when the template is used, and becomes the post’s link.
  • Campaign: the campaign posts started from the template belong to. Search for a campaign by name, or type a new name to add one, just as you do in the composer.
  • Channels: the channels a new post starts with.
  • Document types: the types of page the template is for. See Templates for document types.

A template’s name can be up to 100 characters long, and no two templates can have the same name. Names are compared without regard to case or to how an accent was typed, so “Weekly tip” and “WEEKLY TIP” count as the same name. If something can’t be saved, a message tells you why and the field it is about is marked.

In the UmbSocial section’s sidebar, select Create next to Compose and choose From a template. Then pick the template you want, typing in the search box to find it by name. The composer opens on a new post filled with the template’s text, link, campaign and channels. Choose New post instead for an empty post. Selecting Compose itself still opens an empty post, as it always has.

Nothing is saved until you save the post yourself. If you leave the composer without saving, Umbraco asks whether to discard your changes, as it does for any other unsaved post. A channel that has been paused or removed since the template was made is left out, and so is a campaign that no longer exists. If your site sets the campaign centrally, the composer’s campaign is left as it is.

When a post you are writing would make a good starting point for others, open the menu next to Save draft in the composer and select Save as template. Give the template a name and select Save. The template keeps the post’s text, link, campaign and channels, and the post itself isn’t saved.

A template saved from a post that AI helped write, or saved by an API user, is marked as written by AI. The list shows AI in its Written by column. The mark stays when the template is changed or duplicated.

A post started from such a template is written with AI too. UmbSocial saves it as a draft straight away, rather than filling the composer, and opens it. Like any post AI helped write, someone with Approve, or with Schedule while approvals are off, reviews it before it goes on the calendar. The draft needs at least one channel, so if none of the template’s channels is still there, a message says so and no post is made.

A template can be tied to one or more document types, such as your blog post type, with Document types in the template’s editor. Choose them with Umbraco’s own document type picker.

When someone uses Share on social… on a page of one of those types, the new post starts from the template:

  • With one template for the page’s type, the composer is filled from it straight away: its text, channels and campaign. The page then fills in the link, its title, description and image, and ties the post to the page, as it always does. The template’s own link is left out, because the page is the link.
  • With more than one, UmbSocial asks which to use, listing every template for the type. Close the list without choosing, and the post is filled from the page alone.
  • With none, the post is filled from the page alone, as without Pro.

The template’s campaign wins over the campaign chosen for the document type under Pages on social. If your site sets the campaign centrally, the composer’s campaign is left as it is.

A template written with AI is never filled in by itself, because its posts are AI drafts that someone reviews. When the type’s only templates are written with AI, the post is filled from the page alone. When it is listed among others and you choose it, UmbSocial saves an AI draft straight away, tied to the page and its language, and opens it, as From a template does.

A document type that is deleted after a template was tied to it is dropped from the template quietly the next time the template is saved or duplicated. Choosing a document type that isn’t on the site is refused with template.document_type_unknown.

The same templates can start the posts that pages of a type make on their own: see Posting automatically.

Tags live under UmbSocial › Tags. You need the Manage settings permission to create, change or delete them. Everyone who can see posts sees their tags.

To add a tag, select Create, give the tag a name at the top, choose its colour, and select Save. The colours are Umbraco’s own: blue, green, yellow and red. The Preview row shows how the tag looks on a post. A tag’s name can be up to 50 characters long, and no two tags can have the same name, ignoring case and how an accent was typed.

The list shows each tag with its colour, how many posts have it, and when it was last changed. Deleting a tag removes it from every post that has it, after you confirm.

In the composer, the Tags panel under the text lets you choose up to ten tags for the post. Select Choose to pick from your tags, using the search box to find one by name, and remove any tag you no longer want.

Tags are part of the post. Choosing them counts as a change, so leaving without saving asks whether to discard it, and they are saved when you save the post, whether you save it yourself or the composer saves the draft for you. If the tags can’t be saved, the post stays unsaved so you can try again. When you save, a message says why; when the composer saves the draft for you, it shows Not saved at the bottom instead. If a tag you chose is deleted under UmbSocial › Tags before you save, it is taken off the post, a message says so, and the rest of the tags are saved.

The Tags panel is read-only on a post you can’t change.

You can change the tags of the same posts you can change. With only the Write permission, that is your own drafts. With Approve, it is also anyone’s post that is waiting for approval, and with Schedule, it is any post. Each change to a post’s tags is recorded in the post’s History tab as “Tags changed”, with the tags it has afterwards.

The queue, the calendar and the Published page show each post’s tags in their colours, and each has a Tag filter in its toolbar. Type to find a tag, and choose it to see only the posts that have it. Clear the filter to see them all again. On Published, the Needs attention count and the list of campaigns still cover all your published posts, whatever tag you have chosen. The filter is shown once at least one tag exists.

When a post’s history is sealed, because UmbSocial isn’t licensed and the post is older than the free edition keeps, its tags are removed with the rest of its content. They are also removed when a post is deleted.

If UmbSocial isn’t licensed, your templates and tags are kept exactly as they are, along with the tags on each post and the document types each template is for. UmbSocial › Templates, UmbSocial › Tags, From a template, Save as template, starting a page’s post from a template, the composer’s Tags panel, the tags on posts and the tag filter are all hidden, and the back office API refuses every request about templates and tags. When the licence is valid again, everything comes back as it was.

The services behind them, IPostTemplateService and IPostTagService, check the licence themselves as well: your own code finds nothing and is refused changes with licence.pro_required too.

Templates are served by the management API under /umbraco/management/api/v1/umbsocial/pro/templates:

Request Permission What it does
GET /templates?filter=&skip=&take=&documentType= Write Returns a page of templates, ordered by name. The filter matches a name, and documentType (a document type’s key) narrows the list to the templates for that type.
GET /templates/{key} Write Returns one template, with its campaign’s key, name and value.
POST /templates Write Creates a template owned by the signed-in user from a name, text, linkUrl, campaignKey, channelKeys and documentTypeKeys.
PUT /templates/{key} Write Changes a template. Only its owner can, unless the user has Manage settings.
DELETE /templates/{key} Write Deletes a template, with the same rule as changing one.
POST /templates/{key}/duplicate Write Copies a template under the next free name, owned by the signed-in user.
POST /templates/{key}/post Write Saves a draft from the template, as using a template written with AI does, and answers the post’s key and version. The optional body, { "sourceContentKey": "…", "sourceCulture": "en-GB" }, ties the draft to a page and its language; that needs Browse on the page, and is checked as the core checks a post’s page.

Tags are served under /umbraco/management/api/v1/umbsocial/pro:

Request Permission What it does
GET /tags?filter=&skip=&take= View Returns a page of tags, ordered by name, each with how many posts have it.
GET /tags/items?keys= View Returns the tags with these keys.
GET /tags/{key} View Returns one tag.
POST /tags Manage settings Creates a tag from a name and a colour: default, positive, warning or danger.
PUT /tags/{key} Manage settings Renames a tag or changes its colour.
DELETE /tags/{key} Manage settings Deletes a tag and removes it from every post.
GET /posts/tags?keys= View Returns the tags of each of these posts that has any.
PUT /posts/{key}/tags Write Replaces a post’s tags with up to ten tagKeys, under the core’s rule for whose posts the user may change; a sealed post or one being sent can’t be changed. The replacement is one transaction: if the same post’s tags are saved at the same moment, the request is refused with tag.busy rather than leaving the post half-tagged.

The posts lists take the tag filter as filters[tag]=<tag key>, through the core’s post filter extension point.

A refused request returns these codes in its problem details: field.required:name, field.too_long:name, field.too_long:text, link.https_required, template.name_taken, template.not_yours, template.not_found, template.document_type_unknown, page.not_found, page.no_access, page.culture_invalid, field.required:culture, field.too_long:culture, tag.name_taken, tag.colour_invalid, tag.too_many, tag.not_found, tag.busy, post.not_yours, post.sealed, post.in_flight and post.not_found.

UmbSocial Pro also publishes these notifications, which you can handle like any other Umbraco notification:

Notification When
SocialPostTemplateSavingNotification Before a template is created, changed or duplicated. A handler can change the draft, or cancel the save with a message, which the person sees as template.cancelled:<message>.
SocialPostTemplateSavedNotification After a template has been created or changed. IsNew tells you which.
SocialPostTemplateDeletingNotification Before a template is deleted. A handler can cancel the delete with a message.
SocialPostTemplateDeletedNotification After a template has been deleted.
SocialPostTagSavingNotification Before a tag is created or changed. A handler can change the name or the colour, or cancel with a message (tag.cancelled:<message>).
SocialPostTagSavedNotification After a tag has been created or changed.
SocialPostTagDeletingNotification Before a tag is deleted. A handler can cancel the delete with a message.
SocialPostTagDeletedNotification After a tag has been deleted.
SocialPostTagsSavingNotification Before a post’s tags are replaced. A handler can change the list of tag keys, or cancel with a message.
SocialPostTagsSavedNotification After a post’s tags have changed. It isn’t raised when the same tags are saved again.