Migration notes 6.1 (pre-alignment)

public interface ISignOffProcessDefinitionWorkflowService
        extends IBitemporalObjectWorkflowService<SignOffProcessDefinitionDTO>
{

    /**
     * Start the workflow process for creating a new sign-off process definition.
     * <p>
     * Note: this starts a new workflow process instance.  It will be blocked if the object's key is currently involved in another process instance.
     * It will also fail validation if the object already exists in the persistent storage.
     *
     * @param object the sign-off process definition to create
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for starting the process, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException if the object fails the creation validation
     * @see IKeyedObjectWorkflowService#startProcess(String, String, IKeyedObject, String, String, java.util.Map)
     */
    ProcessRecordDTO create(SignOffProcessDefinitionDTO object, String comment, Map<String, Object> variables) throws ValidationException;

    /**
     * Start the workflow process for updating a (published/approved) sign-off process definition.
     * <p>
     * Note: this starts a new workflow process instance.  It will be blocked if the object's key is currently involved in another process instance.
     * It will also fail validation if the object doesn't currently exist in the persistent storage.
     *
     * @param object the sign-off process definition to update
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for starting the process, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException if the object fails the update validation
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    UserTaskRecordDTO update(SignOffProcessDefinitionDTO object, String comment, Map<String, Object> variables) throws ValidationException;

    /**
     * Start the workflow process for archiving a (published/approved) sign-off process definition.
     * <p>
     * Note: this starts a new workflow process instance.  It will be blocked if the object's key is currently involved in another process instance.
     * It will also fail validation if the object doesn't currently exist in the persistent storage.
     *
     * @param key the sign-off process definition to archive
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for starting the process, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException if the object fails the archive validation
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    UserTaskRecordDTO archive(String key, String comment, Map<String, Object> variables) throws ValidationException;

    /**
     * Import a CSV file containing sign-off process definitions.
     * A new ({@link IKeyedObjectService#createOrUpdate(IKeyedObject) create or update}) process instance is started for each row of the file.
     * <p>
     * Note: this starts multiple new workflow process instances.  Each of these may be blocked if the corresponding object's key is currently involved in another process instance.
     *
     * @param csv the CSV file to import
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the list of history records for starting each process, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException if an object fails the archive validation
     * @throws IOException if there is an error reading the CSV file
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    List<AHistoryRecordDTO> upload(Reader csv, String comment, Map<String, Object> variables) throws ValidationException, IOException;

    /**
     * Save a new version of an object as it progresses through the workflow.
     * <p>
     * This performs the "save" action and sets the workflow status to "SAVED"
     *
     * @param key the object's identifying key
     * @param object the new version of the object
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     * @throws ValidationException the request could not be processed on the current state
     */
    default UserTaskRecordDTO save(String key, SignOffProcessDefinitionDTO object, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(key, object, "save", comment, variables);
    }

    /**
     * Publish/approve a new version of an object that has progressed through the workflow.  This ends the workflow process instance for the object.
     * <p>
     * This performs the "publish" action and sets the workflow status to "PUBLISHING"
     *
     * @param key the object's identifying key
     * @param object the (optional) new version of the object
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     * @throws ValidationException the request could not be processed on the current state
     */
    default UserTaskRecordDTO publish(String key, SignOffProcessDefinitionDTO object, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(key, object, "publish", comment, variables);
    }

    /**
     * Delete an object that was progressing through the workflow.  This ends the workflow process instance for the object.
     * <p>
     * This performs the "delete" action and sets the workflow status to {@code null}.
     *
     * @param key the object's identifying key
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     * @throws ValidationException the request could not be processed on the current state
     */
    default UserTaskRecordDTO delete(String key, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(key, null, "delete", comment, variables);
    }

    /**
     * Retrieve a process definition with its key, adding the available actions depending on the process instance's state.
     *
     * @param key of the {@link SignOffProcessDefinitionDTO} to retrieve
     * @return a {@link SignOffProcessDefinitionDTO} with actions
     */
    SignOffProcessDefinitionDTO getSignOffProcessDefinitionWithActions(String key);

    /**
     * Retrieve all process definitions with their key as key of the map, adding the available actions depending on the process instance's state.
     *
     * @return a map of {@link SignOffProcessDefinitionDTO}s with actions
     */
    Map<String, SignOffProcessDefinitionDTO> getSignOffProcessDefinitionsWithActions();

    /**
     * Retrieve the history (audit log) of a {@link SignOffProcessDefinitionDTO} identified by
     * signOffProcessDefinitionKey. This history will include all the process instances that were used to
     * modify the object, as well as all the user tasks involved in those processes. The records match
     * those returned by startProcess() and taskStateTransition()
     *
     * @param signOffProcessDefinitionKey - the key of the {@link SignOffProcessDefinitionDTO}
     * @param includeVariables - if true, then the variables associated with the task ID will be
     *     wrapped in the response
     * @return the history records of the {@link SignOffProcessDefinitionDTO} specified by {@code
     *     signOffProcessDefinitionKey}
     */
    List<AHistoryRecordDTO> processInstanceHistory(
            String signOffProcessDefinitionKey,
            boolean includeVariables);
}

