Skip to content

Waypoints

A Waypoint is a saved state or configuration of a Jet that you can return to later—e.g. a backup or snapshot. Each waypoint is based on a waypoint template (defined on the Jet Template in the Waypoints tab) and belongs to one Jet. Waypoints save and restore variable values and can store metadata; the template can define up to four Flight Plans: Create (prepare), Arrive, Leave, and Delete.

Access Rules

Group Action Condition
Manager R Waypoint access level is "Manager" or less and user is in "Users" or "Managers" on the Jet
Manager CRU Waypoint access level is "Manager" or less and user is in "Managers" on the Jet's Jet Template
Manager D Same as CRU and the waypoint was created by the user
Root CRUD Any record

Info

CRUD stands for Create, Read, Update, Delete.

Waypoint Configuration

Waypoints are created and managed from a Jet form, Waypoints tab (Cetmix Tower > Jets > Jets → open a Jet → Waypoints). They can also be opened from the Waypoints action or search.

Jet Waypoint Form

General Settings

Field Description
Name Waypoint name (e.g. "Snapshot before update").
Type Waypoint template this waypoint is based on. Defines Create/Arrive/Leave/Delete Flight Plans. Chosen from templates of the Jet's Jet Template.
Reference Used for automation and YAML export/import. Generated automatically if not provided. Shown only when set.
State Current state of the waypoint. See Waypoint States below.
Access Level Minimum access to this waypoint: "Manager" or "Root". Set from the waypoint template.

Important

The waypoint type (template) can only be changed when the waypoint is in the "draft" state. Once the waypoint has been prepared or used, its type cannot be modified.

Waypoint States

Waypoints progress through different states during their lifecycle:

State Description
Draft Initial state when waypoint is created. Can be modified or deleted freely.
Preparing Waypoint is being prepared. The "Create Flight Plan" from the template is being executed.
Ready Waypoint is ready and can be flown to. All preparation steps completed successfully.
Error An error occurred during preparation, arrival, or leaving. The waypoint cannot be used until fixed.
Arriving Jet is currently arriving at this waypoint. The "Arrive Flight Plan" is being executed.
Leaving Jet is currently leaving this waypoint. The "Leave Flight Plan" is being executed.
Current This is the current waypoint where the jet is located. Only one waypoint per jet can be in this state.
Deleting Waypoint is being deleted. The "Delete Flight Plan" from the template is being executed.
Deleted Waypoint has been deleted.

Variable Values

Developer Mode

This field is visible only in developer mode.

Waypoints save and restore variable values: when leaving a waypoint, jet-specific values are saved to it; when arriving, they are restored to the Jet. Only jet-level values are stored (not template/server/global), so each waypoint can represent a different configuration state.

Metadata

Developer Mode

The Metadata field is visible only in developer mode.

Waypoints can store metadata—a JSON object describing the Jet's state or context (paths, versions, file lists, etc.). It is shown in the form (developer mode). Servers and Jets also have a metadata field; waypoint metadata is the one exposed in variables as tower.jet.waypoint.<key> and in flight-plan custom variables __waypoint_<key>. When a waypoint is prepared or arrived at, the Flight Plan can save metadata with waypoint.write({"metadata": {...}}) or waypoint.update_metadata({...}); when restoring, the plan can read it from waypoint.metadata.

In flight plans, use custom variables: __waypoint_<metadata_key> (e.g. metadata {"environment": "production"} → __waypoint_environment).

Saving and restoring metadata in Python commands

In Python code commands inside your Flight Plans, you can write metadata when preparing or leaving a waypoint, and read it when arriving. When the plan runs in waypoint context, the Python command context provides waypoint (the current waypoint record), along with server, jet, jet_template, env, and custom_values (see Command). Use the waypoint variable directly.

Save metadata (e.g. in Create or Leave Flight Plan). Use waypoint.update_metadata(metadata) to merge new keys into existing metadata (preserves existing data); or waypoint.write({"metadata": {...}}) to replace the whole metadata dict:

# Merge into existing metadata (recommended when adding or updating keys)
waypoint.update_metadata({
    "db_version": "15.0",
    "backup_files": ["/data/db.sql", "/data/media.tar.gz"],
    "custom_note": "Before major upgrade"
})

Restore / use metadata (e.g. in Arrive Flight Plan):

version = waypoint.metadata.get("db_version")
backup_files = waypoint.metadata.get("backup_files", [])

Custom Variables

When executing flight plans, waypoints provide the following custom variables:

Variable Description
__waypoint Waypoint reference
__waypoint_type Waypoint template reference
__waypoint_state Current waypoint state
__waypoint_<key> Waypoint metadata values (if metadata exists)

These variables are automatically available in all flight plans executed for the waypoint (create, arrive, leave, delete).

Waypoint Lifecycle

Creating a Waypoint

To create a new waypoint:

  1. Add a new waypoint on the "Waypoints" tab of a Jet
  2. Waypoint is created in "draft" state
  3. Reference is automatically generated if not provided
  4. Access level is set from the waypoint template, adjust it if needed
  5. Click the "Prepare" button on the waypoint

When a waypoint is prepared (moved from "draft" to "preparing"):

  1. If the waypoint template has a "Create Flight Plan", it is executed
  2. The waypoint state changes to "preparing" while the plan runs
  3. Upon successful completion, the waypoint state changes to "ready"
  4. If no "Create Flight Plan" is configured, the waypoint immediately becomes "ready"

Prepare button on a draft waypoint

Activating a Waypoint

To activate a waypoint:

Fly here button on a ready waypoint

  1. Click the "Fly here" button on the waypoint
  2. The waypoint state changes to "arriving"
  3. If there is a current waypoint, it is left first (state changes to "leaving")
  4. The current waypoint's variable values are saved
  5. If the current waypoint has a "Leave Flight Plan", it is executed
  6. Once leaving is complete, the new waypoint's "Arrive Flight Plan" is executed (if configured)
  7. Variable values are restored from the new waypoint
  8. The new waypoint becomes the current waypoint (state: "current")
  9. The previous waypoint state changes to "ready"

Deleting a Waypoint

To delete a waypoint click the "Delete" button on the waypoint.

When deleting a waypoint:

  • Draft state: Waypoint can be deleted immediately
  • Ready/Error state:
  • If the waypoint template has a "Delete Flight Plan", it is executed first (state: "deleting")
  • Upon completion, the waypoint is deleted
  • If no "Delete Flight Plan" is configured, the waypoint is deleted immediately
  • Other states: Waypoint cannot be deleted (except "deleting" and "deleted" states)

Important

The current waypoint cannot be deleted. You must first fly to another waypoint before deleting it.

Waypoint form in error state (e.g. when in Ready/Error state for deletion)

Error Handling

If a flight plan fails during waypoint operations:

  • During preparation: Waypoint state changes to "error"
  • During arrival:
  • Variable values are restored from the previous current waypoint
  • Previous waypoint state is set back to "current"
  • New waypoint state changes to "error"
  • During leaving: Waypoint state changes to "error"
  • During deletion: Waypoint remains in "deleting" state

Waypoints in "error" state cannot be used until the issue is resolved and the waypoint is reset or re-prepared.