Issue Tracker

Overview

Issue Tracker is BigLedger’s own work-tracking applet: projects, issue types, sprints, labelled issues with comments, worklogs, attachments and sub-tasks, a drag-and-drop kanban board and an issues report. It is a TNT-USER applet, so it runs inside a tenant, but it is built for a support desk that tracks issues on behalf of several customer tenants: 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 table 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 bl_wf_issue_hdr table that the Unified Contact Center’s Issue Tracker panel writes to, and the two applets share the same Application Settings → Issue Category screen.

Measured 2026-09-16: 13 active catalogue links across 7 tenants; 2 logins hold a user-tenant link; no GitHub repository link exists yet.

Where it fits

Screens and menus

The application title bar reads Issue Tracker Applet; the registry name is Issue Tracker. app.routing.ts L45 sets the main path to applets/akaun/issue-tracker-applet, matching the registry routerLink. On open the applet redirects to Issues (L262–L266).

Start-up gate. Before any screen is useful the applet loads the login’s user-tenant links from akaun_master (tenant.effects.ts L140–L172). 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 (app.component.ts L104–L121). With exactly one link the tenant is auto-selected; with several, the is_default row wins, then the most recent last_access_date, else a tenant-selection dialog (tenant.effects.ts L177–L219). Selecting a tenant writes last_access_date on the link row (L72–L107).

Main menu (menu-items.ts)

Issue detail page

issues/:tenantCode/:issueGuid (app.routing.ts L73–L85) is the only issue create/edit screen. :issueGuid = new is create mode. The older Issue Create and Issue Edit view columns were removed from the page stack (issue-pages.service.ts L50–L52) 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 (bl_wf_issue_event rows) 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 (issue-detail.component.html L66–L68); there is no control on this page for status, priority or issue type — the handlers exist (issue-detail.component.ts L1214, L1240, L1671) but nothing in the template calls them. Status changes are made by dragging a card between kanban columns; issue type is set only by the quick-create dialog.

Settings (gear)

