> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage mBOM versions and release approvals

> Create mBOM versions, move them between statuses, and set up the approvals that gate release through the ION GraphQL API.

A part's mBOM is versioned. A version's status decides whether you can edit it and which statuses it can move to, and approvals can gate its release. You edit the items of an editable version: a version in **Draft**, or one in **In Review** that no reviewer has approved or rejected. For which changes need a new version, see [Manage BOM versions](https://docs.firstresonance.io/build-hardware/bills-of-materials/versions.md). To manage the items in a version, see [Manage mBOM items](https://docs.firstresonance.io/api/guides/mboms.md).

## mBOM statuses

| Status | API value | What you can do |
| - | - | - |
| **Draft** | `DRAFT` | Edit the items. A new version starts here. |
| **In Review** | `IN_REVIEW` | Edit the items until a reviewer approves or rejects the version. After that, the items are read only until the version moves back to **Draft**. Reviewers approve the version while it's in this status. |
| **Released** | `RELEASED` | Read only. |
| **Archived** | `ARCHIVED` | Read only. |

A version can move between statuses as follows:

| From | Can move to |
| - | - |
| **Draft** | **In Review**, **Archived** |
| **In Review** | **Draft**, **Released**, **Archived** |
| **Released** | **Draft**, **In Review**, **Archived** |
| **Archived** | **Draft**, **In Review** |

A version can't go straight from **Draft** to **Released**. Move it to **In Review** first.

`isLatestVersion` is true for the part's highest version number. `isLatestReleasedVersion` is true for the highest version number among the part's **Released** versions.

## Create an mBOM version

Create a version with `createMbom`. The new version gets the next version number for the part and starts in **Draft**.

```graphql theme={null}
mutation CreateMBom($input: CreateMBomInput!) {
    createMbom(input: $input) {
        mbom {
            id partId version status
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "partId": 1
    }
}
```

By default, the new version is a copy of the part's latest version, including every item with its substitutes and reference designators. If the part has no mBOM yet, the new version is empty.

Two options change what gets copied:

* `copyMbom` defaults to `true`. Set it to `false` to create an empty version.
* `mbomId` copies a specific version instead of the latest. The version must belong to the part in `partId`. Don't combine `mbomId` with `copyMbom: false`.

The request fails with one of these messages when the options conflict:

| Cause | Message |
| - | - |
| `mbomId` with `copyMbom` set to `false` | `mbomId cannot be used when copyMbom is false.` |
| `mbomId` for a different part | `mbomId (X) to be copied does not match specified partId (Y).` |

## Move an mBOM between statuses

Change a version's status with `updateMbom`. Pass the mBOM's `id`, its current `etag`, and the new `status`. The `id` is an `Int!`. The item mutations and `deleteMbom` take an `ID!` instead.

```graphql theme={null}
mutation UpdateMBom($input: UpdateMBomInput!) {
    updateMbom(input: $input) {
        mbom {
            id status version
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "etag": "etag1",
        "status": "IN_REVIEW"
    }
}
```

A move that the table in [mBOM statuses](#mbom-statuses) doesn't allow fails with `MBom with status DRAFT cannot transition to RELEASED.`, with the two statuses in place of `DRAFT` and `RELEASED`.

Two rules apply to specific moves:

* **Moving to Released.** If the organization has release approvals, the move fails with `Cannot set mBOM status to RELEASED until all approval requests have been approved.` until the approvals in [Release approvals](#release-approvals) are in place. Moving to **In Review** never needs approval.
* **Moving a Released version back to Draft or In Review.** The move fails if aBOM build requirements or part kit items reference the version's items. The message names the kinds of record that block it, as in `mBOM cannot be deleted or moved from RELEASED status because BuildRequirements, PartKitItems reference mBOM items from this mBOM.` Moving a Released version to **Archived** isn't blocked this way.

## Delete a draft mBOM

You can delete only a version in **Draft**. Deleting a version in any other status fails, and so does deleting a draft whose items are referenced by aBOM build requirements or part kit items. Delete the version with `deleteMbom`, passing the `id` and the current `etag`.

```graphql theme={null}
mutation DeleteMBom($id: ID!, $etag: String!) {
    deleteMbom(id: $id, etag: $etag) {
        id
    }
}
```

Set the variables:

```json theme={null}
{
    "id": 1,
    "etag": "etag1"
}
```

## Release approvals

Release approvals are optional. An organization turns them on by adding approval roles to the **Released** gate. Each approval role names an ION role and the number of approvers from that role that a release needs.

A version can move to **Released** when both of these are true:

* Every approval request on the version is approved.
* For each approval role, the version has at least that role's `count` of approval requests.

If the organization has no approval roles and a version has no approval requests, the version can move to **Released** with no approval.

### Set up approval roles

You manage approval roles through the API only. ION has no page for them. The only gate is `RELEASED`.

Create a role with `createMbomApprovalRole`:

```graphql theme={null}
mutation CreateMBomApprovalRole($input: CreateMBomApprovalRoleInput!) {
    createMbomApprovalRole(input: $input) {
        approvalRole {
            roleId gateType count
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "roleId": 3,
        "gateType": "RELEASED",
        "count": 2
    }
}
```

`count` must be 1 or more. A role that already exists for the gate is changed with `updateMbomApprovalRole` and removed with `deleteMbomApprovalRole`. Both take the role's `roleId`, the `gateType`, and the current `etag`. List the roles with the `mbomApprovalRoles` query.

### Request and record approvals

An approval request is a separate record. Create one request for each person who should approve:

```graphql theme={null}
mutation CreateMBomApprovalRequest($input: CreateMBomApprovalRequestInput!) {
    createMbomApprovalRequest(input: $input) {
        approvalRequest {
            id status roleId assignedToId
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "mbomId": 1,
        "gateType": "RELEASED",
        "roleId": 3,
        "assignedToId": 12
    }
}
```

These rules apply to a request:

* The version must be in **Draft** or **In Review**. Otherwise the request fails with `Cannot create approval request for released gate unless the status is at or before in_review.`
* The person in `assignedToId` must hold the role in `roleId`. Otherwise the request fails with `The assignee does not have the role` and the role's name.
* A person can have only one request per version and gate.

The assignee records their decision with `createMbomApproval`. The approval is recorded for the user that makes the call.

```graphql theme={null}
mutation CreateMBomApproval($input: CreateMBomApprovalInput!) {
    createMbomApproval(input: $input) {
        approval {
            id status mbomId reviewer { id }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "mbomId": 1,
        "gateType": "RELEASED",
        "status": "APPROVED",
        "comment": "Approved",
        "content": [{ "children": [{ "text": "Approved" }] }]
    }
}
```

`content` is required. `status` is `APPROVED`, `REJECTED`, or `PENDING`. An approval with the `PENDING` status is a comment and doesn't need a request. For `APPROVED` and `REJECTED`, these rules apply:

* The version must be in **In Review**. Otherwise the call fails with `Cannot do approval if MBoms is not in in_review status.`
* You must have an approval request on the version. Otherwise the call fails with `You have no approval requests that match the approval requests.`
* You can approve a gate only once. A second approval fails with `You have already approved an approval request for this approval gate.`

Once every request is approved and each role has its `count`, move the version to **Released** with `updateMbom`.

An organization setting decides whether a procedure uses a pinned mBOM version. For more information, see [Enable mBOM version selection](https://docs.firstresonance.io/administration/production-settings/enable-mbom-version-selection.md).


## Related topics

- [Manage mBOM items](https://docs.firstresonance.io/api/guides/mboms.md)
- [Manage BOM versions](https://docs.firstresonance.io/build-hardware/bills-of-materials/versions.md)
- [Create and release a procedure](https://docs.firstresonance.io/build-hardware/procedures/create-and-release-a-procedure.md)
- [Manage parts and revisions](https://docs.firstresonance.io/api/guides/parts-and-part-revisioning.md)
- [Manufacturing BOM (mBOM)](https://docs.firstresonance.io/build-hardware/bills-of-materials/manufacturing-bom.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.