Reference: AI Parsing¶

The AI Parsing module ensures automated data extraction from documents (invoices, receipts) using the external Apertia.ai service. It serves as a bridge between incoming files (email attachments, CRM documents) and structured entities in CRM (Invoices, Quotes).

Architecture and Data Flow¶

The processing process is asynchronous and controlled by AiParsingRecord entity states.

flowchart TD
    Email[Incoming Email] -->|Hook| Extractor[EmailExtractor]
    File[Document in CRM] -->|Action| Extractor

    Extractor -->|Create| Record[AiParsingRecord<br/>(Status: Draft)]
    Extractor -->|Upload| API[Apertia.ai API]

    API -->|200 OK| RecordSent[AiParsingRecord<br/>(Status: Sent)]

    API -.->|Webhook Callback| Webhook[ProcessExtractionCallback]
    Webhook -->|Update JSON| RecordReceived[AiParsingRecord<br/>(Status: Received)]

    RecordReceived -->|Trigger| Service[AiParsingRecordService]
    Service -->|Provider::process| RecordParsed[AiParsingRecord<br/>(Status: Parsed)]

    RecordParsed -->|Provider::apply| Entity[Target Entity<br/>(e.g. Received Invoice)]
    Entity -->|Link| RecordCompleted[AiParsingRecord<br/>(Status: Completed)]

Data Entities¶

AiParsingRecord¶

Main entity tracking the extraction process of a single document.

Field	Type	Description
`status`	Enum	Process state: `Draft` -> `Sent` -> `Received` -> `Parsed` -> `Completed` (or `Failed`).
`extractionEntityType`	Varchar	Target entity type (e.g. `SupplierInvoice`).
`parsedData`	JSON	Structured data after processing by provider (ready for CRM).
`receivedData`	JSON	Raw data from external AI service.
`attachments`	File	Original file being extracted.
`parent`	Link	Link to entity where extraction originated (e.g. Email).
`children`	Link	Link to created target entity.

System Components¶

Extractors¶

Obtain files and context from source entities. - EmailExtractor: Processes email attachments. Checks sender/recipient against allowed lists. - DocumentExtractor: Allows manual triggering on Document entity.

Providers (Logic Providers)¶

Define logic for specific target entity type. Map generic data from AI to specific CRM fields. - SupplierInvoiceProvider: Maps data to Received Invoice (supplier, RegID, items, amounts). - InvoiceLikeProvider: Generic class for invoice documents.

Integration (Apertia API)¶

Communication takes place with external endpoint defined in administration. - Authentication: Bearer Token. - Upload: Multipart POST request with file. - Callback: Webhook receiving JSON with extracted data.

Configuration (System Settings)¶

Settings in data/config.php or via Administration UI.

aiParsableEntityTypeList: List of entities allowed for extraction.
aiParsableEmails: Email addresses to automatically extract from.
aiParsingEntityMatchingMode: Matching mode (createIfNotFound - creates new Account, awaitExisting - waits for existing).
aiParsingAutoCompletionAfterParsing: If true, system attempts to automatically create target entity immediately after data reception (without user approval).