public interface ISignOffProcessInstanceWorkflowService
        extends IVersionedObjectWorkflowService<SignOffProcessInstanceDTO> {

    /**
     * Initiate the workflow process for signing-off on data.
     * The {@link SignOffProcessInstanceDTO object} points to the sign-off process definition, which describes both the workflow process to use and the scope of the data to be signed-off, additionally the object's as-of date specifies the date for which the data is being signed off.
     * <p>
     * Note: this starts a new workflow process instance.  It will be blocked if the object's key is currently involved in another process instance.
     * It will also fail validation if the object already exists in the persistent storage.
     *
     * @param object  the sign-off process instance to initiate
     * @param variables optional variables to pass on initiation
     * @return the history record for starting the process, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException if the initiation fails validation
     * @see IKeyedObjectWorkflowService#startProcess(String, String, IKeyedObject, String, String, java.util.Map)
     */
    AHistoryRecordDTO initiate(SignOffProcessInstanceDTO object, Map<String, Object> variables) throws ValidationException;

    /**
     * Request approval for the sign-off process instance.
     * <p>
     * This performs the {@link Action#REQUEST_APPROVAL} action and sets the workflow status to PENDING
     *
     * @param object  the process instance
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException the request could not be processed on the current state
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    default UserTaskRecordDTO requestApproval(SignOffProcessInstanceDTO object, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(object.getKey(), object, Action.REQUEST_APPROVAL.toString(), comment, variables);
    }

    /**
     * Cancel approval request for the sign-off process instance.
     * <p>
     * This performs the {@link Action#CANCEL_REQUEST} action and sets the workflow status to INITIATED
     *
     * @param object  the process instance
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException the request could not be processed on the current state
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    default UserTaskRecordDTO cancelRequest(SignOffProcessInstanceDTO object, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(object.getKey(), object, Action.CANCEL_REQUEST.toString(), comment, variables);
    }

    /**
     * Approve the sign-off process instance.  This completes the workflow and the process instance object will be persisted.
     * <p>
     * This performs the {@link Action#APPROVE} action and sets the workflow status to APPROVED.
     *
     * @param object  the process instance
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException the request could not be processed on the current state
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    UserTaskRecordDTO approve(SignOffProcessInstanceDTO object, String comment, Map<String, Object> variables) throws ValidationException;

    /**
     * Reject the sign-off process instance.
     * <p>
     * This performs the {@link Action#REJECT} action and sets the workflow status to INITIATED.
     *
     * @param object  the process instance
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException the request could not be processed on the current state
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    UserTaskRecordDTO reject(SignOffProcessInstanceDTO object, String comment, Map<String, Object> variables) throws ValidationException;

    /**
     * Close the sign-off process instance.
     * <p>
     * This performs the {@link Action#CLOSE} action and sets the workflow status to EXPORT_SUCCEEDED.
     * <p>
     * A closed sign-off process is considered done and will not be affected by an update signal.
     *
     * @param object  the process instance
     * @param comment an optional user comment
     * @param variables optional variables to store with the process instance
     * @return the history record for the user task, see {@link IKeyedObjectWorkflowService#processInstanceHistory(String)}
     * @throws ValidationException the request could not be processed on the current state
     * @see IKeyedObjectWorkflowService#taskStateTransition(String, IKeyedObject, String, String, java.util.Map)
     */
    default UserTaskRecordDTO close(SignOffProcessInstanceDTO object, String comment, Map<String, Object> variables) throws ValidationException {
        return taskStateTransition(object.getKey(), object, Action.CLOSE.toString(), comment, variables);
    }

    /**
     * Notify relevant processes that the status of an application server has changed. This allows processes to
     * be moved into a new workflow task whilst the application server is not running, and moved back to the
     * appropriate task when the server resumes.
     * @param serverName the name of the server
     * @param status the new status of the server
     */
    void notifyApplicationStatusChange(String serverName, ApplicationStatus status);

    /**
     * Retrieve a process instance with its key, adding the available actions depending on the process instance's state.
     *
     * @param key of the {@link SignOffProcessInstanceDTO} to retrieve
     * @return a {@link SignOffProcessInstanceDTO} with actions
     */
    SignOffProcessInstanceDTO getSignOffProcessInstanceWithActions(String key);

    /**
     * Retrieve all process instances with their key as the key of the map, adding the available actions depending on the process instance's state.
     *
     * @return a Map of {@link SignOffProcessInstanceDTO}s with actions
     */
    Map<String, SignOffProcessInstanceDTO> getSignOffProcessInstancesWithActions();

    /**
     * Retrieve the history (audit log) of a {@link SignOffProcessInstanceDTO} identified by
     * signOffProcessInstanceKey. This history will include all the process instances that were used to
     * modify the object, as well as all the user tasks involved in those processes. The records match
     * those returned by startProcess() and taskStateTransition()
     *
     * @param signOffProcessInstanceKey - the key of the {@link SignOffProcessInstanceDTO}
     * @param includeVariables - if true, then the variables associated with the task ID will be
     *     wrapped in the response
     * @return the history records of the {@link SignOffProcessInstanceDTO} specified by {@code
     *     signOffProcessInstanceKey}
     */
    List<AHistoryRecordDTO> processInstanceHistory(
            String signOffProcessInstanceKey,
            boolean includeVariables);
}

/**
 * <b>ISignOffRestClientBuilder</b>
 *
 * <p>Used to provide {@link RestClient.Builder} instances for building and sending authenticated requests to Atoti servers connected to Sign-Off.
 * This allows for the creation of {@link RestClient} instances with specific configurations for each server, for example, to handle URLS, authentication or custom headers.
 *
 * @author ActiveViam
 */
public interface ISignOffRestClientBuilder {

    /**
     * Get a {@link RestClient.Builder} for the specified server name.
     *
     * @param serverName the name of the server for which to get the {@link RestClient.Builder}
     * @return a {@link RestClient.Builder} configured for the specified server
     */
    RestClient.Builder getRestClientBuilder(String serverName);

}