0
# Scheduling and Triggers
1

2
CDAP provides a flexible scheduling system that allows programs to be triggered based on time, data availability, or other program status changes. The scheduling system supports constraints and complex trigger combinations.
3

4
## Capabilities
5

6
### Schedule Builder
7

8
Creates configurable schedules with triggers and constraints for automated program execution.
9

10
```java { .api }
11
/**
12
 * Builder for scheduling a program with triggers and constraints
13
 */
14
public interface ScheduleBuilder {
15
    ScheduleBuilder setDescription(String description);
16
    ScheduleBuilder setProperties(Map<String, String> properties);
17
    ScheduleBuilder setTimeout(long time, TimeUnit unit);
18
    
19
    // Constraints
20
    ConstraintProgramScheduleBuilder withConcurrency(int max);
21
    ScheduleBuilder withDelay(long delay, TimeUnit unit);
22
    ConstraintProgramScheduleBuilder withTimeWindow(String startTime, String endTime);
23
    ConstraintProgramScheduleBuilder withTimeWindow(String startTime, String endTime, TimeZone timeZone);
24
    ConstraintProgramScheduleBuilder withDurationSinceLastRun(long duration, TimeUnit unit);
25
    
26
    // Trigger types
27
    ScheduleCreationSpec triggerByTime(String cronExpression);
28
    ScheduleCreationSpec triggerOnPartitions(String datasetName, int numPartitions);
29
    ScheduleCreationSpec triggerOnPartitions(String datasetNamespace, String datasetName, int numPartitions);
30
    ScheduleCreationSpec triggerOnProgramStatus(String programNamespace, String application, String appVersion,
31
                                              ProgramType programType, String program, ProgramStatus... programStatuses);
32
    ScheduleCreationSpec triggerOnProgramStatus(String programNamespace, String application, ProgramType programType,
33
                                              String program, ProgramStatus... programStatuses);
34
    ScheduleCreationSpec triggerOnProgramStatus(String application, ProgramType programType,
35
                                              String program, ProgramStatus... programStatuses);
36
    ScheduleCreationSpec triggerOnProgramStatus(ProgramType programType, String program, ProgramStatus... programStatuses);
37
    ScheduleCreationSpec triggerOn(Trigger trigger);
38
}
39
```
40

41
### Constraint Program Schedule Builder
42

43
Extends ScheduleBuilder with additional constraint configuration for programs that require specific execution conditions.
44

45
```java { .api }
46
public interface ConstraintProgramScheduleBuilder extends ScheduleBuilder {
47
    // Inherits all ScheduleBuilder methods with additional constraint capabilities
48
}
49
```
50

51
### Trigger Factory
52

53
Provides factory methods for creating various types of triggers that can be combined in complex scheduling scenarios.
54

55
```java { .api }
56
public interface TriggerFactory {
57
    // Factory methods for creating triggers
58
}
59
```
60

61
### Schedule Creation Specification
62

63
Represents a complete schedule configuration ready for deployment.
64

65
```java { .api }
66
public class ScheduleCreationSpec {
67
    // Complete schedule specification
68
}
69
```
70

71
**Usage Examples:**
72

73
```java
74
import co.cask.cdap.api.schedule.ScheduleBuilder;
75
import co.cask.cdap.api.app.ProgramType;
76

77
// Time-based scheduling
78
ScheduleCreationSpec timeSchedule = buildSchedule("daily-job", ProgramType.WORKFLOW, "DataProcessing")
79
    .setDescription("Run data processing workflow daily at 2 AM")
80
    .withTimeWindow("02:00", "06:00")  // Only run between 2-6 AM
81
    .withConcurrency(1)  // Only one instance at a time
82
    .triggerByTime("0 0 2 * * ?");  // Cron: daily at 2 AM
83

84
// Partition-based scheduling
85
ScheduleCreationSpec partitionSchedule = buildSchedule("partition-processor", ProgramType.SPARK, "PartitionAnalysis")
86
    .setDescription("Process when new partitions are available")
87
    .withDelay(5, TimeUnit.MINUTES)  // Wait 5 minutes after trigger
88
    .triggerOnPartitions("input-dataset", 10);  // Trigger when 10+ new partitions
89

90
// Program status-based scheduling
91
ScheduleCreationSpec statusSchedule = buildSchedule("cleanup-job", ProgramType.MAPREDUCE, "CleanupJob")
92
    .setDescription("Run cleanup after main processing completes")
93
    .triggerOnProgramStatus(ProgramType.WORKFLOW, "MainWorkflow", ProgramStatus.COMPLETED);
94
```
95

96
## Trigger Types
97

98
### Time-based Triggers
99
- **Cron expressions**: Standard cron syntax for time-based scheduling
100
- **Time windows**: Restrict execution to specific time ranges
101
- **Delays**: Add delays between trigger and execution
102

103
### Data-based Triggers
104
- **Partition triggers**: Execute when new dataset partitions are available
105
- **Minimum partition count**: Wait for a specific number of new partitions
106

107
### Program Status Triggers
108
- **Status transitions**: React to other program completions or failures
109
- **Cross-application triggers**: Schedule based on programs in other applications
110
- **Cascading workflows**: Chain program executions based on status
111

112
### Constraints
113

114
Schedules can include constraints that must be satisfied before program execution:
115

116
- **Concurrency limits**: Control maximum parallel executions
117
- **Time windows**: Restrict execution to specific time periods
118
- **Duration since last run**: Prevent too-frequent executions
119
- **Timeouts**: Automatically cancel jobs that don't execute within time limits