Skip to main content

Hook

The Hook task is a powerful component in OSPROV's workflow builder that enables integration with custom code and external systems. It allows you to extend workflow functionality beyond standard tasks, execute custom business logic, and interact with external services at specific points in your workflow.

Purpose​

The Hook task is designed to:

  • Execute custom code during workflow execution
  • Integrate workflows with external systems and APIs
  • Implement complex business logic that standard tasks cannot handle
  • Automate actions based on workflow data
  • Control workflow routing based on custom conditions

Prerequisites​

Before you can use a Hook task in your workflow, you need to create a hook:

  1. Navigate to Hooks in the admin menu
  2. Click Create New Hook
  3. Define your hook with custom code or select a pre-built hook
  4. Save and publish your hook so it becomes available for use in workflows

Adding a Hook Task to Your Workflow​

Basic Setup​

  1. In the Workflow Builder, drag the Hook task from the task palette onto the canvas
  2. Click on the Hook task to open its configuration panel
  3. Configure the following required settings:
    • Hook: Select the hook you want to execute from the dropdown menu
    • Title for process: Enter a descriptive title that will appear in the submission history
    • Label for status: (Optional) Override the default status label

Hook Selection​

The hook selection determines what code will be executed:

  • Select from available hooks in your organization
  • Hooks can be custom code written specifically for your organization
  • Hooks can also be pre-built integrations with external systems
  • The selected hook will have access to the workflow submission data

Advanced Settings​

Visibility Settings​

  • Hide from submission history: When checked, prevents this hook task from appearing in the submission history
    • Useful for keeping the submission history focused on user actions
    • The hook still executes, but isn't visible in the history
    • Helps reduce clutter in complex workflows with many tasks

How Hook Tasks Work​

When a workflow reaches a Hook task:

  1. The system loads the selected hook
  2. The hook code is executed with access to the workflow submission data
  3. The hook can read and manipulate submission data
  4. The hook returns a status that determines the next workflow action
  5. The workflow proceeds based on the hook's return status

Unlike action tasks (Approve, Review, Process), Hook tasks:

  • Do not appear in users' task lists
  • Do not require any user action to complete
  • Execute automatically and immediately
  • Can control workflow routing based on their execution results

Hook Return States​

Hooks can return different states that control workflow behavior:

  1. continue or completed: The workflow proceeds to the next task normally
  2. reject: The workflow is rejected and typically returns to the applicant
  3. on-hold: The workflow is put on hold until manually resumed
  4. [number]: The workflow jumps to the specified task sequence number

This powerful control over workflow routing allows hooks to implement complex business logic and decision-making.

Use Cases​

External System Integration​

Use Hook tasks to integrate with external systems:

  • Send data to external APIs when a workflow reaches a certain stage
  • Retrieve information from external databases to enrich workflow data
  • Update external systems based on workflow decisions
  • Synchronize data between OSPROV and other business systems

Automated Data Processing​

Implement automated data processing with hooks:

  • Perform complex calculations based on form data
  • Validate submission data against business rules
  • Transform data into different formats
  • Generate reports or documents based on submission data

Conditional Workflow Routing​

Create sophisticated routing logic:

  • Route workflows based on complex business rules
  • Implement multi-factor decision making
  • Skip unnecessary tasks based on submission data
  • Route to different approval paths based on calculated risk scores

Automated Actions​

Trigger automated actions at specific workflow points:

  • Send custom notifications to stakeholders
  • Create records in other systems
  • Generate and store documents
  • Schedule follow-up activities

Best Practices​

  1. Error handling: Ensure hooks include proper error handling to prevent workflow disruption
  2. Performance optimization: Keep hook code efficient to avoid slowing down workflow execution
  3. Logging: Include appropriate logging in hooks for troubleshooting
  4. Security: Be careful with sensitive data in hooks, especially when interacting with external systems
  5. Testing: Thoroughly test hooks with different scenarios before using them in production workflows
  6. Documentation: Document hook functionality and expected behavior for future reference

Troubleshooting​

Hook Not Executing​

If a hook isn't executing:

  • Verify that the hook exists and is correctly configured
  • Check that the hook code doesn't contain syntax errors
  • Ensure the hook has the necessary permissions to access required resources
  • Check the system logs for any errors during hook execution

Hook Execution Errors​

If a hook is executing but producing errors:

  • Review the hook code for logical errors
  • Check that any external systems or APIs the hook interacts with are available
  • Verify that the hook has access to all required data
  • Test the hook in isolation to identify specific issues

Unexpected Workflow Routing​

If a hook is causing unexpected workflow routing:

  • Check the return state from the hook
  • Verify that the hook's logic for determining the return state is correct
  • Test the hook with different input data to understand its behavior
  • Review the workflow design to ensure it handles all possible hook return states
  • Hook Builder: Create and manage hooks in the admin interface
  • Conditional Tasks: Alternative for simpler conditional logic
  • Form Tasks with Auto-fill Hooks: Use hooks to pre-fill forms

Summary​

The Hook task is a powerful extension point in OSPROV's workflow builder that enables custom code execution, external system integration, and complex business logic implementation. By strategically placing hook tasks in your workflows, you can extend functionality beyond standard tasks and create sophisticated automated processes.

Unlike action tasks that require user interaction, hook tasks execute automatically and can control workflow routing based on their execution results. This makes them ideal for system integration, automated processing, and implementing complex business rules that standard tasks cannot handle.