Build

Overview

Builds represent manufacturing or assembly activities where you consume component materials and produce finished goods. They update inventory by removing components from stock and adding finished products, while tracking the cost of goods manufactured. Builds are essential for companies that assemble products from parts or manufacture finished goods.

The build process follows a clear workflow. You create a build specifying the product to produce, the quantity to make, and the components to consume. Many builds use the product's Bill of Materials (BOM) as a template, automatically pulling in the component list, but you can also manually specify components for one-off assembly jobs.

When you start a build, components are consumed from inventory. The system deducts the specified quantities of each component from warehouse stock, creating negative stock history entries. This consumption happens immediately upon starting, reflecting that those materials are no longer available for other uses - they're now work in progress.

Upon completing the build, finished products are added to inventory. The system creates positive stock history entries for the produced quantity, specifying which lot ID and sublocation will hold the finished goods. The completion step finalizes the build and calculates the cost of goods manufactured (COGM) based on the component costs plus any overhead or labor costs included in the build.

The cost accounting in builds is important for accurate financial reporting. COGM is calculated from the actual costs of the components consumed, tracking those costs forward to the finished products. This cost flows through to subsequent sales, ensuring your cost of goods sold reflects the actual manufacturing costs. The system calculates both total COGM and per-unit COGM, supporting detailed financial analysis.

Builds can be started and completed immediately for simple assemblies, or they can remain in "started" status for extended periods if production takes time. The system tracks estimated and actual start dates, estimated and actual completion dates, giving you visibility into production timelines. Builds can also be canceled if production is abandoned, which reverses the component consumption and doesn't produce finished goods.

GraphQL API

The build collection provides access to build data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: buildViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
18 filter options
14 sortable fields
8 relations to other collections

Query Examples

Basic Query

The build collection is accessed via the buildViewConnection query, which returns a Relay-style connection with pagination support.

