Atoti Sign-Off API

public interface ISignOffService {

    /**
     * Initiates a task.
     *
     * @param key The key for the task.
     */
    void initiate(SignOffProcessKey key);

    /**
     * Approves a task.
     *
     * @param key The key for the task.
     */
    void approve(SignOffProcessKey key);

    /**
     * Requests an export and returns a map of export type and task ID.
     *
     * @param instance The sign-off instance for which the export is requested.
     * @return A map of export type and task ID.
     */
    Map<String, String> export(SignOffProcessInstanceExportDTO instance);

    /**
     * Requests the status of the supplied export tasks.
     *
     * @param tasks The map of export type and task ID.
     * @return The status of the tasks.
     */
    SignOffExportStatusDTO status(Map<String, String> tasks);

    /**
     * Requests KPI values for a sign-off process instance.
     *
     * @param completion The sign-off process instance.
     * @return The map of KPI name to value, goal and status.
     */
    Map<String, KpiDTO> kpis(SignOffProcessInstanceExportDTO completion);
}

/**
 * This rest controller implemented on your application server allows the Sign-Off server to communicate with your application server.
 */
@RestController
@RequestMapping(ISignOffRestService.NAMESPACE)
public interface ISignOffRestService {

    /**
     * A namespace for the REST service mapping.
     */
    String NAMESPACE = "sign-off";

    /**
     * This method is called via REST by the Sign-Off server upon creating a new task.
     * While the Sign-Off server will change the status of the task to be available for adjustments, you should implement this to perform any required steps on the data on the server side.
     * For instance, you may want to mark the data on which adjustments will be performed as "frozen".
     *
     * @param instance sign-off process instance, must contain the definitionName and a list of filters
     * @param forceReset in case there is some pending work already associated with the task it will be discarded
     */
    @PutMapping("/initiate/{forceReset}")
    void initiate(@RequestBody SignOffProcessInstanceExportDTO instance, @PathParam("forceReset") boolean forceReset);

    /**
     * This method is called via REST by the Sign-Off server upon creating a new task. 
     * While the Sign-Off server will change the status of the task to be available for adjustments, you should implement this to perform any required steps on the data on the server side.
     * For instance, you may want to mark the data on which adjustments will be performed as "frozen". 
     *
     * @param instance sign-off process instance, must contain the definitionName and a list of filters
     */
    @PutMapping("/initiate")
    default void initiate(@RequestBody SignOffProcessInstanceExportDTO instance) {
        initiate(instance, true);
    }

    /**
     * This method may be called via REST by the Sign-Off server in a _custom workflow_, where a task has an end state, such as "discarded" or "deleted".
     * When tasks are in that state, your application server should implement the behavior, and proceed to any cleanup required on the application server side.
     * For instance, you may remove any adjustment or trace of this task in the store of your application server.
     *
     * @param task The task ID
     */
    @PutMapping("/discard")
    void discard(@RequestBody String task);

    /**
     * This method is called via REST by the Sign-Off server when the task changes state to `INITIATED` or `EXPORT_SUCCEEDED`, for instance.
     * The returned `String` is not actively used in the Sign-Off server. 
     * However, this can be used for sending back a status from your application server in a _custom workflow_.
     *
     * @param instance sign-off process instance
     * @return the state of the task
     */
    @PostMapping("/update-state")
    String updateState(@RequestBody SignOffProcessInstanceExportDTO instance);

    /**
     * This method is called via REST by the Sign-Off server to retrieve the KPIs associated with a task. 
     * These are used in the `4-eyes-kpi` workflow to automatically approve a task.
     * You should then implement this method for your application server to return the KPIs associated with the task.
     * The `Map` is expected to be the KPIs object by their name as in the `SignOffProcessInstanceExportDTO`.
     *
     * @param completion sign-off process instance
     * @return Response
     */
    @PostMapping("/kpis")
    @Produces(MediaType.APPLICATION_JSON)
    Map<String, KpiDTO> kpis(@RequestBody SignOffProcessInstanceExportDTO completion);


