SAP / ERP Integration

1. Business Summary

Centralized cron-driven synchronization of accounts, resources, client invoices, vendor invoices, internal invoices, and inbound payment endpoints; with retry queue, blacklist, and reconciliation.

2. Business Value

Keeps financial books aligned with operational reality; enables consolidated reporting.

3. Users / Stakeholders

Finance, executives, IT/integration owners.

4. Workflows

A. Cron processing
- getCrons() fetches SapCronJob.done=0; routes by entity to a sync function.
- On failure (status 2/3), getFailedItems() retries within configured intervals (10 min – 8 hr) until fail_num >= max_trial_number.

B. Account sync
- sapAccountSync() constructs CardCode AC_<id>, CardType=C, fields including UnifiedFederalTaxID, U_Payment_Behavior, U_Payment_Term, U_Account_Type, U_Parent, U_Beneficiary_Address/Country, BPLID; URL Sap.add_account or update_account.

C. Resource/vendor sync
- Sap.add_resource / update_resource.

D. Client invoice sync
- sapClientInvoiceSync() gates by submitted=1, sap_posted!=1, date ≥ 2018-01-01; loops jobs to assemble line items; reconciliation post-sync.

E. Vendor invoice sync
- sapVendorInvoiceSync() builds task-level line items with VatGroup, distribution rules, resource mapping.

F. Internal invoice sync
- IC transactions; CardCode logic depends on branch.

G. Inbound payment endpoints
- addClientPayment() and addVendorPayment() receive REST payloads from SAP.

5. Sub-Features

• SapCronJob queue table.
• sap_retrials retry table.
• sapSetLog audit logging.
• Configure-based endpoints/credentials.

6. Business Rules

• Date hardcoded cutoffs (≥ 2018-01-01).
• Currency default "##".
• Submitted/sap_posted gating.
• fail_num caps with cooling intervals.

7. Data Entities

SapCronJob, sap_retrials, sapSetLog, plus all synced business entities.

8. Entry Points

• Cron: SapController.getCrons + processCron.
• REST: addClientPayment, addVendorPayment.

9. Inputs & Outputs

• Inputs: queue items, REST payloads.
• Outputs: SAP requests, IDs persisted, logs, retries.

10. Integrations

• SAP HANA / SAP B1 (configurable endpoints).

11. Calculations / Logic

• Currency rate, tax lookups, distribution rule mapping.

12. Status Lifecycle

• Cron job: 0 pending → 1 success → 2 error → 3 retry → (4 skipped).

13. Permissions

• Service-to-service basic auth on REST endpoints.
• Internal cron called by scheduler.

14. Reports & KPIs

• Sync success rate, retry counts, failure reasons.

15. Risks & Observations

• Hard-coded credentials in Configure reads.
• Retry without exponential backoff.
• Idempotency by sap_id only — partial updates risky.
• No transaction guarantees across multi-line invoices + payment details.
• Hard-coded date and currency defaults.

16. Source Code Evidence

• app/Controller/SapController.php (~5,409 LOC).
• Endpoints under Configure::read('Sap.*').
• app/Controller/SecurityCronJobsController.php (queue handling pattern parallels SAP cron).