# Topdesk Service Intelligence Runtime

> Operate the TOPdesk Service Intelligence workflow with connector checks, analyzer orchestration, run history, governance gates, and HTML/Markdown readouts.

- Skill: `rweisssieker-xp/topdesk-service-intelligence-runtime` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add rweisssieker-xp/topdesk-service-intelligence-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rweisssieker-xp/topdesk-service-intelligence-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: rweisssieker-xp (https://skillmd.com/u/rweisssieker-xp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rweisssieker-xp/topdesk-service-intelligence-runtime

---


# 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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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
   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`.