Skip to main content
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. To manage the items in a version, see Manage mBOM items.

mBOM statuses

A version can move between statuses as follows: 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.
Set the variables:
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:

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.
Set the variables:
A move that the table in 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 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.
Set the variables:

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:
Set the variables:
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:
Set the variables:
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.
Set the variables:
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.