Release Snapshot Execution API

Snapshot Execution (Pipeline Stage Execution) data can be retrieved using this REST service. This service provides the current status of a snapshot and information about its progress through the pipeline.

Authentication - Use Basic Authentication for this API.

GET

This GET service will return the JSON representation of a snapshot execution given a snapshot Id.

In the case of replays, only the latest execution will be returned.

API URL

http://host:port/flexdeploy/rest/v1/releases/{releaseId}/snapshot/{snapshotId}/execution

Request

ParameterTypeRequiredDescription
snapshotIdURLYesPath parameter for the snapshot Id which is used to return a snapshot execution
releaseIdURLYesPath parameter for the release Id which contains the snapshot
gateNameQueryNo

If given, the Pipeline Stage Execution will only be returned if gateName is present in one of them.

All Pipeline Stage Executions that have been executed will be returned.

This will indicate that a gate matching that name was already passed, or is currently waiting for a schedule or approval.

stepNameQueryNo

If given, Pipeline Stage Executions will only be returned if stepName is present in one of them.

All Pipeline Stage Executions that have been executed will be returned.

This will indicate that a step matching that name was already passed, or is currently running.

environmentIdQueryNo

If given, Pipeline Stage Executions will be filtered to only this environment.

This filter is performed before filtering for gate and step names.

If a gate or step name is provided with this parameter, that gate or step must be present in this stage or the Pipeline Stage Executions array will always contain 0 elements.

Response

Snapshot Execution JSON objects can having the following attributes:

AttributeTypeDescription
pipelineExecutionIdLongThe Id of the Pipeline Execution

snapshotId

LongThe Id of the snapshot
pipelineExecutionStatusString

The status of the Pipeline Execution. Possible values are:

  • RUNNING- The pipeline is in progress now.
  • FAILED - The pipeline failed. It is eligible for replay.
  • ABORTED - The pipeline was aborted. It is eligible for replay.
  • OUT_OF_DATE - The pipeline was superseded by a later version that went through the gate ahead of it. It is NOT eligible for replay. To make these exact versions go through the pipeline, copy the snapshot by creating a new one derived from it.
  • SUCCESSFUL - The pipeline was completed.
pipelineStageExecutionsArray of pipelineStageExecutionsAn array of pipeline stages (environment) executions in the order that they appear on the pipeline definition page.

Elements of pipelineStageExecutions have the following attributes:

AttributeTypeDescription
environmentIdLong

The Id of this environment (stage)


environmentCodeString

The code of this environment (stage)

e.g. DEV

stageExecutionStatusString

The status of the Stage Execution. Possible values are:

  • RUNNING_GATES - Waiting for a gate to complete
  • FAILED - The stage failed. It is eligible for replay.
  • OUT_OF_DATE - The pipeline was superseded by a later version that went through the gate ahead of it. It is NOT eligible for replay. To make these exact versions go through the pipeline, copy the snapshot by creating a new one derived from it.
  • REJECTED - An approval was denied. It is eligible for replay.
  • GATES_FAILED - The gates failed. It is eligible for replay.
  • ABORTED - The pipeline failed. It is eligible for replay.
  • SUCCESSFUL - The pipeline execution completed this stage. This snapshot's result in this stage is final.
environmentNameString

The name of this environment (stage)

e.g. Dev

currentGateNameString

The name of the gate currently being processed, or null if not currently waiting on a gate.

It is possible that the next action will be to wait on a gate but that it hasn't begun to wait yet.

currentStepNameString

The name of the step currently being processed, or null if not currently running a step.

It is possible that the next action will be to perform a step but that it hasn't begun yet.

It is possible that multiple steps are currently being run. This will still return one result.

It is possible that all the child steps of a parent step have completed but that the thread that is processing step execution hasn't noticed yet. In this case the parent step will be returned even though all its children are complete. In a few moments the next step will be returned instead.

stageExecutionIdLongThe Id of the stageExecution
stepExecutionsArray of stepExecution

An array of steps in the order that they appear on the pipeline definition stage details page.

The json object was flattened so groups and parent and child steps are easier to parse.

environmentSortOrderIntegerThe order of the environment in the pipeline definition
gateExecutionsArray of gateExecutionAn array of gates in the order that they appear on the pipeline definition stage details page.

Elements of stepExecution have the following attributes:

AttributeTypeDescription
stepNameLong

The name of the step

stepTypeString

The type of the step:

  • STAGE_SCHEDULED_STEP
  • STAGE_GROUP_STEP
  • STAGE_DEPLOY_ALL_STEP
  • STAGE_UTILITY_WF_STEP
  • STAGE_MANUAL_STEP
  • STAGE_WAIT_STEP
  • STAGE_TEST_STEP
  • STAGE_EXECUTE_ALL_STEP
  • STAGE_NOTIFICATION_STEP
  • STAGE_TEST_ALL_STEP
  • STAGE_EXEC_ALL_UTILITY_STEP
  • STAGE_DEPLOY_STEP
stepStatusString
  • PRECOND_SKIPPED
  • RUNNING
  • FAILED
  • ABORTED
  • PENDING_APPROVAL
  • SUCCESSFUL
stepDescriptionStringThe description of the step
waitDurationLongThe wait time of a wait step
roleNameStringThe role associated to the step
cronExpressionString

The cron expression in a scheduled step. 

Starting in the 4.6 release, multiple Cron Expressions can be specified using semicolon as a delimeter. For example, 

0 0 11 ? * *;0 0 12 ? * *

is equivalent to

0 0 11-12 ? * *

This allows for Cron Expressions that are scheduled to run on the 2nd and 4th Friday which is not normally possible with Quartz Cron.

A new Admin Screen was added to test expressions in the Administration Menu on the Admin Operations Screen.

