Previously known as Tree Actions, Entity Actions is a feature that provides a generic place for secondary or additional functionality for an entity type. An entity type can be a media, document and so on.

Items in an Umbraco Tree can have associated Actions. The actions visible to the currently logged in user can be controlled via User Permissions.

You can set a User's permissions for each item in the Umbraco Content tree from the User Section of the Umbraco Backoffice.

If you are developing a custom section, or a custom Dashboard, you might want to display some different options based on a User's permission set on a particular item.

Entity Actions in the UI

Sidebar Context Menu

Sidebar Context Menu is an entity action that can be performed on a menu item. For example in the content section you can perform some extra actions on the content such as sorting, moving, etc.

Registering an Entity Action

TODO: can we show the typescript interface for the manifest?

import { extensionRegistry } from '@umbraco-cms/extension-registry';
import { MyEntityAction } from './entity-action';

const manifest = {
	type: 'entityAction',
	alias: 'My.EntityAction',
	name: 'My Entity Action',
	weight: 10,
	api: MyEntityAction,
	forEntityTypes: ['my-entity'],
	meta: {
		icon: 'icon-add',
		label: 'My Entity Action',
		repositoryAlias: 'My.Repository',
	},
};

extensionRegistry.register(manifest);

Default Element

// TODO: get interface
interface UmbEntityActionElement {}

The Entity Action Class

As part of the Extension Manifest you can attach a class that will be instanciated as part of the action. It will have access to the host element, a repository with the given alias and the unique (key etc) of the entity.

The class either provides a getHref method, or an execute method. If the getHref method is provided, the action will use the link. Otherwise the execute method will be used. When the action is clicked the execute method on the api class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements.

Example of providing a getHref method:

import { UmbEntityActionBase } from '@umbraco-cms/entity-action';
import { UmbControllerHostElement } from '@umbraco-cms/controller';
import type { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);
	}

	async getHref() {
		return 'my-link/path-to-something';
	}
}

Example of providing a execute method:

import { UmbEntityActionBase } from '@umbraco-cms/entity-action';
import { UmbControllerHostElement } from '@umbraco-cms/controller';
import type { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);
	}

	async execute() {
		await this.repository.myAction(this.unique);
	}
}

If any additional contexts are needed, these can be consumed from the host element:

import { UmbEntityActionBase } from '@umbraco-cms/entity-action';
import { UmbContextConsumerController } from '@umbraco-cms/controller';
import { UMB_MODAL_SERVICE_CONTEXT } from '@umbraco-cms/modal';
import { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);

		new UmbContextConsumerController(this.host, UMB_MODAL_SERVICE_CONTEXT, (instance) => {
			this.#modalService = instance;
		});
	}
  ...
}

We currently have a couple of generic actions that can be used across silos, so we don't have to write the same logic again: copy, move, trash, delete, etc. We can add more as we discover the needs.

User Permission Codes

Here is a list of the tree actions and associated user permission codes shipped by Umbraco CMS and add-on projects (such as Umbraco Deploy), as well as those used by some community packages.

If building a package or adding custom tree actions to your solution, it's important to pick a permission letter that doesn't clash with one of these.

If you have created a package using a custom tree action, please consider providing an update to this documentation page via a PR to the documentation repository, such that other developers can discover and avoid using the same permission letter.

Currently, we allow two extension points on the client for user permissions:

• Entity User Permissions - Relates to an entity (example document).

• Granular User Permission - Relates to a $type server schemaType.

Each permission comes with a set of verbs, that will be checked against client and server-side.

The Core currently ships with entity user permission for documents. The permissions are as follows:

Entity User Permissions will be registered in the extension registry with a manifest with the following type. Example:

{
    "type": "entityUserPermission",
    "alias": "Umb.UserPermission.Document.Rollback",
    "name": "Document Rollback User Permission",
    "meta": {
      "entityType": "document",
      "verbs": ["Umb.Document.Rollback"],
      "labelKey": "actions_rollback",
      "descriptionKey": "actionDescriptions_rollback",
      "group": "administration",
    },
  },

Granular permissions will also be registered. It is possible to provide a custom element to build the needed UX for that type of permission:

{
    "type": "userGranularPermission",
    "alias": "Umb.UserGranularPermission.Document",
    "name": "Document Granular User Permission",
    "element": "element.js",
    "meta": {
      "schemaType": "DocumentPermissionPresentationModel",
      "label": "Documents",
      "description": "Assign permissions to specific documents",
    },
  },