Zinform - User contributions [en-gb]

Zinform 6 Software

2026-03-16T19:52:09Z

Mike:

== Current Downloads ==
[https://dl.zinform.co.nz/ZinformAccounts_6_1_16_2.exe Zinform 6 (6.1.16.2)]

[https://dl.zinform.co.nz/ZinformAccountsSetup_5.3.40.exe Zinform 5 (5.3.40)]

'''Important:''' These two versions rely on each other. Once Z6.1.16.2 has been run it '''will require''' Z5.3.40 to operate correctly.

== Previous Downloads ==
[https://dl.zinform.co.nz/ZinformAccounts_6_1_14_1.exe Zinforrm 6 (6.1.14.1)]

[https://dl.zinform.co.nz/ZinformAccountsSetup_5.3.38.exe Zinform 5 (5.3.38)]

[https://dl.zinform.co.nz/emPOWER_5_3_24.zip emPOWER (5.3.24)]

Current Release Features

2026-03-12T20:57:52Z

Mike:

== Release Details ==

'''Current Release:''' 6.3.0.0

=== Version 6.3.0.0 ===

* '''Web Services and Scheduled Services Module''' (New):
** Full RESTful data API (''GET/POST/PUT/DELETE'') with configurable entity endpoints
** Scripted API system — custom C# endpoints compiled at runtime via Roslyn
** Scheduled background services with orchestrated lifecycle management
** Subscriber access control and per-endpoint authentication
** Anonymous endpoint support for public-facing integrations
** Built on .NET 10
** See [[#Web Services and Scheduled Services]] section below for full details

=== Version 6.2.0.2 ===

* '''Department Enhancements''': Improved department code handling and error reporting
* '''BCTI Document Function''': Updated document function to better handle Buyer Created Tax Invoice generation
* '''Chromium Removal''': Removed embedded Chromium dependency; critical software versions bumped

=== Version 6.2.0.0 ===

* '''SyncFusion Removal''': Removed SyncFusion component library
** Migrated GridView controls to WPF DataGrid
** Integrated [https://github.com/lepoco/wpfui WPFUI] library for modern UI components
** Updated NumberBox usage to align with new library
** Updated GemBox license keys
* '''Debug Email Mode''': Added debug email mode for troubleshooting email delivery
* '''Department User Fields''': Additional user fields available at department level
* '''UI and Wizard Options''': General UI and wizard option refinements
* '''Supplier Category/Type Support''': Added supplier category and type classification with UI improvements
* '''Other Party Contact Methods''': Refactored Other Party contact methods with ComboBox support
* '''Statement Aging''': Refactored statement aging logic for out-of-period allocations
* '''Registry Item Handling''': Refactored AddRegistryItem to return BoolReturn with status for improved error handling

=== Version 6.1.16.3 Pre Release ===

* '''Graph Updates''': Updated graph components
* '''Warning Cleanup''': General codebase warning cleanup and tidy-up

=== Version 6.1.16.2 ===

* [[File:TriButtonZinMsgBox.png|thumb|170px]]
'''ZinMessageBox''': Added custom message box component for runtime scripting to allow for custom 'tri button' layouts and new custom icons.
* '''Document Scripting''': Message box now available to runtime document scripts via Business Layer
* General tweaks and refinements
* '''Statement Generation Improvements''':
** Major SQL and CTE optimizations for faster, more accurate financial statements
** Fixed transaction allocation logic to properly handle bidirectional allocations
** Improved running balance calculations for aged arrears
** Enhanced deduplication strategies to prevent duplicate transactions in statements
** Better handling of current month transactions vs historical aging buckets

=== Version 6.1.16.1 ===

* '''Progress Bar Improvements''': Updated progress bar to handle child loops and display status correctly for better user feedback during long operations (Allows for more complex looping within runtime scripting)

=== Version 6.1.16.0 ===

* '''Departments Launch''': Added department management functionality (moved away from Zinform 5)
* '''BCTI Enhancements''': Changes to enhance BCTI (Buyer Created Tax Invoice) Generation
* '''Document Functions''': Updated and improved document functions
* '''Customer/Supplier Display Fixes''': Fixed display of customers and suppliers for statements and documents
* '''License Management Fix''': Fixed opening organization license on first requirement
* '''Connection Handling''': Fixed cancel connection functionality

=== Version 6.1.15.0 ===

* '''General Document Wizard Enhancements''': Added features to publish general documents with improved functionality
* '''Invoice Statement Support''': Updates to support comprehensive invoice statements
* '''Code Cleanup''': Tidied warnings throughout the codebase

=== Version 6.1.14.1 Release Features: ===

Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')

Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

== Web Services and Scheduled Services ==

ASP.NET Core Web API built on .NET 10, hosted as a Windows Service, providing external API access to Zinform data and a runtime scripting platform for custom integrations and scheduled tasks.

=== Data API ===

Full CRUD RESTful API with configurable entity endpoints:

* '''Entity Endpoints''': Expose any Zinform database entity via configurable route aliases (e.g. /api/data/customers, /api/data/invoices)
* '''Per-Endpoint Access Control''': Each endpoint individually configurable for Read, Create, Update, and Delete permissions
* '''Paging and Sorting''': Built-in pagination with configurable max page sizes, multi-field ordering (ascending/descending)
* '''Filtering''': Query string filters (e.g. ?filter.Name=Smith) and advanced POST query with operators including eq, neq, gt, gte, lt, lte, contains, startswith, endswith, between, in, isnull, isnotnull
* '''Nested Filter Logic''': AND/OR filter groups with nested sub-groups for complex queries
* '''Field Selection''': Request specific fields to reduce payload size
* '''Endpoint Discovery''': GET /api/data lists all available enabled endpoints with their permissions

=== Scripted API ===

Custom API endpoints powered by Roslyn C# runtime compilation:

* '''Custom Endpoints''': Define custom routes (e.g. /api/script/myintegration) with C# script bodies compiled and cached at runtime
* '''ImportScripter Pattern''': Scripts follow the same ImportScripter class pattern used in the Zinform desktop application for consistency
* '''Full Business Layer Access''': Scripts receive a BusinessLayerMain instance providing full access to all Zinform business logic
* '''Request/Response Model''': Custom ZinHttpRequest / ZinHttpResponse objects with access to query parameters, JSON body, headers, and authenticated user identity
* '''Per-Method Control''': Each scripted endpoint configurable for specific HTTP methods (GET, POST, PUT, DELETE)
* '''Script Caching''': Compiled scripts are cached with SHA256 hash-based invalidation — scripts recompile automatically when updated
* '''Endpoint Discovery''': GET /api/script lists all available scripted endpoints with descriptions

=== Script Execution API ===

Direct script execution endpoint for ad-hoc or remote scripting:

* '''Remote Script Execution''': POST C# scripts to /api/script/execute for server-side execution
* '''ZinParameters Support''': Pass key/value parameters to scripts, matching the desktop runner interface
* '''Timeout Control''': Configurable execution timeout (up to 5 minutes) with cancellation support
* '''Structured Results''': Returns success/failure status, output, error detail, and execution duration

=== Scheduled Background Services ===

Orchestrated background task system driven by database-stored service definitions:

* '''Service Orchestrator''': Master hosted service that manages the lifecycle of all background workers
* '''Dynamic Configuration''': Service definitions stored in the database — add, update, enable, or disable services without restarting the application
* '''Automatic Change Detection''': Polls DB every 60 seconds for definition changes; workers are started, stopped, or restarted as needed using RowVersion tracking
* '''Roslyn Script Execution''': Each service runs a C# script body with full Business Layer access
* '''Run Tracking''': Automatic tracking of run count, fail count, last run time, last output/error, and next scheduled run
* '''User Data Fields''': Five custom user data fields (User0-User4) per service definition for script-accessible configuration

'''Trigger Types:'''

* '''Timer Trigger''': Configurable interval-based triggers with:
** Interval in seconds (e.g. every 5 minutes)
** Optional initial delay before first execution
** Business hours window (e.g. only fire between 8am-6pm)
* '''Folder Watch Trigger''': Monitor a folder for new or changed files and trigger service execution automatically
* '''Email Trigger''': Monitor an inbox for incoming emails and trigger service execution on receipt

=== Authentication ===

Multi-provider authentication supporting:

* '''Local JWT''': Username/password authentication via /api/auth/login
* '''Microsoft Entra ID''': Azure AD / Entra ID OAuth2
* '''Google OAuth''': Google account authentication
* '''Generic OAuth''': Configurable custom OAuth2 provider
* '''API Key''': Static API key authentication via X-Api-Key header for legacy/simple integrations
* '''Anonymous''': Unauthenticated access for public endpoints
* '''Per-Endpoint Auth Schemes''': Each data and scripted endpoint can specify which authentication schemes are accepted

=== Subscriber Access Control ===

* '''Subscriber Middleware''': Validates subscriber keys and stores subscriber context for downstream use
* '''Per-Endpoint Subscriber Permissions''': Subscribers can be granted access to specific data endpoints and scripted endpoints independently
* '''Encrypted Subscriber Keys''': Subscriber authentication keys with encryption support

=== Administration ===

* '''Admin Console''': Localhost-only admin interface for service management
* '''Swagger / OpenAPI''': Full Swagger UI documentation with all authentication schemes documented
* '''Service Definition Admin''': Admin UI in Zinform desktop for managing service definitions, scripted endpoints, API endpoints, and request metrics
* '''Request Metrics''': Built-in request tracking for monitoring API activity
* '''Windows Service Hosting''': Runs as a Windows Service or under IIS

=== Coming Soon: ===

Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Current Release Features

2026-03-12T20:56:59Z

Mike:

== Release Details ==
'''Current Release:''' 6.1.16.2

=== Version 6.1.16.2 ===

* [[File:TriButtonZinMsgBox.png|thumb|170x170px]]'''ZinMessageBox''': Added custom message box component for runtime scripting to allow for custom 'tri button' layouts and new custom icons.
* '''Document Scripting''': Message box now available to runtime document scripts via Business Layer
* General tweaks and refinements
* '''Statement Generation Improvements''':
** Major SQL and CTE optimizations for faster, more accurate financial statements
** Fixed transaction allocation logic to properly handle bidirectional allocations
** Improved running balance calculations for aged arrears
** Enhanced deduplication strategies to prevent duplicate transactions in statements
** Better handling of current month transactions vs historical aging buckets

=== Version 6.1.16.1 ===

* '''Progress Bar Improvements''': Updated progress bar to handle child loops and display status correctly for better user feedback during long operations (Allows for more complex looping within runtime scripting)

=== Version 6.1.16.0 ===

* '''Departments Launch''': Added department management functionality (moved away from Zinform 5)
* '''BCTI Enhancements''': Changes to enhance BCTI (Buyer Created Tax Invoice) Generation
* '''Document Functions''': Updated and improved document functions
* '''Customer/Supplier Display Fixes''': Fixed display of customers and suppliers for statements and documents
* '''License Management Fix''': Fixed opening organization license on first requirement
* '''Connection Handling''': Fixed cancel connection functionality

=== Version 6.1.15.0 ===

* '''General Document Wizard Enhancements''': Added features to publish general documents with improved functionality
* '''Invoice Statement Support''': Updates to support comprehensive invoice statements
* '''Code Cleanup''': Tidied warnings throughout the codebase

=== Version 6.1.14.1 Release Features: ===
Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')
Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

=== Coming Soon: ===
Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Current Release Features

2026-03-12T20:47:03Z

Mike:

== Release Details ==

'''Current Release:''' 6.3.0.0

=== Version 6.3.0.0 ===

* '''Web Services & Scheduled Services Module''' (New):
** Full RESTful data API (''GET/POST/PUT/DELETE'') with configurable entity endpoints
** Scripted API system — custom C# endpoints compiled at runtime via Roslyn
** Scheduled background services with orchestrated lifecycle management
** Subscriber access control and per-endpoint authentication
** Anonymous endpoint support for public-facing integrations
** Built on .NET 10
** See [[#Web Services & Scheduled Services]] section below for full details

=== Version 6.2.0.2 ===

* '''Department Enhancements''': Improved department code handling and error reporting
* '''BCTI Document Function''': Updated document function to better handle Buyer Created Tax Invoice generation
* '''Chromium Removal''': Removed embedded Chromium dependency; critical software versions bumped

=== Version 6.2.0.0 ===

* '''SyncFusion Removal''': Removed SyncFusion component library
** Migrated GridView controls to WPF DataGrid
** Integrated [https://github.com/lepoco/wpfui WPFUI] library for modern UI components
** Updated NumberBox usage to align with new library
** Updated GemBox license keys
* '''Debug Email Mode''': Added debug email mode for troubleshooting email delivery
* '''Department User Fields''': Additional user fields available at department level
* '''UI & Wizard Options''': General UI and wizard option refinements
* '''Supplier Category/Type Support''': Added supplier category and type classification with UI improvements
* '''Other Party Contact Methods''': Refactored Other Party contact methods with ComboBox support
* '''Statement Aging''': Refactored statement aging logic for out-of-period allocations
* '''Registry Item Handling''': Refactored AddRegistryItem to return BoolReturn with status for improved error handling

=== Version 6.1.16.3 Pre Release ===

* '''Graph Updates''': Updated graph components
* '''Warning Cleanup''': General codebase warning cleanup and tidy-up

=== Version 6.1.16.2 ===

* [[File:TriButtonZinMsgBox.png|thumb|170px]]
'''ZinMessageBox''': Added custom message box component for runtime scripting to allow for custom 'tri button' layouts and new custom icons.
* '''Document Scripting''': Message box now available to runtime document scripts via Business Layer
* General tweaks and refinements
* '''Statement Generation Improvements''':
** Major SQL and CTE optimizations for faster, more accurate financial statements
** Fixed transaction allocation logic to properly handle bidirectional allocations
** Improved running balance calculations for aged arrears
** Enhanced deduplication strategies to prevent duplicate transactions in statements
** Better handling of current month transactions vs historical aging buckets

=== Version 6.1.16.1 ===

* '''Progress Bar Improvements''': Updated progress bar to handle child loops and display status correctly for better user feedback during long operations (Allows for more complex looping within runtime scripting)

=== Version 6.1.16.0 ===

* '''Departments Launch''': Added department management functionality (moved away from Zinform 5)
* '''BCTI Enhancements''': Changes to enhance BCTI (Buyer Created Tax Invoice) Generation
* '''Document Functions''': Updated and improved document functions
* '''Customer/Supplier Display Fixes''': Fixed display of customers and suppliers for statements and documents
* '''License Management Fix''': Fixed opening organization license on first requirement
* '''Connection Handling''': Fixed cancel connection functionality

=== Version 6.1.15.0 ===

* '''General Document Wizard Enhancements''': Added features to publish general documents with improved functionality
* '''Invoice Statement Support''': Updates to support comprehensive invoice statements
* '''Code Cleanup''': Tidied warnings throughout the codebase

=== Version 6.1.14.1 Release Features: ===

Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')

Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

== Web Services & Scheduled Services ==

ASP.NET Core Web API built on .NET 10, hosted as a Windows Service, providing external API access to Zinform data and a runtime scripting platform for custom integrations and scheduled tasks.

=== Data API ===

Full CRUD RESTful API with configurable entity endpoints:

* '''Entity Endpoints''': Expose any Zinform database entity via configurable route aliases (e.g. <code>/api/data/customers</code>, <code>/api/data/invoices</code>)
* '''Per-Endpoint Access Control''': Each endpoint individually configurable for Read, Create, Update, and Delete permissions
* '''Paging & Sorting''': Built-in pagination with configurable max page sizes, multi-field ordering (ascending/descending)
* '''Filtering''': Query string filters (<code>?filter.Name=Smith</code>) and advanced POST query with operators including eq, neq, gt, gte, lt, lte, contains, startswith, endswith, between, in, isnull, isnotnull
* '''Nested Filter Logic''': AND/OR filter groups with nested sub-groups for complex queries
* '''Field Selection''': Request specific fields to reduce payload size
* '''Endpoint Discovery''': <code>GET /api/data</code> lists all available enabled endpoints with their permissions

=== Scripted API ===

Custom API endpoints powered by Roslyn C# runtime compilation:

* '''Custom Endpoints''': Define custom routes (e.g. <code>/api/script/myintegration</code>) with C# script bodies compiled and cached at runtime
* '''ImportScripter Pattern''': Scripts follow the same <code>ImportScripter</code> class pattern used in the Zinform desktop application for consistency
* '''Full Business Layer Access''': Scripts receive a <code>BusinessLayerMain</code> instance providing full access to all Zinform business logic
* '''Request/Response Model''': Custom <code>ZinHttpRequest</code> / <code>ZinHttpResponse</code> objects with access to query parameters, JSON body, headers, and authenticated user identity
* '''Per-Method Control''': Each scripted endpoint configurable for specific HTTP methods (GET, POST, PUT, DELETE)
* '''Script Caching''': Compiled scripts are cached with SHA256 hash-based invalidation — scripts recompile automatically when updated
* '''Endpoint Discovery''': <code>GET /api/script</code> lists all available scripted endpoints with descriptions

=== Script Execution API ===

Direct script execution endpoint for ad-hoc or remote scripting:

* '''Remote Script Execution''': POST C# scripts to <code>/api/script/execute</code> for server-side execution
* '''ZinParameters Support''': Pass key/value parameters to scripts, matching the desktop runner interface
* '''Timeout Control''': Configurable execution timeout (up to 5 minutes) with cancellation support
* '''Structured Results''': Returns success/failure status, output, error detail, and execution duration

=== Scheduled Background Services ===

Orchestrated background task system driven by database-stored service definitions:

* '''Service Orchestrator''': Master hosted service that manages the lifecycle of all background workers
* '''Dynamic Configuration''': Service definitions stored in the database — add, update, enable, or disable services without restarting the application
* '''Automatic Change Detection''': Polls DB every 60 seconds for definition changes; workers are started, stopped, or restarted as needed using RowVersion tracking
* '''Roslyn Script Execution''': Each service runs a C# script body with full Business Layer access
* '''Run Tracking''': Automatic tracking of run count, fail count, last run time, last output/error, and next scheduled run
* '''User Data Fields''': Five custom user data fields (User0–User4) per service definition for script-accessible configuration

'''Trigger Types:'''

* '''Timer Trigger''': Configurable interval-based triggers with:
** Interval in seconds (e.g. every 5 minutes)
** Optional initial delay before first execution
** Business hours window (e.g. only fire between 8am–6pm)
* '''Folder Watch Trigger''': Monitor a folder for new or changed files and trigger service execution automatically
* '''Email Trigger''': Monitor an inbox for incoming emails and trigger service execution on receipt

=== Authentication ===

Multi-provider authentication supporting:

* '''Local JWT''': Username/password authentication via <code>/api/auth/login</code>
* '''Microsoft Entra ID''': Azure AD / Entra ID OAuth2
* '''Google OAuth''': Google account authentication
* '''Generic OAuth''': Configurable custom OAuth2 provider
* '''API Key''': Static API key authentication via <code>X-Api-Key</code> header for legacy/simple integrations
* '''Anonymous''': Unauthenticated access for public endpoints
* '''Per-Endpoint Auth Schemes''': Each data and scripted endpoint can specify which authentication schemes are accepted

=== Subscriber Access Control ===

* '''Subscriber Middleware''': Validates subscriber keys and stores subscriber context for downstream use
* '''Per-Endpoint Subscriber Permissions''': Subscribers can be granted access to specific data endpoints and scripted endpoints independently
* '''Encrypted Subscriber Keys''': Subscriber authentication keys with encryption support

=== Administration ===

* '''Admin Console''': Localhost-only admin interface for service management
* '''Swagger / OpenAPI''': Full Swagger UI documentation with all authentication schemes documented
* '''Service Definition Admin''': Admin UI in Zinform desktop for managing service definitions, scripted endpoints, API endpoints, and request metrics
* '''Request Metrics''': Built-in request tracking for monitoring API activity
* '''Windows Service Hosting''': Runs as a Windows Service or under IIS

=== Coming Soon: ===

Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Current Release Features

2026-01-20T20:20:43Z

Mike:

Current Release Features

2026-01-20T20:12:47Z

Mike:

== Release Details ==
'''Current Release:''' 6.1.16.2

=== Version 6.1.16.2 ===

* [[File:TriButtonZinMsgBox.png|thumb|170x170px]]'''ZinMessageBox''': Added custom message box component for runtime scripting to allow for custom 'tri button' layouts and new custom icons.
* '''Document Scripting''': Message box now available to runtime document scripts via Business Layer
* General tweaks and refinements
* Enhanced SQL and CTE's for pulling data for Statements on GetMonthlyRunningTransactions2 with improvement on speed and data returned including details for allocations future and past dated.

=== Version 6.1.16.1 ===

* '''Progress Bar Improvements''': Updated progress bar to handle child loops and display status correctly for better user feedback during long operations (Allows for more complex looping within runtime scripting)

=== Version 6.1.16.0 ===

* '''Departments Launch''': Added department management functionality (moved away from Zinform 5)
* '''BCTI Enhancements''': Changes to enhance BCTI (Buyer Created Tax Invoice) Generation
* '''Document Functions''': Updated and improved document functions
* '''Customer/Supplier Display Fixes''': Fixed display of customers and suppliers for statements and documents
* '''License Management Fix''': Fixed opening organization license on first requirement
* '''Connection Handling''': Fixed cancel connection functionality

=== Version 6.1.15.0 ===

* '''General Document Wizard Enhancements''': Added features to publish general documents with improved functionality
* '''Invoice Statement Support''': Updates to support comprehensive invoice statements
* '''Code Cleanup''': Tidied warnings throughout the codebase

=== Version 6.1.14.1 Release Features: ===
Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')
Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

=== Coming Soon: ===
Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

File:TriButtonZinMsgBox.png

2026-01-20T20:03:55Z

Mike: TriButtonZinMsgBox

== Summary ==
TriButtonZinMsgBox

Current Release Features

2026-01-20T20:02:57Z

Mike: Updated

== Release Details ==
'''Current Release:''' 6.1.16.2

=== Version 6.1.16.2 ===

* '''ZinMessageBox''': Added custom message box component for runtime scripting to allow for custom 'tri button' layouts and new custom icons.
* '''Document Scripting''': Message box now available to runtime document scripts via Business Layer
* General tweaks and refinements
* Enhanced SQL and CTE's for pulling data for Statements on GetMonthlyRunningTransactions2 with improvement on speed and data returned including details for allocations future and past dated.

=== Version 6.1.16.1 ===

* '''Progress Bar Improvements''': Updated progress bar to handle child loops and display status correctly for better user feedback during long operations (Allows for more complex looping within runtime scripting)

=== Version 6.1.16.0 ===

* '''Departments Launch''': Added department management functionality (moved away from Zinform 5)
* '''BCTI Enhancements''': Changes to enhance BCTI (Buyer Created Tax Invoice) Generation
* '''Document Functions''': Updated and improved document functions
* '''Customer/Supplier Display Fixes''': Fixed display of customers and suppliers for statements and documents
* '''License Management Fix''': Fixed opening organization license on first requirement
* '''Connection Handling''': Fixed cancel connection functionality

=== Version 6.1.15.0 ===

* '''General Document Wizard Enhancements''': Added features to publish general documents with improved functionality
* '''Invoice Statement Support''': Updates to support comprehensive invoice statements
* '''Code Cleanup''': Tidied warnings throughout the codebase

=== Version 6.1.14.1 Release Features: ===
Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')
Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

=== Coming Soon: ===
Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Current Release Features

2026-01-20T19:49:13Z

Mike:

== Release Details ==
'''Current Release:''' 6.1.16.2

=== Current Release Features: ===
Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')
Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

=== Coming Soon: ===
Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Mike:

{{ScriptingNav}}

== Overview ==

The Invoice PDF Import System provides automated processing of supplier invoices using AI-powered document analysis. The system extracts invoice data from PDF files and creates AP (Accounts Payable) invoices in the accounting system with minimal manual intervention.

== Key Features ==

* '''Multi-file processing''': Process multiple PDF invoices in a single operation
* '''AI-powered extraction''': Uses vision AI models to read and interpret invoice documents
* '''Invoice type detection''': Automatically distinguishes between Service and Parts invoices
* '''Data validation''': Performs mathematical verification of totals and line items
* '''Automated invoice creation''': Generates complete AP invoices with line items
* '''Batch processing''': Optional batch creation for grouping related invoices

== Invoice Types ==

=== Service Invoices ===

Service invoices contain work performed on specific vehicles or equipment. Key characteristics:

* Include vehicle/equipment identifiers (Serial Number, Make, Model, Meter Reading)
* Contain detailed service description text
* Service description may span multiple pages
* Serial Number is used as the Department identifier

=== Parts Invoices ===

Parts invoices list individual components or products purchased. Key characteristics:

* Focus on part numbers and quantities
* No vehicle-specific information
* Line items include Part Number + Description format

== Data Extraction ==

The system extracts the following information from invoice PDFs:

=== Header Information ===

* Invoice Type (Service/Parts)
* Invoice Number
* Invoice Date
* Order Number (Sales Order for Parts, Purchase Order for Service)
* Serial Number (Service invoices only)
* Customer Reference Number
* Service Description (Service invoices only)

=== Line Items ===

For each line on the invoice:

* Description (Part Number + Description for parts)
* Quantity
* Unit Price
* Extended Total (line total)

=== Financial Totals ===

* Net Subtotal (excluding tax)
* Total GST/Tax
* Total Amount (including tax)

== AI Model Configuration ==

The system supports multiple AI vision providers:

* '''Anthropic''' (default): Claude vision models
* '''OpenAI''': GPT vision models

Configuration parameters:

* <code>AIModel</code>: Model identifier string
* <code>AIModelId</code>: Specific model version
* <code>AIVisionEnabled</code>: Enable/disable AI processing
* <code>AIApiKey</code>: Encrypted API key for authentication

== Data Validation ==

The extraction process includes built-in validation:

=== OCR Accuracy ===

* Disambiguates common character confusions (Z/2, O/0, I/1/l, S/5, G/6)
* Reads all pages of multi-page invoices

=== Mathematical Verification ===

* Verifies sum of line items matches subtotal (within 0.02 tolerance)
* Confirms GST calculation (≈ 15% of subtotal)
* Validates total = subtotal + GST

== Invoice Creation Process ==

=== Line Item Processing ===

'''For Service Invoices:'''

* Creates a nominal line item with service description
* Adds offsetting line item for calculation purposes
* Uses extracted line items for parts/materials used

'''For Parts Invoices:'''

* Converts each extracted line item to invoice row
* Calculates GST inclusive totals
* Computes unit prices from extended totals

=== Department Assignment ===

* Service invoices: Uses Serial Number as Department
* Parts invoices: Department left blank or as specified

=== Financial Calculations ===

All amounts are stored GST exclusive with separate tax tracking:

<pre>
GST Exc Total = Line Extended Total
Total With GST = GST Exc Total × 1.15
GST Amount = Total With GST - GST Exc Total
Unit Price = GST Exc Total ÷ Quantity
</pre>

=== Invoice Record Creation ===

Creates AP invoice with:

* Transaction Type: APINV
* Vendor/Supplier: OtherPartyId (default: "5521")
* Location: Configurable (default: "Misc")
* Payment Date: 20th of month following invoice date
* Reference: Invoice Number from PDF
* Line items with all pricing and tax details

=== Batch Processing ===

Optional batch creation groups related invoices:

* Batch ID defaults to supplier/vendor ID
* Includes batch comments for tracking
* Supports recurring batch patterns

== Error Handling ==

The system includes comprehensive error handling:

=== PDF Processing Errors ===

* Invalid or corrupted PDF files
* Missing or unreadable pages
* Unsupported PDF formats

=== Data Extraction Errors ===

* No invoice detected in PDF
* Invalid JSON response from AI model
* Missing required fields
* Multiple invoices in single PDF (selects largest by subtotal)

=== Invoice Creation Errors ===

* Invalid supplier/vendor ID
* Missing required master data (items, departments)
* Transaction validation failures
* Batch creation conflicts

== Usage Guidelines ==

=== File Selection ===

# Use the file picker dialog to select one or more PDF files
# Only PDF files are supported
# Multiple files can be processed in sequence

=== Best Practices ===

* Ensure invoice PDFs are clear and readable
* Verify supplier master data exists before import
* Check that department codes (serial numbers) are valid
* Review created invoices for accuracy
* Use batch processing for related invoices from same supplier

=== Post-Import Actions ===

* Review generated invoices in the system
* Verify line item details and totals
* Confirm department assignments
* Check payment dates
* Approve batches when ready for posting

== Technical Architecture ==

=== Components ===

* '''Import Scripter''': Main orchestration class
* '''AI Vision Service''': PDF analysis and data extraction
* '''Invoice Functions''': Business logic for invoice creation
* '''Transaction Functions''': Database persistence layer

=== Data Flow ===

<pre>
PDF File → AI Vision Analysis → JSON Extraction →
Data Validation → Invoice Row Creation →
AP Invoice Generation → Database Persistence
</pre>

=== Performance Considerations ===

* Batch loading of items and departments
* Dictionary-based lookups for master data
* Minimal database queries during processing
* Asynchronous AI processing support

== Configuration Requirements ==

=== System Parameters ===

* AI API credentials (encrypted)
* Default supplier/vendor ID
* Default location ID
* Invoice numbering scheme
* Tax calculation rules (GST rate)
* Payment terms (default 20 days after month-end)

=== Master Data Prerequisites ===

* Supplier/vendor records
* Item master data (for parts)
* Department codes (for service invoices)
* Location codes
* Transaction type definitions

== Integration Points ==

The Invoice PDF Import integrates with:

* '''Item Management''': Item lookup and validation
* '''Department Management''': Department code resolution
* '''Transaction Processing''': Invoice creation and posting
* '''Batch Management''': Batch header creation and tracking
* '''AI Vision Services''': External API for document analysis

== See Also ==

* [[Import Scripting]]
* [[Transaction Processing]]
* [[AI Vision Services]]

[[Category:Scripting]]
[[Category:Import Functions]]
[[Category:AI Features]]

2025-11-10T03:06:50Z

Mike:

Import File Scripting

2025-11-10T03:04:29Z

Mike:

= File Import System Documentation =

This page documents the file import infrastructure in ZinformAccounts, providing templates and patterns for implementing various file format imports including CSV, XML, Excel, JSON, and other data sources.

== Overview ==

The import system provides a flexible framework for processing external data files into the ZinformAccounts database. All imports follow consistent patterns for error handling, validation, and transaction management.

== Supported File Formats ==

=== Excel Files (.xlsx, .xls) ===

Using GemBox.Spreadsheet for Excel file processing:

<syntaxhighlight lang="csharp">
using GemBox.Spreadsheet;

public List<T> ImportExcel<T>(string filePath) where T : new()
{
var workbook = ExcelFile.Load(filePath);
var worksheet = workbook.Worksheets[0];
var results = new List<T>();

// Get header row to map columns
int headerRowIndex = 0;
var headers = new Dictionary<int, string>();

for (int col = 0; col < worksheet.CalculateMaxUsedColumns(); col++)
{
var headerValue = worksheet.Cells[headerRowIndex, col].Value?.ToString();
if (!string.IsNullOrEmpty(headerValue))
headers[col] = headerValue;
}

// Process data rows
for (int row = headerRowIndex + 1; row < worksheet.Rows.Count; row++)
{
var item = MapRowToObject<T>(worksheet.Rows[row], headers);
if (item != null)
results.Add(item);
}

return results;
}
</syntaxhighlight>

=== CSV Files ===

Using CsvHelper for CSV processing with flexible date handling:

<syntaxhighlight lang="csharp">
using CsvHelper;
using CsvHelper.Configuration;
using System.Globalization;

public List<T> ImportCsv<T>(string filePath, bool hasHeader = true)
{
var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
HasHeaderRecord = hasHeader,
MissingFieldFound = null,
BadDataFound = null,
TrimOptions = TrimOptions.Trim
};

using var reader = new StreamReader(filePath);
using var csv = new CsvReader(reader, config);

// Register custom type converters for dates
csv.Context.TypeConverterCache.AddConverter<DateTime>(new FlexibleDateConverter());

return csv.GetRecords<T>().ToList();
}

public class FlexibleDateConverter : ITypeConverter
{
private readonly string[] _dateFormats = new[]
{
"dd/MM/yyyy",
"d/M/yyyy",
"yyyy-MM-dd",
"dd-MM-yyyy",
"dd.MM.yyyy"
};

public object ConvertFromString(string text, IReaderRow row, MemberMapData memberMapData)
{
if (DateTime.TryParseExact(text, _dateFormats,
CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
return date;

throw new InvalidOperationException($"Cannot parse date: {text}");
}
}
</syntaxhighlight>

=== XML Files ===

<syntaxhighlight lang="csharp">
using System.Xml.Linq;
using System.Xml.Serialization;

// Method 1: Using XDocument for flexible parsing
public List<T> ImportXmlFlexible<T>(string filePath, Func<XElement, T> mapper)
{
var doc = XDocument.Load(filePath);
var results = new List<T>();

foreach (var element in doc.Descendants("Record"))
{
var item = mapper(element);
if (item != null)
results.Add(item);
}

return results;
}

// Method 2: Using XML Serialization for strongly-typed objects
public T ImportXmlSerialized<T>(string filePath) where T : class
{
var serializer = new XmlSerializer(typeof(T));
using var stream = File.OpenRead(filePath);
return serializer.Deserialize(stream) as T;
}
</syntaxhighlight>

=== JSON Files ===

<syntaxhighlight lang="csharp">
using Newtonsoft.Json;

public T ImportJson<T>(string filePath)
{
var json = File.ReadAllText(filePath);
return JsonConvert.DeserializeObject<T>(json);
}

public List<T> ImportJsonArray<T>(string filePath)
{
var json = File.ReadAllText(filePath);
return JsonConvert.DeserializeObject<List<T>>(json) ?? new List<T>();
}
</syntaxhighlight>

=== Tab-Delimited and Fixed-Width Files ===

<syntaxhighlight lang="csharp">
// Tab-delimited files
public List<Dictionary<string, string>> ImportTabDelimited(string filePath)
{
var lines = File.ReadAllLines(filePath);
if (lines.Length == 0) return new List<Dictionary<string, string>>();

var headers = lines[0].Split('\t');
var results = new List<Dictionary<string, string>>();

for (int i = 1; i < lines.Length; i++)
{
var values = lines[i].Split('\t');
var record = new Dictionary<string, string>();

for (int j = 0; j < Math.Min(headers.Length, values.Length); j++)
{
record[headers[j]] = values[j];
}

results.Add(record);
}

return results;
}

// Fixed-width files
public class FixedWidthField
{
public string Name { get; set; }
public int StartPosition { get; set; }
public int Length { get; set; }
public Type DataType { get; set; }
}

public List<Dictionary<string, object>> ImportFixedWidth(string filePath, List<FixedWidthField> fields)
{
var lines = File.ReadAllLines(filePath);
var results = new List<Dictionary<string, object>>();

foreach (var line in lines)
{
var record = new Dictionary<string, object>();

foreach (var field in fields)
{
if (line.Length >= field.StartPosition + field.Length)
{
var value = line.Substring(field.StartPosition, field.Length).Trim();
record[field.Name] = ConvertToType(value, field.DataType);
}
}

results.Add(record);
}

return results;
}
</syntaxhighlight>

== Generic Import Script Template ==

<syntaxhighlight lang="csharp">
using System;
using System.IO;
using System.Data;
using System.Text;
using System.Windows;
using System.Linq;
using System.Collections.Generic;
using ZinBusinessLayer;
using ZinDATA;
using ZinBusinessLayer.Models;

public class GenericImportScripter
{
private BusinessLayerMain zinBL;
private readonly List<string> errors = new List<string>();
private readonly List<string> warnings = new List<string>();

public bool Main(BusinessLayerMain bl, ZinParameters parameters, ZinParameters returnParameters)
{
zinBL = bl;

try
{
// Get parameters
var filename = parameters.GetItemString("FileName");
var importType = parameters.GetItemString("ImportType");
var validateOnly = parameters.GetItemBool("ValidateOnly") ?? false;

// Determine file type and import
var extension = Path.GetExtension(filename).ToLower();
dynamic data = null;

switch (extension)
{
case ".xlsx":
case ".xls":
data = ImportExcel(filename);
break;
case ".csv":
data = ImportCsv(filename);
break;
case ".xml":
data = ImportXml(filename);
break;
case ".json":
data = ImportJson(filename);
break;
case ".txt":
data = DetermineAndImportText(filename);
break;
default:
throw new NotSupportedException($"File type {extension} is not supported");
}

// Validate data
if (!ValidateData(data))
{
returnParameters.SetItem("Errors", string.Join("\n", errors));
return false;
}

// Process data if not validation only
if (!validateOnly)
{
return ProcessData(data, importType);
}

returnParameters.SetItem("ValidationResult", "Data validated successfully");
return true;
}
catch (Exception ex)
{
returnParameters.SetItem("Error", $"Import failed: {ex.Message}");
LogError($"Import failed: {ex.ToString()}");
return false;
}
}

private bool ValidateData(dynamic data)
{
// Implement validation logic based on data type
if (data == null || (data is ICollection coll && coll.Count == 0))
{
errors.Add("No data found in import file");
return false;
}

// Add custom validation rules here
return errors.Count == 0;
}

private bool ProcessData(dynamic data, string importType)
{
using (var transaction = zinBL.BeginTransaction())
{
try
{
int recordsProcessed = 0;
int recordsFailed = 0;

foreach (var record in data)
{
try
{
ProcessRecord(record, importType);
recordsProcessed++;
}
catch (Exception ex)
{
recordsFailed++;
LogError($"Failed to process record: {ex.Message}");

// Optionally continue or rollback on error
if (recordsFailed > 10) // Threshold for failures
{
transaction.Rollback();
return false;
}
}
}

transaction.Commit();
LogInfo($"Import completed: {recordsProcessed} records processed, {recordsFailed} failed");
return recordsFailed == 0;
}
catch (Exception ex)
{
transaction.Rollback();
LogError($"Transaction failed: {ex.Message}");
return false;
}
}
}

private void ProcessRecord(dynamic record, string importType)
{
// Implement record processing based on import type
switch (importType)
{
case "Invoice":
ProcessInvoiceRecord(record);
break;
case "Payment":
ProcessPaymentRecord(record);
break;
case "Customer":
ProcessCustomerRecord(record);
break;
case "Item":
ProcessItemRecord(record);
break;
default:
throw new NotSupportedException($"Import type {importType} is not supported");
}
}

private void LogError(string message)
{
errors.Add(message);
zinBL.LoggingFunctions?.LogError(message);
}

private void LogInfo(string message)
{
zinBL.LoggingFunctions?.LogInfo(message);
}
}
</syntaxhighlight>

== Import Mapping Configuration ==

<syntaxhighlight lang="csharp">
public class ImportMapping
{
public string SourceField { get; set; }
public string TargetField { get; set; }
public Type DataType { get; set; }
public bool Required { get; set; }
public object DefaultValue { get; set; }
public Func<object, object> Transform { get; set; }
public Func<object, bool> Validate { get; set; }
}

public class ImportConfiguration
{
public List<ImportMapping> Mappings { get; set; } = new List<ImportMapping>();
public bool SkipEmptyRows { get; set; } = true;
public bool TrimValues { get; set; } = true;
public int HeaderRow { get; set; } = 0;
public int DataStartRow { get; set; } = 1;
public string DateFormat { get; set; } = "dd/MM/yyyy";
public bool StopOnError { get; set; } = false;
public int MaxErrors { get; set; } = 100;
}
</syntaxhighlight>

== Common Import Patterns ==

=== Batch Processing ===

<syntaxhighlight lang="csharp">
public async Task<ImportResult> BatchImportAsync<T>(
IEnumerable<T> data,
int batchSize = 100,
Func<List<T>, Task<bool>> processBatch = null)
{
var result = new ImportResult();
var batch = new List<T>(batchSize);

foreach (var item in data)
{
batch.Add(item);

if (batch.Count >= batchSize)
{
var success = await processBatch(batch);
if (success)
result.SuccessCount += batch.Count;
else
result.FailureCount += batch.Count;

batch.Clear();
}
}

// Process remaining items
if (batch.Count > 0)
{
var success = await processBatch(batch);
if (success)
result.SuccessCount += batch.Count;
else
result.FailureCount += batch.Count;
}

return result;
}
</syntaxhighlight>

=== Duplicate Detection ===

<syntaxhighlight lang="csharp">
public class DuplicateDetector<T>
{
private readonly Func<T, string> _keySelector;
private readonly HashSet<string> _existingKeys;

public DuplicateDetector(Func<T, string> keySelector)
{
_keySelector = keySelector;
_existingKeys = new HashSet<string>();
}

public bool IsDuplicate(T item)
{
var key = _keySelector(item);
return !_existingKeys.Add(key);
}

public List<T> RemoveDuplicates(IEnumerable<T> items)
{
var unique = new List<T>();

foreach (var item in items)
{
if (!IsDuplicate(item))
unique.Add(item);
}

return unique;
}
}
</syntaxhighlight>

=== Data Transformation Pipeline ===

<syntaxhighlight lang="csharp">
public class TransformPipeline<TSource, TTarget>
{
private readonly List<Func<TSource, TSource>> _transformations = new();
private Func<TSource, TTarget> _finalMapping;

public TransformPipeline<TSource, TTarget> AddTransformation(Func<TSource, TSource> transform)
{
_transformations.Add(transform);
return this;
}

public TransformPipeline<TSource, TTarget> SetMapping(Func<TSource, TTarget> mapping)
{
_finalMapping = mapping;
return this;
}

public TTarget Process(TSource source)
{
var current = source;

foreach (var transform in _transformations)
{
current = transform(current);
}

return _finalMapping(current);
}

public List<TTarget> ProcessBatch(IEnumerable<TSource> sources)
{
return sources.Select(Process).ToList();
}
}
</syntaxhighlight>

== Error Handling and Logging ==

<syntaxhighlight lang="csharp">
public class ImportLogger
{
private readonly BusinessLayerMain _bl;
private readonly List<ImportError> _errors = new();
private readonly StringBuilder _log = new();

public ImportLogger(BusinessLayerMain bl)
{
_bl = bl;
}

public void LogError(int rowNumber, string field, string message, object value = null)
{
var error = new ImportError
{
RowNumber = rowNumber,
Field = field,
Message = message,
Value = value?.ToString(),
Timestamp = DateTime.Now
};

_errors.Add(error);

var logMessage = $"Row {rowNumber}, Field '{field}': {message}";
if (value != null)
logMessage += $" (Value: {value})";

_log.AppendLine(logMessage);
_bl.LoggingFunctions?.LogError(logMessage);
}

public void ExportErrorReport(string filePath)
{
using var writer = new StreamWriter(filePath);
writer.WriteLine("Row,Field,Error,Value,Time");

foreach (var error in _errors)
{
writer.WriteLine($"{error.RowNumber},{error.Field},\"{error.Message}\",\"{error.Value}\",{error.Timestamp:yyyy-MM-dd HH:mm:ss}");
}
}
}

public class ImportError
{
public int RowNumber { get; set; }
public string Field { get; set; }
public string Message { get; set; }
public string Value { get; set; }
public DateTime Timestamp { get; set; }
}
</syntaxhighlight>

== File Upload and Validation ==

<syntaxhighlight lang="csharp">
public class FileImportValidator
{
private readonly long _maxFileSize = 50 * 1024 * 1024; // 50MB
private readonly string[] _allowedExtensions = { ".csv", ".xlsx", ".xls", ".xml", ".json", ".txt" };

public ValidationResult ValidateFile(string filePath)
{
var result = new ValidationResult();

// Check file exists
if (!File.Exists(filePath))
{
result.AddError("File does not exist");
return result;
}

// Check file extension
var extension = Path.GetExtension(filePath).ToLower();
if (!_allowedExtensions.Contains(extension))
{
result.AddError($"File type {extension} is not allowed");
}

// Check file size
var fileInfo = new FileInfo(filePath);
if (fileInfo.Length > _maxFileSize)
{
result.AddError($"File size exceeds maximum allowed size of {_maxFileSize / (1024 * 1024)}MB");
}

// Check file is readable
try
{
using var stream = File.OpenRead(filePath);
// Attempt to read first byte to ensure file is accessible
stream.ReadByte();
}
catch (Exception ex)
{
result.AddError($"Cannot read file: {ex.Message}");
}

// Validate file content structure
if (result.IsValid)
{
result = ValidateFileContent(filePath, extension);
}

return result;
}

private ValidationResult ValidateFileContent(string filePath, string extension)
{
var result = new ValidationResult();

switch (extension)
{
case ".csv":
ValidateCsvStructure(filePath, result);
break;
case ".xlsx":
case ".xls":
ValidateExcelStructure(filePath, result);
break;
case ".xml":
ValidateXmlStructure(filePath, result);
break;
case ".json":
ValidateJsonStructure(filePath, result);
break;
}

return result;
}

private void ValidateCsvStructure(string filePath, ValidationResult result)
{
try
{
var lines = File.ReadAllLines(filePath).Take(10).ToList();

if (lines.Count == 0)
{
result.AddError("CSV file is empty");
return;
}

// Check for consistent column count
var firstLineColumns = lines[0].Split(',').Length;
for (int i = 1; i < lines.Count; i++)
{
var columnCount = lines[i].Split(',').Length;
if (columnCount != firstLineColumns)
{
result.AddWarning($"Inconsistent column count at line {i + 1}");
}
}
}
catch (Exception ex)
{
result.AddError($"Failed to validate CSV structure: {ex.Message}");
}
}
}

public class ValidationResult
{
public List<string> Errors { get; } = new List<string>();
public List<string> Warnings { get; } = new List<string>();

public bool IsValid => Errors.Count == 0;

public void AddError(string message) => Errors.Add(message);
public void AddWarning(string message) => Warnings.Add(message);
}
</syntaxhighlight>

== Performance Optimization ==

=== Memory-Efficient Large File Processing ===

<syntaxhighlight lang="csharp">
public class LargeFileProcessor
{
public async Task ProcessLargeFileAsync(string filePath, Func<string, Task<bool>> processLine)
{
const int bufferSize = 65536; // 64KB buffer

using var fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize, useAsync: true);
using var reader = new StreamReader(fileStream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true, bufferSize);

string line;
int lineNumber = 0;

while ((line = await reader.ReadLineAsync()) != null)
{
lineNumber++;

if (!await processLine(line))
{
throw new ImportException($"Failed to process line {lineNumber}");
}
}
}
}
</syntaxhighlight>

=== Parallel Processing ===

<syntaxhighlight lang="csharp">
public class ParallelImporter<T>
{
public async Task<ImportResult> ImportParallelAsync(
IEnumerable<T> data,
Func<T, Task<bool>> processItem,
int maxDegreeOfParallelism = 4)
{
var result = new ImportResult();
var semaphore = new SemaphoreSlim(maxDegreeOfParallelism);
var tasks = new List<Task<bool>>();

foreach (var item in data)
{
await semaphore.WaitAsync();

tasks.Add(Task.Run(async () =>
{
try
{
return await processItem(item);
}
finally
{
semaphore.Release();
}
}));
}

var results = await Task.WhenAll(tasks);

result.SuccessCount = results.Count(r => r);
result.FailureCount = results.Count(r => !r);

return result;
}
}

public class ImportResult
{
public int SuccessCount { get; set; }
public int FailureCount { get; set; }
public int TotalCount => SuccessCount + FailureCount;
public double SuccessRate => TotalCount > 0 ? (double)SuccessCount / TotalCount * 100 : 0;
}
</syntaxhighlight>

== Best Practices ==

# '''Always validate before import'''
#* Check file format and structure
#* Validate required fields
#* Check data types and ranges
#* Identify duplicates

# '''Use transactions'''
#* Wrap imports in database transactions
#* Implement rollback on failure
#* Consider savepoints for partial commits

# '''Implement proper error handling'''
#* Log all errors with context
#* Provide detailed error reports
#* Allow partial success where appropriate

# '''Optimize for performance'''
#* Use batch processing for large datasets
#* Implement async/await patterns
#* Consider parallel processing where safe
#* Use streaming for large files

# '''Maintain data integrity'''
#* Check foreign key relationships
#* Validate business rules
#* Ensure referential integrity
#* Handle nullable fields properly

# '''Provide user feedback'''
#* Show progress indicators
#* Report success/failure counts
#* Export error logs
#* Allow preview before commit

# '''Security considerations'''
#* Validate file types and sizes
#* Scan for malicious content
#* Sanitize input data
#* Implement access controls

# '''Make imports resumable'''
#* Track processed records
#* Allow restart from failure point
#* Implement idempotent operations

== See Also ==

* [[Data Validation]]
* [[Transaction Management]]
* [[Error Handling]]
* [[Performance Optimization]]
* [[Database Operations]]
* [[File Management]]
* [[Logging System]]

[[Category:Import/Export]]
[[Category:Data Processing]]
[[Category:File Operations]]
[[Category:Technical Documentation]]

Import PDF File Scripting - AI Importing

2025-11-10T02:53:05Z

Mike: Created page with "Import PDF File Scripting - AI Importing"

Import PDF File Scripting - AI Importing

Import File Scripting

2025-11-10T02:52:34Z

Mike: Created page with "Import File Scripting"

Import File Scripting

Current Release Features

2025-11-10T02:48:37Z

Mike:

== Release Details ==
'''Current Release:''' 6.1.14.1

=== Current Release Features: ===
Document Manager:

* Advanced Scripting via new Business Layer.

User Manager:

* Additional Roles and Permissions available to the new Business Layer

Organisation Settings:

* Logo
* Postal and Physical Address for Documents
* Default Bank Account
* Advanced Invoice Settings
* Microsoft Graph Email Sending via Entra App.
* SMTP Settings

Bank Manager:

* Management of Bank Accounts
* New Bank Account Import Settings
** ANZ
** BNZ
** Westpac
** ASB (''In Active Development'')
** Kiwibank (''In Active Development'')
Import File Admin

* Generic CSV Import To allow for CSV/XLSX/JSON/XML file import to AP Invoice.

Import PDF Admin (AI Enabled - Special License Required)

* Reading of PDF AP Invoices Direct to AP Batch.
* Scripting to Control Every Aspect.
* Multi Page, Complex or Simple Invoices are handled quickly saving time on data import.

Departments Admin

* Management of Departments away from Zinform 5
* Additional Code Support to allow for up to 5 Codes
** Eg: Could be used to track Registration Number of a Vehicle to A Department, Trailers, ID Numbers etc for AP Invoices etc.

=== Coming Soon: ===
Organisation Settings:

* IMAP Settings (Coming Soon)

CRM Module (Coming Soon)

Email Processing (Coming Soon)

Current Release Features

2025-11-10T02:40:29Z

Mike:

Document Scripting

2025-11-10T00:14:39Z

Mike:

= Document Scripting =

Document Scripting allows you to create custom documents in ZinformAccounts by writing C# code that processes templates and data. This guide covers the core functions and patterns you'll use.

== Getting Started ==

Every document script follows this basic structure:

<syntaxhighlight lang="csharp">
public class DocumentScripter
{
public static BusinessLayerMain zinBL;
public static Document document;

public bool Main(BusinessLayerMain bl, object documentTemplate, object? otherPartyDataTable,
ZinParameters parameters, ZinParameters returnParameters, User? user)
{
zinBL = bl;
// Your code here
return true; // or false if error
}
}
</syntaxhighlight>

'''Important:''' Your class must be named <code>DocumentScripter</code> and have a <code>Main</code> method with these exact parameters.

== Working with ZinWord Documents ==

=== Creating and Loading Documents ===

<syntaxhighlight lang="csharp">
// Create a new document
ZinWord document = new ZinWord(zinBL);

// Load from file
document.LoadDocument(documentFileName);

// Load from stream
document.LoadStream(memoryStream);

// Clone an existing document (useful when processing multiple records)
ZinWord clonedDoc = sourceDocument.Clone(true);
</syntaxhighlight>

=== Saving Documents ===

<syntaxhighlight lang="csharp">
// Save to file - format determined by extension
document.SaveDocument(saveFileName);

// Examples:
document.SaveDocument("MyFile.pdf"); // Saves as PDF
document.SaveDocument("MyFile.docx"); // Saves as Word document
</syntaxhighlight>

=== Checking Document Content ===

<syntaxhighlight lang="csharp">
// Check if document has any content (text, tables, or images)
bool hasContent = zinBL.DocumentFunctions.DocumentHasContent(document);
</syntaxhighlight>

=== Attaching Documents ===

<syntaxhighlight lang="csharp">
// Combine multiple documents into one (useful for bulk processing)
ZinWord bulkDocument = new ZinWord(zinBL);
bulkDocument.AttachDocument(sourceDocument1);
bulkDocument.AttachDocument(sourceDocument2);
bulkDocument.SaveDocument("Bulk_Output.pdf");
</syntaxhighlight>

== Working with Bookmarks ==

Bookmarks are placeholders in your Word templates that you replace with actual data.

=== Setting Bookmark Values ===

<syntaxhighlight lang="csharp">
// Set text value
document.SetBookmarkString("BookmarkName", "Value");

// Set HTML content (for formatted text, tables, etc.)
document.SetBookmarkHtml("BookmarkName", htmlString);

// Set hyperlink
document.SetBookmarkHyperLink("BookmarkName", hyperLinkItem);

// Set image from file
document.SetBookmarkImageFromFile("BookmarkName", pictureFileName);

// Set image from Picture object
document.SetBookmarkImage("BookmarkName", pictureItem);
</syntaxhighlight>

=== Deleting Bookmarks ===

<syntaxhighlight lang="csharp">
// Remove a bookmark and its content
document.DeleteBookmark("BookmarkName");
</syntaxhighlight>

=== Getting All Bookmarks ===

<syntaxhighlight lang="csharp">
// Retrieve all bookmarks in the document
var bookmarks = document.GetBookmarks();

foreach (var bookmark in bookmarks)
{
// Process each bookmark
string name = bookmark.Name;
// ... do something with the bookmark
}
</syntaxhighlight>

== Standard Bookmarks ==

ZinformAccounts provides automatic processing for common bookmarks:

=== ProcessStandardBookmarks ===

<syntaxhighlight lang="csharp">
zinBL.DocumentFunctions.ProcessStandardBookmarks(
document, // ZinWord document to process
otherParty, // ZOtherParty object (customer/supplier)
parameters, // ZinParameters with document settings
zinBL, // Business layer instance
logoWidth, // Logo width in pixels (e.g., 193)
logoHeight, // Logo height in pixels (e.g., 70)
minAddressLines, // Minimum address lines (default: 4)
addresseeFirstLineAddress, // Use first line as addressee (default: false)
stateAsCity // Treat state as city (NZ DB) (default: false)
);
</syntaxhighlight>

'''Supported Standard Bookmarks:'''
* <code>OrganisationLogo</code> - Your company logo
* <code>OrganisationName</code> - Your company name
* <code>OrganisationAddress</code> - Your postal address
* <code>OrganisationPhone</code> - Your phone number
* <code>OrganisationEmail</code> - Your email address
* <code>OrganisationWebsite</code> - Your website URL
* <code>OrganisationBankAccount</code> - Bank account name and number
* <code>OrganisationBankAccountNumber</code> - Bank account number only
* <code>OrganisationBankAccountName</code> - Bank account name only
* <code>DocumentDate</code> - Current date (formatted as "dd MMMM yyyy")
* <code>DocumentId</code> - Document ID from parameters
* <code>GSTNumber</code> - Tax registration number
* <code>OtherPartyId</code> - Customer/Supplier ID
* <code>OtherPartyName</code> - Customer/Supplier name
* <code>OtherPartyAddress</code> - Customer/Supplier postal address
* <code>OtherPartySalutation</code> - Greeting (from Administrator/Manager contact)
* <code>ReferenceId</code> - Reference ID
* <code>OrganisationNameFooter</code> - Company name for footer

=== ProcessExtraInvoiceBookmarks ===

For invoice-specific bookmarks (duplicated bookmarks with "2" suffix):

<syntaxhighlight lang="csharp">
zinBL.DocumentFunctions.ProcessExtraInvoiceBookmarks(
document, otherParty, parameters, zinBL,
logoWidth, logoHeight, minAddressLines,
addresseeFirstLineAddress, stateAsCity
);
</syntaxhighlight>

=== ProcessInvoiceBookmarks ===

Handles delivery address for invoices:

<syntaxhighlight lang="csharp">
zinBL.DocumentFunctions.ProcessInvoiceBookmarks(
document, otherParty, parameters, zinBL, transaction,
minAddressLines, stateAsCity, "DELIVERY"
);
</syntaxhighlight>

'''Supported Bookmark:'''
* <code>DeliverToDetails</code> - Delivery address (deleted if no delivery address exists)

=== ProcessExtraStatementBookmarks ===

For statement-specific bookmarks (duplicated bookmarks with "2" suffix):

<syntaxhighlight lang="csharp">
zinBL.DocumentFunctions.ProcessExtraStatementBookmarks(
document, otherParty, parameters, zinBL,
logoWidth, logoHeight, minAddressLines,
addresseeFirstLineAddress, stateAsCity
);
</syntaxhighlight>

== Working with Parameters ==

Parameters pass data between the UI and your script.

=== Getting Parameter Values ===

<syntaxhighlight lang="csharp">
// Get string value
string documentId = parameters.GetItemString("DocumentId");

// Get datetime value
DateTime asAtDate = (DateTime)parameters.GetItemDateTime("DateAsAt");

// Get boolean value
bool individual = parameters.GetItemBoolean("IndividualDocuments");

// Get output extension
string extension = parameters.GetItemString("OutputExtension");
string filter = parameters.GetItemString("OutputExtensionFilter");
</syntaxhighlight>

=== Setting Return Parameters ===

<syntaxhighlight lang="csharp">
// Return the save location to the caller
returnParameters.SetItemString("SaveLocation", saveLocation);

// Return error message if something fails
returnParameters.SetItemString("ReturnError", "No File Save Location Chosen!");
</syntaxhighlight>

== File Operations ==

=== Save File Dialog ===

<syntaxhighlight lang="csharp">
string saveLocation = FileFunctions.OpenSaveFileDialog(
document.DocumentOutputFolder, // Default folder
String.Format("Statement_{0}", DateTime.Now.ToString("yyyyMMdd_hhmmss")), // Default filename
parameters.GetItemString("OutputExtension"), // Default extension (e.g., "pdf")
parameters.GetItemString("OutputExtensionFilter") // File type filter
);

if (saveLocation != null && saveLocation.Length > 0)
{
// User selected a location
}
else
{
// User cancelled - handle error
returnParameters.SetItemString("ReturnError", "No File Save Location Chosen!");
return false;
}
</syntaxhighlight>

=== Creating Directories ===

<syntaxhighlight lang="csharp">
string folderPath = Path.Combine(baseFolderPath, $"OtherParty_{otherPartyId}");

if (!Directory.Exists(folderPath))
{
Directory.CreateDirectory(folderPath);
}

string saveFileName = Path.Combine(folderPath, "Statement.pdf");
</syntaxhighlight>

== Working with DataTables ==

When processing multiple records (e.g., statements for multiple customers):

<syntaxhighlight lang="csharp">
// Validate the DataTable parameter
DataTable otherPartyDataTable;
if (otherPartyDataTable != null && otherPartyDataTable is DataTable)
{
otherPartyDataTable = (DataTable)otherPartyDataTable;
}
else
{
throw new InvalidOperationException("otherPartyDataTable is not a valid DataTable");
}

// Loop through rows
foreach (DataRow row in otherPartyDataTable.Rows)
{
// Get values from the row
string otherPartyId = (string)row["OtherPartyId"];

// Load the full OtherParty object
var otherParty = zinBL.OtherPartyFunctions.GetOtherPartyById(otherPartyId);

// Process document for this party
}
</syntaxhighlight>

== Progress Bar ==

Show progress when processing multiple records:

<syntaxhighlight lang="csharp">
ProgressBarManager.Start("Processing Statements", true, totalCount, progressBar =>
{
int currentCount = 1;

foreach (DataRow row in dataTable.Rows)
{
// Check for cancellation
if (progressBar.CancellationPending || ProgressBarManager.IsCancelled())
{
break;
}

// Update progress
progressBar.ReportProgress(currentCount, $"Processing: {customerName}");

// Do work here...

currentCount++;
}

// Mark as finished
ProgressBarManager.Finished();
});
</syntaxhighlight>

== Financial Functions ==

=== Statement Data ===

<syntaxhighlight lang="csharp">
// Get statement details (aged balances)
ZinStatementDetails details = zinBL.DocumentFunctions.GetStatementDetails(
zinBL,
otherParty,
statementDate,
DocumentTypes.ARStatement // or DocumentTypes.APRemittance
);

// Access aged balances
decimal current = details.CurrentBalance;
decimal oneMonth = details.OneMonthOverdue;
decimal twoMonths = details.TwoMonthsOverdue;
decimal threeMonths = details.ThreeMonthsOverdue;
decimal total = details.TotalDue;
</syntaxhighlight>

=== Transaction Data ===

<syntaxhighlight lang="csharp">
// Get monthly running transactions (preferred method)
var (transactions, statementDetails) = zinBL.DocumentFunctions.GetMonthlyRunningTransactions2(
statementDate,
otherPartyId,
zinBL
);

// transactions is List<StatementTransaction2>
// statementDetails is ZinStatementDetails with aged balances

// Process transactions
foreach (var tran in transactions)
{
DateTime date = tran.Date;
int type = tran.Type;
string reference = tran.Reference;
decimal value = tran.Value;
decimal runningBalance = tran.RunningBalance;
decimal subTotal = tran.SubTotal;
}
</syntaxhighlight>

=== Combining Transaction Lists ===

<syntaxhighlight lang="csharp">
// Combine and sort multiple transaction lists by date
var combined = zinBL.DocumentFunctions.CombineTransactions(listOne, listTwo);
</syntaxhighlight>

=== Date Utilities ===

<syntaxhighlight lang="csharp">
// Get last day of month
DateTime monthEnd = DocumentFunctions.GetEndOfMonth(someDate);
// Example: 15/03/2024 returns 31/03/2024
</syntaxhighlight>

== Building HTML Tables ==

For inserting formatted tables into bookmarks:

<syntaxhighlight lang="csharp">
var htmlTable = new StringBuilder();

htmlTable.AppendLine("<table style='width: 100%; border-collapse: collapse;'>");
htmlTable.AppendLine("<thead>");
htmlTable.AppendLine("<tr>");
htmlTable.AppendLine("<td style='padding: 5px; font-family: \"Aptos\", sans-serif;'><b>Date</b></td>");
htmlTable.AppendLine("<td style='padding: 5px; font-family: \"Aptos\", sans-serif;'><b>Reference</b></td>");
htmlTable.AppendLine("<td style='padding: 5px; text-align: right; font-family: \"Aptos\", sans-serif;'><b>Amount</b></td>");
htmlTable.AppendLine("</tr>");
htmlTable.AppendLine("</thead>");
htmlTable.AppendLine("<tbody>");

foreach (var item in dataList)
{
htmlTable.AppendLine("<tr>");
htmlTable.AppendLine($"<td style='padding: 2px; font-family: \"Aptos\", sans-serif;'>{item.Date:dd/MM/yyyy}</td>");
htmlTable.AppendLine($"<td style='padding: 2px; font-family: \"Aptos\", sans-serif;'>{item.Reference}</td>");
htmlTable.AppendLine($"<td style='padding: 2px; text-align: right; font-family: \"Aptos\", sans-serif;'>{item.Amount:$#,##0.00}</td>");
htmlTable.AppendLine("</tr>");
}

htmlTable.AppendLine("</tbody>");
htmlTable.AppendLine("</table>");

// Insert into document
document.SetBookmarkHtml("TableBookmark", htmlTable.ToString());
</syntaxhighlight>

'''Tips for HTML Tables:'''
* Use inline styles (external CSS won't work)
* Specify <code>font-family: "Aptos", sans-serif;</code> for consistency
* Use <code>text-align: right</code> for numbers
* Add padding for readability: <code>padding: 5px;</code>
* Format currency: <code>{value:$#,##0.00}</code>

== Email Integration ==

=== Sending Documents via Email ===

<syntaxhighlight lang="csharp">
// Get email addresses for specific contacts
var emailAddresses = otherParty.GetEmailContactsAsEmailCompatibleStringById(document.EmailContactIds);

if (emailAddresses.Length > 0)
{
// Replace placeholders in email body
string emailBody = document.EmailBody.Replace("[OtherPartyName]", otherParty.Name);

// Send email with attachment
var result = zinBL.Emailing.SendEmailWithImage(
emailAddresses, // To addresses
"", // CC addresses
"", // BCC addresses
document.EmailSubject, // Subject
emailBody, // HTML body
zinBL, // Business layer
attachmentFilePath, // Path to attachment
false, // Is HTML
70L, // Image quality
444, // Max image width
"unsubscribe@yourdomain.com" // Unsubscribe email
);

if (!result.success)
{
MessageBox.Show(result.errorMessage);
}
}
</syntaxhighlight>

== Best Practices ==

=== Error Handling ===

<syntaxhighlight lang="csharp">
try
{
// Your code here

if (somethingWentWrong)
{
returnParameters.SetItemString("ReturnError", "Clear error message here");
return false;
}
}
catch (Exception ex)
{
MessageBox.Show($"An error occurred: {ex.Message}\n{ex.StackTrace}", "Error");
returnParameters.SetItemString("ReturnError", ex.Message);
return false;
}

return true; // Success
</syntaxhighlight>

=== Memory Management ===

When processing many documents, clean up:

<syntaxhighlight lang="csharp">
foreach (DataRow row in dataTable.Rows)
{
var clonedDoc = sourceDoc.Clone(true);

// Process document...

// If not saving this document, explicitly dispose
clonedDoc = null;
}
</syntaxhighlight>

=== Conditional Processing ===

<syntaxhighlight lang="csharp">
// Only add to bulk document if not emailed
bool wasEmailed = false;

if (document.EmailIfPossible && emailAddresses.Length > 0)
{
// Send email
wasEmailed = true;
}

if (!wasEmailed)
{
bulkDocument.AttachDocument(processedDoc);
}
</syntaxhighlight>

== Common Patterns ==

=== Pattern: Individual vs Bulk Documents ===

<syntaxhighlight lang="csharp">
bool individual = parameters.GetItemBoolean("IndividualDocuments");
ZinWord bulkDoc = new ZinWord(zinBL);

foreach (var otherParty in otherParties)
{
var doc = ProcessDocument(otherParty);

if (individual)
{
// Save individual file
string fileName = $"{folderPath}/Document_{otherParty.OtherPartyId}.pdf";
doc.SaveDocument(fileName);
}
else
{
// Add to bulk document
bulkDoc.AttachDocument(doc);
}
}

// Save bulk document if not individual
if (!individual && zinBL.DocumentFunctions.DocumentHasContent(bulkDoc))
{
bulkDoc.SaveDocument(saveLocation);
}
</syntaxhighlight>

=== Pattern: Processing with Progress ===

<syntaxhighlight lang="csharp">
ProgressBarManager.Start("Processing Documents", true, dataTable.Rows.Count, progressBar =>
{
int currentCount = 1;

foreach (DataRow row in dataTable.Rows)
{
if (progressBar.CancellationPending || ProgressBarManager.IsCancelled())
{
break;
}

progressBar.ReportProgress(currentCount, $"Processing: {currentItem}");

// Do work...

currentCount++;
}

ProgressBarManager.Finished();
});
</syntaxhighlight>

=== Pattern: Empty Row Padding ===

<syntaxhighlight lang="csharp">
int minLines = 13;
int currentLines = dataList.Count;
int emptyLines = Math.Max(0, minLines - currentLines);

for (int i = 0; i < emptyLines; i++)
{
htmlTable.AppendLine("<tr style='height: 12px;'>");
htmlTable.AppendLine("<td></td><td></td><td></td>");
htmlTable.AppendLine("</tr>");
}
</syntaxhighlight>

== Debugging ==

<syntaxhighlight lang="csharp">
// Add this using statement at top of your script:
using ZinformAccounts.Debugger;

// Launch debugger at any point
DebuggerExtensions.LaunchNow("Starting Main method");

// Show debug information
MessageBox.Show($"Debug: {variableName}");
</syntaxhighlight>

== Complete Example ==

Here's a simplified but complete statement script:

<syntaxhighlight lang="csharp">
using System;
using System.Text;
using System.Windows;
using System.Data;
using ZinBusinessLayer;
using ZinBusinessLayer.HelperClasses;
using ZinBusinessLayer.Enums;
using ZinBusinessLayer.Word;

public class DocumentScripter
{
public static BusinessLayerMain zinBL;
public static Document document;

public bool Main(BusinessLayerMain bl, object documentTemplate, object? otherPartyDataTable,
ZinParameters parameters, ZinParameters returnParameters, User? user)
{
zinBL = bl;

if (!(documentTemplate is ZinWord sourceDoc))
{
returnParameters.SetItemString("ReturnError", "Invalid document template");
return false;
}

document = zinBL.DocumentFunctions.GetDocument(parameters.GetItemString("DocumentId"));
DateTime statementDate = (DateTime)parameters.GetItemDateTime("DateAsAt");

string saveLocation = FileFunctions.OpenSaveFileDialog(
document.DocumentOutputFolder,
$"Statement_{DateTime.Now:yyyyMMdd_hhmmss}",
parameters.GetItemString("OutputExtension"),
parameters.GetItemString("OutputExtensionFilter")
);

if (string.IsNullOrEmpty(saveLocation))
{
returnParameters.SetItemString("ReturnError", "No save location chosen");
return false;
}

DataTable dataTable = (DataTable)otherPartyDataTable;
ZinWord bulkDoc = new ZinWord(zinBL);

ProgressBarManager.Start("Processing Statements", true, dataTable.Rows.Count, progressBar =>
{
int count = 1;

foreach (DataRow row in dataTable.Rows)
{
if (progressBar.CancellationPending) break;

string otherPartyId = (string)row["OtherPartyId"];
var otherParty = zinBL.OtherPartyFunctions.GetOtherPartyById(otherPartyId);

progressBar.ReportProgress(count, $"Processing: {otherParty.Name}");

var doc = sourceDoc.Clone(true);

// Process bookmarks
zinBL.DocumentFunctions.ProcessStandardBookmarks(
doc, otherParty, parameters, zinBL, 193, 70, 5
);

// Get statement data
var (transactions, details) = zinBL.DocumentFunctions.GetMonthlyRunningTransactions2(
statementDate, otherPartyId, zinBL
);

// Build transaction table
var html = new StringBuilder();
html.AppendLine("<table style='width: 100%;'>");
foreach (var tran in transactions)
{
html.AppendLine("<tr>");
html.AppendLine($"<td>{tran.Date:dd/MM/yyyy}</td>");
html.AppendLine($"<td>{tran.Reference}</td>");
html.AppendLine($"<td style='text-align: right;'>{tran.Value:$#,##0.00}</td>");
html.AppendLine("</tr>");
}
html.AppendLine("</table>");

doc.SetBookmarkHtml("Transactions", html.ToString());
doc.SetBookmarkString("TotalDue", details.TotalDue.ToString("#,##0.00"));

bulkDoc.AttachDocument(doc);
count++;
}

ProgressBarManager.Finished();
});

if (zinBL.DocumentFunctions.DocumentHasContent(bulkDoc))
{
bulkDoc.SaveDocument(saveLocation);
}

returnParameters.SetItemString("SaveLocation", saveLocation);
return true;
}
}
</syntaxhighlight>

== Troubleshooting ==

{| class="wikitable"
! Problem !! Solution
|-
| Bookmark not found error || Check spelling - bookmarks are case-sensitive
|-
| HTML not rendering properly || Use inline styles only, no external CSS
|-
| Progress bar not showing || Ensure you call <code>ProgressBarManager.Finished()</code>
|-
| Document won't save || Check file path and ensure extension matches format
|-
| Changes not appearing || Make sure you're modifying the correct document instance (not the template)
|-
| Out of memory with many documents || Process in batches, dispose of documents after use
|}

== Additional Resources ==

* [[Transaction_Types|Transaction Types Reference]]
* [[Document_Templates|Creating Document Templates]]
* [[Bookmark_Reference|Complete Bookmark Reference]]

[[Category:Scripting]]
[[Category:Documents]]

Minimum System Requirements

2025-11-10T00:05:41Z

Mike: /* Microsoft SQL Server */

=== Supported Microsoft Windows Operating Systems ===
'''Zinform Accounts''' can operate on Windows 10 or Windows Server 2019 or later operating systems.

* '''Minimum:''' Windows 10
* '''Recommended:''' Windows 11
* '''Minimum:''' Windows Server 2019
* '''Recommended:''' Windows Server 2019

'''Zinform Accounts''' might run under older versions of Windows, but they are not supported or recommended by Exodesk.

These recommendations are based upon Microsoft's Windows product lifecycles. Please note that we do not support Windows versions where Microsoft has deemed them end of life.

=== Microsoft .NET 9 ===

* '''Zinform Accounts 6.x.x''' requires that the latest [https://dotnet.microsoft.com/en-us/download/dotnet/9.0 .net 9 runtime] is installed.

=== Microsoft WebView2 Runtime ===
'''Zinform Accounts''' version 6.0.+ a requires the Microsoft WebView2 Runtime to be correctly installed on your computer. Click [https://developer.microsoft.com/en-us/microsoft-edge/webview2/?form=MA13LH here] for installer page. We recommend that you install the Evergreen Standalone Installer.

''Note, the Microsoft Edge WebView2 Runtime is automatically installed with Windows 11 and from June 2022 onwards with Windows 10.''

=== Memory (RAM) ===

* '''Minimum:''' 8GB RAM.
* '''Recommended:''' 16GB RAM or more on 64-bit operating systems.

=== Display Resolution ===

* '''Minimum:''' 1920 x 1080 or higher

=== Network ===
'''Zinform Accounts''' should be run over a 1GB network if not running on a single PC / RDP Server due to data requirements.

=== Microsoft SQL Server ===
The '''Zinform Accounts''' '''6''' requires Microsoft SQL Server 2019 and higher database software.

* '''Required:''' SQL Server 2019 or 2022 (Express or Better).
* '''Min Compatibility Level: 150'''
[[File:CompatabilityLevel.png|thumb|510x510px|Compatibility Level]]

File:CompatabilityLevel.png

2025-11-10T00:03:27Z

Mike:

Compatability Level

Minimum System Requirements

2025-11-10T00:00:28Z

Mike: .Net generic page

Permissions and Roles

2025-09-30T01:36:15Z

Mike:

= User Roles & Permissions Guide =

== Overview ==
The system has six user roles, each with different permission levels. Think of it as a video game tier list, but for business operations. 🎮
----

== Min Zinform 6 Version ==
The minimum system version for to enable roles is 6.1.13.0

== Role Hierarchy ==

=== 🦸‍♂️ Super Administrator ===
'''"God Mode Activated"'''

Full system access. Can do literally everything.

'''Key Permissions:'''

* All administrative functions
* Global settings configuration
* License management
* User management (create, update)
* Organization details
* Email & banking settings
* File & PDF imports
* Department management
* Document creation & updates

'''Use Case:''' System owner, IT director, or that one person who knows where all the bodies are buried.
----

=== 👑 Administrator ===
'''"Almost Everything Except the Nuclear Codes"'''

Company-level admin with near-complete access. Currently identical to SuperAdmin (you might want to revisit this).

'''Key Permissions:'''

* Same as SuperAdministrator
* Access to all operational and administrative functions

'''Use Case:''' Senior management, operations director, trusted lieutenant.

'''⚠️ Note:''' The comments suggest <code>CanAccessGlobalSettings</code> and <code>CanUpdateLicense</code> should probably be SuperAdmin-only. Worth reviewing.
----

=== 💪 Super User ===
'''"Power User with Training Wheels Off"'''

Can handle most day-to-day operations but can't mess with the company structure or users.

'''Key Permissions:'''

* ✅ Document management (create, update)
* ✅ File & PDF imports
* ✅ Department management
* ✅ Admin menu access
* ❌ Organization settings
* ❌ User management
* ❌ Financial settings
* ❌ License updates

'''Use Case:''' Team lead, operations manager, power user who gets stuff done.
----

=== ⚡ Power User ===
'''"Operational Access, Hold the Danger"'''

More limited than SuperUser. Can manage departments but not much else.

'''Key Permissions:'''

* ✅ Department management
* ✅ Admin menu access
* ❌ Everything else

'''Use Case:''' Department head, mid-level manager, someone who needs organizational visibility but limited editing rights.
----

=== 👤 Base User ===
'''"Standard Issue Employee"'''

Basic operational access. Can use the system but can't change anything structural.

'''Key Permissions:'''

* ❌ All administrative functions disabled
* Can view and use standard features (implied)

'''Use Case:''' Regular employees, data entry staff, most of your workforce.
----

=== 👀 Read-only User ===
'''"Look But Don't Touch"'''

View-only access. The digital equivalent of a museum visitor.

'''Key Permissions:'''

* ❌ Everything is disabled
* ✅ IsReadOnly flag enabled

'''Use Case:''' Auditors, consultants, stakeholders, interns, or anyone who needs to see data but
shouldn't change anything.
----

== Quick Reference Matrix ==
{| class="wikitable"
!Permission
!Super Admin
!Admin
!Super User
!Power User
!Base User
!Read Only
|-
|Organization Details
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|Global Settings
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|Admin Menu
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|License Management
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|Document Management
|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|-
|User Management
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|Email Settings
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|Banking Settings
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|-
|File/PDF Imports
|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|-
|Department Management
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|Read Only
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|{{no}}
|{{yes}}
|}
----

== Best Practices ==

# '''Start Restrictive:''' Assign the minimum role needed. You can always promote users later.
# '''Regular Audits:''' Review user roles quarterly. That intern from 2019 probably doesn't need SuperAdmin anymore.
# '''Separation of Duties:''' Keep financial and user management permissions limited to trusted admins.
# '''Document Changes:''' Log role changes, especially escalations to Admin/SuperAdmin.

----

== Notes for Developers ==

* '''Admin vs SuperAdmin:''' Currently identical. Consider restricting <code>CanAccessGlobalSettings</code> and <code>CanUpdateLicense</code> to SuperAdmin only.
* '''Money = Admin Territory:''' Financial permissions deliberately restricted to admin roles.
* '''BaseUser:''' Currently has no explicit permissions. Define what they ''can'' do in your application logic.

== Role Configuration ==
Roles are setup on the Users form from the Admin menu.
[[File:Image RoleConfig.png|left|thumb]]

File:Image RoleConfig.png

2025-09-30T01:35:35Z

Mike:

Role Config

Permissions and Roles

2025-09-30T01:32:46Z

Mike: /* Overview */

Zinform Wiki Home

2025-09-30T01:31:14Z

Mike: