TaskBlockService (engine-api 9.7.20 API)

All Known Subinterfaces:: TaskBlockServiceDefaults

@Path(value="/tasks/v2")
 @Consumes(value={"application/xml","application/json"})
 @Produces(value={"application/xml","application/json"})
public interface TaskBlockService

Manages tasks with blocks on the XL Deploy Server.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`abort(java.lang.String taskId)` Aborts an active task.
`StepBlockState`	`addPause(java.lang.String taskId, java.lang.String stepPath)` Add a pause step at the specified position.
`void`	`archive(java.lang.String taskId)` Archive an executed task.
`TaskWithBlock`	`assign(java.lang.String taskId, java.lang.String owner)` Assigns a task to a different user.
`void`	`cancel(java.lang.String taskId)` Cancels a stopped task.
`java.util.stream.Stream<TaskWithBlock>`	`export(org.joda.time.LocalDate begin, org.joda.time.LocalDate end, com.xebialabs.deployit.engine.api.dto.Paging paging)` Searches for tasks with detailed step information.
`void`	`forceCancel(java.lang.String taskId)` Force-cancels a stopped task - do a best-effort cleanup, continuing on when steps of an always-run phase fail
`java.util.List<TaskWithBlock>`	`getAllCurrentTasks(FetchMode fetchMode)` Returns all active tasks for all users.
`BlockState`	`getBlock(java.lang.String taskId, java.lang.String blockPath)` Returns a block by ID.
`java.util.List<TaskWithBlock>`	`getCurrentSatelliteTasks(java.lang.String satelliteId, FetchMode fetchMode)` Returns all active satellite tasks for all users.
`java.util.List<TaskWithBlock>`	`getMyCurrentTasks(FetchMode fetchMode)` Returns the active tasks of the logged in user.
`java.util.List<TaskWithBlock>`	`getMySatelliteTasks(java.lang.String satelliteId, FetchMode fetchMode)` Returns all active satellite tasks the logged in user.
`StepState`	`getStep(java.lang.String taskId, java.lang.String stepPath, org.joda.time.DateTime ifModifiedSince)` Retrieves information about a step.
`StepBlockState`	`getSteps(java.lang.String taskId, java.lang.String blockPath)` Returns a block with steps by ID.
`TaskWithBlock`	`getTask(java.lang.String taskId)` Returns a task by ID.
`java.util.stream.Stream<TaskWithBlock>`	`query(org.joda.time.LocalDate begin, org.joda.time.LocalDate end, com.xebialabs.deployit.engine.api.dto.Paging paging)` Searches for archived tasks without step information.
`void`	`schedule(java.lang.String taskId, org.joda.time.DateTime time)` Schedules a task.
`TaskWithBlock`	`skip(java.lang.String taskId, java.util.List<java.lang.String> stepIds)` Indicates that one or more steps should be skipped.
`void`	`start(java.lang.String taskId)` Starts a task.
`void`	`stop(java.lang.String taskId)` Gracefully stops an active task.
`TaskWithBlock`	`takeover(java.lang.String taskId, java.lang.String owner)` Takeover a task from the owner.
`TaskWithBlock`	`unskip(java.lang.String taskId, java.util.List<java.lang.String> stepIds)` Indicates that one or more steps should no longer be skipped, but executed.

Method Detail

getMyCurrentTasks

@GET
 @Path(value="current")
java.util.List<TaskWithBlock> getMyCurrentTasks(@QueryParam(value="fetchMode")
                                                                             FetchMode fetchMode)

Returns the active tasks of the logged in user. By default returns full tasks, but summary mode should be preferred for performance.

Parameters:: fetchMode - whether to strip block data for tasks or to do a full fetch
Returns:: a list of tasks with blocks.

getAllCurrentTasks

@GET
 @Path(value="current/all")
java.util.List<TaskWithBlock> getAllCurrentTasks(@QueryParam(value="fetchMode")
                                                                                  FetchMode fetchMode)

Returns all active tasks for all users. Only allowed for admin. By default returns full tasks, but summary mode should be preferred for performance.

Parameters:: fetchMode - whether to strip block data for tasks or to do a full fetch
Returns:: a list of tasks with blocks.

getMySatelliteTasks

@GET
 @Path(value="current/satellite")
java.util.List<TaskWithBlock> getMySatelliteTasks(@QueryParam(value="satelliteId")
                                                                                         java.lang.String satelliteId,
                                                                                         @QueryParam(value="fetchMode")
                                                                                         FetchMode fetchMode)

