Chapter 24 — SAP Business One integration and SAP reports

Module code: SAP_REPORTS Features: sap_reports_dashboard, sap_sync, sap_pending_approvals, sap_pending_purchase_orders, sap_purchase_order_drafts, sap_payment_tracking, sap_bank_reconciliation, sap_sales_reports, sap_reports_settings Home: /sap-reports/

Further detail: docs/DATA_SOURCES_SAP_VS_PORTAL.md, docs/BANK_RECON_PORTAL.md, docs/PO_APPROVAL_PORTAL_PLAN.md.

This chapter applies only if your organisation runs SAP Business One. Most customers do not, and the rest of the product works without it.

24.1 What the integration is for

Where SAP Business One is the system of record, TOSS ERP acts as the working surface over it: better screens for approvals, warehouse operations, bank reconciliation and sales analysis, on top of SAP's own data.

The division of responsibility is fixed and worth stating plainly:

Layer	Owns
SAP Business One	The master data and documents it holds — stock quantities, batches, purchase orders, payments, the general ledger
TOSS ERP	Operational screens, warehouse layout, approval workflow, reconciliation workspace, and an audit trail of everything asked of SAP

24.2 The two connections

Channel	Used for
SAP HANA (direct SQL read)	Bulk synchronisation and live queries — gate pass lookups, approvals, analytics
Service Layer (REST)	Writing back — creating and editing purchase order drafts, posting stock transfers

Reading uses HANA; writing uses the Service Layer. If HANA synchronisation is switched off, several screens fall back to previously mirrored data or report an error rather than showing something misleading.

24.3 What comes from SAP and what does not

This distinction causes more confusion than anything else in the product. The modules below are portal-only and work without SAP at all:

Human Resources          Accounting (chart, journals, invoices, e-invoicing)
Partners                 Project Management
Item master (inventory)  Manufacturing
Portal Sales             Help Desk
Portal Purchase          Merchandising

Partners are not synced from SAP. Neither is the portal item master. A customer existing in SAP does not make it exist here; create it in Chapter 5.

The portal's own Sales and Purchase modules (Chapters 6 and 7) are separate from the SAP mirrored reports and the SAP purchase drafts described below. They are two different things that both involve orders, and mixing them up is the most common misunderstanding here.

24.4 Settings

/settings/sap-integration/     connection settings
/sap-reports/settings/         SAP reports settings and connection tests

/settings/sap-integration/ holds the Service Layer connection. When use portal settings is on, the values here are used and the server's environment file is not consulted — so the settings screen is the single place to change them.

/sap-reports/settings/ provides connection tests for both channels. Run both tests after any change rather than discovering a bad credential when a user tries to approve something.

24.5 Synchronisation

/sync/                              synchronisation management
/api/sync-history/                  past runs
/api/sync-logs/<id>/                the log for one run

The synchronisation screen lets you:

Action	Purpose
Start a sync	Pull a data set from SAP now
Check status	See progress of a running sync
Cancel	Stop a running sync
Update configuration	Change what is synced and how often
Start / stop the automatic daemon	Run syncs on a schedule
Check daemon status	Confirm it is alive
Trigger reconciliation	Compare portal data against SAP and report differences

Every run is recorded. /api/sync-history/ lists them; the log for one run shows what happened and any errors; logs can be downloaded for support.

The comparison view is the one to trust. It shows where the portal and SAP disagree. A sync that reports success but leaves differences is telling you about a filter or a mapping problem, not a network one.

Synchronisation actions are rate-limited per user. If an action is refused after repeated attempts, wait rather than retrying immediately.

24.6 Purchase order approvals

/pending-approvals/                  the approval queue
/pending-approvals/history/          approval history
/pending-approvals/audit-report/     audit report

Where SAP routes purchase orders through an approval workflow, approvers do the work here rather than in SAP.

How visibility works

Approvers see only the drafts where they are on that document's approval chain, as defined by the SAP workflow template. There is no global "finance sees everything" list. If a purchase order is missing from your queue, you are not on its chain.

Approving

Open /pending-approvals/.
Open a purchase order. You see its lines, its history, comments and attachments.
Review it.
Approve or reject, with a comment.

The real SAP user is recorded as the approver. The action is carried out against SAP as you, not as a shared service account — which is what makes the SAP approval record meaningful. You may be asked for your SAP credentials; they are stored for your session and can be cleared at any time.

Rejecting sends the document back to the originator, following SAP's own workflow behaviour. The portal captures your comment and writes an audit entry.

Attachments and comments

Attachments are held in the portal only, for audit. They are not pushed into SAP's document management. If a document must live in SAP, put it there directly.

The audit report

/pending-approvals/audit-report/ shows who approved what and when, with the comments. This is the record for an internal audit.

24.7 Pending purchase orders and drafts

