Commands API

API Version: 1.0.0
Base URL: https://next.itrslab.com/commands/api

The ITRS Commands API provides a comprehensive interface for managing and executing commands within the ITRS Analytics platform. This API allows you to register commands, execute them, monitor their status, and manage command execution history.

Command Registry Copied

The Command Registry endpoints allow you to manage command definitions, including creating, updating, deleting, and querying commands.

Insert/Update Command Copied

Endpoint: PUT /v1/commands
Description: Upsert a command (insert or update if it already exists).

Request Copied

Parameter	Type	Location	Required	Description
command	PutCommandRequest	Body	Yes	The command definition to insert or update

Example Request Copied

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "targets": [
      {
        "entity": {
          "entityFilter": {
            "expression": {
              "set": {
                "namespace": "itrsgroup.com/system",
                "name": "severity",
                "values": ["critical", "warn"]
              }
            }
          }
        }
      }
    ],
    "displayName": "Notify",
    "resources": ["commands.notify"],
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "description": "Select the configuration to use",
          "type": {
            "options": {
              "strings": {
                "entries": [
                  {
                    "value": "1",
                    "displayValue": "Kubernetes Containers"
                  }
                ]
              }
            }
          }
        }
      }
    ]
  }
}

Response Copied

Success (200 OK):

{
  // PutCommandResponse - typically empty for success
}

Delete Command Copied

Endpoint: DELETE /v1/commands
Description: Delete a command from the registry.

Request Copied

Parameter	Type	Location	Required	Description
serviceNamespace	string	Query	No	The service namespace of the command to delete
serviceName	string	Query	No	The service name of the command to delete
name	string	Query	No	The name of the command to delete

Example Request Copied

DELETE /v1/commands?serviceNamespace=itrsgroup.com/obcerv/app&serviceName=obcerv-app-notifications&name=entity:notify

Response Copied

Success (200 OK):

{
  // DeleteCommandResponse - typically empty for success
}

Query Commands Copied

Endpoint: POST /v1/commands/query
Description: Query command definitions that apply to a specific target and/or service.

Request Copied

Parameter	Type	Location	Required	Description
request	QueryCommandsRequest	Body	Yes	The query criteria

Example Request Copied

{
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "cluster",
          "value": "itrs-obcerv"
        },
        {
          "key": "namespace",
          "value": "itrs"
        }
      ]
    }
  },
  "skip": 0,
  "limit": 100
}

Response Copied

Success (200 OK):

