Issue Tracker

BigLedger’s own work-tracking applet for a support desk that tracks issues on behalf of more than one customer tenant: projects, sprints, labelled issues with comments and worklogs, a kanban board and an issues report, with an optional two-way sync into GitHub. Nothing here posts or moves stock. The board’s columns come from the options of a custom field coded Status placed on the issue; without it the board is empty, and an issue whose status matches no column drops silently into the first one.

Overview

Issue Tracker is BigLedger’s own work-tracking applet: projects, issue types, sprints, labelled issues with comments, worklogs, attachments and a history, a drag-and-drop kanban board and an issues report. It runs inside a tenant, but it is built for a support desk that tracks issues on behalf of more than one customer tenant: every issue carries the customer tenant it belongs to, a Tenants switcher at the top of the menu filters the list to one of them, and a platform-level link decides which customer tenants each login may see. An optional two-way sync mirrors issues into GitHub Issues and a GitHub Projects V2 board.

Nothing here posts a journal, moves stock or creates a financial document. Issue Tracker is the back-office face of the same issue records that the Unified Contact Center’s Issue Tracker panel writes to, and the two applets share the same Application Settings → Issue Category screen.

The issue records are shared, so do not read them as this applet’s own. A custom integration can write issues directly, with its own status values, and those rows appear nowhere in the applet’s filters. If you report on issues outside the applet, filter on what this applet writes rather than counting everything.

Where it fits

Screens and menus

The application title bar reads Issue Tracker Applet; the registry name is Issue Tracker. On open the applet redirects to Issues.

Start-up gate. Before any screen is useful the applet loads the login’s user-tenant links. A login with no active link gets a dialog that cannot be closed — “You do not have permission to access any tenants. Please contact your administrator.” — and re-opens itself if dismissed. With exactly one link the tenant is auto-selected; with several, the link marked Is Default wins, then the most recently used tenant, else a tenant-selection dialog. Selecting a tenant records it as the most recently used.

Main menu

Issue detail page

The issue detail page is the only issue create/edit screen; opening it with no issue selected is create mode. The older Issue Create and Issue Edit screens were removed from the page stack and are unreachable; the quick-create dialog survives on the two dashboards.

The page is GitHub-shaped: click-to-edit title, a rich-text description, attachments in the main pane, a Details card in the sidebar (Assignee, Reporter, GitHub Repository, Project, Sprint, Label 1–3), a More Details block of custom fields, and three tabs — Comments, History and Worklogs (description, hours 0–24 in 0.5 steps, date). Buttons: New Issue, Sync with GitHub, Create Issue / Cancel in create mode, Save Changes / Cancel when the sidebar has unsaved edits.

Status is shown only as a read-only badge; there is no control on this page for status, priority or issue type. Status changes are made by dragging a card between kanban columns; issue type is set only by the quick-create dialog. There is also no delete on this page or on the Issues list — the only screen that offered one is the unreachable Issue Edit screen — so an issue created here can be retired only through the API or by the UCC applet.

Where the kanban columns come from

The Main Dashboard does not carry a fixed list of statuses. On load it looks through the custom-field placements on the issue that are visible and active for the one whose definition code is exactly Status, and turns that field’s options into the columns, in option order. Three things follow that the board itself does not explain:

• No Status custom field placed on the issue, no columns. The board renders empty and the console says No Status custom field definition found. The definition is created in Tenant Admin › Custom Field Management; the placement under Settings → Custom Fields Placement here.
• A card is placed by exact, case-sensitive match of its status against an option code. It reads the issue’s Status custom-field value first and falls back to the issue’s workflow status. A status that matches no column — including the empty status every issue created from the detail page has, because create mode writes no workflow status — is dropped silently into the first column.
• The quick-create dialog’s status list is hard-coded (TO DO, UNDER INVESTIGATION, IN PROGRESS, PENDING TEST, DONE, WILL NOT DO, IN REVIEW, REJECTED, DECLINED) and the KPI strip counts only TO DO, IN PROGRESS, PENDING TEST and DONE. If your Status options are spelled differently, the dialog creates issues the board mis-files and the KPI tiles stay at zero while Total rises.

