Shortcuts

Shortcuts puts desktop, Start menu, Applications menu, Dock and web-link shortcuts on managed machines and keeps them there. It works like the Shortcuts part of Group Policy Preferences, but also covers Linux and macOS. You define a policy as a list of shortcut items and assign it to collections, tags or agents. Each agent then creates, replaces, updates or deletes those shortcuts and reports the result for every item and user profile. The agent does the work itself, so a shortcut a user deletes comes back without the server, and the module works on an air-gapped network.

Scope

Windows, Linux and macOS agents. Each item names its own platform, and an agent gets only the items for its platform.
A licensed module. Your licence must include Shortcuts (module.shortcuts). Without it, the pages are hidden, the REST endpoints return 403 and nothing is sent to agents. See Separately licensed modules.
Nothing changes by default. The master switch Enforce shortcut policies is off by default. Until you turn it on, agents only report what is on the machine.
Athena removes only its own shortcuts. The one exception is an item with the Delete action (see Ownership).
No taskbar or Start pinning. Windows does not let a management tool pin items for the user, so Shortcuts does not offer it.

Where Shortcuts appears#

Place	Address	What it shows
Policies → Shortcuts	`/policies/shortcuts`	The Enforce shortcut policies switch, the Policies list with a compliance bar per policy, and the Assignments list. Part of the Policies group.
Policy editor	`/policies/shortcuts/new`, `/policies/shortcuts/editor/<id>`	New shortcut policy / Edit shortcut policy: the General card, the Shortcut items table and the item editor.
Policies landing card	`/policies`	Policies, Items, Agents with problems (agents with a Failed or Conflict item) and Enforcement (On or Off).
Agent details → Shortcuts	Agent details tab	One machine's effective policy, any policies not applied there, and each item's state per profile. Read-only, and updated live when the agent reports.

Permissions

Permission	Key	Default roles	Allows
View shortcuts	`shortcuts.view`	Helpdesk, Operator, Admin	See shortcut policies, items, icons and each agent's shortcut state. Ask an agent for a fresh report.
Manage shortcuts	`shortcuts.manage`	Helpdesk, Operator, Admin	Create, edit and delete shortcut policies, items and assignments, upload icons, and turn enforcement on or off.
Manage full-path shortcuts	`shortcuts.fullpath`	Admin	On top of Manage shortcuts: create, edit or delete an item that uses the Full path location, which can be anywhere the agent's SYSTEM or root account can write. Deleting a policy that holds such an item needs it too.

Without shortcuts.fullpath, full-path items open read-only in the editor and the REST API returns 403. See Permission Model.

Quick start#

Open Policies → Shortcuts and click New policy. Give it a name and click Save policy. The editor reopens on the saved policy.
Click Add item. Choose the Platform and Type, a Name, the Target (or URL), the Location and For which users, then click Save item.
Back on the Shortcuts page, under Assignments, pick the policy and a collection or tag and click Add assignment. Start with a small test collection.
Open a test machine's Shortcuts tab. While enforcement is off, it shows what is there and what is missing (Drift), and nothing is changed.
When you are happy, turn on Enforce shortcut policies.

Shortcut types and locations#

Platform	Type (as shown)	Locations offered
Windows	Shortcut (.lnk), Web link (.url)	Desktop, Start menu, Start menu \ Programs, Startup, Favorites, Full path
Linux	Application (.desktop), Link (.desktop)	Desktop, Applications menu, Startup (autostart), Full path
macOS	Dock item, Finder alias, Web link (.webloc)	Desktop, Dock, Full path