{
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "targets": [
        {
          "entity": {
            "entityFilter": {
              "expression": {
                "set": {
                  "namespace": "itrsgroup.com/system",
                  "name": "severity",
                  "values": ["critical", "warn"]
                }
              }
            }
          }
        }
      ],
      "displayName": "Notify",
      "resources": ["commands.notify"],
      "arguments": [
        {
          "key": "Configuration",
          "argument": {
            "description": "Select the configuration to use",
            "type": {
              "options": {
                "strings": {
                  "entries": [
                    {
                      "value": "1",
                      "displayValue": "Kubernetes Containers"
                    }
                  ]
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Register Commands Copied

Endpoint: POST /v1/commands/register
Description: Registers all commands for a service. All commands must have the same service definition. Any existing commands not in the request will be deleted.

Request Copied

Parameter	Type	Location	Required	Description
request	RegisterCommandsRequest	Body	Yes	Service and commands to register

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "targets": [
        {
          "entity": {
            "entityFilter": {
              "expression": {
                "set": {
                  "namespace": "itrsgroup.com/system",
                  "name": "severity",
                  "values": ["critical", "warn"]
                }
              }
            }
          }
        }
      ],
      "displayName": "Notify",
      "resources": ["commands.notify"],
      "arguments": [
        {
          "key": "Configuration",
          "argument": {
            "description": "Select the configuration to use",
            "type": {
              "options": {
                "strings": {
                  "entries": [
                    {
                      "value": "1",
                      "displayValue": "Kubernetes Containers"
                    }
                  ]
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Response Copied

Success (200 OK):

{
  "added": 2,
  "updated": 1,
  "deleted": 1
}

Get Command Service Copied

Endpoint: GET /v1/commands/service
Description: Retrieves a command service definition.

Request Copied

Parameter	Type	Location	Required	Description
namespace	string	Query	No	The service namespace
name	string	Query	No	The service name

Example Request Copied

GET /v1/commands/service?namespace=itrsgroup.com/obcerv/app&name=obcerv-app-notifications

Response Copied

Success (200 OK):

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "filters": [],
  "commands": ["entity:notify"]
}

Command Execution Copied

The Command Execution endpoints manage the lifecycle of command execution, from triggering commands to monitoring their status and managing their output.

Execute Command Copied

Endpoint: POST /v1/commands/execution
Description: Submits a command for execution.

Request Copied

Parameter	Type	Location	Required	Description
command	ExecuteCommandRequest	Body	Yes	The command to execute

Example Request Copied

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "string": "1"
        }
      }
    ],
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "node",
            "value": "itrsgroup.node.101.com"
          }
        ]
      }
    }
  }
}

Response Copied

Success (200 OK):

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_TRIGGERED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

Clear Command Execution History Copied

Endpoint: DELETE /v1/commands/execution/history
Description: Clears historical command execution entries for a user.

Request Copied

Parameter	Type	Location	Required	Description
from	string (date-time)	Query	No	Clear commands that terminated after this point in time
to	string (date-time)	Query	No	Clear commands that terminated before this point in time. Defaults to current time if not supplied

Example Request Copied

DELETE /v1/commands/execution/history?from=2024-06-01T00:00:00Z&to=2024-06-15T00:00:00Z

Response Copied

Success (200 OK):

{
  // ClearCommandExecutionHistoryResponse - typically empty
}

Query Triggered Commands Copied

Endpoint: POST /v1/commands/execution/query
Description: Returns all triggered commands for a service.

Request Copied

Parameter	Type	Location	Required	Description
request	QueryTriggeredCommandsRequest	Body	Yes	Query parameters

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "limit": 20,
  "skip": 0
}

Response Copied

Success (200 OK):

{
  "commandEntries": [
    {
      "commandExecution": {
        "execId": "1",
        "command": {
          "id": {
            "service": {
              "namespace": "itrsgroup.com/obcerv/app",
              "name": "obcerv-app-notifications"
            },
            "name": "entity:notify"
          },
          "arguments": [
            {
              "key": "Configuration",
              "argument": {
                "string": "1"
              }
            }
          ],
          "target": {
            "entity": {
              "dimensions": [
                {
                  "key": "node",
                  "value": "itrsgroup.node.101.com"
                }
              ]
            }
          }
        },
        "triggeredAt": "2024-06-15T19:32:49.552871Z"
      }
    }
  ],
  "hasMore": false
}

Update Command Status Copied

Endpoint: PUT /v1/commands/execution/status
Description: Sets the status of an executing command.

Request Copied

Parameter	Type	Location	Required	Description
request	PutCommandExecutionStatusRequest	Body	Yes	Status update request

Example Request (Claim Command) Copied

{
  "claim": {
    "claimFor": "300s",
    "execId": "1"
  }
}

Response Copied

Success (200 OK):

{
  "execId": "20",
  "claimId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CLAIMED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

Query Command Status Copied

Endpoint: POST /v1/commands/execution/status/query
Description: Query the latest status of executing commands.

Request Copied

Parameter	Type	Location	Required	Description
request	QueryTriggeredCommandsStatusRequest	Body	Yes	Query parameters

Example Request Copied

{
  "from": "2024-06-15T05:58:31.013397Z",
  "skip": 0,
  "limit": 100,
  "stateFilter": ["COMMAND_LIFECYCLE_COMPLETED"]
}

Response Copied

Success (200 OK):

{
  "commandStatusEntries": [
    {
      "execId": "1",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_COMPLETED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": ["admin"],
            "groups": ["engineering-managers"]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "completedAt": "2024-07-23T09:13:34.062745Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        }
      }
    }
  ],
  "hasMore": false,
  "numEntries": 1024
}

Endpoint: POST /v1/commands/execution/status/subscribe
Description: Subscribes to triggered command status updates via Server-Sent Events.

Request Copied

Parameter	Type	Location	Required	Description
request	SubscribeTriggeredCommandsStatusRequest	Body	Yes	Subscription parameters

Example Request Copied

{
  "from": "2024-06-15T05:58:31.013397Z",
  "limit": 100
}

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: status-update
data: {
  "statusEntry": {
    "execId": "1",
    "command": { ... },
    "status": { ... }
  }
}

Endpoint: POST /v1/commands/execution/subscribe
Description: Subscribes to commands that have been triggered for a service via Server-Sent Events.

Request Copied

Parameter	Type	Location	Required	Description
request	SubscribeTriggeredCommandsRequest	Body	Yes	Service to subscribe to

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Middleware Gateway"
  }
}

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: command-execution
data: {
  "commandExecution": {
    "execId": "1",
    "command": { ... },
    "triggeredAt": "2024-07-23T09:12:39.065404Z"
  }
}

Cancel Command Execution Copied

Endpoint: DELETE /v1/commands/execution/{execId}
Description: Cancels an executing command. Only applies to commands that support cancellation.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	A unique identifier for this command instance
reason	string	Query	No	The reason for the cancellation

Example Request Copied

DELETE /v1/commands/execution/123?reason=User%20requested%20cancellation

Response Copied

Success (200 OK):

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "User requested cancellation"
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

Clear Single Command Execution Entry Copied

Endpoint: DELETE /v1/commands/execution/{execId}/history
Description: Clears a specific historical command execution entry.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution id