    /**
     * This method is called via REST by the Sign-Off server when a task is exported (after approval in the default workflows).
     * This method should implement an export of the data related to the task provided. After completing the export, the Sign-Off server will complete the task workflow.
     * The `Map` expected is the task ID for each export template.
     *
     * @param instance sign-off process instance
     * @return A map of export type to DEE task ID.
     */
    @PostMapping("/export")
    @Produces(MediaType.APPLICATION_JSON)
    Map<String, String> export(@RequestBody SignOffProcessInstanceExportDTO instance);

    /**
     * This method is called via REST by the Sign-Off server to retrieve the state of the export to attach it to the task in the Sign-Off server.
     * The `SignOffExportStatusDTO` is expected to hold the update of the status of the export of the tasks provided in the `Map`. 
     * This is the same `Map` that is returned in the implementation of the export method.
     *
     * @param tasks The tasks to retrieve statuses for.
     * @return A status DTO object containing statuses for all tasks requested.
     */
    @PostMapping("/status")
    @Produces(MediaType.APPLICATION_JSON)
    SignOffExportStatusDTO status(@RequestBody Map<String, String> tasks);
}

/**
 * This class is used to carry the process definition name and asOfDate
 */
@AllArgsConstructor
@Getter
public class SignOffProcessKey {

    private final String definitionName;
    private final LocalDate asOfDate;

    /**
     * Returns the definition key, using @see KeyGenerator
     *
     * @return The definition key.
     */
    public String definitionKey() {
        return KeyGenerator.getKey(getDefinitionName(), getAsOfDate());
    }

    /**
     * Returns a String representation of the key.
     *
     * @return The String representation of the key.
     */
    @Override
    public String toString() {
        return definitionKey();
    }
}

/**
 * A DTO for exporting a sign-off task.
 */
@NoArgsConstructor
@Getter
@Setter
@EqualsAndHashCode
@ToString
public class SignOffProcessInstanceExportDTO {

    /**
     * The key of the export task.
     */
    private String key;

    /**
     * The name of the export task.
     */
    private String name;

    /**
     * The date being exported.
     */
    private LocalDate asOfDate;

    /**
     * The domain of the export task.
     */
    private String domain;

    /**
     * The filters to apply to the export.
     */
    private List<List<String>> filters;

    /**
     * The KPIs to export.
     */
    private List<String> kpis;

    /**
     * The name of the server for which the export is requested.
     */
    private String serverName;

    /**
     * The status of the export.
     */
    private String status;

}

/**
 * A DTO for the status of a sign-off task export.
 */
@NoArgsConstructor
@Getter
@Setter
@EqualsAndHashCode
@ToString
public class SignOffExportStatusDTO implements Serializable {

    /**
     * The status of the sign-off export.
     */
    private String status;

    /**
     * The subtasks of the sign-off export main task.
     */
    private Map<String, SignOffExportSubtaskStatusDTO> subtasks = new HashMap<>();

    /**
     * A DTO for the status of sign-off export subtasks.
     */
    @NoArgsConstructor
    @Getter
    @Setter
    @EqualsAndHashCode
    @ToString
    public static class SignOffExportSubtaskStatusDTO implements Serializable {

        /**
         * The status of the export subtask.
         */
        private String status;

        /**
         * The first file of the export.
         */
        private String firstFile;

        /**
         * The number of files that have been exported.
         */
        private Integer nbFiles;

        /**
         * If the subtask fails, the exception that caused the failure.
         */
        private String exception;

        /**
         * If the subtask fails, the cause of the failure.
         */
        private String cause;

        /**
         * The timestamp of the run stopping.
         */
        private String runStopTime;
    }
}

/**
 * A DTO for a KPI.
 */
@NoArgsConstructor
@Getter
@Setter
@EqualsAndHashCode
@ToString
@JsonIgnoreProperties(ignoreUnknown = true)
public class KpiDTO implements Serializable {

    private static final long serialVersionUID = -8453317403169130322L;

    /**
     * The value of the KPI.
     */
    private Object value;

    /**
     * The goal of the KPI.
     */
    private Object goal;

    /**
     * The status of the KPI.
     */
    private Object status;
}