DEV Community

Explorer
Explorer

Posted on

🚨 Resuming Stuck Joget Workflow Tools with API

#api #joget #lowcode

1. Overview

A critical issue in production environments is a workflow process halting when the Joget server unexpectedly goes down. While user activities are often easy to "Complete" manually via the Process Monitor, processes stuck specifically on a Tool Plugin (like an Email Tool or integration script) often resist normal completion attempts. The "Complete" button in the Process Monitor UI has no effect because a Tool is a server-side action, not a user-driven workflow task.

This post reveals the expert method, recommended by the Joget support team, to reliably force-resume or restart a stuck tool using the built-in JSON Monitoring API.

2. How It Works

When a tool element is stuck, the workflow engine typically believes the tool is still running or failed to complete its transaction. The solution is to issue a direct command to the workflow engine using the API endpoint specifically designed to manage activity states:

  • API Endpoint: The /monitoring/activity/start endpoint is used to push the activity back into the "ready" or "running" state, effectively forcing a re-execution of the tool's logic.
  • Authentication: The API requires administrative credentials (Basic Authentication or URL parameters) to ensure only authorized users can manipulate the workflow state.
  • Parameters: You must provide the specific Process Instance ID and the Activity Definition ID (the unique ID of the tool element in the workflow designer) to target the exact stuck step.

3. Full API Command

The API call uses the POST method and the /monitoring/activity/start/ endpoint.

POST /jw/web/json/monitoring/activity/start/(*:processId)/(*:activityDefId)
Enter fullscreen mode Exit fullscreen mode

Example Request (Using URL Authentication) 

http://localhost:8080/jw/web/json/monitoring/activity/start/24002_sampleApp_requestForm_approver_process/email_on_received?j_username=admin&j_password=admin
Enter fullscreen mode Exit fullscreen mode
Parameter Description Example Value
Method Must be used to change state. POST
processId The specific instance ID of the stalled workflow. 24002_sampleApp_requestForm_approver_process
activityDefId The unique ID of the stuck Tool Plugin. email_on_received
j_username/j_password Admin credentials for authorization. admin/admin

4. Example Use Cases

  • ✅ Integration Failure Recovery: A process is stuck on an API Tool Plugin because the external service was temporarily unavailable during a server interruption. Restarting the tool allows the integration to run again.
  • ✅ Notification Retries: An Email Tool failed to send due to a mail server timeout. The API call forces the email tool to re-execute and notify users correctly.
  • ✅ Data Sync Issues: A Script Tool responsible for data synchronization failed mid-execution and left the process in an ambiguous state. The API forces the engine to resolve the tool's status and advance the flow.

5. Customization Tips

  • 💡 Postman Environment: Create an environment variable in Postman for your base Joget URL (e.g., http://localhost:8080/jw) and your admin credentials to quickly execute these recovery calls without re-typing.
  • 💡 Basic Auth: For better security, use the Basic Auth tab in Postman or similar tools instead of passing credentials in the URL parameters, especially in non-local environments.
  • 💡 Logging: Before using this method, always consult the Joget server logs (wflow.log, catalina.out, etc.) to understand why the tool failed initially. Addressing the root cause is crucial to prevent recurrence.

6. Key Benefits

  • 🚀 Immediate Process Continuity: Quickly recovers stalled business processes without requiring manual data intervention or lengthy server restarts.
  • 🚀 High Data Integrity: By utilizing the official Monitoring API, you maintain the integrity of the workflow state within the Joget engine.
  • 🚀 Targeted Fix: Allows administrators to precisely fix specific process instances without affecting other running processes.

7. Security Note

🔒 API Exposure: This API grants the power to manipulate live workflow states. Never expose this endpoint publicly. Ensure that any system making calls to this API uses strong administrative credentials and operates exclusively within a secure network environment.

8. Final Thoughts

Understanding how to directly interface with the Joget workflow engine via the Monitoring JSON API is a critical skill for any advanced Joget administrator. It provides the necessary surgical precision to handle edge cases like stuck Tool Plugins, ensuring your production workflows remain resilient and functional even after unexpected interruptions.

Top comments (0)