Example Request Copied

DELETE /v1/commands/execution/123/history

Response Copied

Success (200 OK):

{
  // ClearCommandExecutionEntryResponse - typically empty
}

Endpoint: POST /v1/commands/execution/{execId}/output/subscribe
Description: Subscribes to command status and output changes for a specific command via Server-Sent Events.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution id

Example Request Copied

POST /v1/commands/execution/123/output/subscribe

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: output-update
data: {
  "entry": {
    "status": { ... },
    "outputStreams": {
      "outputStream": {
        "streamOperation": "STREAM_OPERATION_APPEND",
        "contentType": "text/plain",
        "output": "INFO  - Started"
      },
      "execStream": {
        "streamOperation": "STREAM_OPERATION_REPLACE",
        "contentType": "text/plain",
        "output": "Command 'tail -f app.log' returned exit code 0"
      }
    },
    "command": { ... }
  }
}

Extend Command Time-to-Live Copied

Endpoint: POST /v1/commands/execution/{execId}/time-to-live
Description: Extends the time-to-live of a running command.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution id
request	ExtendTtlRequest	Body	Yes	TTL extension request

Example Request Copied

{
  "execId": "1",
  "extendBy": "3600s"
}

Response Copied

Success (200 OK):

{
  "endOfLife": "2024-06-15T05:58:31.013397Z"
}

Configuration Copied

Get Configuration Copied

Endpoint: GET /v1/config
Description: Returns the application’s current configuration settings.

Request Copied

No parameters required.

Example Request Copied

GET /v1/config

Response Copied

Success (200 OK):

{
  "config": {
    "rpcTimeout": "30s",
    "serviceLivenessTimeout": "3600s",
    "entityCacheTtl": "30s",
    "commandRegistration": {
      "housekeepingInterval": "300s",
      "tokenTtl": "60s"
    },
    "commandExecution": {
      "claimTimeout": "300s",
      "retentionPeriod": "2592000s",
      "housekeepingInterval": "3600s",
      "persistenceEnabled": true,
      "persistencePath": "/data/commands",
      "maxEntries": 10000,
      "maxHistory": 100,
      "timeToLive": "3600s",
      "statsPollInterval": "300s",
      "averageEntrySizeBytes": 16384,
      "averageHistoricalEntrySizeBytes": 65536
    }
  }
}

API Information Copied

Get API Versions Copied

Endpoint: GET /versions
Description: Returns the supported API versions.

Request Copied

No parameters required.

Example Request Copied

GET /versions

Response Copied

Success (200 OK):

{
  "versions": ["v1"]
}

Data Models Copied

All schemas are listed in alphabetical order for easy reference.

Any Copied

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

{
  "value": {
    "@type": "string"
  },
  "yaml": "string"
}

ArgumentType Copied

Represents different types of arguments that can be passed to commands.

{
  "string": {
    "default": "string",
    "minLength": 0,
    "maxLength": 100,
    "isPassword": false,
    "isMultiLine": false
  }
}

BooleanType Copied

{
  "default": false
}

CancelCommandExecutionResponse Copied

Response returned when canceling a command execution.

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "User requested cancellation"
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

ClaimCommand Copied

Used to claim a command for execution.

{
  "claimFor": "300s",
  "execId": "1",
  "comment": "string"
}

ClearCommandExecutionEntryResponse Copied

Response for clearing a single command execution entry.

{}

ClearCommandExecutionHistoryResponse Copied

Response for clearing command execution history.

{}

Command Copied

Represents a command definition that can be executed.

{
  "id": {
    "service": {
      "namespace": "string",
      "name": "string"
    },
    "name": "string"
  },
  "targets": [
    {
      "entity": {
        "entityFilter": {
          "expression": {
            "set": {
              "namespace": "itrsgroup.com/system",
              "name": "severity",
              "values": ["critical", "warn"]
            }
          }
        }
      }
    }
  ],
  "displayName": "string",
  "resources": ["string"],
  "categories": ["string"],
  "arguments": [
    {
      "key": "string",
      "argument": {
        "name": "string",
        "description": "string",
        "required": false,
        "type": { }
      }
    }
  ],
  "description": "string"
}

CommandArgument Copied

Represents a command argument value.

{
  "string": "value"
}

CommandArgumentEntry Copied

Maps a command argument key to its value.

{
  "key": "Configuration",
  "argument": {
    "string": "1"
  }
}

CommandArgumentType Copied

Defines the type and properties of a command argument.

{
  "required": false,
  "name": "string",
  "description": "string",
  "type": {
    "string": {
      "default": "string",
      "minLength": 0,
      "maxLength": 100
    }
  }
}

CommandArgumentTypeEntry Copied

Maps a command argument key to its type definition.

