tradon/notes/accounting/excel_api/CLIENT_DELIVERY_README.md

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:

(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.