Web links (.url, Linux Link, .webloc) accept only http, https, file and mailto URLs.
Subfolder puts the shortcut in a folder under the location, for example Start menu \ Programs \ Contoso. It isn't used with Full path or the Dock.
Full path takes a folder (the shortcut's file name is still Name). It must be absolute (C:\..., \\server\share\... or %VARIABLE%\... on Windows, /... on Linux and macOS). It may not point into Windows, /etc (except /etc/xdg/autostart), /usr/bin, /System or the agent's own data folder, and may not contain ...
On Linux, the all-users Applications menu is /usr/local/share/applications and the all-users Startup is /etc/xdg/autostart. Per user they are ~/.local/share/applications and ~/.config/autostart. The Desktop is the user's localized desktop folder from ~/.config/user-dirs.dirs, or ~/Desktop.
On GNOME desktops, the agent marks a Desktop .desktop file as trusted while the user is signed in, so it can be launched without Allow Launching.
On macOS, a Finder alias is created as a symbolic link. Dock items are added to that user's Dock and only that user's Dock is restarted.

For which users#

Choice	Value	Where the shortcut goes
all users	`AllUsers`	The machine-wide location, once. Windows: the Public Desktop and the all-users Start menu and Startup. Not offered for Windows Favorites, the Linux Desktop, or any macOS location except Full path, because those have no all-users folder.
every profile	`EveryProfile`	Written by the agent into each existing user profile, signed in or not, plus the profile that seeds new users (the Default profile on Windows, `/etc/skel` on Linux).
each user at sign-in	`AtSignIn`	Written into a user's profile while that user is signed in. The agent checks for new sign-ins every minute. Users who are signed out show Pending sign-in. Dock items use only this choice.

Per-user variables in an all-users item

%USERPROFILE%, %APPDATA%, %LOCALAPPDATA%, %HOMEPATH%, %HOMEDRIVE%, $HOME and ~/ in an all users item resolve under the SYSTEM or root account's profile, not the user's. The editor shows a warning, and the REST API and PowerShell return it with the save. Use a machine path such as %ProgramFiles%, or choose every profile or each user at sign-in.

When applied: Create, Replace, Update, Delete#

Action	Shortcut missing	Athena's shortcut is there	Someone else's shortcut is there
Create	Created.	Left alone. If it no longer matches the item it is reported as Drift, but not rewritten.	Left alone, reported as Conflict.
Replace	Created.	Deleted and re-created when it differs from the item, so local edits are overwritten.	Left alone, reported as Conflict.
Update	Created.	Only the fields set in the item are changed when it differs.	Left alone, reported as Conflict.
Delete	Nothing to do (Removed).	Deleted.	Deleted. The editor warns about this, and the change is audited as a warning.

Items are applied top to bottom. The agent re-checks every 15 minutes, and straight away when it gets a new policy, so a deleted shortcut comes back within that time. Each write must finish within 10 seconds (a slow network target is reported as a timeout). The agent reads each shortcut back before it reports Applied.

Ownership: which shortcuts Athena removes

The agent keeps its own record of every shortcut it creates, and marks the file itself where the format allows. A shortcut counts as Athena's only when both agree. Because of this:

Removing an item or a policy, unassigning a policy, or another policy winning on the machine removes only Athena's shortcuts. A user's shortcut with the same name and location stays.
Remove Athena's shortcut when this item no longer applies is on by default. Turn it off to leave the shortcut in place when the item stops applying.
To clean up a shortcut that a user or an installer made, add an item with the Delete action for that name and location.

Item fields#

Field (as shown)	Rules
Name	The file name, without extension. Up to 120 characters. No `\ / : * ? " < > \|`, not `.` or `..`, no trailing dot or space, and not a reserved device name such as `CON` or `NUL`.
Target / URL	Required except for Delete. Up to 2,048 characters, on one line.
Arguments, Working folder	Up to 2,048 characters each, on one line. Arguments are never run through a shell.
Only if the target exists	The agent creates nothing and reports Target missing when the target isn't there, and removes Athena's shortcut if it already made one. Not used for web links.
Icon	The target's own icon, or an uploaded icon: `.ico` for Windows, `.png` or `.svg` for Linux, up to 256 KB each and 2 MB per policy. macOS items always use the target's icon.
Hotkey	Windows Shortcut (.lnk) on the Desktop or Start menu only. Format `Ctrl+Alt+K`: Ctrl, Alt or Shift plus a letter, digit or F1-F24. A letter or digit needs Ctrl or Alt. Two enabled items in one policy may not share a hotkey.
Run	Windows Shortcut (.lnk) only: Normal window, Minimized or Maximized.
Comment (tooltip)	Up to 260 characters.
Item enabled	A disabled item is not sent, so it counts as no longer applied.

A policy holds up to 200 items. Policy names are unique and up to 200 characters.

Assignments and which policy wins#

Only one shortcut policy applies to each machine. Assignments are ordered by priority. The first assignment that matches the machine (lowest priority number) decides its policy. Every other policy that also matches is Not applied there, and none of its items reach that machine. Items from different policies are never merged.

Specificity does not win. An agent assignment at priority 5 loses to a tag assignment at priority 1. Use Move up and Move down to change the order.
The winning policy wins even if it has no items for the machine's platform. A Windows-only policy at priority 1 leaves a Mac with no shortcuts. Make separate per-platform policies, or put the items for every platform in one policy.
A disabled policy is skipped, so its machines get the next matching policy, or none.
The page assigns to collections and tags. To assign to a single agent, use the REST API or Add-AthenaShortcutAssignment -TargetKind Agent.
The policy list shows "Not applied on N of M agents: another policy wins there", and the editor shows the same for its own agents.

The enforcement switch and the lease#

Enforce shortcut policies, at the top of the Shortcuts page, is the master switch. It is off by default. While it is off, agents report what is on the machine and change nothing: missing shortcuts show Drift ("Missing; will be created once enforcement is on") and Delete items show "Will be deleted once enforcement is on." Turning it on or off is audited as a warning.

Each agent holds its policy for a lease of 14 days. The server renews it when the agent connects, when you change a policy, item, assignment or the switch, and once a day on its own. If the lease runs out, the agent stops changing shortcuts and only reports. Shortcuts it already created stay, including after the licence lapses.

The lease length is set with the REST API only: PUT /api/shortcuts/settings with leaseDays from 1 to 365.
The daily refresh interval is the Modules:Shortcuts:LeaseRefreshHours setting (default 24, minimum 1) in configuration.
Adding a machine to a collection or tag doesn't send it the policy straight away. It gets it at its next connection or the daily refresh. To send every connected agent its policy now, schedule Shortcuts: refresh policy leases in Scheduled Jobs. This also removes uploaded icons that no item uses.

The agent's Shortcuts tab#

The tab shows the Effective policy (with its priority and the assignment that matched), the policies Not applied here, the Last report time, and one row per item and profile with Item, Where, Action, Profile, State and Detail. Click the refresh button to ask the agent to report now. "Revision N not acknowledged by the agent yet" means the agent hasn't received your latest change.

State	Meaning
Applied	The shortcut is there and matches the item.
Removed	Deleted by a Delete item, or removed because the item no longer applies.
Pending sign-in	An each user at sign-in item for a user who isn't signed in.
Target missing	Only if the target exists is on and the target isn't there.
Drift	Missing or different, and not changed: enforcement is off, the lease ran out, or the action is Create.
Conflict	A shortcut Athena didn't create is at that name and location. Replace and Update never overwrite it.
Not applied	The item belongs to a policy that another policy beats on this machine.
Not capable	The machine has no such folder for that user, or the item can't be placed there.
Failed	The write failed. The Detail column gives the agent's reason.

Only Conflict and Failed count as problems on the landing card and in the filter fields.

Filter fields#

Use these in collections, tagging rules, monitors and reports (see Filter Field Reference):

Field	Shown as	Type	Value
`Module.shortcuts.FailedCount`	Shortcuts: failed items	Number	Rows in Failed state. 0 if the agent never reported.
`Module.shortcuts.ConflictCount`	Shortcuts: conflicting items	Number	Rows in Conflict state. 0 if the agent never reported.
`Module.shortcuts.PendingRevision`	Shortcuts: policy not yet received	Boolean	`true` when the agent doesn't yet hold the latest revision of its policy.

Audit events#

Event	Key	When
Shortcut policy changed	`shortcuts.policy-changed`	A policy is created, updated or deleted.
Shortcut item changed	`shortcuts.item-changed`	An item is created, updated or deleted, with the changed fields. A warning for Delete items and full-path items.
Shortcut icon uploaded	`shortcuts.icon-uploaded`	A new icon is uploaded.
Shortcut assignment changed	`shortcuts.assignment-changed`	An assignment is added, removed or reordered.
Shortcut enforcement or lease changed	`shortcuts.enforcement-toggled`	The master switch or the lease length changed (warning).
Shortcut status requested	`shortcuts.status-requested`	Someone asked an agent to report its shortcuts.

See the Audit Event Types Reference and Audit Forwarding to SIEM.

REST API#

All routes are under /api/shortcuts. view routes need shortcuts.view and manage routes need shortcuts.manage. Without the licence every route returns 403. Choices travel as names (for example "kind": "Lnk"), never numbers. Invalid values return 400 with the reason and are never adjusted.

Route	Needs	Does
`GET /api/shortcuts/settings`	view	`enforcementEnabled` and `leaseDays`.
`PUT /api/shortcuts/settings`	manage	Change either; a null field is unchanged. `leaseDays` 1-365.
`GET /api/shortcuts/policies`, `GET /api/shortcuts/policies/{id}`	view	List policies with their items, or get one.
`POST /api/shortcuts/policies`	manage	Create a policy (`name`, `description`, `enabled`). `409` if the name is taken.
`PUT /api/shortcuts/policies/{id}`	manage	Change name, description or enabled.
`DELETE /api/shortcuts/policies/{id}`	manage	Delete a policy with its items and assignments. `403` if it holds a full-path item and you lack `shortcuts.fullpath`.
`GET /api/shortcuts/policies/{id}/items`	view	The policy's items.
`POST /api/shortcuts/policies/{id}/items`, `PUT .../items/{itemId}`	manage	Add or replace an item. The response holds the item and any `warnings`.
`DELETE /api/shortcuts/policies/{id}/items/{itemId}`	manage	Delete an item.
`POST /api/shortcuts/icons`	manage	Upload an icon as multipart field `file`. Returns its `sha256`, used as an item's `iconSha256`.
`GET /api/shortcuts/icons/{sha256}`	view	Download an icon.
`GET /api/shortcuts/assignments`	view	All assignments.
`POST /api/shortcuts/assignments`	manage	Add one (appended last). Body: `policyId`, `targetKind` (`Agent`, `Collection` or `Tag`), `targetKey` (agent id, collection id or tag name).
`DELETE /api/shortcuts/assignments/{id}`	manage	Remove one.
`POST /api/shortcuts/assignments/reorder`	manage	Body `{"assignmentIds": [...]}`: every id exactly once, highest precedence first.
`GET /api/shortcuts/agents/{id}/effective-items`	view	The agent's effective policy and items, the policies not applied there, and every reported row.
`GET /api/shortcuts/agents/{id}/state`	view	What the agent last reported. `404` if it never reported.
`POST /api/shortcuts/agents/{id}/status`	view	Ask the agent to report now. Returns `true` when sent, `false` when it isn't connected.

An item body uses: enabled, os (Windows, Linux, MacOs), kind (Lnk, Url, Desktop, DesktopLink, Dock, Alias, Webloc), action (Create, Replace, Update, Delete), scope (AllUsers, EveryProfile, AtSignIn), location (Desktop, StartMenu, StartMenuPrograms, Startup, Favorites, ApplicationsMenu, Dock, FullPath), name, subFolder, fullPath, target, arguments, workingDirectory, comment, iconSha256, iconIndex (0-9999), hotkey, runStyle (Normal, Minimized, Maximized), onlyIfTargetExists, removeWhenNotApplied (default true) and ordinal (null = last).

For example, an intranet link on every Windows user's desktop:

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"os":"Windows","kind":"Url","action":"Replace","scope":"AllUsers",
       "location":"Desktop","name":"Intranet","target":"https://intranet.example.local/"}' \
  "https://<server>:8443/api/shortcuts/policies/7/items"