{
  "key": "Configuration",
  "argument": {
    "description": "Select the configuration to use",
    "type": {
      "options": {
        "strings": {
          "entries": [
            {
              "value": "1",
              "displayValue": "Kubernetes Containers"
            }
          ]
        }
      }
    }
  }
}

CommandCancellationRequest Copied

Represents a command cancellation request.

{
  "execId": "20",
  "cancelledBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs",
    "roles": ["admin"],
    "groups": ["engineering-managers"]
  },
  "cancelledAt": "2024-06-15T19:51:42.444117Z",
  "reason": "User requested cancellation"
}

CommandExecutionConfig Copied

Configuration settings for command execution.

{
  "claimTimeout": "300s",
  "retentionPeriod": "2592000s",
  "housekeepingInterval": "3600s",
  "persistenceEnabled": true,
  "persistencePath": "/data/commands",
  "maxEntries": 10000,
  "maxHistory": 100,
  "timeToLive": "3600s",
  "statsPollInterval": "300s",
  "averageEntrySizeBytes": 16384,
  "averageHistoricalEntrySizeBytes": 65536
}

CommandExecutionEntry Copied

Represents a command execution with its status and output.

{
  "status": {
    "state": "COMMAND_LIFECYCLE_COMPLETED"
  },
  "outputStreams": {
    "outputStream": {
      "streamOperation": "STREAM_OPERATION_APPEND",
      "contentType": "text/plain",
      "output": "Command output"
    }
  },
  "command": {
    "id": {
      "service": {
        "namespace": "string",
        "name": "string"
      },
      "name": "string"
    }
  },
  "displayName": "Snooze"
}

CommandExecutionRequest Copied

Request to execute a command.

{
  "execId": "20",
  "command": {
    "id": {
      "service": {
        "namespace": "string",
        "name": "string"
      },
      "name": "string"
    }
  },
  "triggeredBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs"
  },
  "triggeredAt": "2024-06-15T19:51:17.437128Z"
}

CommandId Copied

Unique identifier for a command.

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "name": "entity:notify"
}

CommandOutputStreams Copied

Contains the output streams from command execution.

{
  "outputStream": {
    "streamOperation": "STREAM_OPERATION_APPEND",
    "contentType": "text/plain",
    "output": "INFO - Started"
  },
  "errorStream": {
    "streamOperation": "STREAM_OPERATION_APPEND",
    "contentType": "text/plain",
    "output": "Error message"
  },
  "execStream": {
    "streamOperation": "STREAM_OPERATION_REPLACE",
    "contentType": "text/plain",
    "output": "Command 'tail -f app.log' returned exit code 0"
  }
}

CommandRegistrationConfig Copied

Configuration settings for command registration.

{
  "housekeepingInterval": "300s",
  "tokenTtl": "60s"
}

CommandRegistrationToken Copied

Token used for batched command registration.

{
  "token": "f47ac10b58cc4372a5670e02b2c3d479",
  "expiry": "2024-06-15T05:58:31.013397Z"
}

CommandStatus Copied

Represents the current status and lifecycle state of a command execution.

{
  "state": "COMMAND_LIFECYCLE_TRIGGERED",
  "triggerInfo": {
    "triggeredAt": "2024-06-15T19:51:17.437128Z",
    "triggeredBy": {
      "username": "jbloggs",
      "displayName": "Joe Bloggs",
      "roles": ["admin"],
      "groups": ["engineering-managers"]
    }
  },
  "claimInfo": {
    "claimedAt": "2024-06-15T19:51:27.439549Z",
    "claimExpiresAt": "2024-06-15T19:56:47.439558Z",
    "comment": "string"
  },
  "outputInfo": {
    "lastUpdatedAt": "2024-06-15T19:51:37.442321Z",
    "completedAt": "2024-06-15T19:51:37.442321Z",
    "hasOutputStream": true,
    "hasExecStream": true,
    "hasErrorStream": false
  },
  "failureInfo": {
    "failedAt": "2024-06-15T19:51:37.442321Z",
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions"
  },
  "cancellationInfo": {
    "cancelledAt": "2024-06-15T19:51:42.444117Z",
    "reason": "Cancelled by user 'admin'"
  },
  "endOfLife": "2024-06-15T20:51:17.437128Z"
}

CommandStatusEntry Copied

Command status with execution details.

{
  "execId": "20",
  "command": {
    "id": {
      "service": {
        "namespace": "string",
        "name": "string"
      },
      "name": "string"
    }
  },
  "status": {
    "state": "COMMAND_LIFECYCLE_COMPLETED"
  },
  "displayName": "Snooze"
}

CommandStatus_CommandCancellationInfo Copied

Information about command cancellation.

{
  "cancelledAt": "2024-06-15T19:51:42.444117Z",
  "reason": "User requested cancellation"
}

CommandStatus_CommandClaimInfo Copied

Information about command claim.

{
  "claimedAt": "2024-06-15T19:51:27.439549Z",
  "comment": "string",
  "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
}

