# Project plan — sagegs1xml (Sage2GS1Xml / BSBC Invoice Export)

Evidence date: 2026-10-04.

Source repository: `git@bitbucket.org:overdrive/sagegs1xml.git`, `master` at `fc601bb` (2019-11-20, "Initial commit", author maanie@overdrive.co.za).

`git ls-remote --heads` on that date returned only `refs/heads/master` at the same commit. There is no README, issue list, or milestone file in the tree. This plan describes what that commit contains. It does not decide what the product should become.

Credential literals in `SQLConnector.vb`, `frmMain.vb`, and `SUN_SAGE2XML.sql` are not copied into this document.

## Product

The window title is **BSBC Invoice Export**. The ClickOnce product name is **Sage2XML**, publisher **Sungula**, suite **Sage2XML**. The assembly and project name are **Sage2GS1Xml**. The Git slug is **sagegs1xml**.

Provenance: **Implemented** (`frmMain.Designer.vb` form text, `Sage2GS1Xml.vbproj` publish properties, `AssemblyInfo.vb`, `Sage2GS1Xml/bin/Debug/Sage2GS1Xml.application`).

What the desktop program does on `master`: an operator picks a date range and a local folder, the program calls two SQL procedures against a database named `BSBC`, writes a pipe-delimited `.csv` per invoice, uploads that file by FTP, and deletes the local file after a successful upload. Shoprite/Checkers (`AccountLink` `5261`) and Pick n Pay (`AccountLink` `6960`) are the only account codes with a folder and an FTP path.

A SQL script in the same project, `Sage2GS1Xml/SUN_SAGE2XML.sql`, builds a GS1 / EAN.UCC SOAP invoice XML document. The WinForms code does not execute that procedure. Provenance: **Implemented** as a file in the tree, and **Implemented** as unused by `frmMain.vb`.

No written product goal was found. Who still operates this program is **Unknown / Requires Confirmation**.

## What this repository is

A Visual Studio Windows Forms application (VB.NET, .NET Framework 4.5) plus one SQL script and a committed Debug build. Solution format is Visual Studio 2013 (`Sage2GS1Xml.sln`). A user file and `.vs/Sage2GS1Xml/v15/` indicate the tree was also opened with Visual Studio 2017. Provenance: **Implemented**.

## History

| Marker | Evidence | Provenance |
|---|---|---|
| Assembly copyright 2015 | `AssemblyInfo.vb` | **Implemented** |
| Window subtitle "25 June 2018" | `frmMain.vb` load, appended only when ClickOnce `CurrentDeployment` succeeds | **Implemented** |
| ClickOnce revision 44, version `1.0.0.44` | `Sage2GS1Xml.vbproj` `ApplicationRevision`; committed `Sage2GS1Xml.application` | **Implemented** |
| Git import 2019-11-20 | single commit `fc601bb` | **Implemented** |
| Older Team Foundation Server collection | `Sage2GS1Xml.sln` `SccTeamFoundationServer` = `https://sungula.visualstudio.com/defaultcollection`. Project SCC properties are `SAK` | **Implemented** as a historical pointer. Whether that collection still holds history is **Unknown** |

The Git date is the import of an already-built tree (binaries, `obj`, ClickOnce revision 44). It is not evidence that development started in November 2019. Provenance: **Inferred** from the contents of the only commit.

## Branches

Default branch is `master`. No other remote head was listed on 2026-10-04.

## Scope that is in the repository

- One main form with a Main tab (dates, process, log, upload-only checkbox) and a Settings tab (SQL server, FTP fields, output folder).
- SQL access through `SQLConnector` on a background worker, database name `BSBC`.
- CSV file creation and FTP upload for two customer account codes.
- User-scoped settings for server, FTP, XML credentials, and folder path. Only some of those settings are read by the process that runs.
- ClickOnce publish metadata aimed at `sage2xml.sungulademo.co.za`.
- `SUN_SAGE2XML.sql`, copied to the build output, which emits GS1 invoice XML for account `6960`.

Out of scope of what the WinForms process calls:

- The GS1 SOAP document built by `SUN_SAGE2XML`. Nothing in `frmMain.vb` executes it.
- `Pastel.Evolution.dll`. It is referenced from a path outside the repository and no VB file uses the namespace.
- Definitions of `SUN_GETINVOICES` and `SUN_GETINVOICEDETAILS`. The application executes them. Their bodies are not in Git.
- Tests, a README, a pipeline file, and a scheduler.

