Job Troubleshooting

When a job fails, check parameters, permissions, input data, external connectivity, retry behavior, and whether the same operation works for a smaller test case.

Document the root cause and the corrective action so recurring incidents become easier to resolve.

Triage Flow

Start with these questions:

1. Did the job start?
2. Did the job finish?
3. Did it process the expected records?
4. Did it fail for all records or only some?
5. Is the error local, permission-related, data-related, or external-system-related?
6. Is retry safe?

Job Does Not Start

Check:

• user has permission to run the job,
• job ID or URL is correct,
• job is registered in configuration,
• required parameters are present,
• scheduler or queue is running,
• backend service is available,
• no JavaScript or dialog validation blocks execution.

If a parameter is optional from a business perspective, it should not be required by the dialog.

Job Starts but Processes No Data

Check:

• filters and date ranges,
• selected client or mandate,
• source folder or mailbox,
• search query or DQL,
• object lifecycle states,
• whether data was already processed,
• whether the job runs under the expected user or service user.

Job Fails for One Record

When only one record fails, compare it with a working record.

Check:

• mandatory fields,
• client/accounting area,
• address and bank data,
• currency and daily rate,
• tax code,
• permissions,
• lifecycle state,
• attached file availability,
• external identifiers.

Job Fails for All Records

When all records fail, suspect configuration or connectivity.

Check:

• external service availability,
• credentials,
• MQTT topic or agent status,
• ERP license or endpoint,
• global mapping,
• database connection,
• recently changed configuration.

MQTT Agent Error

For MQTT-based jobs, capture:

• action name,
• request topic,
• response topic,
• request payload,
• response payload,
• query_id if SQL queries are used,
• agent log excerpt,
• agent configuration,
• external system response.

Typical issue:

query_id parameter is required

This means the request reached the agent, but the payload was incomplete for the requested action.

ERP Export Error

For ERP export failures, capture:

• invoice object ID,
• ERP connector name,
• payload or generated file,
• ERP response,
• address and bank mapping,
• currency and amount fields,
• tax code,
• booking rows,
• current lifecycle state.

Before retrying, verify whether the ERP already created a booking.

Permission Error

For errors such as:

no write permission for object with id <obj_id>

check:

• current user,
• user roles,
• object obj_acl,
• lifecycle state,
• workflow assignee fields,
• client role,
• accounting area,
• substitution logic,
• whether the action needs elevated service-user execution.

Support Case Template

Use this structure when handing a case to development or second-level support:

Field	Value
Customer/installation
Environment
Timestamp
User
Job/action
URL or job ID
Object ID
Expected result
Actual result
Error message
Relevant log excerpt
Retry safe?	Yes/No/Unknown
Working comparison