# GL Accounts Excel API - Client Delivery

## Recommended Files

Send these files to the client:

- `GL_Accounts_Client_Template.xlsx`
- `GLAccountsExcelApi.bas`
- `gl_accounts_sql_poc.sql`
- `GL_Accounts_Functions_Documentation.pdf`

## Why This Package Is Stable

`GL_Accounts_Client_Template.xlsx` is macro-free and contains no active UDF
formulas. It does not open ODBC connections when the workbook starts, so Excel
can load it normally even before the client database connection is configured.

The previous `.xlsm` proof-of-concept workbooks are not recommended for client
delivery because Microsoft 365 may inspect or recalculate embedded VBA/UDF
formulas while opening the workbook. That can block Excel at `Opening ... 0%`
if ODBC, macro trust, or the database is not ready.

## Client Setup Flow

1. Apply `gl_accounts_sql_poc.sql` on the target database.
2. Create a PostgreSQL ODBC System DSN, for example `TradonGLApi`, then
   configure `GL_API_CONNECTION_STRING` in `GLAccountsExcelApi.bas` as
   `DSN=TradonGLApi;Uid=tradon_readonly;Pwd=...;`.
3. Import `GLAccountsExcelApi.bas` into Excel VBA, or deploy it through the
   client's approved add-in/macro process.
4. Open `GL_Accounts_Client_Template.xlsx`.
5. On the `Functions` sheet, run `InstallGLApiFormulas` to mark result cells
   as ready. This does not write live Excel formulas.
6. Run `RefreshGLApi` to call the database, write plain result values, then
   disable database calls again.

## Implemented Excel Functions

- `GetAccountBaseAmount`
- `GetAccountRealBaseAmount`
- `GetAccountAmount`
- `GetAccountAbbr`
- `GetAccountName`
- `GetAccountContact`
- `GetAccountContactCode`
- `GetAccountContactName`

All functions use:

```excel
(companyKey, accountCode, currencyIso, valueDate)
```

## Operational Notes

- `currencyIso` currently filters the transaction currency. It is not yet an
  output conversion currency.
- `GetAccountContact` is kept for backward compatibility and returns party
  code first, name fallback.
- `GetAccountContactCode` returns party code first.
- `GetAccountContactName` returns party name first.
- The VBA module starts with database calls disabled, so copy/paste cannot
  open ODBC connections by itself.
- `InstallGLApiFormulas` prepares result cells without creating live
  `GetAccount...` worksheet formulas.
- `RefreshGLApi` enables database calls only during the macro execution, clears
  the cache, evaluates each formula text, writes plain values, then disables
  database calls again.
- `ClearGLApiFormulas` removes any live formulas from result cells and replaces
  them with `#GLAPI_OFF`.
- `DisableGLApi` turns database calls off again and closes the ODBC connection.