Orbit — complete functional guide

Product: Orbit by Ideonex Scope of this document: every screen, every field, every option value, and what each one means in practice.

This is written to be read in two ways. Read Part 1 straight through to learn how the product is meant to be used. Use Parts 2 onward as a reference when you need to know what a particular dropdown value actually does.

Everything here describes how the product actually behaves. Where it does not do something people commonly assume it does, that is called out rather than left for you to discover.

Part 1 — The flow

1. The mental model

Five nouns, nested. Learn these and the rest of the product follows.

Organisation  ─ one workspace, one bill, one set of users
   │
   ├── Department  ─ optional. A role granted here covers every project beneath it
   │      └── Team ─ a group of people you can assign work or roles to as a unit
   │
   └── Project     ─ a place you work in. Owns its issue types, workflow,
          │           board, components, versions, SLA policies, security levels
          │
          ├── Issue ─ the unit of work. Typed, keyed (ENG-142), owned, staged
          │      ├── Sub-tasks, links, comments, attachments, work logs
          │      ├── Participants  ─ everyone with a named job on it
          │      └── Baton         ─ who is holding it *right now*
          │
          ├── Board / Backlog / Sprints / Roadmap
          ├── Releases / Environments / Deployments
          └── Test suites / cases / cycles

Two ideas separate this product from a plain ticket list, and both are worth understanding before you start.

The baton. Every status declares which role owns work sitting in it. When an issue moves to "QA Failed", the engine knows that status is owned by the developer role, looks up who is filling the developer role on that issue, and hands it to them. Nobody reassigns anything by hand. The current holder is called the baton holder, and the product tracks how long they have held it, who passed it to them, how many times the issue has changed hands, and how many times it has gone backwards.

Stage versus status. A status is precise ("Regression Failed"). A stage is the macro phase a manager asks about ("it's in QA"). Every status belongs to exactly one of 16 stages, from a shared catalogue, which is what lets a portfolio report ask "how much work is stuck in QA across 40 projects" and get a truthful answer even though each project renamed its statuses.

2. Getting the workspace running

2.1 Register the organisation

/signup. You choose a workspace name and slug, create the owner account, and pick how many paid users you are registering.

• Price is INR 100 per paid seat per month. Viewer-role users are free.
• The organisation owner consumes one seat.
• The first 10 organisations ever registered can claim one calendar month free with no Razorpay charge. Eligibility is counted in a global counter; deleting an organisation does not give the place back. The offer is available only at initial registration, never later.
• The free month includes the full feature set.

2.2 Order of setup

Do these in order. Each one makes the next useful.

1. Create a project (/projects → new). Pick its type; that decides which issue types it accepts. See §16.
2. Invite people (/admin/people). Each invitation carries a role.
3. Install a workflow (/admin/workflows). Nothing is seeded beyond a starter workflow — you choose a template or keep it minimal.
4. Set project role defaults (project settings). This is the step teams skip and then wonder why routing does nothing. Without it, every new issue starts with an empty roster and the first handoff lands on nobody.
5. Optionally: SLA policies, security levels, components, versions, custom fields, automation rules, SSO.

2.3 Signing in

• Password login at /login.
• Single sign-on if an administrator has configured and enabled a provider: Google, Microsoft, GitHub, Okta, generic OpenID Connect, or SAML.
• If the workspace has enforced SSO turned on, password login is rejected for everyone except the workspace owner, who keeps a break-glass path in case the identity provider breaks.

On first login the server quietly creates anything missing — a starter project, a board, a general chat channel — and gives any issue without a project a home and an issue key.

3. A day in the product

This is the path the product is designed around. Follow it once and the rest of the reference will make sense.

Morning: what is actually on you

Two screens, and the difference matters.

/my-queue is the one to start with. It is ordered by how long the baton has sat with you, so the thing at the top is the thing somebody has been waiting on longest.

Raising work

/issues/new, or /create-ticket (the old URL, which redirects). Or, from chat, /ticket PROJ "Title" high @someone.

You pick a project, an issue type, and a priority; you write a title and a description. Everything else is optional at creation and can be filled in later. See §4 for every field.

The issue gets a key on creation — ENG-142 — from the project's own counter. That key never changes and is what people quote in conversation.

Moving work

Open the issue. The header answers three questions a status field cannot:

1. Where is it? The stage pipeline — a stepper showing how far through it is.
2. Who has it? The baton card — the holder, the role they are acting in, how long they have held it, and whether they are overdue.
3. What can be done next? The transition bar.

The transition bar shows every move available to you. The forward move is the only filled button, so the common case is a glance rather than a read. Moves you cannot make are shown disabled with the reason, not hidden — "Close needs the two open subtasks finished" tells you what to do, where a missing button just looks broken.

