refactor: template steps

core/flamingock-core-api/src/main/java/io/flamingock/api/template/AbstractChangeTemplate.java

@@ -20,6 +20,7 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 
 
@@ -31,8 +32,17 @@ public abstract class AbstractChangeTemplate<SHARED_CONFIGURATION_FIELD, APPLY_F
     protected String changeId;
     protected boolean isTransactional;
     protected SHARED_CONFIGURATION_FIELD configuration;
+    /**
+     * @deprecated Use {@link #stepsPayload} instead. Will be removed in a future release.
+     */
+    @Deprecated
     protected APPLY_FIELD applyPayload;
+    /**
+     * @deprecated Use {@link #stepsPayload} instead. Will be removed in a future release.
+     */
+    @Deprecated
     protected ROLLBACK_FIELD rollbackPayload;
+    protected List<TemplateStep<APPLY_FIELD, ROLLBACK_FIELD>> stepsPayload;
 
 
     private final Set<Class<?>> reflectiveClasses;
@@ -56,6 +66,7 @@ public AbstractChangeTemplate(Class<?>... additionalReflectiveClass) {
             reflectiveClasses.add(configurationClass);
             reflectiveClasses.add(applyPayloadClass);
             reflectiveClasses.add(rollbackPayloadClass);
+            reflectiveClasses.add(TemplateStep.class);
         } catch (ClassCastException e) {
             throw new IllegalStateException("Generic type arguments for a Template must be concrete types (classes, interfaces, or primitive wrappers like String, Integer, etc.): " + e.getMessage(), e);
         } catch (Exception e) {
@@ -83,16 +94,34 @@ public void setConfiguration(SHARED_CONFIGURATION_FIELD configuration) {
         this.configuration = configuration;
     }
 
+    /**
+     * @deprecated Use {@link #setStepsPayload(List)} instead. Will be removed in a future release.
+     */
+    @Deprecated
     @Override
     public void setApplyPayload(APPLY_FIELD applyPayload) {
         this.applyPayload = applyPayload;
     }
 
+    /**
+     * @deprecated Use {@link #setStepsPayload(List)} instead. Will be removed in a future release.
+     */
+    @Deprecated
     @Override
     public void setRollbackPayload(ROLLBACK_FIELD rollbackPayload) {
         this.rollbackPayload = rollbackPayload;
     }
 
+    @Override
+    public void setStepsPayload(List<TemplateStep<APPLY_FIELD, ROLLBACK_FIELD>> stepsPayload) {
+        this.stepsPayload = stepsPayload;
+    }
+
+    @Override
+    public List<TemplateStep<APPLY_FIELD, ROLLBACK_FIELD>> getStepsPayload() {
+        return stepsPayload;
+    }
+
     @Override
     public Class<SHARED_CONFIGURATION_FIELD> getConfigurationClass() {
         return configurationClass;

core/flamingock-core-api/src/main/java/io/flamingock/api/template/ChangeTemplate.java

@@ -15,6 +15,8 @@
  */
 package io.flamingock.api.template;
 
+import java.util.List;
+
 /**
  * Interface representing a reusable change template with configuration of type {@code CONFIG}.
  *
@@ -29,10 +31,26 @@ public interface ChangeTemplate<SHARED_CONFIG_FIELD, APPLY_FIELD, ROLLBACK_FIELD
 
     void setConfiguration(SHARED_CONFIG_FIELD configuration);
 
+    /**
+     * @deprecated Use {@link #setStepsPayload(List)} instead. Will be removed in a future release.
+     */
+    @Deprecated
     void setApplyPayload(APPLY_FIELD applyPayload);
 
+    /**
+     * @deprecated Use {@link #setStepsPayload(List)} instead. Will be removed in a future release.
+     */
+    @Deprecated
     void setRollbackPayload(ROLLBACK_FIELD rollbackPayload);
 
+    void setStepsPayload(List<TemplateStep<APPLY_FIELD, ROLLBACK_FIELD>> stepsPayload);
+
+    List<TemplateStep<APPLY_FIELD, ROLLBACK_FIELD>> getStepsPayload();
+
+    default boolean hasStepsPayload() {
+        return getStepsPayload() != null && !getStepsPayload().isEmpty();
+    }
+
     Class<SHARED_CONFIG_FIELD> getConfigurationClass();
 
     Class<APPLY_FIELD> getApplyPayloadClass();

core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplateStep.java

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2025 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.api.template;
+
+/**
+ * Represents a single step in a step-based change template.
+ *
+ * <p>Each step contains an {@code apply} operation that executes during the forward
+ * migration, and an optional {@code rollback} operation that executes if the step
+ * or a subsequent step fails.</p>
+ *
+ * <h2>YAML Structure</h2>
+ * <pre>{@code
+ * steps:
+ *   - apply:
+ *       type: createCollection
+ *       collection: users
+ *     rollback:
+ *       type: dropCollection
+ *       collection: users
+ *   - apply:
+ *       type: insert
+ *       collection: users
+ *       parameters:
+ *         documents:
+ *           - name: "John"
+ *     rollback:
+ *       type: delete
+ *       collection: users
+ *       parameters:
+ *         filter: {}
+ * }</pre>
+ *
+ * <h2>Rollback Behavior</h2>
+ * <ul>
+ *   <li>Rollback is optional - steps without rollback are skipped during rollback</li>
+ *   <li>When a step fails, all previously successful steps are rolled back in reverse order</li>
+ *   <li>Rollback errors are logged but don't stop the rollback process</li>
+ * </ul>
+ *
+ * @param <APPLY> the type of the apply payload
+ * @param <ROLLBACK> the type of the rollback payload
+ */
+public class TemplateStep<APPLY, ROLLBACK> {
+
+    private APPLY apply;
+    private ROLLBACK rollback;
+
+    public TemplateStep() {
+    }
+
+    public TemplateStep(APPLY apply, ROLLBACK rollback) {
+        this.apply = apply;
+        this.rollback = rollback;
+    }
+
+    /**
+     * Returns the apply payload for this step.
+     *
+     * @return the apply payload (required)
+     */
+    public APPLY getApply() {
+        return apply;
+    }
+
+    /**
+     * Sets the apply payload for this step.
+     *
+     * @param apply the apply payload
+     */
+    public void setApply(APPLY apply) {
+        this.apply = apply;
+    }
+
+    /**
+     * Returns the rollback payload for this step.
+     *
+     * @return the rollback payload, or null if no rollback is defined
+     */
+    public ROLLBACK getRollback() {
+        return rollback;
+    }
+
+    /**
+     * Sets the rollback payload for this step.
+     *
+     * @param rollback the rollback payload (optional)
+     */
+    public void setRollback(ROLLBACK rollback) {
+        this.rollback = rollback;
+    }
+
+    /**
+     * Checks if this step has a rollback payload defined.
+     *
+     * @return true if a rollback payload is defined
+     */
+    public boolean hasRollback() {
+        return rollback != null;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("TemplateStep{");
+        sb.append("apply=").append(apply);
+        if (rollback != null) {
+            sb.append(", rollback=").append(rollback);
+        }
+        sb.append('}');
+        return sb.toString();
+    }
+}

core/flamingock-core-commons/src/main/java/io/flamingock/internal/common/core/preview/TemplatePreviewChange.java

@@ -27,6 +27,7 @@ public class TemplatePreviewChange extends AbstractPreviewTask {
     private Object configuration;
     private Object apply;
     private Object rollback;
+    private Object steps;
 
     public TemplatePreviewChange() {}
 
@@ -44,6 +45,7 @@ public TemplatePreviewChange(String fileName,
                                  Object configuration,
                                  Object apply,
                                  Object rollback,
+                                 Object steps,
                                  TargetSystemDescriptor targetSystem,
                                  RecoveryDescriptor recovery) {
         super(id, order, author, templateName, runAlways, transactional, system, targetSystem, recovery, false);
@@ -52,6 +54,7 @@ public TemplatePreviewChange(String fileName,
         this.configuration = configuration;
         this.apply = apply;
         this.rollback = rollback;
+        this.steps = steps;
     }
 
     public String getFileName() {
@@ -98,12 +101,21 @@ public void setRollback(Object rollback) {
         this.rollback = rollback;
     }
 
+    public Object getSteps() {
+        return steps;
+    }
+
+    public void setSteps(Object steps) {
+        this.steps = steps;
+    }
+
     @Override
     public String toString() {
         return "TemplatePreviewChange{" + "profiles=" + profiles +
                 ", configuration=" + configuration +
                 ", apply=" + apply +
                 ", rollback=" + rollback +
+                ", steps=" + steps +
                 ", id='" + id + '\'' +
                 ", order='" + order + '\'' +
                 ", author='" + author + '\'' +

core/flamingock-core-commons/src/main/java/io/flamingock/internal/common/core/preview/builder/TemplatePreviewTaskBuilder.java

@@ -40,6 +40,7 @@ class TemplatePreviewTaskBuilder implements PreviewTaskBuilder<TemplatePreviewCh
     private Object configuration;
     private Object apply;
     private Object rollback;
+    private Object steps;
     private TargetSystemDescriptor targetSystem;
     private RecoveryDescriptor recovery;
 
@@ -108,6 +109,10 @@ public void setRecovery(RecoveryDescriptor recovery) {
         this.recovery = recovery;
     }
 
+    public void setSteps(Object steps) {
+        this.steps = steps;
+    }
+
     @Override
     public TemplatePreviewChange build() {
 
@@ -127,6 +132,7 @@ public TemplatePreviewChange build() {
                 configuration,
                 apply,
                 rollback,
+                steps,
                 targetSystem,
                 recovery);
     }
@@ -153,6 +159,7 @@ TemplatePreviewTaskBuilder setFromDefinition(ChangeTemplateFileContent templateT
         setConfiguration(templateTaskDescriptor.getConfiguration());
         setApply(templateTaskDescriptor.getApply());
         setRollback(templateTaskDescriptor.getRollback());
+        setSteps(templateTaskDescriptor.getSteps());
         setTransactional(templateTaskDescriptor.getTransactional() != null ? templateTaskDescriptor.getTransactional() : true);
         setRunAlways(false);
         setTargetSystem(templateTaskDescriptor.getTargetSystem());

core/flamingock-core-commons/src/main/java/io/flamingock/internal/common/core/template/ChangeTemplateFileContent.java

@@ -27,6 +27,7 @@ public class ChangeTemplateFileContent {
     private Object configuration;
     private Object apply;
     private Object rollback;
+    private Object steps;
     private TargetSystemDescriptor targetSystem;
     private RecoveryDescriptor recovery;
 
@@ -120,6 +121,14 @@ public void setRollback(Object rollback) {
         this.rollback = rollback;
     }
 
+    public Object getSteps() {
+        return steps;
+    }
+
+    public void setSteps(Object steps) {
+        this.steps = steps;
+    }
+
     public TargetSystemDescriptor getTargetSystem() {
         return targetSystem;
     }