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 java.lang.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

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

- - ### Field Detail

    - #### SERVICE_NAME

          static final java.lang.String SERVICE_NAME

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### serviceName

          default java.lang.String serviceName()

      Specified by:
        `serviceName` in interface `ApiService`

    - #### addAttachments

          @POST
          @Path("{taskId:.*/Task[^/]*}/attachments")
          @Consumes("multipart/form-data")
          java.util.List<Attachment> addAttachments​(@PathParam("taskId")
                                                    java.lang.String taskId,
                                                    @Context
                                                    javax.servlet.http.HttpServletRequest request)
                                             throws java.io.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:
        `java.io.IOException`

    - #### addAttachment

          Attachment addAttachment​(java.lang.String taskId,
                                   java.lang.String fileName,
                                   byte[] fileByteArray)
                            throws java.io.IOException

      Adds one attachment files to a task.
      Throws:
        `java.io.IOException`

    - #### deleteAttachment

          @DELETE
          @Path("{taskId:.*/Task[^/]*}/attachments/{attachmentId:.*/Attachment[^/]*}")
          void deleteAttachment​(@PathParam("taskId")
                                java.lang.String taskId,
                                @PathParam("attachmentId")
                                java.lang.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")
                       java.lang.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")
                        java.lang.String taskId,
                        @QueryParam("targetContainerId")
                        java.lang.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")
                          java.lang.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​(java.lang.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")
                              java.lang.String taskId,
                              @QueryParam("targetType")
                              java.lang.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

          @POST
          @Path("/{containerId:.*?}/tasks")
          Task addTask​(@PathParam("containerId")
                       java.lang.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")
                       java.lang.String containerId,
                       Task task,
                       java.lang.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")
                            java.lang.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​(java.lang.String taskId,
                            java.lang.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")
                        java.lang.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​(java.lang.String taskId,
                        java.lang.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")
                        java.lang.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​(java.lang.String taskId,
                        java.lang.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")
                         java.lang.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​(java.lang.String taskId,
                         java.lang.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")
                         java.lang.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​(java.lang.String taskId,
                         java.lang.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")
                     java.lang.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​(java.lang.String taskId,
                     java.lang.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,
                     java.util.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")
                     java.lang.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")
                          java.lang.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​(java.lang.String taskId,
                          java.lang.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")
          java.util.List<Variable> getVariables​(@PathParam("taskId")
                                                java.lang.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")
          java.util.List<Variable> updateInputVariables​(@PathParam("taskId")
                                                        java.lang.String taskId,
                                                        java.util.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")
                           java.lang.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​(java.lang.String taskId,
                           java.lang.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")
                          java.lang.String taskId,
                          @PathParam("username")
                          java.lang.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")
          java.util.List<Task> searchTasksByTitle​(@QueryParam("taskTitle")
                                                  java.lang.String taskTitle,
                                                  @QueryParam("phaseTitle")
                                                  java.lang.String phaseTitle,
                                                  @QueryParam("releaseId")
                                                  java.lang.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​(java.lang.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​(java.lang.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")
                      java.lang.String taskId)

      Deletes a task.
      Parameters:
        `taskId` - the task identifier.

    - #### deleteDependency

          @DELETE
          @Path("/{dependencyId:.*/Dependency[^/]*}")
          void deleteDependency​(@PathParam("dependencyId")
                                java.lang.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")
                                   java.lang.String taskId,
                                   @PathParam("targetId")
                                   java.lang.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")
                                     java.lang.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")
                                        java.lang.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")
                               java.lang.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")
                        java.lang.String taskId)

      Locks a task.
      Parameters:
        `taskId` - the task identifier.

    - #### unlockTask

          @DELETE
          @Path("{taskId:.*/Task[^/]*}/lock")
          void unlockTask​(@PathParam("taskId")
                          java.lang.String taskId)

      Unlocks a task.
      Parameters:
        `taskId` - the task identifier.