Start Activity¶

Start an activity

The request body allows for the execution of arbitrary activities.

The following activity types are included in the core Yamcs module:

• COMMAND: Execute a single command

  Args:

  • command (string): Required. Qualified name of a command

  • args (map): Named arguments, if the command requires any

  • extra (map): Extra command options

  • processor (string): Processor name. If not provided, Yamcs defaults to any processor it can find with commanding enabled.

  Example:

  {
    "type": "COMMAND",
    "args": {
      "command": "/YSS/SIMULATOR/SWITCH_VOLTAGE_ON",
      "args": {
        "voltage_num": 3
      },
      "processor": "realtime"
    }
  }
  

• STACK: Execute a stack

  Args:

  • bucket (string): Required. The name of the bucket containg the stack

  • stack (string): Required. The name of the stack object inside the bucket

  • processor (string): Processor name. If not provided, Yamcs defaults to any processor it can find with commanding enabled.

  Example:

  {
    "type": "STACK",
    "args": {
      "bucket": "mybucket",
      "stack": "mystack.ycs",
      "processor": "realtime"
    }
  }
  

• SCRIPT: Run a script

  Args:

  • script (string): Required. Script identifier. This should be the relative path to an executable file in one of the search locations. When unconfigured, the default search location is etc/scripts/ relative to the Yamcs working directory.

  • args (string or string[]): Script arguments

  • processor (string): If provided, this information is passed to the script in an environment variable YAMCS_PROCESSOR.

  • runner (string): In case of multiple script runners, you can provide this field, to indicate which runner this script execution applies to.

  Example:

  {
    "type": "SCRIPT",
    "args": {
      "script": "simulate_los.py",
      "args": "--duration 60",
      "processor": "realtime"
    }
  }
  

URI Template

POST /api/activities/{instance}/activities

{instance}

Yamcs instance name

Request Body

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;
}

Response Type

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;
}

Related Types

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",
}