> ## 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 parts and revisions

> Query, create, update, revision, and delete Parts through the ION GraphQL API, including custom revision schemes.

Part objects in ION represent abstractions that carry information about a particular part, while the physical parts themselves are Inventory objects. A Part object dictates the mBOM, revision, supplier part number, tracking type, and other attributes of a part.

The following table lists common Part attributes and their descriptions. For the full list of Part fields, use the [GraphiQL editor](https://app.firstresonance.io/graphiql) to view the Part object.

| Part field       | Description                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| `id`             | Unique identifier of the Part object.                                                             |
| `partNumber`     | Parts must have a unique `partNumber` and `revision`.                                             |
| `revision`       | Revision for the part. Defaults to A.                                                             |
| `trackingType`   | If set, enforces all inventory for the part to match the tracking type. Either `serial` or `lot`. |
| `quantity`       | The summed quantity of all inventory for a part.                                                  |
| `partsInventory` | List of Inventory objects related to a part.                                                      |
| `runs`           | List of runs related to the part.                                                                 |
| `mbom`           | List of mBOM items that describe the BOM of a part.                                               |

## Query parts

The queries below list parts by a filter or get a specific part.

List parts with a filter:

```graphql theme={null}
query GetParts($filters: PartsInputFilters, $first: Int) {
    parts(filters: $filters, first: $first) {
        edges {
            node {
                id partNumber description thumbnail { s3Key s3Bucket url }
                fileAttachments { url } quantity
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "partNumber": {
            "eq": "ion-12"
        }
    },
    "first": 10
}
```

Get a single part by ID:

```graphql theme={null}
query GetPart{
    part(id: 1) {
        id partNumber description quantity
    }
}
```

## Create a part

The `createPart` mutation creates a Part object with a particular part number. The part number and revision must be unique. If you supply no revision in the mutation, the part defaults to revision A. Once created, you cannot update the revision of a part. Instead, use the `createPartRevision` mutation to iterate a part's revision. The mutation returns the new part.

Create the part with this mutation:

```graphql theme={null}
mutation CreatePart($input: CreatePartInput!) {
    createPart(input: $input) {
        part {
            id revision partNumber description
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "partNumber": "ion-12",
        "description": "Part for API docs.",
        "revision": "C"
    }
}
```

<Tip>
  If the part you create contains custom attributes, declare the attributes when you create the part, even if an attribute contains no value.
</Tip>

To create a part with attributes, include them in the mutation input:

```graphql theme={null}
mutation CreatePart($input: CreatePartInput!) {
    createPart(input: $input) {
        part {
            id revision partNumber description attributes { key value }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "partNumber": "ion-12",
        "description": "Part for API docs.",
        "revision": "C",
        "attributes": [
            {
                "key": "Attribute 1"
            },
            {
                "key": "Attribute 2",
                "value": "Value for attribute 2"
            }
        ]
    }
}
```

## Update a part

The `updatePart` mutation updates a Part object. You can update the tracking type to either `serial` or `lot` only if all existing inventory objects related to the part conform to the new tracking type. The mutation returns the updated Part object.

Update the part with this mutation:

```graphql theme={null}
mutation UpdatePart($input: UpdatePartInput!) {
    updatePart(input: $input) {
        part { id partNumber description revision }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "etag": "etag1",
        "partNumber": "ion-13",
        "description": "Updated part for API docs."
    }
}
```

## Create a part revision

The `createPartRevision` mutation creates a new revision for a particular part. You can generate a revision from any part. For example, if your part "ion-13" has existing revisions A and B, you can generate a third revision C from either revision A or B. All information in the new revision is copied from the old revision unless you explicitly override it in the mutation input. The new revision is the next valid alphabetic character from the part's latest revision. If the part's latest revision is C, the new revision is D. If the part's latest revision is Z, the new revision is AA. The mutation returns the newly created Part object with the updated revision.

Create a revision with this mutation:

```graphql theme={null}
mutation CreatePartRevision($input: CreatePartRevisionInput!) {
    createPartRevision(input: $input) {
        part {
            id partNumber revision
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "etag": "etag1",
        "description": "New revision for part in API docs."
    }
}
```

## Delete a part

The `deletePart` mutation deletes a Part object. This deletes the Part object and cascades to delete the mBOM and mBOM substitutes associated with the part. You cannot delete a part that has existing inventory or that was used within a run. The mutation returns the ID of the deleted part.

Delete the part with this mutation:

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

Set the variables:

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

## Custom part revision scheme

ION lets you define custom schemes for part revisioning. You define these schemes in your organization's settings. The mutation below creates a new scheme. You first need the ID and etag of the organization before you can update its settings. Four additional variables define a part revision scheme:

* **name** (string): The name of the new revision scheme.
* **default** (boolean): If `true`, all newly created parts inherit this revision scheme.
* **allowOverflow** (boolean): Defines whether ION raises an error when the revision scheme reaches its max iteration, or overflows to the next available value.
* **format** (array of strings): Defines how the values of a revision scheme appear. The string values in the array can be `NUMERIC`, `ALPHABETICAL`, or single-character-length constants. The format below defines part revisions like `00-1` or `95-7`.

Create the revision scheme with this mutation:

```graphql theme={null}
mutation CreateOrganizationPartRevisionScheme(
        $input: CreatePartRevisionSchemeSettingInput!) {
    createOrganizationPartRevisionScheme(input: $input) {
        organization {
            id settings {
                parts {
                    revisionSchemes {
                        default name allowOverflow format } } }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "name": "new scheme",
        "default": true,
        "format": ["NUMERIC", "NUMERIC", "-", "NUMERIC"],
        "etag": "etag1",
        "allowOverflow": true
    }
}
```

## Update a part revision scheme

Once a part revision scheme exists in your organization's settings, you can update it. The only fields you can update on a part revision scheme are `allowOverflow` and `default`.

Update the revision scheme with this mutation:

```graphql theme={null}
mutation UpdateOrganizationPartRevisionScheme(
        $input: UpdatePartRevisionSchemeSettingInput!) {
    updateOrganizationPartRevisionScheme(input: $input) {
        organization {
            id settings {
                parts {
                    revisionSchemes {
                        default name allowOverflow format } } }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "name": "new scheme",
        "default": false,
        "etag": "etag1",
        "allowOverflow": false
    }
}
```

## Convert the revision scheme of an existing part

Two strategies change the revision scheme of an existing part. Both set the `revisionScheme` for a part in either the `updatePart` or `createPartRevision` mutation above. Set `revisionScheme` to the name of one of the schemes in your organization's settings.

* Setting `revisionScheme` in the `updatePart` mutation casts the part's revision. For example, if a part currently has revision `D` and you update that part to use the revisionScheme "new scheme" created above, the revision is set to `00-4`.
* Setting `revisionScheme` in the `createPartRevision` mutation resets the part's revision, starting it over from the initial revision of the new scheme. If a part has revision `D` and you update the part's `revisionScheme` in the `createPartRevision` mutation, it is set to `00-1`.