MY-SST APPLET

Overview

The MY-SST applet is where a Malaysian SST-registered company defines its taxable periods, decides which posted documents belong in each period, and produces the SST-02 return for the Royal Malaysian Customs Department (RMCD).

It does four things and nothing else: it maintains tax years (bl_fi_filing_year_hdr) and filing cycles (bl_fi_filing_hdr); it maintains tariff codes (bl_fi_mst_label_hdr under the TARIFF_CODES label list) and tax codes (bl_fi_cfg_tax_code); it files posted generic documents, which copies their taxed lines into a frozen snapshot table (bl_fi_tax_txn); and it reports — three on-screen reports plus the SST-02 itself, which is computed entirely from that snapshot.

The applet does not calculate tax on a transaction. Tax is calculated on the sales, purchase and POS documents from the tax code attached to each line. The applet only decides which of those already-taxed lines land in which return.

Where it fits

Screens and menus

Route root: applet/tnt/wavelet/erp/my-sst. Landing route is Tax Year.

The Tax Filing & Submission workspace

Opening a filing cycle gives a three-level tab structure. The nesting matters, because Service and Sales behave differently at every level below it.

Tax Filing & Submission
├── Details            (cycle metadata + Lock + Delete)
└── Tax Filing
    ├── Service
    │   ├── Filed Transactions
    │   ├── Unfiled Transactions
    │   ├── SST-02
    │   ├── SST-02 Version 2
    │   └── SST-02 Version 3
    └── Sales
        ├── Filed Transactions
        ├── Unfiled Transactions
        └── SST-02

The Service tab carries three SST-02 variants and the Sales tab carries one. The variants are not drafts of each other — each calls a different endpoint with a different hard-coded set of service tax codes (see How each SST-02 box is computed).

Tariff Code screens

Configuration

Before you can use it

Applet settings

Applet-local, and none of it works. app.routing.ts imports the applet’s own FieldConfigurationComponent and DefaultSettingsComponent from components/settings-container/, not the shared blg-shared-utilities screen. The submodule is present and pinned at 7f59480, but it is not what the settings routes render (METHOD §29). AppletSettingsModule and AppletPersonalizationModule are both in AppModule.imports, so the screens do render — they simply do not save.

Four-proof result: no setting in this applet passes all four proofs through its own screens.

models/applet-settings.model.ts declares 25 keys (INCLUDE_* ×6, DEFAULT_BRANCH, DEFAULT_LOCATION, ENABLE_* ×6, PRINTABLE, 15 ENABLE_CUSTOM_STATUS_*). A plain grep of the whole src/ tree finds a reader for exactly one of them.

DEFAULT_BRANCH is the interesting row. The SST-02 components read it from SessionSelectors.selectPersonalSettings, which the shared session effect populates from the per-user USER_SETTINGS row on bl_applet_login_subject_link_ext — not from the applet-level APPLET_SETTINGS row that this applet’s Default Selection screens try to write. So the one consumed setting is a personal setting that this applet’s personalization screen cannot save. In practice the Branch field on the SST-02 tabs starts empty.

There is no inline app-applet-settings-toggle gear anywhere in the applet (METHOD §8 checked, zero hits).

Document behaviour settings

Not applicable in the usual sense: this applet creates no generic document, so there is no status flow, no posting toggle, no printable selection and no e-Invoice flag on its own records. The two behaviours that would normally be settings are fixed in the backend:

• Which documents are eligible is fixed by the SQL in SSTUow (tax type, posting status, settlement) — see Lifecycle and effects.
• Which tax codes each SST-02 box sums is fixed by literals in SSTController — see the table below.

Settings in other applets that control this applet

Feature visibility and permissions

Permission families are not what the menu names suggest, and no single “SST” family covers the applet.

Tariff codes and tax codes are written through the generic label and tax-code endpoints and carry those endpoints’ permission families, not an SST family.

No bl_applet_client_side_perm_dfn rows are seeded for this applet, so the Client-Side Permission listing — the screen the settings route redirects to — opens empty.