Returns all active satellite tasks the logged in user. By default returns full tasks, but summary mode should be preferred for performance.

Parameters:: satelliteId - the ID of the satellite where task will be executed; fetchMode - whether to strip block data for tasks or to do a full fetch
Returns:: a list of tasks with blocks.

getCurrentSatelliteTasks

@GET
 @Path(value="current/all/satellite")
java.util.List<TaskWithBlock> getCurrentSatelliteTasks(@QueryParam(value="satelliteId")
                                                                                                  java.lang.String satelliteId,
                                                                                                  @QueryParam(value="fetchMode")
                                                                                                  FetchMode fetchMode)

Returns all active satellite tasks for all users. Only allowed for admin. By default returns full tasks, but summary mode should be preferred for performance.

Parameters:: satelliteId - the ID of the satellite where task will be executed; fetchMode - whether to strip block data for tasks or to do a full fetch
Returns:: a list of tasks with blocks.

getTask

@GET
 @Path(value="{taskid}")
TaskWithBlock getTask(@PathParam(value="taskid")
                                                    java.lang.String taskId)

Returns a task by ID.

Parameters:: taskId - the ID of the task
Returns:: the task with blocks.
Permission:: Available only to admin and owner of the task

getBlock

@GET
 @Path(value="{taskid}/block/{blockPath}")
BlockState getBlock(@PathParam(value="taskid")
                                                                    java.lang.String taskId,
                                                                    @PathParam(value="blockPath")
                                                                    java.lang.String blockPath)

Returns a block by ID.

Parameters:: taskId - the ID of the task; blockPath - the ID of the block
Returns:: the block.
Permission:: Available only to admin and owner of the task

getSteps

@GET
 @Path(value="{taskid}/block/{blockPath}/step")
StepBlockState getSteps(@PathParam(value="taskid")
                                                                             java.lang.String taskId,
                                                                             @PathParam(value="blockPath")
                                                                             java.lang.String blockPath)

Returns a block with steps by ID.

Parameters:: taskId - the ID of the task; blockPath - the ID of the block
Returns:: the block with steps.
Permission:: Available only to admin and owner of the task

getStep
```
@GET
 @Path(value="{taskid}/step/{stepPath}")
StepState getStep(@PathParam(value="taskid")
                                                                java.lang.String taskId,
                                                                @PathParam(value="stepPath")
                                                                java.lang.String stepPath,
                                                                @HeaderParam(value="If-Modified-Since")
                                                                org.joda.time.DateTime ifModifiedSince)
```
Retrieves information about a step.

Parameters:

taskId - the ID of the task

stepPath - the path of the step in the block tree.

ifModifiedSince - the if-modified-since date in RFC 1123 (RFC 822 with 4-digit years) date format.

Returns:

XML containing a StepState if the step has not been modified since ifModifiedSince

RestDetails:

The call returns a response with status code of 304 (Not Modified) if the step has not been modified since ifModifiedSince, otherwise returns a status code of 200 (OK) and the XML containing a StepState.

Permission:

Available only to admin and owner of the task

ApiDetails:

The method throws a RuntimeException if the step has not been modified since ifModifiedSince, otherwise returns a StepState

start

@POST
 @Path(value="{taskid}/start")
void start(@PathParam(value="taskid")
                                                java.lang.String taskId)

Starts a task.

Parameters:: taskId - the ID of the task
Permission:: Available only to admin and owner of the task

schedule

@POST
 @Path(value="{taskid}/schedule")
void schedule(@PathParam(value="taskid")
                                                      java.lang.String taskId,
                                                      @QueryParam(value="time")
                                                      org.joda.time.DateTime time)

Schedules a task.

Parameters:: taskId - the ID of the task; time - the local time (including the local timezone) when the task should be started by the server.
Permission:: Available only to admin and owner of the task

stop

@POST
 @Path(value="{taskid}/stop")
void stop(@PathParam(value="taskid")
                                              java.lang.String taskId)

Gracefully stops an active task.

Parameters:: taskId - the ID of the task
Permission:: Available only to admin and owner of the task

abort

@POST
 @Path(value="{taskid}/abort")
void abort(@PathParam(value="taskid")
                                                java.lang.String taskId)

Aborts an active task.

Parameters:: taskId - the ID of the task
Permission:: Available only to admin and owner of the task

cancel

