topdesk-service-intelligence-runtime

name	topdesk-service-intelligence-runtime
description	Operate the TOPdesk Service Intelligence workflow with connector checks, analyzer orchestration, run history, governance gates, and HTML/Markdown readouts.
license	MIT

TOPdesk Service Intelligence Runtime

Use this skill when a user wants to move from individual TOPdesk accelerator scripts to an operational run: connector readiness, data inputs, analyzer execution, evidence outputs, governance gates, and repeatable reporting.

What This Skill Provides

• Runtime configuration schema for local TOPdesk exports and optional live API/OData access.
• Connector preflight checks for TOPDESK_BASE_URL, TOPDESK_USERNAME, and TOPDESK_APP_PASSWORD.
• Orchestration for Tenant Drift, Process Debt, AI Adoption Ledger, Automation Sandbox, Readiness Scoring, Digital Twin Light, and Executive Narrative.
• Run history as JSONL so repeated executions can be compared.
• SQLite run store for persisted runtime and module results.
• Monitoring JSON for external checks, dashboards, or scheduled-job health probes.
• Windows Scheduled Task registration script for repeatable local execution.
• DPAPI-backed local secret store for TOPdesk runtime credentials.
• Local HTTP status server with health, runs, modules, and dashboard endpoints.
• HTML and Markdown runtime readouts for stakeholders.
• Production gates that state what is ready, blocked, or requires tenant-specific credentials.

Boundaries

• State hosted monitoring, SaaS operation, or unattended production execution only when the deployment, owner, scheduler, secret store, monitoring, and support model exist.
• Do not fetch live TOPdesk data unless the tenant has approved credentials, purpose, scope, and retention.
• Treat live connector use as tenant-specific. The plugin ships scripts and operating artifacts; the customer controls credentials and environment.

Standard Workflow

1. Create or edit a runtime config from assets/runtime-config.example.json.

2. Run a dry plan first:

   python topdesk-service-intelligence-runtime/scripts/run_service_intelligence.py --config runtime-config.json --out-dir out/runtime --dry-run
   

3. Run connector preflight if live access is in scope:

   python topdesk-service-intelligence-runtime/scripts/topdesk_live_connector.py preflight
   

4. Store approved TOPdesk credentials in the local DPAPI secret store when environment variables should not be kept in the task definition:

   python topdesk-service-intelligence-runtime/scripts/topdesk_secret_store.py set --store out/runtime/topdesk-secrets.dpapi.json
   python topdesk-service-intelligence-runtime/scripts/topdesk_live_connector.py preflight --secret-store out/runtime/topdesk-secrets.dpapi.json
   

5. Execute the runtime against approved exports:

   python topdesk-service-intelligence-runtime/scripts/run_service_intelligence.py --config runtime-config.json --out-dir out/runtime
   

6. Persist state and monitoring when operating repeatedly:

   python topdesk-service-intelligence-runtime/scripts/run_service_intelligence.py --config runtime-config.json --out-dir out/runtime --state-db out/runtime/service-intelligence.sqlite --monitoring-json out/runtime/runtime-monitoring.json
   

7. Serve the local status API and dashboard:

   python topdesk-service-intelligence-runtime/scripts/service_intelligence_server.py --state-db out/runtime/service-intelligence.sqlite --monitoring-json out/runtime/runtime-monitoring.json
   

8. Register a local Windows schedule when owner, retention, and disable path are approved:

   powershell -ExecutionPolicy Bypass -File topdesk-service-intelligence-runtime/scripts/Register-ServiceIntelligenceSchedule.ps1 -ConfigPath runtime-config.json -OutDir out/runtime -StateDb out/runtime/service-intelligence.sqlite -MonitoringJson out/runtime/runtime-monitoring.json -WhatIf
   

9. Review runtime-readout.md, runtime-dashboard.html, runtime-plan.json, runtime-history.jsonl, operational-gates.csv, service-intelligence.sqlite, and runtime-monitoring.json.

Inputs

The runtime config accepts these optional sections:

• tenant: Tenant name and environment label.
• inputs: CSV paths for catalogs, incidents, status transitions, assignment transitions, AI usage, automation scenarios, readiness checklist, baseline metrics, and digital-twin scenarios.
• modules: Boolean flags for the analyzers to run.
• governance: Owner, retention, PII policy, approval reference, and production gate state.
• connector: Optional live access mode. Keep enabled false until credentials and approval are ready.
• runtime.web: Optional local HTTP server settings.

Outputs

• runtime-plan.json: resolved modules, inputs, blockers, and commands.
• runtime-readout.md: human-readable operating report.
• runtime-dashboard.html: local HTML dashboard for run status and gates.
• operational-gates.csv: gate-by-gate readiness evidence.
• runtime-history.jsonl: append-only run ledger.
• service-intelligence.sqlite: persisted run and module state when --state-db is supplied.
• runtime-monitoring.json: latest machine-readable status when --monitoring-json is supplied.
• Local HTTP endpoints: /health, /api/runs, /api/modules, and /dashboard.