CommandStatus_CommandFailureInfo Copied

Information about command failure.

{
  "failedAt": "2024-06-15T19:51:37.442321Z",
  "code": "PERMISSION_DENIED",
  "message": "Insufficient permissions"
}

CommandStatus_CommandOutputInfo Copied

Information about command output.

{
  "lastUpdatedAt": "2024-06-15T19:51:37.442321Z",
  "completedAt": "2024-06-15T19:51:37.442321Z",
  "hasOutputStream": true,
  "hasExecStream": true,
  "hasErrorStream": false
}

CommandStatus_CommandTriggerInfo Copied

Information about command triggering.

{
  "triggeredAt": "2024-06-15T19:51:17.437128Z",
  "triggeredBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs",
    "roles": ["admin"],
    "groups": ["engineering-managers"]
  }
}

CommandStream Copied

Represents a single output stream from command execution.

{
  "streamOperation": "STREAM_OPERATION_APPEND",
  "contentType": "text/plain",
  "output": "Command output"
}

CommandTarget Copied

The target of a command execution.

{
  "entity": {
    "dimensions": [
      {
        "key": "node",
        "value": "itrsgroup.node.101.com"
      }
    ]
  }
}

CommandTargetFilter Copied

Filter that determines the targets a command applies to.

{
  "entity": {
    "entityFilter": {
      "expression": {
        "set": {
          "namespace": "itrsgroup.com/system",
          "name": "severity",
          "values": ["critical", "warn"]
        }
      }
    }
  }
}

CommandTarget_Entity Copied

Entity target for command execution.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

CommandTarget_Log Copied

Log target for command execution.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "log": {
    "namespace": "string",
    "name": "string"
  }
}

CommandTarget_Metric Copied

Metric target for command execution.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "metric": {
    "namespace": "string",
    "name": "string"
  }
}

CommandsServiceConfig Copied

Configuration settings for the Commands service.

{
  "rpcTimeout": "30s",
  "serviceLivenessTimeout": "3600s",
  "entityCacheTtl": "30s",
  "commandRegistration": {
    "housekeepingInterval": "300s",
    "tokenTtl": "60s"
  },
  "commandExecution": {
    "claimTimeout": "300s",
    "retentionPeriod": "2592000s",
    "housekeepingInterval": "3600s",
    "persistenceEnabled": true,
    "persistencePath": "/data/commands",
    "maxEntries": 10000,
    "maxHistory": 100,
    "timeToLive": "3600s",
    "statsPollInterval": "300s",
    "averageEntrySizeBytes": 16384,
    "averageHistoricalEntrySizeBytes": 65536
  }
}

DateList Copied

List of date options for user input.

{
  "dates": [
    {
      "date": "2024-06-15",
      "timezone": "UTC"
    }
  ],
  "default": {
    "date": "2024-06-15",
    "timezone": "UTC"
  },
  "allowUserInput": false
}

DateType Copied

Date argument type.

{
  "default": {
    "date": "2024-06-15",
    "timezone": "UTC"
  }
}

DeleteCommandResponse Copied

Response for command deletion.

{}

Dimension Copied

A single entity dimension key-value pair.

{
  "key": "string",
  "value": "string"
}

DurationList Copied

List of duration options for user input.

{
  "durations": ["300s", "600s"],
  "default": "300s",
  "allowUserInput": false
}

DurationType Copied

Duration argument type.

{
  "default": "300s",
  "min": "1s",
  "max": "3600s",
  "exclusiveMin": false,
  "exclusiveMax": false
}

EntityFilter Copied

Filter for entities using expressions or dimension filters.

{
  "expression": {
    "set": {
      "namespace": "itrsgroup.com/system",
      "name": "severity",
      "values": ["critical", "warn"]
    }
  }
}

EntityTargetFilter Copied

Filter for entity targets.

{
  "entityFilter": {
    "expression": {
      "set": {
        "namespace": "itrsgroup.com/system",
        "name": "severity",
        "values": ["critical", "warn"]
      }
    }
  }
}

ExecuteCommandRequest Copied

Request to execute a command.

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "string": "1"
        }
      }
    ],
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "node",
            "value": "itrsgroup.node.101.com"
          }
        ]
      }
    }
  }
}

ExecuteCommandResponse Copied

Response from command execution.

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_TRIGGERED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

ExecutingCommand Copied

Represents a command that is being or has been executed.

{
  "id": {
    "service": {
      "namespace": "string",
      "name": "string"
    },
    "name": "string"
  },
  "arguments": [
    {
      "key": "string",
      "argument": {
        "string": "value"
      }
    }
  ],
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    }
  },
  "executionGroup": "string"
}

Expression Copied

Generic expression object for filtering.

{
  "additionalProperties": []
}

ExtendTtlRequest Copied

Request to extend command time-to-live.

{
  "execId": "1",
  "extendBy": "3600s"
}