@DELETE
 @Path(value="{taskid}")
void cancel(@PathParam(value="taskid")
                                             java.lang.String taskId)

Cancels a stopped task.

Parameters:: taskId - the ID of the task
Permission:: Available only to admin and owner of the task

forceCancel
```
@DELETE
 @Path(value="{taskid}/force")
void forceCancel(@PathParam(value="taskid")
                                                        java.lang.String taskId)
```
Force-cancels a stopped task - do a best-effort cleanup, continuing on when steps of an always-run phase fail

Parameters:

taskId - the ID of the task

Permission:

Available only to admin

skip

@POST
 @Path(value="{taskid}/skip")
TaskWithBlock skip(@PathParam(value="taskid")
                                                       java.lang.String taskId,
                                                       java.util.List<java.lang.String> stepIds)

Indicates that one or more steps should be skipped.

Parameters:: taskId - the ID of the task; stepIds - the paths of the steps to skip
Returns:: a task
Permission:: task#skip_step

unskip

@POST
 @Path(value="{taskid}/unskip")
TaskWithBlock unskip(@PathParam(value="taskid")
                                                           java.lang.String taskId,
                                                           java.util.List<java.lang.String> stepIds)

Indicates that one or more steps should no longer be skipped, but executed.

Parameters:: taskId - the ID of the task; stepIds - the paths of the steps to unskip
Returns:: a task
Permission:: task#skip_step

addPause

@POST
 @Path(value="{taskid}/add-pause/{stepPath}")
StepBlockState addPause(@PathParam(value="taskid")
                                                                            java.lang.String taskId,
                                                                            @PathParam(value="stepPath")
                                                                            java.lang.String stepPath)

Add a pause step at the specified position.

Parameters:: taskId - the ID of the task; stepPath - the path of the step
Returns:: a task with full step information.
Permission:: Available only to admin and owner of the task

assign

@POST
 @Path(value="{taskid}/assign/{owner}")
TaskWithBlock assign(@PathParam(value="taskid")
                                                                   java.lang.String taskId,
                                                                   @PathParam(value="owner")
                                                                   java.lang.String owner)

Assigns a task to a different user.

Parameters:: taskId - the ID of the task; owner - the name of the user that will be the new owner of the task.
Returns:: the task.
Permission:: task#assign

takeover

@POST
 @Path(value="{taskid}/takeover/{owner}")
TaskWithBlock takeover(@PathParam(value="taskid")
                                                                       java.lang.String taskId,
                                                                       @PathParam(value="owner")
                                                                       java.lang.String owner)

Takeover a task from the owner. This will re-assign the task to your logged in user. This is the reverse of the assign(String, String) method, which allows you to re-assign a task.

Parameters:: taskId - the ID of the task to take over; owner - the current owner of the task
Returns:: the task you took over.
Permission:: task#takeover

query

@GET
 @Path(value="query")
java.util.stream.Stream<TaskWithBlock> query(@QueryParam(value="begindate")
                                                                        org.joda.time.LocalDate begin,
                                                                        @QueryParam(value="enddate")
                                                                        org.joda.time.LocalDate end,
                                                                        @BeanParam
                                                                        com.xebialabs.deployit.engine.api.dto.Paging paging)

Searches for archived tasks without step information.

Parameters:: begin - The first day we want to see tasks from, or null for no such limit.; end - The last day we want to see tasks from, or null for no such limit.; paging - Paging paging parameters to fetch tasks page by page.
Returns:: a list of tasks limited to maximum of value of xl.rest.api.maxPageSize per page. response header X-Total-Count determines the total number of tasks.
Permission:: report#view

export

@GET
 @Path(value="export")
java.util.stream.Stream<TaskWithBlock> export(@QueryParam(value="begindate")
                                                                          org.joda.time.LocalDate begin,
                                                                          @QueryParam(value="enddate")
                                                                          org.joda.time.LocalDate end,
                                                                          @BeanParam
                                                                          com.xebialabs.deployit.engine.api.dto.Paging paging)

Searches for tasks with detailed step information.

Parameters:: begin - The first day we want to see tasks from, or null for no such limit.; end - The last day we want to see tasks from, or null for no such limit.; paging - Paging paging parameters to fetch tasks page by page.
Returns:: a list of tasks limited to maximum of value of xl.rest.api.maxPageSize per page. response header X-Total-Count determines the total number of tasks.
Permission:: report#view

Interface TaskBlockService