Save Item¶

interface SaveItemRequest {

  // Item source
  source: string;

  // Optional item identifier.
  //
  // If not set, an ID will be assigned by the server.
  //
  // If set, it should be a valid UUID.
  id: string;

  // Item name
  name: string;

  // Item type
  type: TimelineItemType;

  // Item start. The fields `start`, `relativeTime` and `dependsOn`
  // are mutually exclusive
  start: string;  // RFC 3339 timestamp

  // Item duration. Applies also if `relativeTime` is specified
  duration: string; // Duration in seconds. Example: "3s" or "3.001s"

  // Tags
  tags: string[];

  // If this item is part of a group, this is the group identifier
  groupId: string;

  // If the item time specification is relative to another item,
  // `relativeTime` contains a reference to that item, as well
  // as the relative start (the duration is the same as given by the
  // `duration` field).
  relativeTime: RelativeTime;

  // Item description
  description: string;

  // Additional properties used by the Yamcs Web UI for rendering purposes.
  properties: {[key: string]: string};

  // Mission-specific custom data. Unlike `properties`, this field is ignored
  // by the Yamcs Web UI.
  extra: {[key: string]: string};

  // Activity definition associated to this item.
  //
  // Required if `type` is ACTIVITY.
  activityDefinition: ActivityDefinitionInfo;

  // Can be used only if `type` is ACTIVITY.
  //
  // Specifies which other activities/items this activity depends on.
  //
  // Start time of this activity is derived by looking at each predecessor's
  // start condition and among them establishing the latest start time.
  predecessors: PredecessorInfo[];

  // Can be used only if `type` is ACTIVITY
  //
  // Indicates if the activity should start automatically.
  //
  // When `false`, the activity will be moved to `READY` state waiting to be
  // started manually.
  //
  // Defaults to `false` for manual activities, and `true` otherwise.
  autoStart: boolean;
}

interface TimelineItem {

  // Item identifier.
  //
  // The identifier is assigned by the source that created the item.
  //
  // It is possible but unlikely for two items coming from two different
  // sources to have the same identifier.
  //
  // - The "rdb" source sets the id to a UUID.
  // ` The "commands" source sets the id to the command id
  id: string;

  // Human-readable name of this item
  name: string;
  type: TimelineItemType;

  // Absolute start time of the item (computed by the server when
  // `relativeTime` is used).
  start: string;  // RFC 3339 timestamp
  duration: string; // Duration in seconds. Example: "3s" or "3.001s"
  tags: string[];

  // If this item belongs to a group, this is the group identifier
  groupId: string;

  // If this item time specification is relative to another item, `relativeTime`
  // contains a reference to that item as well as the relative start (the duration
  // is the same as the `duration` field).
  //
  // Note that start of the item is computed by the server based on the
  // `relativeTime` before sending the item to the client.
  relativeTime: RelativeTime;

  // Detailed description of the item
  description: string;

  // Additional properties used by the Yamcs Web UI for rendering purposes.
  properties: {[key: string]: string};

  // Mission-specific custom data. Unlike `properties`, this field is ignored
  // by the Yamcs Web UI.
  extra: {[key: string]: string};

  // For activities: execution status
  status: ExecutionStatus;

  // For activities: if the status is FAILED or ABORTED, this may indicate the reason
  // some information may also be available in the item log
  failureReason: string;

  // Activity definition associated to this item.
  // Only set when `type` equals ACTIVITY.
  activityDefinition: ActivityDefinitionInfo;

  // Identifiers of activity runs matching this item.
  // Only set when `type` equals ACTIVITY.
  runs: string[];

  // Activity runs for this item
  // Only set when `type` equals ACTIVITY.
  activityRuns: ActivityInfo[];

  // Dependencies on other activities/events.
  //
  // Only applicable when `type` equals ACTIVITY.
  //
  // Start time of this activity is derived by looking at each predecessor's
  // start condition and among them establishing the latest start time.
  predecessors: PredecessorInfo[];

  // Indicates if the activity should start automatically. If false,
  // the activity goes into READY state and must be started manually.
  //
  // Only applicable when `type` equals ACTIVITY.
  autoStart: boolean;
}

