Docs Developer Site
Developer Docs Code Xp8 Web Tools

Admin Tools

Contents

Admin tools are custom adminitrative interfaces made availabe within the XP admin.

Introduction

An admin tool are self-contained mini-applications that run within the XP admin.

  • Secured via the same authentication and authorization as the rest of the admin.

  • Listed in the XP menu with icon and name

  • Can mount contextual Universal APIs .

  • Can connect to Admin extensions by declaring named interfaces that extensions implement.

  • Mounts at /admin/<app-key>/<tool-name> — one URL per tool.

Access always requires the caller to hold role:system.admin.login. Per-tool access is then granted to anyone in role:system.admin or to any principal listed in the tool’s allow: field.

Usage

To declare a tool, place a descriptor and an implementation under src/main/resources/admin/tools/<tool-name>/:

src/main/resources/admin/tools/
  my-tool/
    my-tool.yaml   (1)
    my-tool.ts     (2)
    my-tool.svg    (3)
1 Descriptor — see below.
2 HTTP function implementation for the tool URL.
3 Optional SVG icon shown in the Launcher. The file must sit next to the descriptor and share its base name.

The folder name, descriptor base name, and implementation base name must all match <tool-name>.

Descriptor

The descriptor is YAML only — .yaml and .yml are both accepted, and .yaml wins if both are present.

src/main/resources/admin/tools/<tool-name>/<tool-name>.yaml
kind: "AdminTool"
title: "Content Studio"          (1)
description: "Manage content"    (2)
allow:                           (3)
  - "role:system.authenticated"
apis:                            (4)
  - "admin:extension"
  - "content"
interfaces:                      (5)
  - "contentstudio.menuitem"
  - "contentstudio.contextpanel"
config:                          (6)
  property_1: "value_1"
1 title — string, or { text, i18n } for localization. Shown in the Launcher.
2 description — string, or { text, i18n }.
3 allow — principal keys (roles, groups, users) granted access. The implicit role:system.admin always has access regardless. Required to expose the tool to non-admins.
4 apis — list of Universal API descriptor keys mounted under this tool’s URL. Bare names refer to APIs in the same app; <app>:<api> form borrows from another app. APIs become reachable as service points at /admin/<app-key>/<tool-name>/_/<app>:<api>.
5 interfaces — named interface points this tool exposes. Admin extensions whose interfaces: list intersects with this list are eligible to be mounted into the tool. Names are free-form strings — pick stable identifiers and document them.
6 config — free-form key/value map readable from the implementation.
Localized title/description
title:
  text: "My tool"
  i18n: "i18n.my-tool.display-name"

Implementation

The implementation lives at src/main/resources/admin/tools/<tool-name>/<tool-name>.ts and exports an HTTP function for each method the tool should respond to.

Sample my-tool.ts
exports.GET = (req) => {
    const view = resolve('my-tool.html');
    return {
        body: render(view, { user: req.user }),
        contentType: 'text/html'
    };
};

The implementation is the entry point for /admin/<app-key>/<tool-name> and any deeper path that does not match a service-point URL. For anything beyond a couple of static endpoints, use the router library for method dispatch, parameter extraction, and pattern matching.

URL

  • Tool entry point: /admin/<app-key>/<tool-name>

  • API service point under the tool: /admin/<app-key>/<tool-name>/_/<app>:<api-name>

  • Admin extension dispatcher under the tool: /admin/<app-key>/<tool-name>/_/admin:extension/<app>:<extension-name>/

Generate URLs from the implementation with the Portal library: adminUrl() for the tool itself, apiUrl() for mounted APIs.

Access control

The admin service enforces two checks:

  1. The caller must hold role:system.admin.login. Without this, the request never reaches the descriptor.

  2. The tool’s descriptor must permit the caller. role:system.admin is always permitted; otherwise the caller must match at least one principal in allow:.

A failed check returns 401 Unauthorized if the configured ID provider asks for credentials, otherwise 403 Forbidden.

Mounting Universal APIs

Any API listed in apis: is mounted as a service point under the tool’s URL. The same API can simultaneously be mounted on the Web endpoint (mount: ["web"] in the API descriptor) — the two mounts are independent. See Universal API: Service point.

Hosting admin extensions

A tool publishes the interface names it exposes in interfaces:. Any deployed admin extension whose own interfaces: list intersects with this set becomes eligible to be mounted into the tool, subject to the extension’s own allow: list. The reserved interface name "generic" matches any tool. See Admin extensions for the consumer side.

Launcher

The XP admin Launcher lists every deployed tool the caller is allowed to access, using title, description, and the <tool-name>.svg icon from the descriptor. The default Launcher tool itself is com.enonic.xp.app.main:home, served at /admin.

Contents

Contents