Data model - ION Manual

Overview

When you integrate against ION, eight or nine entities cover about 95% of what you touch. Each entity below shows what it represents, how it connects to the others, and what it maps to in adjacent systems such as ERP, MES, PLM, and QMS. The full schema lives in schema.graphql and the API Playground.

Entity map

The core entities connect through these relationships:

• tags
• instances of
• template for
• PartSubtype (categorization, many-to-many)
• Part (library item, design intent)
• PartInventory (stockable or serialized unit)
• Procedure (template)
• PurchaseOrder line items
• Run (execution)
• RunBatch (batched runs)
• RunStep
• BuildRequirement (aBOM line item)
• Issue (quality event)

Parts

A Part is the library entry. It holds a part number, description, revision, and the design intent. A Part is not the physical thing on the shelf. That physical thing is a PartInventory.

Query a part:

query GetPart {
  part(id: "42") {
    id
    partNumber
    description
    revision
    partType
    trackingType
    status
    partSubtypes { id name }
  }
}

Maps to: “SKU” or “Item Master” in ERP. “PartNumber” in PLM.

PartSubtype

A PartSubtype is a categorization tag attached to a Part. Subtypes group parts that share routing, inspection, or planning behavior. Examples include “Mounting hardware”, “Critical-to-quality fasteners”, and “Long-lead-time stock”. A part can have multiple subtypes. Query the subtypes:

query Subtypes {
  partSubtypes(first: 50) {
    edges {
      node {
        id
        name
        description
      }
    }
  }
}

Maps to: “Item Family”, “Commodity Code”, or “Product Line” in ERP. Don’t confuse a subtype with revision lineage. Revision lineage is revisedFromId on Part.

PartInventory

A PartInventory is a physical instance of a Part. It can be a serialized unit, a lot, or a quantity at a location. This is the entity that gets installed onto assemblies, consumed in runs, or shipped.

Query a part inventory record:

query Inventory {
  partInventory(id: "9876") {
    id
    serialNumber
    lotNumber
    quantity
    status
    part { id partNumber description }
    location { id name }
    madeOnAssemblyParentPartInventory { id serialNumber }
  }
}

Maps to: “Serial” or “Lot” in MES. “Inventory unit” or “Stockable item” in WMS. “Asset” in PLM.

Assemblies (as-built BOM)

An as-built BOM is the parent and child tree of PartInventory units that compose a finished assembly. ION represents this tree two ways. The madeOnAssemblyParentPartInventory reference on each PartInventory points up the tree. The BuildRequirement records define which parts to install where to complete the assembly. To traverse the tree downward:

query AbomTree {
  partInventory(id: "9876") {
    id
    serialNumber
    part { partNumber }
    buildRequirements {
      id
      part { partNumber }
      quantity
      abomInstallations {
        id
        partInventory {
          id
          serialNumber
          part { partNumber }
        }
      }
    }
  }
}

To walk up the tree, follow madeOnAssemblyParentPartInventory recursively. Maps to: “Bill of Materials” in ERP. “Assembly tree” in PLM. “Bill of Build” in MES.

The mBOM (manufacturing BOM) is the planned structure. The aBOM (as-built) is what was actually installed at run time. Both have GraphQL types in ION.

Procedures and run steps

A Procedure is the manufacturing routing template. It defines what should happen on the floor. A Procedure is composed of steps. Query a procedure with its steps:

query Proc {
  procedure(id: "12") {
    id
    title
    version
    steps {
      id
      title
      position
      type
      fields {
        id
        name
        type
      }
    }
  }
}

Maps to: “Routing” in ERP. “Recipe” or “Standard Operating Procedure” in MES. “Work Instruction” in QMS.

Runs and run steps

A Run is one execution of a Procedure against a specific PartInventory. Run steps are the per-execution instances of the procedure’s steps. A run step is where operators record measurements, sign off, and report quality issues.

Query a run with its steps:

query GetRun {
  run(id: "1234") {
    id
    title
    status
    procedure { id title version }
    partInventory { id serialNumber part { partNumber } }
    steps {
      id
      position
      status
      endTime
      fields { id name value }
    }
  }
}

Maps to: “Work Order” in ERP. “Production Order” in MES. “Build” or “Job” colloquially.

Build requirements

A BuildRequirement is a line item on an aBOM. It defines how many of a given part to install to complete the assembly. Operators install against build requirements during a run. Each install is a row of abomInstallations (an ABomInstallation) that links the PartInventory consumed to the build requirement satisfied. For the user-facing flow, see Editing build requirements.

Issues

An Issue is a quality event. It can be a nonconformance, deviation, supplier problem, or observation. Issues attach to runs, run steps, or part inventories. Issues follow a defined lifecycle. The states are Pending, In Progress, In Review, and Resolved. Disposition types determine what happens to the affected inventory. Query open issues by disposition:

query OpenIssues {
  issues(filters: { status: { eq: IN_PROGRESS } }) {
    edges {
      node {
        id
        title
        status
        issueDispositionType { id title }
        assignedTo { id name }
        runStep { id }
      }
    }
  }
}

For more information, see Issue states, dispositions, and resolutions. Maps to: “Nonconformance Report” (NCR) in QMS. “CAPA” precursor in QMS. “Defect” in PLM. “Incident” in ServiceNow-style systems.

Purchase orders

For supply chain integrations:

query OpenPOs {
  purchaseOrders(filters: { isOpen: { eq: true } }) {
    edges {
      node {
        id
        prettyStr
        status
        supplier { id name }
        purchaseOrderLines {
          id
          part { partNumber }
          quantity
          receivedQuantity
        }
      }
    }
  }
}

Maps to: “PO” in ERP. Receiving against a PO updates PartInventory records.

File attachments

Files attach to entities polymorphically through the entity ID. For the upload flow and the entity { id } lookup pattern, see File upload.

The entity polymorphic ID

ION gives every attachable object a uniform ID through an entities reference. Most major entities expose an entity { id } field. This field is the target for several features:

• File attachments
• Subscriptions (notifications)
• Comments
• Cross-entity links, such as an issue to a run step

Don’t confuse this field with the entity’s own id. When an integration calls for an entityId, fetch the parent’s entity.id first.

Field-mapping cheat sheet

When you bridge from another system, use this rough translation:

Etag-based concurrency

Every mutable entity returns an _etag on read. Pass it back on update and delete mutations. ION rejects writes whose etag doesn’t match the current value. A mismatch returns a 409. For more information, see Error codes 409. When you integrate, read then write inside a short window. Propagate the etag through your service.

Discovering the rest of the schema

You can find anything not on this page three ways:

1. API Playground: an interactive schema explorer at /api-reference/playground.
2. schema.graphql: committed to this repository and kept in sync with the production schema.
3. __schema introspection: programmatic access.