Package com.xebialabs.xlrelease.api.v1

# Interface TaskApi

All Superinterfaces:
  `ApiService`

@Path("/api/v1/tasks/") @Consumes("application/json") @Produces("application/json") public interface TaskApi extends ApiService
Operations on tasks.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `SERVICE_NAME`

  ### Fields inherited from interface com.xebialabs.xlrelease.api.ApiService

  `DEFAULT_RESULTS_PER_PAGE, DEFAULT_RESULTS_PER_PAGE_STRING, DEPTH, ORDER_BY, PAGE, PAGE_IS_OFFSET, RESULTS_PER_PAGE, ROLE_IDS_DATA`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Task`
  `abortTask(String taskId, Comment comment)`
  Aborts a task.
  `Task`
  `abortTask(String taskId, String comment)`
  Aborts a task.
  `Attachment`
  `addAttachment(String taskId, String fileName, byte[] fileByteArray)`
  Adds one attachment files to a task.
  `List<Attachment>`
  `addAttachments(String taskId, jakarta.servlet.http.HttpServletRequest request)`
  Adds one or more attachment files to a task, serialized in XLR format.
  `GateCondition`
  `addCondition(String taskId, Condition condition)`
  Adds a condition to a gate task.
  `Dependency`
  `addDependency(String taskId, String targetId)`
  Adds a dependency to a gate task.
  `Task`
  `addTask(String containerId, Task task)`
  Adds a task to a phase or a container task.
  `Task`
  `addTask(String containerId, Task task, Integer position)`
  Adds a task to a phase or a container task.
  `Task`
  `assignTask(String taskId, String username)`
  Assigns a task to a user.
  `Task`
  `changeTaskType(String taskId, String targetType)`
  Changes a task type to the target type.
  `Task`
  `commentTask(String taskId, Comment comment)`
  Adds a comment to a task.
  `Task`
  `commentTask(String taskId, String comment)`
  Adds a comment to a task.
  `Task`
  `completeTask(String taskId, Comment comment)`
  Completes a task.
  `Task`
  `completeTask(String taskId, String comment)`
  Completes a task.
  `Task`
  `copyTask(String taskId, String targetContainerId, int targetPosition)`
  Copy a task
  `void`
  `delete(String taskId)`
  Deletes a task.
  `void`
  `deleteAttachment(String taskId, String attachmentId)`
  Deletes an attachment from a task.
  `void`
  `deleteCondition(String conditionId)`
  Deletes a condition from a gate task.
  `void`
  `deleteDependency(String dependencyId)`
  Deletes a dependency from a gate task.
  `Task`
  `failTask(String taskId, Comment comment)`
  Fails a task.
  `Task`
  `failTask(String taskId, String comment)`
  Fails a task.
  `Task`
  `getTask(String taskId)`
  Returns a task by ID.
  `List<Variable>`
  `getVariables(String taskId)`
  Return the variables used by the task input fields.
  `void`
  `lockTask(String taskId)`
  Locks a task.
  `Comment`
  `newComment(String commentText)`
  Factory method to create a new instance of a Comment.
  `Task`
  `newTask()`
  Factory method to create a new instance of a Manual Task.
  `Task`
  `newTask(String type)`
  Factory method to create a new instance of a Task object.
  `Task`
  `reopenTask(String taskId, Comment comment)`
  Reopen a task that has been completed in advance.
  `Task`
  `reopenTask(String taskId, String comment)`
  Reopen a task that has been completed in advance.
  `Task`
  `retryTask(String taskId, Comment comment)`
  Retry failed task.
  `Task`
  `retryTask(String taskId, String comment)`
  Retry failed task.
  `List<Task>`
  `searchTasksByTitle(String taskTitle, String phaseTitle, String releaseId)`
  Search tasks by title within a release.
  `default String`
  `serviceName()`
  `Task`
  `skipTask(String taskId, Comment comment)`
  Skips a task.
  `Task`
  `skipTask(String taskId, String comment)`
  Skips a task.
  `Task`
  `start(Task task, List<Variable> variables)`
  Starts a task that is waiting for input.
  `Task`
  `start(String taskId, Comment comment)`
  Start pending task.
  `Task`
  `start(String taskId, StartTask startTask)`
  Starts a task that is waiting for input.
  `Task`
  `start(String taskId, String comment)`
  Start pending task.
  `void`
  `unlockTask(String taskId)`
  Unlocks a task.
  `GateCondition`
  `updateCondition(GateCondition condition)`
  Updates a condition on a gate task.
  `GateCondition`
  `updateCondition(String conditionId, Condition condition)`
  Updates a condition on a gate task.
  `List<Variable>`
  `updateInputVariables(String taskId, List<Variable> variables)`
  Updates the variables values of a UserInputTask It doesn't remove or add new variables
  `Task`
  `updateTask(Task task)`
  Updates a task.
  `Task`
  `updateTask(String taskId, Task task)`
  Updates a task.
  `Task`
  `updateTask(String taskId, Task task, boolean overrideLock)`
  Updates a task.

- ## Field Details

  - ### SERVICE_NAME

    static final String SERVICE_NAME
    See Also:
      - Constant Field Values

- ## Method Details

  - ### serviceName

    default String serviceName()
    Specified by:
      `serviceName` in interface `ApiService`

  - ### addAttachments

    @POST @Path("{taskId:.*/Task[^/]*}/attachments") @Consumes("multipart/form-data") List<Attachment> addAttachments(@PathParam("taskId") String taskId, @Context jakarta.servlet.http.HttpServletRequest request) throws IOException
    Adds one or more attachment files to a task, serialized in XLR format.
    Parameters:
      `taskId` - the task identifier.
      `request` - multipart/form-data request with attachment file.
    Returns:
      the domain objects of the uploaded attachments.
    Throws:
      `IOException`

  - ### addAttachment

    Attachment addAttachment(String taskId, String fileName, byte[] fileByteArray) throws IOException
    Adds one attachment files to a task.
    Throws:
      `IOException`

  - ### deleteAttachment

    @DELETE @Path("{taskId:.*/Task[^/]*}/attachments/{attachmentId:.*/Attachment[^/]*}") void deleteAttachment(@PathParam("taskId") String taskId, @PathParam("attachmentId") String attachmentId)
    Deletes an attachment from a task.
    Parameters:
      `taskId` - the task identifier.
      `attachmentId` - the attachment identifier.

  - ### getTask

    @GET @Path("/{taskId:.*/Task[^/]*}") Task getTask(@PathParam("taskId") String taskId)
    Returns a task by ID.
    Parameters:
      `taskId` - the task identifier
    Returns:
      the task which has the given identifier.

  - ### copyTask

    @POST @Path("{taskId:.*/Task[^/]*}/copy") Task copyTask(@PathParam("taskId") String taskId, @QueryParam("targetContainerId") String targetContainerId, @QueryParam("targetPosition") int targetPosition)
    Copy a task
    Parameters:
      `taskId` - the task identifier.
      `targetContainerId` - identifier of the target task container.
      `targetPosition` - the position where to copy the task to. Cannot be `< 0` and also `not >= container.size()`
    Returns:
      the copy of the task

  - ### updateTask

    Task updateTask(Task task)
    Updates a task.
    Parameters:
      `task` - new contents of the task.
    Returns:
      the updated task.

  - ### updateTask

    @PUT @Path("/{taskId:.*/Task[^/]*}") Task updateTask(@PathParam("taskId") String taskId, Task task)
    Updates a task.
    Parameters:
      `taskId` - the task identifier.
      `task` - new contents of the task.
    Returns:
      the updated task.

  - ### updateTask

    Task updateTask(String taskId, Task task, boolean overrideLock)
    Updates a task.
    Parameters:
      `taskId` - the task identifier.
      `task` - new contents of the task.
      `overrideLock` - enables override of locked task.
    Returns:
      the updated task.

  - ### changeTaskType

    @POST @Path("{taskId:.*/Task[^/]*}/changeType") Task changeTaskType(@PathParam("taskId") String taskId, @QueryParam("targetType") String targetType)
    Changes a task type to the target type. Target type can be one of core task types such as "xlrelease.GateTask" or a custom script definition type, such as "jenkins.Build".
    Parameters:
      `taskId` - the identifier of the task.
      `targetType` - the new task type.
    Returns:
      task with new type.

  - ### addTask

    Task addTask(String containerId, Task task)
    Adds a task to a phase or a container task.
    Parameters:
      `containerId` - the identifier of the task container: either a `Phase`, a `ParallelGroup` or a `SequentialGroup`.
      `task` - the task to add.
    Returns:
      the added task.

  - ### addTask

    @POST @Path("/{containerId:.*?}/tasks") Task addTask(@PathParam("containerId") String containerId, Task task, @QueryParam("position") Integer position)
    Adds a task to a phase or a container task.
    Parameters:
      `containerId` - the identifier of the task container: either a `Phase`, a `ParallelGroup` or a `SequentialGroup`.
      `task` - the task to add.
      `position` - the position at which the task will be added.
    Returns:
      the added task.

  - ### completeTask

    @POST @Path("/{taskId:.*/Task[^/]*}/complete") Task completeTask(@PathParam("taskId") String taskId, Comment comment)
    Completes a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'complete' action.
    Returns:
      the updated task.

  - ### completeTask

    Task completeTask(String taskId, String comment)
    Completes a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'complete' action.
    Returns:
      the updated task.

  - ### skipTask

    @POST @Path("/{taskId:.*/Task[^/]*}/skip") Task skipTask(@PathParam("taskId") String taskId, Comment comment)
    Skips a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'skip' action.
    Returns:
      the updated task.

  - ### skipTask

    Task skipTask(String taskId, String comment)
    Skips a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'skip' action.
    Returns:
      the updated task.

  - ### failTask

    @POST @Path("/{taskId:.*/Task[^/]*}/fail") Task failTask(@PathParam("taskId") String taskId, Comment comment)
    Fails a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'fail' action.
    Returns:
      the updated task.

  - ### failTask

    Task failTask(String taskId, String comment)
    Fails a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'fail' action.
    Returns:
      the updated task.

  - ### abortTask

    @POST @Path("/{taskId:.*/Task[^/]*}/abort") Task abortTask(@PathParam("taskId") String taskId, Comment comment)
    Aborts a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'abort' action.
    Returns:
      the updated task.

  - ### abortTask

    Task abortTask(String taskId, String comment)
    Aborts a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'abort' action.
    Returns:
      the updated task.

  - ### retryTask

    @POST @Path("/{taskId:.*/Task[^/]*}/retry") Task retryTask(@PathParam("taskId") String taskId, Comment comment)
    Retry failed task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'retry' action.
    Returns:
      the updated task.

  - ### retryTask

    Task retryTask(String taskId, String comment)
    Retry failed task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'retry' action.
    Returns:
      the updated task.

  - ### start

    @POST @Path("/{taskId:.*/Task[^/]*}/startNow") Task start(@PathParam("taskId") String taskId, Comment comment)
    Start pending task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'startNow' action.
    Returns:
      the updated task.

  - ### start

    Task start(String taskId, String comment)
    Start pending task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'startNow' action.
    Returns:
      the updated task.

  - ### start

    Task start(Task task, List<Variable> variables)
    Starts a task that is waiting for input.
    Parameters:
      `task` - the task to be started.
      `variables` - the input variables required to start a task.
    Returns:
      the updated task.

  - ### start

    @POST @Path("/{taskId:.*/Task[^/]*}/start") Task start(@PathParam("taskId") String taskId, StartTask startTask)
    Starts a task that is waiting for input.
    Parameters:
      `taskId` - the task identifier.
      `startTask` - the object with parameters required to start a task, e.g. variables.
    Returns:
      the updated task.

  - ### reopenTask

    @POST @Path("/{taskId:.*/Task[^/]*}/reopen") Task reopenTask(@PathParam("taskId") String taskId, Comment comment)
    Reopen a task that has been completed in advance.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'reopen' action.
    Returns:
      the updated task.

  - ### reopenTask

    Task reopenTask(String taskId, String comment)
    Reopen a task that has been completed in advance.
    Parameters:
      `taskId` - the task identifier.
      `comment` - a comment describing the 'reopen' action.
    Returns:
      the updated task.

  - ### getVariables

    @GET @Path("/{taskId:.*/Task[^/]*}/variables") List<Variable> getVariables(@PathParam("taskId") String taskId)
    Return the variables used by the task input fields.
    Parameters:
      `taskId` - the task identifier.
    Returns:
      input variables used by the task.

  - ### updateInputVariables

    @PUT @Path("/{taskId:.*/Task[^/]*}/variables") List<Variable> updateInputVariables(@PathParam("taskId") String taskId, List<Variable> variables)
    Updates the variables values of a UserInputTask It doesn't remove or add new variables
    Parameters:
      `taskId` - the task identifier.
      `variables` - the variables with values to be updated.
    Returns:
      the updated variables.

  - ### commentTask

    @POST @Path("/{taskId:.*/Task[^/]*}/comment") Task commentTask(@PathParam("taskId") String taskId, Comment comment)
    Adds a comment to a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - the comment text to be added to the task.
    Returns:
      the updated task.

  - ### commentTask

    Task commentTask(String taskId, String comment)
    Adds a comment to a task.
    Parameters:
      `taskId` - the task identifier.
      `comment` - the comment text to be added to the task.
    Returns:
      the updated task.

  - ### assignTask

    @POST @Path("/{taskId:.*/Task[^/]*}/assign/{username: .*?}") Task assignTask(@PathParam("taskId") String taskId, @PathParam("username") String username)
    Assigns a task to a user.
    Parameters:
      `taskId` - the task identifier.
      `username` - the username of the user the task will be assigned to.
    Returns:
      the updated task.

  - ### searchTasksByTitle

    @GET @Path("/byTitle") List<Task> searchTasksByTitle(@QueryParam("taskTitle") String taskTitle, @QueryParam("phaseTitle") String phaseTitle, @QueryParam("releaseId") String releaseId)
    Search tasks by title within a release.
    Parameters:
      `taskTitle` - the task title.
      `phaseTitle` - the phase title (optional).
      `releaseId` - the release identifier.
    Returns:
      a List of tasks that match the title within the release.

  - ### newTask

    Task newTask()
    Factory method to create a new instance of a Manual Task.
    Returns:
      the task object.

  - ### newTask

    Task newTask(String type)
    Factory method to create a new instance of a Task object.

    Example script which adds a custom script task to the current phase:

         phase = getCurrentPhase()
         task = taskApi.newTask("xlrelease.GateTask")
         task.title = "My Gate Task"
         taskApi.addTask(phase.id, task)

    Parameters:
      `type` - the type of the task. For example: `xlrelease.GateTask`.
    Returns:
      the task object.

  - ### newComment

    Comment newComment(String commentText)
    Factory method to create a new instance of a Comment.
    Parameters:
      `commentText` - comment text
    Returns:
      the comment object.

  - ### delete

    @DELETE @Path("/{taskId:.*/Task[^/]*}") void delete(@PathParam("taskId") String taskId)
    Deletes a task.
    Parameters:
      `taskId` - the task identifier.

  - ### deleteDependency

    @DELETE @Path("/{dependencyId:.*/Dependency[^/]*}") void deleteDependency(@PathParam("dependencyId") String dependencyId)
    Deletes a dependency from a gate task.
    Parameters:
      `dependencyId` - the identifier of the gate task dependency.

  - ### addDependency

    @POST @Path("/{taskId:.*/Task[^/]*}/dependencies/{targetId:.*?}") Dependency addDependency(@PathParam("taskId") String taskId, @PathParam("targetId") String targetId)
    Adds a dependency to a gate task.
    Parameters:
      `taskId` - the identifier of the gate task to add the dependency to.
      `targetId` - the identifier of the release, phase or task that the gate will depend on, or a variable which will resolve to such an identifier. When using a variable you can also combine variables, for example "Applications/${shortReleaseId}"
    Returns:
      the added Dependency

  - ### addCondition

    @POST @Path("{taskId:.*/Task[^/]*}/conditions") GateCondition addCondition(@PathParam("taskId") String taskId, Condition condition)
    Adds a condition to a gate task.
    Parameters:
      `taskId` - the identifier of the gate task to add the condition to.
      `condition` - the condition to add.
    Returns:
      the added gate condition.

  - ### updateCondition

    @POST @Path("/{conditionId:.*/GateCondition[^/]*}") GateCondition updateCondition(@PathParam("conditionId") String conditionId, Condition condition)
    Updates a condition on a gate task. Use this method to (un)check the condition.
    Parameters:
      `conditionId` - the identifier of the gate task condition.
      `condition` - the new values of the condition.
    Returns:
      the updated gate condition.

  - ### updateCondition

    GateCondition updateCondition(GateCondition condition)
    Updates a condition on a gate task. Use this method to (un)check the condition.
    Parameters:
      `condition` - the new values of the condition.
    Returns:
      the updated gate condition.

  - ### deleteCondition

    @DELETE @Path("{conditionId:.*/GateCondition[^/]*?}") void deleteCondition(@PathParam("conditionId") String conditionId)
    Deletes a condition from a gate task.
    Parameters:
      `conditionId` - the identifier of the gate task condition.

  - ### lockTask

    @PUT @Path("{taskId:.*/Task[^/]*}/lock") void lockTask(@PathParam("taskId") String taskId)
    Locks a task.
    Parameters:
      `taskId` - the task identifier.

  - ### unlockTask

    @DELETE @Path("{taskId:.*/Task[^/]*}/lock") void unlockTask(@PathParam("taskId") String taskId)
    Unlocks a task.
    Parameters:
      `taskId` - the task identifier.