interface RelativeTime {

  // Identifier of the item that this time is relative to.
  relto: string;
  relativeStart: string; // Duration in seconds. Example: "3s" or "3.001s"
}

interface ActivityDefinitionInfo {

  // Activity type.
  // Common types: MANUAL, SCRIPT, COMMAND, STACK
  type: string;

  // Activity arguments. The expected arguments
  // are different for each activity type
  args: {[key: string]: any};

  // Optional label.
  //
  // Keep short. Used in Yamcs Timeline charts.
  label: string;

  // Human-readable description of the essence of this activity.
  // For example, for a script this would be the name of the script.
  //
  // This is an output field only.
  description: string;
}

interface PredecessorInfo {

  // Item identifier of the predecessor
  itemId: string;

  // What is the predecessor's state before the successor
  // can be started.
  //
  // If not specified, ON_COMPLETION will be used
  startCondition: StartCondition;

  // Name of the predecessor item
  //
  // This is an output field only
  name: string;
}

interface ActivityInfo {

  // Activity identifier
  id: string;

  // Start time of the activity
  start: string;  // RFC 3339 timestamp

  // Differentiator in case of multiple activities
  // with the same start time
  seq: number;

  // Activity status
  status: ActivityStatus;

  // User who started the run
  startedBy: string;

  // Activity type
  type: string;

  // Activity arguments
  args: {[key: string]: any};

  // Label for display in Yamcs Timeline charts
  label: string;

  // Activity detail (short descriptive)
  detail: string;

  // Stop time of the activity run
  stop: string;  // RFC 3339 timestamp

  // User who stopped the run. Only set if the activity
  // was manually stopped
  stoppedBy: string;

  // If set, the activity is stopped, but failed
  failureReason: string;
}

enum TimelineItemType {

  // Events are things that will happen at a specific time.
  EVENT = "EVENT",

  // Unlike events, activities have an execution status
  ACTIVITY = "ACTIVITY",

  // A grouping of other items (events and/or activities)
  ITEM_GROUP = "ITEM_GROUP",

  // A grouping of activities. The group is itself an activity
  ACTIVITY_GROUP = "ACTIVITY_GROUP",
}

enum StartCondition {

  // Start this activity regardless of the outcome of the predecessor.
  // This can be used to make activities depend on other non-activity items
  ON_COMPLETION = "ON_COMPLETION",

  // Start this activity only if the predecessor completes successfully.
  ON_SUCCESS = "ON_SUCCESS",

  // Start this activity only if the predecessor fails.
  ON_FAILURE = "ON_FAILURE",

  // Start this activity as soon as its predecessor has started
  ON_START = "ON_START",
}

enum ExecutionStatus {

  // The activity is planned for future execution. Not yet eligible to start.
  PLANNED = "PLANNED",

  // The activity is waiting to be started manually by an operator.
  // This is typically the case for activities with autoStart = false.
  READY = "READY",

  // The activity will be able to start once its dependencies have completed.
  WAITING_ON_DEPENDENCY = "WAITING_ON_DEPENDENCY",

  // The activity is currently running
  IN_PROGRESS = "IN_PROGRESS",

  // The activity has completed successfully
  SUCCEEDED = "SUCCEEDED",

  // The activity started but was manually aborted by the operator.
  ABORTED = "ABORTED",

  // The activity has completed with failure.
  FAILED = "FAILED",

  // The activity was skipped because a dependency was not met.
  SKIPPED = "SKIPPED",

  // The activity was canceled before starting, typically by operator action.
  CANCELED = "CANCELED",

  // The activity was paused explicitly by the operator.
  PAUSED = "PAUSED",

  // The activity is paused during execution, waiting for user input or intervention.
  // Once input is received, execution may continue automatically.
  WAITING_FOR_INPUT = "WAITING_FOR_INPUT",
}

enum ActivityStatus {

  // An activity is runing
  RUNNING = "RUNNING",

  // The activity was cancelled. It may or may not still be running
  // (verify stop time).
  CANCELLED = "CANCELLED",

  // The activity completed successfully
  SUCCESSFUL = "SUCCESSFUL",

  // An error occurred while running this activity
  FAILED = "FAILED",
}