Implementation:Apache Dolphinscheduler IWorkflowControlClient Trigger

Knowledge Sources	Apache DolphinScheduler
Domains	Workflow_Orchestration, Scheduling
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for triggering workflow executions using IWorkflowControlClient RPC methods with WorkflowManualTriggerRequest, WorkflowScheduleTriggerRequest, and WorkflowBackfillTriggerRequest DTOs.

Description

IWorkflowControlClient is an @RpcService interface providing three trigger methods: manualTriggerWorkflow, scheduleTriggerWorkflow, and backfillTriggerWorkflow. Each accepts a type-specific request DTO with workflow identification, execution parameters, and mode-specific fields (e.g., backfill time list, schedule time, timezone). The server-side implementation (WorkflowControlClient) validates the request and creates a command record.

Usage

Use manualTriggerWorkflow for user-initiated runs, scheduleTriggerWorkflow for cron-triggered runs, and backfillTriggerWorkflow for historical data processing. All are called via the RPC proxy mechanism.

Code Reference

Source Location

• Repository: dolphinscheduler
• File: dolphinscheduler-extract/dolphinscheduler-extract-master/src/main/java/org/apache/dolphinscheduler/extract/master/IWorkflowControlClient.java (L42-67)
• File: dolphinscheduler-extract/dolphinscheduler-extract-master/src/main/java/org/apache/dolphinscheduler/extract/master/transportor/workflow/WorkflowManualTriggerRequest.java (L35-39)
• File: dolphinscheduler-extract/dolphinscheduler-extract-master/src/main/java/org/apache/dolphinscheduler/extract/master/transportor/workflow/WorkflowBackfillTriggerRequest.java (L35-39)

Signature

@RpcService
public interface IWorkflowControlClient {
    @RpcMethod
    WorkflowManualTriggerResponse manualTriggerWorkflow(
        WorkflowManualTriggerRequest request);

    @RpcMethod
    WorkflowBackfillTriggerResponse backfillTriggerWorkflow(
        WorkflowBackfillTriggerRequest request);

    @RpcMethod
    WorkflowScheduleTriggerResponse scheduleTriggerWorkflow(
        WorkflowScheduleTriggerRequest request);
}

@Data @Builder
public class WorkflowManualTriggerRequest {
    private Integer userId;
    private Long workflowDefinitionCode;
    private Integer workflowDefinitionVersion;
    private List<Long> startNodes;
    private FailureStrategy failureStrategy;
    private TaskDependType taskDependType;
    private String workerGroup;
    private String tenantCode;
    private Flag dryRun;
}

@Data @Builder
public class WorkflowBackfillTriggerRequest {
    private Integer userId;
    private Long workflowCode;
    private List<String> backfillTimeList;
    private FailureStrategy failureStrategy;
    private String workerGroup;
    private String tenantCode;
}

Import

import org.apache.dolphinscheduler.extract.master.IWorkflowControlClient;
import org.apache.dolphinscheduler.extract.master.transportor.workflow.WorkflowManualTriggerRequest;
import org.apache.dolphinscheduler.extract.master.transportor.workflow.WorkflowBackfillTriggerRequest;
import org.apache.dolphinscheduler.extract.master.transportor.workflow.WorkflowScheduleTriggerRequest;

I/O Contract

Inputs

Name	Type	Required	Description
workflowDefinitionCode	Long	Yes	Unique code identifying the workflow definition
workflowDefinitionVersion	Integer	Yes	Version of the workflow to execute
userId	Integer	Yes	User initiating the trigger
failureStrategy	FailureStrategy	No	CONTINUE or END on task failure (default: CONTINUE)
workerGroup	String	No	Target worker group for task execution
backfillTimeList	List<String>	Backfill only	List of historical time periods to process

Outputs

Name	Type	Description
WorkflowManualTriggerResponse	DTO	Contains created workflow instance ID
WorkflowBackfillTriggerResponse	DTO	Contains created workflow instance IDs (one per backfill time)
WorkflowScheduleTriggerResponse	DTO	Contains created workflow instance ID

Usage Examples

Manual Trigger

IWorkflowControlClient client = Clients
    .withService(IWorkflowControlClient.class)
    .withHost(masterAddress);

WorkflowManualTriggerResponse response = client.manualTriggerWorkflow(
    WorkflowManualTriggerRequest.builder()
        .userId(1)
        .workflowDefinitionCode(123456L)
        .workflowDefinitionVersion(1)
        .failureStrategy(FailureStrategy.CONTINUE)
        .taskDependType(TaskDependType.TASK_POST)
        .workerGroup("default")
        .tenantCode("default")
        .dryRun(Flag.NO)
        .build()
);

Backfill Trigger

WorkflowBackfillTriggerResponse response = client.backfillTriggerWorkflow(
    WorkflowBackfillTriggerRequest.builder()
        .userId(1)
        .workflowCode(123456L)
        .backfillTimeList(Arrays.asList(
            "2024-01-01 00:00:00",
            "2024-01-02 00:00:00",
            "2024-01-03 00:00:00"
        ))
        .failureStrategy(FailureStrategy.CONTINUE)
        .workerGroup("default")
        .tenantCode("default")
        .build()
);

Related Pages

Implements Principle

• Principle:Apache_Dolphinscheduler_Workflow_Triggering