flowtask 5.12.7__tar.gz → 5.12.8__tar.gz

{flowtask-5.12.7 → flowtask-5.12.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtask
-Version: 5.12.7
+Version: 5.12.8
 Summary: Framework for Task orchestration
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: Apache-2.0

{flowtask-5.12.7 → flowtask-5.12.8}/flowtask/conf.py

@@ -546,6 +546,22 @@ ZOOM_WEBHOOK_REPLAY_WINDOW_SECONDS = config.getint(
 )
 ZOOM_ALLOWED_CIDRS = config.get('ZOOM_ALLOWED_CIDRS', fallback='')
 
+## Maintenance / Status service (SOC2 CC8):
+# Master switch for the MaintenanceService (status + changelog + windows).
+MAINTENANCE_ENABLED = config.getboolean("MAINTENANCE_ENABLED", fallback=True)
+# Whether to email a summary of upcoming maintenance windows on startup.
+MAINTENANCE_NOTIFY_ON_STARTUP = config.getboolean(
+    "MAINTENANCE_NOTIFY_ON_STARTUP", fallback=True
+)
+# Recipient for maintenance-window notifications (falls back to DEFAULT_RECIPIENT).
+MAINTENANCE_NOTIFY_EMAIL = config.get("MAINTENANCE_NOTIFY_EMAIL", fallback=None)
+# Changelog source: a GitHub "owner/name" slug and/or a local CHANGELOG.md.
+MAINTENANCE_GITHUB_REPO = config.get("MAINTENANCE_GITHUB_REPO", fallback=None)
+MAINTENANCE_GITHUB_TOKEN = config.get("MAINTENANCE_GITHUB_TOKEN", fallback=None)
+MAINTENANCE_CHANGELOG_TITLE = config.get(
+    "MAINTENANCE_CHANGELOG_TITLE", fallback="What's New"
+)
+
 try:
     from navconfig.conf import *  # pylint: disable=W0401,W0614 # noqa
 except ImportError as e:

{flowtask-5.12.7 → flowtask-5.12.8}/flowtask/interfaces/workday/handlers/custom_report.py

@@ -129,6 +129,22 @@ class CustomReportType(WorkdayTypeBase):
                 result[f"ID_{key}"] = values[0] if len(values) == 1 else values
             return result or None
 
+        # JSON RaaS shape: a list of dicts whose values are plain scalars, e.g.
+        # ``[{"Time_Entry_Codes": "A; B"}, {"Time_Entry_Codes": "C"}]``. Merge by
+        # key, joining repeated values with ``"; "`` so the multi-instance group
+        # collapses into a single flat string column.
+        if all(all(not isinstance(v, (dict, list)) for v in i.values()) for i in items):
+            result = {}
+            for item in items:
+                for key, value in item.items():
+                    if value is None:
+                        continue
+                    if key in result:
+                        result[key] = f"{result[key]}; {value}"
+                    else:
+                        result[key] = value
+            return result or None
+
         return None
 
     def _expand_list_dict_columns(self, df: pd.DataFrame, drop_original: bool) -> pd.DataFrame:
@@ -207,6 +223,37 @@ class CustomReportType(WorkdayTypeBase):
             self._logger.error(f"Error parsing XML response: {e}")
             raise
 
+    def _parse_json_to_entries(self, body: Any) -> List[Dict[str, Any]]:
+        """Extract ``Report_Entry`` rows from a RaaS JSON response.
+
+        Workday's ``?format=json`` RaaS output is already a list of flat dicts
+        (no namespace prefixes, no ``type``/``_value`` wrappers), so it feeds
+        straight into ``pd.json_normalize``. Multi-instance group columns arrive
+        as a list of dicts with scalar values, collapsed later by
+        :meth:`_list_of_dicts_to_dict` when ``flatten_list_dicts`` is set.
+
+        Args:
+            body: Parsed JSON payload (dict) or a raw JSON string/bytes.
+
+        Returns:
+            List of report-entry dicts (empty when none present).
+        """
+        import json as _json
+
+        if isinstance(body, (bytes, bytearray)):
+            body = body.decode("utf-8", errors="replace")
+        if isinstance(body, str):
+            body = _json.loads(body)
+
+        if isinstance(body, list):
+            return body
+        if isinstance(body, dict):
+            entries = body.get("Report_Entry", [])
+            if entries and not isinstance(entries, list):
+                entries = [entries]
+            return entries or []
+        return []
+
     def _build_raas_url(
         self,
         report_name: str,
@@ -317,12 +364,21 @@ class CustomReportType(WorkdayTypeBase):
             'flatten_list_dicts', 'drop_flattened_columns',
             'supervisory_organizations', 'supervisory_organizations_wid',
             'supervisory_organization_wid', 'include_subordinate_organizations',
-            'query_string_template'
+            'query_string_template', 'output_format'
         }
 
         offer_and_hire = self._coerce_bool(query_params.pop('offer_and_hire', False))
         flatten_list_dicts = self._coerce_bool(query_params.pop('flatten_list_dicts', False))
         drop_flattened_columns = self._coerce_bool(query_params.pop('drop_flattened_columns', False))
+        # Output format: 'xml' (default, legacy) or 'json'. JSON yields a cleaner
+        # shape for reports with nested multi-instance groups (no xmltodict
+        # cardinality split), at the cost of needing a flowtask that supports it.
+        output_format = str(query_params.pop('output_format', 'xml')).strip().lower()
+        if output_format not in ('xml', 'json'):
+            self._logger.warning(
+                "Unknown output_format '%s'; falling back to 'xml'", output_format
+            )
+            output_format = 'xml'
         report_path = query_params.pop('report_path', None)
         query_string_template = query_params.pop('query_string_template', None)
 
@@ -356,6 +412,10 @@ class CustomReportType(WorkdayTypeBase):
             if k not in internal_params
         }
 