Fields

Tax Year (bl_fi_filing_year_hdr)

Tariff Code (bl_fi_mst_label_hdr)

txn_type is set to the literal TARIFF_CODES and label_list_guid to the GUID of the TARIFF_CODES label list looked up at screen load.

Tax Code (bl_fi_cfg_tax_code)

tax_country is set to MYS — the alpha-3 code of the single country the form filters the country list down to. is_input / is_output are derived from whether the type string contains INPUT.

Filing Cycle (bl_fi_filing_hdr)

fiscal_year_guid is assigned from a form control named fiscal that does not exist on this form, so a filing cycle is always created with a null fiscal year.

The FinancialFilingDataConsistencyObject validates FK existence for company, branch, fiscal year and fiscal period, and the presence of the platform housekeeping columns. It does not validate that the end date is after the start date, and it does not check for overlapping cycles. Two cycles covering the same month are accepted, and the same document can be filed into both.

Lifecycle and effects

This applet writes no journal, creates no generic document, and moves no stock. Its effect on the ledger is nil; its effect on the tax record is bl_fi_tax_txn.

What “Unfiled” means, and why Service and Sales differ

The Unfiled Transactions grid is a live query over bl_fi_generic_doc_hdr. The two tabs use different SQL.

The Service side is therefore a payment-basis view: an unpaid service invoice never appears, however final it is, and a service invoice paid in April appears in the April period even if it was raised in February. That is the Malaysian service-tax rule, and it is implemented in SQL rather than as a setting. The Sales side is accrual-basis and does not even require the document to be final.

File and File All

FILE IT posts the selected document GUIDs to fi/tax-txns/file/backoffice-ep/. FILE ALL posts the current filter to fi/tax-txns/service|sales/file-all/backoffice-ep/, which re-runs the eligibility query server-side and files everything it returns.

For each document, TaxTxnService.fileTaxTxn walks bl_fi_generic_doc_line, keeps only lines whose txn_type is PNS (the item / product-and-service line type), and writes one bl_fi_tax_txn row per kept line. Each row is a snapshot: document type, both document numbers, transaction date, header net / tax / txn / withholding amounts, the line’s net, tax and txn amounts multiplied by the line signum, tax code, tax rate, tariff code, currency, item code, description, quantity, and the entity’s name, GUID, customer-or-supplier flag and tax registration number.

Consequences worth knowing:

• Non-PNS lines never reach the return. A taxed charge or freight line that the document carries as a different line type is taxed on the invoice and absent from the SST-02.
• On success the header’s posting_tax_gst is set to POSTED; that is the only thing that moves a document from Unfiled to Filed.
• FILE IT skips documents already at posting_tax_gst = 'POSTED'. FILE ALL does not — it files whatever the eligibility query returns.
• If the write fails, the controller returns HTTP 200 with an empty list for that document and leaves posting_tax_gst unset. Nothing is raised to the user.

Unfile

UNFILE IT posts to fi/tax-txns/unfile/backoffice-ep/. For each document the controller builds a criteria of company plus document header GUID, and TaxTxnService.unfileTaxTxn calls deleteTaxTxn on container.stream().findFirst().get() — the first matching row only. It then clears posting_tax_gst to null on the header.

So on a document with more than one taxed line, Unfile hard-deletes one bl_fi_tax_txn row, leaves the rest attached to the filing cycle, and marks the document unfiled. Filing it again adds a second full set of rows. This is the mechanism behind the recurring duplicate-filing reports. Unfile is a delete, not a status change; there is no audit row left behind.

If no matching row exists, .get() on the empty result throws.

Lock

Lock is PUT fi/filings/backoffice-ep/lock/{guid}.