/pending-purchase-orders/     open purchase orders in SAP
/purchase-drafts/             draft purchase orders
/purchase-drafts/new/         create a draft in SAP

Purchase order drafts are created in SAP through the Service Layer from the portal screen. The search helpers — vendor, item, warehouse, and the price hint — read from SAP so the draft is built from real master data.

This is the one place the portal writes purchasing documents into SAP. It is not the same as the portal's own Purchase module.

24.8 Payment tracking

/sap-reports/payment-tracking/    payment tracking report

Tracks payment documents from SAP with drill-down to each document, an audit check, and attachments. Use it to answer "was this actually paid, and against what".

24.9 SAP bank reconciliation

Home: /sap-bank-reconcile/

A workspace for matching bank statement lines against SAP payment documents. It is separate from the portal's own bank statement reconciliation (Chapter 12) — this one works against SAP's payments.

The flow

1. Import SAP payments      pull incoming and outgoing payment documents
2. Upload the statement     CSV or PDF becomes statement lines
3. Smart match              scored suggestions you confirm or reject
4. Review                   the reconciled tab; unreconcile if needed
5. Report                   filter, print, export

The screens

/sap-bank-reconcile/                        dashboard
/sap-bank-reconcile/payments/               imported SAP payments
/sap-bank-reconcile/payments/import/        import them
/sap-bank-reconcile/statement/              statement uploads
/sap-bank-reconcile/statement/upload/       upload one
/sap-bank-reconcile/statement/<id>/lines/   its lines
/sap-bank-reconcile/match/                  the matching workspace
/sap-bank-reconcile/match/run/              run smart matching
/sap-bank-reconcile/report/                 reconciliation report

Matching

Open the matching workspace.
Run smart match. Candidate pairs are scored and proposed.
Work the suggestions: confirm the right ones, reject the wrong ones.
Where nothing was proposed, use manual match to pair a statement line with a payment yourself.
Bulk confirm and bulk reject handle a long run of obvious cases at once.

Read a suggestion before confirming it. A score is a probability, not a fact, and two payments of the same amount on the same day are exactly where scoring is weakest.

Unmatch — individually or by group — undoes a confirmed match.

The report

/sap-bank-reconcile/report/ filters by house bank and date range and shows the statement and SAP ledger figures, the memo, and who matched each line. Print it, or export to Excel or PDF for the period file.

24.10 Sales analytics

/sap-reports/sales/                       SAP sales reports
/sap-reports/sales/analytics-dashboard/   analytics dashboard
/sap-reports/sales/analytics-live/        live analytics

Sales analysis over SAP's own sales data, with drill-down by partner and by product category. The live view queries SAP directly, so it reflects the current position rather than the last sync.

24.11 Permissions

Feature	Controls
`sap_reports_dashboard`	The SAP reports home
`sap_sync`	Synchronisation screens and actions
`sap_pending_approvals`	The PO approval queue
`sap_pending_purchase_orders`	Open purchase orders
`sap_purchase_order_drafts`	Creating and editing drafts in SAP
`sap_payment_tracking`	Payment tracking
`sap_bank_reconciliation`	The bank reconciliation workspace
`sap_sales_reports`	Sales analytics
`sap_reports_settings`	Settings and connection tests

Grant approval rights only to people who genuinely appear on SAP approval chains — holding the permission without being on a chain simply shows an empty queue.

24.12 Routine

Daily
  [ ] Check the sync history for failed runs
  [ ] Clear the approval queue
  [ ] Confirm the automatic sync daemon is running

Weekly
  [ ] Run the reconciliation comparison and investigate differences
  [ ] Work the bank reconciliation to a clean position

Monthly
  [ ] Produce the reconciliation report for the period file
  [ ] Review the approval audit report

24.13 Troubleshooting

Symptom	Cause	Fix
A sync refuses to start	HANA synchronisation is switched off	Enable it in settings, or accept that the screen shows mirrored data
A screen shows stale figures	The last sync failed or has not run	Check the sync history and the log for that run
Sync succeeds but data still disagrees	A filter or mapping problem, not a connection one	Run the comparison view; it names the differences
An action is refused after repeated attempts	Sync actions are rate-limited per user	Wait, then try again
The approval queue is empty	You are not on any document's approval chain	This is by design; check the SAP workflow template
An approval fails at SAP	SAP credentials missing or wrong, or the document changed in SAP	Re-enter your SAP credentials; refresh and retry
An attachment is not visible in SAP	Attachments are portal-only, for audit	Attach it in SAP directly if it must live there
A stock transfer fails to post	SAP unreachable, or the warehouse mapping is wrong	Check the connection tests and the WMS warehouse mapping (Chapter 9)
Smart match proposes nothing	Payments not imported, or dates outside the range	Import the payments; widen the range
A wrong match was confirmed	Scoring is a probability	Unmatch it and match manually
A partner from SAP is missing	Partners are not synced	Create it in Chapter 5