ExtendTtlResponse Copied

Response from extending command time-to-live.

{
  "endOfLife": "2024-06-15T05:58:31.013397Z"
}

FailCommand Copied

Used to mark a command as failed.

{
  "claimId": "string",
  "code": "PERMISSION_DENIED",
  "message": "Insufficient permissions"
}

FloatList Copied

List of float options for user input.

{
  "floats": [1.0, 2.5, 3.0],
  "default": 1.0,
  "allowUserInput": false
}

FloatType Copied

Float argument type.

{
  "default": 0.0,
  "min": -100.0,
  "max": 100.0,
  "exclusiveMin": false,
  "exclusiveMax": false
}

GetApiVersionsResponse Copied

Response containing supported API versions.

{
  "versions": ["v1"]
}

GetCommandServiceResponse Copied

Response containing command service details.

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "filters": [],
  "commands": ["entity:notify"]
}

GetConfigResponse Copied

Response containing application configuration.

{
  "config": {
    "rpcTimeout": "30s",
    "serviceLivenessTimeout": "3600s",
    "entityCacheTtl": "30s",
    "commandRegistration": {
      "housekeepingInterval": "300s",
      "tokenTtl": "60s"
    },
    "commandExecution": {
      "claimTimeout": "300s",
      "retentionPeriod": "2592000s",
      "housekeepingInterval": "3600s",
      "persistenceEnabled": true,
      "persistencePath": "/data/commands",
      "maxEntries": 10000,
      "maxHistory": 100,
      "timeToLive": "3600s",
      "statsPollInterval": "300s",
      "averageEntrySizeBytes": 16384,
      "averageHistoricalEntrySizeBytes": 65536
    }
  }
}

GoogleProtobufAny Copied

Contains an arbitrary serialized message along with a @type.

{
  "@type": "string"
}

IntegerList Copied

List of integer options for user input.

{
  "integers": [1, 2, 3],
  "default": 1,
  "allowUserInput": false
}

IntegerType Copied

Integer argument type.

{
  "default": 0,
  "min": -100,
  "max": 100
}

LogTargetFilter Copied

Filter for log targets.

{
  "entityFilter": {
    "expression": {
      "set": {
        "namespace": "itrsgroup.com/system",
        "name": "severity",
        "values": ["critical", "warn"]
      }
    }
  },
  "log": {
    "namespace": "string",
    "name": "string"
  }
}

MetricTargetFilter Copied

Filter for metric targets.

{
  "entityFilter": {
    "expression": {
      "set": {
        "namespace": "itrsgroup.com/system",
        "name": "severity",
        "values": ["critical", "warn"]
      }
    }
  },
  "metric": {
    "namespace": "string",
    "name": "string"
  }
}

NamedAny Copied

Automatically-generated message used to represent maps of Any as ordered (name,value) pairs.

{
  "name": "string",
  "value": {
    "value": {},
    "yaml": "string"
  }
}

NamespacedName Copied

Namespace and name pair for resources.

{
  "namespace": "string",
  "name": "string"
}

OrderedDimensionsFilter Copied

Filter that exactly matches entity dimensions taking order into account.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

PutCommandExecutionStatusRequest Copied

Request to update command execution status.

{
  "claim": {
    "claimFor": "300s",
    "execId": "1",
    "comment": "string"
  }
}

PutCommandExecutionStatusResponse Copied

Response from updating command execution status.

{
  "execId": "20",
  "claimId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CLAIMED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": ["admin"],
        "groups": ["engineering-managers"]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "endOfLife": "2024-06-15T20:51:17.437128Z"
  }
}

PutCommandRequest Copied

Request to insert or update a command.

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "targets": [
      {
        "entity": {
          "entityFilter": {
            "expression": {
              "set": {
                "namespace": "itrsgroup.com/system",
                "name": "severity",
                "values": ["critical", "warn"]
              }
            }
          }
        }
      }
    ],
    "displayName": "Notify",
    "resources": ["commands.notify"],
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "description": "Select the configuration to use",
          "type": {
            "options": {
              "strings": {
                "entries": [
                  {
                    "value": "1",
                    "displayValue": "Kubernetes Containers"
                  }
                ]
              }
            }
          }
        }
      }
    ]
  }
}

PutCommandResponse Copied

Response from command insertion/update.

{}

QueryCommandsRequest Copied

Request to query commands.

{
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "cluster",
          "value": "itrs-obcerv"
        },
        {
          "key": "namespace",
          "value": "itrs"
        }
      ]
    }
  },
  "skip": 0,
  "limit": 100
}

QueryCommandsResponse Copied

Response from querying commands.

{
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "targets": [
        {
          "entity": {
            "entityFilter": {
              "expression": {
                "set": {
                  "namespace": "itrsgroup.com/system",
                  "name": "severity",
                  "values": ["critical", "warn"]
                }
              }
            }
          }
        }
      ],
      "displayName": "Notify",
      "resources": ["commands.notify"]
    }
  ]
}

