/  Yamcs HTTP API  /  Management  /  Get Instance

Get InstanceΒΆ

Get an instance

If an instance does not have web services enabled, it will be listed among the results, but none of its URLs will be filled in.

URI Template

GET /api/instances/{instance}
{instance}

Yamcs instance name.

Response Type

interface YamcsInstance {

  // Instance name.
  name: string;
  missionDatabase: MissionDatabase;
  processors: ProcessorInfo[];
  state: InstanceState;

  //in case the state=FAILED, this field will indicate the cause of the failure
  // the missionDatabase and other fields may not be filled when this happens
  failureCause: string;
  missionTime: string;  // RFC 3339 timestamp

  // Labels assigned to this instance. Each entry is keyed by the tag name
  // of the label. The value represent the label value for that tag.
  labels: {[key: string]: string};

  // Feature capability hints for client use
  capabilities: string[];

  // Name of the template, if this instance was generated
  template: string;

  // Arguments used during template processing, if this instance
  // was generated
  templateArgs: {[key: string]: string};

  // Whether the template is stil available
  templateAvailable: boolean;

  // Whether the template has changed since this instance was
  // generated
  templateChanged: boolean;
}

Related Types

interface MissionDatabase {

  // This is the config section in mdb.yaml
  configName: string;

  // Root space-system name
  name: string;

  // Root space-system header version
  version: string;
  spaceSystem: SpaceSystemInfo[];
  parameterCount: number;
  containerCount: number;
  commandCount: number;
  algorithmCount: number;
  parameterTypeCount: number;
}

interface SpaceSystemInfo {
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  version: string;
  history: HistoryInfo[];
  sub: SpaceSystemInfo[];
  ancillaryData: {[key: string]: AncillaryDataInfo};
}

// Used by external clients to identify an item in the Mission Database
// If namespace is set, then the name is that of an alias, rather than
// the qualified name.
interface NamedObjectId {
  name: string;
  namespace: string;
}

interface HistoryInfo {
  version: string;
  date: string;
  message: string;
  author: string;
}

interface ProcessorInfo {

  // Yamcs instance name.
  instance: string;

  // Processor name.
  name: string;
  type: string;
  spec: string;
  creator: string;
  hasAlarms: boolean;
  hasCommanding: boolean;
  state: ServiceState;
  replayRequest: ReplayRequest;
  replayState: ReplayState;
  services: ServiceInfo[];
  persistent: boolean;
  time: string;  // RFC 3339 timestamp
  replay: boolean;
  checkCommandClearance: boolean;

  // If true, this processor can not be deleted.
  protected: boolean;

  // Globally available acknowledgments (in addition to Acknowledge_Queued,
  // Acknowledge_Released and Acknowledge_Sent)
  acknowledgments: AcknowledgmentInfo[];
}

//used to replay (concurrently) TM packets, parameters and events
interface ReplayRequest {

  // **Required.** The time at which the replay should start.
  start: string;  // RFC 3339 timestamp

  // The time at which the replay should stop.
  // If unspecified, the replay will keep going as long  as there is remaining data.
  stop: string;  // RFC 3339 timestamp

  //what should happen at the end of the replay
  endAction: EndAction;

  //how fast the replay should go
  speed: ReplaySpeed;

  // Reverse the direction of the replay
  reverse: boolean;
  parameterRequest: ParameterReplayRequest;

  // By default all Packets, Events, CommandHistory are part of the replay
  // Unless one or more of the below requests are specified.
  packetRequest: PacketReplayRequest;
  eventRequest: EventReplayRequest;
  commandHistoryRequest: CommandHistoryReplayRequest;
  ppRequest: PpReplayRequest;

  // Start the replay following initialization
  // Defaults to true, if unspecified
  autostart: boolean;
}

interface ReplaySpeed {
  type: ReplaySpeedType;
  param: number;
}

interface ParameterReplayRequest {
  nameFilter: NamedObjectId[];
  sendRaw: boolean;
  performMonitoring: boolean;
}

interface PacketReplayRequest {

  // No filter, means all packets for which privileges exist, are sent
  nameFilter: NamedObjectId[];

  //if specified, only replay packets originally received on one of those links
  tmLinks: string[];
}

interface EventReplayRequest {
}

interface CommandHistoryReplayRequest {

  // No filter, means all command history entries are sent
  nameFilter: NamedObjectId[];
}

//Request to replay parameters - they can be filtered by the parameter group
interface PpReplayRequest {

  // No filter, means all pp groups are sent
  groupNameFilter: string[];

  // exclude the parameters from these groups
  //   this takes precedence over the filter above (i.e. if a group is part of both, it will be excluded)
  groupNameExclude: string[];
}

interface ServiceInfo {

  // Yamcs instance name
  instance: string;

  // Service name
  name: string;

  // Service state
  state: ServiceState;

  // Java class name
  className: string;

  // Processor name (in case this is a processor service)
  processor: string;

  // Short failure message when `state` is FAILED.
  failureMessage: string;

  // Stacktrace when `state` is FAILED.
  failureCause: string;
}

interface AcknowledgmentInfo {

  // Acknowledgment name
  name: string;

  // Description of the acknowledgment
  description: string;
}

enum ServiceState {

  // A service in this state is inactive. It does minimal work and
  // consumes minimal resources.
  NEW = "NEW",

  // A service in this state is transitioning to ``RUNNING``.
  STARTING = "STARTING",

  // A service in this state is operational.
  RUNNING = "RUNNING",

  // A service in this state is transitioning to ``TERMINATED``.
  STOPPING = "STOPPING",

  // A service in this state has completed execution normally.
  // It does minimal work and consumes minimal resources.
  TERMINATED = "TERMINATED",

  // A service in this state has encountered a problem and may
  // not be operational. It cannot be started nor stopped.
  FAILED = "FAILED",
}

enum EndAction {
  LOOP = "LOOP",
  QUIT = "QUIT",
  STOP = "STOP",
}

enum ReplaySpeedType {
  AFAP = "AFAP",
  FIXED_DELAY = "FIXED_DELAY",
  REALTIME = "REALTIME",
  STEP_BY_STEP = "STEP_BY_STEP",
}

enum ReplayState {

  // just at the beginning or when the replay request (start, stop or packet selection) changes
  INITIALIZATION = "INITIALIZATION",
  RUNNING = "RUNNING",

  // The replay has reached the end with the endaction stop
  STOPPED = "STOPPED",

  // The replay stopped due to an error.
  ERROR = "ERROR",
  PAUSED = "PAUSED",

  // The replay is finished and closed
  CLOSED = "CLOSED",
}

enum ServiceState {

  // A service in this state is inactive. It does minimal work and
  // consumes minimal resources.
  NEW = "NEW",

  // A service in this state is transitioning to ``RUNNING``.
  STARTING = "STARTING",

  // A service in this state is operational.
  RUNNING = "RUNNING",

  // A service in this state is transitioning to ``TERMINATED``.
  STOPPING = "STOPPING",

  // A service in this state has completed execution normally.
  // It does minimal work and consumes minimal resources.
  TERMINATED = "TERMINATED",

  // A service in this state has encountered a problem and may
  // not be operational. It cannot be started nor stopped.
  FAILED = "FAILED",
}

enum InstanceState {
  OFFLINE = "OFFLINE",
  INITIALIZING = "INITIALIZING",
  INITIALIZED = "INITIALIZED",
  STARTING = "STARTING",
  RUNNING = "RUNNING",
  STOPPING = "STOPPING",
  FAILED = "FAILED",
}