6.6 KiB
SOWAAN ERP INVOICE INTEGARTION
1 PURPOSE AND GUIDANCE
The purpose of this integration is to synchronize invoice transactions generated in IFS Cloud with Sowaan ERP.
2 BUSINESS REQUIREMENTS AND REFERENCES
3 INTRODUCTION
The integration supports the complete invoice lifecycle from invoice creation in IFS through invoice creation in Sowaan ERP, submission to ZATCA, status monitoring, and final completion or rejection tracking:
IFS Invoice Creation
↓
Invoice Detection
↓
Sowaan ERP Invoice Creation
↓
ZATCA Submission
↓
ZATCA Status Monitoring
↓
Final Completion / Rejection Tracking
4 SCOPE
Included Invoice Types
The integration currently supports:
• Customer Order Invoices
• Project Invoices
• Instant Invoices
Out of Scope
The integration does not create or maintain master data.
The following information is migrated independently through the approved Data Migration Tool process:
• Customers
• Customer Addresses
• Address References
• Master Data Information
5 HIGH LEVEL ARCHITECTURE
The integration follows the flow below:
IFS Cloud
↓
Main Integration Services
↓
Integration Payload Queue
↓
Child Integration Services
↓
Sowaan ERP
↓
ZATCA Submission
↓
ZATCA Status Monitoring
↓
Custom Integration Tracker
↓
IFS Invoice Pages
6 WORKFLOW CONFIGURATION MODEL
The integration is configuration-driven.
Workflow configurations determine which company-specific invoices are processed and define the connectivity required between IFS Cloud and Sowaan ERP.
7 POLLING PHASE
The polling phase is responsible for identifying invoices that are eligible for transmission.
No invoice is sent to Sowaan ERP during this phase. The objective is only to:
• Detect New Invoices
• Create Queue Records
• Prepare invoices for processing.
To prevent unnecessary reprocessing, invoices are retrieved using incremental filtering.
The framework evaluates: Last Execution Date, Maximum Previously Processed Invoice ID and Company Code.
This mechanism allows the framework to detect new invoices late arriving invoices and missed invoices.
8 PAYLOAD QUEUE
Once invoices are identified and queued for processing, the integration retrieves the latest invoice information from IFS, including invoice header information, invoice lines, and customer tax details required by Sowaan ERP. The invoice is then transformed into the required Sowaan ERP format and transmitted to Sowaan ERP for creation.
Following successful invoice creation, the integration submits the invoice to ZATCA through Sowaan ERP, periodically monitors the returned status, and updates the tracking information throughout the lifecycle until the invoice reaches a final state.
9 CUSTOMER INFORMATION HANDLING
Before invoice transmission, the integration retrieves customer tax information required by Sowaan ERP.
Examples include:
• Commercial Registration Number (CR)
• VAT Registration Number
The integration only consumes this information during processing.
Creation and maintenance of customer master data remain outside the integration scope and are handled through Data Migration activities.
10 STATE MACHINE
The integration uses a controlled state-based processing model to track invoice progress.
Preliminary: A new invoice has been detected and is awaiting processing.
Invoice Created: The invoice has been successfully created in Sowaan ERP.
Invoice Submitted to ZATCA: The invoice has been successfully submitted to ZATCA through Sowaan ERP.
Processing: ZATCA is still processing the invoice. The invoice remains active and will be checked again during subsequent executions.
Completed: The invoice has been successfully cleared, and the processing lifecycle has finished.
Rejected: The invoice was rejected during the ZATCA process. The invoice is removed from further processing and requires investigation.
11 ZATCA STATUS MONITORING
Following submission, the integration periodically queries Sowaan ERP to retrieve the latest ZATCA processing status.
Possible outcomes include:
• Processing
• Cleared
• Rejected
Invoices remain under monitoring until a final status is returned.
12 CUSTOM INTEGRATION TRACKING FRAMEWORK
To improve visibility and traceability, a dedicated invoice tracking mechanism was introduced within IFS.
Purpose: The tracking framework provides invoice-level monitoring independent of the technical processing logs. It allows business and support users to view integration progress directly from the corresponding invoice screen.
The tracking framework records:
• Company
• Invoice ID
• Invoice Number
• Invoice Type
• Sowaan Invoice Name
• Integration Status
• Integration Message
• ZATCA UUID
• ZATCA Status
• Created Date
The tracking information is automatically synchronized whenever the integration status changes.
Tracking information is displayed directly within the corresponding invoice pages in IFS, providing users with immediate visibility into the processing lifecycle without requiring access to integration logs.
13 ERROR HANDLING
The framework includes several protection mechanisms to ensure reliable processing.
Payload Locking: Prevents multiple processors from handling the same invoice simultaneously.
Task Locking: Prevents multiple executions of the same integration task.
Duplicate Detection: Prevents duplicate invoices from being processed multiple times.
Retry Management: Failed invoices can be retried automatically or manually according to the configured retry policy.
14 SUMMARY
The implemented solution provides:
• The implemented solution provides:
• Automated invoice synchronization from IFS Cloud to Sowaan ERP.
• Support for Customer Order, Project, and Instant Invoices.
• Multi-company configuration through workflow configurations.
• Controlled processing and retry handling.
• Full ZATCA submission and monitoring lifecycle.
• Custom invoice-level tracking within IFS.
• Direct visibility of integration progress from standard IFS invoice pages.
• Clear separation between transactional invoice processing and customer master-data migration.