Dragging a card to another column saves the whole issue with both its workflow status and its Status custom-field value set to the column key. Dragging within a column swaps the two cards' positions on the default board, creating positions where either card has none; with no default board set, same-column drags are not recorded.

Settings (gear)

The settings navigation carries an Issue Tracker Settings group — Projects, Issue Types, Project Categories, Users, Teams, Sprint, User Tenant, Tenant Repository Link, Custom Fields Placement, Kanban Board — above the System Configuration group (Application Settings, Field Settings, Default Selection), the shared Applet Access, the four server-side permission listings, Triggers (webhooks), and two Developer Tools links (Applet Log, Reset Applet State) that route to a 404 page.

The Kanban Board link is shown to everyone, but board administration itself is granted only to logins that actually hold a board-administrator record — seeing the link does not mean you can administer boards.

The Projects screen under Settings is a second copy of the Projects screen: its edit page has only Details and Notifications (no People, Issue Types or Delete), and its create page drops the Project Key on save. Use the main-menu Projects screen.

Personalization

Field Settings (routes to the same unbound stub as Settings), Default Selection, Sidebar; the Preset Themes, Color Assist and Easy Navigation links route to a 404 page. Profiles → My Profile is routed but linked from nowhere; it shows a read-only About Me tab. A Plans screen exists in the applet but has no route and cannot be opened.

Configuration

Before you can use it

Note that the GitHub token is platform-global: one credential serves every tenant.

Issue e-mail is deliberately not in this table. The Projects → Notifications screen exists and saves rows, but no path this applet’s screens use can send an e-mail — see Lifecycle and effects → E-mail for the three independent reasons.

Applet settings

Settings live in three applet-local screens. Anyone who can open Settings can change them; there is no per-setting authority.

Settings → Application Settings (tenant-wide):

There is no issue-code format setting anywhere in this applet or the backend: issue numbers are a per-project running sequence with no format option (see Lifecycle). Do not plan an issue-code scheme around one.

Settings → Default Selection:

Default Branch and Default Location on the same screen are saved but have no effect anywhere in this applet. They are the document-applet template.

Settings → Field Settings shows eight toggles (Unit Discount, SST/VAT/GST, WHT, Blanket Order, Segment, G/L Dimension, Profit Center, Project) and a SAVE button, but nothing on it is saved.

Personalization → Default Selection does not save either, and the first change to either drop-down produces an error.

Settings in other applets that control this applet

Feature visibility / permissions

This applet defines no client-side permissions, so Applet Access has nothing to grant and no screen can be hidden per role.

Server-side permissions are checked per action with the pattern OWNER or ADMIN, else the verb. The families the applet’s screens hit:

Four naming prefixes coexist (TNT_API_DM_WF_, TNT_API_WF_, BL_MODULE_WF_, MST_API_DM_APP_); a permission set built from the first prefix alone leaves the reports, categories and both link screens unauthorised.

Fields

Every edit screen in this applet saves the whole record it loaded with the fields on the form overwritten, so no editor here blanks the fields it does not show. That is worth saying because it means the Required rules below are screen-side only unless a backend rule is named: the backend runs no validation at all on issues, sprints, kanban boards or repository links saved from this applet, and the checks it does run elsewhere are on statuses, revisions, dates and references — nothing in the backend checks that a code is unique.

Issue — the detail page in create mode

The form takes a title, a description, and in the sidebar an assignee, the reporter (read-only, the current login), a GitHub repository, a project, a sprint, three label slots and one control per placed custom field. Everything else an issue can carry — priority, issue type, workflow status, the eight other label slots, the target/actual dates, billing and cost amounts, story points and mandays — is not on this screen. What the screen does not say:

Issue — the quick-create dialog (both dashboards)