PowerShell#

The Athena PowerShell module (2.17.0 and later) has these cmdlets. The server's warnings come back as PowerShell warnings.

Cmdlet	Does
`Get-AthenaShortcutPolicy [-Id] [-Name <wildcard>]`	List policies with their items.
`New-AthenaShortcutPolicy -Name [-Description] [-Disabled]`	Create a policy.
`Set-AthenaShortcutPolicy -Id [-Name] [-Description] [-Enabled]`	Change a policy.
`Remove-AthenaShortcutPolicy -Id`	Delete a policy (asks for confirmation).
`Add-AthenaShortcutItem -PolicyId ...`	Add an item. Takes `-Os`, `-Kind`, `-Action`, `-Scope`, `-Location`, `-Name`, `-Target`, `-Arguments`, `-WorkingDirectory`, `-Comment`, `-SubFolder`, `-FullPath`, `-IconSha256`, `-Hotkey`, `-RunStyle`, `-OnlyIfTargetExists`, `-RemoveWhenNotApplied`, `-Enabled`.
`Set-AthenaShortcutItem -PolicyId -ItemId ...`	Change only the parameters you pass (an empty string clears a field).
`Remove-AthenaShortcutItem -PolicyId -ItemId`	Delete an item (asks for confirmation).
`Send-AthenaShortcutIcon -Path`	Upload an icon and return its `Sha256`.
`Add-AthenaShortcutAssignment -PolicyId -TargetKind -TargetKey`	Assign a policy to an `Agent`, `Collection` or `Tag` (appended last).
`Get-AthenaShortcutState -AgentId [-Summary]`	One row per item and profile with its state, or with `-Summary` the agent view.

