Job: with Event Topic

Audience: Integrators who need downstream subscribers to observe job execution progress or outcomes over MQTT — separately from the structured log messages going to KeeperLogger.

Most job tasks only need KeeperLogger for output. This example is for the less common case where another component needs to react to events your task publishes in real time: a dashboard, an alerting bridge, an orchestrator, or any subscriber that cannot wait for log aggregation. The eventTopic field declares a dedicated MQTT topic for this purpose, and mqttTopics.allowedPublications must list it explicitly or publish calls will be denied.

This example uses Windows paths. For Linux and macOS, apply the path and osFilter changes shown in the Minimal Linux and Minimal macOS examples.

The Job JSON

{
  "id": "my-tool",
  "name": "My Tool",
  "description": "Runs MyTool on an interval and publishes progress events to a dedicated MQTT topic.",
  "enabled": true,

  "schedule": {
    "intervalMinutes": 60
  },

  "eventTopic": "Jobs/my-tool/events",

  "osFilter": {
    "windows": true,
    "linux": false,
    "macOS": false
  },

  "mqttTopics": {
    "allowedPublications": [
      "KeeperLogger",
      "Jobs/my-tool/events"
    ],
    "allowedSubscriptions": []
  },

  "parameters": [],

  "tasks": [
    {
      "id": "run-tool",
      "name": "Run tool",
      "ExecutionType": "Service",
      "command": "MyTool",
      "executablePath": "C:\\Program Files\\KeeperPrivilegeManager\\Jobs\\bin\\MyTool\\MyTool.exe",
      "arguments": "--keeper-api-base={KeeperApiBaseUrl}",
      "timeoutSeconds": 3600,
      "continueOnFailure": false,
      "scriptType": "Auto"
    }
  ]
}

What to Change

Field

What to Put Here

id	A unique identifier for this job. Use hyphens — no underscores. Filename must match: my-tool.json for "id": "my-tool".
name	A human-readable name shown in logs and the admin view.
eventTopic	The MQTT topic your task publishes events to. Must match exactly — same string — in mqttTopics.allowedPublications.
mqttTopics.allowedPublications	Must include both KeeperLogger (if you publish logs) and the eventTopic string. Any topic your task publishes to must appear here.
tasks[0].command	The name of your binary without a path or extension.
tasks[0].executablePath	Full path to your binary on the endpoint.
tasks[0].arguments	Flags your binary accepts. Keep {KeeperApiBaseUrl}.

How This Works

eventTopic declares the MQTT topic the agent associates with this job's execution events. If you omit it, the default topic pattern is Jobs/{jobId}/events — for a job with "id": "my-tool", that is Jobs/my-tool/events. Setting it explicitly, as shown here, makes the topic visible in the JSON and prevents surprises if the default pattern ever changes.

The critical rule is that eventTopic and mqttTopics.allowedPublications must stay in sync. The broker enforces the allowed publications list at the point of publish — if your task publishes to Jobs/my-tool/events but that string is not in allowedPublications, the MQTT connection will succeed and the publish call will be silently denied. This is the most common misconfiguration with event topics. Whenever you change eventTopic, update allowedPublications to match.

Your task binary publishes to the event topic the same way it publishes to KeeperLogger — via the MQTT connection it opens after reading broker settings from Plugin Settings. The event topic is just an additional topic the broker permits. The payload format is your choice; it does not need to follow the KeeperLogger RequestMessage structure.

Subscribers receive the events in real time as your task publishes them. Confirm with your administrator that the subscribing component has permission to subscribe to the event topic before designing around it.

Before You Deploy

1. Verify that eventTopic and the corresponding entry in mqttTopics.allowedPublications are identical strings. A mismatch is not a validation error — it will only surface at runtime as a denied publish.

2. Confirm that any downstream subscriber has MQTT subscribe permission for the event topic.

3. Deploy the binary to executablePath before registering the job.

4. Filename must match id.

Deploy

Validate before saving:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/validate" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-tool.json)

Create the job:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-tool.json)

Trigger a manual run and verify that events appear on the expected topic:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/my-tool/trigger" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body "{}"