Invoices Workspace

The Invoices workspace centralises every pre-configured template that the finance and verification teams use to generate payment-ready documents. This is where you select an existing template, preview the results with the right organisation unit and period, and then download the file in the format required by your payment workflow.

Why invoice templates matter

Invoice templates bundle the complex configuration that links tariff datasets, organisation units, grouping rules, and export columns. Each template stores:

• The dataset identifiers that determine which services, tariffs, and quality scores feed the totals.
• The period type (Monthly, Quarterly, or Yearly) so the UI can offer the correct list of reporting periods.
• Optional extra calculations and custom rows used by finance teams when reconciling incentive payments.
• A full download history that proves when a document was generated, by whom, and for which organisation unit.

By centralising this configuration, the workspace helps teams focus on selecting the correct metadata and reviewing totals instead of wrestling with spreadsheets.

Page layout at a glance

The landing page lists every invoice template your account can access. This guide focuses on previewing, downloading, and reviewing history rather than the template creation flow.

Table columns on the landing page

Access prerequisites

Before opening the detailed dialog, confirm the following:

1. User role – Only users with roles that include invoice permissions will see the workspace. Data Entry-only users can view the list but cannot open the download dialog.
2. Organisation unit scope – The dropdown inside the dialog shows the organisation units that are assigned to your user account. If you cannot find a facility or district, request sharing from an administrator.
3. Dataset connectivity – Invoice templates reference one or more tariff datasets. If a dataset has been archived or if tariffs are missing, the preview may return empty values until the configuration is restored.
4. Bank details readiness – Bank account names and numbers pull from facility bank records. Encourage facilities to keep those details up to date so the exported invoices are complete.

Working with the actions menu

Each row in the table has an actions button with three choices:

1. Preview – Opens the invoice dialog on the Details tab with the preview controls active. Use this when you want to confirm totals before downloading.
2. History – Opens the same dialog but jumps directly to the History tab, showing who downloaded the file previously and for which period.
3. Completeness – Navigates to the completeness checker. That tool is outside the scope of this document but is useful when verifying that every facility has submitted data.

Selecting either Preview or History loads the invoice dialog described below.

Navigating the invoice dialog

The invoice dialog is a full-height modal with tabs. It remembers which tab to open based on the action you selected. The dialog always shows three tabs:

• Details – Summary information, metadata selectors, and (for previews) a live grid of invoice rows.
• History – The chronological list of downloads, including period, organisation unit, timestamp, and user.
• Settings – The configuration snapshot that explains how the template behaves, including additional columns, custom rows, and grouping defaults.

Use the tab strip near the top of the dialog to move between sections at any time.

Details tab essentials

The Details tab is split into two zones:

1. Template summary – A compact grid that repeats the template name, period type, and total download count. When preview or download mode is active, it also exposes the selectors you must complete.
2. Preview panel – When you open the dialog in preview mode, the right-hand column becomes a mini report showing up to 20 rows of invoice data. This helps you confirm grouping and totals before exporting the full file.

Selection controls on the Details tab

These controls appear when you open the dialog through the Preview or History options. They define the dataset slice used for previews and downloads.

How period options are built

• Monthly templates – The app offers the last 12 completed months counted backwards from the current month. Labels are formatted as YYYY MMM to aid recognition, while the API sends YYYYMM.
• Quarterly templates – The dropdown lists the last eight quarters. Each option clearly states the quarter number and year (e.g., 2023 Q4). These periods align with the fiscal cadence configured in DHIS2; if your programme treats Q1 as July–September, the backend supplies that mapping.
• Yearly templates – The control shows the last five complete financial years. If the fiscal year spans multiple calendar years, the label includes the fiscal reference such as FY 2022/2023.

When you change the period type at the template level, the dialog automatically refreshes the options so you never mix fiscal and calendar periods.

Organisation unit behaviour

• The dropdown includes only units that belong to your assignment tree and are enabled for invoices.
• Searching works across full names, so typing a district or facility name quickly narrows the list.
• When grouping by level, you may still pick a lower-level facility as the base selection; grouping then aggregates rows under the higher-level headings in the preview and export.

Grouping logic

Grouping is optional but powerful. It influences both the preview and the downloaded file:

• Selecting a level such as District (Level 3) groups facility rows under their district headings and shows group subtotals.
• If a facility lacks a parent at the chosen level, the preview marks the grouping column with a fallback label so you can spot configuration gaps.
• Changing the grouping level automatically refreshes the preview data when a period is selected.