QueryTriggeredCommandsRequest Copied

Request to query triggered commands.

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "limit": 20,
  "skip": 0
}

QueryTriggeredCommandsResponse Copied

Response from querying triggered commands.

{
  "commandEntries": [
    {
      "commandExecution": {
        "execId": "1",
        "command": {
          "id": {
            "service": {
              "namespace": "itrsgroup.com/obcerv/app",
              "name": "obcerv-app-notifications"
            },
            "name": "entity:notify"
          }
        },
        "triggeredAt": "2024-06-15T19:32:49.552871Z"
      }
    }
  ],
  "hasMore": false
}

QueryTriggeredCommandsStatusRequest Copied

Request to query triggered command status.

{
  "from": "2024-06-15T05:58:31.013397Z",
  "skip": 0,
  "limit": 100,
  "stateFilter": ["COMMAND_LIFECYCLE_COMPLETED"]
}

QueryTriggeredCommandsStatusResponse Copied

Response from querying triggered command status.

{
  "commandStatusEntries": [
    {
      "execId": "1",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_COMPLETED"
      }
    }
  ],
  "hasMore": false,
  "numEntries": 1024
}

RegisterCommandsRequest Copied

Request to register commands for a service.

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "targets": [
        {
          "entity": {
            "entityFilter": {
              "expression": {
                "set": {
                  "namespace": "itrsgroup.com/system",
                  "name": "severity",
                  "values": ["critical", "warn"]
                }
              }
            }
          }
        }
      ],
      "displayName": "Notify",
      "resources": ["commands.notify"]
    }
  ]
}

RegisterCommandsResponse Copied

Response from registering commands.

{
  "added": 2,
  "updated": 1,
  "deleted": 1
}

RenewClaimCommand Copied

Used to renew a command claim.

{
  "claimFor": "300s",
  "claimId": "string",
  "comment": "string"
}

Scopes Copied

List of permission scopes.

{
  "scopes": ["view", "execute"]
}

SendCommandOutput Copied

Used to send command output during execution.

{
  "claimId": "string",
  "stateOperation": "COMMAND_STATE_OPERATION_COMPLETE",
  "outputStreams": {
    "outputStream": {
      "streamOperation": "STREAM_OPERATION_APPEND",
      "contentType": "text/plain",
      "output": "Command completed successfully"
    }
  }
}

Service Copied

Identifies a service that can provide commands.

{
  "namespace": "itrsgroup.com/geneos",
  "name": "Middleware Gateway"
}

StringList Copied

List of string options for user input.

{
  "entries": [
    {
      "value": "1",
      "displayValue": "Option 1"
    }
  ],
  "default": {
    "value": "1",
    "displayValue": "Option 1"
  },
  "allowUserInput": false
}

StringList_StringEntry Copied

Single string entry with value and display value.

{
  "value": "1",
  "displayValue": "Kubernetes Containers"
}

StringType Copied

String argument type.

{
  "default": "string",
  "minLength": 0,
  "maxLength": 100,
  "isPassword": false,
  "isMultiLine": false
}

SubscribeTriggeredCommandOutputResponse Copied

Response from subscribing to command output.

{
  "entry": {
    "status": {
      "state": "COMMAND_LIFECYCLE_COMPLETED"
    },
    "outputStreams": {
      "outputStream": {
        "streamOperation": "STREAM_OPERATION_APPEND",
        "contentType": "text/plain",
        "output": "INFO - Started"
      },
      "execStream": {
        "streamOperation": "STREAM_OPERATION_REPLACE",
        "contentType": "text/plain",
        "output": "Command 'tail -f app.log' returned exit code 0"
      }
    },
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      }
    }
  }
}

SubscribeTriggeredCommandsRequest Copied

Request to subscribe to triggered commands.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Middleware Gateway"
  }
}

SubscribeTriggeredCommandsResponse Copied

Response from subscribing to triggered commands.

{
  "commandExecution": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      }
    },
    "triggeredAt": "2024-07-23T09:12:39.065404Z"
  }
}

SubscribeTriggeredCommandsStatusRequest Copied

Request to subscribe to command status updates.

{
  "from": "2024-06-15T05:58:31.013397Z",
  "limit": 100
}

SubscribeTriggeredCommandsStatusResponse Copied

Response from subscribing to command status updates.

{
  "statusEntry": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      }
    },
    "status": {
      "state": "COMMAND_LIFECYCLE_FAILED"
    }
  }
}

TimeOfDay Copied

Represents a time of day.

{
  "hours": 12,
  "minutes": 30,
  "seconds": 0,
  "nanos": 0
}

TimeOfDayList Copied

List of time of day options for user input.