$p = New-AthenaShortcutPolicy -Name 'Corporate Links'
$icon = Send-AthenaShortcutIcon -Path .\intranet.ico
Add-AthenaShortcutItem -PolicyId $p.Id -Os Windows -Kind Url -Action Replace -Scope AllUsers `
    -Location Desktop -Name Intranet -Target https://intranet.example.local/ -IconSha256 $icon.Sha256
Add-AthenaShortcutAssignment -PolicyId $p.Id -TargetKind Tag -TargetKey kiosk
Get-AthenaShortcutState -AgentId <agent-id> | Where-Object State -in 'Failed','Conflict'

Troubleshooting#

Symptom	What to check
Everything shows Drift and nothing is created	Enforcement is off, or the agent's lease ran out ("The agent has not heard from the server for too long"). Turn on Enforce shortcut policies, or check the agent's connection.
Conflict: "was not created by Athena"	A user or an installer made a shortcut with that name at that location. Rename the item, or add a Delete item for that name to remove it.
All items are Not applied	Another policy has a higher-priority assignment that matches this machine. Check the assignment order.
A newly tagged machine has no shortcuts	Membership changes are picked up at the next connection or the daily refresh. Run Shortcuts: refresh policy leases to send now.
The tab says Never reported	The agent is older than this feature, or hasn't connected since. Update the agent.
Failed: did not finish within 10 seconds	The target is on a slow or unreachable network path.
Save refused: "A hotkey only works for a shortcut on the Desktop or in the Start menu."	Move the item to the Desktop or Start menu, or clear the hotkey.
Save refused: "Items with a full path need the shortcuts.fullpath permission."	Ask an Admin, or use a named location.

Policies: the group this module belongs to.
Collections and Agent Tags: the groups you assign policies to.
Software Deployment: install the applications your shortcuts point to.
Licensing: separately licensed modules.