The vendored shared settings navigation (shared-utilities/modules/settings/settings.component.html) hard-codes 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 from settingItems (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 404.

The Kanban Board link is behind *ngIf="isKanbanBoardAdmin". settings-container.component.ts L49 sets that flag with (result?.totalRecords || 0) >= 0, which is always true, so the link shows to everyone; the dashboard’s own copy of the same check (main-dashboard.effects.ts L162) uses > 0 and is the one that actually gates board administration.

The Projects screen under Settings is a second copy of the Projects screen: its edit page has only Details and Notifications (People and Issue Types are commented out, the Delete button too), 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 404. Profiles → My Profile is routed but linked from nowhere (its menu entry is commented out); it shows a read-only About Me tab. A Plans component tree exists in the repository with no route, no module import and empty templates.

Configuration

Before you can use it

Note that the GitHub token is platform-global: one GITHUB_LOGIN_CREDENTIAL row in akaun_master serves every tenant (GitHubConfig.java L47–L50).

Applet settings

Settings live in three applet-local screens; none uses the shared FieldConfigurationComponent from blg-shared-utilities (this repository vendors its own copy of shared-utilities under micro-fe/projects/shared-utilities and has no .gitmodules). Anyone who can open Settings can change them; there is no per-setting authority.

Settings → Application Settings (application-settings.component.ts, saved with saveMasterSettingsInit, tenant-wide):

Two more keys sit in the same form and are written on every SAVE but have no control and no consumer: ISSUE_CODE_FORMAT (initial value <running_no>) and RUNNING_NUMBER_GENERATION_METHOD (initial RANDOM_NUMBER_GENERATOR) — application-settings.component.ts L45–L46; the template renders only the category slots, nothing in the applet reads either key, and the backend numbers issues from a database sequence with no format option (see Lifecycle). Do not plan an issue-code scheme around them.

Settings → Default Selection (default-settings.component.ts, saved with saveMasterSettingsInit):

Default Branch and Default Location on the same screen are saved (DEFAULT_BRANCH, DEFAULT_LOCATION) but read by nothing in this applet — they are the document-applet template.

Settings → Field Settings renders eight mat-slide-toggles (Unit Discount, SST/VAT/GST, WHT, Blanket Order, Segment, G/L Dimension, Profit Center, Project) with no form binding and a SAVE button with no handler (field-configuration.component.html). Nothing is persisted.

Personalization → Default Selection is routed directly while written as a child component: @Input() appletSettings$ is never bound, the subscription that would populate it is commented out (personal-default-settings.component.ts L31–L39), and the first change to either drop-down throws on this.appletContainer.bl_applet_exts (L41). SAVE emits to no listener. Nothing is persisted.

Settings in other applets that control this applet

Feature visibility / permissions

bl_applet_client_side_perm_dfn holds no rows for IssueTrackerApplet (2026-09-16), so Applet Access has nothing to grant and no screen can be hidden per role.

Server-side permissions are checked per endpoint in the backend 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

Issue (detail page, create mode)

Issue (quick-create dialog, dashboards)

The dialog and the detail page default priority differently (MAJOR vs medium) and neither value is validated by the backend — priority and issue_status are free text on bl_wf_issue_hdr (L44, L63).

Project (main-menu Projects)

Sub-tabs: People (e-mail, verified against existing logins, rank default MEMBER), Issue Types (multi-select), Notifications (event name, single user, current assignee / reporter / user / project lead checkboxes, single e-mail address, team).

Sprint, Issue Type, Project Category, Kanban Board

Issue Type and Project Category creates check for a duplicate code client-side (Issue type code already exists!).

Custom Fields Placement

User Tenant link, Tenant Repository link

Users, Teams, Category Groups

bl_wf_user_hdr.github_username is what the inbound sync matches a GitHub assignee against.

Lifecycle and effects

Issue Tracker writes only workflow tables — bl_wf_issue_hdr, bl_wf_issue_comment_hdr, bl_wf_attachment_hdr, bl_wf_issue_worklog, bl_wf_issue_event, bl_wf_issue_dashboard(_link), bl_wf_issue_sprint_hdr, bl_wf_project_hdr and their links — plus two akaun_master link tables. No *DataConsistencyObject signum, no JournalPostingTypeHandler entry, no stock processor; grep of the wf packages for journal, generic-document and stock services finds only unused imports.

Statuses

bl_wf_issue_hdr carries two independent status columns. status is the platform row status (ACTIVE / INACTIVE / DELETED); issue_status is the workflow status 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 named (dashboard-container.component.ts, onKanbanDrop). The inbound GitHub sync maps GitHub closed to status = INACTIVE and open to ACTIVE, never DELETED (WFIssueInboundGithubService.java L486–L490).

Create and update

The detail page posts to core2/tnt/dm/wf/issue-hdrs/backoffice-ep (wf-issue-hdr.service.ts L12; WFIssueHdrController.java L67–L92). That controller checks TNT_API_DM_WF_ISSUE_CREATE and calls WFIssueHdrUow.create directly — it does not run WfIssueDataConsistencyObject (L78). The title, project and issue-type rules in that validator apply only to the older core2/tnt/dm/wf/issues endpoints used by the quick-create dialog and by UCC (WFIssueService.java L47, L89). On the detail page the only guards are the client-side toasts.

The issue number comes from AppSequenceCounterUow.incrementAndGet("bl_wf_issue_hdr", "ISSUE_TRACKER", [project key]) and is written to both issue_key and issue_number (WFIssueHdrUow.java L46–L59). Only the first container of a batch is numbered. There is no configurable prefix or format in the backend; the PROJ-n style shown in the UI is the project key concatenated client-side.

After a successful create or update the controller writes a bl_wf_issue_event row (ISSUE_CREATED / ISSUE_UPDATED; L80–L86, L131) and, when the issue has a github_repo_full_name, enqueues it on bl_wf_issue_sync_to_github_queue (L90, L135; WFIssueGithubSyncQueueService.java L52–L107 — never throws, so a slow GitHub cannot fail a save). Delete writes no event row (ISSUE_DELETED exists in WFIssueEventConstants but is never persisted), and event writes are wrapped in a swallowed try (WFIssueService.java L61–L63), so History is best-effort.

E-mail: an ISSUE_EMAIL_NOTIFICATION job is queued only when the project has a notification config row for the event; recipients are the union of assignee, reporter, creator, the configured single user and the last updater (IssueEmailNotificationProcessor.java L94–L121). The config’s property_json keys single_email_address, single_user, current_assignee, current_reporter, current_user are cast directly — a missing key throws.

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

All issues live in the login tenant’s database; the API visa is built from sessionStorage.tenantCode (shared-utilities/visa.ts L6) and never changes when a tenant is selected. Selecting a customer tenant only adds tenant_guids = <guid> to the issue query, which the backend turns into guid_tenant IN (:tenant_guids) (WFIssueHdrUow.java L220). On GET …/issue-hdrs/backoffice-ep/query the backend fills that filter from the login’s user-tenant links only when the caller sent none (WFIssueHdrController.java L252–L254); a caller who supplies tenant_guids explicitly is not intersected with the link table, and the sibling GET /backoffice-ep, GET /backoffice-ep/{guid} and GET /backoffice-ep/query/count apply no tenant filter at all (L180–L223, L275–L290). 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 writes go through WFIssueInboundGithubService, never through the controller, so they do not enqueue an outbound push (IssueHdrToGithubSyncProcesor.java L46–L50).

The webhook worker is an in-process bounded pool (2–4 threads, queue 500); a restart discards what is queued and the reconciliation job is the recovery (WFIssueGithubWebhookController.java L60–L72, L107–L114).

What VOID / delete reverses

There is no VOID. Delete on an issue, sprint, board or link sets the row’s status to DELETED through the ordinary delete endpoint; nothing downstream is reversed because nothing downstream is posted. Deleting a GitHub-linked issue locally does not close it in GitHub (delete does not enqueue an outbound event).

Related applets

• Unified Contact Center — its Issue Tracker panel writes to the same issue table through the …/issues/ucc/backoffice-ep endpoints and reads the same eleven category-group slots.
• 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 table.
• Scheduler — where the reconciliation job is defined.