Itential Admin
Platform Health and Adapters
admin-platform
Monitor platform health, manage adapters and applications (start/stop/restart/configure), control workflow engine workers, manage database indexes, and check system status.
About this skill
Monitor platform health, manage adapters and applications (start/stop/restart/configure), control workflow engine workers, manage database indexes, and check system status. Use for day-to-day platform operations and troubleshooting.
Instructions
Platform Administration - Health, Adapters, Applications & Engine
Day-to-day platform operations: is the platform healthy? Are adapters connected? Are workers running? Need to restart something? This skill covers monitoring, adapter/app lifecycle, engine control, and index management.
Org, team & personal rules
Before using this skill, check custom/org/, custom/team/ and custom/dev/
in this skill’s own folder. Read every .md file found — any folder may be
empty or absent. Apply them on top of everything below; where a file overrides a
specific rule here, follow the override. More specific wins: dev > team > org >
this document. No customization may weaken this skill’s safety
rules or put credentials in committed files.
Concepts
- Adapters — connectors to external systems (ServiceNow, AWS, Meraki, etc.). Each has a state (RUNNING/STOPPED), connection config, and properties.
- Applications — internal platform apps (WorkFlowEngine, ConfigurationManager, MOP, etc.). Each can be started/stopped/restarted independently.
- Workers — job and task workers that execute workflow steps. Can be activated/deactivated.
- Profiles — saved configurations of adapter/app settings for different environments (dev/staging/prod).
- Indexes — MongoDB indexes used by platform apps. Can become stale and need rebuilding.
Gotchas
GET /health/adaptersreturns{results: [...]}— adapters are in theresultsarrayGET /health/applicationsalso returns{results: [...]}— same shape- Adapter lifecycle is
PUTnotPOST:PUT /adapters/{name}/restart - Adapter
{name}is the instance name fromhealth/adaptersidfield, NOT the package name - Adapter properties endpoint:
PUT /adapters/{name}/propertiestakes{properties: {...}}wrapper - Application restart/stop/start uses the app name from
health/applications, e.g.,WorkFlowEngine GET /health/systemreturns OS-level stats (CPU, memory, uptime), NOT platform healthGET /health/serverreturns platform version, node version, build info- Accounts use
{results: [...], total: N}shape — NOT{data: [...]} - Workflow engine activate/deactivate is
POST(no body required) - Rate limit can only be updated when workers are deactivated —
POST /workflow_engine/deactivatefirst, then update, thenPOST /workflow_engine/activate - Log level change uses a
propertieswrapper withtransportandlevel—{"properties": {"transport": "file", "level": "debug"}}, not{"loglevel": ...}. Transports:file,console,syslog GET /adapters/{name}/changelogsreturns HTTP 500 with “Release notes are available online…” on 6.5 — release notes live at docs.itential.com, not in the APIGET /adapters/{name}/exportcan fail with HTTP 500 (Cannot read properties of undefined);GET /adapters/{name}returns the same configuration (name,type,model,properties) and always works
Health Monitoring
Platform overview
GET /health/server
Returns: version, release, build, arch, platform, node version.
{
"version": "6.5.2",
"release": "6.5.2",
"build": "2025.114.11",
"arch": "x64",
"platform": "linux",
"versions": {"node": "20.20.0", ...},
"uptime": 123456,
"memoryUsage": {...},
"cpuUsage": {...},
"dependencies": {...}
}
Quick version check: GET /version → returns just the version string.
System health (OS-level)
GET /health/system
Returns OS-level stats: arch, release (kernel), uptime, freemem, totalmem, loadavg, cpus.
Who am I?
GET /whoami
Returns current user: id, username, provenance, groups, roles.
Adapter health
GET /health/adapters
{
"results": [
{
"id": "ServiceNow",
"package_id": "@itentialopensource/adapter-servicenow",
"type": "Adapter",
"version": "...",
"state": "RUNNING",
"connection": {"state": "ONLINE"},
"uptime": 123456
}
],
"total": 1
}
Key fields:
id— instance name (use this for lifecycle commands)package_id— adapter packagestate—RUNNING,STOPPED,ERRORconnection.state— upper-case, e.g.ONLINEwhen the adapter can reach its system
Adapter properties are not in the health response — use GET /adapters/{name}.
Single adapter: GET /health/adapters/{name}
Application health
GET /health/applications
{
"results": [
{
"id": "WorkFlowEngine",
"package_id": "@itential/app-workflow_engine",
"type": "Application",
"state": "RUNNING",
"description": "...",
"version": "..."
}
],
"total": 1
}
Single application: GET /health/applications/{name}
Adapter Lifecycle
| Method | Endpoint | Description |
|---|---|---|
| PUT | /adapters/{name}/restart |
Restart an adapter |
| PUT | /adapters/{name}/start |
Start a stopped adapter |
| PUT | /adapters/{name}/stop |
Stop a running adapter |
| GET | /adapters/{name} |
Get full adapter configuration |
| PUT | /adapters/{name} |
Update adapter configuration |
| PUT | /adapters/{name}/properties |
Update adapter properties only |
| PUT | /adapters/{name}/loglevel |
Change adapter log level |
| GET | /adapters/{name}/changelogs |
Change history — returns 500 on 6.5 (see Gotchas) |
| GET | /adapters/{name}/export |
Export adapter configuration — may return 500; use GET /adapters/{name} |
| DELETE | /adapters/{name} |
Delete an adapter |
| POST | /adapters/import |
Import adapter configuration |
Restart an adapter:
PUT /adapters/ServiceNow/restart
No body required. Returns the updated adapter state.
Update adapter properties:
PUT /adapters/ServiceNow/properties
{
"properties": {
"host": "https://instance.service-now.com",
"authentication": {
"username": "admin",
"password": "new-password"
}
}
}
Note: the properties wrapper is required.
Change log level:
PUT /adapters/ServiceNow/loglevel
{
"properties": {
"transport": "file",
"level": "debug"
}
}
Levels for file and console: error, warn, info, debug, trace, spam. For syslog: debug, info, warning, error. PUT /applications/{name}/loglevel takes the same body.
Get adapter configuration schema:
GET /schema/adapters/{name}
Returns the JSON Schema defining valid adapter properties. Use this to understand what fields are configurable.
Application Lifecycle
| Method | Endpoint | Description |
|---|---|---|
| PUT | /applications/{name}/restart |
Restart an application |
| PUT | /applications/{name}/start |
Start a stopped application |
| PUT | /applications/{name}/stop |
Stop a running application |
| GET | /applications/{name} |
Get full application configuration |
| PUT | /applications/{name} |
Update application configuration |
| PUT | /applications/{name}/properties |
Update application properties only |
| PUT | /applications/{name}/loglevel |
Change log level |
| GET | /applications/{name}/changelogs |
Get change history |
Restart an application:
PUT /applications/WorkFlowEngine/restart
Get application schema:
GET /schema/applications/{name}
Workflow Engine Control
Worker status
GET /workflow_engine/workers/status
{
"jobWorker": {"running": true, "clusterValue": "not defined", "localValue": "not defined", "startupValue": true},
"taskWorker": {"running": true, "clusterValue": "not defined", "localValue": "not defined", "startupValue": true}
}
Activate/deactivate engine
POST /workflow_engine/activate
POST /workflow_engine/deactivate
No body required. Controls whether the engine processes jobs.
Rate limiting
GET /workflow_engine/workers/rate_limit
{"rateLimit": 0, "rateLimitPeriod": 1}
PUT /workflow_engine/workers/rate_limit
{"rateLimit": 10, "rateLimitPeriod": 1}
rateLimit— max jobs per period (0 = unlimited)rateLimitPeriod— period in seconds
Database Indexes
List all indexes
GET /indexes
Returns an object keyed by collection name, each with application and an indexes array.
Check index status
GET /indexes/status
Shows which collections have pending index rebuilds.
GET /indexes/{collection}/status
Status for one collection: {"missing": [], "misnamed": [], "external": [], "indexed": 3, "total": 3, "collectionSize": 91391, "inProgress": false} — rebuild when missing or misnamed isn’t empty.
Rebuild indexes
POST /indexes/{collection}
Triggers index rebuild for a collection. Use when queries are slow or after migrations.
Customization
Platform banner
GET /customization/banner
PUT /customization/banner
Set a platform-wide banner message (e.g., “Maintenance window tonight 10pm-2am”). GET returns {"result": {...}}; PUT takes the banner itself — text, active, startTime, dismissible and allPages are required:
{
"text": "Maintenance window tonight 10pm-2am",
"active": true,
"startTime": "2026-10-09T22:00:00.000Z",
"endTime": "2026-10-10T02:00:00.000Z",
"dismissible": true,
"allPages": true,
"backgroundColor": "#007dbc"
}
Admin Scenarios
1. Platform health check
1. GET /version → confirm platform version
2. GET /health/server → check server health
3. GET /health/adapters → check all adapter states
4. GET /health/applications → check all app states
5. GET /workflow_engine/workers/status → check workers running
6. Flag any STOPPED/ERROR adapters or apps
2. Restart a failing adapter
1. GET /health/adapters/{name} → confirm it's in ERROR/STOPPED
2. PUT /adapters/{name}/restart → restart it
3. GET /health/adapters/{name} → verify RUNNING
4. If still failing: GET /adapters/{name} → check configuration
5. GET /schema/adapters/{name} → understand configurable properties
6. PUT /adapters/{name}/properties → fix config if needed
3. Troubleshoot slow job processing
1. GET /workflow_engine/workers/status → are workers running?
2. GET /workflow_engine/workers/rate_limit → is rate limiting active?
3. GET /indexes/status → are indexes stale?
4. POST /indexes/{collection} → rebuild if needed
5. PUT /workflow_engine/workers/rate_limit → adjust if rate limited