Subscriptions

Subscriptions allow your application to receive automatic updates from Pico as events happen on the shop floor - without constantly polling the API.

Instead of repeatedly asking "did anything change?", you open a connection once and Pico pushes updates to you immediately when:

• A work order is completed (so you can update inventory in your ERP)
• An operation definition is created or modified (so you can sync your product catalog)
• A product structure changes (so you know what components are needed)

Think of it like subscribing to notifications - you tell Pico what events you care about, and it notifies you the moment they happen.

Available Subscriptions

operationsStream

Stream real-time updates for operations (products, subassemblies, and processes).

Use case: Monitor when operation definitions are created or updated in the system.

subscription {
  operationsStream {
    id
    externalId
    name
    updatedAt
  }
}

subOperationsStream

Stream updates for parent-child operation relationships.

Use case: Track changes to product/subassembly structures and their component operations.

subscription {
  subOperationsStream {
    parentId
    subId
    subGroup
    updatedAt
  }
}

operationOrderCompletesStream

Subscribe to work order completion events with full production details.

Use case: Capture completed work orders for ERP integration, including produced serials and consumed materials.

subscription {
  operationOrderCompletesStream {
    externalOrderId
    operation {
      id
      externalId
      name
    }
    operationSummary {
      startedAt
      cycleTime
      endState {
        producedSerial
        at
        station { name }
        operator { name }
      }
      consumedSerials {
        id
        partNo: externalId
        serial: value
      }
    }
  }
}

Filtering Subscriptions

All subscriptions support optional where clauses to filter events:

subscription {
  operationsStream(where: { id: { _eq: "prod-123" } }) {
    id
    name
  }
}

Filter for specific operations:

You can subscribe to completions of a specific operation by filtering on the operation ID:

subscription {
  operationOrderCompletesStream(where: {
    operation: { id: { _eq: "operation-123" } }
  }) {
    externalOrderId
    operation {
      id
      externalId
      name
    }
    operationSummary {
      endState {
        producedSerial
        at
      }
    }
  }
}

Connection Protocol

How Subscriptions Work

Subscriptions use the WebSocket protocol to maintain a persistent, bidirectional connection between your application and the Pico API:

1. Initial Connection: Your client establishes a WebSocket connection to the GraphQL endpoint (typically wss:// for secure connections)
2. Subscribe: Send your subscription query through the WebSocket connection
3. Listen: The connection stays open and the server pushes updates to you in real-time as events occur
4. Automatic Updates: When a work order completes or an operation changes, the server immediately sends the data through the existing connection
5. Close: The connection remains open until you explicitly unsubscribe or disconnect

Client Requirements

Your GraphQL client must support WebSocket-based subscriptions. Compatible clients include:

• Apollo Client (with @apollo/client/link/ws)
• urql (with @urql/exchange-graphql-ws)
• graphql-ws (standalone library)
• Relay (with subscription support)

Connection URL

WebSocket connections typically use:

• ws://your-pico-api:port/graphql for development
• wss://your-pico-api/graphql for production (secure WebSocket)

Consult your Pico administrator for the exact WebSocket endpoint URL.