Press a transition. If it has a screen, you are asked for the fields it needs (a rejection always asks for a reason). If it has validators, they run server-side and refuse with an explanation. If it has an approval gate, the issue parks where it is and an approval request goes out; the move completes when quorum is met.

Then the baton moves, automatically, to whoever fills the role that owns the new status.

The round trip that shows why this exists

A bug in the Defect Lifecycle workflow:

QA raises it                      → baton: triage officer
Triage confirms and routes        → baton: dev lead
Dev lead assigns                  → baton: developer
Developer fixes, marks ready      → baton: QA lead   (handoff #1, forward)
QA lead assigns a tester          → baton: QA engineer
Tester fails it                   → baton: the developer who wrote it
                                     (handoff #2, backward, bounceCount = 1)
Developer fixes again             → baton: the tester who failed it
                                     (not "the queue" — the baton remembers)
Tester passes it                  → baton: reporter, to verify
Reporter confirms                 → Closed

Nobody reassigned anything. handoffCount is 4, bounceCount is 1. An issue whose bounce count reaches 3 is flagged as ping-ponging, because work that has failed QA three times is usually a misunderstood requirement rather than a careless developer.

Closing and reopening a bug: the QA engineer who verified a fix can Close it from QA Passed, Regression Passed or Shipped. Anyone who works bugs can Reopen a closed or done bug (a reason is required). Won't fix and Cancel need issue:close (Project Manager and above).

Ending the day

• Log time on what you worked on (issue screen → Log work).
• Anything you are blocked on: park it with a transition whose intent is park, and say why. It returns to where it came from when you resume it.
• /reports if you run a team.

Part 2 — Work items

4. Creating an issue, field by field

Screen: /issues/new.

Created through the API, an issue can also carry a parent (making it a sub-task), a sprint, an epic, components, versions, a security level, a milestone and custom fields.

If the project has no issues yet you will be sent to create a project first. Issues cannot exist outside a project.

5. Issue types, and when to use each

Sixteen types exist. A project only offers the subset that suits it.

Development types

Note on the terms you may be used to. If your previous tool used scenario / bug / enhancement, the mapping is: scenario → a test case under Testing, or a spike if it is an investigation rather than a test; bug → bug; enhancement → improvement. Test scenarios are first-class objects here rather than an issue type, which is what lets them be executed repeatedly in cycles and produce defects.

Service management types

Which types a project offers

Set from the project type at creation, and editable afterwards:

Development and service issues live in one collection deliberately: links, comments, attachments, watchers, activity, search and audit then work uniformly across both, so a bug found in QA can link to the production incident that caused it with no special machinery.

6. Priority, severity, impact, urgency, risk

Five different questions. They are separate fields because conflating them is how a backlog ends up with forty "critical" items.

Priority — how soon we will act

Stored values: lowest, low, medium, high, urgent, highest. The create form, the issue screen and the API all offer the full set.

Priority is what SLA targets are keyed on, and the default sort on every work list.

Severity — how badly it is broken

sev1, sev2, sev3, sev4, or blank. Mostly used on bugs and incidents.

Severity is a statement of fact about the defect. Priority is a decision about scheduling. A sev1 in a system nobody uses this quarter can legitimately be low priority.

Service fields: impact and urgency

On service issues, these two justify the priority rather than replacing it.

• Impact — how wide the blast radius is: low, medium, high, organisation.
• Urgency — how soon it has to be fixed: low, medium, high, critical.

Change fields: change type and risk

On change and change_request issues:

• Change type — standard (pre-approved, routine, low risk), normal (goes to the Change Advisory Board), emergency (bypasses the board, still needs one signature, and the audit records that it was an emergency).
• Risk — low, medium, high. The ITIL workflow asks for a rollback plan before a change with risk can proceed.

7. Resolutions

Set when an issue enters a status flagged as a resolution. Entering such a status also stamps resolvedAt.

Terminal statuses (done, closed, cancelled, rejected, duplicate, wont-do) cannot be left except through an explicit reopen transition.

8. Issue links

Nine link types, in mirrored pairs plus one symmetric.

is_blocked_by is not decoration: the no_blocking_links validator refuses a transition while any blocking link is still open.

9. The issue screen

/issues/:id. Everything you can do to one piece of work.

The header

Fields you can edit inline

Project, type, priority, severity, assignee, reporter, labels, components, fix release, affects release, environment, milestone, sprint, story points, due date, start date, estimates, security level, and any custom fields the project defines.

Service issues additionally show: requester, requester department, category, subcategory, impact, urgency, change type, risk.

Actions

Tabs

• Comments — the conversation, newest last. Internal notes marked.
• History — every field change, as from/to pairs, with who and when.
• Handoffs — the team-to-team passes, separate from the noise of ordinary field edits.

Security level

If the project defines security levels, an issue can be restricted to one. An issue with no level is visible to anyone who can see the project — that is the normal case and the deliberate default.

Someone who cannot read a restricted issue gets a 404, not a 403. Confirming that a restricted issue exists is itself a leak.

The people named on the issue keep access by default (includeParticipants, includeReporter), so applying a level cannot lock an assignee out of their own work.

Part 3 — The workflow engine

10. Stages, statuses and categories

Three layers, each answering a different question.

Status category — what boards and burndowns read

Three values, and only three:

Renaming a status never breaks velocity or burndown maths, because those read the category.

Stage — the macro phase

Sixteen, ordered. The order is the pipeline.

Suspended sits outside the line on purpose. Work can be parked from anywhere and returns to where it came from, so giving it a position on the pipeline would make every burndown lie.

Status — the precise state

138 statuses in the shared catalogue, each tagged with its stage and the baton role that owns it. Full list in §11.

Status flags

Each status can carry four flags:

Why a shared catalogue

The moment two projects both invent "In QA" with different spellings, cross-project reporting stops working and every board needs a bespoke mapping. A shared id space means the portfolio question gets a truthful answer.

Your organisation still owns its copy: statuses are expanded from the catalogue and copied onto your workflow at install time, so you can rename "QA Failed" to whatever your team calls it without a later release overwriting the change.

11. The full status catalogue

Every status in the shared vocabulary, grouped by stage. Owner is the baton role that holds work sitting in that status: this column is the whole routing mechanism, so read it as "who has it while it is here".

Total: 138 statuses across 16 stages.

Intake — Raised, not yet accepted.

Triage — Classified, reproduced and routed.

Refinement — Specified, designed and estimated.

Ready — Accepted and queued for delivery.

Development — Being built.

Code Review — Peer and architecture review.

Build — Merge, pipeline and artefacts.

QA — Test team verification.

UAT — Business acceptance.

Security — Security and compliance review.

Staging — Pre-production verification.

Release — Packaging, change approval, go/no-go.

Deployment — Going live.

Post-Release — Production verification and warranty.

Closure — Final states.

Suspended — Parked. Returns to wherever it came from.

12. Baton roles and ownership routing

A baton role is a job a person does on one issue for one stage. It is not an organisation role. The same human is a reviewer on one issue and a developer on the next, and neither changes their permissions. Keeping the two separate is what lets ownership rotate without touching anyone's access.

The 23 roles

Handoff marks the roles that represent a different team picking the work up. Only those moments are stamped as handoffs, because the gap between a developer saying "done" and QA actually starting is where delivery time goes, and averaging it with intra-team churn hides it completely.

system and nobody are held by no human. A build runs on its own and there is nobody honest to put on the hook for it; assigning those to a person would make "work assigned to me" meaningless.

How the baton moves

Each transition declares a baton mode. status_owner is the default and the one to reach for: the target status already declares who owns it, so the arrow needs no configuration and stays correct when someone reorders the workflow.

Two extra settings on any transition's baton:

• fallbackRole — where to look if the chosen role has nobody in it on this issue. Without one the engine leaves the issue unassigned rather than guessing, which is safe but lets a queue silently fill with ownerless work. Naming a lead here is the usual answer.
• respondWithinMinutes — the new holder is expected to act within this many minutes. Past it, the baton shows as overdue and the chaser sends one reminder, not one every half hour.

Who actually fills a role

Three layers, most specific wins:

1. Per-issue participants — someone explicitly set on this issue.
2. Project role defaults — who fills each role on new work in this project.
3. Nothing — the role is vacant, shown in the roster panel, and a gate that needs it will refuse with that reason.

Project role defaults accept three strategies:

Today only fixed takes effect. The API accepts and stores pool, strategy and the rotation cursor, but the roster seeder reads the single user field, so a default with only a pool and no named user fills nothing. Set a named user on every role default you rely on.

Participants versus assignee

The single assignee answers "who is holding it right now". It cannot answer "who tested it", "who reviewed the code" or "which lead routed it" — and in a real delivery flow those are the questions asked three months later when something regresses.

Participants are that record. They are additive and never overwritten, so the roster of everyone who touched an issue survives every reassignment. Several people may hold the same role (two reviewers); at most one is primary, and that is the one the baton routes to. Removing someone clears them rather than deleting the record, so history survives.

Handoff directions

Every recorded handoff carries a direction, and the direction is the quality signal.

Two counters on every issue:

• handoffCount — times it has changed hands between teams. A bug at 9 has been round the houses and is worth a human looking at.
• bounceCount — times it has been sent backwards. At 3 the issue is flagged as ping-ponging, which is a smell rather than a rule: work that has failed QA three times is usually a misunderstood requirement, and it is worth a conversation before the fourth attempt.

13. Transitions: intents, validators, screens, gates

A transition is one arrow in the state machine. Every status change goes through the engine — the issue screen, a board drag, an automation rule and an approval completing all take the same path, so a gate cannot be bypassed by using a different screen.

Intent — how the move reads in the UI

Who may fire a transition

Three independent gates, all of which must pass:

1. requiredPermissions — permissions the caller holds in this project.
2. allowedRoles — the original organisation-role gate. Kept so workflows saved before permissions existed keep working. New workflows should leave it empty and use permissions.
3. allowedBatonRoles — only people holding these roles on this issue. This is the gate permissions cannot express: a QA engineer may hold issue:transition across the project, but only the tester actually testing this bug should be able to fail it.

Validators — the 21 guards

Evaluated server-side before a move is allowed. They are data, not code, so you compose your own gates without a deploy.

A validator can carry its own message, so a gate explains itself instead of producing a generic failure.

Transition screens

Fields the user is asked for as part of the move, rather than on the issue's edit form. This is what lets "Reject" demand a reason while "Approve" demands nothing, without either polluting the normal form.

Field types available on a screen: text, textarea, select, multiselect, number, date, user, checkbox. Each can be required and can carry help text.

Post-functions — what happens after a successful move

14. Approvals

An approval is different from a permission. A permission asks "may you press this button". An approval asks "has a named person signed this off", and the signature has to outlive the request.

Firing a gated transition opens an Approval record and parks the issue where it already is. The move completes when quorum is met. There is deliberately no generic "awaiting approval" limbo status in the ITIL template: the issue stays in "CAB Review", so that status keeps meaning what it says.

Configuring a gate

Decisions

Each decision is approved, rejected or abstained, with an optional comment. Abstentions do not count toward quorum.

Captured with each decision, for a regulated audit trail: the role the person was acting in at the time, their IP and their user agent. The acting role is snapshotted so a later role change cannot rewrite history.

The approver list itself is snapshotted when the gate opens. Removing someone from a role mid-flight does not silently change who the approvers were.

Approval statuses

pending, approved, rejected, cancelled, expired.

Where you see them

/my-queue carries an approvals section — everything waiting on your signature. The issue screen shows the approval card with progress.

The payload from the transition screen is held on the approval and replayed when the gate passes, so the resolution and comment the requester typed are not lost while waiting.

15. The six workflow templates

Installed on request from Administration → Workflow studio, never seeded. An organisation that wants five statuses keeps five: dropping a forty-state workflow onto a team that did not ask for one is how process tooling gets a reputation for being in the way.

Statuses are copied onto your workflow at install, so you own your copy and can rename anything without a later release overwriting it.

Workflow schemes

workflow on a project is the default and the fallback. A workflow scheme routes per issue type on top of it, because a bug and an epic do not travel the same road: forcing one workflow onto both means either the epic collects eleven statuses it never enters, or the bug skips the QA gate.

Expected roles

A workflow declares which baton roles it wants filled. These surface on the issue as empty slots to staff, which is how a team discovers it has no QA lead on a bug before the QA gate refuses to open rather than after.

Board columns from a template

Installing a template also proposes board columns grouped by stage, not one per status. One column per status would give a forty-column board nobody can read.

A note on the designer

The workflow studio is read-and-install plus API editing. Workflows can be installed from a template and edited through PUT /api/projects/workflows/:id with the full document, but there is no visual drag-and-drop transition editor yet.

Part 4 — Planning and delivery

16. Projects and their settings

A project is a place you work in, not a filter you set. Cross-project screens exist too (/work/issues, /delivery/releases), and they are the same components rendered outside a project.

Creating a project

Project status and priority

These describe the project itself, not the work inside it. A project can be on hold with every issue open, or completed with a few stragglers; conflating the two hides both.

• Status: draft, active, on_hold, completed, archived
• Priority: low, medium, high, critical

Project settings you will actually use

Custom fields

Nine types: text, textarea, number, date, select, multiselect, checkbox, user, url.

Each field can be marked required, given an option list (for select types), ordered, and restricted to specific issue types so a bug form does not sprout a field that only makes sense on a change request.

Security levels

Project permissions answer "who can see this project". A security level narrows it to one issue — an HR case or an unpatched vulnerability lives in an ordinary project and must not be readable by everyone in it.

Each level has a name, description, colour, and three additive membership lists: users, teams and role keys. Two switches keep people from being locked out of their own work:

• includeParticipants (on by default) — anyone named on the issue keeps access
• includeReporter (on by default) — whoever raised it keeps access

An issue with no level is visible to anyone who can see the project. That default matters: security that is opt-out gets applied to everything and then worked around.

Removing a level that issues still use is refused, because deleting it would make those issues visible to the whole project.

17. Boards, backlog, sprints, roadmap

Board

/work/board, or /projects/:id/board.

A board column maps one or more workflow statuses into one visual lane. Templates propose columns grouped by stage, because one column per status would give a forty-column board nobody can read.

Dragging a card between columns fires a real transition through the engine, so validators, gates and baton routing all apply. A drag that would fail a validator is refused with the reason, not silently reverted.

Backlog

/work/backlog. Ordered list of everything not in an active sprint. Ranking is a sparse float, so a drag-and-drop reorder is a single write rather than a renumber of the whole list.

Needs backlog:prioritise to reorder.

Sprints

/work/sprints, or the project's Sprints tab. Scrum projects only, in practice.

Sprint states: future, active, closed.

Every sprint an issue has ever been in is kept in sprintHistory, for scope-change reporting.

Roadmap

/work/roadmap, or the project's Roadmap tab. Milestones and releases by quarter, with the epics that deliver them.

An epic is placed on the timeline by giving it a milestone: it is then drawn under that milestone, in the milestone's quarter. Use Move to milestone… on an epic (its ⋯ button, which works from the keyboard too) to schedule it, move it to another milestone or take it off the timeline; setting the Milestone field on the epic does the same. Epics with no milestone are listed under Epics without a milestone.

The timeline shows the current quarter and the next three. Milestones dated before it are in an Overdue lane (open ones are flagged Overdue), those after it in a Later lane, and only milestones without a date are under No target date. Every row shows its date.

A milestone's ⋯ menu offers Edit… (name, target date, status, release, description) and every status change, so a commitment that slips is rescheduled rather than removed and added again (removing it unlinks its epics). Milestone statuses: planned, in_progress, at_risk, completed, cancelled.

18. Finding work: views, quick filters, the query language

Named views

Quick filters

Offered in the toolbar menu:

The query language

A JQL-like language. It compiles to a database filter, and anything it cannot parse produces a message aimed at the person who typed it, not a stack trace.

Operators

field = value            field != value
field IN (a, b, c)       field NOT IN (a, b)
field ~ "text"           contains
field IS EMPTY           field IS NOT EMPTY
field > value            >=  <  <=        (dates and numbers)
AND / OR                 parentheses supported
ORDER BY field ASC|DESC

Functions: currentUser(), now(), startOfWeek(), startOfMonth(), and relative dates like -7d and +3d.

Fields you can query

project, key, type (or issuetype), status, statuscategory, resolution, priority, severity, assignee, reporter, creator, watcher, labels (or label), component, fixversion, sprint, epic, parent, storypoints, created, updated, due (or duedate), resolved, summary (or title), description, text.

Sortable fields: key, created, updated, due, priority, status, storypoints, rank, title, assignee.

Examples

project = ENG AND status != Done AND assignee = currentUser() ORDER BY priority DESC
labels IN (regression, customer) AND created > -14d
text ~ "login timeout" AND priority IN (high, urgent)

Saved filters

Save a query with a name. Visibility is private, org or shared, and a filter can be starred to pin it. Anything that runs in the list can be saved, including project keys and active sprint names (project = PAY). Your filter names are unique: a second filter with the same name (ignoring case and surrounding spaces) is refused.

Bulk edit

issue:bulk lets you apply a change to every issue matching a selection in one go. Bulk changes still run through the engine.

19. Testing

Testing is first-class here rather than an issue type, which is what lets the same scenario be run in every regression cycle and keep a history.

Three objects:

Suite   ─ a folder.  One level of nesting only: "Checkout" → "Payments"
  └ Case      ─ a definition of what to check
       └ Execution ─ one run of that case inside one cycle, with a verdict

Test suites

Test cases

A case is a definition. Running it produces an execution.

Test case types, in practice

Test cycles

A cycle is the unit QA works in: "regression for 2.5.0". It pins a set of cases at a point in time, so editing a case later never rewrites history.

Executions and verdicts

One execution per case per cycle: re-testing updates the verdict in place, which is what "retest until green" means.

Per-step results carry not_run, passed, failed or blocked, and the steps are copied from the case at execution time so a later edit to the case does not silently change what was tested.

Each execution can carry a comment, attachments (screenshots and logs backing the verdict), a duration, and a defect — the bug raised from this failure. Raising a defect from a failed execution links the two, which is what makes regression sign-off a real gate rather than a status somebody sets.

Signing off. QA signs off a cycle (test:signoff) once every test has run, nothing failed, was blocked or skipped, and no defect is open. A cycle that does not meet that can still be signed off with a waiver and a written reason, by a project administrator (the project's manager or lead, project:admin), an organization admin or the owner. The waiver and its reason are kept on the cycle and in the audit log.

20. Releases, environments, deployments

Releases

A version of a project that ships. Referenced by id, so renaming a version does not orphan the issues pointing at it.

Release gates. A release carries approvals against three gates: qa, regression and uat; a decision for any other gate is refused. Each approval is approved or rejected with a note, and the latest decision per gate wins — a rejected gate blocks approval until it is approved again. Gates are decided by a release approver (release:approve), a project administrator, an organization admin or the owner. A release cannot reach approved until every required gate is approved — which is what stops that status meaning nothing more than somebody clicking a button.

On an issue: fix release is the version it is scheduled to ship in; affects release is the version where it was found.

Environments

The promotion path is enforced. A release cannot be deployed to a tier until it has already reached the tier below. Try it and the deploy is refused with "that release has not reached the environment below this one; deploy it there first". That is what makes the tier numbers mean something rather than being decoration.

Going backwards is always allowed: a rollback, or re-deploying to development, is never blocked by the promotion path. The rule also only applies to a deployment that names a release; an ad-hoc versioned deploy with no release attached is not checked.

The default environments created for a project are Development (0), QA (1), Staging (2), UAT (3) and Production (4, marked production and requiring an approved release).

Deployments

Duration is stamped automatically when a deployment finishes.

Permissions worth knowing: deployment:create to deploy at all, deployment:production to deploy to a production environment, and deployment:rollback to reverse one.

Part 5 — Service management

21. Service desk and SLAs

A service_desk project accepts the eight service issue types and hides the development ones. Service issues carry an extra block of fields, grouped so it is obvious which belong to a ticket and which to a development issue: a story has no urgency, an incident has no story points.

Service fields

Internal notes

A comment can be flagged internal. Internal notes are hidden from reporters on service-desk projects. Posting one needs ticket:internal_note. Someone who cannot read internal notes sees no trace of them — not in the comments, not in the history, and no notification or email.

What the requester sees and does

A requester who works through the service desk (the Client role) sees their ticket, its public replies and the people working it. Hand-offs, history, the work log and engineering issues linked to the ticket stay internal.

When their ticket is resolved, the requester closes it, not the agent:

Both are recorded in the ticket's history and the audit log. On the Service Request Fulfilment workflow the requester confirms from reporter verification the same way.

SLA policies

Defined per project. Each policy is one clock.

How a clock behaves

• Starts when the issue is created, or at first response for the first_response metric.
• Pauses while the issue sits in a status flagged pausesSla, or in a status named in the policy's pause list. Waiting on a customer or a vendor is not time the delivery team is burning.
• Breaches when elapsed unpaused time passes the target for the issue's priority. A breach is stamped with the time it happened.
• In business-hours mode, only working days and working hours count, so a ticket raised at 5pm Friday does not breach over the weekend.

The working calendar is set in workspace settings: working days (default Monday to Friday) and working hours (default 09:00 to 18:00).

Two notification types fire off clocks: sla-warning and sla-breach. There is also an sla_breached automation trigger.

Part 6 — People and administration

22. Roles and permissions

Permissions are the only thing authorisation checks against. Roles are data that map onto the permission list, so adding a role is a configuration change rather than a deploy.

Two naming conventions carry most of the meaning

• :any — acts on other people's records, not just your own. issue:edit lets you edit yours; issue:edit:any lets you edit anyone's.
• :admin — configures the thing rather than using it.

Anything scoped to a project is resolved per project. Holding project:admin does not mean holding it everywhere.

The 13 role templates

Seeded into every organisation as templates, not law. An owner can edit them or add their own.

Role assignments and scope

A role is granted to a principal (a user or a team) at a scope:

A user's effective permissions are: their base role's permissions, plus any granted overrides, minus any revoked overrides. Role assignments (project, team, department or org scope) can only add permissions inside their scope; they never take any away. To keep someone out of sensitive work, use a private project (only members, the lead and assigned people see it) or an issue security level. A revoked override removes a permission everywhere.

Legacy roles

Five original role names still work and map onto templates:

Billing effect

Only viewer is a free role. Everyone else consumes a paid seat.

23. Organisation structure

/admin/departments, /admin/teams, /admin/roles.

Departments

A division of the organisation: Engineering, Product, Support.

A project belongs to a department, and a role granted at department level covers every project beneath it.

Teams

A working group: Frontend, Backend, QA, DevOps. Teams are the unit work is assigned to and the unit permissions are granted to.

A person can belong to several teams — the developer who also sits in an on-call rota — which is why team membership is not a field on the user.

24. People, invitations, single sign-on

People

/admin/people. List, search, view and edit users. Actions: invite, deactivate, reactivate, delete, change role, set per-user permission overrides.

A user carries: name, email, employee id, department, job title, avatar, timezone, phone, presence, notification preferences.

Presence is online, away, busy or offline, plus an optional custom status with an emoji and a do-not-disturb-until time.

Invitations

Generated in People. Each invitation carries a role: viewer, employee, agent or admin.

Invitation statuses: pending, accepted, revoked, expired.

Acceptance and failure are reported per recipient, and a failed send keeps a copyable invitation link so you can pass it on by hand. The link points at the app URL configured on the server, so a misconfigured APP_URL ships links that look fine and go nowhere.

The recipient lands on /invite/:token.

Single sign-on

/admin/sso. Needs sso:manage.

Supported providers: local (password), Google, Microsoft, GitHub, Okta, generic OpenID Connect, and SAML 2.0 (optional).

Setting one up

1. Create an application at the identity provider.
2. Add the connection here and save it, to get its callback / redirect URI.
3. Register that exact URI with the provider.
4. Enter the credentials.
5. Run the connection test.
6. Enable it.

Enforced SSO requires a successful connection test first. Changing credentials, endpoints, scopes or provider configuration clears the previous test and disables the connection until it passes another one.

Per-connection settings

Caveats stated by the product

• The configuration test checks provider metadata and signing keys. It does not prove the client credentials work. Complete a real sign-in before requiring SSO for the team.
• SAML needs @node-saml/node-saml installed and HTTPS for cross-site callback cookies. It reports unavailable until installed.
• The workspace owner always keeps password recovery access.

Workspace authentication policy

Set in workspace settings:

25. Automation

/admin/automation. Needs automation:manage. Rules can be organisation-wide or scoped to one project.

A rule is: when this happens → if these are true → do these things.

Triggers

Conditions

conditionMatch is all (every condition must hold) or any (one is enough).

Each condition is a field, an operator and a value.

Actions

Guard rails

There is a test endpoint per rule, so you can try one before enabling it.

26. Integrations: webhooks and API keys

/admin/integrations. Needs webhook:manage or apikey:manage.

Webhooks

Outbound HTTPS calls when something happens.

Deliveries use pinned DNS resolution and bounded retries. The product tracks consecutive failures, the last delivery time, the last status code and the last error, and will disable a webhook with a stated reason. There is a test button per webhook.

API keys

Machine credentials for the REST API.

Only a hash of the key is stored, so a lost key cannot be recovered, only replaced.

27. Audit log and workspace settings

Audit log

/admin/audit. Needs audit:view. Exportable.

Every entry records: the actor, the actor's email, the action, the category, the target, a structured diff of what changed, the IP, the user agent and the outcome.

Retention is 365 days.

Workspace settings

/admin/settings. Needs org:manage.

There is also an admin diagnostics endpoint, including a test-email send that an authorised owner can fire at their own address.

Transfer ownership (owner only, at the bottom of the page): choose an active member who is not an external client, confirm with your password, and they become the workspace owner. You stay in the workspace as an Organization Admin; only the new owner can transfer it back. A wrong password is refused without signing you out.

28. Billing and seats

/admin/billing. Needs billing:view; changes need billing:manage.

The plan

Retired plan ids (business_annual, enterprise) stay readable for existing data. Legacy ids monthly, yearly and pro alias onto current plans. All new calculations are INR only; historical invoices and legacy USD fields are retained rather than rewritten.

Included at every level

Unlimited projects, 250 GB storage, 200 automation rules, custom workflows, SSO, SAML, 365-day audit retention, 50 webhooks, 20 API keys, chat and SLAs.

Seats

• A seat is billed for active users in a non-free role. Viewers are free.
• The owner consumes one seat.
• User creation is blocked once seats used reaches seats purchased.
• GET /api/billing/seats/preview quotes a seat change before you commit it.

Subscription statuses

trialing, active, past_due, cancelled, expired.

An expired trial loses access to core product endpoints while billing remains available, so you can always pay to get back in.

Payments

Razorpay, INR. Verification checks the signature, the captured status, the order, the amount and the currency. Seat-change and renewal receipts are bound to the authenticated organisation and cannot be reused for a different purpose or quantity.

Payment purposes: signup, seat_change, renewal, plan_change. Invoice statuses: draft, open, paid, void, refunded.

Renewal is an explicit payment you make from Billing & seats. Recurring mandates and automatic debits are not implemented.

You can also cancel (optionally at period end) and resume.

Part 7 — Communication and reporting

29. Chat, calls and meetings

Channels

/chat, /chat/:channelId. Needs chat:use.

A general channel is created with the workspace, one per project, and one per team. An incident workflow can open a war room channel automatically.

Per-member settings: channel role (owner, admin, member), muted, and notify on — all, mentions or none.

Messages

Messages support threads, emoji reactions, pinning, editing, deletion, and read state per channel.

Attachment and block types on a message: issue_ref (an issue preview), link_preview, code, image, file, system, poll.

Author types: user, bot, system, automation — so a message posted by an automation rule is visibly not a person.

Slash commands

Calls

/calls, /call/:roomId. Needs call:start. Screen sharing needs call:screenshare; recording needs call:record.

Meetings

/meetings. Needs meeting:schedule to create one.

Each meeting exposes an .ics invite at /api/meetings/:id/invite.ics, so it can be added to a normal calendar.

30. Notifications

The bell in the header, plus optional email and web push.

Types

ticket-assigned, status-changed, comment, review, closed, reassigned, baton-passed, baton-overdue, approval-requested, approval-decided, mention, chat-message, thread-reply, watching, sla-breach, sla-warning, due-soon, sprint, automation, billing, security, invite.

baton-passed is deliberately separate from ticket-assigned. The handoff is the thing being announced, not the assignment: "QA passed this back to you, it failed on Safari" reads differently from "you have been assigned an issue", and people triage them differently in a busy inbox.

Priority

low, normal, high.

Per-user preferences

Email

When Email is on (and the workspace's Email notifications switch is on), you are also emailed when you are @mentioned, an issue is assigned or handed to you, something of yours is due soon or has been waiting on you too long, and when a meeting you are invited to is scheduled, changed or cancelled. The requester of a service ticket is emailed about public replies and status changes on it. Nobody is emailed about their own action, and an internal note is never emailed.

Actions

Mark one read, mark all read, clear all, see the unread count.

Web push

Browser push notifications: fetch the public key, subscribe, send a test, unsubscribe. Works per device.

31. Reports

/reports. Needs report:view. report:team and report:org widen the scope from your own work to a team's and then the whole organisation.

Tabs: Overview, Throughput, Velocity, Workload, SLA. A cycle time and a timesheet report are also available from the API.

The baton data backs two things a status field cannot show: stage ageing (how long work has sat in each phase) and the bounce report (which issues keep going backwards). heldMs is denormalised onto each handoff so the bounce report is one query rather than a windowed scan.

32. Attachments

Attach files to issues, comments and test executions.

• Stored on the server's local disk by default, or S3.
• There is a usage endpoint so you can see how much space the workspace is consuming against the 250 GB allowance.
• Download and delete are permission-checked against the issue the attachment belongs to, so an attachment on a restricted issue is restricted too.

Deployment note for administrators: attachments are written to local disk. Render rebuilds the application directory on every deploy, so without UPLOAD_DIR pointed at a mounted persistent disk, every uploaded file is lost at the next release.

Part 8 — Reference

33. Every permission

Every permission in the system, and which of the 13 role templates grants it out of the box. Roles are editable, so treat the right-hand column as the shipped default rather than a rule.

Short names: Owner, Admin, PM (Product Manager), PjM (Project Manager), EM (Engineering Manager), Lead (Team Lead), Dev, QA, DevOps, Support, Employee, Viewer, Client.

Total: 74 permissions.

Work items

Projects and configuration

Agile planning

Releases

Environments and deployments

Testing

Service management

People and org structure

Organisation and platform

Reporting

Communication

34. What the product does not do

Stated plainly, because finding these out in week nine of a rollout is worse than reading them now. All of these are taken from the product's own notes.

Not implemented

Operational limits

Things that are easy to misread

• A status is not a stage. Reports and the pipeline stepper read the stage; boards and burndowns read the status category. Renaming a status changes neither.
• assignee and the baton holder are the same person by definition. They are stored twice so the baton can carry its own timestamps, and the engine keeps them in step. A plain assignee change — a board drag, a bulk edit, an automation rule — repoints the baton.
• Participants are additive. Removing someone clears them rather than deleting the record, so the roster of who touched an issue survives.
• A restricted issue returns 404, not 403. That is intentional.
• The create form caps the due date at one week out. Longer dates are set on the issue screen.
• "Unlimited admins" is not a claim the product makes. Administrator counts are governed by roles and seats like everything else.
• This is a substantial ticketing and collaboration feature set, not complete Jira or Slack parity. The product says so itself.

Appendix A — Route map

Public

Signed in

Inside a project

/projects/:projectId plus: (nothing) for the overview, board, backlog, sprints, roadmap, issues, releases, testing, environments, deployments, team, settings.

Administration

Old URLs that still work

/tickets → /service/tickets · /employees and /team → /admin/people · /board → /work/board · /backlog → /work/backlog · /issues → /work/issues · /create-ticket → /issues/new · /billing → /admin/billing · /tickets/:id → /issues/:id

Appendix B — API surface

Base path /api. Authentication is a bearer token from /api/auth/login or an API key.

Appendix C — Glossary

Generated from the source of ticketing-tool-server and ticketing-tool-application. The status catalogue and permission tables are machine-generated from config/stageCatalogue.js and config/permissions.js, so regenerate them rather than hand-editing when those files change.