Table of contents
Shortcut Integration Overview
Shortcut is a project-management tool for software teams built around stories, epics, iterations, and workflow states. Connecting it brings story activity into the WorkSights timeline the same way other delivery tools do: story creation, movement between workflow states, and comment activity, each credited to whoever actually made the change — not just whoever the story happens to be assigned to.
For connection steps, see Shortcut Setup.
What WorkSights Receives
Stories
WorkSights captures story creation, workflow-state changes, and other field updates. Each change is credited to whoever actually made it, resolved from Shortcut's own change history for that story — not to the story's assignee or owner. If a lead relabels a dozen stories, that activity is credited to the lead, not to each story's owner.
Comments
WorkSights records that a comment was made on a story and who made it. Comment text itself is never fetched or stored — only the occurrence and its author.
Users
WorkSights imports Shortcut workspace members and matches them to WorkSights users by email address. Disabled members and bot or automation accounts are skipped automatically and never generate activity.
WorkSights does not ingest epics, iterations, workflows, or teams as their own entities — they're only referenced by id on a story. Repository, branch, and pull-request content linked from a story is not read through this integration.
How Shortcut Activity Appears
Story activity appears under the Task category. Comment activity appears under General, titled “Commented on” the relevant story.
When the same person makes several related changes to a story in a short window, WorkSights consolidates them into a single activity rather than creating a separate entry for each one. A large bulk edit — relabeling or moving hundreds of stories in one sitting — is summarized into one activity rather than flooding the timeline.
Integration Page Overview
The Shortcut integration page contains:
- Overview - Connection details and integration owner
- Users - Shortcut workspace members mapped to WorkSights users
- Connections - Connected Shortcut workspaces
Data Notes
WorkSights accesses Shortcut using an API token. The integration is read-only, aside from the webhook subscription itself, which Shortcut allows registering with an admin-level token. WorkSights never writes to stories, comments, or any other Shortcut content.
If you connect more than one Shortcut workspace, each currently appears in WorkSights under the plain name “Shortcut” rather than labeled by workspace — check the Connections tab if you need to tell them apart.
Troubleshooting
Shortcut activity is not appearing
Confirm the affected member is mapped in the Users tab. WorkSights matches by email, and a member with no email on file, a disabled account, or a bot/automation account will never generate activity.
Activity is delayed
If your API token is admin-level, updates arrive near-real-time via webhook. If it's a standard-level token, Shortcut activity is instead picked up on an hourly cycle rather than instantly — this is expected, not a sign of a problem, and a standard token is fully supported.
A change is credited to the wrong person
WorkSights credits the person who actually made the change, not the story's assignee or owner. If this looks wrong, check who most recently edited that specific field in Shortcut.
Epics, iterations, or workflows aren't showing up as their own entries
This is expected. WorkSights references them by id on a story but does not ingest them as standalone entities.