waitUntilDateTimestampThe wait until date of a wait step
stepOrderFloatThe order of the step in the stage

Elements of gateExecution have the following attributes:

AttributeTypeDescription
gateNameLong

The name of the gate

gateTypeString

The type of gate

  • STAGE_APPROVAL_GATE
  • STAGE_SCHEDULED_GATE
  • STAGE_EXT_APPROVAL_GATE
  • STAGE_TEST_GATE
gateStatusString
  • PENDING_APPROVAL
  • SCHEDULED
  • PRECOND_SKIPPED
  • FAILED
  • OUT_OF_DATE
  • REJECTED
  • ABORTED
  • SUCCESSFUL
gateDescriptionStringThe description of the gate
roleNameStringThe role associated to the gate
cronExpressionString

The cron expression in a schedule gate

Starting in the 4.6 release, multiple Cron Expressions can be specified using semicolon as a delimeter. For example, 

0 0 11 ? * *;0 0 12 ? * *

is equivalent to

0 0 11-12 ? * *

This allows for Cron Expressions that are scheduled to run on the 2nd and 4th Friday which is not normally possible with Quartz Cron.

A new Admin Screen was added to test expressions in the Administration Menu on the Admin Operations Screen.

gateOrderFloatThe order of the gate in the stage

Response Codes

HTTP CodeDescription
200Snapshot Execution was found and returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Snapshot or release not found
500Unexpected internal server error

Example

If a snapshot in our database had an id of 10401 and releaseId of 10201 and a GET request was sent to http://host:port/flexdeploy/rest/v1/releases/10201/snapshot/10401/execution 

A Snapshot Execution JSON object will be returned with snapshot execution information:

{
   "pipelineExecutionId":10404,
   "snapshotId":10401,
   "pipelineExecutionStatus":"RUNNING",
   "pipelineStageExecutions":[
      {
         "environmentId":11701,
         "environmentCode":"E",
         "stageExecutionStatus":"SUCCESSFUL",
         "environmentName":"e",
         "currentGateName":null,
         "currentStepName":null,
         "stageExecutionId":10405,
         "stepExecutions":[
            {
               "stepName":"asdfasdf",
               "stepType":"STAGE_DEPLOY_ALL_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":1
            }
         ],
         "environmentSortOrder":1,
         "gateExecutions":[
            {
               "gateName":"asdf",
               "gateType":"STAGE_EXT_APPROVAL_GATE",
               "gateStatus":"SUCCESSFUL",
               "gateDescription":null,
               "cronExpression":null,
               "roleName":null,
               "gateOrder":1
            },
            {
               "gateName":"qwewerq",
               "gateType":"STAGE_SCHEDULED_GATE",
               "gateStatus":"SUCCESSFUL",
               "gateDescription":"qwerqwerqwerqwerqwer",
               "cronExpression":"* * 12 * * ?",
               "roleName":"asdfasdfasdf",
               "gateOrder":2
            },
            {
               "gateName":"arraswer",
               "gateType":"STAGE_APPROVAL_GATE",
               "gateStatus":"SUCCESSFUL",
               "gateDescription":"asdferasdf",
               "cronExpression":null,
               "roleName":null,
               "gateOrder":3
            }
         ],

      },
      {
         "environmentId":11112,
         "environmentCode":"D",
         "stageExecutionStatus":"SUCCESSFUL",
         "environmentName":"d",
         "currentGateName":null,
         "currentStepName":null,
         "stageExecutionId":10411,
         "stepExecutions":[
            {
               "stepName":"s",
               "stepType":"STAGE_DEPLOY_ALL_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":1
            },
            {
               "stepName":"d22",
               "stepType":"STAGE_DEPLOY_ALL_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":2
            },
            {
               "stepName":"ggg",
               "stepType":"STAGE_GROUP_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":2
            },
            {
               "stepName":"d2",
               "stepType":"STAGE_DEPLOY_ALL_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":2.1
            },
            {
               "stepName":"test1",
               "stepType":"STAGE_TEST_ALL_STEP",
               "stepStatus":"SUCCESSFUL",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":3
            }
         ],
         "environmentSortOrder":2,
         "gateExecutions":[

         ],

      },
      {
         "environmentId":11703,
         "environmentCode":"G",
         "stageExecutionStatus":"RUNNING_STEPS",
         "environmentName":"g",
         "currentGateName":null,
         "currentStepName":null,
         "stageExecutionId":10420,
         "stepExecutions":[
            {
               "stepName":"44321",
               "stepType":"STAGE_WAIT_STEP",
               "stepStatus":"SCHEDULED",
               "stepDescription":null,
               "waitDuration":null,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":1550699280000,
               "stepOrder":1
            },
            {
               "stepName":"1234",
               "stepType":"STAGE_WAIT_STEP",
               "stepStatus":"SCHEDULED",
               "stepDescription":null,
               "waitDuration":1234,
               "roleName":null,
               "cronExpression":null,
               "waitUntilDate":null,
               "stepOrder":1
            }
         ],
         "environmentSortOrder":3,
         "gateExecutions":[
            {
               "gateName":"test",
               "gateType":"STAGE_TEST_GATE",
               "gateStatus":"SUCCESSFUL",
               "gateDescription":null,
               "cronExpression":null,
               "roleName":"asdfasdftest",
               "gateOrder":1
            }
         ],

      }
   ],
}

If a valid snapshot is is provided, but the query parameters do not yet have execution results, the returned response will be without stage/step/gate execution detail.

{
   "pipelineExecutionId":10404,
   "snapshotId":10401,
   "pipelineExecutionStatus":"RUNNING",
   "pipelineStageExecutions":[
   ]
}
The following macros are not currently supported in the footer:
  • style