create or replace PACKAGE CT_MRDS.WORKFLOW_MANAGER
IS
 
   -- Package Version Information (Semantic Versioning: MAJOR.MINOR.PATCH)
   PACKAGE_VERSION     CONSTANT VARCHAR2(10) := '1.7.0';
   PACKAGE_BUILD_DATE  CONSTANT VARCHAR2(20) := '2025-10-31 16:00:00';
   PACKAGE_AUTHOR      CONSTANT VARCHAR2(100) := 'Grzegorz Michalski';

   -- Version History (Latest changes first)
   VERSION_HISTORY     CONSTANT VARCHAR2(4000) :=
      '1.7.0 (2025-10-31): Added FINALISE_TASK_WITH_TARGET_INFO function for atomic task completion with target info' || CHR(13)||CHR(10) ||
      '1.6.0 (2025-10-31): Converted STORE_TASK_SOURCE_INFO and STORE_TASK_TARGET_INFO from procedures to functions returning sequence keys' || CHR(13)||CHR(10) ||
      '1.5.0 (2025-10-22): Added package versioning system using centralized ENV_MANAGER functions' || CHR(13)||CHR(10) ||
      '1.2.0 (2025-10-05): Added workflow property management (SET/GET_WORKFLOW_PROPERTY)' || CHR(13)||CHR(10) ||
      '1.0.0 (2025-09-10): Initial release with workflow and task lifecycle management';

   -- Line break constant for consistent CRLF formatting across Windows environments
   cgBL       CONSTANT  VARCHAR2(2)   := CHR(13)||CHR(10);

   FUNCTION INIT_WORKFLOW(pServiceName IN VARCHAR2, pWorkflowRunId IN VARCHAR2, pWorkflowName in VARCHAR2)
   RETURN NUMBER;

   PROCEDURE FINALISE_WORKFLOW(pWorkflowHistoryKey IN NUMBER, pWorkflowStatus IN VARCHAR2);
   PROCEDURE FINALISE_WORKFLOW(pWorkflowHistoryKey IN NUMBER, pServiceName IN VARCHAR2, pWorkflowStatus IN VARCHAR2);

   FUNCTION INIT_TASK(pTaskRunId IN VARCHAR2, pTaskName in VARCHAR2, pWorkflowHistoryKey IN NUMBER)
   RETURN NUMBER;

   PROCEDURE FINALISE_TASK(pTaskHistoryKey IN NUMBER, pTaskStatus IN VARCHAR2);

   FUNCTION STORE_TASK_SOURCE_INFO(pTaskHistoryKey IN NUMBER, pSourceName IN VARCHAR2, pNumRows IN NUMBER)
   RETURN NUMBER;

   FUNCTION STORE_TASK_TARGET_INFO(pTaskHistoryKey IN NUMBER, pSourceName IN VARCHAR2,
                                   pNumRowsApplied IN NUMBER, pNumRowsRejected IN NUMBER,
                                   pLoadSuccessful IN VARCHAR2, pServiceName IN VARCHAR2)
   RETURN NUMBER;

   FUNCTION FINALISE_TASK_WITH_TARGET_INFO(pTaskHistoryKey IN NUMBER, pTaskStatus IN VARCHAR2,
                                          pTargetName IN VARCHAR2, pNumRowsApplied IN NUMBER,
                                          pNumRowsRejected IN NUMBER, pLoadSuccessful IN VARCHAR2,
                                          pServiceName IN VARCHAR2)
   RETURN NUMBER;

   vpRunningStatus CT_MRDS.A_WORKFLOW_HISTORY.WORKFLOW_SUCCESSFUL%TYPE := 'R';

   --
   -- Set and get information on workflow level
   --
   PROCEDURE SET_WORKFLOW_PROPERTY(
       pWorkflowHistoryKey IN NUMBER
      ,pServiceName        IN VARCHAR2
      ,pProperty           IN VARCHAR2
      ,pValue              IN VARCHAR2
   );

   FUNCTION GET_WORKFLOW_PROPERTY(
       pWorkflowHistoryKey IN NUMBER
      ,pServiceName        IN VARCHAR2
      ,pProperty           IN VARCHAR2)
   RETURN VARCHAR2;

   ---------------------------------------------------------------------------------------------------------------------------
   -- PACKAGE VERSION MANAGEMENT FUNCTIONS
   ---------------------------------------------------------------------------------------------------------------------------

   /**
      * @name     GET_VERSION
      * @desc     Returns the current version number of the WORKFLOW_MANAGER package.
      *           Uses semantic versioning format (MAJOR.MINOR.PATCH).
      * @example  SELECT WORKFLOW_MANAGER.GET_VERSION() FROM DUAL;
      * @ex_rslt  1.5.0
   **/
   FUNCTION GET_VERSION RETURN VARCHAR2;

   /**
      * @name     GET_BUILD_INFO
      * @desc     Returns comprehensive build information including version, build date, and author.
      *           Uses centralized ENV_MANAGER.GET_PACKAGE_VERSION_INFO function.
      * @example  SELECT WORKFLOW_MANAGER.GET_BUILD_INFO() FROM DUAL;
      * @ex_rslt  Package: WORKFLOW_MANAGER
      *           Version: 1.5.0
      *           Build Date: 2025-10-22 17:00:00
      *           Author: Grzegorz Michalski
   **/
   FUNCTION GET_BUILD_INFO RETURN VARCHAR2;

   /**
      * @name     GET_VERSION_HISTORY
      * @desc     Returns complete version history with all releases and changes.
      *           Uses centralized ENV_MANAGER.FORMAT_VERSION_HISTORY function.
      * @example  SELECT WORKFLOW_MANAGER.GET_VERSION_HISTORY() FROM DUAL;
      * @ex_rslt  WORKFLOW_MANAGER Version History:
      *           1.5.0 (2025-10-22): Added package versioning system...
   **/
   FUNCTION GET_VERSION_HISTORY RETURN VARCHAR2;

END WORKFLOW_MANAGER;
