Using Handlers

Handlers are the foundational tasks that power internal automation in Kinetic workflows. Whether you're sending an email, starting an approval, creating a submission, or transforming data, a handler is behind the scenes doing the work.

Handlers are pre-built pieces of logic written in Ruby and configured via XML. They're available out of the box and can be extended or modified by experienced workflow developers when needed.

---

What Is a Handler?

A handler is a reusable task that performs a specific function inside a workflow. Handlers can:

• Execute platform-native actions (like create/update/delete submissions)
• Trigger notifications or approval processes
• Pause a workflow while waiting for a response (deferred)
• Perform logic like data formatting or transformation

---

When to Use a Handler

Use a handler when your workflow needs to:

• Perform an action inside the Kinetic platform
• Start or respond to an approval
• Send an email or notification
• Execute system logic (such as triggering another workflow)

Handlers are most often used to represent internal system tasks as opposed to external integrations or custom-built routines.

---

Node Types in the Builder

When adding a node to your workflow, you'll choose from:

Handlers appear as standard buttons in the node selection list. You can filter or search for them by name.

---

Types of Handlers

Submission & Data Handlers

Used for creating and managing Kinetic submissions and handling structured data.

• Create Submission – Create a new submission for a form
• Kinetic Request CE Submission Update Observers – Notify relevant observers when a submission changes
• Generic File Upload CE Attachment – Attach files to a submission
• Utility CSV to XML – Convert CSV content into XML for easier processing
• Utility JSON to XML – Convert JSON content into XML

Messaging & Notifications

Used for sending communications or formatting messages.

• Kinetic Request CE Notification Template Send – Send templated messages using configured delivery channels
• Utility Message Formatter – Format values into a dynamic message structure

Workflow Control & Flow Handlers

Used to guide workflow execution across branches, loops, or pauses.

• Defer – Pause a workflow and wait for external input (deferred node)
• Join – Wait until multiple parallel branches complete before proceeding
• Junction – Wait until all required parent branches have completed
• Loop Head – Start a loop construct for repeating a block of nodes
• Loop Tail – Close the loop and evaluate continuation logic
• Wait – Delay execution for a specified time or condition
• Task Return – Exit and complete a workflow tree with results

---

Trigger & API Handlers

Used to start workflows, fire triggers, or make direct API calls.

• Create Trigger – Programmatically fire a trigger for a tree
• Kinetic Core API v1 – Make authenticated API calls to Kinetic Core
• Kinetic Task API v1 – Interact with the Task engine (v1)
• Kinetic Task API v2 – Interact with the Task engine (v2)

Utility & Logic Handlers

Used for transforming, echoing, or passing values between nodes.

• Echo – Pass values through without modification (useful for testing/debugging)

---

Deferred Handlers

Some handlers are deferred, meaning they pause the workflow until an external action completes or updates the node.

Deferred handlers enable:

• Approvals
• Wait states for human input
• Asynchronous process control

Connector Types for Deferred Nodes:

Use the Runs tab to monitor the status of deferred nodes in real time.

---

Importing or Creating Handlers

You can import, export, or create your own handlers via the Plugins > Task Handlers area of the platform.

🛠️

Want to build or modify your own handlers?

Check out our full guide here: Handler File Structure & Creation

---

Best Practices

• Use handlers for atomic system-level actions
• Use the Runs tab to validate behavior
• Use deferred handlers intentionally as they control process flow
• Organize and name handlers clearly for easier reuse

---

What's Next?

• Navigating the Workflow Builder
• Creating Connections and Operations
• Reusing Logic with Routines
• Learning How to Use Deferrals