Skip to main content

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:

FieldValue
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