Implementation:Langgenius Dify WorkflowVariableHooks

Knowledge Sources	Dify
Domains	Workflow Variables React Hooks
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for querying, inspecting, and managing workflow variables, provided by the Dify workflow service layer through a collection of TanStack Query hooks and service functions.

Description

The workflow variable hooks subsystem provides programmatic access to all three categories of workflow variables: inspection variables (runtime node outputs), conversation variables (per-session state), and system variables (built-in context). The system is split across two files:

Service functions in web/service/workflow.ts provide the raw data-fetching layer with pagination support for inspection variables.

TanStack Query hooks in web/service/use-workflow.ts wrap the service functions in React-friendly hooks with automatic caching, invalidation, and mutation support.

The key capabilities include:

• Paginated variable inspection across the entire workflow or scoped to a single node
• Conversation variable management with read, reset-to-default, and reset-to-last-run-value operations
• System variable access for viewing built-in runtime context variables
• Cache invalidation hooks for refreshing variable data after workflow runs or edits

Usage

Use the service functions directly when operating outside of React component context (e.g., in utility functions or non-React code). Use the TanStack Query hooks within React components for automatic data lifecycle management including loading states, error handling, and cache synchronization.

Code Reference

Source Location

• Repository: Dify
• Files:
  • web/service/workflow.ts (Lines 72-98) -- Service functions
  • web/service/use-workflow.ts (Lines 139-186) -- TanStack Query hooks

Signatures

Service Functions:

// Fetch all inspection variables with automatic pagination
export const fetchAllInspectVars = async (
  flowType: FlowType,
  flowId: string
): Promise<VarInInspect[]>

// Fetch inspection variables for a specific node
export const fetchNodeInspectVars = async (
  flowType: FlowType,
  flowId: string,
  nodeId: string
): Promise<VarInInspect[]>

TanStack Query Hooks:

// Get conversation variable values
export const useConversationVarValues = (
  flowType?: FlowType,
  flowId?: string
): UseQueryResult<VarInInspect[]>

// Invalidate conversation variable cache
export const useInvalidateConversationVarValues = (
  flowType: FlowType,
  flowId: string
): () => void

// Reset a conversation variable to its default value
export const useResetConversationVar = (
  flowType: FlowType,
  flowId: string
): UseMutationResult<unknown, unknown, string>

// Reset a variable to its last run value
export const useResetToLastRunValue = (
  flowType: FlowType,
  flowId: string
): UseMutationResult<{ value: any }, unknown, string>

// Get system variable values
export const useSysVarValues = (
  flowType?: FlowType,
  flowId?: string
): UseQueryResult<VarInInspect[]>

// Invalidate system variable cache
export const useInvalidateSysVarValues = (
  flowType: FlowType,
  flowId: string
): () => void

Import

// Service functions
import { fetchAllInspectVars, fetchNodeInspectVars } from '@/service/workflow'

// Hooks
import {
  useConversationVarValues,
  useInvalidateConversationVarValues,
  useResetConversationVar,
  useResetToLastRunValue,
  useSysVarValues,
  useInvalidateSysVarValues,
} from '@/service/use-workflow'

I/O Contract

Inputs (fetchAllInspectVars)

Name	Type	Required	Description
flowType	FlowType	Yes	The type of flow (e.g., app workflow or RAG pipeline), used to construct the API prefix.
flowId	string	Yes	The unique identifier of the workflow application.

Outputs (fetchAllInspectVars)

Name	Type	Description
items	VarInInspect[]	A flat array of all inspection variables across all nodes, automatically paginated and merged.

Inputs (fetchNodeInspectVars)

Name	Type	Required	Description
flowType	FlowType	Yes	The type of flow.
flowId	string	Yes	The workflow application identifier.
nodeId	string	Yes	The specific node whose variables to inspect.

Outputs (fetchNodeInspectVars)

Name	Type	Description
items	VarInInspect[]	Inspection variables scoped to the specified node.

Inputs (useResetConversationVar / useResetToLastRunValue)

Name	Type	Required	Description
varId	string	Yes	The unique identifier of the conversation variable to reset (passed as the mutation argument).

Dependencies

Dependency	Purpose
@tanstack/react-query	Provides useQuery and useMutation hooks for data fetching and cache management.
@/service/base (get, put, del)	HTTP helpers for GET, PUT, and DELETE requests.
@/service/use-base (useInvalid, useReset)	Utility hooks for TanStack Query cache invalidation and reset operations.

Usage Examples

import { fetchAllInspectVars } from '@/service/workflow'
import { useConversationVarValues, useResetConversationVar } from '@/service/use-workflow'

// Fetch all inspection variables (non-React context)
const allVars = await fetchAllInspectVars('app', appId)
allVars.forEach(v => console.log(v.name, v.value))

// In a React component: read conversation variables
function VariablePanel({ flowType, flowId }) {
  const { data: convVars, isLoading } = useConversationVarValues(flowType, flowId)
  const resetVar = useResetConversationVar(flowType, flowId)

  const handleReset = (varId: string) => {
    resetVar.mutate(varId)
  }

  if (isLoading) return <Spinner />
  return (
    <ul>
      {convVars?.map(v => (
        <li key={v.id}>
          {v.name}: {v.value}
          <button onClick={() => handleReset(v.id)}>Reset</button>
        </li>
      ))}
    </ul>
  )
}

Related Pages

Implements Principle

• Principle:Langgenius_Dify_Workflow_Variable_Management