CoCore GraphQL API Overview

Introduction for JDF Developers

Welcome to the CoCore GraphQL API documentation. If you're familiar with JDF (Job Definition Format), you'll find many familiar concepts here, reimagined for a modern, real-time print management system. This guide will help you understand how CoCore's API maps to the print production concepts you already know.

From JDF to GraphQL: A Conceptual Bridge

Why GraphQL?

While JDF uses XML to describe print jobs and their resources, CoCore uses GraphQL to provide:

• Flexible Queries: Request exactly the data you need, nothing more
• Real-time Updates: Subscribe to job state changes and production events
• Type Safety: Strongly typed schema with built-in documentation
• Single Endpoint: One API endpoint for all operations
• Efficient Data Loading: Resolve complex relationships in a single request

Core Concept Mapping

JDF Concept	CoCore Equivalent	Notes
JDF Job Ticket	Job type	Central job definition with metadata
Intent Resources	JobProduct	Customer requirements and specifications
Component Resources	Component	Physical print components (content, cover, insert)
Media Resource	ComponentMedia	Substrate specifications with detailed properties
Layout Resource	ComponentLayout	Imposition and layout specifications
Process Pool	Operation	Production steps and processes
Device Resource	Device	Print devices and equipment
RunList	ComponentFileUsage	File references and content links
NodeInfo States	JobStateEnum, OperationStateEnum	Workflow state tracking
Resource Pool	Various inventory types	LocationStockAvailability, Transfer

Domain Architecture

CoCore organizes print production into clear domains:

1. Production Domain

• Jobs: The central work unit, similar to JDF job tickets
• Components: Physical parts of a job (think JDF Component resources)
• Operations: Processing steps (like JDF Process nodes)
• Milestones: Key checkpoints in production

2. Commerce Domain

• Orders: Customer orders linking to jobs
• Customers: Customer management
• Pricing: Dynamic pricing calculations

3. Device Domain

• Devices: Print equipment and peripherals
• Device Groups: Logical groupings for load balancing
• Capabilities: Device-specific features and constraints

4. Logistics Domain

• Locations: Warehouse and production areas
• Transfers: Material movement
• Stock Availability: Real-time inventory

Key Differences from JDF

1. Query-Driven vs Document-Based

JDF:

<JDF Type="Product" Status="Waiting">
  <ResourcePool>
    <Component Class="Quantity" ID="C1" Status="Available"/>
    <Media Class="Consumable" ID="M1" Status="Available"/>
  </ResourcePool>
</JDF>

CoCore:

query GetJobWithComponents {
  getJob(id: "job-123") {
    state
    components {
      results {
        kind
        media {
          name
          status
        }
      }
    }
  }
}

2. Real-Time State Management

Unlike JDF's polling-based status updates, CoCore provides:

• Real-time subscriptions to state changes
• Event-driven architecture
• Optimistic updates with immediate feedback

3. Flexible Relationships

Where JDF uses references and links between resources, CoCore uses:

• Direct relationship traversal in queries
• Lazy loading of related data
• Bidirectional relationships

Core API Patterns

Keyset Pagination

CoCore uses keyset pagination for efficient data retrieval:

query ListJobs {
  listJobs(first: 20, after: "cursor-xyz") {
    count
    results {
      id
      jobNumber
      name
    }
    startKeyset
    endKeyset
  }
}

Filtering and Sorting

Complex filtering similar to JDF XPath queries:

query FilteredJobs {
  listJobs(
    filter: {
      state: { eq: IN_PRODUCTION }
      createdAt: { greaterThan: "2024-01-01" }
    }
    sort: [{ field: CREATED_AT, order: DESC }]
  ) {
    results {
      id
      jobNumber
    }
  }
}

Mutations with Result Types

All mutations return result types with success/error information:

mutation CreateJob {
  createJob(input: {
    name: "Business Cards - ACME Corp"
    quantity: 1000
    externalId: "JDF-2024-001"
  }) {
    result {
      id
      jobNumber
    }
    errors {
      field
      message
    }
  }
}

Getting Started

1. Explore the Schema

The complete GraphQL schema is available at /api/graphql with introspection enabled. Use tools like GraphQL Playground or Apollo Studio to explore.

2. Authentication

CoCore uses bearer token authentication:

Authorization: Bearer your-api-token

3. Your First Query

Start with a simple query to understand the structure:

query MyFirstQuery {
  me {
    id
    email
  }
  listJobs(first: 5) {
    results {
      id
      jobNumber
      name
      state
    }
  }
}

4. Understanding Results

Most list queries return a keyset page structure:

• count: Total number of records
• results: Array of requested items
• startKeyset/endKeyset: Pagination cursors

Common Integration Patterns

From JDF Submission

If you're migrating from JDF-based job submission:

1. Parse JDF intent and product requirements → Create Job and JobProduct
2. Extract component specifications → Create Component records
3. Map media resources → Set ComponentMedia properties
4. Convert process instructions → Create Operation sequence
5. Link runlist entries → Create ComponentFileUsage records

Workflow Integration

CoCore can complement existing JDF workflows:

• Use GraphQL for real-time status and control
• Maintain JDF for detailed job tickets
• Sync state between systems using subscriptions
• Export to JDF format for legacy devices

Next Steps

• Core Patterns: Deep dive into pagination, filtering, and error handling
• Job Management: Complete job lifecycle management
• Components and Media: Working with print components

Quick Reference

Essential Queries

• getJob(id: ID!): Retrieve a specific job
• listJobs(...): List jobs with filtering and pagination
• getComponent(id: ID!): Get component details
• listOperations(...): List production operations

Essential Mutations

• createJob(input: CreateJobInput!): Create a new job
• updateJob(id: ID!, input: UpdateJobInput): Update job properties
• transitionJobState(id: ID!, state: JobStateEnum!): Change job state
• createComponent(input: CreateComponentInput!): Add a component

Essential Types

• Job: Core job definition
• Component: Print component with media and layout
• Operation: Production process step
• Device: Print equipment
• Order: Customer order

Support and Resources

• GraphQL Playground: Available at /api/graphql in development
• Schema Documentation: Auto-generated from schema annotations
• API Versioning: The schema is versioned and backwards compatible
• Rate Limiting: See headers for rate limit information

Welcome to modern print production with CoCore!