File formats explained

Preview grid structure

When you select both an organisation unit and a period, the preview grid fetches up to 20 representative rows. This lightweight preview keeps the dialog responsive while still reflecting the real export.

Handling calculated columns and custom rows

Some templates include extra computed fields (for example, deductions or bonuses) or summary rows (such as overall programme totals). The preview indicates the presence of these extras even when they are not shown in the 20-row sample:

• Calculated columns are listed under the selector section so you know which formulas will appear in the export.
• Custom rows are summarised in the Settings tab, and the export appends them at the bottom of the table with the configured formulas.

Downloading invoices

Once you have selected the organisation unit, period, grouping, and format, click Download in the dialog footer. The system follows these rules:

1. Validation checks – The download button stays disabled until you choose at least a period. If the template requires an organisation unit but none is selected, the button remains inactive.
2. Grouping parameter – When grouping is enabled, the request includes the chosen level so the exported file shows grouped totals.
3. Export pipeline – The backend returns structured invoice data. The UI then formats it into PDF, Excel, or CSV locally before triggering the browser download.
4. History update – Each successful download records the period, organisation unit, timestamp, and user. The History tab refreshes immediately, so you can confirm the action was logged.

During the export process a spinner appears next to the button label. You can close the dialog after the file downloads; there is no need to remain on the page.

Download history tab

The History tab is your audit trail. It lists the most recent downloads first and keeps a full record of past exports.

Additional behaviours:

• The list shows up to five entries on the main screen. When more exist, a hint reminds you that only the latest records are visible in the dialog and that the full history is available via the API.
• Each new download appears instantly without closing and reopening the dialog.
• If a download fails before completion, it does not create a history record.

Settings tab deep dive

The Settings tab provides transparency into how the template was configured. This is critical when auditors or new team members inherit the workflow.

Key sections include:

1. Datasets referenced – Lists the dataset IDs used for quantities, tariffs, and quality scores. If multiple datasets are bundled, each appears on a separate line.
2. Period type and expiry rules – Shows the period type and whether the template restricts selection to closed periods only (the default). If a special expiry window applies, it is documented here.
3. Organisation unit restrictions – Notes if the template allows only a specific level (for example, district-only invoices). The dialog enforces this restriction when you pick organisation units.
4. Additional columns – Displays the names of calculated columns included in the export, such as “Retention Deduction” or “Bonus Amount.”
5. Custom rows – Lists special footer rows, e.g., “Total Payable” or “Advance to Deduct,” along with hints about the formulas applied.
6. Recent downloads summary – A condensed view of the history so you can confirm usage without switching tabs.

Step-by-step workflow

Best practices for finance teams

1. Align periods with payment cycles – If your programme pays quarterly but quality assessments arrive biannually, confirm the template uses the correct period type to avoid misaligned totals.
2. Verify bank data monthly – Before large disbursements, filter the preview grid to confirm every facility has valid bank details. Missing data should be corrected in the bank details workspace before exporting.
3. Use grouping for district reviews – When district health officers need oversight, export grouped PDFs so each district receives a consolidated appendix.
4. Track download counts – The Downloads column and the History tab together help you monitor who generated which invoice. If a template shows unexpected activity, follow up with the listed users.
5. Capture exceptions in Settings – If you temporarily add a deduction or bonus column, note it in your internal change log so auditors understand why the export changed.

Troubleshooting

• No organisation units appear – Ensure you are assigned to the relevant units in the user management module. If the template restricts selection to a specific level, confirm your units include that level.
• Period dropdown is empty – The template may have a yearly period type while the dataset lacks recent yearly data. Check that the dataset includes completed periods or adjust the template.
• Preview shows missing bank details – Update the facility’s bank record in the Bank Details workspace. The preview uses the first available record; if none exists, the export will contain blanks.
• Download button stays disabled – Verify that you selected a period. For some templates, an organisation unit selection is also required before downloading.
• History tab is blank – The template might be new, or no one has downloaded it since the last reset. Trigger a download to confirm the logging is active.
• Exports take too long – Large grouped exports can take several seconds. Wait for the spinner to finish. If the browser reports a network error, try again with a smaller grouping or check your connection.
• Totals look incorrect – Confirm the template references the correct datasets and that the underlying tariffs and quality scores were updated for the selected period.