Title, description, attachments, issue type, project, priority, status, sprint, assignee, and a Tenant selector of its own. Title, issue type and project are required by the form; attachments over 20 MB are skipped with a toast and are uploaded one by one after the issue exists, so an upload failure leaves the issue created.

The dialog is validated by its own form rules only; the backend runs no validation on what it saves.

Project

Name, code, key, type (Public / Private), category, lead, default assignee, description and an avatar, with People (e-mail verified against existing logins, rank default MEMBER), Issue Types (multi-select) and Notifications sub-tabs. Name and code are required and capped at 255 characters; category and lead are required on create. Code is read-only after save on the screen. What matters:

Sprint, Issue Type, Project Category, Kanban Board, Custom Fields Placement

A sprint takes a name, a code, a free-text period and start/end dates (no rule that the end follows the start). Issue types and project categories take a name, a code and a description; a kanban board a code, a name and a description; a custom-field placement a definition, a target table, a display order, a status and five booleans. The rows that carry something:

User Tenant link, Tenant Repository link

Users, Teams, Category Groups, Categories

A user takes a username, a name, a user type, a GitHub username, an e-mail (verified against a login, with Send Invite) and a description; the backend requires only that name and username are non-empty, and username is read-only after save. A team is a group record (name, code, description, website and an address), and its Users tab records the login, not the Issue Tracker user. A category group takes a code, a name, a type, a param code, a param name and a status; a category a group, a code, a name, a description and an optional parent.

Lifecycle and effects

Issue Tracker writes only workflow records — issues, comments, attachments, worklogs, history events, kanban boards, sprints, projects and their links — plus two platform-level link records. No journal posting, no stock movement, no financial document.

Statuses

An issue carries two independent statuses. The record status is the platform one (ACTIVE / INACTIVE / DELETED from this applet; a custom integration outside it writes its own values into the same field); the workflow status is the one shown on the board and is free text with no enum, no default and no backend transition rule — the quick-create dialog seeds TO DO, the detail page seeds nothing, and a kanban drop writes whatever the target column is keyed. The inbound GitHub sync maps GitHub closed to record status INACTIVE and open to ACTIVE, never DELETED.

Create and update — two endpoints, and this applet uses the lighter one

The backend has two ways of writing an issue. The one every screen in this applet uses — the detail page, the quick-create dialog, the kanban drag, the report — runs no validation, writes History, never queues an e-mail, and queues a GitHub push when the issue has a repository. The other — used by the UCC applet, and by this applet only for attachment upload — validates title, project, issue type and every reference, writes History on a best-effort basis, queues an e-mail when a matching notification config exists, and does not queue a GitHub push.

So the title, project and issue-type rules protect the UCC path and API callers; on this applet’s screens the only guards are the form rules named under Fields.

Every save from the detail page or the kanban board replaces the whole issue with the values it loaded plus the one it changed — which means two people editing the same issue overwrite each other by revision, not by field.

The issue number is a per-project running sequence. There is no configurable prefix or format in the backend; the PROJ-n style shown in the UI is the project key put in front on screen.

History is written after every create and update (ISSUE_CREATED / ISSUE_UPDATED). The update entry is a field-by-field diff of the old and new issue: text, date and amount fields are named in plain words, and references — project, assignee, reporter, issue type, sprint, parent, the eleven label slots — are resolved to names, so changed Assignee: A → B is readable. Comments and attachments write their own entries. Delete writes no event, and History on the UCC path is best-effort.

E-mail — why no issue e-mail can leave this applet today

The pieces exist: an e-mail notification job builds a message from the issue and sends it through a UCC e-mail endpoint via SendGrid. Three independent gaps sit between a Notifications row and a message, and any one of them is enough:

1. Nothing this applet’s screens do queues the job. Only the UCC applet’s write path queues it; the path every screen here uses does not.
2. The rows the Notifications screen writes cannot be matched. The sender looks a config up by its code; the screen stores the event under the config’s name and never sets a code. A row created here therefore matches no event, even on the UCC path.
3. The rows carry no sender. The job needs a UCC e-mail endpoint on the config and fails with Couldn’t find endpoint uuid when there is none; the screen never sets one.

