Routes

Routes are active workflows that track work moving through your system. While stations define what can happen, routes define what is happening for a specific instance of work.

What is a Route?

A route represents an active journey through a series of stops. It has a status, tracks which stops have been completed, and maintains a log of all actions taken.

type Route {
  id: ID!
  tenantId: ID
  name: String
  description: String
  status: RouteStatus
  stops: [Stop]
  track: AWSJSON
  actionLog: [StopActionRecord]
  totalStops: Int
}

Route Status

Routes can be in one of four states:

Status	Description
active	Route is in progress, stops can be completed
paused	Route is temporarily halted
completed	All stops have been finished
cancelled	Route was terminated (irreversible)

Creating Routes

Routes are created using instructions that define how stops should be arranged:

mutation CreateRoute {
  addRoute(input: {
    name: "Customer Onboarding - Acme Corp"
    instructions: [
      {
        trackType: stop
        action: startWith
        actionStationOrRouteTemplateId: "welcome-station-id"
      },
      {
        trackType: stop
        action: addAfter
        actionStationOrRouteTemplateId: "setup-station-id"
        actionTargetStopId: "previous-stop-id"
      },
      {
        trackType: stop
        action: addAfter
        actionStationOrRouteTemplateId: "training-station-id"
        actionTargetStopId: "previous-stop-id"
      }
    ]
  }) {
    id
    name
    status
    stops {
      id
      name
      status
    }
  }
}

Instruction Actions

Action	Description
startWith	Creates the first stop in the route
addAfter	Adds a stop after the target stop
addBefore	Adds a stop before the target stop
addAsFirstChild	Adds as first child (for parallel routes)
addAsLastChild	Adds as last child (for parallel routes)
replace	Replaces an existing stop
remove	Removes a stop from the route

Track Types

Type	Description
stop	A regular station stop
routeTemplate	Insert an entire route template
route	Reference another route

Managing Route Status

Pause a Route

Temporarily halt progress on a route:

mutation PauseRoute {
  pauseRoute(id: "route-123") {
    id
    status
  }
}

Resume a Route

Continue a paused route:

mutation ResumeRoute {
  resumeRoute(id: "route-123") {
    id
    status
  }
}

Cancel a Route

Danger

Cancelling a route is irreversible. The route will be permanently marked as cancelled.

mutation CancelRoute {
  cancelRoute(id: "route-123") {
    id
    status
  }
}

Working with Stops

Mark Stop as Completed

mutation CompleteStop {
  markStopCompleted(
    routeId: "route-123"
    stopId: "stop-456"
  ) {
    id
    stops {
      id
      status
    }
  }
}

Unmark Stop (Revert Completion)

mutation UnmarkStop {
  unMarkStopCompleted(
    routeId: "route-123"
    stopId: "stop-456"
  ) {
    id
    stops {
      id
      status
    }
  }
}

Querying Routes

List All Routes

query ListRoutes {
  listRoutes {
    id
    name
    status
    totalStops
    stops {
      id
      name
      status
    }
  }
}

Get Route Details

query GetRouteDetails {
  getRoute(id: "route-123") {
    id
    name
    status
    track
    stops {
      id
      name
      status
      station {
        id
        description
      }
    }
    actionLog {
      action
      timestamp
      userId
      stopId
      stopName
    }
  }
}

Updating Routes

Update Route Name

mutation UpdateRouteName {
  updateRouteName(
    id: "route-123"
    name: "Customer Onboarding - Acme Corp (Priority)"
  ) {
    id
    name
  }
}

Update Route Structure

Modify the route by adding, removing, or rearranging stops:

mutation UpdateRoute {
  updateRoute(
    id: "route-123"
    input: {
      name: "Updated Workflow"
      instructions: [
        {
          trackType: stop
          action: addAfter
          actionStationOrRouteTemplateId: "new-station-id"
          actionTargetStopId: "existing-stop-id"
        }
      ]
    }
  ) {
    id
    stops {
      id
      name
    }
  }
}

Deleting Routes

mutation DeleteRoute {
  deleteRoute(id: "route-123") {
    id
  }
}

Real-time Subscriptions

Route Added

subscription OnRouteAdded {
  routeAdded(tenantId: "your-tenant-id") {
    id
    name
    status
  }
}

Route Updated

subscription OnRouteUpdated {
  routeUpdated(tenantId: "your-tenant-id") {
    id
    name
    status
    stops {
      id
      status
    }
  }
}

Route Deleted

subscription OnRouteDeleted {
  routeDeleted(tenantId: "your-tenant-id") {
    id
  }
}

Action Log

Every route maintains an action log that records all significant events:

type StopActionRecord {
  action: String      # What happened
  timestamp: AWSDateTime
  userId: String      # Who did it
  stopId: String      # Which stop
  stopName: String    # Stop name for display
}

Query the action log to see the history of a route:

query GetRouteHistory {
  getRoute(id: "route-123") {
    actionLog {
      action
      timestamp
      userId
      stopName
    }
  }
}

Parallel Execution

Routes support parallel (asynchronous) stops using the enableAsynchronousChildren flag:

mutation CreateParallelRoute {
  addRoute(input: {
    name: "Parallel Review Process"
    instructions: [
      {
        trackType: stop
        action: startWith
        actionStationOrRouteTemplateId: "start-station"
        enableAsynchronousChildren: true
      },
      {
        trackType: stop
        action: addAsFirstChild
        actionStationOrRouteTemplateId: "review-a-station"
        actionTargetStopId: "start-stop-id"
      },
      {
        trackType: stop
        action: addAsLastChild
        actionStationOrRouteTemplateId: "review-b-station"
        actionTargetStopId: "start-stop-id"
      }
    ]
  }) {
    id
    track
  }
}

This creates a route where “Review A” and “Review B” can be completed in any order or simultaneously.