{
  "timesOfDay": [
    {
      "timeOfDay": {
        "hours": 9,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      },
      "timezone": "UTC"
    }
  ],
  "default": {
    "timeOfDay": {
      "hours": 9,
      "minutes": 0,
      "seconds": 0,
      "nanos": 0
    },
    "timezone": "UTC"
  },
  "allowUserInput": false
}

TimeOfDayType Copied

Time of day argument type.

{
  "default": {
    "timeOfDay": {
      "hours": 9,
      "minutes": 0,
      "seconds": 0,
      "nanos": 0
    },
    "timezone": "UTC"
  }
}

TimestampList Copied

List of timestamp options for user input.

{
  "timestamps": ["2024-06-15T19:51:17.437128Z"],
  "default": "2024-06-15T19:51:17.437128Z",
  "allowUserInput": false
}

TimestampType Copied

Timestamp argument type.

{
  "default": "2024-06-15T05:58:31.013397Z",
  "min": "2024-01-01T00:00:00Z",
  "max": "2024-12-31T23:59:59Z",
  "exclusiveMin": false,
  "exclusiveMax": false
}

TriggeredCommandEntry Copied

Entry representing a triggered command or cancellation.

{
  "commandExecution": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      }
    },
    "triggeredAt": "2024-06-15T19:32:49.552871Z"
  }
}

UnorderedDimensionsFilter Copied

Filter that exactly matches entity dimensions ignoring order.

{
  "dimensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

User Copied

Represents a user in the system with their permissions and roles.

{
  "username": "jbloggs",
  "displayName": "Joe Bloggs",
  "permissions": {
    "obcerv-app-commands": {
      "scopes": ["view", "execute"]
    }
  },
  "roles": ["admin"],
  "groups": ["engineering-managers"]
}

UserInputOptions Copied

Used for predefined options that users can select from.

{
  "strings": {
    "entries": [
      {
        "value": "1",
        "displayValue": "Option 1"
      }
    ],
    "default": {
      "value": "1",
      "displayValue": "Option 1"
    },
    "allowUserInput": false
  }
}

ZonedDate Copied

Date with timezone information.

{
  "date": "2024-06-15",
  "timezone": "UTC"
}

ZonedTimeOfDay Copied

Time of day with timezone information.

{
  "timeOfDay": {
    "hours": 9,
    "minutes": 0,
    "seconds": 0,
    "nanos": 0
  },
  "timezone": "UTC"
}

Command Lifecycle States Copied

COMMAND_LIFECYCLE_UNSPECIFIED - Default/unspecified state
COMMAND_LIFECYCLE_TRIGGERED - Command has been triggered but not yet claimed
COMMAND_LIFECYCLE_CLAIMED - Command has been claimed by a service
COMMAND_LIFECYCLE_RUNNING - Command is currently executing
COMMAND_LIFECYCLE_COMPLETED - Command completed successfully
COMMAND_LIFECYCLE_FAILED - Command failed to execute
COMMAND_LIFECYCLE_CANCELLED - Command was cancelled

Stream Operations Copied

STREAM_OPERATION_UNSPECIFIED - Default/unspecified operation
STREAM_OPERATION_APPEND - Append to existing stream content
STREAM_OPERATION_REPLACE - Replace existing stream content

Error Responses Copied

All endpoints may return error responses in the following format:

{
  "title": "Bad Request",
  "message": "The metric name must be set",
  "details": {
    "type": "validation_error",
    "path": ".metric.name"
  }
}

Common Error Status Codes Copied

400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists or conflict
500 Internal Server Error - Server error

Previous article Next article

Commands API

Command Registry Copied

Insert/Update Command Copied

Request Copied

Example Request Copied

Response Copied

Delete Command Copied

Request Copied

Example Request Copied

Response Copied

Query Commands Copied

Request Copied

Example Request Copied

Response Copied

Register Commands Copied

Request Copied

Example Request Copied

Response Copied

Get Command Service Copied

Request Copied

Example Request Copied

Response Copied

Command Execution Copied

Execute Command Copied

Request Copied

Example Request Copied

Response Copied

Clear Command Execution History Copied

Request Copied

Example Request Copied

Response Copied

Query Triggered Commands Copied

Request Copied

Example Request Copied

Response Copied

Update Command Status Copied

Request Copied

Example Request (Claim Command) Copied

Response Copied

Query Command Status Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to Command Status Updates Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to Triggered Commands Copied

Request Copied

Example Request Copied

Response Copied

Cancel Command Execution Copied

Request Copied

Example Request Copied

Response Copied

Clear Single Command Execution Entry Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to Command Output Copied

Request Copied

Example Request Copied

Response Copied

Extend Command Time-to-Live Copied

Request Copied

Example Request Copied

Response Copied

Configuration Copied

Get Configuration Copied

Request Copied

Example Request Copied

Response Copied

API Information Copied

Get API Versions Copied

Request Copied

Example Request Copied

Response Copied

Data Models Copied

Any Copied

ArgumentType Copied