+        # RaaS switches output via the ``format`` query param (default is XML).
+        if output_format == 'json' and 'format' not in filtered_params:
+            filtered_params['format'] = 'json'
+
         if offer_and_hire:
             self._logger.debug(
                 "offer_and_hire flag enabled: mapping start/end to Ready for Hire fields and adjusting path"
@@ -412,6 +472,8 @@ class CustomReportType(WorkdayTypeBase):
             # Build base URL without query params, then append template
             base_url = self._build_raas_url(report_name, report_owner, None, report_path)
             url = f"{base_url}?{query_string}"
+            if output_format == 'json' and 'format=' not in query_string:
+                url = f"{url}&format=json"
         else:
             # Use standard URL building with filtered_params
             url = self._build_raas_url(report_name, report_owner, filtered_params, report_path)
@@ -419,6 +481,8 @@ class CustomReportType(WorkdayTypeBase):
         self._logger.info(f"Executing custom report: {report_name}")
         self._logger.debug(f"RaaS URL: {url}")
 
+        accept_mime = "application/json" if output_format == "json" else "application/xml"
+
         # Initialize HTTP client if needed
         if self._http_client is None:
             # Get credentials from component
@@ -446,7 +510,7 @@ class CustomReportType(WorkdayTypeBase):
                     "password": password
                 },
                 auth_type="basic",
-                accept="application/xml",
+                accept=accept_mime,
                 timeout=120
             )
             # Set logger for HTTP client
@@ -457,7 +521,7 @@ class CustomReportType(WorkdayTypeBase):
             result, error = await self._http_client.async_request(
                 url=url,
                 method="GET",
-                accept="application/xml"
+                accept=accept_mime
             )
 
             if error:
@@ -472,15 +536,16 @@ class CustomReportType(WorkdayTypeBase):
             self._logger.error(f"Error executing custom report via REST: {exc}")
             raise
 
-        # Parse the XML response
-        # Convert to bytes for xmltodict
-        xml_bytes = result if isinstance(result, (bytes, bytearray)) else str(result).encode()
-
-        # Parse XML to list of dicts
-        raw_response = self._parse_xml_to_entries(xml_bytes)
+        # Parse the response into a list of report-entry dicts.
+        if output_format == "json":
+            raw_response = self._parse_json_to_entries(result)
+        else:
+            # Convert to bytes for xmltodict
+            xml_bytes = result if isinstance(result, (bytes, bytearray)) else str(result).encode()
+            raw_response = self._parse_xml_to_entries(xml_bytes)
 
         if not raw_response:
-            self._logger.warning("No report entries found in XML response")
+            self._logger.warning("No report entries found in %s response", output_format.upper())
             return pd.DataFrame()
 
         # Convert parsed XML (now as list of dicts) to DataFrame

flowtask-5.12.8/flowtask/interfaces/workday/rest.py

@@ -0,0 +1,217 @@
+"""Workday REST API client (``/ccx/api``).
+
+Minimal async client for Workday's REST surface, sharing :class:`WorkdayConfig`
+(credentials, tenant, prod/sandbox ``env`` selector) with the SOAP
+``WorkdayService``. Unlike the WSDL services — which have **no** operation to
+read raw time clock events — the REST API exposes them, echoing back the
+client-assigned ``Time_Clock_Event_ID`` as ``reference_ID`` and the effective
+``timeEntryCode`` applied to *In* events. That makes post-punch verification
+possible.
+
+Verified endpoints (Workday implementation tenant, 2026-07-03):
+
+- ``GET /ccx/api/v1/{tenant}/workers?search={text}`` — worker lookup; each row
+  carries ``id`` (the Workday WID) and ``descriptor``.
+- ``GET /ccx/api/timeTracking/v5/{tenant}/timeClockEvents?worker={WID}`` — raw
+  clock events. The ``worker`` parameter **requires a WID**; Employee_ID values
+  are rejected with ``400 "not found"``.
+
+Example::
+
+    from flowtask.interfaces.workday.config import WorkdayConfig
+    from flowtask.interfaces.workday.rest import WorkdayRestClient
+
+    client = WorkdayRestClient(config=WorkdayConfig(env="sandbox"))
+    workers = await client.find_worker("123456")
+    events = await client.get_time_clock_events(workers[0]["id"])
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time as _time
+from typing import Any, Optional
+
+import httpx
+
+from flowtask.interfaces.workday.config import WorkdayConfig
+
+
+class WorkdayRestClient:
+    """Async client for Workday's ``/ccx/api`` REST endpoints.
+
+    Uses the same OAuth *refresh-token* grant as ``SOAPClient`` (no Redis
+    dependency — the bearer token is cached in-memory until shortly before
+    expiry). Host and credentials come from :class:`WorkdayConfig`, so the
+    ``WORKDAY_ENV`` prod/sandbox selector applies here too.
+
+    Args:
+        config: Explicit credentials / tenant. ``None`` → ``WorkdayConfig()``
+            (conf fallbacks + ``WORKDAY_ENV``).
+        timeout: HTTP timeout in seconds (default 30).
+        time_tracking_version: REST version segment for the timeTracking
+            service (default ``"v5"`` — the version available on this tenant;
+            ``v6`` returned 400 when probed).
+    """
+
+    def __init__(
+        self,
+        *,
+        config: WorkdayConfig | None = None,
+        timeout: int = 30,
+        time_tracking_version: str = "v5",
+    ) -> None:
+        self.config = config or WorkdayConfig()
+        self.timeout = timeout
+        self.time_tracking_version = time_tracking_version
+        self._token: Optional[str] = None
+        self._token_expires_at: float = 0.0
+        self._logger = logging.getLogger("flowtask.workday.rest")
+
+    # ------------------------------------------------------------------
+    # Auth
+    # ------------------------------------------------------------------
+
+    @property
+    def base_url(self) -> str:
+        """REST base: ``{workday_url}/ccx/api`` (env-aware host)."""
+        return f"{self.config.workday_url.rstrip('/')}/ccx/api"
+
+    def set_token(self, token: str, expires_in: int = 300) -> None:
+        """Reuse an externally obtained bearer token (e.g. from the SOAP flow).
+
+        Args:
+            token: A valid Workday OAuth access token.
+            expires_in: Seconds the token remains valid (default 300).
+        """
+        self._token = token
+        self._token_expires_at = _time.monotonic() + max(expires_in - 10, 0)
+
+    async def get_token(self) -> str:
+        """Return a cached bearer token, refreshing via OAuth when expired.
+
+        Performs the same ``refresh_token`` grant as ``SOAPClient`` (Basic auth
+        with client_id/client_secret against ``token_url``).
+
+        Returns:
+            A valid access token.
+        """
+        if self._token and _time.monotonic() < self._token_expires_at:
+            return self._token
+
+        cid = self.config.resolved_client_id
+        secret = self.config.resolved_client_secret
+        basic = base64.b64encode(f"{cid}:{secret}".encode()).decode()
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            resp = await http.post(
+                self.config.resolved_token_url,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": self.config.resolved_refresh_token,
+                },
+                headers={
+                    "Authorization": f"Basic {basic}",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+            )
+            resp.raise_for_status()
+            payload = resp.json()
+
+        self.set_token(payload["access_token"], int(payload.get("expires_in", 300)))
+        self._logger.debug("Workday REST token refreshed (env=%s)", self.config.resolved_env)
+        return self._token  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------
+    # Core GET
+    # ------------------------------------------------------------------
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        """Perform an authenticated GET against ``{base_url}{path}``.
+
+        Args:
+            path: Path below ``/ccx/api`` (must start with ``/``).
+            params: Optional query parameters.
+
+        Returns:
+            The parsed JSON body.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+        """
+        token = await self.get_token()
+        url = f"{self.base_url}{path}"
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            resp = await http.get(
+                url,
+                params=params or {},
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    # ------------------------------------------------------------------
+    # Endpoints
+    # ------------------------------------------------------------------
+
+    async def find_worker(self, search: str, *, limit: int = 20) -> list[dict]:
+        """Search workers; each result carries ``id`` (WID) and ``descriptor``.
+
+        Args:
+            search: Free-text search (name; associate/employee id support is
+                tenant-dependent — verify before relying on it).
+            limit: Max results (default 20).
+
+        Returns:
+            List of worker dicts (empty when no match).
+        """
+        payload = await self.get(
+            f"/v1/{self.config.tenant}/workers",
+            {"search": search, "limit": limit},
+        )
+        return payload.get("data", [])
+
+    async def get_time_clock_events(
+        self, worker_wid: str, *, limit: int = 100
+    ) -> list[dict]:
+        """Return the raw time clock events of a worker.
+
+        Each event carries ``reference_ID`` (the client-assigned
+        ``Time_Clock_Event_ID`` when the event was created via
+        ``Put_Time_Clock_Events``), ``dateTime`` (UTC ISO), ``eventType``,
+        ``comment``, ``timeZone``, and — on *In* events of time-tracking
+        eligible workers — the effective ``timeEntryCode``.
+
+        Args:
+            worker_wid: The worker's Workday WID (NOT an Employee_ID — the
+                REST API rejects those).
+            limit: Max events returned (default 100).
+
+        Returns:
+            List of event dicts (empty when the worker has none).
+        """
+        payload = await self.get(
+            f"/timeTracking/{self.time_tracking_version}/{self.config.tenant}/timeClockEvents",
+            {"worker": worker_wid, "limit": limit},
+        )
+        return payload.get("data", [])
+
+    async def find_time_clock_event(
+        self, worker_wid: str, reference_id: str
+    ) -> dict | None:
+        """Locate one clock event by its client-assigned ``reference_ID``.
+
+        Convenience for punch verification: after ``Put_Time_Clock_Events``
+        succeeds, the event is visible here within ~1 s (verified live).
+
+        Args:
+            worker_wid: The worker's Workday WID.
+            reference_id: The ``Time_Clock_Event_ID`` sent on the Put.
+
+        Returns:
+            The matching event dict, or ``None`` when not (yet) present.
+        """
+        for event in await self.get_time_clock_events(worker_wid):
+            if event.get("reference_ID") == reference_id:
+                return event
+        return None

flowtask-5.12.8/flowtask/services/maintenance/README.md

@@ -0,0 +1,80 @@
+# Flowtask Maintenance / Status Service
+
+SOC2 **CC8 (change management)** support for Flowtask running in aiohttp
+**server mode**. It exposes three surfaces:
+
+| Surface | What it does |
+|---------|--------------|
+| **Status page** | Reports server liveness, the startup-job outcome and the availability of the `/api/v2/task` and `/api/v2/scheduler` APIs. Failures are persisted (Redis, in-memory fallback) for auditing. |
+| **Changelog page** | End-user "What's New" page built from `CHANGELOG.md` or GitHub Releases and served as HTML. |
+| **Maintenance windows** | Register a window (day + hour range) over HTTP; upcoming windows are shown on the status page and emailed on startup via `async-notify`. |
+
+## Wiring it up
+
+Inside a Navigator `AppHandler.configure()` (already done in `app.py`):
+
+```python
+from flowtask.services.maintenance import MaintenanceService
+
+maintenance = MaintenanceService()
+maintenance.setup(self.app)
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/status` | HTML status page |
+| GET | `/changelog` | HTML "What's New" page |
+| GET | `/api/v2/maintenance/status` | JSON status (HTTP 503 when unhealthy) |
+| GET | `/api/v2/maintenance/failures?limit=` | Recent recorded failures |
+| GET | `/api/v2/maintenance/changelog` | Changelog as JSON |
+| GET | `/api/v2/maintenance/windows?upcoming=true` | List maintenance windows |
+| POST | `/api/v2/maintenance/windows` | Register a window |
+| DELETE | `/api/v2/maintenance/windows/{identifier}` | Remove a window |
+
+### Registering a maintenance window
+
+```bash
+curl -X POST http://localhost:8080/api/v2/maintenance/windows \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "title": "Planned DB upgrade",
+        "day": "2030-05-01",
+        "start_time": "02:00",
+        "end_time": "04:00",
+        "description": "Rolling restart",
+        "notify": true
+      }'
+```
+
+## Reporting a startup job outcome
+
+Any component can flag whether its on-startup work succeeded; the result shows
+up in the `startup_job` status probe:
+
+```python
+service = app["flowtask_maintenance"]
+await service.mark_startup("my_loader", ok=True, detail="warmed cache")
+```
+
+The scheduler installed at `app["_scheduler_"]` is always considered as a
+startup signal automatically, so a stalled scheduler surfaces even when no
+other startup jobs are recorded.
+
+## Configuration (`flowtask/conf.py` / environment)
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `MAINTENANCE_ENABLED` | `True` | Master switch |
+| `MAINTENANCE_NOTIFY_ON_STARTUP` | `True` | Email upcoming windows on startup |
+| `MAINTENANCE_NOTIFY_EMAIL` | `DEFAULT_RECIPIENT` | Notification recipient |
+| `MAINTENANCE_GITHUB_REPO` | `None` | `owner/name` for GitHub-sourced changelog |
+| `MAINTENANCE_GITHUB_TOKEN` | `None` | Optional token for the GitHub source |
+| `MAINTENANCE_CHANGELOG_TITLE` | `What's New` | Changelog page heading |
+| `REDIS_URL` | — | Store backend (falls back to in-memory) |
+| `EMAIL_HOST` / `EMAIL_PORT` / `EMAIL_USERNAME` / `EMAIL_PASSWORD` | — | SMTP account for notifications |
+
+Redis is optional: if it is unreachable the store degrades to an in-process
+fallback and flags itself (`degraded_store` in the failures endpoint) instead of
+taking the server down.

flowtask-5.12.8/flowtask/services/maintenance/__init__.py

@@ -0,0 +1,45 @@
+"""Flowtask Maintenance service (SOC2 CC8 change-management surfaces).
+
+Exposes a status page, an end-user changelog ("What's New") page and a
+maintenance-window registration API for Flowtask running in aiohttp server
+mode.
+
+The heavy orchestrator (:class:`MaintenanceService`) is imported lazily so that
+importing lightweight pieces (models, store, changelog parsing) does not drag in
+the full Flowtask configuration/notify stack.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .models import (
+    ChangelogEntry,
+    FailureRecord,
+    HealthCheck,
+    MaintenanceWindow,
+    ServiceState,
+    StatusReport,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .service import MaintenanceService
+
+__all__ = [
+    "MaintenanceService",
+    "MAINTENANCE_APP_KEY",
+    "StatusReport",
+    "HealthCheck",
+    "ServiceState",
+    "MaintenanceWindow",
+    "FailureRecord",
+    "ChangelogEntry",
+]
+
+
+def __getattr__(name: str):
+    """Lazily resolve the orchestrator symbols to avoid heavy imports."""
+    if name in ("MaintenanceService", "MAINTENANCE_APP_KEY"):
+        from . import service
+
+        return getattr(service, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")