# 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.

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

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# 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:

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

### Sorting

Sort results by one or more fields:

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

### Relations

Query related data:

```graphql
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.

### Query Structure

```graphql
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 |

### Examples

#### Example 1: Total build Metrics

Calculate aggregate metrics across all build records:

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

Expected result structure:

```json
{
  "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)

### 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

#### `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.

**Label:** Work effort Url

#### `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

#### `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

#### `completeDate`
Consolidated completion date for the build, showing either the actual completion date or estimated completion date depending on build status.

**Label:** Complete date

#### `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

#### `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

#### `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

#### `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

#### `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

#### `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

### 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

**Possible Values:**
- `PRUN_CREATED` – Draft
- `PRUN_STARTED` – Started
- `PRUN_COMPLETED` – Completed
- `PRUN_CANCELLED` – Canceled

### Relations

#### cancelTransactionUser
- **Related Collection:** userLogin
- **Label:** Cancel transaction user

#### completeTransactionUser
- **Related Collection:** userLogin
- **Label:** Complete transaction user

#### productToProduce
- **Related Collection:** product
- **Label:** Product to produce