Logs

Logs are the first source for troubleshooting processing errors.

Relevant log areas include web requests, jobs, invoice processing, fulltext, ERP connectors, MQTT agents, e-mail import, and PDF/OCR conversion.

What to Capture

For every support case, capture:

• timestamp with timezone,
• affected user,
• affected object ID,
• request URL or job ID,
• action that was executed,
• relevant log excerpt before and after the error,
• stack trace if available,
• expected behavior,
• whether the issue is reproducible.

For Invoice cases, also capture lifecycle state, client, accounting area, assignees, and object ACL when permissions are involved.

Important Log Areas

Area	Typical logger or source	Used for
Web request	web server, Tornado, WebUI logs	Page errors, form actions, AJAX calls.
Invoice processing	invoice logs	Import, analysis, accounting, workflow, export.
Jobs	job logs or scheduler logs	Manual and scheduled job execution.
Fulltext	fulltext logs	Indexing, search, OCR text availability.
E-mail import	mail/import logs	Mailbox access, message processing, attachments.
ERP connector	connector-specific logs	Payloads, responses, mapping errors.
MQTT agent	agent logs and response payloads	Local connector actions, SQL queries, ERP calls.
PDF/OCR	conversion logs	Preview, OCR, PDF conversion, image processing.

Reading Stack Traces

A stack trace usually contains:

• the top-level request or template,
• the helper or job function that failed,
• the lower-level service or API call,
• the actual exception.

Do not stop at the first wrapper exception. The useful cause is often the inner exception, for example no write permission for object, query_id parameter is required, or an ERP-specific validation response.

Log Patterns

Log pattern	Likely meaning
no write permission for object	User can see the object but cannot perform the requested write or state change.
query_id parameter is required	MQTT or SQL-agent request is missing a required parameter.
unexpected keyword argument	Caller and implementation use incompatible method signatures.
set lifecycle state: 99 system error	Processing failed and moved the object to a system error state.
indexed: <id>	Fulltext indexed a document or object. It does not prove business processing succeeded.

Logging Quality

Good logs should contain enough context to reproduce the issue without exposing secrets.

Useful context:

• object ID,
• user or service account,
• job/action name,
• client/accounting area,
• external system,
• response status,
• clear error reason.

Avoid logging passwords, tokens, full payment files, or unnecessary personal data.