query {
  buildViewConnection(first: 10) {
    edges {
      node {
        buildId
        buildUrl
        cancelDate
        cancelTransactionTimestamp
        completeDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  buildViewConnection(first: 50) {
    edges {
      node { buildId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  buildViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { buildId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  buildViewConnection(
    first: 10
    buildUrl: "/finaleengineer/api/workeffort/100000"
  ) {
    edges {
      node { buildId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  buildViewConnection(
    first: 10
    sort: [{ field: "buildId", mode: "desc" }]
  ) {
    edges {
      node {
        buildId
              }
    }
  }
}

Relations

Query related data (see Relations section for all available relations):

query {
  buildViewConnection(first: 10) {
    edges {
      node {
        buildId
        cancelTransactionUser {
          name
          userLoginUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

buildViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 3 metrics that can be aggregated:

Metric	Parameters	Description
`totalCogm`	`transform`, `operator`	totalCogm for build
`quantityToProduce`	`transform`, `operator`	quantityToProduce for build
`count`	None	Count of items in the result set

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

Examples

Example 1: Total build Metrics

Calculate aggregate metrics across all build records:

query {
  buildViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "buildViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 22 fields:

20 simple fields
2 enum fields (with predefined values)
0 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

`buildId`

Unique identifier for the build work effort. This ID is used to reference and track specific build operations throughout the system.

Label: Build ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  build(buildUrl: "example-url") {
    buildId    # Uses default formatter: html
    buildIdRaw: buildId(formatter: "none")  # Get raw value
  }
}

`buildUrl`

Unique identifier for the build work effort resource in the API. This field is automatically generated by the server and provides a reference to access the build's detailed information through the work effort endpoint.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: Work effort Url
Sortable: No

`cancelDate`

The date when the build was cancelled. This field is not editable and is set when a build's status changes to cancelled.

Label: Cancel date
Sortable: Yes

`cancelTransactionTimestamp`

Transaction timestamp indicating when the build was cancelled. Used for sorting builds by their cancellation time to determine the most recent status change.

Label: Cancel transaction timestamp
Sortable: No

`completeDate`

Consolidated completion date for the build, showing either the actual completion date or estimated completion date depending on build status. This field combines both actual and estimated dates for display and sorting purposes.

Label: Complete date
Sortable: No

`completeDateActual`

The actual date when the build was completed. This editable field records when the build work effort was finalized and marked as complete.

Label: Complete date actual
Sortable: Yes

`completeDateEstimated`

The estimated date for build completion. This editable field allows users to plan and schedule when the build is expected to be finished.

Label: Complete date estimated
Sortable: Yes

`completeTransactionTimestamp`

Transaction timestamp indicating when the build was marked as complete. Used for sorting builds by their completion time to determine the most recently completed builds.

Label: Complete transaction timestamp
Sortable: No

`description`

A text description providing additional context or notes about the build. This field allows users to add human-readable information to identify or explain the purpose of specific builds.

Label: Description
Sortable: Yes

`lotIdToProduce`

The lot identifier for the inventory being produced by this build. This formatted lot ID includes any facility or product prefixes and is displayed to users throughout the system.

Label: Lot ID to produce
Sortable: Yes

`lotIdToProduceUnprefixed`

The lot identifier for the produced inventory without facility or product prefixes. This provides the raw lot ID value for cases where the prefix information is not needed.

Label: Lot ID to produce unprefixed
Sortable: Yes

`quantityToProduce`

The number of units to be produced in this build. This editable quantity field represents the target output for the work effort and can only be modified for draft builds that have not yet been started or completed.

Label: Quantity to produce
Sortable: No

`recordCreated`

The timestamp when this build record was first created in the system. This tracks when the build was initially entered, regardless of when production actually starts.

Label: Created timestamp
Sortable: Yes

`recordLastUpdated`

The timestamp of the most recent modification to this build record. This tracks when any field on the build was last changed, helping identify recently updated builds.

Label: Last updated timestamp
Sortable: Yes

`startDate`

The planned or actual start date for production. This field consolidates the estimated and actual start dates, showing the actual date if production has begun, otherwise showing the estimated date.

Label: Start date
Sortable: No

`startDateActual`

The actual date when production work on this build began. This is recorded when the build status changes to indicate production has started, distinguishing it from the initially estimated start date.

Label: Start date actual
Sortable: Yes

`startDateEstimated`

The estimated date when production work is planned to begin on this build. This date can be edited and is used for planning purposes before the actual start date is recorded.

Label: Start date estimated
Sortable: Yes

`startTransactionTimestamp`

The timestamp when the transaction that started this build was recorded in the system. This captures the exact moment the build transitioned to a started status.

Label: Start transaction timestamp
Sortable: No

`totalCogm`

The total cost of goods manufactured for this build. This calculated value represents the aggregate cost of all materials and resources consumed during the manufacturing process.

Label: Total COGM
Sortable: Yes

`totalCogmPerUnit`

The cost of goods manufactured per individual unit produced. This calculated metric divides the total manufacturing cost by the quantity produced to determine the per-unit cost.

Label: COGM per unit
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

`status`

The current lifecycle status of the build, indicating whether it is created, started, completed, or cancelled. Valid statuses include PRUN_CREATED, PRUN_STARTED, PRUN_COMPLETED, and PRUN_CANCELLED.

Label: Status
Sortable: Yes

Possible Values:

PRUN_CREATED - Draft
PRUN_STARTED - Started
PRUN_COMPLETED - Completed
PRUN_CANCELLED - Canceled

`validation`

Validation constraints applied to build fields to ensure data integrity. For example, lot ID fields are validated to reject invalid characters like emojis or certain unicode symbols, while builds in started or completed status cannot have their inventory consumption or production modified.

Label: Validation
Sortable: No

Possible Values:

##good - Good
##missingItem - Missing item
##quantityMismatch - Build quantity mismatch
##produceMismatch - Produce quantity mismatch
##negativeQuantity - Negative build quantity