feat: Alteration to InstanceLauncher and launch params

Author: Alan Christie

workflow/workflow_abc.py

@@ -15,33 +15,49 @@ class LaunchParameters:
     The launching user API token is the second element when the request header's
     'Authorization' value is split on white-space."""
 
-    application_id: str
+    # The Project UUID to launch the instance in
     project_id: str
+    # A symbolic name of the Instance
     name: str
+    # The user name of the person launching the Instance/Workflow
     launching_user_name: str
+    # The API Access token provided by the User
     launching_user_api_token: str
+    # The specification, which can contain 'variables'
     specification: dict[str, Any]
+    # An alternative way to passing variables to the specification.
+    # If used it will replace any 'variables' key in the specification.
     specification_variables: dict[str, Any] | None = None
-    debug: bool | None = None
-    callback_url: str | None = None
-    callback_token: str | None = None
-    callback_context: str | None = None
-    generate_callback_token: bool | None = None
+    # A string. In DM v4 converted to a boolean and set in the
+    # instance Pod as a label.
+    debug: str | None = None
+    # The RunningWorkflow UUID
     running_workflow_id: str | None = None
+    # The RunningWorkflowStep UUID
     running_workflow_step_id: str | None = None
+    # The application ID (a custom resource name)
+    # used to identify the 'type' of Instance to create.
+    # For DM Jobs this will be 'datamanagerjobs.squonk.it'
+    application_id: str = "datamanagerjobs.squonk.it"
 
 
 @dataclass
 class LaunchResult:
     """Results returned from methods in the InstanceLauncher.
     Any error returned in this object is a launch error, not a Job error."""
 
+    # A numeric non-zero error code if an error occurred
+    # and an optional message
     error_num: int = 0
     error_msg: str | None = None
+    # The Instance UUID that was created for you
     instance_id: str | None = None
+    # The Task UUID that is handling the Instance launch
     task_id: str | None = None
-    callback_token: str | None = None
+    # The rendered command used in the instance
     command: str | None = None
+    # A callback token (unused in Workflows)
+    callback_token: str | None = None
 
 
 class InstanceLauncher(ABC):
@@ -51,7 +67,9 @@ class InstanceLauncher(ABC):
     @abstractmethod
     def launch(
         self,
+        *,
         launch_parameters: LaunchParameters,
+        **kwargs: str,
     ) -> LaunchResult:
         """Launch a (Job) Instance"""
 

workflow/workflow_engine.py

@@ -42,9 +42,6 @@
 _LOGGER.setLevel(logging.INFO)
 _LOGGER.addHandler(logging.StreamHandler(sys.stdout))
 
-# The 'well known' application ID for Jobs
-DM_JOB_APPLICATION_ID: str = "datamanagerjobs.squonk.it"
-
 
 class WorkflowEngine:
     """The workflow engine."""
@@ -155,7 +152,6 @@ def _handle_workflow_start_message(self, r_wfid: str) -> None:
 
         lp: LaunchParameters = LaunchParameters(
             project_id=project_id,
-            application_id=DM_JOB_APPLICATION_ID,
             name=first_step_name,
             launching_user_name=launching_user_name,
             launching_user_api_token=rwf_response["running_user_api_token"],
@@ -164,7 +160,7 @@ def _handle_workflow_start_message(self, r_wfid: str) -> None:
             running_workflow_id=r_wfid,
             running_workflow_step_id=r_wfsid,
         )
-        lr: LaunchResult = self._instance_launcher.launch(lp)
+        lr: LaunchResult = self._instance_launcher.launch(launch_parameters=lp)
         if lr.error_num:
             self._set_step_error(
                 first_step_name, r_wfid, r_wfsid, lr.error_num, lr.error_msg
@@ -286,7 +282,6 @@ def _handle_pod_message(self, msg: PodMessage) -> None:
                     variables: dict[str, Any] | None = rwf_response.get("variables")
                     lp: LaunchParameters = LaunchParameters(
                         project_id=project_id,
-                        application_id=DM_JOB_APPLICATION_ID,
                         name=next_step_name,
                         launching_user_name=rwf_response["running_user"],
                         launching_user_api_token=rwf_response["running_user_api_token"],
@@ -295,7 +290,7 @@ def _handle_pod_message(self, msg: PodMessage) -> None:
                         running_workflow_id=r_wfid,
                         running_workflow_step_id=new_r_wfsid,
                     )
-                    lr = self._instance_launcher.launch(lp)
+                    lr = self._instance_launcher.launch(launch_parameters=lp)
                     # Handle a launch error?
                     if lr.error_num:
                         self._set_step_error(