/*
* Copyright 2016 Red Hat, Inc. and/or its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jbpm.services.api.admin;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import org.jbpm.services.api.TaskNotFoundException;
import org.kie.api.runtime.query.QueryContext;
import org.kie.api.task.model.OrganizationalEntity;
import org.kie.internal.runtime.error.ExecutionError;
import org.kie.internal.task.api.model.EmailNotification;
import org.kie.internal.task.api.model.Notification;
/**
* Provides administrative operations on top of active tasks.
* All operations should be performed by eligible user - in most of the case business administrator.
*/
public interface UserTaskAdminService {
/**
* Adds new potential owners for a given task. Can be instructed to remove existing potential owners
* which means that the task will be released in case it was claimed already.
* Task must be in active state.
* @param taskId unique task id
* @param removeExisting specifies if existing potential owners should be removed
* @param orgEntities one or more potential owner to be added to a task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void addPotentialOwners(long taskId, boolean removeExisting, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Adds new excluded owners for a given task. Can be instructed to remove existing excluded owners.
* Task must be in active state.
* @param taskId unique task id
* @param removeExisting specifies if existing excluded owners should be removed
* @param orgEntities one or more excluded owner to be added to a task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void addExcludedOwners(long taskId, boolean removeExisting, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Adds new business admin for a given task. Can be instructed to remove existing business admins.
* Task must be in active state.
* @param taskId unique task id
* @param removeExisting specifies if existing business admins should be removed
* @param orgEntities one or more business admin to be added to a task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void addBusinessAdmins(long taskId, boolean removeExisting, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Remove existing potential owners from given task. Task must be in active state.
* @param taskId unique task id
* @param orgEntities one or more potential owner to be removed from a task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void removePotentialOwners(long taskId, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Remove existing excluded owners from given task. Task must be in active state.
* @param taskId unique task id
* @param orgEntities one or more excluded owner to be removed from a task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void removeExcludedOwners(long taskId, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Remove existing business admin from given task. Task must be in active state.
* @param taskId unique task id
* @param orgEntities one or more business admin to be removed from a task
* @throws TaskNotFoundException thrown when there is no task with given id
* @throws IllegalStateException in case there are no business admins left on a task - there must be at least one business admin
*/
void removeBusinessAdmins(long taskId, OrganizationalEntity ...orgEntities) throws TaskNotFoundException, IllegalStateException;
/**
* Adds new item to task input variables.
* @param taskId unique task id
* @param name name of the input variable to be added
* @param value value of the input variable
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void addTaskInput(long taskId, String name, Object value) throws TaskNotFoundException;
/**
* Adds new items to task input variables.
* @param taskId unique task id
* @param data map of key (name of the variable) and value (value of the variable)
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void addTaskInputs(long taskId, Map<String, Object> data) throws TaskNotFoundException;
/**
* Removes one or more input variables from a task.
* @param taskId unique task id
* @param name name(s) of the input variables to be removed
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void removeTaskInputs(long taskId, String ...name) throws TaskNotFoundException;
/**
* Removes one or more output variables from a task.
* @param taskId unique task id
* @param name name(s) of the output variables to be removed
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void removeTaskOutputs(long taskId, String... name) throws TaskNotFoundException;
/**
* Reassign automatically a task in case it was not started before time given as timeExpression elapses.
* @param taskId unique task id
* @param timeExpression time expression in duration format as 2s, 5h, 7d
* @param orgEntities users/groups that will be reassigned to after conditions are met
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Long reassignWhenNotStarted(long taskId, String timeExpression, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Reassign automatically a task in case it was not completed before time given as timeExpression elapses.
* @param taskId unique task id
* @param timeExpression time expression in duration format as 2s, 5h, 7d
* @param orgEntities users/groups that will be reassigned to after conditions are met
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Long reassignWhenNotCompleted(long taskId, String timeExpression, OrganizationalEntity ...orgEntities) throws TaskNotFoundException;
/**
* Sends notification (of notification type) to given recipients in case task was not started
* before time given as timeExpression elapses.
* @param taskId unique task id
* @param timeExpression time expression in duration format as 2s, 5h, 7d
* @param notification actual notification to be sent
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Long notifyWhenNotStarted(long taskId, String timeExpression, Notification notification) throws TaskNotFoundException;
/**
* Sends notification (of notification type) to given recipients in case task was not completed
* before time given as timeExpression elapses.
* @param taskId unique task id
* @param timeExpression time expression in duration format as 2s, 5h, 7d
* @param notification actual notification to be sent
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Long notifyWhenNotCompleted(long taskId, String timeExpression, Notification notification) throws TaskNotFoundException;
/**
* Builds email notification based on given parameters that can be used as argument for notifyWhenNotStarted and notifyWhenNotCompleted methods
* @param subjectStr email subject
* @param recipients list of recipients to be included in the notification, must be at least one
* @param bodyStr email body, can reference task variables
* @param fromStr user who sends the email
* @param replyToStr optional reply to address
* @return completely configured email notification instance
*/
EmailNotification buildEmailNotification(String subjectStr, List<OrganizationalEntity> recipients, String bodyStr, String fromStr, String replyToStr);
/**
* Returns task reassignments scheduled for given task
* @param taskId unique task id
* @param activeOnly determines if only active (not yet fired) should be returned
* @return returns list of task reassignments for given task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Collection<TaskReassignment> getTaskReassignments(long taskId, boolean activeOnly) throws TaskNotFoundException;
/**
* Returns task notifications scheduled for given task
* @param taskId unique task id
* @param activeOnly determines if only active (not yet fired) should be returned
* @return returns list of task notifications for given task
* @throws TaskNotFoundException thrown when there is no task with given id
*/
Collection<TaskNotification> getTaskNotifications(long taskId, boolean activeOnly) throws TaskNotFoundException;
/**
* Cancels given notification on a task
* @param taskId unique task id
* @param notificationId unique notification id
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void cancelNotification(long taskId, long notificationId) throws TaskNotFoundException;
/**
* Cancels given reassignment on a task
* @param taskId unique task id
* @param reassignmentId unique reassignment id
* @throws TaskNotFoundException thrown when there is no task with given id
*/
void cancelReassignment(long taskId, long reassignmentId) throws TaskNotFoundException;
/**
* Returns execution errors for given task id
* @param taskId unique task id
* @param includeAcknowledged indicates whether to include acknowledged errors or not
* @param queryContext control parameters for pagination
* @return list of found errors
*/
List<ExecutionError> getErrorsByTaskId(long taskId, boolean includeAcknowledged, QueryContext queryContext);
/**
* Returns execution errors for given task name
* @param taskName name of the task
* @param includeAcknowledged indicates whether to include acknowledged errors or not
* @param queryContext control parameters for pagination
* @return list of found errors
*/
List<ExecutionError> getErrorsByTaskName(String taskName, boolean includeAcknowledged, QueryContext queryContext);
/**
* Returns execution errors for given task name and process id
* @param processId process id of the process that task belongs to
* @param taskName name of the task
* @param includeAcknowledged indicates whether to include acknowledged errors or not
* @param queryContext control parameters for pagination
* @return list of found errors
*/
List<ExecutionError> getErrorsByTaskName(String processId, String taskName, boolean includeAcknowledged, QueryContext queryContext);
/**
* Returns execution errors for given task name, process id and deployment id
* @param deploymentId deployment id that contains given process
* @param processId process id of the process that task belongs to
* @param taskName name of the task
* @param includeAcknowledged indicates whether to include acknowledged errors or not
* @param queryContext control parameters for pagination
* @return list of found errors
*/
List<ExecutionError> getErrorsByTaskName(String deploymentId, String processId, String taskName, boolean includeAcknowledged, QueryContext queryContext);
/**
* Acknowledge given error that it was reviewed and understood
* @param errorId unique id of the error
* @throws ExecutionErrorNotFoundException thrown when there is no unacknowledged error with that id
*/
void acknowledgeError(String... errorId) throws ExecutionErrorNotFoundException;
/**
* Returns execution error identified by given error id
* @param errorId unique id of the error
* @return returns execution error instance
* @throws ExecutionErrorNotFoundException is thrown in case no error was found for given error id
*/
ExecutionError getError(String errorId) throws ExecutionErrorNotFoundException;
/**
* Returns execution errors that are classified as task type errors
* @param includeAcknowledged indicates whether to include acknowledged errors or not
* @param queryContext control parameters for pagination
* @return list of found errors
*/
List<ExecutionError> getErrors(boolean includeAcknowledged, QueryContext queryContext);
}