Improve Wait event Handling (#21)

* Add logic to advance waiting steps on event.
* Add advance pipeline step.
* Add documentation for new step.
* Update deps to latest.

doc/step/advance-pipeline/README.md

@@ -0,0 +1,39 @@
+# Advance Pipeline Step
+
+[cloud-manager-events]: https://www.adobe.io/apis/experiencecloud/cloud-manager/docs.html#!AdobeDocs/cloudmanager-api-docs/master/receiving-events.md
+
+This step will advance the Cloud Manager pipeline. That pipeline must be in the proper state based on the actions specified in the step configuration. If the Cloud Manager pipeline is not in a valid state for advancing, then this step will fail the build.
+
+**Note**: *This feature requires that either a [Pipeline Start Trigger](/doc/trigger/start-pipeline/README.md) or a [Pipeline Start Builder](/doc/builder/start-pipeline/README.md) is defined earlier in the pipeline.*
+
+## Usage
+
+Syntax:
+
+```
+acmAdvancePipeline(
+    actions: ['codeQuality', 'approval']
+)
+```
+
+### Optional Properties
+
+* `actions`: Optional list of [actions][cloud-manager-events] to which this step will respond.
+    * An empty list constitutes all actions.
+    * At this time only two values are valid: *codeQuality* and *approval* 
+
+## Use Cases
+
+### Advance Pipeline After Pause
+
+The intent of this step is to be used in combination with a `acmPipelineStepState` step where the Cloud Manager Pipeline has paused, and offline actions are necessary before advancing the remote Pipeline.
+
+For example: Wait for the Cloud Manager pipeline to reach the Approval step, allowing for out-of-band operations such as performance or load testing using third party tools. Once those are successful advance the pipeline. 
+
+```
+acmPipelineStepState(actions: ['approval'], waitingPause: false)
+...
+// Do other actions here
+...
+acmAdvancePipeline(actions: ['approval'])
+```

doc/step/pipeline-step-state/README.md

@@ -28,6 +28,8 @@ acmPipelineStepState(
   * An empty list constitutes all actions.
 * `advance`: Flag to indicate if this step should advance when receiving a *end* action.
 * `autoApprove`: Flag to indicate that when a *waiting* event occurs, it should advance the Cloud Manager build.
+* `waitingPause`: Flag to indicate if this step should pause the pipeline for user input, when a *waiting* event occurs.
+  * When using this property, the `advance` property should be set to *true*.
 
 ## Use Cases
 
@@ -39,6 +41,12 @@ This step can be used directly in a pipeline to wait for a specific Cloud Manage
 acmPipelineStepState(actions: ['codeQuality'])
 ```
 
+If you wait to wait for a specific step, but do not want this pipeline to pause for user input, then disable the waiting pause.
+
+```
+acmPipelineStepState(actions: ['codeQuality'], waitingPause: false)
+```
+
 ### Pipeline End Step Block
 
 This step can be used inside of a [Pipeline End Step](/doc/step/pipeline-end/README.md) block. In this context, the Jenkins pipeline will simply log each event as it arrives, advancing or not. 

pom.xml

@@ -34,15 +34,15 @@
     <inceptionYear>2020</inceptionYear>
 
     <organization>
-        <name></name>
+        <name>Adobe Inc</name>
     </organization>
 
     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>io.jenkins.tools.bom</groupId>
                 <artifactId>bom-2.249.x</artifactId>
-                <version>26</version>
+                <version>872.v03c18fa35487</version>
                 <scope>import</scope>
                 <type>pom</type>
             </dependency>
@@ -121,7 +121,7 @@
         <dependency>
             <groupId>commons-io</groupId>
             <artifactId>commons-io</artifactId>
-            <version>2.9.0</version>
+            <version>2.10.0</version>
         </dependency>
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>
@@ -138,7 +138,7 @@
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>
             <artifactId>git-client</artifactId>
-            <version>3.7.1</version>
+            <version>3.7.2</version>
         </dependency>
         <dependency>
             <groupId>org.jenkins-ci.plugins.workflow</groupId>

src/main/java/io/jenkins/plugins/adobe/cloudmanager/step/AdvancePipelineStep.java

@@ -0,0 +1,108 @@
+package io.jenkins.plugins.adobe.cloudmanager.step;
+
+/*-
+ * #%L
+ * Adobe Cloud Manager Plugin
+ * %%
+ * Copyright (C) 2020 - 2021 Adobe Inc.
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import javax.annotation.Nonnull;
+
+import hudson.AbortException;
+import hudson.Extension;
+import hudson.model.Run;
+import hudson.model.TaskListener;
+import io.adobe.cloudmanager.StepAction;
+import io.jenkins.plugins.adobe.cloudmanager.step.execution.AdvancePipelineExecution;
+import org.jenkinsci.plugins.workflow.steps.Step;
+import org.jenkinsci.plugins.workflow.steps.StepContext;
+import org.jenkinsci.plugins.workflow.steps.StepDescriptor;
+import org.jenkinsci.plugins.workflow.steps.StepExecution;
+import org.kohsuke.stapler.DataBoundConstructor;
+import org.kohsuke.stapler.DataBoundSetter;
+
+/**
+ * {@link Step} which will advance the current Cloud Manager pipeline execution in Cloud Manager Build context
+ *
+ * By default it will advance the Pipeline regardless of the current state. To narrow the scope, specify the {@code action} context.
+ */
+public class AdvancePipelineStep extends Step {
+  private static final List<StepAction> ALLOWED_ACTIONS = Arrays.asList(StepAction.codeQuality, StepAction.approval);
+
+  private List<StepAction> actions = new ArrayList<>(ALLOWED_ACTIONS);;
+
+  @DataBoundConstructor
+  public AdvancePipelineStep() {
+
+  }
+
+  /**
+   * List of actions to which this Step will respond. <strong>Default:</strong> {@code codeQuality} and {@code approval} actions.
+   */
+  @Nonnull
+  public List<StepAction> getActions() {
+    return actions;
+  }
+
+  @DataBoundSetter
+  public void setActions(List<StepAction> actions) {
+    if (actions != null && !actions.isEmpty()) {
+      this.actions = actions;
+    }
+  }
+
+  @Override
+  public StepExecution start(StepContext context) throws Exception {
+    for (StepAction action : actions) {
+      if (!ALLOWED_ACTIONS.contains(action)) {
+        throw new AbortException(Messages.ApprovePipelineStep_error_invalidAction(action));
+      }
+    }
+    return new AdvancePipelineExecution(context, actions);
+  }
+
+  @Extension
+  public static final class DescriptorImpl extends StepDescriptor {
+    @Override
+    public String getFunctionName() {
+      return "acmAdvancePipeline";
+    }
+
+    @Override
+    public Set<? extends Class<?>> getRequiredContext() {
+      return Collections.unmodifiableSet(new HashSet<>(Arrays.asList(Run.class, TaskListener.class)));
+    }
+
+    @Nonnull
+    @Override
+    public String getDisplayName() {
+      return Messages.ApprovePipelineStep_displayName();
+    }
+  }
+}

src/main/java/io/jenkins/plugins/adobe/cloudmanager/step/PipelineStepStateStep.java

@@ -33,6 +33,7 @@
 import java.util.Set;
 import javax.annotation.Nonnull;
 
+import hudson.AbortException;
 import hudson.Extension;
 import hudson.model.Run;
 import hudson.model.TaskListener;
@@ -65,14 +66,15 @@ public class PipelineStepStateStep extends Step {
   private List<StepAction> actions;
   private boolean autoApprove = false;
   private boolean advance = true;
+  private boolean waitingPause = true;
 
   @DataBoundConstructor
   public PipelineStepStateStep() {
 
   }
 
   /**
-   * List of actions to which this Step will respond. <strong>Default:</strong> all events.
+   * List of actions to which this Step will respond. <strong>Default:</strong> all actions.
    */
   @Nonnull
   public List<StepAction> getActions() {
@@ -111,6 +113,14 @@ public void setAdvance(boolean advance) {
     this.advance = advance;
   }
 
+  /**
+   * Flag to indicate if the pipeline should pause on a <strong>waiting</strong> event.
+   */
+  public boolean isWaitingPause() { return this.waitingPause; }
+
+  @DataBoundSetter
+  public void setWaitingPause(boolean waitingPause) { this.waitingPause = waitingPause; }
+
   /**
    * List all actions for the UI generator example.
    */
@@ -121,7 +131,10 @@ public StepAction[] listActions() {
 
   @Override
   public StepExecution start(StepContext context) throws Exception {
-    return new PipelineStepStateExecution(context, new HashSet<>(getActions()), autoApprove, advance);
+    if (autoApprove && !waitingPause) {
+      throw new AbortException(Messages.PipelineStepStateStep_failure_approveAndNoWait());
+    }
+    return new PipelineStepStateExecution(context, new HashSet<>(getActions()), autoApprove, advance, waitingPause);
   }
 
   @Extension

src/main/java/io/jenkins/plugins/adobe/cloudmanager/step/execution/AbstractStepExecution.java

@@ -137,7 +137,7 @@ protected FlowNode getFlowNode() throws IOException, InterruptedException {
   public final boolean start() throws Exception {
     validateData();
     doStart();
-    return false;
+    return !isAsync();
   }
 
   /**
@@ -176,4 +176,11 @@ public void doResume() throws IOException, InterruptedException {}
    * Subclasses should override this to require specific logic during a stop operation.
    */
   public void doStop() throws Exception {}
+
+  /**
+   * Subclasses should override this to indicate if it is an Async step. Default is {@code true}
+   */
+  public boolean isAsync() {
+    return true;
+  }
 }

src/main/java/io/jenkins/plugins/adobe/cloudmanager/step/execution/AdvancePipelineExecution.java

@@ -0,0 +1,79 @@
+package io.jenkins.plugins.adobe.cloudmanager.step.execution;
+
+/*-
+ * #%L
+ * Adobe Cloud Manager Plugin
+ * %%
+ * Copyright (C) 2020 - 2021 Adobe Inc.
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import java.util.List;
+
+import hudson.AbortException;
+import io.adobe.cloudmanager.CloudManagerApi;
+import io.adobe.cloudmanager.CloudManagerApiException;
+import io.adobe.cloudmanager.PipelineExecution;
+import io.adobe.cloudmanager.PipelineExecutionStepState;
+import io.adobe.cloudmanager.StepAction;
+import io.jenkins.plugins.adobe.cloudmanager.CloudManagerPipelineExecution;
+import org.jenkinsci.plugins.workflow.steps.StepContext;
+
+/**
+ * Execution for a {@link io.jenkins.plugins.adobe.cloudmanager.step.AdvancePipelineStep}, advancing the remote Cloud Manager pipeline.
+ */
+public class AdvancePipelineExecution extends AbstractStepExecution {
+
+  private static final long serialVersionUID = 1L;
+
+  private final List<StepAction> actions;
+
+  public AdvancePipelineExecution(StepContext context, List<StepAction> actions) {
+    super(context);
+    this.actions = actions;
+  }
+
+  @Override
+  public void doStart() throws Exception {
+    try {
+      CloudManagerPipelineExecution build = getBuildData().getCmExecution();
+      CloudManagerApi api = getApi();
+      PipelineExecution pe = api.getExecution(build.getProgramId(), build.getPipelineId(), build.getExecutionId());
+
+      PipelineExecutionStepState step = api.getCurrentStep(pe);
+      StepAction stepAction = StepAction.valueOf(step.getAction());
+      if (actions.contains(stepAction)) {
+        getTaskListener().getLogger().println(Messages.AdvancePipelineExecution_info_advancingPipeline(stepAction));
+        api.advanceExecution(pe);
+        getContext().onSuccess(null);
+      } else {
+        throw new AbortException(Messages.AdvancePipelineExecution_error_invalidPipelineState(stepAction));
+      }
+    } catch (CloudManagerApiException e) {
+      throw new AbortException(e.getLocalizedMessage());
+    }
+  }
+
+  @Override
+  public boolean isAsync() {
+    return false;
+  }
+}