## Architecture

```text
Operator (Windows desktop)
  → Sage2GS1Xml.exe (WinForms, ClickOnce metadata)
      → SQL Server database BSBC
          EXEC SUN_GETINVOICES        (definition not in Git)
          EXEC SUN_GETINVOICEDETAILS  (definition not in Git)
      → local folder
          SHOPRITE\<Reference>.csv
          PNP\<Reference>.csv
      → FTP upload, then delete local file
          xpliquor.dyndns.org /ShopriteInvoices/
          xpliquor.dyndns.org /Invoices/

Not called by the executable:
  SUN_SAGE2XML.sql → GS1 / EAN.UCC SOAP XML column XML_DATA
```

Provenance: **Implemented** for the arrows the VB code performs. The SQL script's result is **Implemented** as script text only.

## Major components

| Component | Location | Role |
|---|---|---|
| Solution | `Sage2GS1Xml.sln` | Single project |
| Main form | `Sage2GS1Xml/frmMain.vb`, `frmMain.Designer.vb` | Dates, process, settings, log |
| SQL client | `Sage2GS1Xml/Classes/SQLConnector.vb` | Connection and background query |
| Log helper | `Sage2GS1Xml/Modules/Globals.vb` | Appends a timestamped line to `txtLog` |
| GS1 SQL script | `Sage2GS1Xml/SUN_SAGE2XML.sql` | Alters `SUN_SAGE2XML`; not called by the form |
| ClickOnce manifest | `Sage2GS1Xml/bin/Debug/Sage2GS1Xml.application` | Install identity version `1.0.0.44` |
| Settings | `Sage2GS1Xml/My Project/Settings.settings`, `App.config` | User-scoped strings |

## Milestones and implementation plan

No milestone list or implementation plan is in the repository.

Current status, as far as Git shows: frozen on `master` since the 2019-11-20 import. Whether the ClickOnce host, the FTP host, or the `BSBC` database procedures are still in use is **Unknown / Requires Confirmation**.

## Dependencies known from the tree

- .NET Framework 4.5 (`Sage2GS1Xml.vbproj`, ClickOnce `compatibleFrameworks`).
- Windows Forms, `System.Data.SqlClient`, `System.Deployment` (ClickOnce version), `System.Net` FTP.
- SQL Server database name `BSBC`. Views and tables named in `SUN_SAGE2XML.sql` (`_bvARTransactionsFull`, `_bvARAccountsFull`, `CLIENT`, `_bvSTTransactionsPivot`, `STKITEM`) match Sage Pastel Evolution naming. That the live database is Sage Evolution is **Inferred**.
- `Pastel.Evolution` hint path `..\..\..\..\PastelSDK\Pastel.Evolution.dll`, outside this repository, with no source usage.
- FTP host `xpliquor.dyndns.org` (invoice upload) and `ftp.sungulademo.co.za` (ClickOnce publish URL).
- Install URL `http://sage2xml.sungulademo.co.za/`.

## Task-metadata discrepancy

The onboarding issue listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root, next to `desktop.ini`, the solution, and `Sage2GS1Xml.vssscc`. `git ls-tree` of `master` at `fc601bb` does not contain the two Sonar paths. Provenance: **Implemented** absence at this revision. They may have been untracked files on the scan host. **Requires Confirmation** if a scanner was added outside Git.

## Human confirmation

- Is BSBC Invoice Export still operated, and is `master` at `fc601bb` the build that operators run?
- Did the CSV + FTP process replace `SUN_SAGE2XML`, or is the GS1 procedure still installed on the `BSBC` server and used by something else?
- Where are the definitions of `SUN_GETINVOICES` and `SUN_GETINVOICEDETAILS`, and what are the 23 columns the CSV writer expects?
- Are account `5261` (Checkers / Shoprite) and account `6960` (PNP) still the customers this export serves?
- Are `sage2xml.sungulademo.co.za` and `xpliquor.dyndns.org` still the install and upload hosts?
- Should the hardcoded SQL login, FTP password, and SQL-procedure credential defaults be rotated? They are in Git history. Values are omitted here.