1. It calls checkPreviousCycleIsLocked: any filing cycle for the same company with an earlier date_start and locked_status IS NULL blocks the lock. The query does not exclude deleted cycles. The response is HTTP 200 with the body PREVIOUS FILING CYCLE IS NOT LOCKED; the applet’s effect recognises this string and shows it as an error toast.
2. Otherwise it sets locked_status = 'LOCKED', locked_time, locked_by_subject_guid and saves.
3. If — and only if — the request body carries a glcode key, it then runs FinancialFilingService.carryForward, which posts a journal named SST-02 Auto Transfer, described AUTO CREATED DURING LOCKING OF FILING CYCLE. The applet never sends glcode: confirmDialog dispatches the lock with {} and the carry-forward dialog is commented out with the note that carry-forward is a GST concept, not an SST one. The branch is reachable only by calling the endpoint directly.

What Lock does not do: it does not stop filing or unfiling. Neither fileTaxTxn, file-all nor unfileTaxTxn reads locked_status. Documents can still be filed into and unfiled from a locked cycle.

What Lock does do, unintentionally: Part A of the SST-02 is queried with locked_status <> 'LOCKED'. Locking a cycle makes its own Part A — company name, SST number, period start and end, due date — come back empty on every subsequent SST-02 render.

There is no unlock action in the applet.

Delete

Deleting a filing cycle first looks for any bl_fi_tax_txn row against it. If one exists the endpoint returns HTTP 200 with FILED_GENERIC_DOC_FOUND and the message Cannot delete this filing cycle: filed documents found. Please unfile all documents first., which the applet surfaces as an error toast. Otherwise the cycle is soft-deleted without firing a webhook.

VOID of a filed document

VoidTaxProcessor is a generic-document queue subscriber (getQueueCode() = "VOID_TAX_PROCESSOR"). When it runs against a document whose posting_journal is POSTED and whose posting_tax_gst is not already VOID, it calls TaxTxnService.reverseTaxTxn, which writes a new bl_fi_tax_txn row with every amount negated and filing_status = VOID, and sets the document’s posting_tax_gst to VOID. It does not delete the original row; the SST-02 nets the two.

Two caveats:

• Nothing in the Java tree enqueues this processor directly. It runs where a tenant’s job template subscribes it to the generic-document queue. Where it is not subscribed, voiding a document leaves its tax transaction in the return.
• If the document was never filed, reverseTaxTxn throws No tax transaction found for this generic document!.

How each SST-02 box is computed

Everything below reads bl_fi_tax_txn filtered by status <> 'DELETED', the company, and the filing cycle. Nothing reads the live documents.

The three Service variants exist because the Malaysian service tax rate changed. Pick the variant whose tax codes match the rate in force for the period you are filing: the original for a 6%-only period, Version 2 for an 8%-only period, Version 3 for a period that straddles the change.

Because the codes are literals in the backend, a tenant whose SST tax codes are not named exactly SRS6, SRS8, SVU-6, IMS6, SRG5, SRG10, SW-5, SW-10, SU-5, SU-10, ESS0, ESA, ESB, ESC-A/B/C, EPC-A/B/C, ZREG0 or ZRLG0 will get a Part B1 that adds up and a Part B2 that is zero. There is no setting to change the mapping.

The three on-screen reports

The first two read live documents. The SST-02 reads the frozen snapshot. They are different numbers by design, and they diverge permanently as soon as a filed document is edited.

Related applets

• Tax Configuration — the other maintenance surface over bl_fi_cfg_tax_code, with different write conventions.
• Organization — company SST registration number and fiscal years.
• Chart of Account — the GL codes the tax journals hit; not written by this applet.
• Doc Item Maintenance — where a tax code reaches a document line.
• Sales Invoice (Internal), Purchase Invoice (Internal), Sales Credit Note (Internal) — the documents that get filed.
• Ledger and Journal — where the tax GL balance actually lives.
• Financial Report — for reconciling the return against the tax GL accounts.
• MY E-Invoice Admin — a separate LHDN obligation on the same documents; it shares no tables with SST filing.

Troubleshooting

Related documentation

• Financial Accounting module — where SST filing sits in the period-end close.
• Tax Configuration applet — the tax-code reference, including the divergence between the two maintenance screens.
• Organization applet — company SST registration and fiscal-year setup.