If a config is created correctly through the API (code = ISSUE_CREATED / ISSUE_UPDATED / ISSUE_DELETED, an endpoint set, all five recipient flags present — a missing flag fails the job), then on the UCC path the recipients are the reporter, the assignee, the creator, the configured single user and the single e-mail address, each only when its checkbox is on. The last updater is not a recipient — their address is used only in the wording of the delete message. The ISSUE_DELETED e-mail is queued before the delete runs, so it goes out even if the delete then fails.

What is queued, and what never runs

Three background jobs belong to this applet:

• Issue e-mail notification — queued on demand, one job per event, never from this applet’s own screens (see E-mail). It is not a scheduled job. Its code is in the processor register, so a scheduler clock could name it, but every run reads the issue and the matched config that the save which queued it put on the job, and a clock carries only the fixed properties typed into it, so a timed run has no new event to report.
• Push to GitHub — queued every time an issue with a repository is saved, on a queue of its own so a slow GitHub cannot delay other jobs. Nothing is pushed until a repository link exists and an issue carries a repository.
• GitHub reconciliation — designed as a per-tenant scheduled job, and nothing creates that job for you: it runs only where somebody has added it in the Scheduler applet with processor GITHUB_TO_ISSUE_HDR_SYNC_CRON_PROCESSOR. Without it, and without a repository link, nothing is ever caught up.

Nothing else is queued. A comment, a worklog, an attachment, a kanban drag and a category change are plain writes: nothing overnight re-reads an issue, closes a stale one, recalculates a dashboard or sends a reminder. The only asynchronous things this applet can start are the GitHub push and — on the UCC path — the e-mail.

Tenant scoping — what the Tenants switcher does and does not do

All issues live in the login tenant’s database, whichever customer tenant is selected. Selecting a customer tenant only adds a tenant filter to the issue list; when the request carries no tenant filter, the list is filtered to the login’s user-tenant links. A caller who supplies a tenant filter explicitly is not checked against the link table, and the single-issue and count lookups apply no tenant filter at all. Treat the user-tenant link as a UI convenience — which tenants appear in the picker — not as a security boundary between the customer tenants tracked in one database.

GitHub sync

Loop safety: inbound changes are applied without going back through the outbound queue, so a change that arrived from GitHub is never pushed back to GitHub.

Webhook deliveries are processed by a small in-memory worker; a restart discards what is queued and the reconciliation job is the recovery.

What VOID / delete reverses

There is no VOID. Every delete in this applet is a soft delete: the record’s status becomes DELETED and it stays in the database. Deleting an issue marks its lines, extensions and history events the same way, so an issue’s History goes with it. Nothing downstream is reversed because nothing downstream is posted, and deleting a GitHub-linked issue locally does not close it in GitHub (delete does not queue an outbound push).

Where a delete can be started from: the edit page of a sprint, issue type, project category, kanban board, user, team or user-tenant link, the Tenant Repository Link listing, and the main-menu Projects listing. Not an issue — no reachable screen offers it — and not from any listing other than those two.

Related applets

• Unified Contact Center — its Issue Tracker panel writes to the same issue records, reads the same eleven category-group slots, and is the only path on which an issue e-mail can be queued.
• Tenant Admin — Custom Field Management, where the Status definition behind the kanban columns (and any other custom field) is created.
• Platform SysAdmin and Tenants V2 — the tenant rows the Tenants switcher lists and the platform permission that lets a login read them.
• Scheduler — hosts the GitHub reconciliation job.

Troubleshooting

Related documentation

• Platform applets — the hub this page belongs to.
• Unified Contact Center — the other writer of the same issue records.
• Tenant Admin — where custom field definitions are made.
• Scheduler — where the reconciliation job is defined.