# Customize the login page
Source: https://docs.firstresonance.io/administration/authentication-settings/customize-login-page

Add your organization's logo and brand colors to the ION sign-in page.

## Customize the login page

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Login Page Branding** card, enter:
   * **Logo URL**: a publicly accessible URL to your logo image (for example, `https://example.com/logo.png`).
   * **Primary Color**: a hex color for buttons and accents (for example, `#16A34A`).
   * **Background Color**: a hex color for the page background (for example, `#FFFFFF`).
3. Click **Save Branding**.

Your branding applies to the login page.


# Enforce MFA
Source: https://docs.firstresonance.io/administration/authentication-settings/enforce-mfa

Require multi-factor authentication for everyone in your organization or just yourself.

For what MFA adds to either sign-in method, see the [Overview](/administration/authentication-settings).

## Enforce MFA for all users

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Multi-Factor Authentication** card, turn on **Require MFA for all users**.

<Warning>
  Org-wide MFA applies to everyone the moment you turn it on. To avoid locking
  users out, confirm your team can enroll an authenticator app, and validate the
  change in a sandbox tenant first if you have one.
</Warning>

## Enforce MFA for yourself

You can enable MFA on your own profile without org-wide enforcement enabled. After enabling, log out and sign back in to start the MFA setup flow. If you lose access to your MFA device, see [Troubleshooting sign-in issues](/administration/authentication-settings/sign-in#troubleshooting).

## Related

* [Troubleshooting sign-in issues](/administration/authentication-settings/sign-in#troubleshooting)


# Overview
Source: https://docs.firstresonance.io/administration/authentication-settings/index

How authentication works in ION: email and password or SSO, and the domain verification that ties users to your organization.

ION identifies every user by their company email address. When someone [signs in](/administration/authentication-settings/sign-in), ION looks at the email's domain to decide what happens next: if the domain has an SSO connection, ION redirects to your identity provider to authenticate; otherwise the user enters an ION password. Everything you configure on the **Settings > Organization > Authentication** page shapes that flow: which domains belong to your organization, whether SSO is on, whether MFA is required, and what the sign-in page looks like.

## Two ways to sign in

* **Email and password**: ION manages the credential. New users get an invite email with a link to set their password, and a forgotten password is [reset from the sign-in page](/administration/authentication-settings/reset-your-password).
* **Single sign-on (SSO)**: your identity provider manages the credential. ION creates a user profile automatically on first SSO sign-in with the default **User** role, and removing someone from your IdP stops their SSO access to ION. Passwords, in this case, are reset in your IdP, not in ION. For connecting and maintaining an IdP, see the [SSO overview](/administration/authentication-settings/sso).

The two coexist per domain, not per user: once SSO is active for a verified domain, users on that domain are routed to the IdP.

## Domains

A claimed, verified domain tells ION that email addresses on that domain belong to your organization. Verification works by DNS: ION gives you a TXT record to publish, then confirms you own the domain. A verified domain acts as an allowlist that associates matching users with your organization at sign-up, and it's the prerequisite for SSO. See [Manage domains](/administration/authentication-settings/manage-domains).


# Manage domains
Source: https://docs.firstresonance.io/administration/authentication-settings/manage-domains

Claim and verify your company's email domain so ION can route users to your organization at login.

A verified domain is required before you can set up enterprise SSO or automatic user provisioning. For what domain verification does, see the [Overview](/administration/authentication-settings).

<Warning>
  Coordinate a full domain change, such as migrating your organization to a new company email domain, with [First Resonance support](https://support.firstresonance.io) in advance. Claiming a new domain associates matching users with your organization going forward. It doesn't move your existing users, who keep signing in with their current email addresses until each account is updated individually.
</Warning>

## Add a domain

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Domain Management** card, enter your domain in the **Add Domain** field and click **Add Domain**.

The domain appears in your **Claimed Domains** list with a **Pending** status.

## Verify the domain

After you add a domain, ION displays the name and value of a DNS TXT record to publish.

1. Give the TXT record name and value to whoever manages your DNS, and have them add it to the domain's DNS settings.
2. Once the record is live, click **Check Verification** next to the domain.

ION checks for the record and updates the domain's status. DNS changes can take a few minutes to propagate. If verification is still **Pending**, wait and try again.

## Domain statuses

| Status       | Meaning                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| **Verified** | Ownership confirmed. ION routes users on this domain to your organization.                                 |
| **Pending**  | Waiting on the DNS record, or DNS hasn't propagated yet.                                                   |
| **Failed**   | ION couldn't find the expected TXT record. Double-check the record and click **Check Verification** again. |

## Remove a domain

1. In the **Domain Management** card, click the remove icon next to the domain.
2. In the **Remove domain** dialog, click **Remove domain** to confirm.

<Warning>
  Removing a domain means users with email addresses on that domain are no longer automatically associated with your organization at login. Only remove a domain you no longer use. If you're transferring your organization to a different domain, work with [First Resonance support](https://support.firstresonance.io) to move accounts over before you remove the old domain.
</Warning>

## Related

* [Set up SSO](/administration/authentication-settings/sso/set-up-sso)


# Reset your password
Source: https://docs.firstresonance.io/administration/authentication-settings/reset-your-password

How to reset a forgotten ION password from the sign-in page.

1. On the ION sign-in page, click **Don't remember your password?**
2. Enter your email address and submit.
3. Check your inbox for a reset email from `invites@firstresonance.io` and follow the link to set a new password.

If your organization uses SSO, reset your password in your identity provider, not in ION.

<Note>
  If the reset email doesn't arrive, check your spam folder. IT teams: allowlist `invites@firstresonance.io` to ensure password reset and invite emails are delivered.
</Note>

## Related

* [Sign in to ION](/administration/authentication-settings/sign-in)


# Sign in to ION
Source: https://docs.firstresonance.io/administration/authentication-settings/sign-in

How to sign in to ION with email and password or single sign-on.

Go to your organization's ION URL and enter your **company email address**, then click **Continue**. ION either prompts you for your ION password or, if your email domain uses SSO, redirects you to your identity provider and back. For how this routing works, see the [Overview](/administration/authentication-settings).

## Sign in for the first time

With SSO, just sign in through your identity provider. The very first person to sign in to a new ION organization becomes its administrator; every subsequent user gets the default **User** role, which an admin can extend.

With email and password, an administrator at your company sends you an invite email with a link to set your password.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I'm told I'm not authorized to access the application">
    Verify that you're signing in with the correct URL: `app-v2.buildwithion.com`, `app-v2.gov.buildwithion.com`, or `app-v2.ap.buildwithion.com` (or the correct sandbox URL if applicable).
  </Accordion>

  <Accordion title="My company is new to ION and I can't sign in for the first time">
    Your ION environment might still be setting up. Wait 15 minutes and try again.
  </Accordion>

  <Accordion title="My account has been deactivated">
    Contact an administrator at your company to reactivate your ION account.
  </Accordion>

  <Accordion title="You have no roles error">
    A required permission isn't enabled for your role. An admin can grant it. See [Create a role](/administration/users-and-permissions/manage-roles).
  </Accordion>

  <Accordion title="I need to reset my MFA and can't access my authenticator device">
    Contact [support](https://support.firstresonance.io/) to reset it.
  </Accordion>
</AccordionGroup>

## Related

* [Reset your password](/administration/authentication-settings/reset-your-password)


# Disable SSO
Source: https://docs.firstresonance.io/administration/authentication-settings/sso/disable-sso

Turn off your SSO connection so users sign in with email and password instead.

For what disabling SSO means for your team, see the [Overview](/administration/authentication-settings).

<Warning>
  Disabling SSO removes the connection entirely. Turning SSO back on later
  requires running the setup wizard again. Anyone already signed in stays signed
  in until their session ends.
</Warning>

## Disable SSO

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Enterprise SSO** card, click **Disable SSO**.

## Related

* [Set up SSO](/administration/authentication-settings/sso/set-up-sso)
* [Rotate your SAML signing certificate](/administration/authentication-settings/sso/rotate-saml-certificate)


# Overview
Source: https://docs.firstresonance.io/administration/authentication-settings/sso/index

The life of an SSO connection in ION: set it up, keep its certificate current, and retire it.

An SSO connection hands authentication to your identity provider (Okta, Microsoft Entra ID, Google Workspace, ADFS, or another SAML or OIDC provider) and has a life beyond initial setup:

1. **Set up**: after verifying your domain, you connect your IdP through a self-service wizard that exchanges SAML or OIDC details and maps user attributes. See [Set up SSO](/administration/authentication-settings/sso/set-up-sso).
2. **Maintain**: SAML connections verify each login against your IdP's signing certificate. When that certificate expires or your security team rotates it, you update ION with the new one, coordinated with the IdP switch. OIDC keys rotate automatically. See [Rotate your SAML signing certificate](/administration/authentication-settings/sso/rotate-saml-certificate).
3. **Retire**: disabling SSO removes the connection and returns your team to email and password sign-in without deleting any accounts. See [Disable SSO](/administration/authentication-settings/sso/disable-sso).

<Warning>
  A misconfigured SSO connection or an out-of-sync certificate rotation blocks fresh sign-ins to production. Validate authentication changes in a sandbox tenant when you have one, and keep the previous certificate on hand during a rotation.
</Warning>


# Rotate your SAML signing certificate
Source: https://docs.firstresonance.io/administration/authentication-settings/sso/rotate-saml-certificate

Replace an expiring or rotated SAML signing certificate on your SSO connection without opening a support ticket.

This page applies to SAML connections only. OIDC connections have no signing certificate to rotate. For how certificate rotation fits into the SSO lifecycle, see the [Overview](/administration/authentication-settings).

## When you'll need to do this

* **Certificate expiry.** Most IdP signing certificates are valid for one to three years. Your IdP or security team issues a replacement before the old one expires.
* **Scheduled key rotation.** Routine security hygiene, or a response to a suspected key compromise.
* **IdP changes.** Switching identity providers, or upgrading the signing algorithm (for example, moving from SHA-1 to SHA-256).
* **Auto-rolled keys.** Your IdP changed its signing key on its own (for example, Microsoft Entra auto-rolled its certificate).

## Before you start

The **Rotate certificate** button is only visible to org administrators with SSO management permission.

Rotating the certificate requires updating both your IdP and ION at roughly the same time. If they're out of sync, logins fail.

<Warning>
  ION holds one signing certificate per connection at a time. There's no overlap
  period where both the old and new certificates are valid. New sign-ins briefly
  fail in the window between your IdP switching to the new key and ION being
  updated to match. Anyone already signed in stays signed in; the certificate is
  only checked on fresh logins.
</Warning>

Keep your previous certificate available until you've confirmed a successful login. Rolling back means pasting the old certificate back.

## What you'll need

From your IdP administrator, get one of the following for the new certificate:

* The new **X.509 certificate** in PEM format (a text block beginning with `-----BEGIN CERTIFICATE-----`), or
* Your IdP's **SAML 2.0 metadata XML** (beginning with `<?xml` or `<EntityDescriptor`).

Either format works. ION detects which one you've provided.

A few formatting tips that prevent common errors:

* **Paste the certificate as text, not a binary file.** Several IdPs (Microsoft Entra ID, ADFS) download the certificate as a binary `.cer`/`.crt` file. Convert it to PEM first: `openssl x509 -inform der -in cert.cer -out cert.pem`. Or paste the metadata XML instead.
* **PEM vs. metadata XML is more than a formatting choice.** A PEM updates only the signing certificate. Pasting metadata XML re-points ION at the whole document, which can also change sign-in endpoints and attribute mappings. For a routine certificate swap, prefer the PEM.
* **Paste only the certificate block.** If using PEM, include everything from `-----BEGIN CERTIFICATE-----` through `-----END CERTIFICATE-----` with no extra text above or below.

## Rotate the certificate

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Enterprise SSO** card, click **Rotate certificate**.
3. Paste the new PEM certificate or SAML metadata XML into the dialog, or use **Upload from file** to select it. ION confirms the format it detected below the input.
4. Have your IdP administrator activate the new signing key.
5. Click **Rotate**. ION immediately starts verifying logins with the new certificate and displays a SHA-256 fingerprint of the new certificate.

<Note>
  ION's fingerprint is SHA-256, but most IdP consoles (Okta, Microsoft Entra,
  ADFS) display a SHA-1 thumbprint, so the two won't match by eye even when
  everything is correct. To compare, generate the SHA-256 yourself: `openssl
      x509 -noout -fingerprint -sha256 -in cert.pem`.
</Note>

6. Ask someone (not yourself) to sign out and sign back in through SSO to verify the new certificate works.

## If sign-ins start failing

This is recoverable and does not affect anyone already signed in.

* **Most likely cause**: ION and your IdP are temporarily out of sync. One is using the new certificate and the other is still on the old one.
* **Fastest fix**: open **Rotate certificate** again and paste the previous certificate back. New sign-ins recover immediately. Then retry the rotation once both sides are ready to switch together.
* If logins still fail after both sides are confirmed on the new certificate, [contact support](https://support.firstresonance.io/) with the fingerprint ION displayed and the time of the change.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will this log everyone out?">
    No. The signing certificate is only checked when someone signs in fresh. Everyone with an active session keeps working uninterrupted.
  </Accordion>

  <Accordion title="Can I load the new certificate ahead of time?">
    Not without a brief interruption. Because ION holds only one certificate at a
    time, loading the new one before your IdP starts signing with it causes new
    sign-ins to fail until the IdP catches up. Switch both sides together instead.
  </Accordion>

  <Accordion title="What if I don't see the Rotate certificate button?">
    The action is restricted to administrators with SSO management permission. Ask
    an admin on your team, or [contact
    support](https://support.firstresonance.io/).
  </Accordion>

  <Accordion title="PEM or metadata XML: which should I use?">
    For a routine certificate swap, paste the PEM. It updates only the signing
    certificate and leaves the rest of your connection untouched. Use metadata XML
    only when you intend to refresh the whole connection (new endpoints or
    attribute mappings).
  </Accordion>

  <Accordion title="My IdP is rolling over and has two certificates. Which do I use?">
    Paste the certificate your IdP will sign with after the cutover, coordinated
    with the switch.
  </Accordion>

  <Accordion title="What exactly does this rotate?">
    This action updates only the IdP signing certificate ION uses to verify login tokens. It does not change ION's request-signing certificate or any assertion-encryption keys. If you need to rotate those, contact [support](https://support.firstresonance.io/).
  </Accordion>
</AccordionGroup>

## Provider-specific notes

<AccordionGroup>
  <Accordion title="Microsoft Entra ID (Azure AD), including GovCloud">
    Entra downloads its certificate as a binary `.cer` (DER) file. Convert it to PEM, or use the federation metadata. Entra auto-rolls its signing certificate and lists multiple certificates in its federation metadata during the overlap, so paste the one it will use after the switch. GovCloud tenants live under `login.microsoftonline.us`.
  </Accordion>

  <Accordion title="Okta">
    Generate the next certificate in Okta, then paste its signing certificate
    (PEM) or Okta's metadata URL/file. Okta metadata lists both encryption and
    signing certificates. ION automatically picks the signing one.
  </Accordion>

  <Accordion title="ADFS">
    ADFS's AutoCertificateRollover publishes a primary and secondary token-signing
    certificate, exported as binary `.cer` (DER). Convert to PEM and paste the one
    that will be primary after the rollover.
  </Accordion>

  <Accordion title="Google Workspace / other SAML providers">
    Download the SAML app's signing certificate as PEM and paste it. If your provider only offers metadata, paste the metadata XML.
  </Accordion>
</AccordionGroup>

## Related

* [Set up SSO](/administration/authentication-settings/sso/set-up-sso)
* [Disable SSO](/administration/authentication-settings/sso/disable-sso)


# Set up SSO
Source: https://docs.firstresonance.io/administration/authentication-settings/sso/set-up-sso

Connect your identity provider to ION so your team can sign in with their existing company credentials.

For how SSO fits into ION authentication, including how accounts are provisioned on first sign-in, see the [Overview](/administration/authentication-settings).

## Before you start

[Claim and verify your email domain](/administration/authentication-settings/manage-domains) before setting up SSO.

Adding SSO after you onboard many users means reconciling existing accounts with your identity provider.

<Warning>
  A misconfigured SSO connection can lock users out of production. If you have a sandbox tenant, validate the connection there before enabling it in production.
</Warning>

## Set up SSO

1. In ION, go to **Settings > Organization > Authentication**.
2. In the **Enterprise SSO** card, click **Configure SSO**, then click **Open SSO Setup Wizard** and follow the steps to connect your identity provider. The wizard walks you through selecting your provider, exchanging SAML or OIDC details, mapping user attributes, and enabling the connection.
3. When the wizard is complete, return to ION and click **Check Status**. Once your IdP connection is live, the card shows **SSO Active** with your provider and connection name.

You can hand the setup wizard link to whoever manages your IdP if you don't have access to configure it yourself.

<Note>
  The wizard shows you the values to enter into your identity provider and collects your provider's metadata or signing certificate directly. You don't need to send anything to First Resonance to complete setup. For more information, see Auth0's [self-service SSO documentation](https://auth0.com/docs/authenticate/enterprise-connections/self-service-SSO).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Check Status shows the connection is not active after completing the wizard">
    The wizard must fully complete and the connection must be enabled before ION can verify it. Return to the wizard and confirm the final step shows the connection as enabled, then try **Check Status** again.
  </Accordion>

  <Accordion title="Users get an error or are redirected back to the ION login page after attempting SSO">
    Confirm your email domain is claimed and verified in ION before enabling SSO. See [Manage domains](/administration/authentication-settings/manage-domains). Unverified domains won't route users to your IdP.
  </Accordion>

  <Accordion title="Attribute mapping errors or users are created without the correct name or email">
    Check the attribute mapping step in the wizard. ION expects the email attribute to be mapped correctly from your IdP. For SAML providers, the email attribute is typically `email` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Confirm with your IdP's documentation.
  </Accordion>

  <Accordion title="SSO was working and stopped after a certificate rotation">
    If your IdP uses SAML and rotated its signing certificate, ION needs to be updated with the new certificate. See [Rotate your SAML signing certificate](/administration/authentication-settings/sso/rotate-saml-certificate).
  </Accordion>
</AccordionGroup>

## Provider-specific notes

The wizard is the same for every provider and shows you the exact service-provider values to enter into your IdP. These notes cover what's specific to the most common providers.

<AccordionGroup>
  <Accordion title="Okta">
    Create a **SAML 2.0** app integration in Okta and paste in the **Single sign-on URL** and **Audience URI (SP Entity ID)** the wizard displays. They take the form `https://firstresonance.auth0.com/login/callback?connection=<connection_name>` and `urn:auth0:firstresonance:<connection_name>`, with the connection name filled in by the wizard. Okta sends the user's `email` in the SAML assertion by default. When you provide Okta's metadata, ION automatically picks the **signing** certificate if both signing and encryption certificates are listed. Background: [Auth0 community guide to Okta as the SAML IdP](https://community.auth0.com/t/saml-setup-okta-as-idp-and-auth0-as-sp/91164).
  </Accordion>

  <Accordion title="Microsoft Entra ID (Azure AD)">
    Register the application in the Microsoft Entra admin center using the **Reply URL (ACS)** the wizard displays (based on `https://firstresonance.auth0.com/login/callback`), then provide your application's **federation metadata** (URL or XML) back in the wizard. Confirm Entra releases the user's **email** claim. **GovCloud** tenants sign in under `login.microsoftonline.us`. Entra **auto-rolls** its signing certificate and lists multiple certificates during the overlap. This matters when you later [rotate the signing certificate](/administration/authentication-settings/sso/rotate-saml-certificate).
  </Accordion>

  <Accordion title="ADFS">
    Configure the relying party in ADFS following [Auth0's ADFS connection documentation](https://auth0.com/docs/connections/enterprise/adfs), using **Realm Identifier** `urn:auth0:firstresonance` and **Endpoint** `https://firstresonance.auth0.com/login/callback`. Then provide your ADFS **federation metadata URL** (for example, `https://adfs.yourcompany.com/FederationMetadata/2007-06/FederationMetadata.xml`) in the wizard.
  </Accordion>
</AccordionGroup>

## Related

* [Rotate your SAML signing certificate](/administration/authentication-settings/sso/rotate-saml-certificate)
* [Disable SSO](/administration/authentication-settings/sso/disable-sso)
* [Manage domains](/administration/authentication-settings/manage-domains)


# Custom attributes
Source: https://docs.firstresonance.io/administration/custom-attributes

Add org-defined metadata fields to ION records (procedures, runs, parts, issues, and more) from Settings.

Custom attributes let you capture additional metadata on ION records beyond the default fields. They are available for the following entity types:

| Entity          | Where in Settings                             |
| --------------- | --------------------------------------------- |
| Procedures      | **Settings > Production > Procedures**        |
| Standard steps  | **Settings > Production > Standard Steps**    |
| Runs            | **Settings > Production > Runs**              |
| Issues          | **Settings > Quality > Issues**               |
| Parts           | **Settings > Supply Chain > Parts**           |
| Purchases       | **Settings > Supply Chain > Purchases**       |
| Receipts        | **Settings > Supply Chain > Receipts**        |
| Suppliers       | **Settings > Supply Chain > Suppliers**       |
| Part kits       | **Settings > Supply Chain > Part Kits**       |
| Locations       | **Settings > Supply Chain > Locations**       |
| Parts Inventory | **Settings > Supply Chain > Parts Inventory** |
| Plans           | **Settings > Supply Chain > Plans**           |
| Further Actions | **Settings > Quality > Further Actions**      |

The **Purchases** page defines two separate attribute sets: **Purchase Order Attributes** apply to the order, and **Purchase Order Line Attributes** apply to each line on the order.

## Add a custom attribute

To add a custom attribute:

1. Go to the Settings page for the entity you want to extend (see table above).
2. In the **Attributes** section, enter a **Name** for the attribute.
3. Select a **Type** from the dropdown.
4. Click **Add**. The attribute is saved immediately.

### Attribute types

The **Type** dropdown lists these options. After you save the attribute, ION shows the type as a badge, which can use a different label than the dropdown option.

| Dropdown option    | Badge label  | Description                                                            |
| ------------------ | ------------ | ---------------------------------------------------------------------- |
| **String**         | String       | Free-text input.                                                       |
| **Number**         | Number       | Numeric value.                                                         |
| **Boolean**        | Boolean      | On or off toggle.                                                      |
| **Datetime**       | Date & Time  | Date and time picker.                                                  |
| **FileAttachment** | File         | File attachment.                                                       |
| **Select**         | Select       | Single-choice dropdown. You define the options after creation.         |
| **Multiselect**    | Multi-Select | Multiple-choice dropdown. You define the options after creation.       |
| **ION: Parts**     | ION: Parts   | Reference to a part record.                                            |
| **ION: Users**     | ION: Users   | Reference to a user.                                                   |
| **Rich Text**      | Rich Text    | Formatted text. Available only on entity types that support rich text. |

## Manage options for select and multi-select attributes

Select and multi-select attributes require you to define their options separately after creation. Options follow an archive-then-delete lifecycle: archiving takes an option out of circulation while leaving the records that already use it intact, and permanent deletion is only available once an option is archived.

To manage an attribute's options:

1. In the **Attributes** section, find the attribute and click the expand arrow next to it.
2. To add an option, type the option name in the input field and press **Enter** or click **Add**.
3. To archive an option, click the archive icon on the option.
4. To work with an option you already archived, expand **Archived**, which shows the archived count, and use one of the icons on the option:
   * The restore icon returns the option to the active list.
   * The delete icon removes the option from the attribute permanently.

Archived options stay out of the pick list on new entries, so nobody can select one again until you unarchive it. A record that already holds an archived option keeps that value.

<Frame>
  <img alt="Expanded Finish attribute of type Select showing an input reading Type option name and press Enter, an Add button, active options Anodized and Powder Coat each with an archive icon, and an ARCHIVED (1) list containing the struck-through option Bare with a restore icon and a delete icon" />
</Frame>

<Warning>
  Deleting an archived option can't be undone. ION blocks the deletion if any
  record still holds the option, so archive it instead when you need to retire an
  option that's in use.
</Warning>

## Edit a custom attribute

The name and type of a custom attribute can't be changed after creation. To rename an attribute or change its type, delete it and create a new one.

For **Select** and **Multi-Select** attributes, you can add and archive options at any time. For more information, see [Manage options for select and multi-select attributes](#manage-options-for-select-and-multi-select-attributes).

## Archive a custom attribute

Archiving an attribute hides it from data entry across ION: it stops appearing on create forms, table column pickers, and the panels that add an attribute to a record. Records that already carry a value for the attribute keep it, and you can still edit that value.

1. In the **Attributes** section, find the attribute you want to archive.
2. Click the archive icon at the end of the attribute row.

To bring an attribute back, expand **Archived** and click the restore icon on the attribute row.

## Delete a custom attribute

Delete is only available on an archived attribute, so archive it first.

To delete a custom attribute:

1. In the **Attributes** section, expand **Archived**.
2. Click the delete button on the attribute row.
3. In the **Delete Attribute** dialog, click **Delete**.

<Tip>
  If you accidentally deleted a custom attribute that other records still
  used, create a new attribute with the exact same name and type. ION will
  restore the attribute and its values on each record.
</Tip>

## Archived values on records

When a record holds a value whose option has since been archived, the value pickers mark it with an **Archived** badge so you can tell it apart from an active option. Because an archived option can't be selected again, ION asks you to confirm in the **Deselect archived option?** dialog before it removes the value.

## How attribute values copy between records

When you duplicate a record, ION carries its custom attribute values to the new record in these cases:

* Splitting an inventory line copies the parent's attribute values to the new line.
* Copying a purchase order copies attribute values on both the order and its lines.
* Creating a new part revision copies the source revision's attribute values.

Creating a brand-new part does not copy attribute values, since there is no source record to copy from.


# Customer S3 Delivery Setup
Source: https://docs.firstresonance.io/administration/customer-s3-delivery-setup

Set up an S3 bucket in your AWS account to receive automated data snapshots from ION.

## Overview

ION delivers automated data snapshots directly to an S3 bucket in your AWS account as `.tar` archives, once you set up the bucket and grant First Resonance access to write to it.

## What you need

* An S3 bucket in your AWS account
* An IAM role that First Resonance assumes to write to your bucket
* An external ID (provided by First Resonance) for secure role assumption

Once configured, snapshots are delivered to:

```
s3://<your-bucket>/<tenant-schema>/<job-id>/
```

## Set up delivery

<Steps>
  <Step title="Create an S3 bucket">
    Create a bucket in your preferred AWS region, either through the AWS console or using the CLI:

    ```bash theme={null}
    aws s3 mb s3://<your-bucket> --region <your-region>
    ```

    We recommend enabling:

    * **Versioning**: protects against accidental overwrites.
    * **Server-side encryption** (SSE-S3 or SSE-KMS): encrypts data at rest.
  </Step>

  <Step title="Create an IAM role">
    Create an IAM role that First Resonance assumes to deliver snapshots to your bucket.

    ### Trust policy

    The trust policy allows First Resonance to assume the role using an external ID. Replace `<fr-account-id>` with the First Resonance AWS account ID for your environment (provided by your account team), and `<external-id>` with the external ID we provide.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::<fr-account-id>:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<external-id>"
            }
          }
        }
      ]
    }
    ```

    The external ID prevents the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) and ensures only First Resonance can assume this role.

    ### Permission policy

    Attach the following policy to the role. Replace `<your-bucket>` with your bucket name.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "SnapshotDeliveryBucketAccess",
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:AbortMultipartUpload",
            "s3:ListBucketMultipartUploads",
            "s3:ListMultipartUploadParts",
            "s3:ListBucket"
          ],
          "Resource": [
            "arn:aws:s3:::<your-bucket>",
            "arn:aws:s3:::<your-bucket>/*"
          ]
        }
      ]
    }
    ```

    <Info>
      `s3:PutObject` handles the core upload. The additional permissions allow First Resonance to clean up incomplete uploads and list bucket contents for verification.
    </Info>
  </Step>

  <Step title="Send your configuration">
    Provide the following details to your account team:

    | Field         | Description                                  |
    | ------------- | -------------------------------------------- |
    | Bucket name   | Your S3 bucket name.                         |
    | Bucket region | The AWS region where your bucket is located. |
    | Role ARN      | The full ARN of the IAM role you created.    |

    First Resonance provides the external ID and configures your snapshot schedule.
  </Step>

  <Step title="Validation">
    After we receive your configuration, our system validates access by:

    1. Assuming the IAM role with the external ID.
    2. Verifying the bucket exists and is accessible.
    3. Writing and deleting a small test object.

    If validation fails, we reach out with the specific error so you can adjust permissions.
  </Step>
</Steps>

## What gets delivered

Each snapshot creates files under your bucket with this structure:

```
s3://<your-bucket>/
  └── <tenant-schema>/
      └── <job-id>/
          ├── snapshot_tables_<job-id>.tar
          └── snapshot_attachments_<job-id>.tar
```

For large snapshots that are split into multiple files, each file includes a part number (for example, `snapshot_tables_part1_<job-id>.tar` and `snapshot_tables_part2_<job-id>.tar`).

* **snapshot\_tables**: all database tables as compressed CSV files, bundled into a tar archive.
* **snapshot\_attachments**: file attachments bundled into a tar archive.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Role assumption fails (AccessDenied)">
    **Cause:** Trust policy does not allow the First Resonance account.

    **Fix:** Verify the `Principal` in the trust policy matches the account ID provided by your account team.
  </Accordion>

  <Accordion title="Role assumption fails with correct principal">
    **Cause:** External ID mismatch.

    **Fix:** Verify the `sts:ExternalId` condition matches the value provided by First Resonance.
  </Accordion>

  <Accordion title="Access denied to bucket">
    **Cause:** Missing or incorrect permission policy.

    **Fix:** Verify the permission policy is attached to the role and the bucket name matches.
  </Accordion>

  <Accordion title="Test write fails (AccessDenied)">
    **Cause:** Role lacks `s3:PutObject` permission.

    **Fix:** Check the permission policy includes `PutObject` on the bucket resource.
  </Accordion>

  <Accordion title="Bucket does not exist">
    **Cause:** Wrong bucket name or region.

    **Fix:** Verify the bucket name and that it exists in the expected region.
  </Accordion>
</AccordionGroup>

## Security notes

* First Resonance uses **STS AssumeRole** with short-lived credentials that are automatically refreshed during long-running snapshots. No credentials are stored.
* The **external ID** ensures only First Resonance can assume the role.
* First Resonance only writes to your tenant's prefix and does not read or modify other data in your bucket.
* All data is transmitted over HTTPS (TLS).

## Related pages

For an overview of data snapshots, see [Data Snapshots](/administration/data-snapshots).


# Data Snapshots
Source: https://docs.firstresonance.io/administration/data-snapshots

Create a full snapshot of your organization's data and attachments from ION for backup, compliance, or analytics purposes.

## Overview

Data snapshots let you create a complete copy of your organization's data from ION. Snapshots are useful for backups, compliance requirements, data warehousing, or feeding external analytics tools. By default, a snapshot includes both:

* **Tables**: all of your organization's structured data, such as parts, inventory, BOMs, runs, and issues.
* **Attachments**: all documents, images, and other files uploaded across ION, including those attached to runs, procedures, and issues.

If needed, you can choose to snapshot only tables or only attachments.

<Note>
  Data snapshots are available depending on your organization's plan and settings. To find out whether snapshots are enabled for your organization, contact your account team.
</Note>

## How data snapshots work

Data snapshots run automatically on a scheduled cadence configured for your organization. To get started, reach out to your account team to set up your snapshot schedule and delivery destination.

Once a snapshot completes, you can download the resulting files from the **data snapshots page**. You can also track the status of all snapshots from the snapshot history table.

<Warning>
  The data snapshots page is only accessible to organization admins for security purposes. All snapshot data is encrypted at rest and in transit using TLS.
</Warning>

## What you receive

Snapshots are delivered as `.tar` archives. A tables snapshot contains one compressed file per table (`.csv.gz` or `.jsonl.gz`), and an attachments snapshot contains all uploaded files.

For large snapshots, ION automatically splits the output into multiple `.tar` files labeled with a part number, such as `snapshot_tables_part1_2026-03-31-143022.tar` and `snapshot_tables_part2_2026-03-31-143022.tar`.

## Delivery destinations

By default, snapshots are stored in ION and made available for download through the UI. Snapshots stored in ION are retained for **30 days**, after which they are automatically deleted.

<Tip>
  You can set up [Customer S3 delivery](/administration/customer-s3-delivery-setup) to have snapshots delivered directly to your own AWS S3 bucket. Delivering to your own bucket gives you ownership of the snapshot files and lets you apply your own retention and access policies.
</Tip>

## Scheduling

Snapshots can be scheduled to run weekly or monthly. Your account team configures the cadence during onboarding.

## Onboarding

To get started with data snapshots:

1. **Contact your account team.** Let them know you want to set up data snapshots and whether you need tables, attachments, or both.
2. **Choose a delivery destination.** Snapshots can be downloaded from ION directly, or delivered to your own S3 bucket.
3. **Set up customer-managed S3 delivery, if applicable.** Follow the [Customer S3 delivery setup](/administration/customer-s3-delivery-setup) guide to create your bucket, configure an IAM role, and share your configuration for validation.
4. **Go live.** Once configured, snapshots run on your chosen schedule and are delivered automatically.

## Snapshot history

The data snapshots page shows the status of all snapshots for your organization:

| Status      | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| Pending     | The snapshot is waiting to be processed.                                         |
| In Progress | The snapshot is currently running.                                               |
| Completed   | The snapshot finished successfully and files are available for download.         |
| Failed      | The snapshot encountered an error. Check the error details for more information. |

<Frame>
  <img alt="Data snapshots page with the download panel for a completed snapshot." />
</Frame>


# Export data
Source: https://docs.firstresonance.io/administration/export-data

Export ION data to CSV or Excel on demand or on a schedule, track each export job, and download the finished file.

The Exports page delivers a data view from ION as a CSV or Excel file, either once on demand or on a recurring schedule. Each run of an export is a job whose status and output you can check from the export's detail page. ION can email the file to the recipients you set, or download it straight to your browser.

## Request an export

1. In ION, go to **OS > Exports**.
2. Click **New Export**.
3. In the **Create export** dialog, fill in:
   * **Name**: what to call this export. This field is required.
   * **View name**: the data view to export. Start typing to search your available views, listed under **Available views**, or enter any view name you have access to. This field is required.
   * **Format**: **CSV** or **Excel**.
   * **Delivery**: how you get the file, **Email** or **Download**. This choice is available on the **Run once** tab; scheduled exports always deliver by email.
   * **Delivery recipients**: the email addresses that receive the file. At least one is required. This field appears only for **Email** delivery.
4. Choose when it runs:
   * On the **Run once** tab, click **Run now** to run the export immediately. With **Download** delivery, ION prepares the file and saves it to your browser once it's ready. With **Email** delivery, ION emails the recipients when the file is ready.
   * On the **Schedule** tab, enter a **Cron expression** and pick a **Timezone**, then click **Save schedule** to run it on a recurring cadence. ION emails the recipients each time the file is ready.

## Manage exports

The Exports table lists each export with its **Name**, **View**, **Schedule**, and **Last updated**. Use the **Enabled** toggle to pause or resume a scheduled export. The actions menu on each row offers **Run now**, **View details**, **Enable** or **Disable**, and **Delete**.

## Check job status and download the file

1. On the **Exports** page, open the actions menu on an export and click **View details**, or click the export's name.
2. The detail page shows the export's **View**, **Format**, **Schedule**, **Recipients**, and whether it is **Enabled**, with a **Run now** button to trigger it again.
3. Under **Recent jobs**, each row is one run:
   * **Status**: **Pending**, **In progress**, **Completed**, or **Failed**. A failed job shows its error message under **Details**.
   * **Trigger**, **Started**, and **Completed**: how and when the job ran.
   * **Rows** and **Size**: what the job produced.
4. On a completed job, click **Download** to save the file.

## Related

* [Data snapshots](/administration/data-snapshots)
* [Export run data](/build-hardware/runs-and-execution/export-runs-data)


# Overview
Source: https://docs.firstresonance.io/administration/ion-importers/index

Use CSV imports to bulk-create or update records in ION.

ION's import feature lets you upload a CSV file to create or update records in bulk. Instead of entering data one row at a time through the UI, you can prepare a spreadsheet offline and import it all at once.

## How imports work

To start an import, navigate to **Imports** in the sidebar, then pick an import type from the **New Import** tab. The importer cards are grouped by category (**Production**, **Supply Chain**, **Quality**, and **OS**) to match where each record type lives in ION. Imports are processed **asynchronously**, so you can navigate away and continue working while the import runs. You receive a notification when the import completes or fails.

Clicking **Start Import** on any card opens the import wizard, which walks you through **Upload**, **Match**, and **Review** steps.

On the **Upload** step you can download the CSV template, toggle the importer's options (the option set varies by importer), or choose **Enter data manually** to type rows into the grid instead of uploading a file.

The editable preview covers files up to 5,000 rows. Upload a larger file and ION says so, skips the **Match** and **Review** steps, and offers **Import file as-is**, which sends the file unedited. A file above 1,000,000 rows is rejected outright.

The **Match** step maps your file's columns to ION fields. ION auto-maps each column to the field whose name it matches, and you can adjust any mapping in that column's **Maps To** dropdown: pick a different field, keep the column as a custom attribute, or skip the column so it isn't imported. Required fields must stay mapped. When you enter data manually instead of uploading, this step becomes a column picker where you choose which fields to include.

On the **Review** step, ION shows your rows in an editable grid. Edit any cell inline, then use the validate control to check the data. ION flags each failing cell with its error and highlights the affected rows, so you can fix them and revalidate before importing. The control reads **Validate** before the first check and **Revalidate** after, and editing a validated file prompts you to revalidate before you can import.

<Frame>
  <img alt="Import wizard Review step showing an editable grid with three rows flagged Name is required and a banner reading 3 issues in rows 1, 2, 3" />
</Frame>

Imports are **all-or-nothing**. If any row fails validation, no rows are written and you receive an error report. You never end up with a partially imported file.

You can track the status of all imports from the **Import History** tab. Expand any failed job to see its per-row error messages, or click **Download** to pull the full error CSV.

## Video walkthrough

The end-to-end import flow is the same for every importer: pick a type, download the template, upload your CSV, run validation, then commit. The walkthrough below uses the mBOM importer as an example.

<iframe />

## Required and optional columns

Each import type has its own set of columns. Some columns are required and must be present in every row, while others are optional. Optional columns that you omit from your CSV are skipped entirely, so ION does not touch those fields on the imported records. Only when an optional column is included in the CSV but left blank for a given row does ION apply a default value based on the field type (see below). If a required column is missing or empty, the import fails with a validation error.

## How empty CSV cells are handled

When an optional column is present in your CSV but a row leaves it blank, the cell defaults to a falsy or zero-equivalent value (not null). This only applies to columns that are actually in the file. Omitting the column entirely leaves the field untouched.

### Lookup and control columns are exempt

A handful of columns are exempt from the falsy-default rule, either because they're used to look up an existing record or control importer behavior, or because `0` isn't a falsy value for that field's type. For these, an empty cell means "not provided":

| Column                                | Importer                                                                                                                                                                       | Empty cell means                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `id`                                  | [Part Inventory](/administration/ion-importers/part-inventory), [Tool Inventory](/administration/ion-importers/tool-inventory), [Issues](/administration/ion-importers/issues) | Create a new record (no update lookup)                                                  |
| `original_name`                       | [Locations](/administration/ion-importers/location-imports)                                                                                                                    | No rename                                                                               |
| `original_po_number`                  | [Purchase Orders](/administration/ion-importers/purchase-orders)                                                                                                               | No rename                                                                               |
| `latitude`, `longitude`               | [Locations](/administration/ion-importers/location-imports)                                                                                                                    | Unset. `0` is not a falsy value for a coordinate                                        |
| `can_hold_inventory`, `pickable`      | [Locations](/administration/ion-importers/location-imports)                                                                                                                    | Keep the field's default of `true`, rather than flipping to `false` like other booleans |
| `last_maintained_date`, `uri`         | [Tool Inventory](/administration/ion-importers/tool-inventory)                                                                                                                 | Unset. No date is written and no URI is stored                                          |
| `due_date`, `quantity`, `assigned_to` | [Runs](/administration/ion-importers/runs)                                                                                                                                     | Unset. No due date, quantity, or assignee is written                                    |

Each importer's column table calls out which fields behave this way.

| Field Type | Empty Cell Value | Examples                                    |
| ---------- | ---------------- | ------------------------------------------- |
| Text       | `""`             | `description`, `address`                    |
| Numeric    | `0`              | `quantity`                                  |
| Boolean    | `false`          | `made_on_assembly`, `available`, `archived` |

<Info>
  If you leave a boolean column blank, ION treats it as **false** (unchecked). To set a field to true, you must explicitly write a truthy value.
</Info>

### Accepted boolean values

Boolean fields accept any of the following (case-insensitive):

| Truthy | Falsy   |
| ------ | ------- |
| `true` | `false` |
| `yes`  | `no`    |
| `1`    | `0`     |

## Errors

When validation fails, ION reports up to **5,000 errors** with the specific row number and a description of the problem. Row numbers correspond to the CSV file where row 1 is the header and row 2 is the first data row.

<Info>
  If your file contains more than 5,000 errors, ION stops scanning at that point. Fix the reported batch and re-upload to see the rest.
</Info>

<Tip>
  Review your column headers and values before uploading, and pay special attention to boolean columns: blank cells default to `false`, so any field you intend to be `true` must be set explicitly. Because imports are all-or-nothing, resolve every error the **Review** step flags and revalidate until the file passes before you re-upload. Run your import in a staging environment and verify the results before importing into production.
</Tip>


# Issue imports
Source: https://docs.firstresonance.io/administration/ion-importers/issues

Create or update issues from a CSV file, including dispositions, assignees, and custom attributes.

## Overview

The Issues importer bulk-creates or updates issues. The distinction is row-by-row:

* Rows **without** an `id` value **create** a new issue. `title` is required, and the issue starts at status `pending` unless the row sets an explicit `status`.
* Rows **with** an `id` value **update** the matching issue.

## Columns

| Column                   | Required         | Description                                                                                                                                      |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                     | No               | Issue ID. Provide to update an existing issue; omit to create a new one. **Lookup column**: an empty cell is treated as "not provided," not `0`. |
| `title`                  | Yes (for create) | Issue title.                                                                                                                                     |
| `status`                 | No               | One of `pending`, `in_progress`, `in_review`, `resolved`. Matched case-insensitively. New issues default to `pending`.                           |
| `cause_condition`        | No               | Plain-text cause description. See [Rich-text fields](#rich-text-fields).                                                                         |
| `disposition`            | No               | Plain-text disposition description. See [Rich-text fields](#rich-text-fields).                                                                   |
| `expected_condition`     | No               | Plain-text expected-condition description. See [Rich-text fields](#rich-text-fields).                                                            |
| `issue_disposition_type` | No               | Title of a disposition type configured in your organization. Matched case-insensitively.                                                         |
| `assigned_to`            | No               | Email address of the user to assign. Matched case-insensitively against existing users.                                                          |

## Rich-text fields

`cause_condition`, `disposition`, and `expected_condition` are rich-text fields in the ION UI. The importer accepts plain text and converts it into a single paragraph, which you can elaborate on later in the UI. On update rows, an empty cell leaves the existing content untouched.

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the issue. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Location imports
Source: https://docs.firstresonance.io/administration/ion-importers/location-imports

Import factory locations from a CSV file, including nested hierarchies, supervisors, and custom attributes.

## Overview

Location imports let you bulk-create or update factory locations. Column headers are matched case-insensitively and extra whitespace is trimmed.

## Columns

| Column                              | Required | Description                                                                                                                                                           |
| ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                              | Yes      | Location name. Must be unique within the CSV and cannot exceed 128 characters.                                                                                        |
| `original_name`                     | No       | If renaming an existing location, this is the current name in ION. Max 128 characters. **Lookup column**: an empty cell means "no rename," not `""`.                  |
| `parent_name`                       | No       | Name of the parent location. Used to build nested hierarchies.                                                                                                        |
| `description`                       | No       | Description of the location. Max 512 characters.                                                                                                                      |
| `address`                           | No       | Physical address. Max 128 characters.                                                                                                                                 |
| `available`                         | No       | Whether the location is available. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                                      |
| `archived`                          | No       | Whether the location is archived. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                                       |
| `exclude_from_merge_part_inventory` | No       | Exclude this location from merged part inventory views. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                 |
| `can_hold_inventory`                | No       | Whether the location is a valid destination for inventory. Boolean field. **Default-true column**: an empty cell keeps the current value rather than setting `false`. |
| `pickable`                          | No       | Whether kitting can pull from the location. Boolean field. **Default-true column**: an empty cell keeps the current value rather than setting `false`.                |
| `latitude`                          | No       | Latitude coordinate. Must be between -90 and 90. Empty cells are treated as unset (not `0`).                                                                          |
| `longitude`                         | No       | Longitude coordinate. Must be between -180 and 180. Empty cells are treated as unset (not `0`).                                                                       |
| `type`                              | No       | Location type. One of `workcenter`, `tote`, `warehouse`, `rack`, or `shelf`.                                                                                          |
| `supervisor`                        | No       | Email address of the supervisor. Must match an existing user in ION.                                                                                                  |

## Custom attributes

Any columns beyond the standard set are matched against your organization's custom location attributes. If a column header does not match a standard column or a configured custom attribute, the import will fail with a validation error.

## Parent-child hierarchies

You can define nested locations by specifying a `parent_name` for each row. ION resolves parents automatically, including parents that are created within the same import. Parents are always processed before their children regardless of row order.

Circular parent-child relationships are detected and rejected. An example is Location A being the parent of Location B, which is in turn the parent of Location A.

<Note>
  **Can Hold Inventory** and **Pickable** are advisory until an admin turns on the matching enforcement setting in **Settings > Supply Chain > Locations**. With **Enforce can hold inventory** on, a row that turns off `can_hold_inventory` for a location that still holds inventory is rejected.
</Note>

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).

For managing locations through the UI, see [Locations and work centers](/build-hardware/locations-and-work-centers).


# mBOM imports
Source: https://docs.firstresonance.io/administration/ion-importers/mbom-imports

Import multi-level bills of materials from a CSV file, using Depth or Level notation to define part hierarchies.

## Overview

mBOM imports let you define multi-level part structures in a single CSV, from top-level assemblies down to individual components. ION supports two ways to describe how parts are nested: **Depth** notation and **Level** notation. ION automatically detects which one you are using based on the first column header in your CSV.

## Import options

| Option                    | Default | Description                                                                                                                                                                                      |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Auto-create missing parts | On      | When enabled, any parts in the import that do not already exist in the Parts Library are created automatically. When disabled, referencing a part that does not exist causes a validation error. |
| Always create new version | On      | When enabled, a new mBOM version is always created. When disabled, the latest version is updated in place if it is a draft; otherwise a new version is created.                                  |

## Columns

| Column                  | Required | Description                                                                                                                                                   |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `depth` or `level`      | Yes      | The first column in your CSV. Determines how the part hierarchy is structured. See sections below.                                                            |
| `part_number`           | Yes      | The part number for this row.                                                                                                                                 |
| `revision`              | Yes      | The part revision.                                                                                                                                            |
| `quantity`              | Yes      | How many of this part are needed in the parent assembly.                                                                                                      |
| `substitutes`           | No       | Alternative parts, formatted as `part_number[revision];part_number[revision]`. Example: `BOLT-300-ALT[A];BOLT-300-METRIC[B]`.                                 |
| `made_on_assembly`      | No       | Whether this part is fabricated as part of the parent assembly. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). |
| `reference_designators` | No       | Reference designator strings for the component. For multiple designators, separate each with a semicolon. Example: `J1;J2;J3`.                                |

<Info>
  Ensure part numbers and revisions match existing records exactly. Part matching is case-insensitive.
</Info>

## Depth notation

Depth notation describes your BOM structure by indenting parts one level at a time, similar to how you might indent items in an outline. The top-level assembly is depth **1**, its direct components are depth **2**, their sub-components are depth **3**, and so on.

To move back up the tree and start a new branch, return to a lower depth number. Rows must be listed in the order they appear in the assembly. Each component must come after the assembly it belongs to.

**Example:** An assembly (`ASSEMBLY-100`) contains a bracket and a panel. The bracket itself requires four bolts.

| depth | part\_number | revision | quantity |
| ----- | ------------ | -------- | -------- |
| 1     | ASSEMBLY-100 | A        | 1        |
| 2     | BRACKET-200  | B        | 2        |
| 3     | BOLT-300     | A        | 4        |
| 2     | PANEL-400    | A        | 1        |

<Warning>
  You cannot skip depth levels. For example, jumping from depth 1 directly to depth 3 is not allowed. Each component must be listed directly under its parent assembly.
</Warning>

## Level notation

Level notation uses a numbering scheme, such as `1`, `1.1`, and `1.1.1`, to explicitly identify where each part sits in the assembly tree. This is similar to how work breakdown structures or section numbering works. The number itself tells you the full path from the top-level assembly down to the component.

Unlike Depth notation, **rows can appear in any order** because the level value fully defines each part's position in the hierarchy. ION sorts and organizes the structure for you.

**Example:** The same assembly as above, with rows intentionally listed out of order to show that ordering does not matter.

| level | part\_number | revision | quantity |
| ----- | ------------ | -------- | -------- |
| 1     | ASSEMBLY-100 | A        | 1        |
| 1.2   | PANEL-400    | A        | 1        |
| 1.1   | BRACKET-200  | B        | 2        |
| 1.1.1 | BOLT-300     | A        | 4        |

Here, `1.1` (BRACKET-200) and `1.2` (PANEL-400) are both direct components of `1` (ASSEMBLY-100), and `1.1.1` (BOLT-300) is a sub-component of the bracket, regardless of the row order in the CSV.

<Warning>
  Every parent level must exist somewhere in the file. For example, you cannot define `1.1.1` without also having a `1.1` row. However, the rows do not need to be in any particular order.
</Warning>

## Cycle detection

ION automatically detects circular references in your mBOM. If assembly A contains part B and part B also contains assembly A (directly or through any chain of intermediate parts), the import fails with a validation error identifying the cycle. This check also applies to substitute parts.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Part inventory imports
Source: https://docs.firstresonance.io/administration/ion-importers/part-inventory

Create or update part inventory records from a CSV file.

## Overview

The Part Inventory importer creates new inventory or updates existing inventory from a single CSV. The distinction is row-by-row:

* Rows **without** an `id` value **create** new inventory. `part_number` is required.
* Rows **with** an `id` value **update** the matching inventory record. `part_number` and `revision` are ignored on update.

Creates run through the same path used by the UI, so aBOM creation, serial autogeneration, and tracking-type validation all apply. Updates run through the matching update path, so cascade behavior such as location propagation and quantity validation is preserved.

## Columns

| Column                | Required         | Description                                                                                                                                                                             |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | No               | Inventory ID. Provide to update an existing record; omit (or leave blank for the row) to create new inventory. **Lookup column**: an empty cell is treated as "not provided," not `0`.  |
| `part_number`         | Yes (for create) | Part number for new inventory. Ignored on update.                                                                                                                                       |
| `revision`            | No               | Part revision. Combined with `part_number` to look up the part; if omitted, the latest revision is used.                                                                                |
| `serial_number`       | No               | Serial number.                                                                                                                                                                          |
| `lot_number`          | No               | Lot number.                                                                                                                                                                             |
| `quantity`            | No               | Quantity. Must be non-negative. Empty cells become `0`.                                                                                                                                 |
| `quantity_scrapped`   | No               | Scrapped quantity. Must be non-negative. Empty cells become `0`.                                                                                                                        |
| `location`            | No               | Location name. Must match an existing location in ION.                                                                                                                                  |
| `supplier`            | No               | Supplier name. Must match an existing supplier in ION.                                                                                                                                  |
| `unit_of_measure`     | No               | Unit of measure name. Must match an existing unit in ION.                                                                                                                               |
| `intent_option`       | No               | Intent option value. Must match a configured intent option.                                                                                                                             |
| `autogenerate_serial` | No               | When `true` on a create row, ION generates a serial number. Cannot be set on update rows. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). |
| `autogenerate_lot`    | No               | When `true` on a create row, ION generates a lot number. Cannot be set on update rows. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).    |

<Info>
  Name-valued fields (`location`, `supplier`, `unit_of_measure`, `intent_option`) are resolved case-insensitively against existing records. An unrecognized name produces a row-level error.
</Info>

<Warning>
  `autogenerate_serial` and `autogenerate_lot` only apply on create rows. Setting either to `true` on a row that includes an `id` is rejected. Remove the `id` or the flag to fix the row.
</Warning>

## Custom attributes

Any column not listed above is treated as a custom attribute on the part inventory. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Part-procedure relation imports
Source: https://docs.firstresonance.io/administration/ion-importers/part-procedure-relations

Link parts to procedures in bulk from a CSV file.

## Overview

The Part-Procedure Relations importer links parts to procedures, one CSV row per `(part, procedure)` pair. The part is identified by `part_number` + `revision`, the procedure by `procedure_title` + `procedure_version`, and the only data field is the `required` flag.

Re-imports are idempotent: if the link already exists, its `required` flag is updated to match the CSV; otherwise a new link is created.

## Columns

| Column              | Required | Description                                                                                                                                                        |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `part_number`       | Yes      | Part number. Matched case-insensitively.                                                                                                                           |
| `revision`          | No       | Part revision. If omitted and the part has exactly one revision, that revision is used; multiple revisions produce an ambiguity error asking you to specify one.   |
| `procedure_title`   | Yes      | Title of the procedure.                                                                                                                                            |
| `procedure_version` | Yes      | Procedure version. Must be a positive integer.                                                                                                                     |
| `required`          | No       | Whether the procedure is required for the part. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). Defaults to `false`. |

<Warning>
  Each `(part, procedure)` pair can appear only once per file. Duplicate rows are rejected.

  Procedure titles aren't globally unique, so a `(procedure_title, procedure_version)` pair that matches more than one procedure produces an ambiguity error rather than guessing.
</Warning>

<Info>
  This importer does not support custom attributes. Any column outside the list above causes a validation error.
</Info>

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Parts imports
Source: https://docs.firstresonance.io/administration/ion-importers/parts

Import parts from a CSV file, including revisions, supplier parts, quality clauses, and custom attributes.

## Overview

The Parts importer lets you bulk-create or revise parts in a single CSV. It supports the same revision behavior as the UI: rows with an explicit revision create or update that exact `(part_number, revision)`, while rows that omit revision either initialize a new part at the org's default revision scheme or auto-revise an existing part using the latest-revision flow (carrying over the source part's mBOM and extensible attributes).

## Columns

| Column                     | Required | Description                                                                                                                              |
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `part_number`              | Yes      | The part number.                                                                                                                         |
| `revision`                 | No       | The part revision. Omit to let ION assign the next revision automatically (or the scheme's initial value if the part is new).            |
| `revision_scheme`          | No       | Name of the revision scheme to use when creating a brand-new part. Defaults to the org's default scheme.                                 |
| `description`              | No       | Free-text description.                                                                                                                   |
| `status`                   | No       | Part status. One of `released` or `archived`. Matched case-insensitively.                                                                |
| `purchase_type`            | No       | Purchase type. One of `receivable_inventory`, `receivable_non_inventory`, or `non_receivable_non_inventory`. Matched case-insensitively. |
| `tracking_type`            | No       | Tracking type. One of `serial` or `lot`, matched case-insensitively. Leave the cell blank for an untracked part; `none` is rejected.     |
| `sourcing_strategy`        | No       | Sourcing strategy. One of `make`, `buy`, or `dual_source`. Matched case-insensitively.                                                   |
| `cost`                     | No       | Default unit cost. Empty cells become `0`.                                                                                               |
| `lead_time`                | No       | Lead time as a duration. See [Duration format](#duration-format).                                                                        |
| `reorder_minimum_quantity` | No       | Reorder minimum. Must be non-negative. Empty cells become `0`.                                                                           |
| `reorder_maximum_quantity` | No       | Reorder maximum. Must be non-negative. Empty cells become `0`.                                                                           |
| `export_controlled`        | No       | Whether the part is export controlled. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).     |
| `unit_of_measure`          | No       | Unit of measure name, such as `each` or `kg`. Must match an existing unit in ION.                                                        |
| `quality_clauses`          | No       | Semicolon-delimited list of quality clause reference names to attach to the part.                                                        |
| `supplier_parts`           | No       | Semicolon-delimited list of supplier-part records. See [Supplier parts](#supplier-parts) below.                                          |

<Info>
  Part matching is case-insensitive. Enum fields (`status`, `purchase_type`, `tracking_type`, `sourcing_strategy`) only accept the values listed above. An invalid value produces a row-level error listing the allowed options.

  A blank enum cell is not the same as leaving the column out. Omit the column and the field is untouched. Include the column and leave a cell blank, and ION clears the field, which succeeds for `tracking_type` and `sourcing_strategy` (making the part untracked, or clearing its strategy) and fails for `status` and `purchase_type`, which can't be empty.
</Info>

## Revisions

The Parts importer mirrors the UI's revision flow:

* **Row with an explicit revision**: looks up `(part_number, revision)`. If it exists, the row updates that part; otherwise it creates a new part at that exact revision.
* **Row without a revision, no existing part with that `part_number`**: ION assigns the initial revision from the configured `revision_scheme` (or the org's default scheme, typically `"A"` or `"1"`).
* **Row without a revision, existing part with that `part_number`**: ION computes the next revision from the latest existing revision and creates a revised part. The new part inherits the mBOM and extensible attributes of the source part.

<Warning>
  You cannot have two rows that both omit `revision` for the same `part_number`. ION cannot disambiguate which one should auto-bump. Specify revisions explicitly to fix the conflict.

  Likewise, an explicit-revision row that collides with an auto-bumped revision from another row is rejected as a duplicate. This happens when one row sets `revision = B` and another auto-bumps to `B`.
</Warning>

## Duration format

The `lead_time` column accepts a duration written in days, hours, and minutes. Use the units `d`, `h`, and `m`, in that order, with optional spaces between terms. Each unit is optional. The value is rounded down to the nearest minute. A plain number with no unit is read as a number of seconds.

Valid values include:

| Value     | Meaning                |
| --------- | ---------------------- |
| `11d`     | 11 days                |
| `1d 2h`   | 1 day, 2 hours         |
| `10d 21m` | 10 days, 21 minutes    |
| `45m`     | 45 minutes             |
| `3600`    | 3,600 seconds (1 hour) |

The **Review** step flags a value that uses any other unit (such as weeks or seconds), lists the units out of order, or is otherwise unparseable.

## Supplier parts

The `supplier_parts` column attaches one or more SupplierParts to the part. Use semicolons (`;`) to separate records and pipes (`|`) to separate fields within a record:

```
supplier_name|supplier_part_number|cost|conversion_factor;supplier_name|...
```

| Field                  | Required | Notes                                        |
| ---------------------- | -------- | -------------------------------------------- |
| `supplier_name`        | Yes      | Must match an existing supplier in ION.      |
| `supplier_part_number` | Yes      | The supplier's part number for this part.    |
| `cost`                 | No       | Falls back to the Part's `cost` if omitted.  |
| `conversion_factor`    | No       | Defaults to `1.0`. Must be greater than `0`. |

Example: `Acme|ACME-WID-001|4.25|1;Globex|GLX-W1`

If a SupplierParts row already exists for the `(part, supplier, supplier_part_number)` combination, the importer updates its `cost` and `conversion_factor` in place. Otherwise it inserts a new row.

## Quality clauses

The `quality_clauses` column accepts a semicolon-delimited list of quality clause `reference_name` values. Each must match an existing Requirement with `requirement_type = QUALITY_CLAUSE`. The importer skips associations that already exist, so re-imports are idempotent.

Example: `QC-001;QC-002`

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the part. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Plan input imports
Source: https://docs.firstresonance.io/administration/ion-importers/plan-inputs

Bulk-add inputs to existing draft plans from a CSV file.

## Overview

The Plan Inputs importer adds inputs to **existing draft plans**, one CSV row per input, with the parent plan identified by `plan_id`. A single file can target multiple plans.

This importer only creates plan inputs. It never modifies the parent plan itself, and because a plan can legitimately hold multiple inputs for the same part, per-row updates are not supported. To rebuild a plan's inputs from scratch, enable the **Replace existing inputs** option in the import dialog. ION then removes the plan's current inputs and recreates them from the CSV.

```
plan_id | part_number | revision | quantity | due_date   | serial_number
42      | WIDGET-A    | A        | 10       | 2026-05-01 |
42      | WIDGET-B    | A        |  5       | 2026-05-01 |
42      | WIDGET-C    | B        |  1       | 2026-05-01 | SN-12345
```

## Import options

| Option                  | Default | Description                                                                                                                                              |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Replace existing inputs | Off     | When enabled, the targeted plans' existing inputs are removed and recreated from the CSV. When disabled, imported inputs are added to the existing ones. |

## Columns

| Column                   | Required | Description                                                                                                                                                      |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plan_id`                | Yes      | ID of the parent plan. The plan must exist and be in **draft** status.                                                                                           |
| `part_number`            | Yes      | Part number of the input. Matched case-insensitively.                                                                                                            |
| `revision`               | No       | Part revision. If omitted and the part has exactly one revision, that revision is used; multiple revisions produce an ambiguity error asking you to specify one. |
| `quantity`               | Yes      | Input quantity. Must be a non-negative integer.                                                                                                                  |
| `due_date`               | Yes      | Due date for the input, such as `2026-05-01`.                                                                                                                    |
| `serial_number`          | No       | Serial number for the input.                                                                                                                                     |
| `name`                   | No       | Display name for the input.                                                                                                                                      |
| `is_generate_new_demand` | No       | Whether the input generates new demand. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                            |
| `is_independent`         | No       | Whether the input is independent. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                                  |

<Warning>
  Plan inputs can only be added to **draft** plans. Rows referencing a plan in any other status fail with a row-level error, as do rows referencing a plan ID that doesn't exist.
</Warning>

<Info>
  This importer does not support custom attributes. Any column outside the list above causes a validation error.
</Info>

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Purchase order imports
Source: https://docs.firstresonance.io/administration/ion-importers/purchase-orders

Import purchase orders and their lines from a single denormalized CSV.

## Overview

The Purchase Orders importer creates or updates Purchase Orders **and** their Purchase Order Lines from a single CSV. The CSV is denormalized: one row per PO line, with the PO header columns repeated across every row that belongs to the same PO.

Example: two POs, three lines.

| po\_number | supplier | currency | part\_number | quantity | cost   |
| ---------- | -------- | -------- | ------------ | -------- | ------ |
| PO-001     | Acme     | USD      | WIDGET-A     | 10       | 5.00   |
| PO-001     | Acme     | USD      | WIDGET-B     | 5        | 12.00  |
| PO-002     | Globex   | EUR      | GADGET-X     | 1        | 100.00 |

Rows sharing the same `po_number` are merged into a single PO header. If a header column is included in your CSV, it must be populated on **every row of that PO** and all values must match. Any blank cell or any value that disagrees with another row of the same PO fails the import with a per-conflict error before any data is written.

## Header columns

These describe the PO itself. If you include a header column in your CSV, it must be present and identical on every row that shares a `po_number`. Otherwise the import fails.

| Column                 | Required | Description                                                                                                   |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `po_number`            | Yes      | PO identifier. The grouping key.                                                                              |
| `original_po_number`   | No       | Existing PO number when renaming. **Lookup column**: an empty cell means "no rename," not `""`.               |
| `po_description`       | No       | Free-text PO description.                                                                                     |
| `supplier`             | No       | Supplier name. Must match an existing supplier.                                                               |
| `ship_to_location`     | No       | Ship-to location name. Must match an existing location.                                                       |
| `bill_to_location`     | No       | Bill-to location name. Must match an existing location.                                                       |
| `currency`             | No       | Currency type, such as `USD` or `EUR`. Must match an existing currency.                                       |
| `ordered_at`           | No       | Order date. Parsed flexibly (any pandas-recognized date format).                                              |
| `assigned_to`          | No       | Email of the user the PO is assigned to. Must match an existing user.                                         |
| `po_intent_option`     | No       | Intent option value at the PO level. Prefixed with `po_` to disambiguate from the line-level `intent_option`. |
| `po_labels`            | No       | Semicolon-delimited list of label values to attach to the PO.                                                 |
| `terms_and_conditions` | No       | Title of a Requirement with type `TERMS_AND_CONDITIONS`. Overrides the org's default.                         |
| `fees`                 | No       | Semicolon-delimited list of fee records. See [Fees](#fees) below.                                             |

## Line columns

These describe a single PO line. Every row contributes one line if any line column is populated.

| Column                   | Required | Description                                                                                                                                     |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `part_number`            | No       | Part number for the line. Combined with `revision` to look up the part.                                                                         |
| `revision`               | No       | Part revision. If omitted, the latest revision of `part_number` is used.                                                                        |
| `description`            | No       | Line description.                                                                                                                               |
| `quantity`               | No       | Line quantity. Must be non-negative.                                                                                                            |
| `cost`                   | No       | Line unit cost. Must be non-negative.                                                                                                           |
| `need_date`              | No       | Date needed. Parsed flexibly.                                                                                                                   |
| `estimated_arrival_date` | No       | Estimated arrival date. Parsed flexibly.                                                                                                        |
| `paid`                   | No       | Marks the line as paid. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                           |
| `percentage_fee_exempt`  | No       | Excludes this line from percentage-based PO fees. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). |
| `labels`                 | No       | Semicolon-delimited list of label values to attach to the line.                                                                                 |
| `quality_clauses`        | No       | Semicolon-delimited list of quality clause titles. Must match Requirements with `requirement_type = QUALITY_CLAUSE`.                            |
| `intent_option`          | No       | Intent option value at the line level.                                                                                                          |

<Info>
  A row that populates only header columns (no `part_number` or other line column) contributes to the PO header but does not create a line. Use this to create or update a PO without lines.
</Info>

## Fees

The `fees` column accepts a semicolon-delimited list of fee records. Each record uses two bracketed fields after the fee name:

```
Name[value][type];Name[value][type]
```

| Field   | Notes                                        |
| ------- | -------------------------------------------- |
| `Name`  | Required. Must be unique within the PO.      |
| `value` | Required. Must parse as a number.            |
| `type`  | Required. One of `currency` or `percentage`. |

Example: `Shipping[50.00][currency];VAT[8.5][percentage]`

<Warning>
  Fee names must be unique within a PO. Duplicate fee names in the same row's `fees` cell are rejected at validation.
</Warning>

## Custom attributes

Any column not in the standard set above is treated as a custom attribute. The importer routes each column to either PO-level or PO-line-level attributes based on which table defines it in your organization's attribute configuration:

* A column matching a PO custom attribute is attached to the PO.
* A column matching a PO-line custom attribute is attached to the line.
* A column matching **both** is **ambiguous** and rejected. Rename one side to disambiguate.
* A column matching neither is rejected as unrecognized.

Matching is case- and format-sensitive, so a CSV header `BatchID` matches an attribute keyed `BatchID` only.

## Header conflicts

Header-column conflicts are collected across all POs and reported together, so you can fix everything in one pass.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Run imports
Source: https://docs.firstresonance.io/administration/ion-importers/runs

Bulk-create runs from a CSV file, including procedures, part inventory, assignees, and run batches.

## Overview

The Runs importer bulk-creates runs, one CSV row per run. It drives the same path as creating runs in the UI, so step copying, batching, and every downstream side effect behave identically.

This importer is **create-only**: it does not update existing runs.

Each run can:

* be created from a **procedure**, identified by `procedure_id` *or* `procedure_title` + `procedure_version` (a run with no procedure is also allowed),
* be tied to **part inventory**, either linking an existing record via `part_inventory_id` or creating a new one via `part_number`,
* join a **run batch** via `run_batch_title`,
* carry an assignee, intent option, due date, and custom attributes.

## Columns

| Column                       | Required    | Description                                                                                                                                                                         |
| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                      | Conditional | Run title. Each row needs either a `title` or `autogenerate_title = true`, but not both.                                                                                            |
| `autogenerate_title`         | Conditional | When `true`, ION generates the run title. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                                             |
| `procedure_id`               | No          | ID of the procedure to create the run from. Cannot be combined with `procedure_title` / `procedure_version`.                                                                        |
| `procedure_title`            | No          | Procedure title. Must be paired with `procedure_version`.                                                                                                                           |
| `procedure_version`          | No          | Procedure version (integer). Must be paired with `procedure_title`.                                                                                                                 |
| `description`                | No          | Free-text description.                                                                                                                                                              |
| `due_date`                   | No          | Due date, such as `2026-06-15`. An empty cell leaves the field unset.                                                                                                               |
| `quantity`                   | No          | Run quantity. Must be a non-negative integer. When the row creates a new inventory via `part_number`, the quantity applies to that inventory. An empty cell leaves the field unset. |
| `part_number`                | No          | Part number. Creates a **new** inventory record for the run. Cannot be combined with `part_inventory_id`.                                                                           |
| `revision`                   | No          | Part revision for the new inventory. If omitted and the part has exactly one revision, that revision is used.                                                                       |
| `serial_number`              | No          | Serial number for the new inventory.                                                                                                                                                |
| `lot_number`                 | No          | Lot number for the new inventory.                                                                                                                                                   |
| `autogenerate_serial_number` | No          | When `true`, ION generates a serial number for the new inventory. Boolean field.                                                                                                    |
| `autogenerate_lot_number`    | No          | When `true`, ION generates a lot number for the new inventory. Boolean field.                                                                                                       |
| `part_inventory_id`          | No          | ID of an **existing** inventory record to link to the run. Cannot be combined with `part_number` or any of the new-inventory columns above.                                         |
| `assigned_to`                | No          | Email address of the user to assign. An empty cell leaves the run unassigned.                                                                                                       |
| `intent_option`              | No          | Intent option name. Must match a configured intent option.                                                                                                                          |
| `export_controlled`          | No          | Whether the run is export controlled. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)).                                                 |
| `run_batch_title`            | No          | Title of the run batch to add the run to. See [Run batches](#run-batches).                                                                                                          |

<Warning>
  Three column groups are mutually exclusive per row:

  * `title` vs. `autogenerate_title`: provide exactly one.
  * `procedure_id` vs. `procedure_title` + `procedure_version`: provide at most one form.
  * `part_inventory_id` vs. `part_number`: when linking an existing inventory, the new-inventory columns (`revision`, `serial_number`, `lot_number`, `autogenerate_serial_number`, `autogenerate_lot_number`) must be empty.
</Warning>

<Info>
  Procedure titles aren't globally unique, so a `(procedure_title, procedure_version)` pair that matches more than one procedure produces an ambiguity error. Use `procedure_id` to disambiguate.
</Info>

## Run batches

Rows sharing a `run_batch_title` are grouped into a single run batch. Batch titles are unique in ION, so this is a find-or-create: if a batch with that title already exists, the runs join it; otherwise ION creates the batch.

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the run. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Supplier imports
Source: https://docs.firstresonance.io/administration/ion-importers/suppliers

Create or update suppliers from a CSV file, including contact details and custom attributes.

## Overview

The Suppliers importer bulk-creates or updates suppliers from a single CSV. Matching is **case-insensitive on `name`**. Rows whose name matches an existing supplier update that supplier, and rows with a new name create one.

## Columns

| Column         | Required | Description                                                               |
| -------------- | -------- | ------------------------------------------------------------------------- |
| `name`         | Yes      | The supplier name. Matched case-insensitively against existing suppliers. |
| `description`  | No       | Free-text description.                                                    |
| `phone_number` | No       | Contact phone number.                                                     |
| `address`      | No       | Supplier address.                                                         |
| `email`        | No       | Contact email address.                                                    |
| `contact_name` | No       | Name of the primary contact.                                              |

<Warning>
  Each supplier name may appear only once per file. Two rows with the same name (compared case-insensitively) produce a duplicate-name validation error.
</Warning>

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the supplier. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).


# Tool inventory imports
Source: https://docs.firstresonance.io/administration/ion-importers/tool-inventory

Create or update tool inventory records from a CSV file, including maintenance dates and asset URIs.

## Overview

The Tool Inventory importer creates or updates inventory records for tools (parts with the **tool** part type). It works like the [Part Inventory importer](/administration/ion-importers/part-inventory), where rows without an `id` create new inventory and rows with an `id` update the matching record, with two tool-specific additions: `last_maintained_date` and `uri`.

Because tools are always serial-tracked, **every create row must provide a `serial_number`** matching the physical asset's tag or manufacturer serial. There is no serial autogeneration and no lot tracking for tool inventory.

## Columns

| Column                 | Required         | Description                                                                                                                                               |
| ---------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | No               | Inventory ID. Provide to update an existing record; omit to create new inventory. **Lookup column**: an empty cell is treated as "not provided," not `0`. |
| `part_number`          | Yes (for create) | Part number of the tool. Ignored on update.                                                                                                               |
| `revision`             | No               | Tool revision. Combined with `part_number` to look up the tool; if omitted, the latest revision is used.                                                  |
| `serial_number`        | Yes (for create) | Serial number identifying the physical tool. Update rows inherit the existing serial.                                                                     |
| `location`             | No               | Location name. Must match an existing location in ION.                                                                                                    |
| `last_maintained_date` | No               | Date the tool was last maintained, in ISO 8601 format, such as `2026-05-01` or `2026-05-01T12:30:00`. An empty cell leaves the field unset.               |
| `uri`                  | No               | Link to the physical asset, such as an asset-management URL. Must be unique across tool inventory; an empty cell stores no value.                         |

<Info>
  `last_maintained_date` only accepts ISO 8601. Ambiguous formats like `1/2/3` are rejected rather than guessed.
</Info>

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the inventory record. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

* [Tools imports](/administration/ion-importers/tools): import the tool definitions first.
* [Part inventory imports](/administration/ion-importers/part-inventory): shared create/update behavior.
* [Importers](/administration/ion-importers): general import behavior, empty cell handling, and error reporting.


# Tools imports
Source: https://docs.firstresonance.io/administration/ion-importers/tools

Create or revise tools from a CSV file, including subtypes and maintenance intervals.

## Overview

The Tools importer bulk-creates or revises tools. In ION, a tool is a part with the **tool** part type, so this importer follows the same revision flow as the [Parts importer](/administration/ion-importers/parts) but exposes a narrower, tool-relevant column set.

Two things are set automatically on every row:

* **Part type** is always `tool`.
* **Tracking type** is always `serial`, because tools are serial-tracked. Including a `tracking_type` column in the CSV is rejected.

## Columns

| Column                 | Required | Description                                                                                                                          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `part_number`          | Yes      | The tool's part number.                                                                                                              |
| `revision`             | No       | The revision. Omit to let ION assign the next revision automatically (or the scheme's initial value if the tool is new).             |
| `revision_scheme`      | No       | Name of the revision scheme to use when creating a brand-new tool. Defaults to the org's default scheme.                             |
| `description`          | No       | Free-text description.                                                                                                               |
| `export_controlled`    | No       | Whether the tool is export controlled. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). |
| `maintenance_interval` | No       | Maintenance interval as a duration. See [Duration format](#duration-format).                                                         |
| `subtypes`             | No       | Semicolon-delimited list of tool subtype names, such as `Torque Wrench;Calibrated`.                                                  |

## Duration format

The `maintenance_interval` column accepts a duration written in days, hours, and minutes. Use the units `d`, `h`, and `m`, in that order, with optional spaces between terms. Each unit is optional. The value is rounded down to the nearest minute. A plain number with no unit is read as a number of seconds.

Valid values include:

| Value       | Meaning                    |
| ----------- | -------------------------- |
| `30d`       | 30 days                    |
| `1d 2h`     | 1 day, 2 hours             |
| `1d 2h 20m` | 1 day, 2 hours, 20 minutes |
| `45m`       | 45 minutes                 |
| `3600`      | 3,600 seconds (1 hour)     |

The **Review** step flags a value that uses any other unit (such as weeks or seconds), lists the units out of order, or is otherwise unparseable.

## Revisions

Revision behavior mirrors the [Parts importer](/administration/ion-importers/parts#revisions): rows with an explicit revision create or update that exact `(part_number, revision)`, while rows that omit revision either initialize a new tool at the scheme's first value or auto-revise an existing tool from its latest revision.

## Subtypes

The `subtypes` column attaches one or more subtypes to the tool. Subtype names are matched case-insensitively; **names that don't exist yet are created automatically**, so you can bootstrap your subtype list from the same CSV. Associations that already exist are skipped, keeping re-imports idempotent.

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the tool. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.

## Related

* [Tool inventory imports](/administration/ion-importers/tool-inventory): import the physical tool instances.
* [Parts imports](/administration/ion-importers/parts): full revision-flow details.
* [Importers](/administration/ion-importers): general import behavior, empty cell handling, and error reporting.


# Labels
Source: https://docs.firstresonance.io/administration/labels

Create and delete the shared labels used to tag and group procedures, runs, purchases, issues, and other records across ION.

**Labels** are shared tags you apply across ION to group related records. The same label library is shared by every object type, so a single label can tie together procedures, runs, purchases, and issues. Use them to slice work by program, customer, priority, or any cross-cutting theme your team tracks.

## Create a label

You create labels inline from any record that supports them, such as a procedure, run, purchase, or issue:

1. On the record, click **Labels** (or **Add labels**).
2. In the picker, type the label name in the **Search or create labels...** box.
3. If no matching label exists, click **Create ""**.

ION creates the label, adds it to the shared library for every object type, and applies it to the current record. To reuse it elsewhere, open the labels picker on another record and search for it.

## Delete a label

Deleting a label removes it from all records across ION. Label deletion is only available through the API; there is no UI option yet.

1. Query for the label to get its `id` and `_etag`. Replace `<your label here>` with the label value.

```graphql theme={null}
{
  labels(filters: {value: {eq: <your label here>}}) {
    edges {
      node {
        id
        _etag
        value
      }
    }
  }
}
```

2. Delete the label using the `id` and `_etag` from the previous query.

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

Variables:

```json theme={null}
{
  "id": "<id from previous step>",
  "etag": "<etag from previous step>"
}
```


# Configure barcode labels
Source: https://docs.firstresonance.io/administration/organization-settings/configure-barcode-labels

Customize barcode label templates for inventory, kits, and locations in ION.

ION can print barcode labels for inventory items, kits, locations, and runs. Each entity type can have multiple named label templates, and you can optionally connect a dedicated print server.

## Create a label template

1. In ION, go to **Settings > Organization > Barcode Labels**.
2. In the **Label templates** section, select the tab for the entity type you want to configure: **Inventory**, **Kits**, **Locations**, or **Runs**.
3. Click **New Template**.
4. Fill in the template fields:

| Field                     | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| **Template Name**         | A name to identify this template.                                      |
| **Print density (DPI)**   | Printer DPI setting. Default is 203. Match this to your printer's DPI. |
| **Label height (inches)** | Height of the label in inches. Default is 1.                           |
| **Label width (inches)**  | Width of the label in inches. Default is 3.                            |
| **ZPL Template**          | The label layout written in ZPL (Zebra Programming Language).          |

5. Click **Create Template**.

<Frame>
  <img alt="Barcode Labels settings showing the Inventory/Kits/Locations/Runs tabs, a templates list, a ZPL template with variable placeholders, an Available Fields panel, and Template Settings for name, print density, and label size." />
</Frame>

## Edit a label template

1. In ION, go to **Settings > Organization > Barcode Labels**.
2. Select the tab for the entity type, then select the template you want to edit from the **Templates** list.
3. Update the template fields.
4. Click **Save Template**.

To remove a template, select it, then click **Deactivate**.

### Available template variables

Insert these variables into your ZPL template and ION replaces them with live data when printing:

| Variable                   | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `${partNumber}`            | Part number                                    |
| `${partDescription}`       | Part description                               |
| `${partRevision}`          | Part revision                                  |
| `${serialNumber}`          | Serial number                                  |
| `${lotNumber}`             | Lot number                                     |
| `${quantity}`              | Quantity                                       |
| `${location}`              | Location                                       |
| `${dateCreated}`           | Date the record was created                    |
| `${barcode}`               | Barcode value                                  |
| `${qrCode}`                | QR code value                                  |
| `${activeKitId}`           | Active kit ID                                  |
| `${abomInstallationCount}` | Number of aBOM installations                   |
| `${canceledPoLineCount}`   | Number of canceled purchase order lines        |
| `${createdBy.email}`       | Email of the user who created the record       |
| `${createdBy.id}`          | ID of the user who created the record          |
| `${createdBy.lastLogin}`   | Last login of the user who created the record  |
| `${createdBy.locationId}`  | Location ID of the user who created the record |

## Connect a print server

A print server lets ION send barcode labels directly to a printer without requiring a browser print dialog.

1. In ION, go to **Settings > Organization > Barcode Labels**.
2. Turn on **Use print server**.
3. In the **Print server API key** field, enter the API key for your print server.

To view the existing API key, click **Show**. You need admin access to reveal the key.


# Configure export control
Source: https://docs.firstresonance.io/administration/organization-settings/configure-export-control

Configure identity groups and understand how ION restricts export-controlled parts, procedures, and runs.

Export control adds a group-based access decision on top of ION's standard roles and permissions. A person needs an allowed identity-provider group to reach export-controlled parts, procedures, and runs. Their normal ION permissions still determine which actions they can perform on the records they can reach.

```mermaid theme={null}
flowchart LR
    subgraph config["1. Configure in your identity provider"]
        G["Add people to the<br/><b>Export UnRestricted</b> group"]
    end
    subgraph signin["2. At each sign-in"]
        S["SSO sends the person's<br/>group membership to ION"]
    end
    subgraph records["3. Records in ION"]
        R["Parts, procedures, and runs<br/>marked <b>export controlled</b>"]
    end
    subgraph access["4. What each person can access"]
        U["<b>Export-unrestricted</b><br/>Every record, including<br/>controlled parts, procedures, and runs"]
        X["<b>Export-restricted</b><br/>Controlled records are hidden from lists;<br/>a direct link returns not found"]
    end

    G --> S --> D{"In an allowed<br/>export group?"}
    R --> D
    D -- "Yes" --> U
    D -- "No or missing" --> X
```

## How ION decides access

During sign-in, ION reads the group memberships your identity provider sends through its standard group data. For each request, ION checks that membership for an exact match with either of these group names:

* `Employee Export UnRestricted`
* `Export UnRestricted`

If either name is present, the person is export-unrestricted for that session. A missing group, an empty group list, or any other group name keeps the person export-restricted. Everyone is export-restricted by default until they belong to one of the allowed groups.

<Info>
  The export-control decision reads your identity provider's group membership, not an arbitrary SSO attribute. If your identity provider stores the entitlement in another attribute, map that value into the group data your SSO connection sends before ION can act on it.
</Info>

## What export control protects

Export control applies to three record types. The effect on an export-restricted person is the same for each: the record is filtered out.

| Flagged record | Access effect for an export-restricted person                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Part           | The part is omitted from query results, and a direct link returns not found. A run associated with the part is also treated as export-controlled.                                                       |
| Procedure      | The procedure is omitted from query results, and a direct link returns not found. A run created from the procedure is also treated as export-controlled.                                                |
| Run            | The run is omitted from query results, and a direct link returns not found. A run is treated as export-controlled when its own flag, its associated part, or its source procedure is export-controlled. |

Because ION filters these records before an update can load them, an export-restricted person can't edit an existing export-controlled part, procedure, or run. They also can't mark a part, procedure, or run as export-controlled.

<Warning>
  Export-control filtering covers parts, procedures, and runs. Related records keep their own access behavior. Part inventory records aren't filtered, but an export-restricted person can't update inventory tied to an export-controlled part.
</Warning>

## Configure export-control access

1. Contact [First Resonance Support](https://support.firstresonance.io/) to enable export control and confirm that your SSO connection sends identity-provider group membership to ION.
2. In your identity provider, create or identify a group named exactly `Employee Export UnRestricted` or `Export UnRestricted`.
3. Add each person who can access export-controlled records to one of the allowed groups. Keep everyone else out of both groups.
4. After you change group membership, have the affected person start a new sign-in session so ION receives their current groups.

ION doesn't manage export-control group membership. You manage it in your identity provider.

## Mark a record as export-controlled

An export-unrestricted person sets the flag on the record itself:

* On a procedure, turn on the **Export control** toggle.
* While creating a run, turn on **Export controlled**.
* On a part, set the `export_controlled` column to `true` when you [import parts](/administration/ion-importers/parts).

## Verify the restriction

1. Prepare a controlled test record:
   * On a test procedure, turn on **Export control**, then create a run from that procedure.
   * To test a part, [import a test part](/administration/ion-importers/parts) with `export_controlled` set to `true`, then associate it with a run.
   * To test a run on its own, turn on **Export controlled** while creating the run.
2. Sign in with an account in one of the allowed groups that also has the ION permissions the records need. Confirm that the part or procedure and its associated run are available.
3. Sign in with an account outside both allowed groups. Confirm that list results omit the controlled records and that a direct link returns not found.
4. If the part has inventory, confirm that the inventory record stays visible but an update to it is blocked.

## Related

* [Set up SSO](/administration/authentication-settings/sso/set-up-sso)
* [Import parts](/administration/ion-importers/parts)
* [Import runs](/administration/ion-importers/runs)


# Configure general settings
Source: https://docs.firstresonance.io/administration/organization-settings/configure-general-settings

Update your organization's name and logo in ION.

General settings control how your organization appears: the name shown across the app, and the logo displayed in the interface and on a printed [purchase order](/manage-supply-chain/purchasing/create-a-purchase-order).

## Set the organization name

1. In ION, go to **Settings > Organization > General Settings**.
2. In the **Organization Name** field, type the new name.

Every organization starts without a name, and clearing the field returns it to that state rather than being rejected. While the field is empty, ION shows your organization's domain in place of the name, which is what the field's placeholder names.

## Update the organization logo

1. In ION, go to **Settings > Organization > General Settings**.
2. In the **Branding** section, click **Change Image**.
3. In the **Upload Photo URL** dialog, enter a publicly accessible URL in the **Image URL** field.
4. Click **Save**.

To remove the current logo, click **Change Image**, then click **Remove**.

The logo is a URL you host, so it can sit on any host. Until you set one, a printed purchase order carries your organization's name alone and its **Company Logo** option is unavailable.

## Related

* [Create a purchase order](/manage-supply-chain/purchasing/create-a-purchase-order)


# Turn on ION Intelligence
Source: https://docs.firstresonance.io/administration/organization-settings/enable-ion-intelligence

Opt your organization in to ION Intelligence and every other AI surface in ION.

AI is off until an admin turns it on. The setting is org-wide, so while it is off nobody in the
organization can reach an AI surface, admins included.

## Turn on ION Intelligence

1. In ION, go to **Settings > Organization > AI**.
2. Under **ION Intelligence**, turn on **Enable ION Intelligence**.

Only an admin can change the setting. Everyone else sees it as read-only.

While it is off, nobody sees an AI entry point anywhere in ION, such as the ION pill and its sidebar
entry, the **ION** tab in the mobile navigation, the suggested-action cards on **Kits**,
**Purchases**, and **Inventory**, and the suggestion pills on a procedure step. Turning it back on
restores them.

<Note>
  Turning it off disables AI everywhere it is reachable, not only on ION's own screens.
</Note>

If ION Intelligence is not available to your organization yet, the section says so in place of the
setting. Contact your First Resonance representative to have it enabled.

## Related

* [ION Intelligence](/automate-with-ion/ion-intelligence)


# Manage OAuth apps
Source: https://docs.firstresonance.io/administration/organization-settings/manage-oauth-apps

Register a custom application to authenticate with the ION API using OAuth 2.0.

OAuth applications let your custom tools and integrations authenticate with the ION API. ION supports two app types: web and desktop apps using the PKCE flow, and IoT or limited-input devices using the Device Authorization Grant.

## Register an app

1. In ION, go to **Settings > Organization > OAuth Apps**.
2. Click **Register App**.
3. Enter an **Application Name**.
4. Select the application type:
   * **Web / Desktop App (PKCE)**: For web or desktop applications using the Authorization Code + PKCE flow.
   * **Device / Wearable**: For IoT devices or limited-input devices using the Device Authorization Grant.
5. Click **Register**.

Copy the **Client ID** from the app's entry for use in your application.

## Add redirect URIs (web / desktop apps only)

After registering a web or desktop app, add the URIs your application uses:

1. In the app's entry, click **Add Callback URL** and enter your callback URL (for example, `https://your-app.com/callback`).
2. Optional: Add any of the following:
   * Click **Add Origin** to add an allowed CORS origin.
   * Click **Add Logout URL** to add a post-logout redirect URL.

An app's URLs are grouped under **Callback URLs**, **Allowed Origins (CORS)**, and **Logout URLs**. To remove one, click the **X** next to the URL you want to remove.

<Note>
  An app's name and type are fixed after registration. To change them, delete the app and register a new one.
</Note>

## Delete an app

1. In ION, go to **Settings > Organization > OAuth Apps**.
2. In the app's entry, click the delete icon.
3. Confirm the deletion.

<Warning>
  Deleting an OAuth app revokes access for all applications using that client ID. This cannot be undone.
</Warning>

## Related

* [API reference](/api-reference)


# Set the date format
Source: https://docs.firstresonance.io/administration/organization-settings/set-the-date-format

Choose how dates are displayed across your ION organization.

The date format setting controls how dates appear throughout ION for all users in your org. Choose from a predefined format or enter a custom one.

## Set the date format

1. In ION, go to **Settings > Organization > Date Time**.
2. In the **Date Format** field, either:
   * Type a custom format string (for example, `YYYY-MM-DD`).
   * Open the dropdown to select a predefined format.
3. Check the **Preview** section to confirm today's date appears in the selected format.

## Predefined formats

| Format        | Example     |
| ------------- | ----------- |
| `YYYY-MM-DD`  | 2026-06-11  |
| `MM/DD/YYYY`  | 06/11/2026  |
| `DD/MM/YYYY`  | 11/06/2026  |
| `DD/MMM/YYYY` | 11/Jun/2026 |
| `DD-MMM-YYYY` | 11-Jun-2026 |


# Auto-assign runs to their creator
Source: https://docs.firstresonance.io/administration/production-settings/auto-assign-runs-to-their-creator

Assign every new run to the person who created it, unless they pick a different assignee.

By default a new run is unassigned until someone picks it up. When this setting is on, a run is assigned to whoever created it unless an assignee is chosen at creation.

## Auto-assign runs to their creator

1. In ION, go to **Settings > Production > Runs**.
2. Turn on **Auto-assign runs to their creator**.

## What changes for the person creating a run

While the setting is on, the run creation form pre-fills **Assigned to** with the current user. The field stays optional, so you can pick someone else, and clearing it still lands the run on the creator.

## Related

* [Create a run](/build-hardware/runs-and-execution/starting-a-run)


# Configure procedure reviewer roles
Source: https://docs.firstresonance.io/administration/production-settings/configure-procedure-reviewer-roles

Set which roles must approve a procedure before it can be released.

Reviewer roles define which roles must sign off on a procedure before it reaches the Released state. Each role has a minimum number of approvals required.

**Settings > Production > Procedures** shows the controls for the approval model your org is on. An org on role-based approvals gets the **Reviewer roles** editor described here. An org on the reviewer-count model gets a single **Reviewers required** field instead. See [Set the number of reviewers required](#set-the-number-of-reviewers-required).

<Note>
  Which model your org uses isn't something you set on this page. To change it, contact [support.firstresonance.io](https://support.firstresonance.io).
</Note>

## Add a reviewer role

1. In ION, go to **Settings > Production > Procedures**.
2. In the **Reviewer roles** section, click **Add role**.
3. Select the role from the dropdown.
4. Set the number of approvals required for that role.
5. Click **Save Changes**.

## Update the approver count

1. In the **Reviewer roles** section, find the role you want to update.
2. In the count field beside the role, enter the number of approvals required.
3. Click **Save Changes**.

## Remove a reviewer role

1. In the **Reviewer roles** section, click **X** next to the role you want to remove.
2. Click **Save Changes**.

## Set the number of reviewers required

On the reviewer-count model, a procedure needs a set number of approvals to be released, from any reviewer, with no per-role breakdown.

1. In ION, go to **Settings > Production > Procedures**.
2. In **Reviewers required**, enter the number of approvals a procedure needs. The value saves on its own a moment after you stop typing.

Enter 0 to release a procedure without approvals. Clearing the field doesn't save an empty value, so the previous number stays until you type a new one.

## Related

* [Configure standard step reviewer roles](/administration/production-settings/configure-standard-step-reviewer-roles)


# Configure run enforcement
Source: https://docs.firstresonance.io/administration/production-settings/configure-run-enforcement

Set which rules ION enforces when runs are in progress or completing.

Run enforcement settings control what you can and can't do during run execution.

## Configure run enforcement

1. In ION, go to **Settings > Production > Runs**.
2. Turn on or off the settings you need:

| Setting                                                  | What it does                                                                |
| -------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Require part-procedure relationship**                  | Parts must be linked to procedures before they can be used in runs.         |
| **Allow run steps to complete without required install** | Steps can be marked complete even if required parts haven't been installed. |
| **Enforce peer signoff**                                 | A different user must sign off on each step completion.                     |
| **Enforce run title template**                           | Run titles must follow the configured naming template.                      |
| **Enforce all aBOM parts installed for completion**      | Runs can't be completed if any aBOM parts remain uninstalled.               |

When **Enforce all aBOM parts installed for completion** is on, you can also turn on **Allow completion with justification** to complete runs with uninstalled parts by providing a written justification.

The **Number of redline approvers required** field on the same page sets how many approvals a redline needs. See [Set the redline approver count](/administration/production-settings/set-redline-approver-count).

## Set the run title template

The run title template names new runs automatically. Set it before turning on **Enforce run title template**, which stays disabled until a valid template is saved.

1. In ION, go to **Settings > Production > Runs**.
2. In **Run title template**, enter the pattern to apply to new run titles, for example `${id}-${partNumber}-${partRevision}`.
3. Include `${id}` (required), plus any of these tokens: `${partNumber}`, `${partRevision}`, `${partDescription}`, `${procedureTitle}`, `${procedureVersion}`, `${serialNumber}`, `${lotNumber}`, `${quantity}`, and `${dueDate}`. Text outside the tokens is kept as written. ION flags a template that omits `${id}` or uses an unknown token.

## Related

* [Require barcode scanning for installations](/administration/production-settings/require-barcode-scanning-for-installations)


# Configure standard step reviewer roles
Source: https://docs.firstresonance.io/administration/production-settings/configure-standard-step-reviewer-roles

Set which roles must approve a standard step before it can be released.

Reviewer roles define which roles must sign off on a standard step before it reaches the Released state.

## Add a reviewer role

1. In ION, go to **Settings > Production > Standard Steps**.
2. In the **Reviewer roles** section, click **Add role**.
3. Select the role from the dropdown.
4. Set the number of approvals required for that role.
5. Click **Save Changes**.

## Update the approver count

1. In the **Reviewer roles** section, find the role you want to update.
2. In the count field beside the role, enter the number of approvals required.
3. Click **Save Changes**.

## Remove a reviewer role

1. In the **Reviewer roles** section, click **X** next to the role you want to remove.
2. Click **Save Changes**.

## Related

* [Configure procedure reviewer roles](/administration/production-settings/configure-procedure-reviewer-roles)


# Enforce mBOM parts assigned to steps
Source: https://docs.firstresonance.io/administration/production-settings/enforce-mbom-parts-assigned-to-steps

Require every mBOM part to be pinned to a version and assigned to a step before a procedure can be sent for review or released.

This setting makes step assignment a condition of moving a procedure forward, and it changes how runs read the mBOM.

## Enforce mBOM parts assigned to steps

1. In ION, go to **Settings > Production > Procedures**.
2. Turn on **Enforce mBOM parts assigned to steps**.

## What the setting changes

With the setting on:

* Every part must be pinned to a specific mBOM version and assigned to a step before a procedure can be sent for review or released.
* New runs follow the pinned version instead of the latest released one.
* Once all of an assembly's parts are assigned to steps, part quantities stay in sync with the assignments: editing a step's assignment updates the run quantity automatically.

The gate applies to both forward transitions: **Draft** to **In Review**, and **In Review** to **Released**. It covers the procedure's own mBOM lines and the components inside its sub-assemblies, at any depth. When something is unassigned, the transition control is disabled and names the count and the first few part numbers.

<Note>
  When ION can't check the whole sub-assembly tree, it says that some components were not checked and asks you to check them before releasing, without blocking the transition. That covers a sub-assembly level holding more items than can be checked at once, and a tree nested deep enough that the check stops early. A failed data load is different: it does block, because a reload clears it.
</Note>

Assigning a sub-assembly's components still needs that sub-assembly's own setup first: its mBOM version has to be pinned, which happens when you assign the sub-assembly in the procedure's right rail.

## Related

* [Create and release a procedure](/build-hardware/procedures/create-and-release-a-procedure)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)


# Require barcode scanning for installations
Source: https://docs.firstresonance.io/administration/production-settings/require-barcode-scanning-for-installations

Require barcode scanning when you install inventory on an aBOM.

When this setting is on, you can only install inventory by scanning a barcode. Manual inventory selection is disabled. You can designate one role that can bypass the restriction.

## Require barcode scanning for installations

1. In ION, go to **Settings > Production > aBOMs**.
2. Turn on **Disable manual inventory installations**.
3. Optional: In the **Role allowed to bypass install restrictions** field, select the role that can still install inventory manually.


# Set the redline approver count
Source: https://docs.firstresonance.io/administration/production-settings/set-redline-approver-count

Set how many approvals are required before a redline is applied in ION.

The redline approver count controls how many users must approve a redline before it is applied to a procedure.

## Set the redline approver count

1. In ION, go to **Settings > Production > Runs**.
2. In the **Number of redline approvers required** field, enter the number of approvals required.

## Related

* [Enable auto-submit redlines](/administration/quality-settings/enable-auto-submit-redlines)


# Configure intent control policies
Source: https://docs.firstresonance.io/administration/quality-settings/configure-intent-control-policies

Set how intent affects run execution, inventory availability, installs, and part quality in ION.

Intent control policies determine what ION does when an item's intent is set to a particular value. The policies are grouped into four sections: **Run Controls**, **Inventory Controls**, **Install Controls**, and **Part Quality**.

<Info>
  Intent control policies appear only when intent features are enabled for your organization.
</Info>

## Configure a policy

1. In ION, go to **Settings > Quality > Intent**.
2. Expand the section that holds the policy you want.
3. Turn on the policy, and choose a mode where one is offered.

Where a policy offers **Hierarchical** or **Exact** matching, the policy compares items by intent rank (set in [Manage intent options](/administration/quality-settings/manage-intent-options)). **Hierarchical** accepts any intent at or above the required tier; **Exact** requires the same tier.

## Run Controls

Govern intent on runs.

| Policy                               | What it does                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Require Intent on Run Create**     | Makes intent mandatory when a run is created.                                                                                                                                                                                                                                                                                                    |
| **Require Intent on Run Update**     | Prevents clearing a run's intent once it has been set.                                                                                                                                                                                                                                                                                           |
| **Require Intent on Run Step Start** | Makes intent mandatory when a run step starts.                                                                                                                                                                                                                                                                                                   |
| **Run Intent Sync**                  | Copies a run's intent to its attached part inventory when the inventory has no intent set. When the run's intent is a lower tier than the inventory's, the **Downgrade inventory on mismatch** option controls whether the inventory is downgraded to match. Assigning a run intent higher than the inventory's current intent is not permitted. |

**Require Intent on Run Create**, **Require Intent on Run Update**, and **Require Intent on Run Step Start** can each be limited to specific procedure types, so only runs of those types require intent.

## Inventory Controls

Govern intent on inventory.

| Policy                                  | What it does                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Require Kit Intent Match**            | Blocks kitting when kitted inventory intent doesn't meet the run's part inventory intent. Checked both when an item is added to a kit and when the kit is delivered to an assembly. Offers **Hierarchical** or **Exact** matching.                                                                                            |
| **PO Line Intent Sync**                 | Propagates intent from a purchase order line to the on-order inventory created from it.                                                                                                                                                                                                                                       |
| **Issue Intent Update**                 | When an issue is resolved, applies an intent to the affected inventory based on the issue's disposition type. You set the disposition-type-to-intent mapping in this policy with **Map disposition types to intent options** and **Add mapping**. A disposition type with no mapping leaves the inventory's intent unchanged. |
| **Required at Manual Inventory Create** | Makes intent mandatory when you create inventory by hand.                                                                                                                                                                                                                                                                     |

## Install Controls

Govern intent during installs.

| Policy                           | What it does                                                                                                                                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Require Install Intent Match** | Blocks an install when the child part's intent doesn't meet the parent assembly's intent. Offers **Hierarchical** or **Exact** matching.                                                                                  |
| **Downgrade on Install**         | Lowers a child part's intent to match the parent when it's installed in an aBOM, but only when the parent assembly's intent is lower than the child's. If the parent's intent is equal or higher, the child is unchanged. |

## Part Quality

Governs part inventory intent.

| Policy                 | What it does                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Part Quality Check** | Keeps part inventory intent from exceeding the part's intent. Applies wherever intent is assigned to inventory: manual assignment, receipt from a purchase order line, run intent sync, and issue resolution. In **Block** mode, an exceeding value raises an error; in **Downgrade** mode, the inventory intent is lowered to match the part. |

## Related

* [Manage intent options](/administration/quality-settings/manage-intent-options)


# Configure issue creation and approvals
Source: https://docs.firstresonance.io/administration/quality-settings/configure-issue-creation-and-approvals

Auto-create issues on run step failure and set how many approvals are required to close an issue.

## Auto-create issues on run step failure

When this setting is on, ION automatically creates an issue ticket whenever a run step is marked as failed.

1. In ION, go to **Settings > Quality > Issues**.
2. Turn on **Create issues on run step failure**.

## Set the number of approvals required

1. In ION, go to **Settings > Quality > Issues**.
2. In the **Number of approvals required** field, enter the number of approvals needed before an issue can be closed.

## Related

* [Rename fields](/administration/quality-settings/rename-fields)
* [Set the default availability behavior for issues](/administration/quality-settings/set-default-availability-behavior)


# Enable auto-submit redlines
Source: https://docs.firstresonance.io/administration/quality-settings/enable-auto-submit-redlines

Automatically apply a redline's changes once all required reviewers have approved.

When auto-submit is on, ION applies a redline's changes as soon as all required reviewers have approved. When off, you must manually submit the redline after all approvals are collected.

## Enable auto-submit redlines

1. In ION, go to **Settings > Quality > Redlines**.
2. Turn on **Auto Submit Redlines**.

## Related

* [Set the redline approver count](/administration/production-settings/set-redline-approver-count)


# Manage disposition types
Source: https://docs.firstresonance.io/administration/quality-settings/manage-disposition-types

Create, edit, and delete issue disposition types, along with their availability behavior and approval roles.

A disposition type defines a disposition decision for your organization: its name, how it affects the availability of the affected inventory, and which roles must approve it before the issue can progress.

## Add a disposition type

1. In ION, go to **Settings > Quality > Issues**.
2. In the **Disposition types** section, type a name in **New disposition type name** and click **Add**.

## Configure a disposition type

Expand a disposition type to set:

| Setting                   | What it does                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**                | Makes the type available to apply to issues. Turn it off to retire a type without deleting it.                                                    |
| **Disposition type name** | The label shown when choosing a disposition.                                                                                                      |
| **Description**           | Optional explanation of when to use the type.                                                                                                     |
| **Availability**          | How the affected inventory behaves once the disposition is applied. Changing it prompts a confirmation that shows how much inventory is affected. |
| **Auto-resolve**          | When on, issues with this disposition resolve automatically once approved, skipping **In Review**.                                                |

The **Availability** options are:

| Option                      | Effect                                                                |
| --------------------------- | --------------------------------------------------------------------- |
| **Available Immediately**   | Inventory is available as soon as the disposition is applied.         |
| **Release on Resolve**      | Inventory becomes available only when the issue reaches **Resolved**. |
| **Permanently Unavailable** | Inventory stays locked out.                                           |

### Approval roles

Each disposition type defines who must approve at each stage of the issue. On an expanded disposition type in **Settings > Quality > Issues**:

1. In **Approver Roles**, click **Add role** and set the number of approvers required from that role. These roles must approve before an issue can leave **Pending**.
2. In **Closure Roles**, click **Add role** and set the number of approvers required. These roles must approve before an issue can reach **Resolved**.

To remove a role from either list, click the remove control next to it.

## Edit a disposition type

Expand the type and change its fields in place. The name and description save when you click away; **Active** and **Auto-resolve** save as soon as you toggle them. Changing **Availability** prompts a confirmation before it takes effect.

## Delete a disposition type

Click the trash icon on the disposition type.

<Tip>
  To stop offering a type without removing it, turn off **Active** instead.
</Tip>

## Related

* [Set the default availability behavior](/administration/quality-settings/set-default-availability-behavior)
* [Configure issue creation and approvals](/administration/quality-settings/configure-issue-creation-and-approvals)


# Manage intent options
Source: https://docs.firstresonance.io/administration/quality-settings/manage-intent-options

Add, edit, and remove the intent values available in your organization.

Intent options are the quality tiers you assign to items, for example **Flight**, **Production**, and **Development**. Their order sets their rank: the option at the top is the strictest, highest-quality tier, and rank decreases as you move down. Intent control policies that compare intent, such as kit and install matching, use this ranking.

## Add an intent option

1. In ION, go to **Settings > Quality > Intent**.
2. In the **Options** section, click **Add Option**.
3. Type a name in the new option's value field.

## Edit an intent option

1. In ION, go to **Settings > Quality > Intent**.
2. In the **Options** section, click the value field for the option you want to edit and update the text.

To configure the **Inspection Run Required** setting for an option, expand the option row and turn **Inspection Run Required** on or off. When it's on, receiving inventory that carries this intent automatically creates the part's inspection runs. When it's off, those inspection runs aren't created automatically on receipt.

## Reorder intent options

In the **Options** section, drag an option row by its grip handle to reorder it.

## Remove an intent option

1. In ION, go to **Settings > Quality > Intent**.
2. In the **Options** section, click **X** next to the option you want to remove.

## Where intent appears

Once your organization uses intent, an intent column shows on the inventory tables across ION. It's editable on the **Inventory** page and in a part's **Inventory** section, and read-only everywhere else:

* The Factory Floor location inventory table.
* A kit's fulfillment table and its kitted inventory rows.
* The inventory tables in the create-issue dialog and the clone or split issue dialog.

The column takes whatever name your organization gave the intent field, so it may not read "Intent". See [Rename fields](/administration/quality-settings/rename-fields).

## Related

* [Rename fields](/administration/quality-settings/rename-fields)
* [Configure intent control policies](/administration/quality-settings/configure-intent-control-policies)


# Rename fields
Source: https://docs.firstresonance.io/administration/quality-settings/rename-fields

Replace default ION field labels with your organization's terminology, from Settings.

ION lets you rename certain built-in fields to match your terminology. The label you enter replaces the default wherever that field appears in ION. The renameable fields are grouped below by the Settings page where you rename them.

## Issues

Rename these on **Settings > Quality > Issues**, in the **Issue ticket label configuration** section.

| Default field      | Alias input                  |
| ------------------ | ---------------------------- |
| Disposition        | **Disposition alias**        |
| Cause condition    | **Cause condition alias**    |
| Expected condition | **Expected condition alias** |

## Further actions

Rename these on **Settings > Quality > Further Actions**.

| Default field     | Alias input                 |
| ----------------- | --------------------------- |
| Problem statement | **Problem statement alias** |
| Analysis notes    | **Analysis notes alias**    |
| Resolution        | **Resolution alias**        |

## Intent

Rename this on **Settings > Quality > Intent**.

| Default field | Alias input      |
| ------------- | ---------------- |
| Intent        | **Intent Alias** |

## Rename a field

1. Go to the Settings page listed for the field you want to rename.
2. Enter your preferred label in that field's alias input.

## Related

* [Custom attributes](/administration/custom-attributes)


# Set the default availability behavior for issues
Source: https://docs.firstresonance.io/administration/quality-settings/set-default-availability-behavior

Control whether inventory tied to an open issue remains available or is put on hold by default.

The default availability behavior applies to inventory tied to issues that don't yet have a disposition type assigned. Once a disposition type is assigned, that type's own availability behavior takes over.

## Set the default availability behavior

1. In ION, go to **Settings > Quality > Issues**.
2. In the **Default availability behavior** field, select the behavior you want.
3. Click **Confirm**.

## Related

* [Configure issue creation and approvals](/administration/quality-settings/configure-issue-creation-and-approvals)


# Security and compliance
Source: https://docs.firstresonance.io/administration/security-and-compliance

How First Resonance handles backups, encryption, and data access for ION.

## Backups

First Resonance performs daily backups of your ION environment. Backups are retained for 25 days and are reserved for emergency database recovery. Backups let First Resonance restore your environment to an earlier point if needed.

## Encryption

ION uses AWS Key Management Service (KMS) to manage encryption keys. AWS KMS is designed so that no one (including First Resonance) can retrieve your plaintext keys.

## GovCloud access

If you're on the GovCloud version of ION and traveling internationally, you can still access ION from outside the United States by connecting through a VPN.


# SIEM integration
Source: https://docs.firstresonance.io/administration/siem-integration

How to pull ION data into your SIEM using the GraphQL API.

ION doesn't have a native SIEM connector, but you can pull any ION data into your SIEM by querying the GraphQL API on a schedule.

For setup instructions, see [API reference](/api-reference/getting-started).

## Polling pattern

A typical polling loop:

1. Read the `last_polled_at` timestamp from your pipeline's state store.
2. Query ION for records where `updatedAt > last_polled_at`.
3. Transform and forward the results to your SIEM ingest endpoint.
4. On success, write the current timestamp as the new `last_polled_at`.

The data most commonly relevant to SIEM ingestion includes:

* **Runs**: production order lifecycle events (created, started, completed, paused).
* **Issues**: quality events, nonconformances, and dispositions.
* **Inventory**: adjustments, transfers, and lot/serial number changes.
* **Users and roles**: membership changes, permission grants, and deactivations.

## Alternatives to polling

If your architecture can accept inbound HTTPS traffic, [webhooks](/api-reference/guides/webhooks) let ION push change events to your endpoint in near-real time, which reduces polling overhead and latency. Webhooks cover the same resources and include the before/after state of the changed record.

Use polling when your SIEM sits behind a firewall that blocks inbound connections, or when your compliance posture requires a strict pull-only model.

## Related

* [API reference](/api-reference/getting-started)
* [Webhooks](/api-reference/guides/webhooks)
* [Security and compliance](/administration/security-and-compliance)


# Allow kitting of WIP inventory for outside processing
Source: https://docs.firstresonance.io/administration/supply-chain-settings/allow-wip-osp-kitting

Let inventory that is out at a supplier on an outside-processing purchase order be kitted while it is still in WIP.

Inventory in **WIP** is not kittable. When this setting is on, one exception applies: inventory linked to a purchase order line through an [outside-processing](/build-hardware/runs-and-execution/outside-processing) run step can be kitted while it is still in **WIP**. All other WIP inventory stays un-kittable.

The exception applies everywhere a kit draws on inventory: the kitting picker, the kit's inventory viewer, and barcode scanning.

## Allow kitting of WIP inventory for OSP

1. In ION, go to **Settings > Supply Chain > Parts Inventory**.
2. Turn on **Allow kitting of WIP inventory for OSP**.

## Related

* [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits)
* [Send a step to outside processing](/build-hardware/runs-and-execution/outside-processing)


# Configure demand settings
Source: https://docs.firstresonance.io/administration/supply-chain-settings/configure-demand-settings

Control how ION calculates material demand and what counts as supply when running Autoplan.

Demand settings control which parts of the BOM drive demand calculations and how supply is counted during Autoplan runs.

## Configure demand settings

1. In ION, go to **Settings > Supply Chain > Plans**.
2. Turn on or off the settings you need:

| Setting                                 | What it does                                                                        |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| **Drive demand below purchased parts**  | Extends demand calculations to sub-components beneath purchased parts in the BOM.   |
| **Drive demand from kits**              | Includes kit requirements when calculating material demand.                         |
| **Group plan items with same date**     | Consolidates plan line items with the same target date into a single group.         |
| **Exclude uncommitted purchase orders** | Counts only ordered POs as supply; draft, requested, and approved POs are excluded. |

## Related

* [Set working time](/administration/supply-chain-settings/set-working-time)


# Configure inventory merge behavior
Source: https://docs.firstresonance.io/administration/supply-chain-settings/configure-inventory-merge-behavior

Control whether merging inventories creates a single new inventory record in ION.

When inventories are merged, this setting controls whether they are combined into a single new inventory record.

## Configure inventory merge behavior

1. In ION, go to **Settings > Supply Chain > Parts Inventory**.
2. In the **Merge Inventories** section, turn **Merge into single new inventory** on or off.


# Configure part revision schemes
Source: https://docs.firstresonance.io/administration/supply-chain-settings/configure-part-revision-schemes

Define the naming formats used to track part revisions in ION.

Revision schemes define how part revisions are named (for example, alphabetic A, B, C or numeric 1, 2, 3). You can configure multiple schemes and set one as the default.

## Revision scheme format

A revision scheme's format defines the sequence of characters a revision can use. You build it from segments and separators:

* Click **A–Z** to add an alphabetic segment (A, B, C, and so on).
* Click **0–9** to add a numeric segment (1, 2, 3, and so on).
* To place a separator between segments, type a single character in the **Separator** field and click **Add**.

A format must include at least one numbering segment (**A–Z** or **0–9**).

## Add a revision scheme

1. In ION, go to **Settings > Supply Chain > Parts**.
2. In the **Part Revision Schemes** section, fill in the new scheme form:
   * Enter a **name** for the scheme.
   * Build the **format**, as described in [Revision scheme format](#revision-scheme-format).
   * Optional: Turn on **Overflow** to continue the sequence past the last defined value.
   * Optional: Turn on **Default** to make this the default scheme.
3. Click **Create Scheme**.

## Edit a revision scheme

1. In ION, go to **Settings > Supply Chain > Parts**.
2. In the **Part Revision Schemes** section, click a scheme to expand it.
3. Update the name, **Allow overflow** setting, or **Default** flag as needed.

## Delete a revision scheme

1. In ION, go to **Settings > Supply Chain > Parts**.
2. In the **Part Revision Schemes** section, click the trash icon on the scheme's row.

## Related

* [Enable part interchangeability](/administration/supply-chain-settings/enable-part-interchangeability)


# Configure purchase order approval workflow
Source: https://docs.firstresonance.io/administration/supply-chain-settings/configure-purchase-order-approval

Define the approval levels required before a purchase order can proceed in ION.

The purchase order approval workflow defines how many levels of approval a PO requires, who is responsible at each level, and the cost threshold that triggers each level.

## How approval levels work

Each approval level activates when a PO's total cost meets or exceeds that level's **Cost Threshold**.

You can add as many levels as you need and reorder them by dragging.

## Configure the approval workflow

1. In ION, go to **Settings > Supply Chain > Purchases**.
2. In the **Approval Policy** section, click **Add Level**.
3. For each level, fill in the fields:
   * **Role**: the role you must have to approve at this level.
   * **Team**: the team responsible for approvals at this level. Can be left for you to select at review time.
   * **Cost Threshold**: the minimum PO total (in your org's currency) that triggers this level.
4. Drag levels into the order in which you want approvals to happen.

## Configure approval reset thresholds

If a PO is edited after approval, ION can automatically reset approvals and require the workflow to run again. Set this in the **Approval Reset Cost Threshold** section:

| Field             | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| **By Percentage** | Reset approvals if the PO total changes by this percentage.                                        |
| **By Amount**     | Reset approvals if the PO total changes by this amount in your org's currency.                     |
| **Condition**     | Whether both thresholds must be met (**and**) or either one is enough (**or**) to trigger a reset. |

## Related

* [Set purchase order defaults](/administration/supply-chain-settings/set-purchase-order-defaults)


# Disable automatic location update on run start
Source: https://docs.firstresonance.io/administration/supply-chain-settings/disable-auto-location-update

Keep inventory at its current location instead of moving it to the step location when a run starts.

By default, ION moves inventory to the step's location when a run starts. When this setting is on, inventory stays at its current location instead.

## Disable automatic location update on run start

1. In ION, go to **Settings > Supply Chain > Parts Inventory**.
2. Turn on **Disable auto location update on run start**.


# Enable part interchangeability
Source: https://docs.firstresonance.io/administration/supply-chain-settings/enable-part-interchangeability

Allow any revision of a part to be used in place of the specific revision specified in the aBOM.

When part interchangeability is on, any revision of a part can be installed wherever the aBOM specifies a particular revision. This is useful when revision-level differences are not functionally significant.

<Note>
  Use this functionality when your organization enforces that part numbers have the same form, fit, and function, and uses different part numbers when they do not.
</Note>

## Enable part interchangeability

1. In ION, go to **Settings > Supply Chain > Parts**.
2. In the **Part Interchangeability** section, turn on **Allow any part revision to be used**.

## How it behaves

Once enabled, while kitting or installing you can consume inventory that has the same part number as the required part even if it's a different revision.

## Related

* [Configure part revision schemes](/administration/supply-chain-settings/configure-part-revision-schemes)


# Manage requirements
Source: https://docs.firstresonance.io/administration/supply-chain-settings/manage-requirements

Create and manage terms and conditions and quality clauses used on purchase orders in ION.

Requirements are reusable terms and conditions or quality clauses that can be attached to purchase orders. Define them in Settings rather than on individual POs so your team always works from a consistent set of approved language. Terms cover payment terms and conditions; quality clauses set requirements for a supplier to deliver against on each PO line, such as a certificate of conformance or a dimensional inspection report.

## Create a requirement

1. In ION, go to **Settings > Supply Chain > Requirements**.
2. Select the tab for the type you want to create: **Terms** or **Quality Clauses**.
3. Click **Create Term** or **Create Quality Clause**.
4. Fill in the fields:
   * For a term:
     * **Title** (required): name of the term as it appears on the PO.
     * **Requirement** (optional): full text of the term or condition (rich text).
   * For a quality clause:
     * **Reference** (required): a short identifier code for the clause, for example `QC-101`.
     * **Title** (required): name of the clause as it appears on the PO.
     * **Requirement** (optional): full text of the quality clause (rich text).
5. Click **Create**.

## Edit a requirement

1. In ION, go to **Settings > Supply Chain > Requirements**.
2. Select the tab for the requirement type: **Terms** or **Quality Clauses**.
3. In the list, click the requirement's **Title**.
4. Make your changes and click **Save**.

## Delete a requirement

1. In ION, go to **Settings > Supply Chain > Requirements**.
2. Select the tab for the requirement type: **Terms** or **Quality Clauses**.
3. In the actions column of the requirement's row, click the trash icon.
4. Confirm the deletion in the dialog, then click **Delete**.

<Warning>
  Deleting a requirement removes it permanently. This cannot be undone.
</Warning>

## Related

* [Set purchase order defaults](/administration/supply-chain-settings/set-purchase-order-defaults)


# Manage units of measure
Source: https://docs.firstresonance.io/administration/supply-chain-settings/manage-units-of-measure

Add and remove the units of measure available for inventory quantities in ION.

Units of measure are the quantity labels available when tracking inventory (for example, `each`, `kg`, `m`).

## Add a unit of measure

1. In ION, go to **Settings > Supply Chain > Inventory**.
2. In the **Units of measure** field, type the unit you want to add.
3. Press **Enter** or click **Add**.

## Remove a unit of measure

1. In ION, go to **Settings > Supply Chain > Inventory**.
2. In the units list, click **X** next to the unit you want to remove.


# Set purchase order defaults
Source: https://docs.firstresonance.io/administration/supply-chain-settings/set-purchase-order-defaults

Pre-populate default locations, currency, and payment terms on new purchase orders in ION.

Purchase order defaults are pre-filled on new POs, so your team doesn't have to set them manually every time.

## Set purchase order defaults

1. In ION, go to **Settings > Supply Chain > Purchases**.
2. Configure the default values:
   * **Default ship to location**: The location pre-populated in the ship-to field.
   * **Default bill to location**: The location pre-populated in the bill-to field.
   * **Default currency**: The currency pre-selected on new POs.
   * **Default terms**: The payment terms pre-selected on new POs.

## Related

* [Configure purchase order approval workflow](/administration/supply-chain-settings/configure-purchase-order-approval)


# Set working time
Source: https://docs.firstresonance.io/administration/supply-chain-settings/set-working-time

Define which days of the week count as working days when Autoplan schedules the parts you make. Purchased-part lead times always use calendar days.

Working time controls which days ION counts as working days when calculating lead times in plans. The value is a standard cron expression. ION reads the day-of-week field (the fifth field) to determine which days count as working days.

For example, `* * * * 1-5` means Monday through Friday.

For the full cron specification, see the [crontab manpage](https://man7.org/linux/man-pages/man5/crontab.5.html).

## What working time applies to

Working time applies when Autoplan schedules parts your organization makes: parts with a make or dual-source sourcing strategy. When Autoplan counts back from a need date to a start date for a made part, it counts only working days, and the start date always lands on a working day.

Purchased-part lead times always use calendar days. Suppliers quote lead times in calendar time, so a supplier lead time of 35 days means 35 calendar days regardless of the working time setting.

<Tip>
  If you record purchased-part lead times in business days, convert them to calendar days when entering them in ION. For a Monday through Friday schedule, multiply by 7/5. For example, 35 business days is about 49 calendar days.
</Tip>

Working time affects only Autoplan scheduling. Purchase order dates, run schedules, and due dates elsewhere in ION use calendar days.

## Set working time

1. In ION, go to **Settings > Supply Chain > Plans**.
2. In the **Working time** field, enter a cron expression.

## Related

* [Configure demand settings](/administration/supply-chain-settings/configure-demand-settings)


# Deactivate a user
Source: https://docs.firstresonance.io/administration/users-and-permissions/deactivate-a-user

Remove a user's access to ION without deleting their history or records.

Deactivating a user revokes their ability to log in to ION. Their account, activity history, and any records they created are preserved.

## Deactivate a user

1. In ION, go to **Settings > Users**.
2. On the user's row, click the actions menu (three dots).
3. Click **Deactivate User**.

The user can no longer log in. They remain visible in the **Users** list with a deactivated status.

## Reactivate a user

1. In ION, go to **Settings > Users**.
2. On the user's row, click the actions menu (three dots).
3. Click **Activate User**. The user can log in again and their status changes to active in the Users list.

## Related

* [Invite a user](/administration/users-and-permissions/invite-a-user)
* [Manage user roles](/administration/users-and-permissions/manage-user-roles)


# Overview
Source: https://docs.firstresonance.io/administration/users-and-permissions/index

ION's access model: users, roles, and teams, how permissions flow, and the full permissions reference.

ION's access model has three building blocks:

* A **user** is an individual with sign-in credentials.
* A **role** is a named, reusable set of permissions.
* A **team** is a group of users you assign, notify, and route sign-offs to together.

## How permissions flow

Permissions attach to roles, never to users directly. A user's access is the union of every role they hold, whether assigned to them directly or through a team they belong to. Roles are **additive**: adding one only grants access, so to narrow what someone can do, give them a role with fewer permissions rather than trying to subtract. Teams hold no permissions of their own, but a role assigned to a team grants its permissions to every current and future member.

Permissions are organized into groups by feature area. Every create, update, and delete action has a permission; read actions generally don't, and read access is managed separately. Changes take effect immediately, and removing a permission from a role removes it from every user and team that holds it. To see a user's effective access, combine the roles on their profile with the roles from their teams.

## Provisioning

| Approach              | How it works                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manual                | Invite users and assign roles directly in ION.                                                                                                                |
| SSO with role mapping | Roles map from your identity provider's groups (Okta, Entra ID) when users sign in. See [Set up SSO](/administration/authentication-settings/sso/set-up-sso). |

## Common roles

Most manufacturing organizations converge on a handful of roles:

| Role                       | What they can do                                                            |
| -------------------------- | --------------------------------------------------------------------------- |
| **Operator**               | Run procedures, file issues. Can't edit procedures or close their own runs. |
| **Lead Operator**          | Everything an Operator can do, plus run review and close.                   |
| **Manufacturing Engineer** | Author procedures, manage parts, schedule runs.                             |
| **Quality Engineer**       | Manage issues, dispositions, CAPAs; read across the org.                    |
| **Buyer / Planner**        | Manage POs, receipts, inventory.                                            |
| **Admin**                  | Org settings, users, integrations.                                          |
| **Read-only**              | View everything, change nothing.                                            |

**Admin** and **Read-only** are system roles: grant them directly to a user, not to a team.

<Tip>
  Pick role names that age well ("Operator," not "FactoryFloorTier1"): renaming a role in use across many users is painful. Keep admin and org-settings access to a small circle, and review role permissions periodically as people change jobs.
</Tip>

## Permissions reference

Permissions control which actions a role can perform, and you assign them to roles, not to individual users. Read permissions (what a role can view) are managed separately and aren't listed here. To add permissions to a role, see [Manage role permissions](/administration/users-and-permissions/manage-role-permissions).

| Permission                                         | Description                                                                          |
| -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `addAssetToItem`                                   | Add an existing file attachment as an asset to an item.                              |
| `addFileAttachmentToItem`                          | Add an existing file attachment to an item.                                          |
| `addHeaderToWebhookReceiver`                       | Add headers to a webhook receiver configuration.                                     |
| `addInputToPlan`                                   | Add inputs to a plan.                                                                |
| `addInventoriesToReceipt`                          | Add multiple inventories to a receipt.                                               |
| `addInventoryToPurchaseOrderLine`                  | Add inventory to a purchase order line.                                              |
| `addInventoryToReceipt`                            | Add a quantity of inventory to a receipt.                                            |
| `addItemsToReceipt`                                | Add items to a receipt from a purchase order, or without a PO.                       |
| `addLabelToItem`                                   | Add labels to an item (run, procedure, kit, etc.).                                   |
| `addLabelToProcedureFamily`                        | Add labels to a procedure family.                                                    |
| `addOauthRedirectUri`                              | Add a callback URL or allowed origin to an OAuth app.                                |
| `addPartInventoryToRunStep`                        | Add part inventory to a run step.                                                    |
| `addPartsToKitFromMbom`                            | Add parts to a kit from an mBOM using the button on the kits page.                   |
| `addPlanItemToPlan`                                | Add plan items to a plan in the results table, outside of plan inputs.               |
| `addRequirementToItem`                             | Add requirements to an item (for example, adding terms to a PO).                     |
| `addResultToPlanItem`                              | Add results to a plan item.                                                          |
| `addSubtypeToPart`                                 | Add subtypes to a part (for example, Tool).                                          |
| `addUserToTeam`                                    | Add users to a team.                                                                 |
| `archiveRun`                                       | Archive a run.                                                                       |
| `attachPermissionGroupToRole`                      | Attach permission groups to a role.                                                  |
| `attachRoleToTeam`                                 | Attach roles to a team.                                                              |
| `attachRoleToUser`                                 | Attach roles to a user.                                                              |
| `batchRunSteps`                                    | Group multiple run steps into a batch for simultaneous execution.                    |
| `cancelRun`                                        | Cancel a run.                                                                        |
| `cancelRunStepRedline`                             | Cancel a redline.                                                                    |
| `checkIn`                                          | Check in to a run.                                                                   |
| `checkOut`                                         | Check out of a run.                                                                  |
| `checkSsoConnectionStatus`                         | Check whether SSO setup is complete.                                                 |
| `cloneProcedure`                                   | Clone a procedure.                                                                   |
| `convertResultsFromPlanItem`                       | Convert results from a plan item.                                                    |
| `convertResultsFromPlanItems`                      | Convert results from multiple plan items.                                            |
| `copyField`                                        | Copy a field in a step.                                                              |
| `copyPurchaseOrder`                                | Copy a purchase order.                                                               |
| `copyPurchaseOrderLine`                            | Copy a line item from a purchase order.                                              |
| `copyStandardStep`                                 | Copy a standard step.                                                                |
| `copyStep`                                         | Copy a step.                                                                         |
| `copyStepToRun`                                    | Copy a step to a run.                                                                |
| `createAbomForPartInventory`                       | Create an aBOM for part inventory.                                                   |
| `createAbomInstallation`                           | Create an aBOM installation.                                                         |
| `createApiKey`                                     | Create an API key.                                                                   |
| `createApprovalLevel`                              | Create an approval level in an approval workflow.                                    |
| `createAsset`                                      | Add an asset to a run or procedure (for example, a file attachment).                 |
| `createBarcodeLabel`                               | Create a barcode label from inventory, kits, or locations.                           |
| `createBarcodePattern`                             | Create a new barcode pattern in organization settings.                               |
| `createBarcodePrintRequest`                        | Generate a print request for barcodes.                                               |
| `createBarcodeTemplate`                            | Create a barcode template in organization settings.                                  |
| `createBuildRequirement`                           | Create a build requirement for an aBOM.                                              |
| `createBuildRequirementReferenceDesignator`        | Create a build requirement reference designator for an aBOM.                         |
| `createBuildRequirementSubstitute`                 | Create a build requirement substitute for an aBOM.                                   |
| `createComment`                                    | Write comments in ION.                                                               |
| `createContact`                                    | Create a contact.                                                                    |
| `createCurrency`                                   | Create a currency (API only).                                                        |
| `createDatagridColumn`                             | Create a datagrid column in a datagrid step.                                         |
| `createDatagridRow`                                | Create a datagrid row in a datagrid step.                                            |
| `createDiffRequest`                                | Create a request to compare two objects, for example two versions of a procedure.    |
| `createFileAttachment`                             | Upload a file attachment.                                                            |
| `createFurtherAction`                              | Create a further action (a corrective or preventive action).                         |
| `createFurtherActionApproval`                      | Approve a further action.                                                            |
| `createFurtherActionApprovalRequest`               | Request approval of a further action.                                                |
| `createFurtherActionApprovalRole`                  | Add a role that can approve a further action.                                        |
| `createFurtherActionIssue`                         | Link a further action to an issue.                                                   |
| `createFurtherActionPart`                          | Link a further action to a part.                                                     |
| `createFurtherActionRun`                           | Link a further action to a run.                                                      |
| `createImportJob`                                  | Create an import job.                                                                |
| `createIntentOption`                               | Create an intent option.                                                             |
| `createInvite`                                     | Invite another person to ION.                                                        |
| `createIssue`                                      | Create an issue ticket.                                                              |
| `createIssueApproval`                              | Approve an issue.                                                                    |
| `createIssueApprovalRequest`                       | Ask someone to approve an issue.                                                     |
| `createIssueDispositionType`                       | Create an issue disposition type in organization settings.                           |
| `createIssueDispositionTypeRole`                   | Select the role that can approve a disposition type on an issue.                     |
| `createIssuePartInventory`                         | Link part inventory to an issue.                                                     |
| `createIssueRelation`                              | Add related issues.                                                                  |
| `createIssues`                                     | Bulk create issues.                                                                  |
| `createKitForRun`                                  | Create a kit from a run.                                                             |
| `createLabel`                                      | Create a label to tag a kit, procedure, run, etc.                                    |
| `createLocation`                                   | Create a new location.                                                               |
| `createLocationSubtype`                            | Create a location subtype.                                                           |
| `createMbom`                                       | Create an mBOM.                                                                      |
| `createMbomApproval`                               | Approve an mBOM.                                                                     |
| `createMbomApprovalRequest`                        | Request approval of an mBOM.                                                         |
| `createMbomApprovalRole`                           | Add roles to approve an mBOM.                                                        |
| `createMbomItem`                                   | Add parts to an mBOM.                                                                |
| `createMbomItemReferenceDesignator`                | Add reference designators to mBOM items.                                             |
| `createMbomSubstitute`                             | Add a substitute to an mBOM item.                                                    |
| `createMbomSubstitutes`                            | Add more than one substitute to an mBOM item.                                        |
| `createMrpJob`                                     | Create a material requirements planning (MRP) job in Autoplan.                       |
| `createMultipleMbomItems`                          | Import an mBOM.                                                                      |
| `createOrganizationDomain`                         | Add a domain to claim for the organization.                                          |
| `createOrganizationGlobalUniqueSerialNumberScheme` | Create a serial number scheme for the organization.                                  |
| `createOrganizationPartRevisionScheme`             | Create a part revision scheme for the organization.                                  |
| `createOrUpdateMultipleMboms`                      | Create or update multiple mBOMs.                                                     |
| `createOrUpdateMultipleMbomsCsv`                   | Create or update multiple mBOMs from a CSV file.                                     |
| `createOrUpdateMultipleParts`                      | Create or update multiple parts.                                                     |
| `createPart`                                       | Create a new part library item.                                                      |
| `createPartInventories`                            | Bulk create part inventories.                                                        |
| `createPartInventory`                              | Create a part inventory.                                                             |
| `createPartKit`                                    | Create a part kit.                                                                   |
| `createPartKitItem`                                | Add parts to a kit.                                                                  |
| `createPartKitItems`                               | Add multiple parts to a kit.                                                         |
| `createPartProcedure`                              | Create a part-procedure relationship.                                                |
| `createPartRevision`                               | Create a part revision.                                                              |
| `createPartSubtype`                                | Create a part subtype (used for tools).                                              |
| `createPlan`                                       | Create a plan.                                                                       |
| `createPlanConstraint`                             | Create a plan constraint.                                                            |
| `createPlanItem`                                   | Create a plan item.                                                                  |
| `createPlanItemAllocation`                         | Create a plan item allocation.                                                       |
| `createPlanReservation`                            | Create a plan reservation.                                                           |
| `createPrintJob`                                   | Create a print job, for example to print barcode labels.                             |
| `createProcedure`                                  | Create a procedure.                                                                  |
| `createProcedureApproval`                          | Approve a procedure.                                                                 |
| `createProcedureApprovalRequest`                   | Request approval of a procedure.                                                     |
| `createProcedureApprovalRole`                      | Add a role that can approve a procedure.                                             |
| `createProcedureVersion`                           | Create a version of a procedure.                                                     |
| `createPurchaseOrder`                              | Create a purchase order.                                                             |
| `createPurchaseOrderApproval`                      | Approve a purchase order.                                                            |
| `createPurchaseOrderApprovalLevel`                 | Create an approval level for a purchase order.                                       |
| `createPurchaseOrderApprovalRequest`               | Ask another user to approve a purchase order.                                        |
| `createPurchaseOrderFee`                           | Add a fee to a purchase order.                                                       |
| `createPurchaseOrderLine`                          | Create a purchase order line.                                                        |
| `createReceipt`                                    | Create a receipt.                                                                    |
| `createRedlineApproval`                            | Approve a redline on a run.                                                          |
| `createRedlineApprovalRequest`                     | Ask another user to approve redlines.                                                |
| `createRedlineApprovalRequests`                    | Request approval of multiple redlines.                                               |
| `createRedlineApprovalRole`                        | Add a role that can approve a redline.                                               |
| `createRedlineApprovals`                           | Approve multiple redlines.                                                           |
| `createRedlineRoleBasedApproval`                   | Approve a redline as part of a role-based approval.                                  |
| `createRedlineRoleBasedApprovalRequest`            | Request role-based approval of a redline.                                            |
| `createRedlineRoleBasedApprovalRequests`           | Request role-based approval of multiple redlines.                                    |
| `createRedlineRoleBasedApprovals`                  | Approve multiple redlines as part of role-based approvals.                           |
| `createRequirement`                                | Create a requirement for purchasing.                                                 |
| `createReview`                                     | Create a review (via mBOMs, issues, procedures, etc.).                               |
| `createReviewRequest`                              | Create a review request.                                                             |
| `createRole`                                       | Create a new role.                                                                   |
| `createRule`                                       | Create a new rule.                                                                   |
| `createRun`                                        | Create a new run.                                                                    |
| `createRunBatch`                                   | Create a run batch.                                                                  |
| `createRuns`                                       | Bulk create runs.                                                                    |
| `createRunStep`                                    | Create a run step.                                                                   |
| `createRunStepEdge`                                | Create a run step dependency.                                                        |
| `createRunStepField`                               | Create a run step field.                                                             |
| `createRunStepFieldValidation`                     | Add a run step field validation.                                                     |
| `createSnapshotExportJob`                          | Create a snapshot export job.                                                        |
| `createSsoSetupTicket`                             | Generate a self-service SSO setup link for an organization admin.                    |
| `createStandardStepVersion`                        | Create a new version of a standard step.                                             |
| `createStep`                                       | Create a new step in a procedure.                                                    |
| `createStepApproval`                               | Create a step approval.                                                              |
| `createStepApprovalRequest`                        | Create a step approval request.                                                      |
| `createStepApprovalRole`                           | Add a role that can approve a step.                                                  |
| `createStepEdge`                                   | Create a step dependency.                                                            |
| `createStepField`                                  | Create a step field.                                                                 |
| `createStepFieldValidation`                        | Create a step field validation.                                                      |
| `createStepPartRequirement`                        | Create an association between a step and an mBOM item.                               |
| `createStepRoleBasedApproval`                      | Approve a step as part of a role-based approval.                                     |
| `createStepRoleBasedApprovalRequest`               | Request role-based approval of a step.                                               |
| `createSupplier`                                   | Create a new supplier in the purchasing module.                                      |
| `createSupplierPart`                               | Create a part supplier.                                                              |
| `createTeam`                                       | Create a new team.                                                                   |
| `createUnitOfMeasurement`                          | Create a new unit of measurement.                                                    |
| `createUserSubscription`                           | Subscribe yourself or another user to something in ION.                              |
| `createWebhookHeader`                              | Create a webhook header.                                                             |
| `createWebhookReceiver`                            | Create a webhook receiver.                                                           |
| `createWebhookSubscription`                        | Create a webhook subscription.                                                       |
| `deleteAbomInstallation`                           | Delete an aBOM installation.                                                         |
| `deleteApiKey`                                     | Delete an API key.                                                                   |
| `deleteApprovalLevel`                              | Delete an approval level from an approval workflow.                                  |
| `deleteAsset`                                      | Delete an asset such as a file attachment.                                           |
| `deleteBarcodePattern`                             | Delete a barcode pattern.                                                            |
| `deleteBuildRequirement`                           | Delete a build requirement.                                                          |
| `deleteBuildRequirementReferenceDesignator`        | Delete a build requirement reference designator.                                     |
| `deleteBuildRequirementSubstitute`                 | Delete a build requirement substitute.                                               |
| `deleteComment`                                    | Delete a comment.                                                                    |
| `deleteContact`                                    | Delete a contact.                                                                    |
| `deleteCurrency`                                   | Delete a currency.                                                                   |
| `deleteDatagridColumn`                             | Delete a datagrid column.                                                            |
| `deleteDatagridColumns`                            | Delete multiple columns from a datagrid.                                             |
| `deleteDatagridRow`                                | Delete a datagrid row.                                                               |
| `deleteDatagridRows`                               | Delete multiple rows from a datagrid.                                                |
| `deleteFileAttachment`                             | Delete a file attachment.                                                            |
| `deleteFurtherActionApprovalRequest`               | Delete a further action approval request.                                            |
| `deleteFurtherActionApprovalRole`                  | Remove a role from a further action approval.                                        |
| `deleteFurtherActionIssue`                         | Remove the link between a further action and an issue.                               |
| `deleteFurtherActionPart`                          | Remove the link between a further action and a part.                                 |
| `deleteFurtherActionRun`                           | Remove the link between a further action and a run.                                  |
| `deleteIntentOption`                               | Delete an intent option.                                                             |
| `deleteIssueApprovalRequest`                       | Delete an issue approval request.                                                    |
| `deleteIssueDispositionType`                       | Delete an issue disposition type.                                                    |
| `deleteIssueDispositionTypeRole`                   | Delete an issue disposition type role.                                               |
| `deleteIssuePartInventory`                         | Delete an issue part inventory.                                                      |
| `deleteIssueRelation`                              | Delete an issue relation.                                                            |
| `deleteLabel`                                      | Delete a label.                                                                      |
| `deleteLocation`                                   | Delete a location.                                                                   |
| `deleteLocationSubtype`                            | Delete a location subtype.                                                           |
| `deleteMbom`                                       | Delete an mBOM.                                                                      |
| `deleteMbomApprovalRequest`                        | Delete an mBOM approval request.                                                     |
| `deleteMbomApprovalRole`                           | Delete an mBOM approval role.                                                        |
| `deleteMbomItem`                                   | Delete an mBOM item.                                                                 |
| `deleteMbomItemReferenceDesignator`                | Delete an mBOM item reference designator.                                            |
| `deleteMbomSubstitute`                             | Delete an mBOM substitute.                                                           |
| `deleteOauthApp`                                   | Delete an OAuth application registration.                                            |
| `deleteOrganizationDomain`                         | Remove a claimed domain from the organization.                                       |
| `deleteOrganizationFurtherActionAttributes`        | Delete further action custom attributes for the organization.                        |
| `deleteOrganizationGlobalUniqueSerialNumberScheme` | Delete a global unique serial number scheme for the organization.                    |
| `deleteOrganizationIssueAttributes`                | Delete issue custom attributes for the organization.                                 |
| `deleteOrganizationLocationAttributes`             | Delete location custom attributes for the organization.                              |
| `deleteOrganizationMbomAttributes`                 | Delete mBOM custom attributes for the organization.                                  |
| `deleteOrganizationPartAttributes`                 | Delete part custom attributes for the organization.                                  |
| `deleteOrganizationPartInventoryAttributes`        | Delete part inventory custom attributes for the organization.                        |
| `deleteOrganizationPartKitAttributes`              | Delete part kit custom attributes for the organization.                              |
| `deleteOrganizationPartKitItemAttributes`          | Delete part kit item custom attributes for the organization.                         |
| `deleteOrganizationPartRevisionScheme`             | Delete a part revision scheme for the organization.                                  |
| `deleteOrganizationPlanAttributes`                 | Delete plan custom attributes for the organization.                                  |
| `deleteOrganizationProcedureAttributes`            | Delete procedure custom attributes for the organization.                             |
| `deleteOrganizationPurchaseOrderAttributes`        | Delete purchase order custom attributes for the organization.                        |
| `deleteOrganizationPurchaseOrderLineAttributes`    | Delete purchase order line custom attributes for the organization.                   |
| `deleteOrganizationReceiptAttributes`              | Delete receipt custom attributes for the organization.                               |
| `deleteOrganizationRunAttributes`                  | Delete run custom attributes for the organization.                                   |
| `deleteOrganizationRunStepAttributes`              | Delete run step custom attributes for the organization.                              |
| `deleteOrganizationStepAttributes`                 | Delete step custom attributes for the organization.                                  |
| `deleteOrganizationSupplierAttributes`             | Delete supplier custom attributes for the organization.                              |
| `deletePart`                                       | Delete a part.                                                                       |
| `deletePartInventory`                              | Delete part inventory.                                                               |
| `deletePartInventoryBuildRequirement`              | Delete a build requirement from part inventory.                                      |
| `deletePartKit`                                    | Delete a part kit.                                                                   |
| `deletePartKitItem`                                | Delete a part kit item.                                                              |
| `deletePartProcedure`                              | Delete a part-procedure relationship.                                                |
| `deletePartSubtype`                                | Delete a part subtype.                                                               |
| `deletePlan`                                       | Delete a plan.                                                                       |
| `deletePlanConstraint`                             | Delete a plan constraint.                                                            |
| `deletePlanItem`                                   | Delete a plan item.                                                                  |
| `deletePlanItemAllocation`                         | Delete a plan item allocation.                                                       |
| `deletePlanReservation`                            | Delete a plan reservation.                                                           |
| `deleteProcedure`                                  | Delete a procedure.                                                                  |
| `deleteProcedureApprovalRequest`                   | Delete a procedure approval request.                                                 |
| `deleteProcedureApprovalRole`                      | Remove a role that can approve a procedure.                                          |
| `deleteProcedureMbom`                              | Delete the mBOM associated with a procedure.                                         |
| `deletePurchaseOrder`                              | Delete a purchase order.                                                             |
| `deletePurchaseOrderApprovalLevel`                 | Delete an approval level for a purchase order.                                       |
| `deletePurchaseOrderApprovalRequest`               | Delete a purchase order approval request.                                            |
| `deletePurchaseOrderFee`                           | Delete a purchase order fee.                                                         |
| `deletePurchaseOrderLine`                          | Delete a purchase order line.                                                        |
| `deleteReceipt`                                    | Delete a receipt.                                                                    |
| `deleteRedlineApprovalRequest`                     | Delete a redline approval request.                                                   |
| `deleteRedlineApprovalRole`                        | Remove a role from a redline approval.                                               |
| `deleteRedlineRoleBasedApprovalRequest`            | Delete a redline role-based approval request.                                        |
| `deleteRequirement`                                | Delete a requirement.                                                                |
| `deleteReviewRequest`                              | Delete a review request.                                                             |
| `deleteRole`                                       | Delete a role.                                                                       |
| `deleteRule`                                       | Delete a rule.                                                                       |
| `deleteRunStep`                                    | Delete a run step.                                                                   |
| `deleteRunStepEdge`                                | Delete a run step dependency.                                                        |
| `deleteRunStepField`                               | Delete a run step field.                                                             |
| `deleteRunStepFieldValidation`                     | Delete a run step field validation.                                                  |
| `deleteStep`                                       | Delete a step.                                                                       |
| `deleteStepApprovalRequest`                        | Delete a step approval request.                                                      |
| `deleteStepApprovalRole`                           | Remove a role from a step approval.                                                  |
| `deleteStepEdge`                                   | Delete a step dependency.                                                            |
| `deleteStepField`                                  | Delete a step field.                                                                 |
| `deleteStepFieldValidation`                        | Delete a step field validation.                                                      |
| `deleteStepPartRequirement`                        | Delete an association between a step and an mBOM item.                               |
| `deleteStepRoleBasedApprovalRequest`               | Delete a step role-based approval request.                                           |
| `deleteSupplier`                                   | Delete a supplier.                                                                   |
| `deleteSupplierPart`                               | Delete a part supplier.                                                              |
| `deleteTeam`                                       | Delete a team.                                                                       |
| `deleteUnitOfMeasurement`                          | Delete a unit of measurement.                                                        |
| `deleteUserSubscription`                           | Delete a user subscription.                                                          |
| `deleteWebhookHeader`                              | Delete a webhook header.                                                             |
| `deleteWebhookReceiver`                            | Delete a webhook receiver.                                                           |
| `deleteWebhookSubscription`                        | Delete a webhook subscription.                                                       |
| `detachPermissionGroupFromRole`                    | Detach a permission group from a role.                                               |
| `detachRoleFromTeam`                               | Detach a role from a team.                                                           |
| `detachRoleFromUser`                               | Detach a role from a user.                                                           |
| `disableSsoConnection`                             | Disable the enterprise SSO connection for the organization.                          |
| `dispatchNotification`                             | Dispatch notifications.                                                              |
| `generateReadEmbeddedAnalytics`                    | Generate read operations for embedded analytics.                                     |
| `generateRunSummary`                               | Generate a summary of a run.                                                         |
| `generateWriteEmbeddedAnalytics`                   | Generate write operations for embedded analytics.                                    |
| `importKitItems`                                   | Import kit items.                                                                    |
| `importKitItemsCsv`                                | Import kit items from a CSV file.                                                    |
| `importStepsFromPdf`                               | Import steps from a PDF document.                                                    |
| `installKitOnAbom`                                 | Install a kit on an aBOM.                                                            |
| `inviteOrganizationMember`                         | Send an invitation email to a new organization member.                               |
| `issueItemToKit`                                   | Issue an item to a kit.                                                              |
| `linkOrganizationToAuth0`                          | Link an existing organization to its identity provider.                              |
| `linkRunStepToPurchaseOrder`                       | Link an outside-processing run step to a purchase order.                             |
| `mergePartInventory`                               | Merge part inventory.                                                                |
| `mergePartInventoryV2`                             | Merge multiple part inventory records into one.                                      |
| `mergeRunStep`                                     | Merge a run step.                                                                    |
| `mergeRunStepToProcedure`                          | Merge a run step into a procedure.                                                   |
| `mergeRunStepToRuns`                               | Merge a run step into runs.                                                          |
| `moveItemToInventory`                              | Move an item to inventory.                                                           |
| `moveKitInventoryToLocation`                       | Move kit inventory to a location.                                                    |
| `provisionCustomer`                                | Provision a new customer organization.                                               |
| `registerOauthApp`                                 | Register a new OAuth application for the organization.                               |
| `removeAllInventoryFromKit`                        | Remove all inventory allocated to a kit.                                             |
| `removeAssetFromItem`                              | Remove an asset from an item without deleting the file attachment.                   |
| `removeHeaderFromWebhookReceiver`                  | Remove a header from a webhook receiver.                                             |
| `removeInputFromPlan`                              | Remove an input from a plan.                                                         |
| `removeInventoryFromPurchaseOrderLine`             | Remove inventory from a purchase order line.                                         |
| `removeInventoryFromReceipt`                       | Remove inventory from a receipt.                                                     |
| `removeItemFromReceipt`                            | Remove an item from a receipt.                                                       |
| `removeLabelFromItem`                              | Remove a label from an item.                                                         |
| `removeLabelFromProcedureFamily`                   | Remove a label from a procedure family.                                              |
| `removeOauthRedirectUri`                           | Remove a callback URL or allowed origin from an OAuth app.                           |
| `removePartInventoryFromRunStep`                   | Remove part inventory from a run step.                                               |
| `removePlanItemFromPlan`                           | Remove a plan item from a plan.                                                      |
| `removeRequirementFromItem`                        | Remove a requirement from an item.                                                   |
| `removeResultFromPlanItem`                         | Remove a result from a plan item.                                                    |
| `removeSubtypeFromPart`                            | Remove a subtype from a part.                                                        |
| `removeUserFromTeam`                               | Remove a user from a team.                                                           |
| `reorderApprovalLevel`                             | Reorder an approval level in an approval workflow.                                   |
| `reorderDatagridColumn`                            | Reorder datagrid columns.                                                            |
| `reorderDatagridRow`                               | Reorder datagrid rows.                                                               |
| `reorderIntentOptions`                             | Reorder intent options.                                                              |
| `reorderPurchaseOrderLine`                         | Reorder purchase order lines.                                                        |
| `reorderRunStepFields`                             | Reorder run step fields.                                                             |
| `reorderRunSteps`                                  | Reorder run steps.                                                                   |
| `reorderStepFields`                                | Reorder step fields.                                                                 |
| `reorderSteps`                                     | Reorder steps.                                                                       |
| `resendInvite`                                     | Resend an invitation.                                                                |
| `resetIssueApprovals`                              | Reset issue approvals.                                                               |
| `resetPurchaseOrderApprovalLevels`                 | Reset the approval levels on a purchase order.                                       |
| `revokeInvite`                                     | Revoke an invitation.                                                                |
| `rotateSsoSigningCredentials`                      | Replace the identity provider signing certificate or metadata on the SSO connection. |
| `saveReceipt`                                      | Save a receipt after adding or removing items.                                       |
| `setDatagridValue`                                 | Set the value of a datagrid cell.                                                    |
| `splitManyPartInventory`                           | Split multiple part inventories.                                                     |
| `splitPartInventory`                               | Split part inventory.                                                                |
| `splitUnfulfilledPartKit`                          | Split an unfulfilled part kit.                                                       |
| `submitRunAbomJustification`                       | Submit the aBOM completion justification on a run.                                   |
| `unbatchRunSteps`                                  | Remove run steps from a batch.                                                       |
| `unlinkRunStepFromPurchaseOrder`                   | Unlink an outside-processing run step from its purchase order.                       |
| `updateAbomInstallation`                           | Update an aBOM installation.                                                         |
| `updateApiKey`                                     | Update an API key.                                                                   |
| `updateApprovalLevel`                              | Update an approval level in an approval workflow.                                    |
| `updateBarcodeLabel`                               | Update a barcode label.                                                              |
| `updateBarcodePattern`                             | Update a barcode pattern.                                                            |
| `updateBarcodeTemplate`                            | Update a barcode template.                                                           |
| `updateBuildRequirement`                           | Update a build requirement.                                                          |
| `updateBuildRequirementReferenceDesignator`        | Update a build requirement reference designator.                                     |
| `updateBuildRequirementSubstitute`                 | Update a build requirement substitute.                                               |
| `updateComment`                                    | Update a comment.                                                                    |
| `updateContact`                                    | Update a contact.                                                                    |
| `updateCurrency`                                   | Update a currency.                                                                   |
| `updateDatagridColumn`                             | Update a datagrid column.                                                            |
| `updateDatagridRow`                                | Update a datagrid row.                                                               |
| `updateFurtherAction`                              | Update a further action.                                                             |
| `updateFurtherActionApproval`                      | Update a further action approval.                                                    |
| `updateFurtherActionApprovalRequest`               | Update a further action approval request.                                            |
| `updateFurtherActionApprovalRole`                  | Update a further action approval role.                                               |
| `updateImportJob`                                  | Update an import job.                                                                |
| `updateInputToPlan`                                | Update a plan input.                                                                 |
| `updateIntentOption`                               | Update an intent option.                                                             |
| `updateIssue`                                      | Update an issue.                                                                     |
| `updateIssueApproval`                              | Update an issue approval.                                                            |
| `updateIssueApprovalRequest`                       | Update an issue approval request.                                                    |
| `updateIssueAttribute`                             | Update an issue custom attribute.                                                    |
| `UpdateIssueAttributes`                            | Update the custom attribute values on an issue.                                      |
| `updateIssueDispositionType`                       | Update an issue disposition type.                                                    |
| `updateIssueDispositionTypeRole`                   | Update an issue disposition type role.                                               |
| `updateLabel`                                      | Update a label.                                                                      |
| `updateLocation`                                   | Update a location.                                                                   |
| `updateLocationAttribute`                          | Update a location custom attribute.                                                  |
| `UpdateLocationAttributes`                         | Update the custom attribute values on a location.                                    |
| `updateLocationSubtype`                            | Update a location subtype.                                                           |
| `updateMbom`                                       | Update an mBOM.                                                                      |
| `updateMbomApproval`                               | Update an mBOM approval.                                                             |
| `updateMbomApprovalRequest`                        | Update an mBOM approval request.                                                     |
| `updateMbomApprovalRole`                           | Update an mBOM approval role.                                                        |
| `updateMbomAttribute`                              | Update an mBOM custom attribute.                                                     |
| `UpdateMbomAttributes`                             | Update the custom attribute values on an mBOM.                                       |
| `updateMbomItem`                                   | Update an mBOM item.                                                                 |
| `updateMbomItemReferenceDesignator`                | Update an mBOM item reference designator.                                            |
| `updateMrpJob`                                     | Update an MRP job in Autoplan.                                                       |
| `updateMultiplePartInventory`                      | Update multiple part inventory records.                                              |
| `updateOauthApp`                                   | Update an OAuth application registration.                                            |
| `updateOrganization`                               | Update organization details.                                                         |
| `updateOrganizationBranding`                       | Update the branding on the organization login page.                                  |
| `updateOrganizationFurtherActionAttributes`        | Update further action custom attributes for the organization.                        |
| `updateOrganizationGlobalUniqueSerialNumberScheme` | Update a global unique serial number scheme for the organization.                    |
| `updateOrganizationIssueAttributes`                | Update issue custom attributes for the organization.                                 |
| `updateOrganizationLocationAttributes`             | Update location custom attributes for the organization.                              |
| `updateOrganizationMbomAttributes`                 | Update mBOM custom attributes for the organization.                                  |
| `updateOrganizationMfaPolicy`                      | Enable or disable the multi-factor authentication requirement for the organization.  |
| `updateOrganizationPartAttributes`                 | Update part custom attributes for the organization.                                  |
| `updateOrganizationPartInventoryAttributes`        | Update part inventory custom attributes for the organization.                        |
| `updateOrganizationPartKitAttributes`              | Update part kit custom attributes for the organization.                              |
| `updateOrganizationPartKitItemAttributes`          | Update part kit item custom attributes for the organization.                         |
| `updateOrganizationPartRevisionScheme`             | Update a part revision scheme for the organization.                                  |
| `updateOrganizationPlanAttributes`                 | Update plan custom attributes for the organization.                                  |
| `updateOrganizationProcedureAttributes`            | Update procedure custom attributes for the organization.                             |
| `updateOrganizationPurchaseOrderAttributes`        | Update purchase order custom attributes for the organization.                        |
| `updateOrganizationPurchaseOrderLineAttributes`    | Update purchase order line custom attributes for the organization.                   |
| `updateOrganizationReceiptAttributes`              | Update receipt custom attributes for the organization.                               |
| `updateOrganizationRunAttributes`                  | Update run custom attributes for the organization.                                   |
| `updateOrganizationRunStepAttributes`              | Update run step custom attributes for the organization.                              |
| `updateOrganizationStepAttributes`                 | Update step custom attributes for the organization.                                  |
| `updateOrganizationSupplierAttributes`             | Update supplier custom attributes for the organization.                              |
| `updatePart`                                       | Update a part.                                                                       |
| `updatePartAttribute`                              | Update a part custom attribute.                                                      |
| `UpdatePartAttributes`                             | Update the custom attribute values on a part.                                        |
| `updatePartInventory`                              | Update part inventory.                                                               |
| `updatePartInventoryAttribute`                     | Update a part inventory custom attribute.                                            |
| `UpdatePartInventoryAttributes`                    | Update the custom attribute values on part inventory.                                |
| `updatePartKit`                                    | Update a part kit.                                                                   |
| `updatePartKitAttribute`                           | Update a part kit custom attribute.                                                  |
| `UpdatePartKitAttributes`                          | Update the custom attribute values on a part kit.                                    |
| `updatePartKitItem`                                | Update a part kit item.                                                              |
| `updatePartKitItemAttribute`                       | Update a part kit item custom attribute.                                             |
| `UpdatePartKitItemAttributes`                      | Update the custom attribute values on a part kit item.                               |
| `updatePartProcedure`                              | Update a part-procedure relationship.                                                |
| `updatePartSubtype`                                | Update a part subtype.                                                               |
| `updatePlan`                                       | Update a plan.                                                                       |
| `updatePlanAttribute`                              | Update a plan custom attribute.                                                      |
| `UpdatePlanAttributes`                             | Update the custom attribute values on a plan.                                        |
| `updatePlanConstraint`                             | Update a plan constraint.                                                            |
| `updatePlanItem`                                   | Update a plan item.                                                                  |
| `updatePlanItemAllocation`                         | Update a plan item allocation.                                                       |
| `updatePlanReservation`                            | Update a plan reservation.                                                           |
| `updateProcedure`                                  | Update a procedure.                                                                  |
| `updateProcedureApproval`                          | Update a procedure approval.                                                         |
| `updateProcedureApprovalRequest`                   | Update a procedure approval request.                                                 |
| `updateProcedureApprovalRole`                      | Update a procedure approval role.                                                    |
| `updateProcedureAttribute`                         | Update a procedure custom attribute.                                                 |
| `UpdateProcedureAttributes`                        | Update the custom attribute values on a procedure.                                   |
| `updatePurchaseOrder`                              | Update a purchase order.                                                             |
| `updatePurchaseOrderApproval`                      | Update a purchase order approval.                                                    |
| `updatePurchaseOrderApprovalLevel`                 | Update an approval level for a purchase order.                                       |
| `updatePurchaseOrderApprovalRequest`               | Update a purchase order approval request.                                            |
| `updatePurchaseOrderAttribute`                     | Update a purchase order custom attribute.                                            |
| `UpdatePurchaseOrderAttributes`                    | Update the custom attribute values on a purchase order.                              |
| `updatePurchaseOrderFee`                           | Update a purchase order fee.                                                         |
| `updatePurchaseOrderLine`                          | Update a purchase order line.                                                        |
| `updatePurchaseOrderLineAttribute`                 | Update a purchase order line custom attribute.                                       |
| `UpdatePurchaseOrderLineAttributes`                | Update the custom attribute values on a purchase order line.                         |
| `updatePurchaseOrderLines`                         | Update multiple purchase order lines.                                                |
| `updateReceipt`                                    | Update a receipt.                                                                    |
| `updateReceiptAttribute`                           | Update a receipt custom attribute.                                                   |
| `UpdateReceiptAttributes`                          | Update the custom attribute values on a receipt.                                     |
| `updateReceiptItem`                                | Update a receipt item.                                                               |
| `updateRedline`                                    | Update a redline.                                                                    |
| `updateRedlineApproval`                            | Update a redline approval.                                                           |
| `updateRedlineApprovalRequest`                     | Update a redline approval request.                                                   |
| `updateRedlineApprovalRequests`                    | Update multiple redline approval requests.                                           |
| `updateRedlineApprovalRole`                        | Update a redline approval role.                                                      |
| `updateRedlineRoleBasedApproval`                   | Update a redline role-based approval.                                                |
| `updateRedlineRoleBasedApprovalRequest`            | Update a redline role-based approval request.                                        |
| `updateRedlineRoleBasedApprovalRequests`           | Update multiple redline role-based approval requests.                                |
| `updateRequirement`                                | Update a requirement.                                                                |
| `updateReview`                                     | Update a review.                                                                     |
| `updateReviewRequest`                              | Update a review request.                                                             |
| `updateRole`                                       | Update a role's name.                                                                |
| `updateRule`                                       | Update a rule.                                                                       |
| `updateRun`                                        | Update a run's information.                                                          |
| `updateRunAbomJustification`                       | Update the aBOM completion justification on a run.                                   |
| `updateRunAttribute`                               | Update a run custom attribute.                                                       |
| `UpdateRunAttributes`                              | Update the custom attribute values on a run.                                         |
| `updateRunBatch`                                   | Update a run batch.                                                                  |
| `updateRunInventoryLocation`                       | Update the location of inventory associated with a run.                              |
| `updateRuns`                                       | Update multiple runs.                                                                |
| `updateRunStep`                                    | Update a run step, including changing its status.                                    |
| `updateRunStepAttribute`                           | Update a run step custom attribute.                                                  |
| `UpdateRunStepAttributes`                          | Update the custom attribute values on a run step.                                    |
| `updateRunStepField`                               | Update a run step field.                                                             |
| `updateRunStepFieldValidation`                     | Update a run step field validation.                                                  |
| `updateRunStepFieldValue`                          | Update the value of a run step field.                                                |
| `updateSession`                                    | Update a check-in or check-out event.                                                |
| `updateSnapshotExportJob`                          | Update a snapshot export job.                                                        |
| `updateStep`                                       | Update step content in a procedure.                                                  |
| `updateStepApproval`                               | Update a step approval.                                                              |
| `updateStepApprovalRequest`                        | Update a step approval request.                                                      |
| `updateStepApprovalRole`                           | Update a step approval role.                                                         |
| `updateStepAttribute`                              | Update a step custom attribute in a procedure.                                       |
| `UpdateStepAttributes`                             | Update the custom attribute values on a step.                                        |
| `updateStepField`                                  | Update a step field in a procedure.                                                  |
| `updateStepFieldValidation`                        | Update a step field validation in a procedure.                                       |
| `updateStepPartRequirement`                        | Update an association between a step and an mBOM item.                               |
| `updateStepRoleBasedApproval`                      | Update a step role-based approval.                                                   |
| `updateStepRoleBasedApprovalRequest`               | Update a step role-based approval request.                                           |
| `updateSupplier`                                   | Update a supplier and their contact information.                                     |
| `updateSupplierAttribute`                          | Update a supplier's custom attributes.                                               |
| `UpdateSupplierAttributes`                         | Update the custom attribute values on a supplier.                                    |
| `updateSupplierPart`                               | Update a part supplier.                                                              |
| `updateTeam`                                       | Update a team's name and settings.                                                   |
| `updateUnitOfMeasurement`                          | Update a unit of measurement in organization settings.                               |
| `updateUser`                                       | Update a user's profile and settings.                                                |
| `updateUserNotification`                           | Update user notifications.                                                           |
| `updateWebhookHeader`                              | Update a webhook header.                                                             |
| `updateWebhookReceiver`                            | Update a webhook receiver.                                                           |
| `updateWebhookSubscription`                        | Update a webhook subscription.                                                       |
| `verifyOrganizationDomain`                         | Verify ownership of a claimed domain.                                                |


# Invite a user
Source: https://docs.firstresonance.io/administration/users-and-permissions/invite-a-user

Send an email invitation to add a new person to your ION organization.

## Invite a user

1. In ION, go to **Settings > Users**.
2. Click **Invite User**.
3. In the **Email Address** field, enter the person's email address. This field is required.
4. Optional: Add more details:
   * In the **Name (optional)** field, enter the person's name.
   * In the **Message (optional)** field, enter a message to include in the invitation email.
   * To invite more than one person at once, click **Add More** and fill in the **Email Address** field for each additional invitee. The message applies to everyone in the invitation.
5. Click **Invite**.

ION sends an invitation email to each address you entered.

## Manage pending invites

The **Pending invites** section on **Settings > Users** lists invitations that haven't been accepted yet, with each invite's email, name, status, when it was sent, and how many times it's been resent. Use the status filter to switch between **Pending**, **Accepted**, and **Revoked** invites.

1. In ION, go to **Settings > Users**.
2. Expand the **Pending invites** section.
3. For an invite that hasn't been accepted, choose an action:
   * Click **Resend invite** to send the invitation email again.
   * Click **Revoke invite**, then confirm, to invalidate the invite. The recipient can no longer use that invite link.

## Related

* [Manage user roles](/administration/users-and-permissions/manage-user-roles)
* [Manage team members](/administration/users-and-permissions/manage-team-members)
* [Deactivate a user](/administration/users-and-permissions/deactivate-a-user)


# Manage role permissions
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-role-permissions

Configure which actions a role can perform by enabling or disabling permissions on the role's detail page.

Add or remove a role's permissions on its detail page. For how permissions work, see [Users and permissions](/administration/users-and-permissions).

## Add permissions to a role

1. In ION, go to **Settings > Roles & Permissions**.
2. Click the role you want to configure.
3. On the role detail page, find the permission group you want to enable.
4. Select the checkbox next to a permission to enable it, or select the group's checkbox to enable every permission in that group at once.

To enable all permissions currently shown, click **Enable All**. The **Enable All** and **Disable All** controls apply to the permissions that match your current search and filter.

## Remove permissions from a role

On the role detail page, clear the checkbox next to a permission to disable it. To disable all permissions currently shown, click **Disable All**. Removing a permission from a role removes it from every user and team that holds that role.

## Related

* [Permissions reference](/administration/users-and-permissions#permissions-reference)
* [Create a role](/administration/users-and-permissions/manage-roles)
* [Manage user roles](/administration/users-and-permissions/manage-user-roles)
* [Manage team roles](/administration/users-and-permissions/manage-team-roles)


# Manage roles
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-roles

Create and delete the roles that group the permissions you assign to users and teams.

A role is a named set of permissions you assign to users and teams. For the access model, common role patterns, and provisioning, see [Users and permissions](/administration/users-and-permissions).

## Create a role

1. In ION, go to **Settings > Roles & Permissions**.
2. Click **New Role**.
3. Enter a name for the role and click **Create Role**.

ION creates the role and opens its detail page. The role has no permissions yet.

## Delete a role

1. In ION, go to **Settings > Roles & Permissions**.
2. In the role's actions menu, click **Delete Role**.
3. In the confirmation dialog, click **Delete**.

<Warning>
  Deleting a role also removes it from every user and team it's assigned to, which can remove those users' access. Deletion can't be undone.
</Warning>

## Related

* [Manage role permissions](/administration/users-and-permissions/manage-role-permissions)
* [Manage team roles](/administration/users-and-permissions/manage-team-roles)
* [Manage user roles](/administration/users-and-permissions/manage-user-roles)


# Manage team members
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-team-members

Add users to a team so they inherit the team's roles and can be assigned and notified as a group.

## Add users to a team

1. In ION, go to **Settings > Teams**.
2. Click the team you want to add users to.
3. In the **Users** card, click **Add Users**.
4. Select the users you want to add and click **Add Selected (N)**, where N is the number of users you selected.

The users appear in the **Users** card and immediately inherit the team's roles.

## Remove a user from a team

1. In ION, go to **Settings > Teams**.
2. Click the team the user belongs to.
3. In the **Users** card, find the user you want to remove.
4. Click the delete icon next to their name.

The user loses any permissions they held through this team. Permissions from other roles or teams are not affected.

## Related

* [Create a team](/administration/users-and-permissions/manage-teams)
* [Manage team roles](/administration/users-and-permissions/manage-team-roles)
* [Invite a user](/administration/users-and-permissions/invite-a-user)


# Manage team roles
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-team-roles

Assign roles to a team so all team members inherit those permissions.

## Add roles to a team

1. In ION, go to **Settings > Teams**.
2. Click the team you want to configure.
3. In the **Roles** card, click **Add Roles**.
4. Select the roles you want to assign and click **Add Selected (N)**, where N is the number of roles you selected.

The roles appear in the **Roles** card and take effect immediately for all team members.

System roles such as **Admin** and **Read-only** can't be assigned to teams. Grant those directly to a user instead.

## Remove a role from a team

1. In ION, go to **Settings > Teams**.
2. Click the team you want to configure.
3. In the **Roles** card, find the role you want to remove.
4. Click the delete icon next to the role name.

All team members lose the permissions from that role. Permissions held through other roles or teams are not affected.

## Related

* [Create a team](/administration/users-and-permissions/manage-teams)
* [Manage team members](/administration/users-and-permissions/manage-team-members)
* [Create a role](/administration/users-and-permissions/manage-roles)


# Manage teams
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-teams

Create and delete the teams that group users so they can be assigned and notified collectively.

## Create a team

1. In ION, go to **Settings > Teams**.
2. Click **New Team**.
3. Enter a name for the team and click **Create Team**.

ION creates the team and opens its detail page.

## Delete a team

1. In ION, go to **Settings > Teams**.
2. In the team's actions menu, click **Delete Team**.
3. Confirm the deletion.

<Warning>
  Deleting a team can't be undone.
</Warning>

## Related

* [Manage team roles](/administration/users-and-permissions/manage-team-roles)
* [Manage team members](/administration/users-and-permissions/manage-team-members)


# Manage user roles
Source: https://docs.firstresonance.io/administration/users-and-permissions/manage-user-roles

Add or remove roles directly on a user's profile to control what they can do in ION.

You can assign roles to a user directly from their profile page. This is the right approach when a user needs a role that isn't shared with a full team, or when you're setting up a single user's access without creating a team.

For assigning roles to many users at once, consider using [teams](/administration/users-and-permissions/manage-team-members) instead.

## Assign a role

1. In ION, go to **Settings > Users**.
2. Click the user's name to open their profile.
3. In the **Roles** section, click **Add**.
4. Select the roles you want to assign.

The roles appear in the user's **Roles** section and take effect immediately.

## Remove a role

1. In ION, go to **Settings > Users**.
2. Click the user's name to open their profile.
3. In the **Roles** section, find the role you want to remove.
4. Click the delete icon next to the role name.

The role is removed and the user loses any permissions they held through it. Permissions from other roles or teams are not affected.

<Note>
  Removing the last role from a user does not deactivate their account. They can still log in but cannot perform any create, update, or delete actions.
</Note>

## Related

* [Create a role](/administration/users-and-permissions/manage-roles)
* [Manage team members](/administration/users-and-permissions/manage-team-members)
* [Invite a user](/administration/users-and-permissions/invite-a-user)


# Migrate to the new aBOM API
Source: https://docs.firstresonance.io/api-reference/abom-actions-for-developers

Update API, ION Actions, webhooks, and SQL from the legacy AbomItems model to BuildRequirements and AbomInstallations.

## Actions needed

This project will introduce breaking changes.

1. **API**: If you are using the API to call any of the below mutations or a query that uses any of the below fields, you will need to update your mutations/queries.
2. **Actions**: If you have any ION actions (rules) using any of the objects below, those will be disabled when this project is released and you will need to update those after release.
3. **Webhooks**: If you have any webhooks listening to any of the objects below, you will need to update your webhook listeners after release.
4. **Analytics**: If you have any SQL queries referencing `abom_items` or `abom_edges` those will need to be updated.

If the above does not apply to you then no changes necessary!

## Changes overview

Below shows an example of a car assembly that is partially installed and the differences between the old structure and the new structure.

Old structure:

```mermaid fullWidth="false" theme={null}
graph TB
  i1([
    inventory 1
    car assembly
    SN 45
  ])
  i2([
    inventory 2
    SN 12
  ])
  i3([
    inventory 3
    SN 13
  ])
  ab1[
    abom item 1
    car assembly
    qty 1
  ]
  ab2[
    abom item 2
    wheel assembly
    qty 1
  ]
  ab3[
    abom item 3
    wheel assembly
    qty 1
  ]
  ab4[
    abom item 4
    wheel assembly
    qty 2
  ]
  ab5[
    abom item 5
    fastener
    qty 50
  ]
  i1 --- ab1
  ab1 ---> ab2
  ab1 ---> ab3
  ab1 ---> ab4
  ab1 ---> ab5
  ab2 --- i2
  ab3 --- i3

  classDef green fill:#9f6,stroke:#333,stroke-width:2px;
  class i1,i2,i3 green
  
```

New structure:

```mermaid fullWidth="false" theme={null}
graph TB
  i1([
    inventory 1
    car assembly
    SN 45
  ])
  i2([
    inventory 2
    SN 12
  ])
  i3([
    inventory 3
    SN 13
  ])
  br1[
    build requirement 1
    wheel assembly
    qty 4
  ]
  br2[
    build requirement 2
    fastener
    qty 50
  ]
  i1 ---> br1
  i1 ---> br2
  br1 --abom installation--- i2 
  br1 --abom installation--- i3

  classDef green fill:#9f6,stroke:#333,stroke-width:2px;
  class i1,i2,i3 green
  
```

Old structure:

* aBOM items represent both the requirement and fulfillment of the installation
* aBOM items are used to link to inventories
* aBOM edges connect aBOM items
* aBOM items change as items are partially installed/removed. New ones get created or deleted, or quantities change

New structure:

* Build requirements belong to parent inventories and represent what needs to be installed
* Build requirements do not change as items are installed into them
* aBOM installations link inventories to a build requirement. The addition of an aBOM installation is an install. The removal of an aBOM installation is an uninstall

## Mutation/query changes

* AbomItems will be replaced by `BuildRequirements` and `AbomInstallations`, where the requirement and fulfillment (install) are clearly delineated
* AbomEdges will be replaced by `PartInventoryBuildRequirements`

Below shows the full list of items that are going away.

### Going away

#### Mutations

* `InstallKitOnAbomItemChildren`
* `CreateAbomItem`
* `DeleteAbomItem`
* `UpdateAbomItem`

#### GQL Objects/Queries

* `AbomItems`
* `ABomEdges`
* `ABomItemReferenceDesignators`

#### Fields

* `PartInventory.abomItems`
* `PartInventory.abomChildren`
* `PartInventory.abomParents`
* `PartInventory.allChildren`
* `PartInventory.allParents`
* `Part.abomItems`
* `MBomItem.abomItems`
* `MBomItemReferenceDesignator.abomItems`
* `AbomItemReferenceDesignator.abomItem`

(and any count fields generated from these relationships)<br />

### Examples

#### API: Installing a part

Old structure:

Previously, you would have to update an existing `abom_item` with an inventory to install that inventory. The `abom_item` at that point may get swapped if the inventory being installed is already linked ot an `abom_item`

<Tabs>
  <Tab title="Update aBOM item">
    ```graphql theme={null}
    mutation UpdateABomItem($input: UpdateABomItemInput!) {
        updateAbomItem(input: $input) {
            abomItem {
                id updatedById partInventoryId
            }
        }
    }
    ```
  </Tab>

  <Tab title="Inputs">
    ```graphql theme={null}
    {
        "input": {
            "id": 1,
            "partInventoryId": 1,
            "etag": "etag"
        }
    }
    ```
  </Tab>
</Tabs>

New structure:

Now installing a part is done via creating an aBOM installation. aBOM installations link inventories to `buildRequirements`. Conversely, uninstalling a part is done by deleting aBOM installations.

<Tabs>
  <Tab title="Create aBOM installation">
    ```graphql theme={null}
    mutation CreateABomInstallation($input: CreateABomInstallationInput!) {
        createAbomInstallation(input: $input) {
            abomInstallation {
                buildRequirementId
                buildRequirementReferenceDesignatorId
                partInventoryId
                quantity
            }
        }
    }
    ```
  </Tab>

  <Tab title="Inputs">
    ```graphql theme={null}
    {
        "input": {
            "buildRequirementId": 1,
            "partInventoryId": 3,
            "quantity": 1
        }
    }

    ```
  </Tab>
</Tabs>

#### SQL: Query for an inventory's aBOM

Old structure:

```sql theme={null}
select 
parent_part.part_number,
parent_part.description,
parent_inventory.serial_number,
parent_inventory.lot_number,
parent_inventory.quantity,
child_part.part_number,
child_part.description,
child_inventory.serial_number,
child_inventory.lot_number,
child_abom_item.quantity as 'installed quantity'

from parts_inventory parent_inventory
inner join parts parent_part on parent_part.id = parent_inventory.part_id
inner join abom_items parent_abom_item on parent_inventory.id = ai.part_inventory_id
inner join abom_edges ae on ae.parent_abom_item_id = parent_abom_item.id
inner join abom_items child_abom_item on child_abom_item.id = ae.child_abom_item_id
inner join parts_inventory child_inventory on child_abom_item.part_inventory_id = child_inventory.id
inner join parts child_part on child_part.id = child_abom_item.part_id

where parent_inventory.id = 105
```

New structure:

```sql theme={null}
select 
parent_part.part_number,
parent_part.description,
parent_inventory.serial_number,
parent_inventory.lot_number,
parent_inventory.quantity,
child_part.part_number,
child_part.description,
child_inventory.serial_number,
child_inventory.lot_number,
ai.quantity as 'installed quantity'

from parts_inventory parent_inventory
inner join parts parent_part on parent_part.id = parent_inventory.part_id
inner join part_inventory_build_requirements pibr on pibr.part_inventory_id = parent_inventory.id
inner join abom_installations ai on pibr.build_requirement_id = ai.build_requirement_id
inner join parts_inventory child_inventory on ai.part_inventory_id = child_inventory.id
inner join parts child_part on child_part.id = child_abom_item.part_id

where parent_inventory.id = 105
```


# API release notes
Source: https://docs.firstresonance.io/api-reference/api-release-notes

Record of ION API changes between releases, including breaking changes and deprecation warnings.



# Manage API keys
Source: https://docs.firstresonance.io/api-reference/authentication/api-keys

Create, use, list, rotate, disable, and delete ION API keys for machine-to-machine integrations.

API keys authenticate machine-to-machine integrations. These include scripts, automations, ETL jobs, MES bridges, IoT devices, and other systems that call ION without a person signing in. You create, manage, and delete them through the API or the UI. For user-facing applications where ION enforces a specific user's permissions, use [OAuth 2.0](/api-reference/authentication/oauth) instead.

## How API keys behave

* Each API key is **specific to the environment** it was generated in. A key created in production will not work in sandbox.
* A key holds the **same permissions the creating user had at the moment it was generated**. Later changes to that user's permissions do not affect the key.
* Generating a new key does **not** invalidate previously generated keys. They keep working until disabled.
* Any automation using a key **acts on behalf of the user who created it**.
* A key is **automatically disabled when its user is deactivated**.

<Note>
  You need the `APIKeyObject` family of permissions to work with API keys. See
  the [permissions
  reference](/administration/users-and-permissions#permissions-reference) for
  details.
</Note>

<Warning>
  For automations and integrations, back the key with a [service
  account](#service-accounts) rather than an individual's user.
</Warning>

## Create a key

An org admin provisions API keys. Each key is bound to a user identity in your organization. Audit logs then reflect which integration made each call.

```graphql theme={null}
mutation CreateAPIKey {
  createApiKey {
    apikey {
      clientId
      clientSecret
    }
  }
}
```

The `clientSecret` is shown **once**. Capture it immediately and store it in a secrets manager such as AWS Secrets Manager, HashiCorp Vault, 1Password, or your CI/CD's encrypted secrets store. ION cannot retrieve a secret after creation.

## Get an access token

A key's `clientId` and `clientSecret` exchange for a short-lived access token through the client-credentials grant. ION then accepts that token on the `Authorization` header. Most integrations use a small client library that handles the exchange and caching for you. See the [Build an API client](/api-reference/guides/python-quickstart) for a runnable example.

To exchange the credentials directly, POST a `client_credentials` grant to the auth server for your environment:

```bash theme={null}
curl -X POST \
  --data-urlencode "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  https://<AUTH_SERVER>/realms/api-keys/protocol/openid-connect/token
```

The auth server and API endpoint differ per environment:

| App URL                               | Auth Server                     | API Endpoint                           |
| ------------------------------------- | ------------------------------- | -------------------------------------- |
| `app-v2.staging.buildwithion.com`     | `staging-auth.buildwithion.com` | `https://staging-api.buildwithion.com` |
| `app-v2.buildwithion.com`             | `auth.buildwithion.com`         | `https://api.buildwithion.com`         |
| `app-v2.staging.gov.buildwithion.com` | `staging-auth.ion-gov.com`      | `https://staging-api.ion-gov.com`      |
| `app-v2.gov.buildwithion.com`         | `auth.ion-gov.com`              | `https://api.ion-gov.com`              |
| `app-v2.staging.ap.buildwithion.com`  | `staging-auth.ion-aus.com`      | `https://staging-api.ion-aus.com`      |
| `app-v2.ap.buildwithion.com`          | `auth.ion-aus.com`              | `https://api.ion-aus.com`              |

Append `/graphql` to the API endpoint for query requests, for example `https://staging-api.buildwithion.com/graphql`. For more runnable scripts, see the [ion-examples repository](https://github.com/FirstResonance/ion-examples).

## List keys

List your organization's API keys:

```graphql theme={null}
query APIKeys {
  apiKeys {
    edges {
      node {
        clientId
        clientSecret
        id
        _etag
      }
    }
  }
}
```

## Enable, disable, or regenerate a secret

Update a key with this mutation:

```graphql theme={null}
mutation UpdateAPIKey($input: APIKeyInput!) {
  updateApiKey(input: $input) {
    apikey {
      clientId
      clientSecret
      enabled
    }
  }
}
```

Set the variables:

```json theme={null}
{
  "input": {
    "clientId": "<your-client-id>",
    "_etag": "<your-api-keys-_etag>",
    "enabled": true,
    "regenerateSecret": false
  }
}
```

Set `enabled` to `false` to disable a key. Set `regenerateSecret` to `true` to rotate its secret. Disabling takes effect immediately. The next request using that key returns `401 Unauthorized`.

## Rotate a key

Rotate an API key when:

* The key might have been exposed, such as being committed to a public repo, leaked in logs, or held by an employee who has left.
* Your org's security policy requires periodic rotation.
* An integration is being decommissioned.

Rotate with zero downtime:

1. Provision a new key alongside the existing one.
2. Deploy the new key to the integration and verify traffic is succeeding with it.
3. Delete the old key.

The old and new keys are both valid during the cutover window. Consumers don't see auth failures.

## Delete a key

Delete a key with this mutation:

```graphql theme={null}
mutation DeleteAPIKey($input: APIKeyInput!) {
  deleteApiKey(input: $input) {
    apikey {
      clientId
    }
  }
}
```

Set the variables:

```json theme={null}
{
  "input": {
    "clientId": "<your-client-id>",
    "_etag": "<your-api-keys-_etag>"
  }
}
```

Deletion is immediate. The next request using that key returns `401 Unauthorized`.

## Service accounts

Service accounts decouple API keys from individual users who might get deactivated. They also make clear that the actions in ION come from a shared service rather than from one person. A service account is an email your company creates and maintains outside of any employee's email. Multiple people can access it as needed.

## Related

* [Authentication](/api-reference/authentication)
* [Authenticate with OAuth 2.0](/api-reference/authentication/oauth)
* [Build an API client](/api-reference/guides/python-quickstart)


# Authentication
Source: https://docs.firstresonance.io/api-reference/authentication/index

How to authenticate against the ION GraphQL API: API keys for machine-to-machine integrations and OAuth 2.0 for user-facing applications.

## Authentication methods

The ION GraphQL API supports two authentication methods: **API keys** for machine-to-machine integrations and **OAuth 2.0** for user-facing applications. Every request uses the same endpoint and `Authorization` header. Only the way you obtain the token differs.

## Endpoint and headers

Every authenticated request targets a single GraphQL endpoint. Include the access token on every request:

```http theme={null}
POST /graphql HTTP/1.1
Host: api.buildwithion.com
Authorization: Bearer <token>
Content-Type: application/json
```

ION also accepts `Authorization: Token <token>` for backward compatibility. Prefer `Bearer`. For multipart file uploads, set `Content-Type: multipart/form-data`. Follow the flow in [File Upload](/api-reference/guides/file-upload).

## Troubleshooting

When ION rejects a request during authentication, the response carries an `errors[].message` payload:

```json theme={null}
{
  "errors": [{ "message": "Token is expired." }]
}
```

For the full list of authentication failures and their fixes (`401 Unauthorized`, `403 Forbidden`, rate limits, and `5xx` errors), see [Error codes](/api-reference/error-codes).

## Related

* [Manage API keys](/api-reference/authentication/api-keys)
* [Authenticate with OAuth 2.0](/api-reference/authentication/oauth)
* [Getting started](/api-reference/getting-started)
* [Error codes](/api-reference/error-codes)


# Authenticate with OAuth 2.0
Source: https://docs.firstresonance.io/api-reference/authentication/oauth

Register an OAuth application, run the authorization code flow, and handle token refresh and scopes for user-facing apps on ION.

Use OAuth 2.0 when the caller is a user-facing application, such as a web app, desktop tool, or mobile client. OAuth lets ION enforce that user's permissions rather than a service account's. For system-to-system integrations, use an [API key](/api-reference/authentication/api-keys) instead.

## Register an OAuth application

Before users can sign in to your application, an org admin must register the application with ION. Run this mutation to register it:

```graphql theme={null}
mutation RegisterApp {
  registerOauthApp(name: "Acme Production Dashboard", appType: "regular_web") {
    oauthApp {
      id
      clientId
    }
  }
}
```

After registration, configure callback URLs, allowed origins, and logout URLs:

```graphql theme={null}
mutation AddCallback {
  addOauthRedirectUri(
    oauthAppId: 42
    uri: "https://app.example.com/auth/callback"
    uriType: "callback"
  ) {
    redirectUri {
      id
      uri
      uriType
    }
  }
}
```

Three URI types are supported:

| URI type   | Purpose                                                                  |
| ---------- | ------------------------------------------------------------------------ |
| `callback` | Where ION redirects users with the authorization code after they sign in |
| `origin`   | Browser origins allowed to make authenticated requests                   |
| `logout`   | Where ION redirects users after sign-out                                 |

Register every URL your application uses (production, staging, local development) to avoid `redirect_uri` mismatches.

## Run the authorization code flow

Follow the standard OAuth 2.0 authorization code flow:

1. **Redirect the user to the ION authorization endpoint.** Include `client_id`, `redirect_uri`, `response_type=code`, `scope`, and `state`.
2. The user authenticates with their ION credentials or SSO.
3. ION redirects to your `redirect_uri` with an authorization `code` and the `state` you sent.
4. **Exchange the code** at the token endpoint for an `access_token`, and optionally a `refresh_token`.
5. **Use the access token** on subsequent API calls.

The authorization and token endpoint URLs depend on your org's auth provider configuration. ION surfaces them in the OAuth app registration response. If you're integrating against ION for the first time, ask your CSM for the endpoint values that match your environment.

## Handle token expiration and refresh

Access tokens have a short lifetime, typically one hour. Two patterns handle expiration:

* **Short-lived integrations.** Let the token expire. Re-run the auth flow the next time the user opens the app.
* **Long-lived integrations.** Request the `offline_access` scope at authorization. Then exchange refresh tokens for new access tokens transparently.

Always re-validate tokens before relying on them. Clock skew, server-side revocation, or org membership changes can invalidate a token mid-flight.

## Scopes

Scopes constrain what an OAuth-issued token can do. Standard scopes include the following:

| Scope            | Allows                                         |
| ---------------- | ---------------------------------------------- |
| `openid`         | Receive an ID token alongside the access token |
| `profile`        | Read the user's profile                        |
| `email`          | Read the user's email                          |
| `offline_access` | Receive a refresh token                        |

ION applies the user's existing role and permission grants on top of the scope. A scope cannot grant a user more access than their role allows.

## Related

* [Authentication](/api-reference/authentication)
* [Manage API keys](/api-reference/authentication/api-keys)
* [Error codes](/api-reference/error-codes)


# Data model
Source: https://docs.firstresonance.io/api-reference/data-model

How ION's core entities relate to each other and how they map to terminology in adjacent systems (ERP, MES, PLM, QMS).

## Overview

When you integrate against ION, eight or nine entities cover about 95% of what you touch. Each entity below shows what it represents, how it connects to the others, and what it maps to in adjacent systems such as ERP, MES, PLM, and QMS.

The full schema lives in [`schema.graphql`](/schema.graphql) and the [API Playground](/api-reference/playground).

## Entity map

The core entities connect through these relationships:

```mermaid theme={null}
flowchart TD
  PartSubtype["PartSubtype (categorization, many-to-many)"]
  Part["Part (library item, design intent)"]
  PartInventory["PartInventory (stockable or serialized unit)"]
  Procedure["Procedure (template)"]
  PurchaseOrder["PurchaseOrder line items"]
  Run["Run (execution)"]
  RunBatch["RunBatch (batched runs)"]
  RunStep["RunStep"]
  BuildRequirement["BuildRequirement (aBOM line item)"]
  Issue["Issue (quality event)"]

  PartSubtype -->|tags| Part
  Part -->|instances of| PartInventory
  PartInventory --> Procedure
  PartInventory --> PurchaseOrder
  Procedure -->|template for| Run
  RunBatch --> Run
  Run --> RunStep
  RunStep --> BuildRequirement
  RunStep --> Issue
```

## Parts

A **Part** is the library entry. It holds a part number, description, revision, and the design intent. A Part is not the physical thing on the shelf. That physical thing is a `PartInventory`.

| Field              | Notes                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------- |
| `id`, `partNumber` | Org-unique within `revision`. `partNumber` is your SKU.                                |
| `description`      | Free text.                                                                             |
| `revision`         | Engineering revision letter or string.                                                 |
| `partType`         | `PART` or `TOOL`.                                                                      |
| `trackingType`     | `SERIAL`, `LOT`, or unset (untracked).                                                 |
| `status`           | `RELEASED` or `ARCHIVED`.                                                              |
| `sourcingStrategy` | `MAKE`, `BUY`, or `DUAL_SOURCE`.                                                       |
| `purchaseType`     | `RECEIVABLE_INVENTORY`, `RECEIVABLE_NON_INVENTORY`, or `NON_RECEIVABLE_NON_INVENTORY`. |
| `partSubtypes`     | Many-to-many with `PartSubtype`. These are categorization tags.                        |
| `cost`, `leadTime` | Optional planning fields.                                                              |
| `revisedFromId`    | Links this revision to its predecessor.                                                |

Query a part:

```graphql theme={null}
query GetPart {
  part(id: "42") {
    id
    partNumber
    description
    revision
    partType
    trackingType
    status
    partSubtypes { id name }
  }
}
```

**Maps to:** "SKU" or "Item Master" in ERP. "PartNumber" in PLM.

## PartSubtype

A **PartSubtype** is a categorization tag attached to a Part. Subtypes group parts that share routing, inspection, or planning behavior. Examples include "Mounting hardware", "Critical-to-quality fasteners", and "Long-lead-time stock". A part can have multiple subtypes.

Query the subtypes:

```graphql theme={null}
query Subtypes {
  partSubtypes(first: 50) {
    edges {
      node {
        id
        name
        description
      }
    }
  }
}
```

**Maps to:** "Item Family", "Commodity Code", or "Product Line" in ERP. Don't confuse a subtype with revision lineage. Revision lineage is `revisedFromId` on Part.

## PartInventory

A **PartInventory** is a physical instance of a Part. It can be a serialized unit, a lot, or a quantity at a location. This is the entity that gets installed onto assemblies, consumed in runs, or shipped.

| Field                               | Notes                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `serialNumber`                      | If the part is serialized.                                                                   |
| `lotNumber`                         | If the part is lot-tracked.                                                                  |
| `quantity`                          | For non-serialized inventory (count).                                                        |
| `status`                            | Such as `AVAILABLE`, `WIP`, `KITTED`, `INSTALLED`, `ON_ORDER`, `SCRAPPED`, or `UNAVAILABLE`. |
| `part`                              | Reference to its `Part`.                                                                     |
| `location`                          | Where it physically lives.                                                                   |
| `madeOnAssemblyParentPartInventory` | If installed onto an assembly, points up the build tree.                                     |
| `entity`                            | Polymorphic id used for file attachments and similar.                                        |

Query a part inventory record:

```graphql theme={null}
query Inventory {
  partInventory(id: "9876") {
    id
    serialNumber
    lotNumber
    quantity
    status
    part { id partNumber description }
    location { id name }
    madeOnAssemblyParentPartInventory { id serialNumber }
  }
}
```

**Maps to:** "Serial" or "Lot" in MES. "Inventory unit" or "Stockable item" in WMS. "Asset" in PLM.

## Assemblies (as-built BOM)

An **as-built BOM** is the parent and child tree of `PartInventory` units that compose a finished assembly. ION represents this tree two ways. The `madeOnAssemblyParentPartInventory` reference on each PartInventory points up the tree. The `BuildRequirement` records define which parts to install where to complete the assembly.

To traverse the tree downward:

```graphql theme={null}
query AbomTree {
  partInventory(id: "9876") {
    id
    serialNumber
    part { partNumber }
    buildRequirements {
      id
      part { partNumber }
      quantity
      abomInstallations {
        id
        partInventory {
          id
          serialNumber
          part { partNumber }
        }
      }
    }
  }
}
```

To walk up the tree, follow `madeOnAssemblyParentPartInventory` recursively.

**Maps to:** "Bill of Materials" in ERP. "Assembly tree" in PLM. "Bill of Build" in MES.

<Note>
  The `mBOM` (manufacturing BOM) is the planned structure. The `aBOM` (as-built) is what was actually installed at run time. Both have GraphQL types in ION.
</Note>

## Procedures and run steps

A **Procedure** is the manufacturing routing template. It defines what should happen on the floor. A Procedure is composed of steps.

Query a procedure with its steps:

```graphql theme={null}
query Proc {
  procedure(id: "12") {
    id
    title
    version
    steps {
      id
      title
      position
      type
      fields {
        id
        name
        type
      }
    }
  }
}
```

**Maps to:** "Routing" in ERP. "Recipe" or "Standard Operating Procedure" in MES. "Work Instruction" in QMS.

## Runs and run steps

A **Run** is one execution of a Procedure against a specific PartInventory. **Run steps** are the per-execution instances of the procedure's steps. A run step is where operators record measurements, sign off, and report quality issues.

| Field           | Notes                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `id`, `title`   |                                                                                                        |
| `status`        | Such as `TODO`, `IN_PROGRESS`, or `COMPLETE`.                                                          |
| `procedure`     | Template.                                                                                              |
| `partInventory` | What's being built.                                                                                    |
| `steps`         | Ordered execution instances (`RunStep`).                                                               |
| `runBatch`      | If the run participates in a batch, see [Run batches](/build-hardware/runs-and-execution/run-batches). |

Query a run with its steps:

```graphql theme={null}
query GetRun {
  run(id: "1234") {
    id
    title
    status
    procedure { id title version }
    partInventory { id serialNumber part { partNumber } }
    steps {
      id
      position
      status
      endTime
      fields { id name value }
    }
  }
}
```

**Maps to:** "Work Order" in ERP. "Production Order" in MES. "Build" or "Job" colloquially.

## Build requirements

A **BuildRequirement** is a line item on an aBOM. It defines how many of a given part to install to complete the assembly. Operators install against build requirements during a run. Each install is a row of `abomInstallations` (an `ABomInstallation`) that links the `PartInventory` consumed to the build requirement satisfied.

For the user-facing flow, see [Editing build requirements](/build-hardware/bills-of-materials/editing-build-requirements).

## Issues

An **Issue** is a quality event. It can be a nonconformance, deviation, supplier problem, or observation. Issues attach to runs, run steps, or part inventories. Issues follow a defined lifecycle. The states are Pending, In Progress, In Review, and Resolved. Disposition types determine what happens to the affected inventory.

Query open issues by disposition:

```graphql theme={null}
query OpenIssues {
  issues(filters: { status: { eq: IN_PROGRESS } }) {
    edges {
      node {
        id
        title
        status
        issueDispositionType { id title }
        assignedTo { id name }
        runStep { id }
      }
    }
  }
}
```

For more information, see [Issue states, dispositions, and resolutions](/track-quality/issues).

**Maps to:** "Nonconformance Report" (NCR) in QMS. "CAPA" precursor in QMS. "Defect" in PLM. "Incident" in ServiceNow-style systems.

## Purchase orders

For supply chain integrations:

```graphql theme={null}
query OpenPOs {
  purchaseOrders(filters: { isOpen: { eq: true } }) {
    edges {
      node {
        id
        prettyStr
        status
        supplier { id name }
        purchaseOrderLines {
          id
          part { partNumber }
          quantity
          receivedQuantity
        }
      }
    }
  }
}
```

**Maps to:** "PO" in ERP. Receiving against a PO updates `PartInventory` records.

## File attachments

Files attach to entities polymorphically through the `entity` ID. For the upload flow and the `entity { id }` lookup pattern, see [File upload](/api-reference/guides/file-upload).

## The `entity` polymorphic ID

ION gives every attachable object a uniform ID through an `entities` reference. Most major entities expose an `entity { id }` field. This field is the target for several features:

* File attachments
* Subscriptions (notifications)
* Comments
* Cross-entity links, such as an issue to a run step

Don't confuse this field with the entity's own `id`. When an integration calls for an `entityId`, fetch the parent's `entity.id` first.

## Field-mapping cheat sheet

When you bridge from another system, use this rough translation:

| Your system says…                      | ION calls it…                                               |
| -------------------------------------- | ----------------------------------------------------------- |
| SKU, Item Master, or Part Number       | `Part.partNumber`                                           |
| Item Family, Commodity, or Group       | `PartSubtype.name` (a part can belong to multiple subtypes) |
| Lot or Batch number                    | `PartInventory.lotNumber`                                   |
| Serial or Asset Tag                    | `PartInventory.serialNumber`                                |
| On-hand quantity                       | `PartInventory.quantity`                                    |
| BOM line item                          | `BuildRequirement`                                          |
| Work Order or Production Order         | `Run`                                                       |
| Routing, Recipe, or Process            | `Procedure`                                                 |
| Operation, Step, or Op                 | `Step` (template) or `RunStep` (execution)                  |
| NCR or Nonconformance                  | `Issue`                                                     |
| Disposition (Use As Is, Rework, Scrap) | `IssueDispositionType`                                      |
| PO                                     | `PurchaseOrder`                                             |
| PO line                                | `PurchaseOrderLine`                                         |
| Vendor or Supplier                     | `PurchaseOrder.supplier` (a `Supplier`)                     |
| Workcenter or Cell                     | `Location` (typed `WORKCENTER`)                             |
| Tote, Bin, or Rack                     | `Location` (other types)                                    |
| User group or Role                     | `Role`                                                      |
| User                                   | `User`                                                      |
| Tenant or Org                          | `Organization`                                              |

## Etag-based concurrency

Every mutable entity returns an `_etag` on read. Pass it back on `update` and `delete` mutations. ION rejects writes whose etag doesn't match the current value. A mismatch returns a 409. For more information, see [Error codes 409](/api-reference/error-codes#409-concurrency-conflict).

When you integrate, read then write inside a short window. Propagate the etag through your service.

## Discovering the rest of the schema

You can find anything not on this page three ways:

1. **API Playground**: an interactive schema explorer at [/api-reference/playground](/api-reference/playground).
2. [`schema.graphql`](/schema.graphql): committed to this repository and kept in sync with the production schema.
3. **`__schema` introspection**: programmatic access.

## Related

* [Example requests](/api-reference/examples)
* [Upload a file](/api-reference/guides/file-upload)
* [Set up webhooks](/api-reference/guides/webhooks)


# Error codes
Source: https://docs.firstresonance.io/api-reference/error-codes

HTTP status codes and GraphQL error payloads ION returns: what each one means, what causes it, and how to fix it.

## Overview

When an ION API request fails, two things tell you what went wrong. The HTTP status code gives you a coarse category and the `errors[]` payload in the response body gives you the specific message. That message often points directly at the fix.

A typical error response looks like this:

```json theme={null}
{
  "errors": [
    {
      "message": "User does not have permission to update this resource."
    }
  ]
}
```

GraphQL operations always return HTTP 200 even when the operation itself fails. The failure shows up in `errors[]`. Authentication and transport failures are the exception. The auth layer can return a 4xx or 5xx status code before GraphQL runs.

## HTTP status reference

| Status | Meaning                       | When you'll see it                                                                                                |
| ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `200`  | Success or GraphQL error      | Always for `/graphql`. Check `errors[]`                                                                           |
| `400`  | Malformed request             | Invalid JSON body, a request body with no `query` key, missing required field on the wire                         |
| `401`  | Unauthenticated               | Missing, expired, or invalid token. See [the 401 table](#401-unauthorized)                                        |
| `403`  | Authenticated but not allowed | Permission, scope, or org-isolation failure. See [403 Forbidden](#403-forbidden)                                  |
| `404`  | Resource not found            | Wrong ID, soft-deleted entity, or not visible to your org                                                         |
| `409`  | Concurrency conflict          | The `_etag` mismatch. Your update raced another writer. See [409 Concurrency conflict](#409-concurrency-conflict) |
| `422`  | Validation error              | Field value violates a domain rule, such as quantity ≤ 0                                                          |
| `429`  | Rate-limited                  | Back off and retry                                                                                                |
| `5xx`  | Server error                  | ION-side failure. Safe to retry with exponential backoff                                                          |

One exception to the `400` row: a request whose body is entirely empty returns `200` with the error in `errors[]`, like any other GraphQL error.

## 401 Unauthorized

ION rejects the request at the authentication layer. Here are the common messages and their fixes:

| Message                                                      | Cause                                                                 | Fix                                                                                                        |
| ------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Please provide proper credentials`                          | No `Authorization` header on the request                              | Add `Authorization: Bearer <token>`.                                                                       |
| `Unable to parse authentication token`                       | Malformed token, such as one that is truncated or in the wrong format | Verify the full token is being sent. A common cause is an env var that lost a trailing character.          |
| `Unable to find appropriate RSA key`                         | The token was signed by a key ION doesn't recognize                   | The token came from the wrong auth provider. Check that you're hitting the right `client_id` and audience. |
| `Token is expired`                                           | The access token's `exp` claim has passed                             | Refresh the token for OAuth, or re-issue it for an API key.                                                |
| `Unable to validate authentication token`                    | Generic verification failure                                          | Re-issue the token. If it persists, check that the token audience and issuer match your environment.       |
| `Token organization does not match user's organization`      | The token was issued for one org, but the user belongs to another     | Re-authenticate the user against their actual organization.                                                |
| `User <email> is deactivated`                                | The user has been deactivated in ION                                  | Reactivate the user or use a different account.                                                            |
| `Sorry, this organization is blocked from accessing ION`     | The org is in a blocked state                                         | Contact your CSM.                                                                                          |
| `Login domain '<domain>' is not valid for this organization` | The user's email domain isn't allowed on the org                      | Add the domain to org settings or use an allowed email.                                                    |

## 403 Forbidden

The request authenticated successfully, but the principal isn't authorized for the operation. The distinct causes each have a different fix.

| Cause                           | What happened                                                                                                                                      | How to fix                                                                               |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Missing role permission**     | The user or service account's role doesn't include the action being performed. For example, the role lacks the "create purchase order" permission. | An admin grants the role the missing permission, or assigns the user a role that has it. |
| **Resource not visible to org** | The entity ID exists in another tenant's data. ION treats it as nonexistent for this caller.                                                       | Verify the ID belongs to your org. Cross-org references are never allowed.               |
| **Read-only organization**      | The org is in read-only mode, such as a billing freeze or compliance hold, and any mutation is rejected.                                           | Contact your CSM to release the read-only flag.                                          |
| **Read-only schema**            | A specific schema, your tenant, is flagged read-only on the ION side.                                                                              | Contact support.                                                                         |
| **Deactivated user**            | The user account is deactivated. Auth still passes if the token is valid, but every operation returns a 403.                                       | Reactivate the user in admin settings.                                                   |
| **Approval gate not satisfied** | The operation requires an approval that hasn't been granted. For example, publishing a procedure that requires QE sign-off.                        | Complete the approval flow first.                                                        |
| **OAuth scope insufficient**    | The token was issued with limited scopes that don't cover the requested operation.                                                                 | Re-authorize the OAuth app with broader scopes.                                          |
| **Feature flag disabled**       | The operation is gated behind a feature flag not enabled for your org.                                                                             | Contact your CSM to enable the feature for your tier.                                    |
| **Cross-org token**             | A token issued for org A is trying to access org B's data.                                                                                         | Re-authenticate against the correct org.                                                 |

<Tip>
  If a 403 says "permission", check the user's role. If it says "not found" or
  refers to an ID, check the entity's tenant. If it says "read-only", check the
  org's billing and compliance state.
</Tip>

### Sample 403 payload

```json theme={null}
{
  "errors": [
    {
      "message": "User does not have permission to perform UPDATE on Purchase Order."
    }
  ]
}
```

The action verb (`UPDATE`) and the resource type (`Purchase Order`) are the two pieces an admin needs to find the missing role permission.

## 404 Not Found

ION returns a 404, and a GraphQL `null` for the field, when the entity doesn't exist or doesn't belong to your tenant. The two cases are intentionally indistinguishable to prevent enumeration. A 404 doesn't leak that an ID exists in another org.

Common causes:

* An ID typo.
* The entity was soft-deleted.
* A cross-tenant ID. See 403 above. Sometimes this surfaces as a 404 instead, depending on the resolver.

If the entity should exist, query a filtered list such as `parts(filters: { id: { in: [42] } }) { edges { node { id } } }` instead of `part(id: "42")`. The filtered query returns an empty `edges` array. That confirms a tenant or scope issue.

## 409 Concurrency conflict

ION uses optimistic concurrency control via the `_etag` field. Every mutable entity returns an `_etag` on read. Mutations require you to pass back the `_etag` you received. If another writer modified the entity in the meantime, the etag won't match and ION returns a 409.

```json theme={null}
{
  "errors": [{ "message": "Concurrent modification detected — etag mismatch." }]
}
```

The fix is always the same:

1. Re-read the entity to get the latest `_etag` and the latest field values.
2. Re-apply your changes on top of the new state.
3. Retry the mutation with the new `_etag`.

This is intentional. Re-reading surfaces the other writer's changes before you overwrite them. Always re-read and re-apply, even when you intend to discard the other writer's changes.

## 422 Validation error

The request was structurally valid and authorized, but a field value violated a domain rule:

* A quantity is zero or negative.
* A required field is missing.
* A date is out of range.
* A string exceeds the maximum length.
* An enum value is not allowed.

The error message names the field and the constraint:

```json theme={null}
{
  "errors": [{ "message": "PartInventory quantity must be greater than 0." }]
}
```

These errors are deterministic. Fix the input and retry.

## 429 Rate limit

ION applies fair-use rate limiting on the `/graphql` endpoint. Production traffic patterns rarely hit it. If you do, the response is HTTP 429.

Address it in this order:

1. Implement exponential backoff in your client. Start at 1 second, double up to about 30 seconds, and add jitter.
2. Batch related queries. One query selecting many fragments beats several queries that each select one fragment.
3. Cache locally. For data that doesn't change often, such as parts and procedures, don't re-fetch every time.

## 5xx Server errors

A 5xx response indicates a failure on ION's side. These responses are safe to retry with exponential backoff.

```http theme={null}
HTTP/1.1 502 Bad Gateway
```

Standard recovery pattern:

1. Retry with exponential backoff. Use 1, 2, 4, and 8 seconds.
2. After three consecutive failures across about 30 seconds, surface the error to the user or on-call.
3. Check ION's status page if available, or contact support if the error persists.

## GraphQL errors\[] shape

Inside the GraphQL response body, an HTTP 200, the `errors` array is the source of truth:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "User does not have permission to perform UPDATE on Purchase Order.",
      "path": ["updatePurchaseOrder"],
      "locations": [{ "line": 2, "column": 3 }]
    }
  ]
}
```

| Field       | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `message`   | Human-readable error.                                             |
| `path`      | Which field in your query failed.                                 |
| `locations` | Position in the query string for IDE and playground integrations. |

A partial `data` payload with a non-empty `errors[]` means the returned fields are valid and one or more other fields failed. Most clients merge these. Yours should too.

## Troubleshooting flow

1. Check the HTTP status.
2. If it's a 200, parse `errors[]` from the response body.
3. Match the message against the tables on this page.
4. If the message is unfamiliar, its wording usually points at the offending field, permission, or resource. Search for it in [Authentication](/api-reference/authentication) and the tables on this page.
5. If you're still stuck, reproduce the call in the [API Playground](/api-reference/playground), which surfaces errors more readably. Paste the request and error into a support ticket.

<Note>
  Most 403s are fixed by granting the user's role the missing permission. Check
  permissions before you change code. For a 409, show the conflict to a human so
  they can re-merge.
</Note>

## Related

* [Authentication](/api-reference/authentication)
* [API playground](/api-reference/playground)


# Example requests
Source: https://docs.firstresonance.io/api-reference/examples

The most common queries and mutations you can run on the ION API

This page collects the most common queries and mutations you can run on the ION API. The quickest way to run them is through the [API Playground](/api-reference/playground).

<Tabs>
  <Tab title="Queries">
    <AccordionGroup>
      <Accordion title="Search parts">
        Find parts by part number or description substring:

        ```graphql theme={null}
        query SearchParts($q: String!, $first: Int) {
          parts(filters: { partNumber: { ilike: $q } }, first: $first) {
            edges {
              node {
                id
                partNumber
                description
                revision
                partType
                status
                partSubtypes { id name }
              }
            }
          }
        }
        ```

        ```json theme={null}
        { "q": "%BRKT%", "first": 25 }
        ```
      </Accordion>

      <Accordion title="Get a procedure with all steps">
        Fetch a procedure template plus every step and its fields:

        ```graphql theme={null}
        query GetProcedure($id: Int!) {
          procedure(id: $id) {
            id
            title
            steps {
              id
              title
              fields { id }
            }
          }
        }
        ```

        ```json theme={null}
        { "id": 12 }
        ```
      </Accordion>

      <Accordion title="Get an aBOM with full hierarchy">
        Walk an as-built BOM tree from the parent down to all installations:

        ```graphql theme={null}
        query AbomTree($id: Int!) {
          partInventory(id: $id) {
            id
            serialNumber
            part { partNumber }
            buildRequirements {
              id
              part { partNumber }
              quantity
            }
          }
        }
        ```

        ```json theme={null}
        { "id": 9876 }
        ```
      </Accordion>

      <Accordion title="Compare two aBOM versions">
        Pull two as-built BOMs and diff them client-side:

        ```graphql theme={null}
        query CompareAboms($idA: Int!, $idB: Int!) {
          a: partInventory(id: $idA) {
            id
            serialNumber
            buildRequirements { id part { partNumber } quantity }
          }
          b: partInventory(id: $idB) {
            id
            serialNumber
            buildRequirements { id part { partNumber } quantity }
          }
        }
        ```

        ```json theme={null}
        { "idA": 9876, "idB": 9877 }
        ```
      </Accordion>

      <Accordion title="List open runs with current step">
        Get every run that's in progress, with the current step the operator is on:

        ```graphql theme={null}
        query OpenRuns {
          runs(filters: { status: { in: ["TODO", "IN_PROGRESS"] } }, first: 100) {
            edges {
              node {
                id
                title
                status
                procedure { id title }
                partInventory { id serialNumber part { partNumber } }
              }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Run history for a part">
        Every run a specific part inventory has gone through, newest first:

        ```graphql theme={null}
        query RunHistory($partInventoryId: Int!) {
          runs(
            filters: { partInventoryId: { eq: $partInventoryId } }
            first: 50
          ) {
            edges {
              node {
                id
                title
                status
                _created
                procedure { id title }
              }
            }
          }
        }
        ```

        ```json theme={null}
        { "partInventoryId": 9876 }
        ```
      </Accordion>

      <Accordion title="Inventory for a part by location">
        List inventory units of a given part, grouped by physical location:

        ```graphql theme={null}
        query InventoryByLocation($partId: Int!) {
          partInventories(filters: { partId: { eq: $partId } }, first: 250) {
            edges {
              node {
                id
                serialNumber
                lotNumber
                quantity
                status
                location { id name type }
              }
            }
          }
        }
        ```

        ```json theme={null}
        { "partId": 12 }
        ```
      </Accordion>

      <Accordion title="Serialized units for a part">
        Get every serialized instance of a part with its current state:

        ```graphql theme={null}
        query SerializedUnits($partId: Int!) {
          partInventories(filters: { partId: { eq: $partId } }, first: 250) {
            edges {
              node {
                id
                serialNumber
                status
                location { id name }
              }
            }
          }
        }
        ```

        ```json theme={null}
        { "partId": 12 }
        ```
      </Accordion>

      <Accordion title="List open issues by disposition">
        All open issues grouped by disposition type for triage:

        ```graphql theme={null}
        query OpenIssuesByDisposition {
          issues(
            filters: { status: { in: ["PENDING", "IN_PROGRESS", "IN_REVIEW"] } }
            first: 250
          ) {
            edges {
              node {
                id
                title
                status
                issueDispositionType { id title }
                assignedTo { id name }
                _created
              }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Get current user and org">
        Verify your token and find which org you're in:

        ```graphql theme={null}
        query Me {
          me {
            id
            name
            email
            organization { id domain }
          }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Mutations">
    <AccordionGroup>
      <Accordion title="Create a part">
        Create a new part in the library:

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

        ```json theme={null}
        {
          "input": {
            "partNumber": "TEST-001",
            "description": "Integration test part",
            "revision": "A",
            "partType": "part",
            "trackingType": "lot"
          }
        }
        ```
      </Accordion>

      <Accordion title="Create a run from a procedure">
        Start a new run by binding a procedure to a part inventory:

        ```graphql theme={null}
        mutation CreateRun($input: CreateRunInput!) {
          createRun(input: $input) {
            run {
              id
              title
              status
              procedure { id title }
              partInventory { id serialNumber }
            }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "procedureId": 12,
            "partInventoryId": 9876,
            "title": "Build #2026-04-26 Unit 1"
          }
        }
        ```
      </Accordion>

      <Accordion title="Submit a run step result">
        Sign off a step with measurements. Requires the step's `_etag`:

        ```graphql theme={null}
        mutation SubmitStep($input: UpdateRunStepInput!) {
          updateRunStep(input: $input) {
            runStep {
              id
              status
              fields { id name value }
            }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "id": 4567,
            "_etag": "abc123",
            "status": "complete",
            "fieldValues": [
              { "runStepFieldId": 88, "value": "PASS" },
              { "runStepFieldId": 89, "value": "12.45" }
            ]
          }
        }
        ```
      </Accordion>

      <Accordion title="Start or complete a run">
        Move a run between lifecycle states:

        ```graphql theme={null}
        mutation UpdateRunStatus($input: UpdateRunInput!) {
          updateRun(input: $input) {
            run { id status startTime endTime }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "id": 1234,
            "_etag": "xyz789",
            "status": "complete"
          }
        }
        ```
      </Accordion>

      <Accordion title="Create a purchase order">
        Issue a new PO with line items:

        ```graphql theme={null}
        mutation CreatePO($input: CreatePurchaseOrderInput!) {
          createPurchaseOrder(input: $input) {
            purchaseOrder {
              id
              status
              supplier { id name }
              purchaseOrderLines { id part { partNumber } quantity }
            }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "vendorId": 42,
            "lineItems": [
              { "partId": 12, "quantity": 100 },
              { "partId": 13, "quantity": 50 }
            ]
          }
        }
        ```
      </Accordion>

      <Accordion title="Create an issue linked to a run">
        Open a quality issue tied to a specific run step:

        ```graphql theme={null}
        mutation CreateIssue($input: CreateIssueInput!) {
          createIssue(input: $input) {
            issue {
              id
              title
              status
              runStep { id }
            }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "title": "Surface scratches on RX-22 lot 4",
            "runStepId": 4567,
            "description": "Visible scratches across 4 of 12 units"
          }
        }
        ```
      </Accordion>

      <Accordion title="Close an issue with a resolution">
        Move an issue to resolved once reviews are signed off:

        ```graphql theme={null}
        mutation ResolveIssue($input: UpdateIssueInput!) {
          updateIssue(input: $input) {
            issue { id status }
          }
        }
        ```

        ```json theme={null}
        {
          "input": {
            "id": 7777,
            "_etag": "etag-value",
            "status": "resolved"
          }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>


# Getting started
Source: https://docs.firstresonance.io/api-reference/getting-started

Make your first authenticated GraphQL request to the ION API.

## Prerequisites

* An ION organization.
* An **API key** for machine-to-machine integrations, or **OAuth credentials** for user-facing applications. For how to obtain each, see [Authentication](/api-reference/authentication).
* A tool that can make HTTPS POST requests with JSON bodies, such as `curl`, `httpie`, or Postman.
* Familiarity with GraphQL.

<Tip>
  New to GraphQL? See the [official GraphQL
  documentation](https://graphql.org/learn/).
</Tip>

## The endpoint

All API requests go to one endpoint:

```
POST https://api.buildwithion.com/graphql
```

Authenticate each request with these headers:

```
Authorization: Bearer <token>
Content-Type: application/json
```

## Get an access token

If you have an **API key**, exchange it for a short-lived access token through your auth provider's client-credentials grant. For a reusable pattern, see the [Build an API client](/api-reference/guides/python-quickstart).

If you use **OAuth 2.0**, complete the authorization code flow in [Authenticate with OAuth 2.0](/api-reference/authentication/oauth). After the user signs in, your callback receives an `access_token`.

Both paths give you a JWT string. Treat it like a password.

## Make your first request

A minimal "who am I?" query confirms the token works:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.buildwithion.com/graphql \
      -H "Authorization: Bearer $ION_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "query { me { id name email organization { id domain } } }"
      }'
    ```
  </Tab>

  <Tab title="Python">
    Install `httpx` (`pip install httpx`), then run:

    ```python theme={null}
    import os
    import httpx

    resp = httpx.post(
        "https://api.buildwithion.com/graphql",
        headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
        json={"query": "query { me { id name email organization { id domain } } }"},
    )
    resp.raise_for_status()
    print(resp.json()["data"]["me"])
    ```

    For a reusable client with retries and error handling, see the [Build an API client](/api-reference/guides/python-quickstart).
  </Tab>
</Tabs>

A successful response looks like this:

```json theme={null}
{
  "data": {
    "me": {
      "id": 42,
      "name": "Ada Lovelace",
      "email": "ada@acme.com",
      "organization": {
        "id": 7,
        "domain": "acme.com"
      }
    }
  }
}
```

If the response is an `errors` payload instead, see [Error codes](/api-reference/error-codes) and its [401 table](/api-reference/error-codes#401-unauthorized).

## Query data

Once auth works, try a domain query. Listing parts is a good first test because it touches inventory, the most common integration target:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.buildwithion.com/graphql \
      -H "Authorization: Bearer $ION_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import httpx

    resp = httpx.post(
        "https://api.buildwithion.com/graphql",
        headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
        json={"query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"},
    )
    resp.raise_for_status()
    print(resp.json()["data"]["parts"]["edges"])
    ```
  </Tab>
</Tabs>

The response should contain up to five parts from your org. If the response comes back empty, your org might not have parts yet. Query `me` again to confirm the token is valid. Then check the admin UI for data.

## Pick your next page

You now have a working integration. Where to go next depends on what you're building:

| If you're…                                                       | Go to                                                                                  |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Building a reusable API client                                   | [Build an API client](/api-reference/guides/python-quickstart)                         |
| Working through common queries and mutations                     | [Example requests](/api-reference/examples)                                            |
| Building real-time event-driven integrations                     | [Set up webhooks](/api-reference/guides/webhooks)                                      |
| Uploading files, such as procedure attachments and run artifacts | [Upload a file](/api-reference/guides/file-upload)                                     |
| Mapping ION's data model into your system                        | [Data model](/api-reference/data-model)                                                |
| Hitting a 403 or unfamiliar error                                | [Error codes](/api-reference/error-codes)                                              |
| Testing without affecting production                             | [Sandbox](/api-reference/sandbox)                                                      |
| Taking an integration to production                              | [Build a production integration](/api-reference/guides/build-a-production-integration) |

## Related

* [Authentication](/api-reference/authentication)
* [Example requests](/api-reference/examples)


# Build an aBOM
Source: https://docs.firstresonance.io/api-reference/guides/abom-as-built-bill-of-materials-api

Build an as-built bill of materials (aBOM) with the ION API: install parts and manage build requirements.

An as-built bill of materials (aBOM) tracks the build process of parts in a hierarchical tree. The aBOM records which part instances and lots are used to create parts, subsystems, and systems. The aBOM is a more detailed version of the mBOM, with relations to physical inventory rather than to parts.

## Set up part inventory

To create an aBOM, you need inventory. For details on creating inventory, see [Manage part inventory and kitting](/api-reference/guides/part-inventory-and-kitting). A part with inventory has a part number, and that part should have an mBOM. ION uses this mBOM to create the aBOM.

When you first create the part inventory, it has only empty build requirements. Build requirements define the parameters for what parts you can install.

## Install parts

You install a part by creating an aBOM installation. An aBOM installation links inventory to `buildRequirements`. To uninstall a part, delete its aBOM installation.

Create the aBOM installation with this mutation:

```graphql theme={null}
mutation CreateABomInstallation($input: CreateABomInstallationInput!) {
    createAbomInstallation(input: $input) {
        abomInstallation {
            buildRequirementId
            buildRequirementReferenceDesignatorId
            partInventoryId
            quantity
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "buildRequirementId": 1,
        "partInventoryId": 3,
        "quantity": 1
    }
}
```

## Edit build requirements

You can add build requirements to an inventory that don't originate from the mBOM.

Create the build requirement with this mutation:

```graphql theme={null}
mutation CreateBuildRequirement($input: CreateBuildRequirementInput!) {
  createBuildRequirement(input: $input) {
    buildRequirement {
      fixedQuantityPerBuildRequirement
      id
      madeOnAssembly
      originMbomItemId
      partId
      partInventories {
        id
      }
      quantityPerParentPartInventory
    }
  }
}
```

Set the variables:

```json theme={null}
{
  "input": {
    "partId": 1,
    "partInventoryId": 484,
    "quantityPerParentPartInventory": 5,
    "madeOnAssembly": false
  }
}
```

Update the build requirement with this mutation:

```graphql theme={null}
mutation UpdateBuildRequirement($input: UpdateBuildRequirementInput!) {
    updateBuildRequirement(input: $input) {
        buildRequirement {
            fixedQuantityPerBuildRequirement
            id
        }
    }
}
```

Set the variables:

```json theme={null}
{
  "input": {
    "id": 1031,
    "etag": "dca4e886ecce4a499d15411006a6d82a",
    "quantityPerParentPartInventory": 8
  }
}
```

This example changes the `quantityPerParentPartInventory` of the `buildRequirement`. You can also change the fixed quantity, made-on-assembly designation, substitutes, and reference designators.

## Related

* [Manage part inventory and kitting](/api-reference/guides/part-inventory-and-kitting)
* [Manage mBOM items](/api-reference/guides/mboms)


# Update run step fields
Source: https://docs.firstresonance.io/api-reference/guides/automatically-updating-fields-in-runs

Query the fields on a run step and update a field value with the GraphQL API.

To update a field on a run step, first query the run to find the field you want, then run a mutation to set its value.

## Get the fields

Query the run to get the fields that exist on the run steps you want to update:

```graphql theme={null}
{
  run(id: 419) {
    id steps {
      id fields {
        id name value type _etag
      }
    }
  }
}
```

The response looks like this:

```json theme={null}
{
  "data": {
    "run": {
      "id": 419,
      "steps": [
        {
          "id": 1429,
          "fields": [
            {
              "id": 1461,
              "name": "required_field",
              "value": null,
              "type": "STRING",
              "_etag": "066b1eb08dab44d6925d7bbd899e92cf"
            },
            {
              "id": 1462,
              "name": "pass_fail",
              "value": null,
              "type": "BOOLEAN",
              "_etag": "066b1eb08dab44d6925d7bbd899e92cf"
            },
            {
              "id": 1463,
              "name": "quality",
              "value": null,
              "type": "SIGNOFF",
              "_etag": "066b1eb08dab44d6925d7bbd899e92cf"
            }
          ]
        }
      ]
    }
  }
}
```

The query returns a list of run steps within that run, and the fields within those run steps. Find the field that you want to update.

## Update a field value

From the example response above, suppose you want to update field `1462` because your test equipment can determine pass or fail. Use this mutation:

```graphql theme={null}
mutation {
  updateRunStepFieldValue(input: {
    id: 1462,
    value: true,
    etag: "066b1eb08dab44d6925d7bbd899e92cf"
  }) {
    runStepField {
      id value
    }
  }
}
```

This mutation does the following:

* Because it updates data, it's a `mutation`.
* The mutation is `updateRunStepFieldValue`.
* The field `id` is `1462` and the `value` you're setting is `true`.
* It includes the `etag` of the original field. The `etag` prevents accidental data overwrites by enforcing concurrency control.

The response returns the `id` and the updated `value` of the field.


# Build a production integration
Source: https://docs.firstresonance.io/api-reference/guides/build-a-production-integration

Take an integration from your first API call to production.

This is the GraphQL API path to an integration. For other approaches, such as the Workflow Builder, see [Create an integration](/automate-with-ion/integrations/create-an-integration). Once your first calls work (see [Getting started](/api-reference/getting-started)), follow this path to take an integration to production.

## Get access

For your own org, ask an admin for access to your [sandbox](/api-reference/sandbox). For an external org, that org grants you access to their environment.

<Warning>
  Gov Cloud is restricted to US persons only. If you're a non-US person building for a Gov Cloud organization, use your own ION sandbox and grant access to other domains instead.
</Warning>

<Note>
  If your organization doesn't have a sandbox yet, reach out to First Resonance to request one.
</Note>

## Set permissions

An admin grants the permissions your integration needs. An API key holds the permissions its creating user had **at the moment it was generated**. Set those permissions first. See the [permissions reference](/administration/users-and-permissions#permissions-reference), [Manage API keys](/api-reference/authentication/api-keys), and [Webhooks](/api-reference/guides/webhooks).

## Connect

Obtain an access token ([Authentication](/api-reference/authentication)) and subscribe to the events you care about ([Webhooks](/api-reference/guides/webhooks)). You can build the integration in a traditional environment such as Python or Node.js, or in a low-code iPaaS tool.

## Map the flow

List the triggers, steps, and API calls your integration needs. Configure any new [custom attributes](/administration/custom-attributes) to represent data that doesn't have a home in ION yet.

<Note>
  Every unique mutation in ION has an associated permission. Use the [API playground](/api-reference/playground) to confirm which permissions a call requires before you build.
</Note>

## Test and promote

Validate your edge cases against the sandbox, then roll out to production. The production environment needs its own set of API keys and webhook receivers.

## Related

* [Getting started](/api-reference/getting-started)
* [Authentication](/api-reference/authentication)
* [Set up webhooks](/api-reference/guides/webhooks)


# Edit time-tracking session data
Source: https://docs.firstresonance.io/api-reference/guides/edit-time-tracking-session-data

Update the check-in and check-out times for a time-tracking session through the ION GraphQL API.

You can edit a session through the API or from a run step. For the in-app workflow, see [Time tracking](/build-hardware/runs-and-execution/time-tracking).

When you need to correct the check-in or check-out time for a session, update the session data through the ION API. The steps below walk through querying for a session and updating its times.

## Get the session ID and information

Query for the sessions you want to edit. This query returns the last five sessions. To narrow the results, query by user or another parameter:

```graphql theme={null}
{
  sessions (last: 5){
    edges {
      node {
        id
        _etag
        runStep {
          runId
          position
        }
        checkIn
        checkOut
        createdBy {
          email
        }
      }
    }
  }
}
```

## Update the session data

Once you have the `id` and `_etag`, use this mutation and input to modify the session data:

```graphql theme={null}
mutation UpdateSession($input: UpdateSessionInput!) {
  updateSession(input: $input) {
    session {
        checkIn
        checkOut
        id
    }
  }
}
```

Provide these query variables:

```json theme={null}
{
  "input": {
    "id": "<from previous step>",
    "etag": "<from previous step>",
    "checkIn": "<use your own value here>",
    "checkOut": "<use your own value here>"
  }
}
```

## Related

* [Time tracking](/build-hardware/runs-and-execution/time-tracking)


# Upload a file
Source: https://docs.firstresonance.io/api-reference/guides/file-upload

Upload files to ION with a three-step flow: request a signed upload URL, send the file directly to ION's file storage, then register the attachment.

ION stores file attachments such as procedure images, run artifacts, and inspection photos. You don't upload a file by posting it through the GraphQL endpoint. Instead, you use a three-step flow: request a signed upload URL from ION, send the file directly to that URL, then register the attachment back to ION with the storage details. Large files upload directly to storage rather than through ION.

The two most common stumbling blocks are capturing the `ETag` from the upload response and choosing the right `entityId`.

## How the flow works

1. Send `requestFileUploadUrl` to ION. ION returns `uploadUrl`, `s3Key`, and `contentType`.
2. Send a PUT request with the file body and `Content-Type` header to `uploadUrl`. Storage returns a `200` response with an `ETag` header.
3. Send `createFileAttachment` to ION with `s3Key`, `s3Etag`, `entityId`, and `filename`. ION returns the `fileAttachment`.

## Prerequisites

* An authenticated GraphQL client. See [Authentication](/api-reference/authentication).
* Permission to attach files to the entity you're targeting.
* The **entity ID** of the object you're attaching to. See [Choose an entityId](#choose-an-entityid).

## Step 1: Request a signed upload URL

Request a signed upload URL:

```graphql theme={null}
query RequestUpload($filename: String!) {
  requestFileUploadUrl(filename: $filename) {
    uploadUrl
    s3Key
    contentType
  }
}
```

**Variables:**

```json theme={null}
{ "filename": "inspection-photo-2026-04-26.jpg" }
```

**Response:**

```json theme={null}
{
  "data": {
    "requestFileUploadUrl": {
      "uploadUrl": "https://ion-files.s3.amazonaws.com/...?X-Amz-Signature=...",
      "s3Key": "uploads/abc123/inspection-photo-2026-04-26.jpg",
      "contentType": "image/jpeg"
    }
  }
}
```

The `uploadUrl` is single-use and time-bound, typically for a few minutes. If you wait too long, the PUT request in step 2 fails. If that happens, request a new URL.

The `contentType` in the response is the value you must send in the PUT request's `Content-Type` header. ION derives it from the filename extension. If the extension doesn't reveal your file's type, request the URL with a more specific filename.

## Step 2: Upload the file

Upload the file directly using the signed URL:

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  --data-binary "@./inspection-photo-2026-04-26.jpg" \
  -i
```

The `-i` flag returns the response headers, including the `ETag` value:

```http theme={null}
HTTP/1.1 200 OK
ETag: "9c1185a5c5e9fc54612808977ee8f548"
```

That `ETag` value, with the surrounding quotes stripped, is your `s3Etag` for step 3. ION uses it to verify that the file you uploaded matches the registration you're about to create.

<Warning>
  Capturing the `ETag` is the most common file-upload bug. Confirm your HTTP
  library exposes response headers and isn't using a wrapper that discards them.
</Warning>

## Step 3: Register the attachment

```graphql theme={null}
mutation RegisterUpload($input: CreateFileAttachmentInput!) {
  createFileAttachment(input: $input) {
    fileAttachment {
      id
      filename
      downloadUrl
      entityId
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "input": {
    "filename": "inspection-photo-2026-04-26.jpg",
    "s3Key": "uploads/abc123/inspection-photo-2026-04-26.jpg",
    "s3Etag": "9c1185a5c5e9fc54612808977ee8f548",
    "entityId": 9876,
    "validateUpload": true
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "createFileAttachment": {
      "fileAttachment": {
        "id": 4242,
        "filename": "inspection-photo-2026-04-26.jpg",
        "downloadUrl": "https://ion-files.s3.amazonaws.com/...",
        "entityId": 9876
      }
    }
  }
}
```

After this returns successfully, the file is visible in the ION UI on the entity you attached it to.

### Input fields

| Field            | Type      | Notes                                                                                                                     |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `filename`       | `String`  | Display filename. It doesn't have to match the storage object's key.                                                      |
| `s3Key`          | `String`  | The `s3Key` value from step 1, which is the storage object key.                                                           |
| `s3Etag`         | `String`  | The `ETag` returned by the storage service in step 2's response, with quotes stripped.                                    |
| `entityId`       | `ID`      | The **entity ID** of the parent object. See [Choose an entityId](#choose-an-entityid).                                    |
| `validateUpload` | `Boolean` | When `true`, ION verifies that the uploaded object exists and matches the `ETag` before creating the record. Recommended. |

<Tip>
  Set `validateUpload` to `true`. ION makes one extra HEAD request and gives you
  immediate feedback when the registration doesn't match the uploaded bytes.
</Tip>

## Choose an entityId

The `entityId` is not the same as the parent object's `id`. ION lets multiple object types share a relationship to file attachments, so you pass the parent's entity ID rather than its own `id`. To attach a file to a run step, the most common case, first fetch the run step's `entity.id`:

```graphql theme={null}
query GetRunStepEntity($runStepId: ID!) {
  runStep(id: $runStepId) {
    id
    entity {
      id
    }
  }
}
```

Use the returned `entity.id`, not `runStep.id`, as the `entityId` in step 3.

The same pattern applies to other targets. Parts, runs, procedures, procedure steps, and run step fields all expose an `entity { id }` you can fetch and use.

| Attachment target | Fetch its `entity.id` via            |
| ----------------- | ------------------------------------ |
| Run step          | `runStep(id) { entity { id } }`      |
| Run               | `run(id) { entity { id } }`          |
| Procedure         | `procedure(id) { entity { id } }`    |
| Procedure step    | `step(id) { entity { id } }`         |
| Part              | `part(id) { entity { id } }`         |
| Run step field    | `runStepField(id) { entity { id } }` |

## End-to-end example in Python

```python theme={null}
import httpx
import os

ION_TOKEN = os.environ["ION_TOKEN"]
GQL_URL = "https://api.buildwithion.com/graphql"

def gql(query, variables=None):
    r = httpx.post(
        GQL_URL,
        headers={"Authorization": f"Bearer {ION_TOKEN}"},
        json={"query": query, "variables": variables or {}},
        timeout=30.0,
    )
    r.raise_for_status()
    payload = r.json()
    if "errors" in payload:
        raise RuntimeError(payload["errors"])
    return payload["data"]

def upload_to_run_step(run_step_id: int, file_path: str) -> int:
    filename = os.path.basename(file_path)

    # 1. Get a signed upload URL
    step_1 = gql(
        "query($f: String!) { requestFileUploadUrl(filename: $f) { uploadUrl s3Key contentType } }",
        {"f": filename},
    )["requestFileUploadUrl"]

    # 2. PUT the file to the signed URL, capture the ETag from the response
    with open(file_path, "rb") as f:
        upload_response = httpx.put(
            step_1["uploadUrl"],
            content=f.read(),
            headers={"Content-Type": step_1["contentType"]},
            timeout=120.0,
        )
    upload_response.raise_for_status()
    s3_etag = upload_response.headers["ETag"].strip('"')

    # 3. Resolve the run step's entity.id
    entity_id = gql(
        "query($id: ID!) { runStep(id: $id) { entity { id } } }",
        {"id": run_step_id},
    )["runStep"]["entity"]["id"]

    # 4. Register the attachment
    result = gql(
        """mutation($input: CreateFileAttachmentInput!) {
            createFileAttachment(input: $input) {
                fileAttachment { id filename }
            }
        }""",
        {
            "input": {
                "filename": filename,
                "s3Key": step_1["s3Key"],
                "s3Etag": s3_etag,
                "entityId": entity_id,
                "validateUpload": True,
            }
        },
    )
    return result["createFileAttachment"]["fileAttachment"]["id"]
```

For the full Python integration template, see [Build an API client](/api-reference/guides/python-quickstart).

## Common errors

| Symptom                                       | Cause                                                                      | Fix                                                                           |
| --------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `403 Forbidden` on the upload PUT             | The upload URL expired before the PUT request happened.                    | Re-request the URL and use it right away.                                     |
| `403 SignatureDoesNotMatch` on the upload PUT | The `Content-Type` header doesn't match what was signed.                   | Send exactly the `contentType` returned in step 1.                            |
| `validateUpload` mutation fails               | The `s3Etag` doesn't match what storage has.                               | Capture the `ETag` after a successful `200` response, not the request hash.   |
| Attachment created but not visible in the UI  | The wrong `entityId`, the parent's `id` instead of `entity.id`.            | Re-fetch the parent's `entity { id }` and register again.                     |
| `Permission denied` on `createFileAttachment` | The user or service account lacks attach permission for the target entity. | Check the role's permissions on the parent resource, such as run step update. |

## Verify the attachment

After step 3, you can confirm the attachment in two ways:

* In the ION UI, open the parent entity and check the attachments panel.
* Via the API, query the attachment back by ID:

```graphql theme={null}
query VerifyUpload($id: ID!) {
  fileAttachment(id: $id) {
    id
    filename
    downloadUrl
    entityId
  }
}
```

The `downloadUrl` is a fresh signed download URL, time-bound the same way the upload URL was. Don't cache it long-term.

<Tip>
  Set a longer timeout for the upload PUT in step 2 than for your GraphQL
  requests. For large files, the upload is the slowest part of the flow.
</Tip>

## Related

* [Authentication](/api-reference/authentication)
* [Build an API client](/api-reference/guides/python-quickstart)
* [Example requests](/api-reference/examples)
* [Error codes](/api-reference/error-codes)


# Manage mBOM items
Source: https://docs.firstresonance.io/api-reference/guides/mboms

Query and manage mBOM items and substitutes through the ION GraphQL API.

An mBOM item represents the bill of materials required to construct a part. A part has an mBOM made up of many mBOM items, which dictate the subparts used in the part's construction. You can think of parts as a tree structure, where the nodes are part objects and the edges are mBOM items. The root of the tree is a part representing a completed assembly. Its mBOM is the parts used in its construction. Each of those parts can have its own mBOM. Maintaining this tree structure through the mBOM and subsequent aBOM is a vital part of ION.

## mBOM items

| mBOM item   | Description                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| id          | Unique identifier of the mBOM item object.                                                                       |
| parent      | The [part](/api-reference/guides/parts-and-part-revisioning) object whose construction this mBOM item describes. |
| part        | The [part](/api-reference/guides/parts-and-part-revisioning) object used in the construction of the parent.      |
| quantity    | The amount of a specific part needed in construction.                                                            |
| substitutes | List of valid substitutes that can be used in place of the specified part.                                       |

## mBOM substitutes

An mBOM substitute is a valid alternative that can be used in place of the defined part. Each mBOM item can have many mBOM substitutes, which are subpart replacements for that specific subpart.

| mBOM substitute | Description                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| id              | Unique identifier of the mBOM substitute object.                                                                           |
| part            | The [part](/api-reference/guides/parts-and-part-revisioning) object that can be substituted for the part in the mBOM item. |
| mbomItem        | The mBOM item for which this object is a valid substitute.                                                                 |

## Query an mBOM item

The queries below list mBOM items by a filter or get a specific mBOM item. It is often more effective to query the mBOM relation through a part object.

List mBOM items with a filter:

```graphql theme={null}
query MBOMItems($filters: MBomItemsInputFilters) {
    mbomItems(filters: $filters) {
        edges {
            node {
                id partId parentId quantity
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "parentId": {
            "eq": 1
        }
    }
}
```

Get a single mBOM item by ID:

```graphql theme={null}
query GetMBOMItem {
    mbomItem(id: 1) {
        id partId parentId quantity
    }
}
```

## Explode a multi-level mBOM

`mbomExplosion` returns every descendant line of a root assembly's mBOM in one request, so you don't have to walk the tree one request per node.

```graphql theme={null}
query MBomExplosion($input: MBomExplosionInput!) {
    mbomExplosion(input: $input) {
        edges {
            node {
                level parentPartId quantity totalQuantity
                mbomItem {
                    id partId parentId
                }
            }
        }
    }
}
```

Set the variables:

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

Each node describes one line of the exploded tree:

| Field           | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| `level`         | Depth in the tree. Lines on the root mBOM are level 1.                                |
| `parentPartId`  | The part whose assembly this line sits under.                                         |
| `quantity`      | The line's own quantity, per one unit of its parent assembly.                         |
| `totalQuantity` | The quantity rolled up through the tree: the parent's total multiplied by `quantity`. |
| `mbomItem`      | The underlying mBOM item, so you can select the part, substitutes, and designators.   |

Lines come back depth-first, so you can rebuild the tree, or write a CSV, straight from the order they arrive in.

`partId` is required. `mbomId` is optional and sets the version used for the **root** level only: pass it to explode a specific version, or omit it to use the part's released mBOM, falling back to its latest when there is no released version. Nested levels always resolve released-else-latest. Passing an `mbomId` that belongs to a different part returns a validation error.

### What the results leave out

Three cases drop lines from the response without returning an error, so check for them before treating a result as a complete tree:

* **Repeated parts.** If a part already appears higher in the same branch, the line for it is left out of the results entirely, rather than returned without its children. A cyclic mBOM terminates instead of looping.
* **Export-controlled parts.** When you aren't allowed to see an export-controlled part, its line is omitted along with everything below it. If the **root** assembly itself is export-controlled, the query returns no lines at all, which reads the same as an assembly that has no mBOM.
* **Very deep trees.** Explosion stops after 100 levels. Anything deeper is dropped silently.

## Query an mBOM substitute

The queries below list mBOM substitutes by a filter or get a specific mBOM substitute.

List mBOM substitutes with a filter:

```graphql theme={null}
query MBOMSubstitutes($filters: MBomSubstituteInputFilters) {
    mbomSubstitutes(filters: $filters) {
        edges {
            node {
                id partId parentId mbomItemId
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "mbomItemId": {
            "eq": 1
        }
    }
}
```

Get a single mBOM substitute by ID:

```graphql theme={null}
query MBOMSubstitute {
    mbomSubstitute(id: 1) {
        id partId parentId mbomItemId
    }
}
```

## Create an mBOM item

An mBOM item defines which parts and how many of those parts are required to build a new part. The parent is the relation to the part being built, and the part relation is the part required in the build. The quantity value must be greater than 0. Returns the newly created mBOM item.

Create the mBOM item with this mutation:

```graphql theme={null}
mutation($input: CreateMBomItemInput!){
  createMbomItem(input: $input){
      mbomItem {
          id parentId partId quantity
      }
  }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "parentId": 2,
        "partId": 1,
        "quantity": 3
    }
}
```

## Update an mBOM item

You can update the quantity of an mBOM item and its associated part. Returns the updated mBOM item.

Update the mBOM item with this mutation:

```graphql theme={null}
mutation UpdateMBomItem($input: UpdateMBomItemInput!) {
  updateMbomItem(input: $input) {
    mbomItem {
      id parentId partId quantity
    }
  }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "etag": "etag1",
        "id": 1,
        "partId": 3,
        "quantity": 5
    }
}
```

## Create mBOM substitutes

Create a valid substitution for a specific part within an mBOM. Any parts listed with mBOM substitutes do not raise a validation error if they are attached to an aBOM instead of the part specified in the original mBOM item.

Create the mBOM substitutes with this mutation:

```graphql theme={null}
  mutation CreateMbomSubstitutes($input:
                                 [CreateMBomSubstituteInput]!){
    createMbomSubstitutes(input: $input){
      mbomSubstitutes {
        id parentId partId mbomItemId
      }
    }
  }
```

Set the variables:

```json theme={null}
{
    "input": [
        { "partId": 3, "parentId": 2, "mbomItemId": 1 },
        { "partId": 4, "parentId": 2, "mbomItemId": 1 }
    ]
}
```

## Delete an mBOM item

You can delete an mBOM item unless it has already been used in the construction of an aBOM. Returns the ID of the deleted mBOM item.

Delete the mBOM item with this mutation:

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

Set the variables:

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

## Delete an mBOM substitute

Delete an mBOM substitute. Returns the ID of the deleted mBOM substitute.

Delete the mBOM substitute with this mutation:

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

Set the variables:

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

## Related

* [Manage parts and revisions](/api-reference/guides/parts-and-part-revisioning)
* [Build an aBOM](/api-reference/guides/abom-as-built-bill-of-materials-api)


# Send a custom notification
Source: https://docs.firstresonance.io/api-reference/guides/notifications

Send custom notifications to ION users with the dispatchNotification GraphQL mutation.

ION has a notification system built into the application's workflows, with both native notifications and notifications you can send through the ION API. For example, when you're assigned to an approved issue disposition, you receive a toast notification while you're using the application and a notification in the notifications tab.

Toast notifications appear in the interface. ION checks for toast notifications every 30 seconds, so a toast can take up to 30 seconds to appear.

To view all notifications in detail, go to the notification page by clicking the envelope icon and selecting **Show all**.

## Send a custom notification

Use the `dispatchNotification` mutation to send custom notifications:

```graphql theme={null}
mutation notification($input:DispatchNotificationInput!){
  dispatchNotification(input: $input){
    response{
      messageId
    }
  }
}
```

Use these query variables:

```json theme={null}
{
  "input": {
    "userId": 3660,
    "notificationType": "WARNING",
    "description": "Purchase order versioned and PDF file generated. Please refresh.",
    "title": "PO Versioned & PDF Generated",
    "linkText": "This is the link",
    "path": "https://app-v2.buildwithion.com/"
  }
}
```

The query variables are:

* `userId`: The ID of the user you want to send the notification to.
* `notificationType`: The type of notification to dispatch. In this example, `WARNING` signifies a critical notification.
* `description`: A brief description of the notification's content.
* `title`: The title of the notification, displayed in the toast notification.
* `linkText`: The text displayed as the link in the notification page, directing users to further details or actions.
* `path`: The URL path users go to when they click either the toast notification or the notification in the application.

## Notification types

ION supports the following notification types:

* `EXTERNAL` (blue): Notifications originating from external systems, typically used for general updates.
* `SIGNOFF` (yellow): Notifications requiring user attention or signoff.
* `WARNING` (red): A critical event the user should be aware of.


# Paginate query results
Source: https://docs.firstresonance.io/api-reference/guides/pagination

Use cursor-based pagination to fetch large GraphQL result sets in batches and avoid timeouts.

For any query that returns a list of results, you should use pagination. Without pagination, a large query is more likely to time out and return a 502 error. A 502 occurs when an API call doesn't receive a response within 30 seconds. You fetch further results as you need them.

The ION GraphQL API uses a cursor pagination pattern.

## Fetch the first page

This example queries the first five parts with the `first` parameter and fetches the `endCursor` in the `pageInfo` object:

```graphql theme={null}
{
  parts(first: 5) {
    edges {
      node {
        id
      }
    }
    pageInfo {
      endCursor         # use this to fetch the next page
      hasNextPage       # are there more parts after this page?
      totalCount        #total number of parts
      count             #number of parts returned by this query
    }
  }
}
```

The response includes the requested edges and the `pageInfo` object:

```json theme={null}
{
  "data": {
    "parts": {
      "edges": [
        {
          "node": {
            "id": 20
          }
        },
        {
          "node": {
            "id": 22
          }
        },
        {
          "node": {
            "id": 24
          }
        },
        {
          "node": {
            "id": 26
          }
        },
        {
          "node": {
            "id": 28
          }
        }
      ],
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW9uOjE5",
        "hasNextPage": true,
        "totalCount": 1259,
        "count": 5
      }
    }
  }
}
```

In addition to `first`, ION queries have the pagination parameters `last`, `before`, and `after`.

## Fetch the next page

To fetch the next page, pass the `endCursor` from the previous query to the `after` parameter:

```graphql theme={null}
{
  parts(first: 5, after: "YXJyYXljb25uZWN0aW9uOjE5") {
    edges {
      node {
        id
      }
    }
    pageInfo {
      endCursor         # use this to fetch the next page
      hasNextPage       # are there more parts after this page?
      totalCount        #total number of parts
      count             #number of parts returned by this query
    }
  }
}
```

This example returns the next five parts after the part identified by that cursor. To query every part in ION, repeat this pattern to fetch parts in batches of five. Use `hasNextPage` to determine whether more results remain after each query.


# Manage part inventory and kitting
Source: https://docs.firstresonance.io/api-reference/guides/part-inventory-and-kitting

Create part inventory through the ION API, issue parts to kits to allocate inventory to runs, and move parts back to inventory.

## Inventory

ION tracks parts by serial number or lot number. You can also leave a part untracked and record only its quantity. Part inventory holds information about a part and sets it up so you can track it in runs and aBOM construction. This page covers how to create part inventory objects, issue those parts to part kits to allocate inventory to runs, and move new or unused parts back into inventory.

| Part inventory | Description                                                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id             | Unique identifier for a part inventory object.                                                                                                                                                  |
| serialNumber   | Required if the part is serial tracked. Must be unique per part, so another inventory object with the same part relation cannot have a matching serial number. Can optionally be autogenerated. |
| lotNumber      | Required if the part is lot tracked. Can optionally be autogenerated.                                                                                                                           |
| location       | Location where the inventory object is stored.                                                                                                                                                  |
| part           | [Part](/api-reference/guides/parts-and-part-revisioning) that this inventory object is an instance of.                                                                                          |
| unitOfMeasure  | How the quantity of this inventory object is measured.                                                                                                                                          |
| quantity       | Amount of inventory present.                                                                                                                                                                    |
| runs           | [Runs](/api-reference/guides/runs) related to this inventory object.                                                                                                                            |
| installed      | `true` if all quantity is attached to aBOM items, otherwise `false`.                                                                                                                            |
| kitted         | `true` if all quantity is kitted to runs, otherwise `false`.                                                                                                                                    |

### Inventory tracking types

| Tracking type |                                                                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| serial        | Any inventory with a serial number has the serial tracking type. It can also have a lot number in addition. Serialized inventory objects can only have a quantity of 0 or 1. |
| lot           | Any inventory object with a lot number and no serial number is lot tracked. Lot-tracked items must have a quantity greater than or equal to 0.                               |
| untracked     | If a part inventory has neither a serial nor a lot number, it is an untracked item. There are no quantity restrictions on an untracked part.                                 |

### Query part inventories

The queries below list part inventories by a filter or get a specific inventory object:

List part inventory with a filter:

```graphql theme={null}
query PartInventories($filters: PartInventoriesInputFilters, $sort: [PartInventorySortEnum]) {
    partInventories(sort: $sort, filters: $filters, first: 50) {
        edges {
            node {
                id cost quantity usageType
                part { partNumber }
                location { id }
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "locationId": {
            "eq": 1
        }
    }
}
```

Get a single part inventory record by ID:

```graphql theme={null}
query PartInventory {
    partInventory(id: 1) {
        id cost quantity usageType
        part { partNumber }
        location { id }
    }
}
```

### Create part inventories

Run the mutation below with the first inputs to create a part inventory object for the serial part with part id 1. Run the mutation again with the second inputs to create an inventory object for the lot-tracked part with part id 2. When you specify no quantity, the inventory object has a quantity of 0. You can also autogenerate the serial number and lot number using the last set of inputs.

Create the inventory with this mutation:

```graphql theme={null}
mutation CreatePartInventory($input: CreatePartInventoryInput!) {
    createPartInventory(input: $input) {
        partInventory {
            id quantity cost usageType createdById
            trackingType locationId supplierId _etag
        }
    }
}
```

Serialized parts can be part of lots too. The input can include a lot number. Serial-tracked parts cannot have a quantity greater than 1. Set the variables for a serialized part:

```json theme={null}
{
    "input": {
        "serialNumber": "sn-1",
        "lotNumber": "123",
        "quantity": 1,
        "partId": 1,
        "supplierId": 1,
        "locationId": 5
    }
}
```

Set the variables for a lot-tracked part:

```json theme={null}
{
    "input": {
        "lotNumber": "lot-12",
        "partId": 2,
        "supplierId": 1,
        "locationId": 5
    }
}
```

Autogenerate a serial or lot number with these variables:

```json theme={null}
{
    "input": {
        "autogenerateSerialNumber": true,
        "autogenerateLotNumber": true,
        "lotNumber": "123",
        "quantity": 1,
        "partId": 1,
        "supplierId": 1,
        "locationId": 5
    }
}
```

### Update inventory items

You can change almost all the fields on an inventory object except its relation to the part it is an instance of. All the quantity and tracking-type validations enforced on creation are also enforced on update. The mutation returns the updated part inventory object.

Update the inventory with this mutation:

```graphql theme={null}
mutation UpdatePartInventory($input: UpdatePartInventoryInput!) {
    updatePartInventory(input: $input) {
        partInventory {
            id quantity cost locationId serialNumber lotNumber
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "id": 1,
        "etag": "etag1",
        "lotNumber": "ion-21",
        "cost": 11.21,
        "locationId": 1
    }
}
```

### Delete part inventories

Delete a part inventory object using the following mutation. It returns the id of the deleted part inventory object.

Delete the inventory with this mutation:

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

Set the variables:

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

## Issue parts to runs

### Part kits

Part kits let you allocate specific parts and quantities for a run. To create a part kit, you must already have a run. See the [Runs](/api-reference/guides/runs) example for how to create one.

To remove parts from inventory and attach them to the run that consumes them, use a part kit object. The mutation below creates a part kit and attaches it to a run:

| Part kits       | Description                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| id              | Unique identifier for a part kit object.                                                                                           |
| run             | [Run](/api-reference/guides/runs) that inventory objects are kitted to.                                                            |
| partInventories | Inventory objects with an additional field, `issuedQuantity`, which identifies the quantity of the inventory allocated to the run. |

Create a kit with this mutation:

```graphql theme={null}
mutation CreatePartKit($input: CreatePartKitInput!) {
    createPartKit(input: $input) {
        partKit {
            id run { id title }
        }
    }
}
```

Set the variables:

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

### Issue inventory to kits

To move parts from inventory into the part kit, use the `issueItemToKit` mutation. Whether a part is serial-tracked, lot-tracked, or untracked, you reference its `partInventoryId` and, when the item is not serial-tracked, the `quantity` you want to issue to that kit:

Issue an item to the kit with this mutation:

```graphql theme={null}
mutation IssueItemToKit($input: InventoryToKitInput!) {
    issueItemToKit(input: $input) {
        partInventory {
            id serialNumber partKits { id }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "partInventoryId": 1,
        "etag": "etag",
        "partKitItemId": 1
    }
}
```

Issuing serials, lots, or untracked parts works similarly and uses the same `issueItemToKit` mutation. When you issue parts to a kit, the kit shows the quantity of that required part fulfilled as `issuedQuantity`. The quantity is decremented from the original inventory object.

### Move parts back to inventory

Once a serial-tracked part is built, move it back to inventory for use on a higher-level assembly. To do so, use the `moveItemToInventory` mutation:

Move an item back to inventory with this mutation:

```graphql theme={null}
mutation MoveItemToInventory($input: InventoryToKitInput!) {
    moveItemToInventory(input: $input) {
        partInventory {
           id quantity partId serialNumber lotNumber 
           location { name } partKits { id }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "quantity": 2,
        "partKitItemId": 1, 
        "etag": "etag",
        "partInventoryId": 3
    }
}
```

Include the quantity in case a lot-tracked or untracked inventory item with a quantity greater than 1 needs to move back to inventory, but not the full amount originally issued. You must include the quantity you are moving back to inventory.

### Query part kits

List part kits with a filter:

```graphql theme={null}
query PartKits($filters: PartKitsInputFilters) {
    partKits(filters: $filters) {
        edges{
            node {
                id
                run { id }
                partInventories { id issuedQuantity }
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "runId": {
            "eq": 1
        }
    }
}
```

## Related

* [Manage parts and revisions](/api-reference/guides/parts-and-part-revisioning)
* [Create a run](/api-reference/guides/runs)
* [Build an aBOM](/api-reference/guides/abom-as-built-bill-of-materials-api)


# Manage parts and revisions
Source: https://docs.firstresonance.io/api-reference/guides/parts-and-part-revisioning

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-v2.buildwithion.com/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`.


# Build an API client
Source: https://docs.firstresonance.io/api-reference/guides/python-quickstart

A runnable Python integration template for ION: authenticate, list parts, create a run, and attach a file.

## Overview

This page gives you a working Python integration. Each function maps to one ION operation you can lift into your own codebase. By the end you have:

* A reusable `IonClient` that handles auth, query and mutation calls, and error parsing.
* Working examples for four common starting tasks: list parts, create a run, submit a run step result, and upload a file attachment.
* Patterns for fragments, error handling, and retry with backoff.

The script needs two environment variables:

```bash theme={null}
export ION_BASE_URL="https://api.buildwithion.com"
export ION_TOKEN="<your-access-token>"
```

If you don't have a token yet, see [Getting a token](/api-reference/authentication).

## Set up the environment

```bash theme={null}
python -m venv .venv
source .venv/bin/activate
pip install "httpx>=0.27" "tenacity>=8.0"
```

You don't need a GraphQL-specific client. `httpx` handles the transport. `tenacity` gives you declarative retry. If you prefer the `gql` library, these patterns translate directly.

## Build the client

```python theme={null}
import os
import httpx
from typing import Any
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type

class IonError(RuntimeError):
    """Raised when ION returns errors[] in the response body."""
    def __init__(self, errors: list[dict[str, Any]]):
        self.errors = errors
        super().__init__("; ".join(e.get("message", "") for e in errors))


class IonClient:
    def __init__(self, base_url: str | None = None, token: str | None = None):
        self.base_url = (base_url or os.environ["ION_BASE_URL"]).rstrip("/")
        self.token = token or os.environ["ION_TOKEN"]
        self._http = httpx.Client(
            base_url=self.base_url,
            headers={"Authorization": f"Bearer {self.token}"},
            timeout=30.0,
        )

    @retry(
        retry=retry_if_exception_type((httpx.HTTPError,)),
        stop=stop_after_attempt(3),
        wait=wait_exponential(multiplier=1, min=1, max=10),
        reraise=True,
    )
    def _post_graphql(self, query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
        r = self._http.post(
            "/graphql",
            json={"query": query, "variables": variables or {}},
        )
        r.raise_for_status()
        payload = r.json()
        if payload.get("errors"):
            raise IonError(payload["errors"])
        return payload["data"]

    def query(self, query: str, **variables) -> dict[str, Any]:
        return self._post_graphql(query, variables)

    def mutate(self, mutation: str, **variables) -> dict[str, Any]:
        return self._post_graphql(mutation, variables)

    def close(self):
        self._http.close()
```

You only call `IonClient.query` and `IonClient.mutate`. `_post_graphql` handles transport-level retries for 5xx and network errors. It surfaces GraphQL-level errors as `IonError`.

## Confirm the token works

Check who you are authenticated as before you do anything else:

```python theme={null}
ME = """
query CurrentUser {
  me {
    id
    name
    email
    organization { id domain }
  }
}
"""

with IonClient() as ion:
    me = ion.query(ME)["me"]
    print(f"Authenticated as {me['name']} ({me['email']}) in org {me['organization']['domain']}")
```

If this fails, see the [401 table in Error codes](/api-reference/error-codes#401-unauthorized). The error message names the fix.

## List parts

```python theme={null}
LIST_PARTS = """
query Parts($filters: PartsInputFilters, $first: Int) {
  parts(filters: $filters, first: $first) {
    edges {
      node {
        id
        partNumber
        description
        revision
        partType
        status
        partSubtypes { id name }
      }
    }
  }
}
"""

with IonClient() as ion:
    edges = ion.query(LIST_PARTS, filters={}, first=20)["parts"]["edges"]
    for edge in edges:
        p = edge["node"]
        subtypes = ", ".join(s["name"] for s in p["partSubtypes"]) or "—"
        print(f"{p['partNumber']}\t{p['description']}\t{subtypes}")
```

## Create a run

```python theme={null}
CREATE_RUN = """
mutation CreateRun($input: CreateRunInput!) {
  createRun(input: $input) {
    run {
      id
      title
      status
      procedure { id title }
      partInventory { id serialNumber }
    }
  }
}
"""

with IonClient() as ion:
    new_run = ion.mutate(
        CREATE_RUN,
        input={
            "procedureId": 12,
            "partInventoryId": 9876,
            "title": "Build #2026-04-26 Unit 1",
        },
    )["createRun"]["run"]
    print(f"Created run {new_run['id']}: {new_run['title']}")
```

Replace `procedureId` and `partInventoryId` with real IDs from your org. To find candidate procedures, see [Example requests](/api-reference/examples).

## Submit a run step result

```python theme={null}
SUBMIT_STEP = """
mutation SubmitStep($input: UpdateRunStepInput!) {
  updateRunStep(input: $input) {
    runStep {
      id
      status
      endTime
      fields { id name value }
    }
  }
}
"""

with IonClient() as ion:
    result = ion.mutate(
        SUBMIT_STEP,
        input={
            "id": 4567,
            "etag": "abc123",        # required for optimistic concurrency
            "status": "COMPLETE",
        },
    )["updateRunStep"]["runStep"]
    print(f"Step {result['id']} → {result['status']} at {result['endTime']}")
```

The `etag` field is required on update. For details, see [Etag-based concurrency](/api-reference/data-model#etag-based-concurrency). If you get a 409, re-fetch the run step, take its new etag, and retry.

## Upload a file attachment

This is the full three-step pattern from [File upload](/api-reference/guides/file-upload):

```python theme={null}
import os

REQUEST_UPLOAD = """
query Upload($filename: String!) {
  requestFileUploadUrl(filename: $filename) {
    uploadUrl
    s3Key
    contentType
  }
}
"""

GET_RUN_STEP_ENTITY = """
query StepEntity($id: ID!) {
  runStep(id: $id) {
    entity { id }
  }
}
"""

CREATE_FILE_ATTACHMENT = """
mutation CreateAttachment($input: CreateFileAttachmentInput!) {
  createFileAttachment(input: $input) {
    fileAttachment { id filename downloadUrl }
  }
}
"""

def attach_to_run_step(ion: IonClient, run_step_id: int, file_path: str) -> int:
    filename = os.path.basename(file_path)

    # 1. Get a signed upload URL
    upload = ion.query(REQUEST_UPLOAD, filename=filename)["requestFileUploadUrl"]

    # 2. PUT the file to S3, capture the ETag
    with open(file_path, "rb") as f:
        s3_response = httpx.put(
            upload["uploadUrl"],
            content=f.read(),
            headers={"Content-Type": upload["contentType"]},
            timeout=120.0,
        )
    s3_response.raise_for_status()
    s3_etag = s3_response.headers["ETag"].strip('"')

    # 3. Resolve the run step's entity.id (NOT the run step's own id)
    entity_id = ion.query(GET_RUN_STEP_ENTITY, id=run_step_id)["runStep"]["entity"]["id"]

    # 4. Register the attachment
    attachment = ion.mutate(
        CREATE_FILE_ATTACHMENT,
        input={
            "filename": filename,
            "s3Key": upload["s3Key"],
            "s3Etag": s3_etag,
            "entityId": entity_id,
            "validateUpload": True,
        },
    )["createFileAttachment"]["fileAttachment"]
    return attachment["id"]


with IonClient() as ion:
    attachment_id = attach_to_run_step(ion, run_step_id=4567, file_path="./inspection.jpg")
    print(f"Attached file id={attachment_id}")
```

Two parts of this pattern are easy to miss. You must capture the S3 ETag. You must fetch `entity.id`, not the parent's `id`. Both are documented in [File upload](/api-reference/guides/file-upload).

## Error handling pattern

The `IonClient` raises `IonError` on GraphQL-level errors. It uses `tenacity` for transport retries. Wrap your business logic in a try and except block that handles each error type:

```python theme={null}
from httpx import HTTPStatusError, ConnectError

def safely_create_run(ion: IonClient, **inputs) -> int | None:
    try:
        result = ion.mutate(CREATE_RUN, input=inputs)
    except IonError as e:
        # GraphQL errors[] — usually 4xx auth/permission/validation
        # Surface to the user; don't retry blindly
        print(f"ION rejected the request: {e}")
        return None
    except HTTPStatusError as e:
        # 5xx after retries exhausted
        print(f"ION 5xx after retries: {e.response.status_code}")
        return None
    except ConnectError:
        # Network down
        print("Cannot reach ION")
        return None
    return result["createRun"]["run"]["id"]
```

For the full HTTP status reference and the GraphQL `errors[]` payload shape, see [Error codes](/api-reference/error-codes).

## Reuse fragments

When several queries return the same entity, such as parts, runs, or purchase orders, define one fragment per entity and inline it everywhere:

```python theme={null}
FRAGMENTS = """
fragment PartFields on Part {
  id
  partNumber
  description
  revision
  partType
  status
  partSubtypes { id name }
}

fragment RunFields on Run {
  id
  title
  status
  procedure { id title }
  partInventory { id serialNumber part { ...PartFields } }
}
"""

LIST_RUNS_WITH_PARTS = FRAGMENTS + """
query Runs($filters: RunsInputFilters) {
  runs(filters: $filters) {
    edges {
      node {
        ...RunFields
      }
    }
  }
}
"""
```

This keeps field selection consistent across calls. A forgotten field, such as `_etag`, becomes a one-line fix instead of a multi-file refactor.

## Related

* [Example requests](/api-reference/examples)
* [Data model](/api-reference/data-model)
* [Set up webhooks](/api-reference/guides/webhooks)
* [API playground](/api-reference/playground)


# Create a run
Source: https://docs.firstresonance.io/api-reference/guides/runs

Create a run from a procedure using the ION GraphQL API.

## Create a run

The following mutation creates a run from a procedure:

```graphql theme={null}
mutation CreateRun($input: CreateRunInput!) {
    createRun(input: $input) {
        run {
            id title procedureId createdById
            dueDate assignedToId description
            partInventory {
                serialNumber
            }
        }
    }
}
```

Use these query variables:

```json theme={null}
{
    "input": {
        "title": "run title",
        "procedureId": 1,
        "dueDate": "2021-09-28T16:57:37",
        "partInventoryId": 2
    }
}
```

## Let ION generate the title

Instead of sending a `title`, you can have ION build one from the organization's run title template. Set `autogenerateTitle` to `true` and omit `title`. Sending both is rejected.

```json theme={null}
{
    "input": {
        "autogenerateTitle": true,
        "procedureId": 1,
        "dueDate": "2021-09-28T16:57:37",
        "partInventoryId": 2
    }
}
```

<Note>
  When your organization has **Enforce run title template** turned on in **Settings > Production > Runs**, ION always generates the title and rejects a request that sends `title`. Omit `title` from both the mutation and the query variables, or set `bypassEnforceRunTitle` to `true` to send your own title anyway. For the template itself, see [Configure run enforcement](/administration/production-settings/configure-run-enforcement).
</Note>


# Set up webhooks
Source: https://docs.firstresonance.io/api-reference/guides/webhooks

Register, subscribe, secure, and test a webhook receiver so your service reacts to changes in ION.

Webhooks let your service react to changes in ION without polling. You register a receiver, which is a URL plus a shared secret then subscribe it to specific events. ION then posts a JSON message to your URL whenever a matching change is committed.

## When to use webhooks vs polling

Use webhooks when:

* Your system can accept inbound HTTP.
* You want low-latency reactions to changes.
* You want to avoid polling for changes.

Stick with polling when:

* Your system can't accept inbound HTTP.
* You only need data on a schedule.
* You need a pull-only model for compliance.

## How delivery works

ION fires a webhook on the change itself, not on the API call that made it. Any committed change to a subscribed `(resource, action)` triggers a delivery, no matter where it came from: the GraphQL API, the ION UI, or an automated action.

Once a matching change commits, ION builds one delivery per matching subscription and POSTs the JSON body to your receiver URL with the `x-ion-signature` header. Delivery is at-least-once: if your receiver returns a non-success response, ION retries.

## Event types

A subscription is a `(resource, action)` pair where:

* `action` is one of `CREATE`, `UPDATE`, or `DELETE`, the operation that fires the webhook.
* `resource` is one of ION's webhookable entities. The schema exposes the full list: use the [API Playground](/api-reference/playground) and inspect the `ResourceEnum` type.

Common resources customers subscribe to:

| Resource           | Typical use case                                                           |
| ------------------ | -------------------------------------------------------------------------- |
| `RUNS`             | Track when production runs are created, updated, or completed              |
| `RUN_STEPS`        | React when a run step is signed off, failed, or has a measurement recorded |
| `PARTS`            | Sync the part library into an external ERP                                 |
| `PARTS_INVENTORY`  | Mirror inventory state into an MES or warehouse system                     |
| `ISSUES`           | Push quality events into a ticketing system                                |
| `PURCHASE_ORDERS`  | Notify procurement on PO state changes                                     |
| `FILE_ATTACHMENTS` | React to new uploads                                                       |

## Payload shape

Every delivery is a JSON POST with this shape:

```json theme={null}
{
  "event_id": 123456,
  "subscription_id": 42,
  "resource": "run_steps",
  "action": "update",
  "transaction_id": 9876543,
  "occurred_at": "2026-04-26T19:33:42.108Z",
  "data": {
    "id": 1234,
    "etag": "abc123",
    "old": { "status": "in_progress" },
    "new": { "status": "complete", "completed_at": "2026-04-26T19:33:42.108Z" }
  }
}
```

| Field                  | Meaning                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `event_id`             | Unique ID for this delivery, used as the idempotency key. See [Idempotency and deduplication](#idempotency-and-deduplication) |
| `subscription_id`      | Which subscription fired this delivery                                                                                        |
| `resource`, `action`   | The `(resource, action)` pair                                                                                                 |
| `transaction_id`       | The DB transaction that produced this change. Events from the same transaction share this ID, which is useful for correlating |
| `occurred_at`          | When the change committed (UTC, ISO 8601)                                                                                     |
| `data.id`              | The primary key of the affected row                                                                                           |
| `data.etag`            | The new etag of the row, for follow-up writes                                                                                 |
| `data.old`, `data.new` | The fields that changed and their before and after values. `old` is null on `CREATE`; `new` is null on `DELETE`               |

<Note>
  `data.old` and `data.new` contain only the fields that changed, and one side
  is always null on a `CREATE` or `DELETE`, so don't assume both are populated.
  If you need the full current state of the entity, requery it through the API
  using `data.id`. The webhook is a change notification, not a full snapshot.
</Note>

## Signature verification

Every delivery includes an HMAC signature in the `x-ion-signature` header. Verify it before trusting the payload. Anyone can reach your endpoint. Only you and ION hold the secret.

The signature signs the receiver URL plus the `data` field's keys and values (alphabetically sorted, `null` values excluded), not the raw body:

```text theme={null}
params       = sorted_alphabetically([f"{k}:{v}" for k, v in data.items() if v is not None])
signed_data  = f"{webhook_uri}?{'&'.join(params)}".encode("utf-8")
signature    = base64(hmac_sha1(shared_secret.encode("utf-8"), signed_data))
```

Implement the same construction on your side and compare:

```python theme={null}
import base64
import hmac
import hashlib

def verify_signature(secret: str, url: str, data: dict, header_signature: str) -> bool:
    params = [f"{k}:{v}" for k, v in sorted(data.items()) if v is not None]
    signed = f"{url}?{'&'.join(params)}".encode("utf-8")
    expected = base64.b64encode(
        hmac.new(secret.encode("utf-8"), signed, hashlib.sha1).digest()
    ).decode()
    return hmac.compare_digest(expected, header_signature)
```

Always use `hmac.compare_digest` or your language's equivalent. A constant-time comparison prevents timing attacks.

## Custom headers

| Header            | Purpose                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `content-type`    | `application/json`, controlled by the receiver's `contentType` setting                                                 |
| `x-ion-signature` | HMAC signature. See [Signature verification](#signature-verification)                                                  |
| Custom headers    | Anything you registered via `addHeaderToWebhookReceiver`, such as auth tokens for downstream gateways or routing hints |

Custom headers are useful when your receiver sits behind an API gateway that requires its own auth, such as an internal API key. Register them once per receiver via `WebhookHeader` mutations and ION attaches them to every delivery.

## Delivery guarantees and retries

* **At-least-once.** ION redelivers if your receiver returns anything other than the configured `expectedResponseCode` (default 200).
* **Retries** follow exponential backoff. Persistent failures eventually mark the event as failed. The failed event is preserved so you can inspect it by querying `webhookEvents`.
* **No ordering guarantees** between independent transactions. Two updates to the same row in one transaction always arrive before any update in a later transaction, but parallel transactions can interleave.
* **No exactly-once.** Build your receiver to be idempotent.

<Tip>
  ION times out a delivery that takes longer than 5 seconds to respond. If your
  processing is slow, acknowledge with a 200 right away and queue the work to
  run asynchronously downstream.
</Tip>

## Idempotency and deduplication

Use `event_id` as your idempotency key. Maintain a recent-events store on your side and short-circuit re-deliveries:

```python theme={null}
def handle(event):
    if seen.contains(event["event_id"]):
        return 200  # already processed; ack to stop retries
    seen.add(event["event_id"])
    process(event)
    return 200
```

`event_id` is unique per delivery and stable across retries.

## Register a receiver

Webhook receivers are registered via the GraphQL API. Create the receiver first:

```graphql theme={null}
mutation CreateReceiver($input: CreateWebhookReceiverInput!) {
  createWebhookReceiver(input: $input) {
    webhookReceiver {
      id
      name
      webhookUri
      sharedSecret # capture this once, needed to verify signatures
      contentType
      expectedResponseCode
    }
  }
}
```

```json theme={null}
{
  "input": {
    "name": "Acme Production Pipeline",
    "description": "Triggers Acme ETL on run completion",
    "webhookUri": "https://hooks.example.com/ion-events",
    "contentType": "json",
    "expectedResponseCode": 200
  }
}
```

The `sharedSecret` in the response is your HMAC key for [signature verification](#signature-verification). It's shown once, so store it like an API key.

<Warning>
  Capture the `sharedSecret` at creation. It's returned exactly once. If you
  lose it, you have to delete and recreate the receiver.
</Warning>

The `webhookUri` must be stable. Every change requires re-registering the
receiver. A fixed Ngrok tunnel works for local testing. A tunnel URL that
rotates on each restart does not work.

## Subscribe to events

Add one or more subscriptions to the receiver. Each subscription is one `(resource, action)` tuple:

```graphql theme={null}
mutation Subscribe($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    webhookSubscription {
      id
      resource
      action
      active
    }
  }
}
```

```json theme={null}
{
  "input": {
    "receiverId": 42,
    "resource": "RUN_STEPS",
    "action": "UPDATE",
    "active": true
  }
}
```

A receiver can have multiple subscriptions.

## Test the receiver

Before pointing production traffic at a new receiver:

1. **Register against your sandbox tenant.** See the [Sandbox guide](/api-reference/sandbox).
2. **Trigger known events.** Create, update, and delete a run step in the sandbox UI, then verify your receiver logs the deliveries.
3. **Inspect failed deliveries.** Query `webhookEvents` filtered by `subscription_id` and `status = "failed"` to see retry history and the request and response bodies ION recorded.

```graphql theme={null}
query FailedEvents($subscriptionId: ID!) {
  webhookEvents(
    filters: { subscriptionId: { eq: $subscriptionId }, status: { eq: FAILED } }
    first: 50
  ) {
    edges {
      node {
        id
        responseStatusCode
        responseReceivedAt
        requestData
        responseData
      }
    }
  }
}
```

This is the fastest way to debug "my receiver isn't firing." The cause is usually a non-200 response code, an SSL certificate issue, or a firewall.

## Monitor deliveries in ION

The same delivery log is browsable in the app: in ION, go to **Developer Platform > Webhook Deliveries**. The **Summary** banner counts loaded deliveries by status, and each row shows one attempt: **Timestamp**, **Status** (**succeeded**, **retrying**, **sending**, or **failed**; a retried delivery passes through several), **HTTP Status**, **Receiver Endpoint**, and **Response Body**. The response body is usually the fastest clue when a delivery fails. Click **Load More** to page through older deliveries.

## Related

* [Authentication](/api-reference/authentication)
* [Sandbox](/api-reference/sandbox)
* [API playground](/api-reference/playground)
* [Error codes](/api-reference/error-codes)


# MCP
Source: https://docs.firstresonance.io/api-reference/mcp-server

Connect AI agents like OpenAI Codex, Claude, and Cursor to ION through the Model Context Protocol (MCP) server.

The Model Context Protocol (MCP) is a standard interface that AI agents use to interact with ION. Agents like OpenAI Codex, Claude, and Cursor connect to the ION MCP server. A connected agent can query and act on your ION data in natural language. You can also build custom agents on top of ION with SDKs such as the AWS Strands SDK.

<Note>
  The ION MCP server is in beta. If you want to build on top of ION, reach out
  and we can help.
</Note>

## Authentication

The MCP server uses OAuth 2.1 dynamic client registration (DCR). You need an existing ION account to authenticate.

## Environments

Each environment has its own MCP server URL. Use the URL for the environment you want to connect to. If you need an environment that isn't listed, let us know.

| Environment           | URL                                            |
| --------------------- | ---------------------------------------------- |
| staging-pub (sandbox) | `https://mcp.staging.buildwithion.com/mcp`     |
| staging-gov (sandbox) | `https://mcp.staging.gov.buildwithion.com/mcp` |
| staging-aus (sandbox) | `https://mcp.staging.ap.buildwithion.com/mcp`  |
| production-pub        | `https://mcp.buildwithion.com/mcp`             |
| production-gov        | `https://mcp.gov.buildwithion.com/mcp`         |
| production-aus        | `https://mcp.ap.buildwithion.com/mcp`          |

## Connect your agent

<Tabs>
  <Tab title="OpenAI Codex">
    You need OpenAI Codex installed and signed in to connect to the ION MCP server.

    1. In your terminal, add the ION MCP server. Swap the name and URL for the environment you want:

       ```bash theme={null}
       codex mcp add ion --url https://mcp.staging.buildwithion.com/mcp
       ```

    2. Sign in to ION through Codex:

       ```bash theme={null}
       codex mcp login ion
       ```

    3. Complete the ION sign-in flow in your browser.

    4. Run `codex mcp list`, or use `/mcp` in the Codex terminal UI, to confirm the server is connected.

    5. Ask Codex for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

    Codex stores MCP server configuration in `~/.codex/config.toml`. The Codex CLI and Codex IDE extension use the same configuration.
  </Tab>

  <Tab title="Claude">
    You need a Claude Pro plan or above to connect to the ION MCP server.

    1. In Claude, go to **Your Profile > Settings > Connectors**. Click **Add custom connector**.
    2. Enter a name and the MCP URL for the environment you want. For example, use the name `ION-SANDBOX` and the URL `https://mcp.staging.buildwithion.com`.
    3. Click **Connect**. Claude prompts you to sign in to ION.
    4. Ask Claude for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

    <Frame>
      <img alt="Claude custom connector settings with the ION MCP server added" />
    </Frame>
  </Tab>

  <Tab title="Cursor">
    You need a Cursor plan to use Cursor.

    1. Open Cursor and go to **Cursor Settings**.

    2. Click **Tools and MCP > Add an MCP Server**.

    3. Enter this configuration. Swap the name and URL for the environment you want. You can add more than one:

       ```json theme={null}
       {
         "mcpServers": {
           "ion": {
             "url": "https://mcp.staging.buildwithion.com/mcp"
           }
         }
       }
       ```

    4. Turn on **Agent** mode. The chat window starts in **Ask** mode, which doesn't allow MCP servers.

    5. Ask Cursor for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

    <Frame>
      <img alt="Cursor Tools and MCP settings with the ION MCP server configured" />
    </Frame>
  </Tab>
</Tabs>


# API playground
Source: https://docs.firstresonance.io/api-reference/playground

Explore the ION GraphQL schema, write queries, and run them against your tenant from the docs.

The API playground lets you explore the ION GraphQL schema and run queries against your tenant before you write client code. Access it by going to **Developer Platform > GraphQL** on the sidebar.

## Authenticate

To run a query, first set your access token in the **Authorization** header field at the top of the playground:

```
Authorization: Bearer <your-token>
```

There are two ways to get a token:

* **API key**: exchange it for a token through your auth provider's client-credentials grant. See [Manage API keys](/api-reference/authentication/api-keys).
* **OAuth 2.0**: complete the authorization code flow and use the resulting access token. See [Authenticate with OAuth 2.0](/api-reference/authentication/oauth).

The playground stores tokens locally in your browser and sends them only to the ION API.

## Quick start

Run this query first to confirm your token works:

```graphql theme={null}
query Me {
  me {
    id
    name
    email
    organization {
      id
      domain
    }
  }
}
```

A successful response means your token is valid for the tenant in `organization.domain`. If you get an `errors[]` payload instead, see [Error codes](/api-reference/error-codes).

## What you can do here

<Warning>
  The playground runs mutations against the live API. Use a [sandbox
  tenant](/api-reference/sandbox) when prototyping mutations so you don't change
  production data.
</Warning>

* **Schema explorer**: click any type to see its fields, arguments, and return types. Hover over a field to see its description.
* **Autocomplete**: start typing a field and the playground suggests valid completions for the current selection set.
* **Variables panel**: pass query variables as JSON instead of hardcoding them in the query body.
* **Headers panel**: set **Authorization** and other custom headers.
* **History**: the playground saves every query you run locally. Re-run or share a saved query with teammates.
* **Schema docs sidebar**: type `__schema` or `__type` to run an introspection query and inspect the schema.

## Example Queries and Mutations

See [Example requests](/api-reference/examples).

## GraphQL Schema reference

The full GraphQL schema is also checked into this repository as [`schema.graphql`](/schema.graphql).

There are three ways to explore the schema:

1. **In the playground**: click around the schema explorer.
2. **In the file**: open `schema.graphql` in your editor.
3. **By introspection**: run `query { __schema { types { name kind } } }` from the playground.

<Tip>
  To find which query or mutation powers a page, open your browser's developer
  tools, go to the **Network** tab, and click around in ION. The app shows the
  exact queries, mutations, and filters it sends.
</Tip>

## Related

* [Authentication](/api-reference/authentication)
* [Getting started](/api-reference/getting-started)
* [Example requests](/api-reference/examples)
* [Sandbox](/api-reference/sandbox)


# Sandbox & dev environments
Source: https://docs.firstresonance.io/api-reference/sandbox

Request a non-production ION environment for integration development, learn what differs from production, and promote your integration when it's ready.

A sandbox is a separate, isolated ION tenant with seeded or copied data. Use one to build and test an integration against the ION API without affecting production.

## When to use a sandbox

Use a sandbox whenever you're:

* Building a new integration, such as an ETL, MES, ERP, Slack bot, or custom dashboard.
* Testing destructive operations, such as bulk inventory adjustments or mass run cancellations.
* Reproducing a customer support issue without touching live data.
* Running automated CI tests against the API.
* Onboarding a new developer who needs API access without production credentials.

If you're only reading data for a one-off report or analysis, production with a read-only API key works too. If you're writing data, use a sandbox first.

## Requesting access

To request a sandbox environment, contact [support](https://support.firstresonance.io) with:

* Why you need a sandbox, including which integration you're building.
* Who needs access, as a list of users or service accounts.
* What data shape you need: a blank org, seeded demo data, or a snapshot of your production tenant.

A typical sandbox is provisioned within a few business days. Sandboxes don't count against your production seat license. Heavy or long-lived sandbox usage can have contract implications. The support team confirms this if it applies.

## Differences from production

A sandbox tenant is operationally separate from production.

| Aspect           | Production                     | Sandbox                                                                                        |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| Base URL         | `https://api.buildwithion.com` | A separate domain provided when your sandbox is provisioned                                    |
| Auth provider    | Production auth provider       | A separate auth instance. **Production credentials do not work here.**                         |
| Data isolation   | Your production tenant         | Fully isolated. Nothing flows between sandbox and production.                                  |
| Rate limits      | Production fair-use limits     | Often more relaxed. Coordinate load testing with [support](https://support.firstresonance.io). |
| Feature flags    | Match your tier                | Can expose features early for evaluation                                                       |
| Data persistence | Permanent                      | Can be reset on request. Sandboxes expire if dormant for long periods.                         |
| SLA              | Production SLA                 | None. Sandboxes are best-effort.                                                               |
| Webhooks         | Live to your real consumers    | Configurable. The default is a sink, so test events don't reach your production consumers.     |

The most common stumbling block is auth credentials. API keys and OAuth apps are environment-scoped, so you have to register them inside the sandbox tenant. Using production credentials against sandbox (or the other way around) will result in `401 Unauthorized` errors.

## What data is available

When the sandbox is provisioned, you choose its starting state:

* **Blank org**: an empty tenant. You populate parts, procedures, and runs as part of testing.
* **Seeded demo data**: pre-populated with example parts, BOMs, and procedures. Best for new-developer onboarding.
* **Snapshot of your production tenant**: a copy of your real data at a point in time, with sensitive fields scrubbed. Best for reproducing production-only bugs. This option can be subject to compliance or legal review depending on your contract.

Sandboxes don't auto-sync from production. To get a fresh snapshot months later, request a refresh from [support](https://support.firstresonance.io).

## Best practices

* Seed test data programmatically. A script that creates a full part, procedure, run, and installation chain is easier to re-run than rebuilding state by hand each time the sandbox resets.
* Tag webhook payloads. When testing webhooks, prefix the consumer URL or set a header such as `X-Test-Run: 1`. This lets you distinguish sandbox-driven events from real ones in your downstream system.
* Smoke-test your integration after every sandbox reset. Even fully scripted setup occasionally drifts.

## Promoting an integration from sandbox to production

When your integration works in sandbox and you're ready for production:

1. **Register production credentials.** Create a new API key or OAuth app registration in the production tenant. Don't reuse sandbox credentials.
2. **Swap the environment config.** Update your service's environment variables, such as `ION_BASE_URL` and `ION_TOKEN`, to point at production.
3. **Verify with read-only operations first.** Start with `me` or a list query before any mutations.
4. **Roll out gradually.** If your integration writes to ION, ramp the volume rather than turning it on at full throughput. Watch for 4xx error rates and back off if they spike.
5. **Keep the sandbox credentials.** You'll want them for the next iteration, for hotfixes, or for reproducing production issues without touching live data.

<Warning>
  Coordinate load testing with [support](https://support.firstresonance.io).
  Sandboxes share infrastructure with other tenants. ION throttles sustained
  high-volume tests, such as 10,000 QPS.
</Warning>

<Note>
  A sandbox is not a staging environment. It's for integration development.
  ION's own staging environment, where new ION features are tested, is strictly
  internal.
</Note>

## Related

* [Authentication](/api-reference/authentication)
* [Getting started](/api-reference/getting-started)
* [Error codes](/api-reference/error-codes)


# Usage limits
Source: https://docs.firstresonance.io/api-reference/usage-limits

How to read the extensions.limits block ION returns when a request crosses a guardrail, so integrations and agentic workflows can adapt before enforcement rejects the request.

## Overview

ION applies fair-use guardrails to the `/graphql` endpoint so one caller's heavy queries can't degrade the API for everyone. To make guardrails **discoverable rather than surprising**, responses that touch a guardrail carry a `limits` block inside GraphQL `extensions`:

```json theme={null}
{
  "data": { "...": "..." },
  "extensions": {
    "limits": {
      "violations": [
        {
          "rule": "max_pagination_first",
          "field": "parts",
          "actual": "N",
          "limit": "N",
          "message": "Requested first: N on 'parts' exceeds the max page size of N."
        }
      ]
    }
  }
}
```

The block contains one field:

* **`violations`**: a list of guardrails your request bumped against. **Only present when non-empty.** A clean request omits the block entirely.

<Note>
  Static caps (page size, depth, aliases, tokens, root fields) carry `actual` and `limit` numbers as shown. Rate-limit entries carry only the rule, `retryAfter` when applicable, and a message. The underlying rate budget is plan-dependent and intentionally not published in responses; follow the guidance in `message` rather than keying off a threshold.
</Note>

## When the block appears

The `limits` block is part of the response `extensions`, alongside anything else ION reports there. Treat it as **optional and additive**: parse it if present, ignore it if absent. Your existing `data` / `errors` handling does not change.

A guardrail surfaces one of two ways, depending on where ION is in rolling a limit out to your org:

| Phase        | What you get                                                         | Request outcome                                                        |
| ------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Advisory** | The condition is reported under `extensions.limits.violations`       | Request still **succeeds**: `data` is returned, no `errors`            |
| **Enforced** | The condition is returned as a GraphQL **error** with a machine code | Request is **rejected**. See [Error Codes](/api-reference/error-codes) |

Advisory is your window to adapt a query **before** it starts getting rejected. Treat any `violations` entry as "fix this and you'll be fine when enforcement turns on."

<Note>
  A successful response with no violations carries no `limits` block at all. If you see `extensions.limits`, there's something to address.
</Note>

## The `violations` array

Each entry is an object identified by its `rule`. Every entry carries a human-readable `message`; the other fields depend on the rule family.

### Structural (query shape)

Static caps on the shape of the query document: page size, nesting depth, aliases, document size, and number of top-level fields.

```json theme={null}
{
  "rule": "max_pagination_first",
  "field": "parts",
  "actual": "N",
  "limit": "N",
  "message": "Requested first: N on 'parts' exceeds the max page size of N."
}
```

| `rule`                                         | Trips on                                         | Fix                                                        |
| ---------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| `max_pagination_first` / `max_pagination_last` | A `first` / `last` page size larger than allowed | Lower the page size and paginate with cursors              |
| `max_depth`                                    | Selection set nested deeper than allowed         | Flatten the query; fetch nested data in follow-up requests |
| `max_aliases`                                  | Too many aliased fields in one document          | Split into multiple requests                               |
| `max_tokens`                                   | Query document too large                         | Break the operation up                                     |
| `max_root_fields`                              | Too many top-level fields in one operation       | Split into multiple operations                             |

`actual` and `limit` are always present on structural entries. `field` is included where a specific field is implicated (for example, pagination or depth) to point you at the offending part of the query.

### Rate limit

A per-tenant token bucket meters sustained throughput. Because it's a throughput signal, this entry carries the retry hint you need to back off:

```json theme={null}
{
  "rule": "rate_limit",
  "retryAfter": "seconds",
  "message": "Rate limit exceeded — retry after Ns."
}
```

| Field        | Meaning                                          |
| ------------ | ------------------------------------------------ |
| `retryAfter` | Seconds to wait before the bucket has room again |

Back off for `retryAfter` seconds, then resume. Spacing requests out helps you stay under the sustained rate.

<Note>
  A `rate_limit` entry **without** `retryAfter` is a permanent block: `{ "rule": "rate_limit", "message": "Access blocked. Contact support if you believe this is in error." }`. Retrying doesn't succeed until an operator lifts the block. Surface the message to the user and contact FirstResonance support, and don't build a retry loop around it.
</Note>

## What enforcement looks like

When a guardrail is enforced rather than advisory, the same condition comes back as a GraphQL error carrying a machine-readable `code`, and the request is rejected. Key off `errors[].extensions.code`, not the message text:

| `code`                      | Corresponds to                                                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QUERY_COMPLEXITY_EXCEEDED` | Any structural violation above                                                                                                                                          |
| `RATE_LIMITED`              | A transient `rate_limit` violation. Also returns **HTTP 429** with a `Retry-After` header                                                                               |
| `BLOCKED`                   | A permanent-block `rate_limit` violation (no `retryAfter`). Returns HTTP 200 with the GraphQL error rather than HTTP 429. Retrying doesn't succeed, so contact support. |

Full payload shapes and remediation live in [Error Codes](/api-reference/error-codes). The field vocabulary matches the advisory `violations` entries, so one parser can handle both paths.

## Recommended client handling

For any integration, and especially unattended or agentic workflows that generate queries dynamically:

1. **Check `extensions.limits.violations` on every response.** No `limits` block means everything is clean; if the block is present, treat each entry as a to-do before enforcement flips on.
2. **On a transient `rate_limit` (or HTTP 429), honor `retryAfter`** with backoff and jitter. Don't hot-loop.
3. **On a `rate_limit` without `retryAfter` (or the `BLOCKED` error code), stop retrying.** This is a permanent block that only lifts when an operator changes the configuration. Surface the message and contact support.
4. **On structural violations, adapt the query.** Use smaller pages, fewer fields, paginate, or split the operation. Retrying the same shape won't help.
5. **Don't hard-code specific limit values.** Structural `actual` and `limit` numbers are stable but plan-dependent; read them from the response so your client stays correct as plans evolve.

## Related

* [Error Codes](/api-reference/error-codes): enforcement payloads (`QUERY_COMPLEXITY_EXCEEDED`, `RATE_LIMITED`, `BLOCKED`) and HTTP status reference.
* [Pagination](/api-reference/guides/pagination): cursor paging to keep page sizes down.
* [Build a Production Integration](/api-reference/guides/build-a-production-integration): retry, backoff, and resilience patterns for unattended clients.


# Custom analytics with the Data Connector
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards

Connecting your BI tools to ION data through the Data Connector, and how to troubleshoot a dashboard that looks wrong.

ION turns your operational data into reports without a separate reporting database. Built-in dashboards cover the highest-frequency questions inside ION.

## Built-in dashboards

ION includes dashboards for build readiness, quality, run execution, inventory, and purchasing. They read the same live data your floor uses, so there's no nightly extract and no sync delay.

Each dashboard scopes to a time window, such as the last 30 days, and to the data your role can access.

## Connect your BI tool

For custom reporting in Power BI, Tableau, Looker, Sigma, or a downstream data warehouse, use the Data Connector, a read-only SQL analytics layer over your ION data.

|                                                                                  |                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector)     | Connect a BI tool or warehouse to ION data through a read-only SQL analytics layer. |
| [Data Products](/automate-with-ion/analytics-and-dashboards/data-products)       | Curated, denormalized datasets that hide model complexity from BI users.            |
| [Available tables](/automate-with-ion/analytics-and-dashboards/available-tables) | The full set of views the Data Connector exposes.                                   |
| [SLAs](/automate-with-ion/analytics-and-dashboards/slas)                         | Replication latency from ION into the Data Connector warehouse.                     |

<Tip>
  Pin down each metric's definition before you build on it. "First-pass yield" can mean several different things; pick one, document the query, and reuse it everywhere.
</Tip>

For one-off questions that no dashboard answers, query the [GraphQL API](/api-reference) directly. See [Common Queries](/api-reference/examples) for copy-paste patterns.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A dashboard shows empty or unexpected data">
    Work through these in order:

    1. **Check the date range.** Dashboards scope to a time window, such as the last 30 days. An event outside the window does not appear, so widen the range to cover the period you're investigating.
    2. **Check the filters.** A filter left in place from an earlier session can hide current data. Clear the filters, confirm the data appears, then reapply only what you need.
    3. **Check your access.** A dashboard shows only the data your role can see. On a limited or test account you may genuinely have no rows, so confirm the role you're signed in with.

    If data is still missing after these checks, and others see the same gap on the same dashboard, gather the details under [When you contact support](#when-you-contact-support) and reach out to [support](https://support.firstresonance.io/).
  </Accordion>

  <Accordion title="Autoplan figures look out of date">
    Figures that depend on Autoplan, such as anticipated demand and clear-to-build, refresh when Autoplan next runs on its configured schedule, not the moment you change an input. A change to a BOM, lead time, or on-hand inventory shows up after the next run.

    When Autoplan output looks wrong, check the inputs first. BOMs, lead times, and on-hand inventory at the relevant locations are the usual cause. Wait one run after correcting an input before re-checking.
  </Accordion>

  <Accordion title="Data Connector data seems stale">
    The Data Connector replicates ION data into its SQL analytics layer asynchronously, so it lags live data slightly. Expected latency is governed by the [SLAs](/automate-with-ion/analytics-and-dashboards/slas). If data is missing well beyond those targets, contact support.
  </Accordion>
</AccordionGroup>

### When you contact support

Include:

* Which dashboard, as a URL or screenshot.
* What you expected versus what you see, with specific numbers.
* The date range and filters in effect.
* When you observed it, and whether it reproduces.
* For Autoplan, the input you changed and when, relative to the next run.
* For the Data Connector, the exact query, its result, and the expected result.

## Related

* [Quality reporting](/track-quality/quality-reporting) for the most common analytics target
* [GraphQL API](/api-reference) for everything dashboards can't do


# Available tables
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/available-tables

The full set of raw, cleaned, and computed tables available through the ION Data Connector.

The [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector) exposes your organization's data as a set of read-only views. These views come in three tiers, listed in full below:

* **Raw**: a near 1:1 replica of each ION entity, with internal system columns removed. This is the "straight data" closest to what you see in the ION app.
* **Cleaned**: the same entities with First Resonance data cleanup and business logic applied (still one row per entity), suffixed `_enriched`.
* **Computed**: curated, performance-optimized [Data Products](/automate-with-ion/analytics-and-dashboards/data-products) with calculations and aggregations maintained by the ION Analytics team.

<Note>
  Table and column names are case-insensitive unless quoted. Names are shown here in lowercase for readability.

  The exact set of **raw** tables available to your organization depends on which ION features you use, so you'll only see views for entities that exist in your schema. The list below is the full ION entity catalog. Customers on GovCloud also have column masking policies applied to certain fields.
</Note>

## Raw tables

A raw view is published for essentially every ION entity in your schema. Internal system tables and change-tracking columns are excluded.

<Note>
  Attribute tables (suffixed `_attributes_base`) store one row per record and attribute `key`. When you join one to its parent record, join on both the record ID and the `key`, otherwise you get a row per attribute and your results fan out.
</Note>

### Parts & inventory

`parts` · `part_attributes_base` · `parts_inventory` · `parts_inventories_attributes_base` · `part_inventory_history` · `part_inventory_build_requirements` · `parts_inventory_rolled_up_costs` · `part_procedures` · `supplier_parts`

### Kits

`parts_kits` · `part_kit_attributes_base` · `part_kit_items` · `part_kit_item_attributes_base` · `part_kit_inventories`

### BOM & builds

`mboms` · `mboms_attributes_base` · `mbom_item` · `mbom_substitute` · `abom_installations` · `build_requirements`

### Runs, procedures & steps

`runs` · `runs_attributes_base` · `run_batches` · `run_steps` · `run_steps_attributes_base` · `run_steps_fields` · `run_steps_dags` · `run_step_part_inventories` · `run_step_sessions` · `procedures` · `procedures_attributes_base` · `steps` · `steps_attributes_base` · `steps_fields`

### Planning & MRP

`plans` · `plans_attributes_base` · `plan_items` · `plan_inputs` · `plan_item_allocations` · `plan_item_results` · `plan_plan_items` · `mrp_jobs`

### Purchasing & receiving

`purchase_orders` · `purchase_orders_attributes_base` · `purchase_order_lines` · `purchase_order_lines_attributes_base` · `purchase_order_line_inventories` · `purchase_order_approval_requests` · `receipts` · `receipts_attributes_base` · `receipt_items` · `suppliers` · `suppliers_attributes_base`

### Quality: issues, further actions, redlines & approvals

`issues` · `issues_attributes_base` · `issue_approval_requests` · `issue_approvals` · `issue_disposition_types` · `issue_part_inventories` · `issue_relations` · `further_actions` · `further_actions_attributes_base` · `further_action_approval_requests` · `further_action_approval_roles` · `further_action_approvals` · `further_action_issues` · `further_action_parts` · `further_action_runs` · `redlines` · `redline_approval_requests` · `review_requests` · `step_approval_requests`

### Locations

`locations` · `locations_attributes_base`

### Organization, users & access

`organizations` · `users` · `user_roles` · `roles` · `teams` · `team_roles` · `team_users`

### Datagrids

`datagrid_columns` · `datagrid_rows` · `datagrid_values`

### Files, labels, comments & entities

`file_attachments` · `entities_file_attachments` · `labels` · `entities_labels` · `comments` · `entities` · `model_tables`

### Barcodes

`barcode_labels` · `barcode_templates`

### Webhooks

`webhook_receivers` · `webhook_subscriptions`

## Cleaned tables

The same entities as above with data cleanup and business logic applied. Each is suffixed `_enriched` and retains entity-level grain (one row per entity).

`barcode_labels_enriched` · `barcode_templates_enriched` · `datagrid_columns_enriched` · `datagrid_rows_enriched` · `datagrid_values_enriched` · `file_attachments_enriched` · `further_actions_attributes_base_enriched` · `issue_approval_requests_enriched` · `issues_attributes_base_enriched` · `issues_enriched` · `locations_attributes_base_enriched` · `locations_enriched` · `mbom_item_enriched` · `mbom_substitute_enriched` · `mboms_attributes_base_enriched` · `mboms_enriched` · `mrp_jobs_enriched` · `organizations_enriched` · `part_attributes_base_enriched` · `part_kit_attributes_base_enriched` · `part_kit_item_attributes_base_enriched` · `part_kit_items_enriched` · `parts_enriched` · `parts_inventories_attributes_base_enriched` · `parts_inventory_enriched` · `parts_kits_enriched` · `plan_items_enriched` · `plans_attributes_base_enriched` · `plans_enriched` · `procedures_attributes_base_enriched` · `procedures_enriched` · `purchase_order_approval_requests_enriched` · `purchase_order_line_inventories_enriched` · `purchase_order_lines_attributes_base_enriched` · `purchase_order_lines_enriched` · `purchase_orders_attributes_base_enriched` · `purchase_orders_enriched` · `receipts_attributes_base_enriched` · `receipts_enriched` · `redline_approval_requests_enriched` · `redlines_enriched` · `review_requests_enriched` · `roles_enriched` · `run_batches_enriched` · `run_steps_attributes_base_enriched` · `run_steps_fields_enriched` · `run_steps_enriched` · `runs_attributes_base_enriched` · `runs_enriched` · `step_approval_requests_enriched` · `steps_attributes_base_enriched` · `steps_fields_enriched` · `steps_enriched` · `suppliers_attributes_base_enriched` · `suppliers_enriched` · `teams_enriched` · `users_enriched` · `webhook_receivers_enriched` · `webhook_subscriptions_enriched`

## Computed tables

The computed tier is a set of curated, pre-joined, and aggregated datasets maintained by the ION Analytics team. For the full list with descriptions and grain, see [Data Products](/automate-with-ion/analytics-and-dashboards/data-products).


# Build readiness aBOM reference
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/build-readiness-abom

Column definitions for the aBOM dashboard and its CSV export in ION Analytics.

The **aBOM** tab in Build Readiness shows the installation status of every part in your as-built BOMs, with cost rollups and issue counts per component. Each row is one required part within one top-level serialized assembly.

To open the dashboard, go to **Analytics > Build Readiness > aBOM**.

## Filters

**Part Number**: narrows all KPIs, charts, and table rows to a single top-level assembly part number. Selecting a part number resets the **Rev** and **Serial** filters.

**Rev**: further narrows to a single revision of the selected assembly. Resets the **Serial** filter.

**Serial**: further narrows to a single serialized instance of the selected assembly.

**Hide root nodes**: when enabled, hides the row where the part is the top-level assembly itself, so the table shows only child components.

## Sub-tabs

The aBOM tab contains two sub-tabs sharing the same filters:

* **aBOM**: the full installation detail table with cost and linkage columns.
* **Issues**: filtered to only rows that have at least one issue, with the same column set.

## KPI cards

| Card            | What it shows                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------- |
| Total Cost      | Sum of `TOTAL_COST` across all rows in the current filter.                                        |
| Total Parts     | Number of distinct top-level assembly instances in the current filter.                            |
| Fully Installed | Number of assembly instances where `IS_FULLY_INSTALLED` is true, and the percentage of the total. |
| Open Issues     | Sum of `OPEN_ISSUE_COUNT` across all rows.                                                        |

The **Issues** sub-tab shows two additional cards: **Open Issues** and **Total Issues** for the filtered set.

## Table columns

| Column           | Export field              | Description                                                                                                                                                     |
| ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Top Level Part   | `TOP_LEVEL_PART_NUMBER`   | The part number of the top-level serialized assembly this row belongs to.                                                                                       |
| Top Level Rev    | `TOP_LEVEL_REVISION`      | The revision of the top-level assembly.                                                                                                                         |
| Top Level SN     | `TOP_LEVEL_SERIAL_NUMBER` | The serial number of the top-level assembly instance.                                                                                                           |
| Top Level Status | `TOP_LEVEL_STATUS`        | The inventory status of the top-level assembly (the same status values used across ION inventory).                                                              |
| Level            | `MIN_LEVEL`               | The BOM level of this component (0 = the top-level assembly itself).                                                                                            |
| Parents          | `PARENTS`                 | The parent assemblies of this component in the aBOM hierarchy. Expand the cell to see each parent's part number, revision, trace, level, and path.              |
| Required Part    | `REQUIRED_PART`           | The part number required at this position in the aBOM.                                                                                                          |
| Required Rev     | `REQUIRED_PART_REVISION`  | The revision of the required part as specified in the aBOM.                                                                                                     |
| Sourcing         | `SOURCING_STRATEGY`       | How the part is sourced: **buy** (purchased) or **make** (manufactured in-house).                                                                               |
| Installed Part   | `INSTALLED_PART`          | The part number of the inventory unit that was actually installed.                                                                                              |
| Installed Rev    | `INSTALLED_PART_REVISION` | The revision of the installed part.                                                                                                                             |
| Installed Trace  | `INSTALLED_PART_TRACE`    | The serial or lot number of the installed inventory unit.                                                                                                       |
| Req Qty          | `TOTAL_REQ_QUANTITY`      | The total quantity required at this BOM position.                                                                                                               |
| Installed Qty    | `INSTALLED_QUANTITY`      | The quantity that has been installed.                                                                                                                           |
| Installed        | `IS_FULLY_INSTALLED`      | Whether the required quantity at this position has been fully installed.                                                                                        |
| BOM Cost         | `PART_COST`               | The cost of this part as defined in the part library.                                                                                                           |
| Unit Cost        | `UNIT_COST`               | The cost recorded on the part inventory line.                                                                                                                   |
| Avg Cost         | `AVG_COST`                | The average cost of this part across purchase orders.                                                                                                           |
| Total Cost       | `TOTAL_COST`              | The total cost for this row, based on the installed quantity and unit cost.                                                                                     |
| Open Issues      | `OPEN_ISSUE_COUNT`        | The number of open issues linked to this component.                                                                                                             |
| Total Issues     | `TOTAL_ISSUE_COUNT`       | The total number of issues linked to this component, including closed ones.                                                                                     |
| Linked Runs      | `LINKED_RUNS`             | Runs associated with this component. Expand the cell to see run ID, status, and due date.                                                                       |
| Linked POs       | `LINKED_POS`              | Purchase order lines associated with this component. Expand the cell to see PO number, position, quantity, cost, line status, PO status, and estimated arrival. |
| Installed At     | `INSTALLED_TIME`          | The timestamp when this component was installed.                                                                                                                |

## Export

The **aBOM** sub-tab and the **Issues** sub-tab each have their own export. Click **Export** in the table toolbar to download the current view as a CSV. Both exports respect all active filters; the Issues export additionally filters to rows with at least one issue.

## Related

* [Build readiness](/automate-with-ion/analytics/build-readiness)
* [Build readiness plans reference](/automate-with-ion/analytics-and-dashboards/build-readiness-plans)
* [Build readiness mBOM reference](/automate-with-ion/analytics-and-dashboards/build-readiness-mbom)


# Build readiness mBOM reference
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/build-readiness-mbom

Column definitions for the mBOM dashboard and its CSV export in ION Analytics.

The **mBOM** tab in Build Readiness shows inventory coverage for each part required by your manufacturing BOMs. Each row is one part in one assembly context. The table and its export use the same column set.

To open the dashboard, go to **Analytics > Build Readiness > mBOM**.

## Filters

**Part Number**: narrows every KPI, chart, and table row to a single top-level assembly. Selecting a part number also resets the **Rev** filter to show only revisions of that assembly.

**Rev**: further narrows to a single revision of the selected assembly.

**Rev Match**: filters rows by whether the available inventory revision matches the BOM revision:

* **All**: show all rows regardless of revision match.
* **Match**: show only rows where the inventory revision matches the BOM revision.
* **Cross-Rev**: show only rows where the inventory revision does not match the BOM revision. Cross-rev inventory cannot be used to fulfill the BOM requirement.

## KPI cards

| Card              | What it shows                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Average Readiness | Average `READINESS_PCT` across all assemblies in the current filter.                                                        |
| Short Parts       | Number of distinct parts with insufficient available inventory to meet their required quantity.                             |
| Shortage Cost     | Total cost value of the shortfall across all short parts.                                                                   |
| Ready to Build    | Number of assemblies at 100% readiness out of the total assemblies in the current filter.                                   |
| Max Builds        | The maximum number of complete assemblies buildable from current available inventory, constrained by the most limited part. |

## Table columns

| Column              | Export field                                  | Description                                                                                                                                                                                                                                                                                                                          |
| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Assembly            | `TOP_LEVEL_PART_NUMBER`, `TOP_LEVEL_REVISION` | The top-level assembly this row rolls up to.                                                                                                                                                                                                                                                                                         |
| Parent Assembly     | `PARENT_ASSEMBLY`                             | The immediate parent assembly of the part in the BOM hierarchy.                                                                                                                                                                                                                                                                      |
| Parent Rev          | `PARENT_REVISION`                             | The revision of the parent assembly.                                                                                                                                                                                                                                                                                                 |
| Parent mBOM Version | `PARENT_MBOM_VERSION`                         | The mBOM version of the parent assembly.                                                                                                                                                                                                                                                                                             |
| Part                | `PART_NUMBER`                                 | The part required at this BOM position.                                                                                                                                                                                                                                                                                              |
| Part Tree           | `PART_TREE`                                   | The full BOM path from the top-level assembly down to this part.                                                                                                                                                                                                                                                                     |
| BOM Rev             | `BOM_REVISION`                                | The revision of the part as specified in the BOM.                                                                                                                                                                                                                                                                                    |
| Inv Rev             | `INVENTORY_REVISION`                          | The revision of the available inventory for this part.                                                                                                                                                                                                                                                                               |
| Rev Match           | `BOM_REVISION_MATCH`                          | Whether the inventory revision matches the BOM revision. A **Cross-Rev** result means the inventory cannot be used to fulfill this requirement.                                                                                                                                                                                      |
| Description         | `DESCRIPTION`                                 | The part description from the part library.                                                                                                                                                                                                                                                                                          |
| Sourcing            | `SOURCING_STRATEGY`                           | How the part is sourced: **buy** (purchased) or **make** (manufactured in-house).                                                                                                                                                                                                                                                    |
| mBOM Qty            | `MBOM_QUANTITY`                               | The quantity of this part specified in the mBOM.                                                                                                                                                                                                                                                                                     |
| Qty Required        | `TOTAL_REQ_QUANTITY`                          | The total quantity required across all demand for this part in the current assembly context.                                                                                                                                                                                                                                         |
| Qty Available       | `QUANTITY_AVAILABLE`                          | Quantity in inventory with status **Available**.                                                                                                                                                                                                                                                                                     |
| Qty On Order        | `QUANTITY_ON_ORDER`                           | Quantity on open purchase orders, not yet received.                                                                                                                                                                                                                                                                                  |
| Shortage            | `SHORTAGE_QTY`                                | The quantity shortfall: `TOTAL_REQ_QUANTITY − QUANTITY_AVAILABLE` when availability is insufficient, otherwise zero.                                                                                                                                                                                                                 |
| Material Cost       | `TOTAL_MATERIAL_COST`                         | Total cost of the required quantity at the part's unit cost.                                                                                                                                                                                                                                                                         |
| Shortage Cost       | `SHORTAGE_COST`                               | Cost value of the shortage quantity.                                                                                                                                                                                                                                                                                                 |
| Readiness           | `READINESS_PCT`                               | The percentage of the assembly's total required quantity covered by available inventory. Calculated as the sum of fulfillable quantities across all parts divided by the total required quantity across all parts. For example, if an assembly requires 7 total units across four parts and 4 units are available, readiness is 57%. |
| Max Builds          | `MAX_BUILDS_FROM_AVAILABLE`                   | `QUANTITY_AVAILABLE / TOTAL_REQ_QUANTITY`. The number of times this part's requirement can be met from available inventory. The assembly-level maximum builds is the minimum of this value across all parts.                                                                                                                         |
| Level               | `LEVEL`                                       | The BOM level of this part (0 = top-level assembly).                                                                                                                                                                                                                                                                                 |
| Short               | `IS_SHORT`                                    | Whether this part has insufficient available inventory to meet its required quantity.                                                                                                                                                                                                                                                |
| Subs                | `HAS_SUBSTITUTES`, `SUBSTITUTE_COUNT`         | Whether approved substitutes exist for this part, and how many.                                                                                                                                                                                                                                                                      |
| Unit Cost           | `UNIT_COST`                                   | The unit cost of the part from the part library.                                                                                                                                                                                                                                                                                     |
| Procedures          | `PROCEDURES`                                  | Procedures linked to this part in the part library. Expand the cell to see procedure name, version, and status.                                                                                                                                                                                                                      |
| Suppliers           | `SUPPLIERS`                                   | Supplier records linked to this part. Expand the cell to see supplier name, supplier part number, and cost.                                                                                                                                                                                                                          |

## Export

Click **Export** in the table toolbar to download the current view as a CSV. The export respects all active filters.

## Related

* [Build readiness](/automate-with-ion/analytics/build-readiness)
* [Build readiness plans reference](/automate-with-ion/analytics-and-dashboards/build-readiness-plans)
* [Build readiness aBOM reference](/automate-with-ion/analytics-and-dashboards/build-readiness-abom)


# Build readiness plans reference
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/build-readiness-plans

Column definitions for the Plans dashboard and its CSV export in ION Analytics.

The **Plans** page in Analytics shows supply coverage for each part across your Autoplan plans. Each row is one part in one plan. The table and its export use the same column set.

To open the dashboard, go to **Analytics > Build Readiness > Plans**.

## Filters

**Plan**: narrows every KPI, chart, and table row to a single plan. Select a plan from the dropdown or leave it set to **All plans** to see the combined view.

## KPI cards

| Card                | What it shows                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Overall Fulfillment | `(QTY_ON_HAND + QTY_COMPLETE) / QTY_TOTAL`, expressed as a percentage, across all rows in the current filter.               |
| Plans               | The number of distinct plans in the current filter.                                                                         |
| On Hand             | Sum of `QTY_ON_HAND` across all rows.                                                                                       |
| WIP                 | Sum of `QTY_WIP` across all rows.                                                                                           |
| On Order            | Sum of `QTY_ON_ORDER` across all rows.                                                                                      |
| Planned             | Sum of `QTY_PLANNED` across all rows. Parts with a non-zero **Planned** value need a purchase order or a run to be created. |

## Table columns

| Column      | Export field                          | Description                                                                                                                             |
| ----------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Plan        | `PLAN_ID`, `PLAN_DESCRIPTION`         | The plan this row belongs to, shown by name.                                                                                            |
| Part        | `PART_NUMBER`, `REVISION`             | The part number and revision required by the plan.                                                                                      |
| Description | `DESCRIPTION`                         | The part description from the part library.                                                                                             |
| Sourcing    | `SOURCING_STRATEGY`                   | How the part is sourced: **buy** (purchased) or **make** (manufactured in-house).                                                       |
| Total Qty   | `QTY_TOTAL`                           | Total quantity requested by kits, plans, and other demand sources for this part. This is the denominator for both percentage columns.   |
| On Hand     | `QTY_ON_HAND`                         | Quantity in inventory with status **Available**.                                                                                        |
| WIP         | `QTY_WIP`                             | Quantity in inventory with status **WIP**.                                                                                              |
| On Order    | `QTY_ON_ORDER`                        | Quantity in inventory with status **On Order**.                                                                                         |
| Planned     | `QTY_PLANNED`                         | Quantity originally planned on runs. This value is static: adjusting a run's quantity does not update it.                               |
|             | `QTY_PLAN_INPUT`                      | Quantity recorded as an Autoplan input for this part.                                                                                   |
|             | `QTY_COMPLETE`                        | Quantity that has been kitted.                                                                                                          |
| Fulfilled   | `PCT_FULFILLED`                       | `(QTY_ON_HAND + QTY_COMPLETE) / QTY_TOTAL`. Represents how much of the total demand is either available in inventory or already kitted. |
|             | `PCT_ON_HAND`                         | `QTY_ON_HAND / QTY_TOTAL`. The share of demand covered by available inventory alone, excluding kitted quantities.                       |
| PO Supplier | `PO_SUPPLIER`, `PO_ESTIMATED_ARRIVAL` | The supplier on the linked purchase order and the estimated arrival date, if a PO exists.                                               |

<Note>
  A blank **Column** field means the field appears in the CSV export but not in the on-screen table.
</Note>

## Export

Click **Export** in the table toolbar to download the current view as a CSV. The export respects the active plan filter, so exporting with a plan selected downloads only that plan's rows.

## Related

* [Build readiness](/automate-with-ion/analytics/build-readiness)


# Data Connector
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/data-connector

Connect ION data to external BI tools and data warehouses via a read-only SQL analytics layer.

The **Data Connector** is a read-only SQL analytics layer that mirrors your operational data, making the same data ION runs on queryable from any BI tool (such as Power BI, Tableau, Looker, or Sigma) or downstream warehouse. You can tie ION data together with ERP, timekeeping, or other systems and run advanced analyses without going through the application UI.

Select **Data Connector** in the ION sidebar to set up and manage your connection. When you complete onboarding, you become an admin, so you can [add users and reset their passwords](/automate-with-ion/analytics-and-dashboards/manage-data-connector-users), [create BI service users](/automate-with-ion/analytics-and-dashboards/get-started-data-connector#connect-a-bi-tool) for tools and scripts, and open the warehouse to run SQL directly, all without filing a support request.

## What's in the replica

The connector exposes three tiers of tables: raw (a near 1:1 replica of each ION entity), cleaned (the same entities with cleanup applied, suffixed `_enriched`), and computed [Data Products](/automate-with-ion/analytics-and-dashboards/data-products) that pre-join and aggregate common views. For the tier definitions and the complete list of tables, see [Available tables](/automate-with-ion/analytics-and-dashboards/available-tables).

For replication latency, see [SLAs](/automate-with-ion/analytics-and-dashboards/slas).


# Data Products
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/data-products

Curated datasets maintained by First Resonance that pre-join and aggregate the most common analytics views.

**Data Products** are views maintained by First Resonance that pre-join and aggregate common queries, so you don't rebuild the same multi-table joins in every dashboard.

Each data product is delivered as a queryable view inside the [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector). Use them as the source for your BI dashboards, such as Power BI, Tableau, Looker, or Sigma, or for downstream pipelines. Refresh latency follows the standard Data Connector [SLAs](/automate-with-ion/analytics-and-dashboards/slas).

<Note>
  Data Products are part of the Data Connector offering. If you don't see them in your warehouse yet, contact your Customer Success Manager about enabling the Data Connector for your organization.
</Note>

Data Products are the **computed** tier of the Data Connector. For the raw and cleaned (`_enriched`) tiers, a near 1:1 replica of every ION entity, see [Available tables](/automate-with-ion/analytics-and-dashboards/available-tables).

## All data products

The complete set of computed views available through the connector. The most commonly used products are documented in detail below.

| Table                            | Description                                                                      |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `autoplan_plan_item_results`     | Autoplan results grouped by plan item (what to make or buy, quantity, due dates) |
| `autoplan_results_by_plan_input` | Autoplan progress and status by plan input                                       |
| `full_bom`                       | Planned and completed work combined for a full production picture                |
| `issue_details`                  | Issues with status plus related redlines and further actions                     |
| `labor_hours`                    | Run-step durations from start and end times, by run, location, and user          |
| `part_kit_item_fulfillment`      | Kit item fulfillment status                                                      |
| `part_quantities_by_inv_status`  | Part quantity by inventory status (Available, WIP, Installed, and others)        |
| `part_substitutes`               | Approved part substitution map                                                   |
| `planned_bom`                    | Recursive planned BOM explosion from MRP and Autoplan demand                     |
| `query_execution_by_workbook`    | Query execution metrics per analytics workbook                                   |
| `recursive_abom`                 | Recursive aBOM explosion                                                         |
| `recursive_mbom`                 | Recursive mBOM explosion                                                         |

## Kitting data products

These data products cover parts, substitutions, inventory, and fulfillment in the kitting process.

### `part_kit_item_fulfillment`

**Unique key:** `(part_kit_id, part_kit_item_id)`

Fulfillment status for each item in a kit. It joins the `part_kit` structure with the individual `part_kit_items` and tracks whether each component has been sourced, picked, staged, or installed. Use it to monitor kit readiness and find staging or fulfillment bottlenecks before work begins.

### `part_substitutes`

**Unique key:** `(part_id, substitute_part_id, mbom_item_id)`

Approved substitute parts for a given `part_id` within the context of a specific `mbom_item_id`. It merges two sources of substitution logic: engineering-driven mBOM alternatives and operations-driven part interchangeability mappings. Planners and operators use it to choose a substitute when the primary part is unavailable or low in inventory.

### `part_quantities_by_inv_status`

**Unique key:** `(part_id)`

Current inventory for each part, grouped by inventory `Status` (Available, Quarantined, Installed, and others). It shows how much of each part is usable versus allocated, blocked, or consumed. Join it with demand metrics to flag low-availability parts.

## BOM data products

### `full_bom`

A flattened, multi-level BOM rollup for fast querying of supply chain and planning data. Dashboards that previously joined the BOM tree at query time, such as Clear to Build, can read directly from `full_bom` for faster load times.

To use Notable Assembly with `full_bom`:

* Define a "Notable Assembly" attribute at the part library level (text or single-select).
* Populate the attribute on the parts you want flagged.
* Configure the attribute name in your Clear-to-Build reporting setup.

## Issue data products

These data products cover manufacturing issue tracking, triage, and resolution. They unify run, step, part, and supplier context with workflow signals such as labels, redlines, related issues, and approvals.

### `issue_details`

**Unique key and grain:**

* Primary grain: one row per issue (`issue_id`).
* When an issue is linked to part inventory or PO line information, the grain expands. In those cases, treat the compound grain as `(issue_id, part_inventory_id, purchase_order_line_id)`.
* If your dashboard expects one row per issue, either filter to the desired part or PO context, or aggregate back to the issue level.

A pre-joined dataset that centralizes the most commonly used fields for issue analysis: assignment, lifecycle timestamps, run and step context, related parts and inventory, supplier and PO traceability, labels, redlines, related issues, approval-based resolution date, further-action rollups, attachments, and freshness signals such as days since last update. Use it for issue queues, SLA tracking, and continuous-improvement dashboards.


# Get started with the Data Connector
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/get-started-data-connector

Connect your BI tool to ION's Snowflake replica and build your first dashboard.

The Data Connector gives you a read-only Snowflake account that mirrors your ION data, so you can query it from Power BI, Tableau, Looker, Sigma, or any other BI tool.

## Set up the Data Connector

Select **Data Connector** in the ION sidebar. The first person from your organization to complete onboarding becomes an admin and can add the rest of the team.

<Note>
  If you don't see the **Data Connector** page, your organization hasn't been onboarded yet. Contact your Customer Success Manager to enable it.
</Note>

The Data Connector page has cards for opening your warehouse (**Go to Data Connector**), managing who has access (**Manage users**), and creating connections for BI tools (**BI service users**).

## Sign in to your account

Your Data Connector account is separate from your ION login. Your ION email and password, or your SSO sign-in, won't work here.

* **Username**: your email address. To confirm the exact username, open **Manage users** on the Data Connector page.
* **Password**: set through the one-time link you receive when your account is created.

To open your warehouse, select **Go to Data Connector**. The Snowflake sign-in opens in a new tab.

<Note>
  Password resets happen on the Data Connector page in ION, not on the warehouse sign-in page. An admin resets it under **Manage users**. For the steps, see [Manage Data Connector users](/automate-with-ion/analytics-and-dashboards/manage-data-connector-users).
</Note>

## Connect a BI tool

BI tools and scripts connect through a **BI service user**, which authenticates with a key pair instead of a password. You generate the key pair yourself and share only the public half, so your private key never leaves your machine.

### Generate a key pair

Run these commands to create a private key (`rsa_key.p8`) and its matching public key (`rsa_key.pub`):

```bash theme={null}
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -nocrypt -out rsa_key.p8
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```

<Warning>
  Keep `rsa_key.p8` private. Your BI tool needs it, and anyone who has it can read your data.
</Warning>

### Create the BI service user

On the Data Connector page, select **BI service users**, then **Add service user**. Enter a **Label** to identify the connection, such as `Tableau Production`, paste the contents of `rsa_key.pub` into **Public key (PEM)**, and select **Create service user**. ION shows the generated **Username**, such as `SVC_TABLEAU_PRODUCTION`. Note it for the next step.

Creating a service user requires admin access. If you're not an admin, ask one to create it for you.

### Configure your BI tool

Open the Snowflake connector in your BI tool and choose key-pair authentication:

* **Username**: the service user's username.
* **Private key**: your `rsa_key.p8` file.
* **Server, warehouse, database, schema, and role**: read them from the **Connection details** card on the **BI service users** page.

The **Connection details** card on that page holds every value a BI tool's connection form asks for, each with a copy control, next to the service user list that supplies the username. **Server** is given as the bare host, with no `https://` prefix, which is what the connection form expects. A value your organization doesn't have is left out of the card.

The exact steps vary by tool:

* [Power BI Snowflake connector](https://learn.microsoft.com/en-us/power-query/connectors/snowflake)
* [Tableau Snowflake connection](https://help.tableau.com/current/pro/desktop/en-us/examples_snowflake.htm)
* [Looker Snowflake dialect](https://cloud.google.com/looker/docs/db-config-snowflake)
* [Sigma Snowflake connection](https://help.sigmacomputing.com/docs/connect-to-snowflake)

To roll a key, select **Rotate key** on the service user and paste a new public key. The old key stops working right away, so update your BI tool with the matching new private key before you rotate.

Once connected, you can browse the available tables directly from your BI tool's data pane.

## Build your first dashboard

The fastest way to build a useful dashboard is to start with a [Data Product](/automate-with-ion/analytics-and-dashboards/data-products) rather than the raw tables. Data Products are pre-joined, pre-aggregated views maintained by First Resonance.

A good starting point for most teams:

1. In your BI tool, open the Snowflake connection and browse to the schema.
2. Find the **computed** tier, which holds the Data Products.
3. Drag in the Data Product that matches your question. For a quality dashboard, start with `issue_details`. For a production overview, start with `full_bom`. For part availability, start with `part_quantities_by_inv_status`.
4. Add filters for date range, team, or part as needed.
5. Build your chart or table from the columns available.

<Note>
  The Data Connector is read-only. Build measures and calculated fields in your BI tool. You can't create tables or write data in the warehouse.
</Note>

For the full list of Data Products and what each one contains, see [Data Products](/automate-with-ion/analytics-and-dashboards/data-products).

If no Data Product fits your question, you can query the raw or cleaned (`_enriched`) tables directly. See [Available tables](/automate-with-ion/analytics-and-dashboards/available-tables) for the full catalog.

## Related

* [Manage Data Connector users](/automate-with-ion/analytics-and-dashboards/manage-data-connector-users)
* [Data Products](/automate-with-ion/analytics-and-dashboards/data-products)
* [Available tables](/automate-with-ion/analytics-and-dashboards/available-tables)
* [SLAs](/automate-with-ion/analytics-and-dashboards/slas)
* [Troubleshooting](/automate-with-ion/analytics-and-dashboards#troubleshooting)


# Manage Data Connector users
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/manage-data-connector-users

Add Data Connector users, reset their passwords, and control admin access from the Data Connector page.

Control who can query the Data Connector from the **Manage users** page. Select **Data Connector** in the ION sidebar, then **Manage users**. Managing users requires admin access, which you get by completing onboarding.

## Add a user

1. On the **Manage users** page, select **Add user**.
2. Select the person from the list. Only active ION users in your organization are eligible. If someone is missing, [invite them to ION](/administration/users-and-permissions/invite-a-user) first.
3. Optional: select **Grant Data Connector admin (CUSTOMER\_ADMIN)** to let them manage users too.
4. Select **Create user**.

ION generates a one-time password link for the new user. The link is emailed to them, or shown to you once to share if email delivery isn't available. It expires in 4 hours. If it lapses, reset the password to generate a new one.

<Note>
  The password email comes from `support@firstresonance.io`. IT teams: allowlist this address so account and reset emails are delivered.
</Note>

## Reset a password

Data Connector passwords are reset from ION, not from the warehouse sign-in page. On the **Manage users** page, select **Reset password** next to the user. ION generates a fresh one-time link and re-sends it. The user follows the link to set a new password.

## Grant or revoke admin

An admin can manage users and create BI service users. To change someone's access, select **Make admin** or **Revoke admin** next to the user. Admins show the **Admin** badge in the user list.

## Deactivate or reactivate a user

To remove someone's access, select **Deactivate** next to the user and confirm. They lose access to the Data Connector right away. Select **Reactivate** to restore it.

## Related

* [Get started with the Data Connector](/automate-with-ion/analytics-and-dashboards/get-started-data-connector)
* [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector)


# SLAs
Source: https://docs.firstresonance.io/automate-with-ion/analytics-and-dashboards/slas

Replication latency targets between ION and the Data Connector's read-only warehouse.

The [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector) replicates your ION data into a read-only SQL analytics layer for custom reports and dashboards. The replica is tiered:

1. **Base tables** generated from the raw replicated data.
2. **Enriched tables and [Data Products](/automate-with-ion/analytics-and-dashboards/data-products)**: transformations layered on top of the base tables to provide aggregated and pre-joined views.

Because replication runs asynchronously, there's a small delay between when a change is made in ION and when it appears in the warehouse. First Resonance commits to the following SLAs:

| Tier                                                                 | P99 latency           |
| -------------------------------------------------------------------- | --------------------- |
| Base table delay (raw replicated data)                               | within **5 minutes**  |
| Enriched table / data product delay (transformations applied on top) | within **30 minutes** |

## Data integrity

Distributed systems carry a non-zero probability of dropping an update during replication. We run integrity checks that detect missed updates and refresh the affected state automatically.


# Build readiness
Source: https://docs.firstresonance.io/automate-with-ion/analytics/build-readiness

mBOM readiness and shortages, as-built installation progress, and plan fulfillment across supply statuses.

In ION, go to **Analytics > Build Readiness**. The surface has three sub-tabs: **mBOM**, **aBOM**, and **Plans**. Use it to answer: can I build this assembly today, what is short and what does the shortage cost, how far along is each as-built unit, and how fulfilled is each plan.

Each detail table has an **Export** control that exports the table, with its current filters applied, to CSV.

## mBOM

The default sub-tab measures whether stock covers each assembly's mBOM. Filter by top-level **Part Number**, **Rev**, and **Rev Match** (All, Match, or Cross-Rev) to control whether inventory at a different revision counts toward readiness.

* KPI cards: **Average Readiness**, **Short Parts**, **Shortage Cost**, **Ready to Build** (assemblies at 100% readiness), and **Max Builds**.
* **Part Fulfillment**: components bucketed as No Stock, Short, or Fulfilled.
* **Top Shortage Parts**: the parts with the highest shortage quantities.
* **mBOM Readiness Detail**: a table grouped by assembly tree, with columns including **Part**, **BOM Rev**, **Inv Rev**, **Rev Match**, **Qty Required**, **Qty Available**, **Qty On Order**, **Shortage**, **Shortage Cost**, **Readiness**, and **Max Builds**, plus expandable **Procedures** and **Suppliers** details per part.

## aBOM

Tracks installation progress and cost on as-built assemblies. Filter by **Part Number**, **Rev**, and **Serial**, and toggle **Hide root nodes** to drop top-level rows from the tree.

* KPI cards: **Total Cost**, **Total Parts**, **Fully Installed**, and **Open Issues**.
* **Installation Status**: installed versus not installed parts.
* **Parts by Level**: part counts across BOM levels.
* **aBOM Detail**: a table grouped by assembly tree, with columns including **Required Part**, **Installed Part**, **Req Qty**, **Installed Qty**, **Installed**, **Unit Cost**, **Total Cost**, **Open Issues**, and expandable **Linked Runs** and **Linked POs** details.

An **Issues** view within this sub-tab lists only the parts that carry issues, so you can see quality blockers on the build without leaving the tree.

## Plans

Measures fulfillment per plan. Pick a plan from the **Plan** selector or view all plans at once.

* KPI cards: **Overall Fulfillment**, **Plans**, **On Hand**, **WIP**, **On Order**, and **Planned** (quantity that still needs a PO or run).
* **Overall Status Distribution**: quantities by supply status.
* **Status by Plan**: the fulfillment breakdown per plan as stacked percentages.
* **Build Status Detail**: a table with columns including **Plan**, **Part**, **Sourcing**, **Total Qty**, **On Hand**, **WIP**, **On Order**, **Planned**, **Fulfilled**, and **PO Supplier**.

## Related

* [Build readiness mBOM reference](/automate-with-ion/analytics-and-dashboards/build-readiness-mbom)
* [Build readiness aBOM reference](/automate-with-ion/analytics-and-dashboards/build-readiness-abom)
* [Build readiness plans reference](/automate-with-ion/analytics-and-dashboards/build-readiness-plans)


# Overview
Source: https://docs.firstresonance.io/automate-with-ion/analytics/index

ION's built-in Analytics area: five dashboard surfaces covering inventory, build readiness, purchasing, quality, and run execution.

Analytics is ION's built-in dashboard area. It answers the highest-frequency operational questions, such as what stock is available, which assemblies are ready to build, which purchase order lines are past due, how old open issues are, and which runs are overdue, without leaving ION or setting up a BI tool. It differs from the [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector), which is a read-only SQL layer for building your own reports in an external BI tool; Analytics is the reporting ION ships with.

You open it from **Analytics** in the left navigation. The page is organized into five tabs, one per surface:

| Tab                                                                          | What it covers                                                                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [**Inventory**](/automate-with-ion/analytics/inventory-analytics)            | Stock on hand by status and location, transaction history, and expiring inventory.         |
| [**Build Readiness**](/automate-with-ion/analytics/build-readiness)          | mBOM readiness and shortages, as-built (aBOM) installation progress, and plan fulfillment. |
| [**Purchase Orders**](/automate-with-ion/analytics/purchase-order-analytics) | Open PO lines, past-due aging, supplier on-time performance, and receipts.                 |
| [**Quality**](/automate-with-ion/analytics/quality-analytics)                | Open issues, resolution time, age distribution, and dispositions.                          |
| [**Run Execution**](/automate-with-ion/analytics/run-execution-analytics)    | Active and overdue runs, completion progress, and labor.                                   |

Every surface follows the same layout: a row of KPI cards at the top, charts in the middle, and a detail table at the bottom. Detail tables load more rows as you scroll, show the total row count in the footer, and include an **Export** button that saves the underlying data as a file.

Two controls in the page header work across all tabs: a search box that matches a dashboard by name and jumps to it, and **Refresh**, which re-queries every widget on the current tab. Dashboards show only the data your role can access.


# Inventory analytics
Source: https://docs.firstresonance.io/automate-with-ion/analytics/inventory-analytics

Stock on hand by status and location, inventory transaction history, and expiring or expired inventory.

In ION, go to **Analytics > Inventory**. The surface has three sub-tabs: **Inventory**, **Transaction History**, and **Expiring Inventory**. Use it to answer: how much stock is available, where is it, what moved and who moved it, and what expires soon.

Each detail table has an **Export** control that exports the table, with its current filters applied, to CSV.

## Inventory

The default sub-tab shows overall stock health:

* KPI cards: **Available Inventory**, **WIP**, **Total Kitted**, and **Expiring / Expired**.
* **Inventory by Status**: distribution of inventory lines across statuses such as available, wip, and kitted.
* **Top Locations**: the ten locations holding the most inventory lines.
* **Inventory Detail**: a table grouped by part, with cascading filters for part number, revision, trace, location, and status. Key columns include **Part Number**, **Revision**, **Serial**, **Lot Number**, **Location**, **Status**, **Qty Total**, **Qty Available**, and **Qty Kitted**.

## Transaction History

A ledger of every inventory movement. Filter by inventory ID, **From Location**, **To Location**, and a date range. Columns include **Timestamp**, **Part Number**, **Trace**, **Action**, **Quantity**, **From Status**, **To Status**, **From Location**, **To Location**, and **User**, so you can trace what changed, where it went, and who did it.

## Expiring Inventory

A table of inventory with expiration dates, showing **Part Number**, **Serial**, **Lot**, **Qty Available**, **Expiration Date**, **Status** (Expired or Good), and **Location**. Use it to pull expiring stock before it reaches the floor.


# Purchase order analytics
Source: https://docs.firstresonance.io/automate-with-ion/analytics/purchase-order-analytics

Open PO lines, past-due aging, supplier on-time performance, and receipt volume over time.

In ION, go to **Analytics > Purchase Orders**. The surface has two sub-tabs: **PO Lines** and **Receipts**. Use it to answer: what is on order, what is late, which suppliers deliver on time, and what arrived recently.

Each detail table has an **Export** control that exports the table, with its current filters applied, to CSV.

## PO Lines

The default sub-tab tracks the open order book:

* KPI cards: **Open PO Lines**, **Past Due**, **Open Outstanding Value**, and **Avg Days Since Receipt**.
* **PO Line Status**: distribution of lines by status.
* **Past Due Aging**: late lines bucketed by days past due.
* **Supplier On-Time %**: on-time delivery rate for the ten suppliers with the most lines.
* **Purchase Order Lines**: a detail table with columns including **ION PO #**, **Line #**, **Part**, **Supplier**, **Status**, **Qty Ordered**, **Qty Received**, **% Received**, **Need Date**, **Need Date Age** (Past Due, Due in 2wk, Due in 1mo, 1mo+, or No Need Date), and **Est. Cost**.

## Receipts

The receiving side of the pipeline, scoped to recent activity:

* KPI cards: **Receipts (30d)**, **Quantity Received (30d)**, **Avg Lead Time (30d)** (PO creation to receipt, purchase receipts only), and **Non-Purchase (30d)** for receipts not tied to a purchase order.
* **Receipts by Week**: receipt counts over the last 12 weeks, stacked by Purchase versus Non-Purchase.
* **Receipts**: a detail table with columns including **Receipt Date**, **Type**, **ION PO #**, **Supplier**, **Part Number**, **Qty Received**, and **Received By**.


# Quality analytics
Source: https://docs.firstresonance.io/automate-with-ion/analytics/quality-analytics

Open issue counts, resolution time, age distribution, and disposition breakdown across quality issues.

In ION, go to **Analytics > Quality**. Use it to answer: how many issues are open, how long do they take to resolve, which ones are aging, and how they are being dispositioned.

The dashboard shows:

* KPI cards: **Open Issues**, **Avg Days to Resolve**, **Active Redlines** (issues with active redlines), and **Open Further Actions** (issues with open corrective actions).
* **Issues by Status**: distribution of issues across lifecycle states.
* **Age Distribution**: issues bucketed by how long they have been open.
* **Disposition Types**: issue counts per disposition.
* **Quality Issues**: a detail table with columns including **Title**, **Status**, **Disposition**, **Assigned To**, **Days Open** (highlighted past 14 and 30 days), **Age Bucket**, **Redlines**, **Actions**, and **Location**.

The **Quality Issues** table has an **Export** control that exports the table, with its current filters applied, to CSV.

For the underlying issue lifecycle, dispositions, and approvals, see [Issues](/track-quality/issues).


# Run execution analytics
Source: https://docs.firstresonance.io/automate-with-ion/analytics/run-execution-analytics

Active and overdue runs, completion progress, step counts, and labor hours per run.

In ION, go to **Analytics > Run Execution**. Use it to answer: how many runs are active, which are overdue, how far along each run is, and how much labor runs consume.

The dashboard shows:

* KPI cards: **Active Runs**, **Avg Completion**, **Overdue Runs** (past due date and still open), and **Avg Labor** in hours per run.
* **Runs by Status**: run counts per status.
* **Completion Distribution**: runs bucketed by completion percentage, from 0% to 100%.
* **Run Execution Detail**: a table with columns including **Run ID**, **Procedure**, **Part Number**, **Serial**, **Status**, **Progress** (a completion bar per run), **Steps** (completed out of total), **Failed** (failed step count), **Labor (hrs)**, **Assigned To**, and **Due Date**.

The **Run Execution Detail** table has an **Export** control that exports the table, with its current filters applied, to CSV.

For how runs and steps work on the floor, see [Runs and execution](/build-hardware/runs-and-execution).


# Integrations
Source: https://docs.firstresonance.io/automate-with-ion/integrations

Third-party integrations and ION automations, prebuilt or build your own.

An integration is a script that runs when something happens in ION. An ION event triggers it, usually through a [webhook](/api-reference/guides/webhooks) and sometimes on a schedule. From there it can do almost anything: read and write ION data through the [GraphQL API](/api-reference), call an external system, send a notification, or generate a document.

First Resonance builds and ships prebuilt integrations through the [ION Marketplace](https://marketplace.firstresonance.io/), and you can also build your own.

Integrations take many shapes. Two common ones:

* A **third-party integration** syncs data between ION and another system, such as pulling part releases from your PLM or pushing purchase orders to your ERP.
* An **ION automation** runs logic against ION itself, such as querying and mutating data through the GraphQL API when an event fires.

## Getting started

* **Deploy a prebuilt integration or automation**: browse the [ION Marketplace](https://marketplace.firstresonance.io/) and the catalogs below, then follow [Deploy an integration or automation](/automate-with-ion/integrations/deploying-integrations-and-automations).
* **Build your own**: if nothing prebuilt fits, use the Workflow Builder, webhooks, or the GraphQL API. See [Create an integration](/automate-with-ion/integrations/create-an-integration).
* **Design the data flow across systems**: see the [ERP and PLM reference architecture](/automate-with-ion/integrations/erp-plm-reference-architecture).
* **Generate PDFs from ION objects** such as purchase orders and run packets: see [Export data as PDF](/automate-with-ion/integrations/export-data-as-pdf).

<Note>
  Partner integrations evolve quickly. Your Manufacturing Success Engineer has the current state of every connector and what's in the pipeline.
</Note>

## Third-party integrations

Connectors First Resonance and its partners maintain for the systems you already run. Most use standard protocols ([AMQP](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol) for messaging, [GraphQL](/api-reference) for direct queries, and webhooks), so you don't wire each one from scratch.

### PLM and PDM

<CardGroup>
  <Card title="Arena" href="/automate-with-ion/integrations/arena">
    Pull part and BOM releases from Arena PLM into ION.
  </Card>

  <Card title="Duro" href="/automate-with-ion/integrations/duro">
    Sync the Duro catalog with ION parts and BOMs.
  </Card>

  <Card title="Teamcenter" href="/automate-with-ion/integrations/teamcenter">
    Siemens Teamcenter PLM integration.
  </Card>

  <Card title="Solidworks" href="/automate-with-ion/integrations/solidworks">
    Direct CAD release into ION.
  </Card>
</CardGroup>

### ERP and finance

<CardGroup>
  <Card title="NetSuite" href="/automate-with-ion/integrations/netsuite">
    Inventory, purchase order, and receipt sync with NetSuite ERP.
  </Card>

  <Card title="QuickBooks" href="/automate-with-ion/integrations/quickbooks">
    Sync purchase order details to QuickBooks Online.
  </Card>
</CardGroup>

### Procurement and sourcing

<CardGroup>
  <Card title="Procurable" href="/automate-with-ion/integrations/procurable">
    Strategic sourcing and supplier management.
  </Card>

  <Card title="Datum" href="/automate-with-ion/integrations/datum">
    Supplier data and component intelligence.
  </Card>
</CardGroup>

### Collaboration and productivity

<CardGroup>
  <Card title="Slack" href="/automate-with-ion/integrations/slack">
    Notifications and slash-command lookups.
  </Card>

  <Card title="Smartsheet" href="/automate-with-ion/integrations/smartsheet">
    Two-way sync with Smartsheet plans.
  </Card>
</CardGroup>

## ION automations

Prebuilt automations First Resonance maintains that run logic against ION itself, such as querying and mutating data through the GraphQL API when an event fires. See [ION automations](/automate-with-ion/integrations/automations) for the current list and how they differ from ION Actions.

## Related

* [API reference](/api-reference)
* [Webhooks](/api-reference/guides/webhooks)
* [Manage actions](/automate-with-ion/ion-actions/manage-actions)


# Arena
Source: https://docs.firstresonance.io/automate-with-ion/integrations/arena

Arena PLM Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/arena.md`.
</Note>

Establish Arena as the source of truth for product/component metadata, and bill of materials (BOM), while ION parts remain up to date with changes made in Arena with no manual intervention. This integration eliminates the extra effort it typically takes to manually import part details and BOM information into ION, which will help you create procedures and get to building faster.

<Note>
  Skip to the [Integration set up](#integration-set-up) section for instructions on how to deploy or reconfigure this integration.
</Note>

[https://www.loom.com/share/1fe6a3a269714e1b865f2bacd52aa6a7?sid=ebe1402f-843c-49a4-8b3b-109e23a9daf6](https://www.loom.com/share/1fe6a3a269714e1b865f2bacd52aa6a7?sid=ebe1402f-843c-49a4-8b3b-109e23a9daf6)

## Arena Change Order Submission

Upon submitting a change within Arena, an event will be created to be processed by the integration. On the interval you set, the integration uploads the parts and associated attributes into ION. If applicable, for each top-level part the integration automatically generates a new draft mBOM version for that part, adds all of the components, and then releases that mBOM version in ION.

## Integration Set up&#x20;

1. Navigate to the **Integrations** page designated by the two arrows in the bottom left corner of your screen.

   <figure><img alt="" /><figcaption><p>Select Integrations in the Bottom Left Hand Corner</p></figcaption></figure>
2. Select the Arena integration instance from the marketplace, and hit **Configure.**&#x20;
3. Hit **Next** and add your API credentials. You can find documentation on [API keys](/api-reference/authentication/api-keys) here.
   * **IMPORTANT:** Each API Key is associated with a specific environment, be sure to generate the API keys from the correct environment and configure the automation to the designated environment.<br />

     <figure><img alt="" /><figcaption><p>Set your Environment According to Where the API Keys were Generated</p></figcaption></figure>
4. Configure the Arena PLM Connection using your Arena login credentials as seen below:

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
5. A note on revision schemes: If you have parts in arena with complex revisions (AA1, A1-N, etc...) you MUST ensure that a revision scheme matching that revision is present in your ION environment. For example, revision A01 has the format seen below. We named ours as shown but you can name yours whatever you like. All that matters is that the format matches the revision. The integration will break if it cannot find a revision scheme that matches the revision attempting to be pushed.'

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
6. You have the option to drive the Sourcing Strategy in ION in two different ways.&#x20;
   1. The first is via a simple single-select custom attribute in Arena, as shown below. Make sure this attribute is added to the part category in Arena.

      <figure>
        <img alt="" />

        <figcaption />
      </figure>

      To configure your integration to utilize this attribute, toggle the below configuration on and add this information to the Native attributes.

      <figure>
        <img alt="" />

        <figcaption />
      </figure>

      <figure>
        <img alt="" />

        <figcaption />
      </figure>
   2. Alternatively, you can use the sourcing relationships shown in [Sourcing information](#sourcing-information).

<Warning>
  Do not include tracking type information in the above native attributes data map. That is covered more in [Traceability attribute](#traceability-attribute).
</Warning>

1. To finish the configuration, you can map the data between the two platforms by adding key-value pairs for ION native attributes and custom attributes. The keys are ION fields and the values are Arena fields. Here is an example of what your custom attributes could look like.&#x20;

<figure>
  <img alt="" />

  <figcaption />
</figure>

### Arena Specific Setup:

#### Sourcing Information:

When setting up your items in Arena you will have the option to set up sourcing relationships under the "Sourcing" tab. In the picture below I set up a sourcing relationship and a corresponding vendor part number. If you set this up, ION will be able to mark the part as MAKE/BUY/DUAL\_SOURCE, will set the supplier part number, and will be able to pull over vendor into a custom attribute if you so wish.&#x20;

<figure>
  <img alt="" />

  <figcaption />
</figure>

#### Thumbnails:

You can bring over one image from Arena to set as the thumbnail for your ION part. In the files section of your item, you can add one file of the Image/Picture type. Here is an example:

<figure>
  <img alt="" />

  <figcaption />
</figure>

<figure>
  <img alt="" />

  <figcaption />
</figure>

#### Traceability Attribute:

To get the traceability information (LOT/SERIAL/NONE) to come over you will need to set up a custom attribute on the Arena side as shown in your workspace settings:

<figure>
  <img alt="" />

  <figcaption />
</figure>

<figure><img alt="" /><figcaption><p>Populate the the attribute name in this section of the Integration setup</p></figcaption></figure>

#### Non-planned items:

It is common in manufacturing to design assemblies that will be sourced completely from a supplier. The supplier will source all of the sub-components of that assembly and deliver a completed assembly to your door. A common example of this type of sourcing is PCBAs. In these cases, it is common to only migrate the top-level assembly to ION instead of all the subcomponents (board-level components: capacitors, transistors, etc...). If migrated, the subcomponents can add unnecessary demand to ION's Autoplan MRP engine and cause as-built records for the assemblies to show incomplete. For these reasons, we built an additional (optional) feature in the integration that will only migrate the top-level assembly if it is marked on the item level in Arena. Here is the logic and setup:

Below is a screenshot of an item-level attribute called "planned-item" (although you can call it anything you want). The mandatory part of this setup is the list values section. Make sure to have only two options "TRUE" & "FALSE" (case sensitive). If the attribute is set to FALSE on the item record then the integration will not migrate the BOM for that item.

<figure>
  <img alt="" />

  <figcaption />
</figure>

#### Integration Configuration:

To configure the integration's arena side, you need to create a trigger and an integration. To do this, you must have **admin privileges**&#x20;

#### Creating the trigger

<figure><img alt="" /><figcaption><p><strong>Navigate to workspace settings</strong></p></figcaption></figure>

<figure><img alt="" /><figcaption><p><strong>Under the integrations tab, click the plus sign next to "Triggers" to add a new trigger</strong></p></figcaption></figure>

Press create new trigger and then add the following attributes:

<figure>
  <img alt="" />

  <figcaption />
</figure>

#### Creating the integration:

You will need to create the integration via Arena, using the instructions documented [here](https://www.arenasolutions.com/solutions/marketplace/arena-ion-integration/).&#x20;

We recommend you acquire a machine integration user (cost \~\$3k) and set up the integration with those user credentials. Talk to your Arena rep or use the "Contact Support" button above to acquire a machine account.

### Finalizing the integration setup:

After configuring the integration in Arena, you will need to get the integration GUID and paste that into the integration configuration in ION. Here is how you locate the integration GUID in Arena:

1. once you log in, you should see the integration in your main dashboard view

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
2. Click the view (or reconcile) button on the right-hand side of the integration.
3. Once there, you should see this screen. The integration GUID is the capitalized string of characters after the colon.

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
4. With that string in hand, you can navigate back over to the integration config in ION and enter that in the box at the bottom that says "integration GUID"

### Configuration Help:

If you would like assistance setting up this integration or any other integration please reach out through Chat.


# ION automations
Source: https://docs.firstresonance.io/automate-with-ion/integrations/automations

The prebuilt ION automations available in the Marketplace, and what each one does.

An ION automation is a prebuilt integration that First Resonance maintains and runs logic against ION when an event fires. It can write back to ION, send notifications, generate documents, or call an external system. Deploy one from the Marketplace; see [Deploy an integration or automation](/automate-with-ion/integrations/deploying-integrations-and-automations).

You can browse this same list in ION itself: in the sidebar, select **Integrations**.

<Note>
  Both ION automations and [ION Actions](/automate-with-ion/ion-actions) run custom logic on an ION event, but they work differently. An ION Action runs inside ION while a change is being saved, so it can allow, block, or warn on that change. An ION automation runs on the integration platform and reacts to an event that has already happened, so it can't allow, block, or warn on a change. Instead it takes action, such as firing mutations, sending notifications, or calling external systems.
</Note>

| Automation                                                      | Description                                                                                                                |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Auto-approve part-procedure relationships                       | Approves a part-procedure link automatically and fills in its optional or required field.                                  |
| Auto-assign issue on creation                                   | Assigns a new issue to the part's responsible engineer, the run's creator, or a configured team, in order.                 |
| Auto-assign PO to the creator of the PO                         | Assigns the purchase order's creator as its assignee when the PO is created.                                               |
| Auto-checkout on inactivity                                     | Checks a user out of their run session after a period of inactivity.                                                       |
| Auto-consumption of line-side inventory                         | Deducts line-side inventory against the run's mBOM when a configured run step completes.                                   |
| Auto-create linear step dependencies                            | Adds a dependency from a newly inserted step to the steps immediately before and after it.                                 |
| Auto-kit expired material                                       | Kits inventory nearing its expiration date on a schedule and assigns the kit to a team.                                    |
| Auto-populate quality clauses based on purchase order tier      | Sets a PO's quality clauses from a configured tier attribute value.                                                        |
| Auto-send purchase emails to suppliers                          | Emails a purchase order PDF to its supplier when triggered from ION.                                                       |
| Auto-update mBOM revision on part revision update               | Bumps the mBOM revision, and any draft mBOMs, when a part is revised.                                                      |
| Auto-update part library cost based on purchase order line cost | Updates a part's library unit cost from its PO line cost once the order is placed.                                         |
| Autogenerate child issue for remove and replace dispositions    | Creates a linked child issue for the removed part when an issue's disposition needs one.                                   |
| Autoplan scheduler                                              | Runs Autoplan on a configured schedule instead of only on demand.                                                          |
| Complete informational steps                                    | Autocompletes an informational step, and its parent, once you've completed it once before.                                 |
| Data imprint                                                    | Copies a value between related ION records, such as part pedigree onto inventory.                                          |
| Data imprint from run step field to part inventory attribute    | Copies a run step field's value onto the run's part inventory attribute.                                                   |
| Imprint vendor name to part inventory                           | Copies the supplier name, or your org name for made parts, onto new part inventory.                                        |
| Intent data imprint                                             | Copies intent-level data from runs and purchase orders onto part inventory, and applies upgrade or downgrade dispositions. |
| ION Actions to control PO approval workflow                     | Deploys ION Action rules that enforce PO approval requirements, such as reviewer changes and cost-threshold approvals.     |
| Maintain only one procedure version                             | Archives a procedure's older versions when a new version is approved.                                                      |
| Map inspection procedures by intent level                       | Creates an inspection procedure for a received part based on its PO line's intent level.                                   |
| Map inspection procedures by quality clauses                    | Creates an inspection run for a received part based on the quality clauses on its PO line.                                 |
| Migrate PO attribute data                                       | Moves a value from one PO attribute to another, converting a number to text.                                               |
| Notify purchase order assignee of PO approval                   | Notifies the PO assignee, or its creator if none is set, when an approval is approved or rejected.                         |
| Part inventory intent management                                | Blocks installing lower-intent inventory into a higher-intent part or kit.                                                 |
| PO header to PO line attribute propagation                      | Copies purchase order attributes onto its lines, including mapped Need By and ETA dates.                                   |
| PO status control                                               | Deploys ION Action rules that block a PO from skipping approval or entering review before every line has a cost.           |
| Prevent run closure if aBOM is not completed                    | Blocks a run's last step from completing or canceling until the aBOM is fully filled out.                                  |
| Purchase order PDF and versions                                 | Versions a purchase order and generates a PDF as it changes through approval.                                              |
| Receiving data input requirements                               | Requires a receiving location, blocks over-receipt, or requires a serial or lot number, per your configuration.            |
| Recreate run on failure                                         | Creates a replacement run when another run fails, so you can schedule the rework.                                          |
| Replace team assignee with specific role                        | Reassigns an issue from a team to a specific role on that team, such as the on-call person.                                |
| Require part inventory details on run creation                  | Blocks run creation without a part inventory item, or without a lot or serial number, per your configuration.              |
| Run scheduler                                                   | Duplicates a run on a fixed schedule for work that repeats predictably.                                                    |
| Scrap inventory on scrap disposition                            | Sets an issue's inventory to Scrapped when the issue resolves with a scrap disposition.                                    |
| Set close-by on issue creation                                  | Sets the run step an issue must resolve by, so the run can't close while it's open.                                        |
| Set kitting status to draft                                     | Sets a kit created from a run to Draft instead of Requested, so you can finish it before requesting.                       |
| Update tool date of last maintenance                            | Sets a tool's last-maintained date when its maintenance run completes.                                                     |
| Upload PO PDF to PO                                             | Generates a PDF and attaches it to the purchase order once it's ordered.                                                   |

## Related

* [Deploy an integration or automation](/automate-with-ion/integrations/deploying-integrations-and-automations)
* [ION Actions](/automate-with-ion/ion-actions)


# Create an integration
Source: https://docs.firstresonance.io/automate-with-ion/integrations/create-an-integration

Build your own integration when no prebuilt connector fits, using the Workflow Builder, webhooks, or the GraphQL API.

When no [prebuilt connector or automation](/automate-with-ion/integrations) fits, you can build your own. Three patterns work well, from least to most code.

## Workflow Builder

Build an integration visually in ION, without code. Use it to connect a system that isn't on the prebuilt list, or to assemble a custom automation from triggers and actions. See [Workflow Builder overview](/automate-with-ion/workflow-builder) for what you can build, or go straight to [Create a flow](/automate-with-ion/workflow-builder/create-a-flow) to wire up a flow's trigger and connection.

The Workflow Builder is available to selected organizations. Contact [support.firstresonance.io](https://support.firstresonance.io) to enable it.

## Webhooks

Push ION events to your own system as they happen. Subscribe to the resources and actions you care about, and ION delivers an event to your endpoint when they occur. Use this when your system reacts to changes in ION. See [Webhooks](/api-reference/guides/webhooks).

## GraphQL API

Read from or write to ION directly. The same GraphQL surface that powers the ION interface is available to you, so anything the app can do, your integration can do. Use this for two-way sync, bulk operations, or anything the Workflow Builder and webhooks don't cover. New to the API? Start with [Getting started](/api-reference/getting-started). To take an API integration from your first call to production, see [Build a production integration](/api-reference/guides/build-a-production-integration). For the full surface, see [the API reference](/api-reference).

<Tip>
  Connect the highest-leverage system first, usually your ERP, since inventory and purchase order data drive the most downstream value. Pick one source of truth per concept (parts in PLM, inventory in ION, the general ledger in ERP) and sync one way from there rather than bidirectionally syncing every field.
</Tip>

## Related

* [Deploy an integration or automation](/automate-with-ion/integrations/deploying-integrations-and-automations)
* [ERP and PLM reference architecture](/automate-with-ion/integrations/erp-plm-reference-architecture)
* [Webhooks](/api-reference/guides/webhooks)
* [API reference](/api-reference)


# Datum
Source: https://docs.firstresonance.io/automate-with-ion/integrations/datum

Connect ION purchasing with Datum sourcing so approved quotes create draft purchase orders in ION.

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/datum.md`.
</Note>

### Integration Information

From a high level, ION is your source of truth for inventory, and to get inventory into the system you need to receive purchase orders. Datum handles all functions related to the sourcing process including requisitions, managing and interacting with suppliers, quoting, approvals, and open-order updates. ION remains the source of truth for parts but the integration enables those parts to sync to Datum on release. Once the sourcing process is complete and the quote is approved in Datum, the integration creates a draft purchase order in ION. From there you can either issue the purchase order through the Datum supplier portal or continue to submit purchase orders using ION. See [ION automations](/automate-with-ion/integrations/automations) to email purchase orders to suppliers automatically.

After the PO is submitted, expected delivery dates can be updated in Datum which will automatically update the line item ETA on the ION purchase order. Post-receipt functions like billing will still be handled by your financial management software.

Future functionality of the integration will include ION's Autoplan feature pushing plan items to Datum as new requisitions, further enabling your purchasing team to operate efficiently.

<figure><img alt="" /><figcaption><p>Here is a quick graphic depicting the standard purchasing flow overlayed with how the two tools connect. </p></figcaption></figure>

### Integration Setup

1. In ION, navigate to the **Integrations** page designated by the two arrows in the bottom lefthand corner of your screen.
2. Search for and select the Datum integration and then press **Configure**
3. Add your ION API keys which can be obtained by following the [API keys](/api-reference/authentication/api-keys) documentation. Make sure to get API keys for the environment you are setting this integration up in. For example, if you are setting this up in sandbox you will need execute the API key instructions in sandbox.
4. Add your Datum API key which can be obtained in your Datum admin account page > Developer Tab
5. Please reach out to Datum at [matt@datumsource.com](mailto:matt@datumsource.com) for the rest of the Datum side of the integration setup.
6. Select UAT or Production to determine which Datum environment you will receive data from.
7. Press finish.

<figure>
  <img alt="" />

  <figcaption />
</figure>


# Deploy an integration or automation
Source: https://docs.firstresonance.io/automate-with-ion/integrations/deploying-integrations-and-automations

Deploy a prebuilt integration or automation from the ION Marketplace by configuring its ION API connection and the fields it needs.

ION's prebuilt integrations and automations live in the ION Marketplace. To deploy one, open the Marketplace, configure its connection to ION, and fill in the fields the integration needs.

## Deploy from the Marketplace

1. In the sidebar, select **Integrations** to open the ION Marketplace.
2. Find the integration or automation you want, then select **Configure**.
3. In the ION API connection step, enter your ION API key and secret, then select the environment to run in. See [API keys](/api-reference/authentication/api-keys) for how to create them.
4. Fill in any additional fields the integration requires. These point the integration at the ION objects or attributes it acts on, and come as free-text inputs or pick-lists. Each integration documents its own fields.
5. For a partner integration, connect the external system (such as Arena, Duro, or Smartsheet) using that partner's setup steps.

<Warning>
  API keys are environment-specific. A sandbox key and secret do not work in production. Use keys generated in the same environment you are deploying to.
</Warning>

<Note>
  An API key inherits the permissions of its creator. Create the key as a user with the permissions the integration needs.
</Note>

The integration's [webhook](/api-reference/guides/webhooks) subscriptions are created when you first deploy an instance, and are removed only when you deactivate that instance, not when you pause it.

<Note>
  Some webhook-driven automations need their trigger set explicitly: a **ResourceEnum** value (what to listen to) and a **WebhookSubscriptionActions** value (what to listen for). Find the valid values in ION's GraphQL documentation explorer, and match the input format exactly as it appears there.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="You don't see the Integrations page">
    Your organization might not have Marketplace access yet. Contact [Support](https://support.firstresonance.io/) to request it.
  </Accordion>

  <Accordion title="An automation stops triggering after an environment change">
    Each environment needs its own API keys, so an instance moved between sandbox and production stops working. Redeploy it with keys from the target environment:

    1. Record the current setup of your instances.
    2. Deactivate the existing instances to clear any stray webhook subscriptions between environments.
    3. Create new instances using the API key and secret for the correct environment.
    4. Confirm the trigger's resource and action when you create each instance.
  </Accordion>

  <Accordion title="A deployed integration shows no executions, and webhook events return 401">
    The integration deployed successfully, but you see no executions, and the webhook events in the ION API return 401 errors. This happens when API keys were entered into the trigger details. Open the integration's summary page, select **Reconfigure**, and expand the trigger details. Delete any API key listed there with the trash icon. The trigger details should have nothing below the URL for each flow.
  </Accordion>
</AccordionGroup>

## Related

* [API keys](/api-reference/authentication/api-keys) for creating the credentials an integration uses
* [Webhooks](/api-reference/guides/webhooks) for how ION delivers events to an integration


# Duro
Source: https://docs.firstresonance.io/automate-with-ion/integrations/duro

Duro PLM Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/duro.md`.
</Note>

Skip to the [Set up](#set-up) section for instructions on how to deploy or reconfigure this integration.

Establish Duro as the source of truth for product/component metadata, and bill of materials (BOM), while ION parts remain up to date with changes made in Duro with no manual intervention. This integration eliminates the extra effort it typically takes to manually import part details and BOM information into ION, which will help you create procedures and get to building faster.

[https://www.loom.com/share/3d3d6732c5f648688179e797aa7c7621?sid=748a2559-f090-4afd-bcda-8d13e50425a2](https://www.loom.com/share/3d3d6732c5f648688179e797aa7c7621?sid=748a2559-f090-4afd-bcda-8d13e50425a2)

### Duro Change Order Approved

On change order approval within Duro, an integration with ION will fire which propagates part information and BOM changes to ION. Any time a new part, a new revision, or a new BOM is released in Duro via the change order process, that information will propagate to ION. ION, with the use of [mBOM versions](/build-hardware/bills-of-materials/versions), automatically generates a new draft mBOM version for that part, adds all of the components, and then releases that mBOM version in ION.

<Note>
  Remember, ION does not have a release process and we do not prevent you from manipulating part data in ION once a component has been released in Duro. This is useful for setting sourcing strategy, tracking type, and supplier part relationships in ION if it is not set in Duro. If you want to prevent this, see [role-based access control](/administration/users-and-permissions).
</Note>

<figure><img alt="" /><figcaption><p>Duro Integration</p></figcaption></figure>

## mBOMs Versions in ION

We recommend that you create a new mBOM version that you release in ION if you want to add additional information such as tape, epoxies, and adhesives not covered by the engineering BOM.

## Determining the Suppliers of your BOM

When importing your BOM, we recommend you use [supplier part numbers](/manage-supply-chain/purchasing/unit-of-measure-conversions) to map the BOM to specific suppliers. This data feeds supplier and procedure suggestions, and often your procurement team lives in ION, so we do not recommend setting up the integration to pull this data from Duro and instead create that data directly in ION. We recommend creating a DCO to release a BOM into ION before it gets approved via an ECO, so you can parallelize sourcing and finalizing the engineering instead of treating this as a waterfall approach. The sole caveat is that you may want manufacturers and MPNs to come over to ION because engineering often is pulling those parts from a specific spec and manufacturer, especially for commercially available parts. From there, the sourcing team can use ION to determine the supplier/distributor for those parts.&#x20;

## Set up&#x20;

1. Navigate to the **Integrations** page designated by the two arrows in the bottom left corner of your screen.

   <figure><img alt="" /><figcaption><p>Select Integrations in the Bottom Left Hand Corner</p></figcaption></figure>
2. Select Duro integration instance from the marketplace, and hit **Configure.**&#x20;
3. Hit **Next** and add your API credentials. You can find documentation on [API keys](/api-reference/authentication/api-keys) here.

   * **IMPORTANT:** Each API Key is associated with a specific environment, be sure to generate the API keys from the correct environment and configure the automation to the designated environment. Be sure to also select the correct environment. If you are on the `Gov Cloud` environment then selecting `Production` will result in an error. Contact your Customer Success Engineer if you are unsure which environment you are on.

   <figure><img alt="" /><figcaption><p>Set your Environment According to Where the API Keys were Generated</p></figcaption></figure>
4. Generate a Duro API Key by [navigating to the integration settings page](https://mfg.duro.app/settings/integrations) and select Get API Key. Input that into the configuration of the integration.&#x20;
   1. NOTE: Duro API keys expire every 90 days. Learn more from [Duro here!](https://duro.zendesk.com/hc/en-us/articles/11814592464532-Quick-Start-Guide-to-using-Duro-s-GraphQL-API#h_01GMY1Z7ZGR8Y7KR4V8FG24F2M)
5. Select the Duro GraphQL Link. There are two possible values. ITAR clients should use `https://app.goveduro.us/graphql` while all others should use `https://mfg-core-api.duro.app/graphql`<br />

   <figure><img alt="" /><figcaption><p>Select the Duro GraphQL Link</p></figcaption></figure>
6. Ensure the revision schemes for your production and prototype parts are created in ION and the names inputted into the configuration screen. Ensure the allow overflow box is checked if you are going to go over two characters.<br />

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
7. To finish the configuration, you can map the data between the two platforms by adding key value pairs for ION native attributes and custom attributes. The keys are ION fields and the values are Duro fields. Below is an example of the mapping.
   1\.

   <figure>
     <img alt="" />

     <figcaption />
   </figure>
8. You can map values from the primary source as well such as manufacturer or distributor, however, please see the above section on Suppliers in ION for our recommended approach.
9. Hit Finish to complete the integration configuration. Head to the *Test* page, and copy the Post URL of Flow 1 by clicking the *clipboard icon* as seen below in order to configure the webhook in Duro in the following step.&#x20;

   <figure><img alt="" /><figcaption><p>Find the Post URL of Flow 1 from the Test Tab</p></figcaption></figure>
10. The last step is creating a Duro webhook that sends data to ION when a change order is approved. Navigate to the webhook page in settings and create new one. You can populate the URL with the URL you captured in the previous step. Fill out the remaining details as seen below.

    <figure>
      <img alt="" />

      <figcaption />
    </figure>

<Note>
  Please ensure the *Include all Components and Products data* below is checked as seen below
</Note>

### Current Limitations and Troubleshooting

* At the moment, file attachments and links to specs, manufacturers, distributors, drawings, and others are not supported. Don't hesitate to contact our team if this is a critical need for your operation.
* Ensure your revision schemas are updated in ION to support Alphabetical and Numerical and ensure the integration settings reflect the case-sensitive names. If you change the schema names in ION, ensure the integration is updated to reflect that.
* Ensure you have selected the correct `Environment` and `Duro GraphQL Link`
* If your Duro integration was working then suddenly stops, check your Duro API keys. The API keys from Duro are unique to each user and expire every 90 days! Learn more from [Duro here.](https://duro.zendesk.com/hc/en-us/articles/11814592464532-Quick-Start-Guide-to-using-Duro-s-GraphQL-API#h_01GMY1Z7ZGR8Y7KR4V8FG24F2M)


# ERP and PLM reference architecture
Source: https://docs.firstresonance.io/automate-with-ion/integrations/erp-plm-reference-architecture

How ION integrates with ERP and PLM systems: the triad model, BOM lifecycle, canonical data flows, the 3-way match pattern, the 14 rules, and the recommended deployment sequence.

## Overview

ION integrates with two adjacent system classes in every hardware-manufacturing stack: **PLM** (Product Lifecycle Management) upstream and **ERP** (Enterprise Resource Planning) downstream. This page is the reference for those integrations: what flows where, what doesn't, and the recommended deployment sequence.

Read this before scoping an integration with [Arena](/automate-with-ion/integrations/arena), [NetSuite](/automate-with-ion/integrations/netsuite), [Teamcenter](/automate-with-ion/integrations/teamcenter), [Duro](/automate-with-ion/integrations/duro), Onshape, or any other ERP or PLM system. The per-vendor pages cover *how* a specific connector works; this page covers *why* the architecture is shaped the way it is.

> Diagrams in this doc are authored in [Mermaid](https://mermaid.js.org/) and render natively in the manual.

## ION in the factory stack

ION Factory OS is a **Manufacturing Execution System (MES)** at Level 3 of the ISA-95 enterprise-control hierarchy, with native production planning extending into Level 4. ION's job is to track and document the transformation of raw materials into finished goods on the production floor, and to be the closed-loop bridge between the engineering systems that *define* what gets built (PLM) and the financial systems that *transact* what gets bought, sold, and counted (ERP).

```mermaid theme={null}
flowchart TB
    subgraph L4["Level 4: Business Planning & Logistics"]
        ERP["ERP<br/>NetSuite · Dynamics 365 · SAP · Epicor"]
        PLM["PLM<br/>Teamcenter · Arena · Windchill · Onshape · Duro · SolidWorks PDM"]
        CRM["CRM · HRM"]
    end
    subgraph L3["Level 3: Manufacturing Operations Management"]
        ION["<b>ION Factory OS</b><br/>MES + native production planning<br/>Runs · Procedures · Quality · Labor · Traceability · As-built · Inventory (shop-floor)"]
        Adj["Adjacent L3 systems<br/>LIMS · WMS · CMMS"]
    end
    subgraph L2["Level 2: Supervisory Control"]
        SCADA["SCADA · HMI · Historians"]
    end
    subgraph L1["Level 1: Direct Control"]
        PLC["PLC · DCS"]
    end
    subgraph L0["Level 0: Physical Process"]
        Field["Sensors · Actuators · Machines"]
    end

    L4 <-->|"Plans, intent,<br/>transactions"| L3
    L3 <-->|"Setpoints,<br/>process data"| L2
    L2 <--> L1
    L1 <--> L0
```

Every integration question reduces to *which level owns this data, and who else needs a copy?* The rules below fall out of this picture.

## Why integrate at all: the business goals

Every ERP and PLM integration ION ships should trace back to one or more of these outcomes. If a proposed integration scope does not advance one of these, it is not the right scope.

| Goal                                | What it means in practice                                                                                                                                                                | Where the integration lives                    |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Proper billing with 3-way match** | Vendor invoices are paid only when PO + Bill + Item Receipt match. No phantom payments, no missed receipts.                                                                              | ERP ↔ ION                                      |
| **Inventory valuation**             | Finance can value on-hand and WIP inventory in dollars, with audit trail back to receipts and consumption.                                                                               | ION → ERP (receipts, completions, consumption) |
| **Accurate COGS: material + labor** | Cost of goods sold is calculated from actual material consumed and actual labor recorded, not standard-cost approximations. Critical for cost-plus contracts and gross margin reporting. | ION → ERP (consumption + labor)                |
| **Reduce ERP seat license cost**    | Production teams work in ION, not in NetSuite, Dynamics, or SAP. Only finance and procurement need ERP seats.                                                                            | ION as the production UI; ERP for finance only |
| **Engineering change traceability** | Production reflects the released engineering revision; as-built records tie back to the design version that produced them.                                                               | PLM ↔ ION                                      |
| **Closed-loop quality**             | NCRs and deviations found in production feed back into engineering as ECRs; production runs don't proceed against stale revisions.                                                       | ION → PLM (NCRs / MRBs / inspection results)   |

These are the goals to lead with on the first slide of any integration scoping conversation. Everything below is the architecture that makes them deliverable.

## The triad: PLM, MES (ION), ERP

These three systems are the operational triad of any modern hardware manufacturer. Each owns a distinct part of the product's life. Trouble starts when one tries to do another's job.

```mermaid theme={null}
flowchart LR
    subgraph PLM_block["PLM: Product Intent"]
        PLM["What the product<br/><b>should</b> be"]
        PLM_owns["Engineering BOM (eBOM)<br/>Parts · Revisions · Drawings<br/>ECN / ECR<br/>Routings (engineering)<br/>Product hierarchy"]
    end

    subgraph ION_block["ION: Production Reality"]
        ION["What the product<br/><b>actually became</b>"]
        ION_owns["Runs · Procedures<br/>As-built BOM (aBOM)<br/>Quality / NCRs / MRBs<br/>Labor · Traceability<br/>Shop-floor inventory<br/>Issues · Deviations"]
    end

    subgraph ERP_block["ERP: Financial Transactions"]
        ERP["What the product<br/><b>cost and earned</b>"]
        ERP_owns["Suppliers (financial)<br/>Purchase Orders<br/>Item Receipts<br/>Item master (financial)<br/>GL · AP · AR · Costing"]
    end

    PLM -->|"Parts · eBOM · routings · ECNs"| ION
    ION -->|"As-built · NCRs · test results"| PLM
    ERP -->|"POs · suppliers · terms"| ION
    ION -->|"Receipts · completions · consumption"| ERP
```

**One-line summary:**

* **PLM** = the *intent* (engineering definition).
* **MES (ION)** = the *reality* (what actually happened on the floor).
* **ERP** = the *accounting* (what was bought, what was received, what was paid).

The rest of this document is precision around what flows between them.

## PLM ↔ ION reference architecture

PLM is the system of record for the engineering definition of the product. ION is the system of record for what the production floor does with that definition.

### The BOM lifecycle: eBOM → mBOM → aBOM

The BOM is not a single object. It evolves across the manufacturing lifecycle, and each stage has a different owner. Conflating them is the most common source of integration scope confusion.

| Stage                                                                               | Owner | What it is                                                                                                                                                                | Lifetime                                                     |
| ----------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **eBOM, Engineering BOM**                                                           | PLM   | The design intent. The list of parts and assemblies the engineer specifies, by revision. Released into production.                                                        | Tied to the engineering revision; immutable once released.   |
| **[mBOM, Manufacturing BOM](/build-hardware/bills-of-materials/manufacturing-bom)** | ION   | The manufacturing-ready BOM, derived from the eBOM. Adds manufacturing-only items (consumables, fasteners, fixtures), alternates, work-center assignments, kit groupings. | One per procedure version; updates with procedure revisions. |
| **[aBOM, As-built BOM](/build-hardware/bills-of-materials/as-built-bom)**           | ION   | The actual record of what was consumed in a specific serial number or lot. Captures substitutions, scrap, rework, and deviations.                                         | One per serial number or run; immutable once the run closes. |

The flow is **eBOM (PLM) → mBOM (ION) → aBOM (ION) → optional feedback to PLM**.

```mermaid theme={null}
flowchart LR
    eBOM["<b>eBOM</b><br/>Engineering BOM<br/>(PLM)<br/>Design intent"]
    mBOM["<b>mBOM</b><br/>Manufacturing BOM<br/>(ION)<br/>Released for production"]
    aBOM["<b>aBOM</b><br/>As-built BOM<br/>(ION)<br/>Actual consumption per SN"]
    Feedback["NCRs · MRBs ·<br/>as-built reconciliation<br/>(ION → PLM)"]

    eBOM -->|"Released revision"| mBOM
    mBOM -->|"Run instantiates<br/>procedure"| aBOM
    aBOM -->|"Deviations,<br/>configuration record"| Feedback
    Feedback -.->|"Drives ECRs"| eBOM
```

<Note>
  **When there is no PLM:** Many small or mid-stage manufacturers have no formal PLM. In that case, ION holds what is functionally an mBOM (sometimes informally called "the BOM"), and there is no upstream eBOM. This is acceptable for Phase 1 deployments. As soon as PLM is introduced (often Phase 3), eBOM authority moves to PLM, and ION's BOM becomes explicitly the mBOM. The "BOM lives in ION" state is transitional, not a permanent architectural commitment.
</Note>

### Canonical data flows: PLM → ION

| Object                                   | Direction                  | Purpose                                                                                          | ION's role                                                                                      |
| ---------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| **Items / Parts (engineering identity)** | PLM → ION                  | Establish the part the floor builds or consumes; carry engineering revision and lifecycle state. | Manufacturing reference; ION can also hold financial-side metadata that mirrors ERP's Items.    |
| **eBOM (engineering BOM)**               | PLM → ION                  | Define what should be in the assembly per the engineering revision.                              | Source from which ION derives its mBOM.                                                         |
| **Routings (engineering definition)**    | PLM → ION                  | Define the high-level steps of manufacture.                                                      | Imported as procedure / step templates.                                                         |
| **ECN / ECR notifications**              | PLM → ION                  | Propagate engineering change.                                                                    | Trigger procedure revision; surface to operators in-context; gate runs against stale revisions. |
| **Drawings / CAD links**                 | PLM → ION (reference only) | Operator access to design spec.                                                                  | Reference link in step content; ION does not host the CAD.                                      |

**On Items duplication:** Items typically exist in both PLM (engineering identity: revision, lifecycle, drawing reference) **and** ERP (financial identity: cost, GL account, tax code, vendor part number). PLM is the upstream source for the engineering attributes; ERP is the upstream source for the financial attributes. **ION holds the operational view**: the item as it appears on the floor, kitted, consumed, scanned. ION can pull from either or both depending on what's in the customer's stack.

### Canonical data flows: ION → PLM

| Object                                                                     | Direction             | Purpose                                                                                           | PLM's role                                                                    |
| -------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **[As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)** | ION → PLM             | What was actually consumed and built per serial number, with substitutions and lot/serial detail. | Engineering audit trail; configuration management; type certification record. |
| **[NCRs / MRB outcomes](/track-quality/issues)**                           | ION → PLM             | Defects, deviations, dispositions found in production.                                            | Source for ECRs back into engineering.                                        |
| **In-process inspection / test results**                                   | ION → PLM             | Production verification data.                                                                     | Engineering certification, type acceptance, design-of-experiments feedback.   |
| **Production traceability records**                                        | ION → PLM (reference) | "This serial number was built from these parts via these procedures against this revision."       | Linked to the design version that produced it.                                |

### What does NOT cross the PLM ↔ ION line

* **eBOM authoring in ION.** PLM owns the engineering BOM when PLM exists. ION derives an mBOM from it; ION does not modify the eBOM.
* **Drawings / CAD in ION.** ION holds reference links, not drawings. PLM is the source.
* **Engineering revisions in ION.** Revision authority lives in PLM. ION shows the released revision in production context.
* **Real-time CAD round-trip.** No live CAD editing from ION. If the operator finds a problem, that becomes an [NCR or MRB](/track-quality/issues), which feeds an ECR back to PLM, where the engineer makes the change.

### ION's PLM connector posture

* **Production today:** [Arena](/automate-with-ion/integrations/arena) (multiple A\&D customers), Onshape (selected customers), [Duro](/automate-with-ion/integrations/duro) (in deployment).
* **Partner-built:** [Teamcenter](/automate-with-ion/integrations/teamcenter) (via a PLM systems-integrator partner). Teamcenter integration sits at the PLM customization edge: most customers engage their PLM consultant for the Teamcenter side, and ION owns the ION side.
* **Verify before scope:** PLM systems often have major version differences (Duro vs. Duro Hub, Windchill versions, on-prem vs. cloud Teamcenter). Verify the customer's actual deployment before signing scope.

## ERP ↔ ION reference architecture

ERP is the system of record for financial transactions. ION is the system of record for production execution. They share a small, well-defined set of objects.

### Canonical data flows: ERP → ION

| Object                                             | Direction                    | Purpose                                | ION's role                                                 |
| -------------------------------------------------- | ---------------------------- | -------------------------------------- | ---------------------------------------------------------- |
| [Purchase Orders](/manage-supply-chain/purchasing) | ERP → ION                    | Procurement → production trigger       | Read-only execution view; lines mapped to ION parts        |
| Suppliers                                          | ERP → ION (via PO)           | Identify vendor on the floor           | Created in ION as a side-effect of PO sync                 |
| Payment Terms                                      | ERP → ION                    | Reference data on POs                  | Display only                                               |
| Item master (financial)                            | ERP → ION (optional, lookup) | Item identity for non-PLM-driven shops | Read-only reference; PLM is preferred source if both exist |

### Canonical data flows: ION → ERP

| Object                                                     | Direction                       | Purpose                                                                    | ERP's role                                |
| ---------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- |
| [Receipts (shop-floor)](/manage-supply-chain/receiving)    | ION → ERP                       | Materials physically received against PO                                   | Triggers Item Receipt + financial posting |
| Work order completions                                     | ION → ERP                       | Production output recorded for cost rollup                                 | GL recognition of completed inventory     |
| Labor / time                                               | ION → ERP (cost-plus customers) | Direct labor on jobs                                                       | Cost-plus billing, GL labor allocation    |
| [Inventory](/manage-supply-chain/inventory) reconciliation | ION → ERP (report, not sync)    | Periodic reconciliation between shop-floor reality and financial inventory | Adjusting entries; not real-time mirror   |

### Syncing to ERP

Prefer event-driven sync over scheduled polling. ION emits [webhooks](/api-reference/guides/webhooks) the moment an event occurs, such as a run completing or a receipt posting, so the ERP stays current and failures surface in context instead of on the next poll. If your ERP doesn't need updates that often, have your integration queue ION's events and batch them into the ERP on a schedule. ION has supported integrations with NetSuite, Epicor, Dynamics 365, Business Central, Odoo, and Infor.

To sync as-built consumption to the ERP, query the aBOM installations on the part inventory produced by completed runs:

```graphql theme={null}
query ($filters: RunsInputFilters) {
  runs(filters: $filters) {
    edges {
      node {
        title
        partInventory {
          part { partNumber }
          quantity
          buildRequirements {
            abomInstallations {
              quantityInstalledPerParentPartInventory
              partInventory {
                location { id }
                part { partNumber }
              }
            }
          }
        }
      }
    }
  }
}
```

For each installed part inventory, multiply the quantity produced by `quantityInstalledPerParentPartInventory` to get total consumption. The same component can appear more than once when it's installed from different inventory locations. For a run that produced three of Assembly Part One, that gives 15 of Component Part One (2.4 × 3 + 2.6 × 3) and 9 of Component Part Two (3 × 3).

### What does NOT cross the ERP ↔ ION line

* **Bidirectional inventory sync.** ION owns shop-floor inventory in real time. ERP owns financial inventory at posting cadence. They reconcile periodically. *They do not bidirectionally mirror.* This is the single most damaging anti-pattern in MES/ERP integration. (See Rule 5 below.)
* **Production scheduling in ERP.** Work order release and floor scheduling live in ION. ERP can hold high-level demand or master schedule, but the dispatch happens in MES.
* **GL postings authored by ION.** ION emits the events (receipt, completion, labor). ERP posts to GL according to its own rules.
* **Vendor bills, invoices, AP, AR.** ERP-only. Out of any normal ION integration scope.
* **Items master authored by ION.** If PLM is in the picture, PLM authors. If ERP is the only product-data system (rare for hardware companies that build), ERP authors. ION never authors.

### ION's ERP connector posture

* **Production today:** [NetSuite](/automate-with-ion/integrations/netsuite) (multiple deployments), Dynamics 365 (electric aviation customer).
* **In-flight:** SAP (early scoping; pattern not yet certified).
* **Customer-side configuration is the customer's responsibility:** custom forms, scripts, saved searches, OAuth, role permissions, sandbox provisioning. Either the customer's internal ERP admin or the customer's ERP consulting partner.

### The 3-way match: the canonical AP control loop

The single most-asked-for outcome from any ERP integration is **3-way match**: the financial control that prevents an invoice from being paid unless three documents agree.

```mermaid theme={null}
flowchart LR
    subgraph ION_side["ION (production)"]
        Run["Run / Receipt event<br/>on the floor"]
    end

    subgraph ERP_side["ERP (3-way match)"]
        PO["<b>Purchase Order</b><br/>What was authorized"]
        Receipt_ERP["<b>Item Receipt</b><br/>What physically arrived"]
        Bill["<b>Vendor Bill</b><br/>What the vendor invoiced"]
        Match{"3-way<br/>match"}
        Pay["AP releases<br/>payment"]
    end

    Run -->|"Receipt in ION<br/>creates Item Receipt"| Receipt_ERP
    PO --> Match
    Receipt_ERP --> Match
    Bill --> Match
    Match -->|"All three agree<br/>(qty, price, item)"| Pay
```

**ION's role in 3-way match:** ION's job is to make the **Item Receipt** real, automatic, and accurate by recording what physically arrived at the receiving dock and triggering the matching ERP record. Without a connected ION, the Item Receipt is a manual data-entry step in the ERP that operators forget, mis-key, or batch up. This is where most "phantom payments" and "missed receipts" come from.

**Why this is the lead outcome:** every CFO understands 3-way match. It is the easiest integration goal to socialize internally and the most defensible ROI story.

**What 3-way match needs from each side:**

| Side             | Required                                                                                                                          | Why                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| ERP              | Purchase Orders with line-level detail (item, qty, price); Vendor Bill workflow; Item Receipt entity that can be created via API. | The match logic lives in ERP.                         |
| ION              | Receipts at the line level, tied back to the originating PO via a durable join key; quantity and item agreement with the PO line. | The trigger event lives in ION.                       |
| Customer process | Vendor invoices submitted to AP through a defined channel; receiving discipline at the dock (don't receive what didn't arrive).   | The control only works if the human process feeds it. |

### Multi-location and inter-location transfers

Customers with multiple physical sites introduce a class of integration questions that single-site customers do not face:

* **Where does inter-location inventory transfer get recorded?** ION owns the operational transfer (parts physically move site-to-site under custody chain). ERP owns the financial reclassification (inventory by location for tax / GL).
* **Granularity question:** does the ERP need site-level inventory tracking, or is location-level handled entirely in ION? Most customers benefit from site-level rollups in ERP and bin/cell-level granularity in ION.
* **Planning question:** does demand at one site automatically trigger procurement at another, or are sites planned independently? This is a planning-system question more than a strict integration question, but it shapes how much of MRP / Autoplan to expose across sites.

These are scoping questions for the Phase 2 / Phase 3 conversation. Surface them early when the customer has more than one site.

### PO setup attributes

ERP POs typically carry attributes that ION needs but doesn't author: department, location, cost center, project code, GL account override, tax code. These need to flow with the PO so that ION can route receipts to the correct location and so that downstream financial events (consumption, completion) carry the right tags.

The ION NetSuite connector handles this via configurable PO Header and PO Line attribute data maps. For non-NetSuite ERPs, equivalent mappings need to be defined per integration. **This is configuration, not code**, but it is non-trivial work that should not be skipped at scoping time.

## The combined picture: ION as the execution spine

In a fully-instrumented A\&D or hardware manufacturer, the three systems form a closed loop. Engineering defines (PLM), production executes (ION), finance accounts (ERP). Each cycle of build → release → ship → invoice closes through ION.

### Integration control plane

The triad above is the executive view. Use the diagram below for scoping: it groups objects by ownership, shows the high-confidence lanes, and keeps financial posting separate from operational execution.

```mermaid theme={null}
flowchart LR
    %% Keep ownership explicit: PLM defines, ION executes, ERP accounts.
    classDef plm fill:#eef5ff,stroke:#6b9bd8,color:#1f2937
    classDef ion fill:#eefcf6,stroke:#35a06e,color:#1f2937
    classDef erp fill:#fff7e6,stroke:#d28b27,color:#1f2937
    classDef event fill:#f5f3ff,stroke:#8b5cf6,color:#1f2937
    classDef ledger fill:#fdf2f8,stroke:#db2777,color:#1f2937

    subgraph PLM["PLM: engineering definition"]
        direction TB
        ENG_ITEMS["Engineering items<br/>revisions · lifecycle"]:::plm
        EBOM["Released eBOM"]:::plm
        CHANGE["ECNs / ECRs"]:::event
        ENG_ITEMS --> EBOM --> CHANGE
    end

    subgraph ION["ION Factory OS: execution spine"]
        direction TB
        PARTS["Operational parts<br/>shop-floor identity"]:::ion
        MBOM["mBOM + procedures<br/>build plan"]:::ion
        DEMAND["Demand + plans<br/>work order release"]:::ion
        RUN["Run execution<br/>operators · quality · labor"]:::ion
        ABOM["aBOM + receipts<br/>actual material record"]:::ion
        INV["Granular inventory<br/>bin · cell · serial · lot"]:::ion
        PARTS --> MBOM --> DEMAND --> RUN --> ABOM --> INV
    end

    subgraph ERP["ERP: financial system of record"]
        direction TB
        FIN_ITEMS["Financial item master<br/>cost · GL · tax"]:::erp
        PO["Purchase orders<br/>suppliers · terms · attributes"]:::erp
        MATCH["3-way match<br/>PO · receipt · vendor bill"]:::ledger
        LEDGER["GL · AP · AR<br/>valuation · postings"]:::ledger
        FIN_ITEMS --> PO --> MATCH --> LEDGER
    end

    ENG_ITEMS -->|"engineering identity"| PARTS
    EBOM -->|"released structure"| MBOM
    CHANGE -->|"change impact"| MBOM
    CHANGE -->|"NCR / MRB feedback"| RUN

    PO -->|"PO sync + line attributes"| DEMAND
    PO -->|"supplier context"| PARTS
    FIN_ITEMS -.->|"optional financial lookup"| PARTS

    ABOM -->|"item receipt event"| MATCH
    ABOM -.->|"consumption posting"| LEDGER
    INV -.->|"valuation reconciliation<br/>not bidirectional sync"| LEDGER
    RUN -.->|"as-built feedback"| CHANGE
```

**How to read this diagram:**

* **Each column has one owner:** PLM owns engineering definition, ION owns execution truth, and ERP owns financial accounting.
* **ION is the execution spine:** engineering releases and ERP demand converge into parts, mBOMs, plans, runs, aBOMs, receipts, and granular inventory.
* **Financial controls stay clean:** ION creates real receipt and consumption events; ERP performs 3-way match, AP / AR, GL, and valuation.
* **Dotted arrows are posting or reconciliation paths:** they update accounting or feedback systems without creating bidirectional inventory ownership.

### Reference deployments

ION is in production across the following ERP and PLM combinations. New customers can scope against these patterns rather than starting from scratch.

| Industry segment                      | ERP          | PLM        | Integration shape                                            | Status         |
| ------------------------------------- | ------------ | ---------- | ------------------------------------------------------------ | -------------- |
| Satellite communications (mid-size)   | NetSuite     | Arena      | PO sync NS→ION; Item Receipts ION→NS; Arena part / eBOM sync | Live           |
| Autonomous maritime (mid-size)        | NetSuite     | None       | PO sync; inventory reconciliation reporting                  | Live           |
| Electric aviation (large)             | Dynamics 365 | (mixed)    | ERP sync; webhook-based event flow                           | Live           |
| Defense maritime (small, high-growth) | NetSuite     | None       | Phased: ION standalone → NS PO + receipt sync                | In deployment  |
| Defense / aerospace tooling           | NetSuite     | Teamcenter | Three-system: NetSuite ERP + Teamcenter PLM + ION MES        | Active scoping |
| Defense engine components             | (varies)     | Arena      | Quality + procedure sync                                     | Active         |

### The recommended sequence for a new customer

The following deployment sequence is recommended. Each phase is useful on its own, so you can adopt them in order without waiting to finish the rest.

```mermaid theme={null}
flowchart LR
    P1["<b>Phase 1: Foundation</b><br/>ION standalone<br/>Runs · Procedures · Quality<br/>Inventory (shop-floor)<br/>Operator workflows<br/>Traceability"]
    P2["<b>Phase 2: Connect</b><br/>ERP integration<br/>POs · Receipts · Suppliers<br/>(via certified connector)"]
    P3["<b>Phase 3: Engineering loop</b><br/>PLM integration<br/>Parts · eBOM · ECNs · Routings<br/>As-built feedback"]
    P4["<b>Phase 4: Orchestrate</b><br/>Forward-deployed scope:<br/>ION-driven PO creation<br/>(Autoplan)<br/>Cost roll-ups<br/>Outside processing"]

    P1 --> P2
    P2 --> P3
    P3 --> P4
```

**Phase 1, Foundation.** ION is deployed standalone as the production system of record. [Procedures](/build-hardware/procedures), [runs](/build-hardware/runs-and-execution), [quality](/track-quality/issues), kitting, traceability, and [shop-floor inventory](/manage-supply-chain/inventory) live in ION. ERP and PLM continue to operate as today. **No integration dependency for go-live.** This pattern protects margin and de-risks the launch.

**Phase 2, Connect (ERP).** A pre-built, certified connector links ION to the ERP. [POs](/manage-supply-chain/purchasing) flow into ION, [receipts](/manage-supply-chain/receiving) flow back. The customer's ERP admin or consultant configures the ERP-side; ION's team configures the ION-side. **Configuration, not custom development.**

**Phase 3, Engineering loop (PLM).** PLM integration brings part master, eBOM, and engineering change notifications into ION; sends as-built and NCR data back. Often phased: parts + eBOM first; ECNs and as-built second.

**Phase 4, Orchestrate.** Forward-deployed engineering work that goes beyond the certified connectors: ION-driven PO creation via Autoplan, financial cost roll-ups, outside processing flows, cost-plus labor reporting. **Scoped per engagement, not assumed.**

## Canonical rules

The following rules apply to every ION integration. They are the distillation of canonical MES/ERP/PLM literature (ISA-95, MESA) and the accumulated experience across 20+ customer deployments. They exist to keep integration scope aligned with what actually works, and to prevent the failure patterns that are easy to fall into during early scoping conversations.

| #  | Rule                                                                                                                                                                                                          | Why                                                                                                                                                    |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1  | **PLM owns engineering intent. ION owns production reality. ERP owns financial transactions.**                                                                                                                | The triad. Every other rule follows from this.                                                                                                         |
| 2  | **PLM authors the eBOM. ION produces the [as-built BOM](/build-hardware/bills-of-materials/as-built-bom).** They are different objects with different lifecycles.                                             | The eBOM is design-time; the aBOM is run-time. Trying to merge them creates ambiguous state.                                                           |
| 3  | **Engineering revisions are released *into* production, not authored *from* it.** Operator-found problems become NCRs/MRBs that feed ECRs back to PLM, where the engineer makes the change.                   | Configuration management requires a single authoring path.                                                                                             |
| 4  | **POs are owned by ERP. Receipts on the floor are owned by ION.** A receipt in ION triggers an Item Receipt in ERP, not the reverse.                                                                          | Production reality leads; financial recording follows.                                                                                                 |
| 5  | **Inventory does not bidirectionally sync between ION and ERP.** ION holds shop-floor reality in real time; ERP holds financial inventory at posting cadence. They reconcile, they do not mirror.             | The single most damaging anti-pattern in MES/ERP integration. Bidirectional sync creates race conditions, conflicting truths, and reconciliation hell. |
| 6  | **Inventory and locations are out of scope for any first-pass ERP integration.** Phase 3+ conversation, scoped explicitly.                                                                                    | Pulling inventory into a first-pass ERP sync creates more reconciliation pain than it solves.                                                          |
| 7  | **Production scheduling lives in MES.** ERP can hold demand or master schedule; dispatch happens in ION.                                                                                                      | Schedule rigidity in ERP is incompatible with shop-floor reality.                                                                                      |
| 8  | **Items master lives where it was born.** PLM if engineering-led, ERP if procurement-led. ION never authors. If both PLM and ERP claim it, PLM wins for hardware companies.                                   | Single source of truth for item identity.                                                                                                              |
| 9  | **Connectors before commitments.** ION integrations are available via pre-built, certified connectors. New connectors are scoped, priced, and sequenced separately, not assumed in a master agreement.        | Avoids the "we'll build it" trap that produces multi-month delays and missed scope.                                                                    |
| 10 | **Every integration ships with a defined acceptance criterion, owner, and SLA.** No indefinite UAT states.                                                                                                    | UAT-stuck-at-90% is the second-most-common failure pattern after scope ambiguity.                                                                      |
| 11 | **Health monitoring is part of the integration, not a follow-up.** Integrations that "worked at handoff" but degraded silently are unacceptable.                                                              | Post-launch silent degradation is how customers lose confidence in months, not weeks.                                                                  |
| 12 | **Verify the customer's actual environment before scoping.** ERP version, PLM version, on-prem vs. cloud, custom forms / scripts already in place.                                                            | Wrong-version assumptions cause weeks of delay.                                                                                                        |
| 13 | **Three-party engagements (ION + customer + customer's SI) require explicit scoping with all three named on the SOW.**                                                                                        | Scoping gaps between ION and the customer's SI cause silent failures and finger-pointing.                                                              |
| 14 | **Default to two-party (ION + customer).** Insert third-party SI only when the customer's environment requires it (for example, PLM that needs vendor expertise like Teamcenter) or the customer asks for it. | Smaller engagement, fewer hand-offs, less cost.                                                                                                        |

## Source documents

* **ISA-95 standard**: ANSI/ISA-95.00.01 *Enterprise-Control System Integration*
* **MESA model**: Manufacturing Enterprise Solutions Association, MESA-11 functional areas

## Related

* [Bills of Materials](/build-hardware/bills-of-materials): mBOM and aBOM in detail
* [Purchasing](/manage-supply-chain/purchasing): POs and the ERP receipt loop
* [Receiving](/manage-supply-chain/receiving): the dock-side trigger for 3-way match
* [Issues and NCRs](/track-quality/issues): the quality feedback loop into PLM


# Export data as PDF
Source: https://docs.firstresonance.io/automate-with-ion/integrations/export-data-as-pdf

How to export data from ION in the form of a PDF

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/pdf-generator.md`.
</Note>

This guide outlines a way to export data from ION using a tool we also use internally: [Carbone.io](https://carbone.io/).

<Note>
  This method does not protect ITAR-restricted data. See [Carbone disclaimer](#carbone-disclaimer) below.
</Note>

***

### Step 1: Start with an Example PDF

Start with an example PDF you already use today, ideally one that includes all the data you want to share in the format your recipients expect. This could be a purchase order, audit log, or build report.&#x20;

***

### Step 2: Define the Data Query

Using the ION GraphQL Explorer, create the API query you need to retrieve all of the information that appears in your example PDF. Identify a real object in ION, such as a purchase order, run, or quality issue, as a sample to build and test your query against.

Ensure the query returns data in a structured JSON format that matches the fields and structure expected by the template you will create in Step 3. Below is an example of a query and the response.

API Call:

```graphql theme={null}
{
  partKit(id:780){
    _updated
    id
    deliveryLocation{
      address
    }
    partKitItems{
      part{
        partNumber
        revision
        description
      }
      quantity
    }
  }
}
```

JSON Response:

```json theme={null}
{
  "data": {
    "partKit": {
      "_updated": "2025-05-08T00:33:40.275245",
      "id": 780,
      "deliveryLocation": {
        "address": "600 Wilshire Blvd,\nSuite 1500,\nLos Angeles, CA 90017"
      },
      "partKitItems": [
        {
          "part": {
            "partNumber": "7777-03",
            "revision": "C",
            "description": "Wheel assembly"
          },
          "quantity": 4
        },
        {
          "part": {
            "partNumber": "1111-545-01",
            "revision": "B",
            "description": "Mounting screw"
          },
          "quantity": 8
        },
        {
          "part": {
            "partNumber": "7777-02",
            "revision": "B",
            "description": "Car body"
          },
          "quantity": 1
        },
        {
          "part": {
            "partNumber": "SA",
            "revision": "1",
            "description": "Spoiler Assembly"
          },
          "quantity": 2
        }
      ]
    }
  }
}
```

***

### Step 3: Create the Template and Test

Use the example PDF from Step 1 as a guide to create a `.docx` or `.odt` template file. Your goal is to recreate the layout and structure of the PDF using Carbone's templating syntax.

For each field in your JSON response from Step 2, insert a dynamic placeholder in the template to represent the data. For example, if you're working with a part kit, your template might include placeholders like `{data.partKit.id}`, or `{data.partKit.deliveryLocation.address}`. Below is an example of a template we created to generate a packing list.

<figure>
  <img alt="" />

  <figcaption />
</figure>

[Download file](/images/automate-with-ion/packing-list.docx)

<Note>
  If you need more information on how to configure complex templates with Carbone.io, we recommend checking out their [quickstart guide!](https://carbone.io/documentation/quickstart/getting-started/generate-a-document.html)
</Note>

Once your template is ready, upload it to Carbone.io and pair it with the JSON data to generate the final PDF. You can preview and adjust formatting as needed until the output matches your expectations.

<Note>
  We recommend adding a few dynamic placeholders at a time in order to test and quickly debug if needed.&#x20;
</Note>

Each template created will have an ID and Carbone has an API key that you can use to automatically call it's API and generate these reports. Here is an example of the [Carbone.io studio](https://carbone.io/documentation/quickstart/getting-started/generate-a-document.html) which enables us to determine if the template is rendering the data correct.

<figure>
  <img alt="" />

  <figcaption />
</figure>

***

### Conclusion

This approach helps you generate clear, professional documents using the latest data in ION, with minimal overhead. It's flexible, supports complex formatting, and can be adapted for a variety of export use cases. You can use the template ID and Carbone API key to setup automated workflows that upload PDFs to ION based on an [event that is triggered](/api-reference/guides/webhooks).

Let us know if you’d like help getting started or want to set this up as part of an automated workflow.

## Carbone disclaimer

ION uses [Carbone](https://carbone.io/), a third-party open-source PDF generator, for PDF document creation via the API. Carbone is designed with privacy in mind: data is not stored and is used only for report generation. Reports are automatically deleted immediately after download, or within one hour, whichever comes first.

If you need heightened data privacy, Carbone offers on-premise and AWS private cloud hosting options. See [Carbone on AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-m4tdvrln53afm).

Carbone is an independent project, not maintained by First Resonance. For support, updates, or security inquiries related to Carbone, refer to its open-source community. ION ensures integration compatibility but does not assume liability for Carbone’s functionality or security.


# NetSuite
Source: https://docs.firstresonance.io/automate-with-ion/integrations/netsuite

How the paid NetSuite ERP integration connects ION purchasing, receiving, and inventory data with NetSuite accounting.

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/netsuite/README.md`.
</Note>

<Note>
  Please note that the Netsuite integration is available as a **paid add-on**. Contact your customer success manager to learn more about pricing and how to enable the Netsuite integration for your account.&#x20;
</Note>

NetSuite is a cloud-based ERP. The integration between ION and NetSuite is not a one-size-fits-all solution; it requires careful configuration to align with specific business needs and the existing setup of NetSuite.&#x20;

## Recommended System Configuration

High-level goals of the integration:

1. Billing integration with proper 3-way matching functionality
2. AP/AR/GL tracking&#x20;
3. Accurate cost of goods sold (COGS) for make parts (labor and materials)
4. Controlled sales order process

When thinking about how your systems interact it is important to define a business process "swimlane." The swimlane should contain key business processes and in which system you desire them to be performed. Here is a common NetSuite ↔ ION business process swimlane:

<figure>
  <img alt="" />

  <figcaption />
</figure>

In the above example, Business A wishes to do all their factory operations like purchasing, receiving, warehouse management, work order execution, etc... in ION and use NetSuite for sales, employee configuration, vendor onboarding, billing, etc... The two systems need to talk to one another to ensure the right data is available to perform said processes.&#x20;

Once you have a high-level idea of your business processes and where they will be performed it is helpful to understand how and where the systems will interact & the level of detail required to be pushed between systems. Here is an **example** NetSuite configuration diagram based on tried and true business practices & with the simplicity/reliability of the integration in mind:

<figure>
  <img alt="" />

  <figcaption />
</figure>

In the above diagram, ION handles everything from plans to work order execution. Telling NetSuite when it makes purchase orders, consumes material on runs, and scraps material due to quality defects. An (optional) addition to the software stack is a PLM to manage engineering development and part release. The PLM sends parts to both systems, and BOMs to ION, so that activities can happen on the ION side and GL configuration can happen on the NetSuite side. A few additional notes:

1. Sales orders, created in NetSuite, transfer over to create Autoplan inputs
2. Purchase orders are generated from plans in ION. These purchase orders are duplicated on the NetSuite side to add inventory to the system and to enable billing
3. Receiving activities in ION to generate item receipts in NetSuite to enable a 3-way match
4. Billing activities can take place in NetSuite
5. Runs are generated from ION plan items using procedures. Runs can generate workOrder objects in NetSuite (optional) or upon run completion an assemblyBuild record can be generated to put assemblies into NetSuite at cost (labor and materials)
6. When material is scrapped in ION, the material is scrapped in NetSuite&#x20;
7. Both systems have inventory but ION maintains the granular location-based tracking & NetSuite has a bucketed view. Doing so gives finance teams a simplified, yet accurate, view of inventory. Bucketizing the inventory in NetSuite also greatly simplifies the integration between the two systems.

Remember, this is our recommended flow and can be altered based on the preferences of your business. We recommend this flow for its simplicity and efficiency although we have seen other customers be successful with other configurations.

#### Additional NetSuite ↔ ION Integration Workflows

In addition to the recommended swimlane and configuration described above, it is important to note that workflows between ION and NetSuite can be tailored to fit each organization’s operational and financial requirements. Below are three illustrative examples of how the integration can be configured at different levels of complexity. These examples are not exhaustive but provide a sense of how the integration can be adapted to specific business processes.

**1. Basic Workflow (Foundational Integration)**

* **ION** manages purchasing, receiving, and work order execution.
* **NetSuite** manages vendors, billing, and general ledger.
* Purchase Orders initiated in ION are mirrored in NetSuite for financial tracking.
* Receiving in ION automatically creates Item Receipts in NetSuite to enable 3-way matching.
* Inventory is tracked in detail within ION; NetSuite maintains simplified, bucketized balances.
* Billing and invoicing occur exclusively in NetSuite.

*Use case:* Ideal for early-stage teams needing reliable financial reporting and auditability while keeping factory operations simple.

<figure>
  <img alt="" />

  <figcaption />
</figure>

**2. Medium Complexity Workflow (Operational & Financial Alignment)**

* Sales Orders originate in NetSuite and flow into ION as demand signals for Autoplan.
* **ION** executes planning, purchasing, receiving, and production runs.
* Purchase Orders and Receipts in ION sync back to NetSuite to drive AP/AR and vendor performance tracking.
* Work Orders in ION can generate corresponding Work Orders or Assembly Builds in NetSuite, enabling accurate COGS calculations.
* Scrap, rework, and disposition data in ION syncs with NetSuite for visibility into material variances.
* Finance teams rely on NetSuite dashboards for consolidated reporting, while operators use ION for granular traceability.

*Use case:* Companies scaling production who need tighter operational and financial visibility while maintaining efficiency.

<figure>
  <img alt="" />

  <figcaption />
</figure>

**3. Complex Workflow (Full Lifecycle Integration)**

* **PLM → ION + NetSuite:** PLM pushes part data and BOMs to ION and part master data to NetSuite.
* **Sales Orders → Autoplan:** NetSuite sales orders drive Autoplan scheduling in ION.
* **Procurement:** Purchase Orders are generated in ION, synced with NetSuite for vendor invoicing, and tracked bi-directionally.
* **Receiving + Quality:** Receiving in ION creates receipts in NetSuite and optionally triggers quality workflows (inspection, NCRs).
* **Production:** Runs in ION trigger Work Orders in NetSuite; on completion, ION passes assembly build data (materials + labor) to NetSuite for COGS and financial reconciliation.
* **Inventory:** ION manages granular, location-level inventory while NetSuite holds consolidated inventory positions for finance.
* **Disposition + Analytics:** Scrap, rework, and further actions in ION are synced to NetSuite for accurate reporting.

*Use case:* Organizations in regulated industries (aerospace, defense, medical) requiring tight digital thread integration from engineering through production to finance.

<figure>
  <img alt="" />

  <figcaption />
</figure>

Notes on Customization

* These workflows represent **common integration archetypes**. Actual configurations may vary depending on existing ERP setups, compliance requirements, and operational preferences.
* Customers often start with a **basic integration** and evolve toward **medium or complex workflows** as production volume and reporting requirements grow.
* ION’s **flexible, open API** ensures integrations can scale with your business needs, avoiding rigid “one-size-fits-all” approaches.

In the following pages, we outline the details of various flows.


# Purchasing in NetSuite, Receiving in ION
Source: https://docs.firstresonance.io/automate-with-ion/integrations/netsuite/netsuite

Sync purchase orders from NetSuite into ION and send ION receipts back for three-way matching.

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/netsuite/netsuite.md`.
</Note>

Sync purchase orders created, approved, or rejected in NetSuite with [ION Purchases](/manage-supply-chain/purchasing). This integration allows your organization to utilize NetSuite's advanced purchase order approvals, accounting, and finance systems. Once the purchase order is created in ION, receive the inventory from each purchase order and sync the receipts into NetSuite so you can 3 way match.

<Note>
  Use the Setup below for instructions on how to deploy this integration.
</Note>

### Functionality

* Purchases that do not yet exist in ION will be created and a custom attribute called "Netsuite PO Number" will store the NetSuite PO Number associated with the ION Purchase. These will not match so please use this value to compare NetSuite against ION.
  * Purchase order updates like line changes or header changes will be reflected on the ION side
* Suppliers will be created in ION if they do not exist at the time of purchase
* Parts need to be manually maintained in both systems for the ION purchase to be correctly populated. [Warning logs](/automate-with-ion/integrations/deploying-integrations-and-automations) will appear that let you know when parts or suppliers do not exist in ION.
* Receiving: Upon saving a receipt in ion (pressing Save Receipt), an itemReceipt will be created in NetSuite for the purchase order linked to the receipt.&#x20;
* Upon closing a PO in NetSuite, open purchase order lines in ION will be canceled
* Upon deleting a PO in NetSuite the PO will be deleted in ION

#### Purchase Order Statuses

| NetSuite Status                                                               | ION Status |
| ----------------------------------------------------------------------------- | ---------- |
| Pending Supervisor Approval                                                   | Draft      |
| <p>Approved by Supervisor </p><p>Pending Receipt <br />Partially Received</p> | Ordered    |
| <p>Pending Bill, </p><p>Fully Billed</p>                                      | Received   |
| Closed                                                                        | Canceled   |

### Setup

1. Follow the initial setup on the [deploying integrations and automations](/automate-with-ion/integrations/deploying-integrations-and-automations) page to get started.
2. To authenticate with NetSuite, please follow these instructions as an administrator:
   1. Enable SuiteTalk
      * Navigate to **Setup** > **Company** > **Enable Features**
      * Under the **Suite Cloud** tab, ensure that both **REST WEB SERVICES** and **OAUTH 2.0** are checked.
   2. To Create an OAuth 2.0 app with JWT Option
      * Go to Setup > Integration > Manage Integrations > New
      * Give your integration a name and a description.
      * Un-check **TOKEN-BASED AUTHENTICATION** and **TBA: AUTHORIZATION FLOW** under Token-based Authentication
      * Ensure the following are checked under OAuth 2.0
        * **REST WEB SERVICES**
        * **CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT**
      * Take note of and save your **CONSUMER KEY** and **CONSUMER SECRET** as it will not be shown again in Netsuite after this step
   3. Generating the Certificate ID and Private Key for JWT
      * A private key is required for JWT-based authentication. Follow the steps below or refer to the [NetSuite Documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#Related-Topics) for generating or importing a private key.
      * On your machine create a valid certificate abiding by the Netsuite requirements using OpenSSL in a terminal. This will generate two .pem files on your local machine containing key used as the **Private Key for JWT** information and the certificate for the next step
        * Example query: `openssl req -x509 -newkey rsa:4096 -sha256 -keyout auth-key.pem -out auth-cert.pem -nodes -days 730`
        * .pem files generated: auth-key.pem, auth-cert.pem
      * In Netsuite, navigate to Setup > Integration > OAUTH 2.0 CLIENT (M2M) SETUP and select **Create New**
      * Choose the proper **Entity**, **Role**, and select the **Application** created in the previous section.
      * For **Certificate** choose the auth-cert.pem file generated in the previous steps.
      * Press save
      * Once saved, a **Certificate ID** is generated. Save this for the ION integration.
   4. In your ION integration's connection configuration, select the **Netsuite OAuth 2.0 Client Credentials** connection type and enter the following:
      * Token URL: [https://\<ACCOUNT NUMBER>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token](https://6340330-sb1.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token)
      * Certificate ID from OAUTH 2.0 CLIENT (M2M) SETUP
      * Private Key from the auth-key.pem file. copy the entire text including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- text
      * Consumer Key (Client ID) from the Netsuite integration
      * Consumer Secret (Client Secret) from the Netsuite integration<br />
3. For the integration to work successfully you need to create the following custom attributes in your organization settings:
   1. purchase order -- key: "Netsuite PO Number", type: String
   2. purchase order -- key: "Netsuite RecordID", type: String
   3. purchase order line -- key: "Non-receivable", type: Boolean
   4. purchase order line -- key: "ns\_line\_id", type: Number
4. Configure your custom attributes by mapping ION custom attribute name (left) to the attribute name in your Netsuite instance. Below is an **EXAMPLE** of what a mapping can look like. Please reach out to your Netsuite IT administrator or consultant to get a list of attributes to map.

<figure>
  <img alt="" />

  <figcaption />
</figure>

<figure>
  <img alt="" />

  <figcaption />
</figure>

1. Hit **Finish** and take note of the URL for the Purchasing Flow<br />

   <figure><img alt="" /><figcaption><p>Hit the clipboard icon to copy this URL. You will need this in the next step</p></figcaption></figure>
2. Create a custom script by navigating to **Customization > Scripting.** Save the below script locally and use that when creating a new script. The script that will send updates to ION when Purchase Orders in NetSuite are updated and created. Update the URL in the HTTPS POST method to the URL you copied from above.
   1. <mark>WARNING: When you upload the script, ensure that your script name has .js after it or you will get a 'MODULE NOT FOUND' error when saving a purchase order.</mark>

````javascript theme={null}
/**
 * @NApiVersion 2.x
 * @NScriptType UserEventScript
 * @NModuleScope SameAccount 
 */

define(['N/https', 'N/record', 'N/log'], function(https, record, log) {

    function afterSubmit(context) {
        var newRecord = context.newRecord;
        var purchaseOrderId = newRecord.id;
        var eventType = context.type;
        
        var poData = {
            POId: purchaseOrderId,
            eventType: eventType  // 'create', 'edit', or 'delete'
        };
        
        if (eventType === 'delete') {
            // Handle deletion
            poData.message = "Delete this purchase order in ION";
        } else {
            // Handle create or edit
            var poRecord = record.load({
                type: record.Type.PURCHASE_ORDER,
                id: purchaseOrderId,
                isDynamic: true
            });
            
            poData.tranId = poRecord.getValue({ fieldId: 'tranid' });
            poData.date = poRecord.getValue({ fieldId: 'trandate' });
            poData.vendor = poRecord.getValue({ fieldId: 'entity' });
            poData.status = poRecord.getValue({ fieldId: 'status' });
        }

        log.debug("poData", poData);
      
        var payload = JSON.stringify(poData);
        
        var response = https.post({
            url: 'https://hooks.prismatic.io/trigger/SW5zdGFuY2VGbG93Q29uZmlnOjVkM2NkNWFhLWNhMmUtNDY5MC1iOWFlLTdmZmE0NzkxNzQ1MQ==', 
            body: payload,
            headers: {
                'Content-Type': 'application/json'
            }
        });
        
        var responseBody = response.body;
        var responseCode = response.code;
        
        log.debug('HTTP Response', 'Code: ' + responseCode + ', Body: ' + responseBody);
    }
        
    return {
        afterSubmit: afterSubmit
    };
});

```
````

<figure><img alt="" /><figcaption><p>Script Creation in NetSuite</p></figcaption></figure>

6. Hit **Deploy Script** and deploy the script to Purchase Orders. Set the attributes according to the image below.

<figure><img alt="" /><figcaption><p>Script Deployment in NetSuite</p></figcaption></figure>

#### Close/Cancellation Functionality:

How it works: Canceling the ION purchase order moves unreceived lines to unavailable.

To setup the cancellation functionality you will need to create a mass update script that will scan for closed purchase orders daily and will then run an edit/save update on each; triggering the integration to run and cancel the ION PO. Here is what that mass update will look like:

<figure>
  <img alt="" />

  <figcaption />
</figure>


# Procurable
Source: https://docs.firstresonance.io/automate-with-ion/integrations/procurable

Supplier onboarding and compliance through the Procurable partner integration.

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/procurable.md`.
</Note>

**Overview**

Integration with Procurable enables 100% faster supplier onboarding while ensuring compliance with its integrations with Descartes, Climatiq, Docusign and more.

Reach out to [ali@procurable.ai](mailto:ali@procurable.ai) for more information about the integration.


# Quickbooks
Source: https://docs.firstresonance.io/automate-with-ion/integrations/quickbooks

Quickbooks Online (QBO) Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/quickbooks.md`.
</Note>

<Note>
  Use the [Setup](#setup) section for instructions on how to deploy this integration.
</Note>

Sync [ION purchase order](/manage-supply-chain/purchasing) details to Quickbooks where your accounting and finance teams can digest the data.

When a purchase in ION is set to '***Ordered***', this will send changes to Quickbooks. The Quickbooks purchase order document number will match the ION purchase order ID so you can always match purchases across both systems. Below are the data fields that are being sent from ION to QBO.

* Part Number
* Purchase Order Line Unit Cost
* Purchase Order Line Total Cost
* Purchase Order Line Quantity
* Purchase Order Line Description
* Purchase Order Line Expense Account (As Required)
* Purchase Order Line Class (As Required)
* Purchase Order ID
* Purchase Order Fee Name and Value
* Purchase Order Currency
* Purchase Order Shipping Address
* Purchase Order Supplier

#### Inventoried Purchase Order Lines

Inventoried purchase order lines in ION are PO lines that have a part and quantity linked in ION and no expense code is specified. These result in inventory being created that shows up as ***On Order*** and then turns to available after being received.

For inventoried purchase order lines in Quickbooks, items in Quickbooks are matched with ION parts if the name includes the part number and revision with the following format:

* `($partNumber) Rev ($revision)`
* For example, "820412-001 Rev B"

If an item does not exist in QBO, then new inventoried items are automatically generated using the Income Account, Inventory Asset Account, and Expense Account as provided in the integration setup as seen below. Inventoried items are required to populate purchase order lines in Quickbooks that are not expensed/categorized.

<figure><img alt="" /><figcaption><p>Navigate to Products/Services > New > Inventory to See the List of Fields Required to Create an Inventoried Product</p></figcaption></figure>

In addition to being created on the fly when purchase orders are being synced, ION parts are also created in QBO as inventoried items when the ION part is created or updated in ION.

#### Non-Inventoried Purchase Order Lines

If no part is specified on the PO line, then this is a non-inventoried line that will create a categorized purchase line on the Quickbooks purchase order. If no part is associated with an ION PO line, then the default for the expense account is what your organization configures as the inventory expense account as seen below. If an expense code is specified on the PO line, then the categorized expense will utilize that account instead of the inventory expense account. For the scenario where you want to specify the expense account per line item, the expense accounts can be set up in ION as a Select custom attribute as seen below. The various accounts will need to be added to the custom attribute as options that can be selected on the PO line.

<figure>
  <img alt="" />

  <figcaption />
</figure>

#### Fees and Secondary Expenses

For fees on a purchase order in ION, you can configure an Account for Fees as seen below which categorizes all fees (for example, shipping and taxes) according to the account specified.

Please keep in mind that as an organization, you will need to ensure that your expense codes, classes, and suppliers will need to be kept in sync. This integration will handle errors and inform you when data is out of sync (for example, an expense code exists in ION and not in QBO).

## Setup

1. Navigate to the **Integrations** page designated by the two arrows in the bottom left corner of your screen.

   <figure><img alt="" /><figcaption><p>Select Integrations in the Bottom Left Hand Corner</p></figcaption></figure>
2. Select the Quickbooks integration instance from the marketplace, and hit **Configure.**&#x20;
3. Add your ION API credentials. You can find documentation on [API keys](/api-reference/authentication/api-keys) here.
   * **IMPORTANT:** Each API Key is associated with a specific environment, be sure to generate the API keys from the correct environment and configure the automation to the designated environment.

     <figure><img alt="" /><figcaption><p>Set your Environment According to Where the API Keys were Generated</p></figcaption></figure>
4. Connect with Quickbooks and choose the company in Quickbooks Online to deploy this integration. A Quickbooks Online **admin** will be required to download the application.
5. Type in the **NAMES** (not type) of the different accounts in your Quickbooks instance. The AP account will be associated with the purchase order. The Income Account, Inventory Asset Account, and Expense Account will be associated with new inventoried products that need to be created to match parts on purchases in ION. The Account for Fees will categorize all fees on an ION Purchase according to the account you set here.
6. To recap step 5 these are the mandatory fields to fill in:
   1. Accounts Payable
   2. Income Account
   3. Inventory Asset Account
   4. Inventory Expense Account
   5. Account for Fees
7. Finally, type in your **ION Purchase Order Line Attribute** names related to Class and Expense that you have set up in your ION organization settings. Please set up these attributes as ***Select*** types. This must be an exact match, case sensitive.
   1. The class attribute is the name of the PO line attribute in ION that will sync to the Quickbook class attribute.
   2. The expense attribute is the name of the PO line attribute in ION that will sync to the Quickbook Expense account for the line item.
8. Press finish.


# Slack
Source: https://docs.firstresonance.io/automate-with-ion/integrations/slack

Integrate ION notifications with Slack and Gov Slack

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/slack.md`.
</Note>

<Note>
  Skip to the [Set up](#set-up) section for instructions on how to deploy or reconfigure this integration.
</Note>

[https://www.loom.com/share/ae6708a8668547dc9fd7a5dc27950011](https://www.loom.com/share/ae6708a8668547dc9fd7a5dc27950011)

Get notified in [Slack](https://slack.com/) of ION events to close the loop on critical issues and help your factory move faster. Any notification in ION can be output to Slack, allowing teams to bring users back to ION at key moments.

If a user is subscribed to a certain ION object and that object changes state, a user is mentioned in a comment, or assigned a task, ION will notify that user directly in Slack.

For example, if as user is mentioned are mentioned (@Alice) in a comment in ION that will send a direct message to Alice in Slack with a link back to ION where the location that the mention came from.

<figure><img alt="" /><figcaption><p>Examples of notification types within ION</p></figcaption></figure>

## Notification Types&#x20;

ION has many notification types to configure - see the list below or reference the `NotificationTypeEnum` in the [API playground](/api-reference/playground). Your organization can choose to add these below notification types as values to the integration, which will then allow the integration to send them to Slack. See step 6 in the [Set up](#set-up) section on how to configure your organization Slack notifications.

|    Keyword in Slack Integration   |                                                                                                                  Notes                                                                                                                  |
| :-------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|         `approval_request`        | The user is requested to approve an ION object, like a [Purchase](/manage-supply-chain/purchasing), [Standard Step](/build-hardware/procedures/standard-steps) or [Redline](/build-hardware/runs-and-execution/redlines-and-deviations) |
|             `comment`             |                                                                                         Someone commented on an object a user is subscribed to.                                                                                         |
|     `datagrid_value_assigned`     |                                                               The user is requested to review a [datagrid](/build-hardware/procedures/manage-procedure-steps) cell signoff                                                              |
| `issue_approval_request_assigned` |                                                                            The user is assigned to an approval request for an [Issue](/track-quality/issues)                                                                            |
|          `issue_assigned`         |                                                                                        The user is assigned to an [Issue](/track-quality/issues)                                                                                        |
|          `issue_created`          |                                                                            An [Issue](/track-quality/issues) is created on an object subscribed by the user.                                                                            |
|       `issue_status_changed`      |                                                                                             An Issue the user is subscribed to changes state                                                                                            |
|             `mention`             |                                                                                                   The user is @ mentioned in a comment                                                                                                  |
|        `part_kit_assigned`        |                                                                                      The user is assigned to a [Kit](/manage-supply-chain/kitting)                                                                                      |
|     `part_kit_status_changed`     |                                                                              A [Kit](/manage-supply-chain/kitting) the user is subscribed to changes state                                                                              |
|        `procedure_released`       |                                                                             A [Procedure](/build-hardware/procedures) the user is subscribed to is released                                                                             |
|     `procedure_status_changed`    |                                                                            A [Procedure](/build-hardware/procedures) the user is subscribed to changes state                                                                            |
|              `review`             |                                                                                        A user approved a [Procedure](/build-hardware/procedures).                                                                                       |
|          `review_request`         |                                                                                The user is requested to review a [Procedure](/build-hardware/procedures)                                                                                |
|           `run_assigned`          |                                                                                   The user is assigned to a [Run](/build-hardware/runs-and-execution)                                                                                   |
|        `run_step_assigned`        |                                                                              The user is assigned to a step in a [Run](/build-hardware/runs-and-execution)                                                                              |
|         `run_step_changed`        |                                                                        A [Run](/build-hardware/runs-and-execution) step the user is subscribed to changes status                                                                        |
|     `run_step_field_assigned`     |                                                                 The user is requested to review a run step [field](/build-hardware/procedures/step-field-types) signoff                                                                 |
|             `signoff`             |                                                                    The user is requested to sign off a [field](/build-hardware/procedures/step-field-types) in a Run.                                                                   |
|     `purchase_order_assigned`     |                                                                               The user is assigned to a [Purchase Order](/manage-supply-chain/purchasing)                                                                               |

## Set up&#x20;

1. Navigate to the **Integrations** page designated by the two arrows in the bottom lefthand corner of your screen.

   <figure><img alt="" /><figcaption><p>Select Integrations in the Bottom Left Hand Corner</p></figcaption></figure>
2. Select Slack integration instance from the marketplace, and hit **Configure.**&#x20;
3. Hit **Next** and add your API credentials. You can find documentation on [API keys](/api-reference/authentication/api-keys) here.
   * **IMPORTANT:** Each API Key is associated with a specific environment, be sure to generate the API keys from the correct environment and configure the automation to the designated environment.<br />

     <figure><img alt="" /><figcaption><p>Set your Environment According to Where the API Keys were Generated</p></figcaption></figure>
4. Connect with Slack to download the application
5. Scroll down to where you can **Add value.**&#x20;
6. Here, you can type in the notifications you want your organization to receive from the list above or hit the trash button to delete types you do not want to receive. By default, all of the notifications are turned on. Be sure to add them in lowercase!

<figure>
  <img alt="" />

  <figcaption />
</figure>


# Smartsheet
Source: https://docs.firstresonance.io/automate-with-ion/integrations/smartsheet

Smartsheet Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/smartsheet.md`.
</Note>

<Note>
  Use the [Set up](#set-up) section for instructions on how to deploy this integration.
</Note>

Leverage Smartsheet's powerful scheduling and planning capabilities to manage your ION factory operations with ease. Smartsheet can create 'dependencies' between different runs in ION so that changes to dates in one will propagate to down stream dependencies. The integration once deployed will work for your entire organization.

### Bidirectional Sync

The bidirectional sync, is initiated when a new run is created in ION which the integration will automatically propagate the new run information over to Smartsheet. The data transferred from ION to Smartsheet when the ION run is created or updated is seen below. Similarly, when the run start and end dates in Smartsheet are updated, the information is synced over to ION.&#x20;

In order to ensure duplicate rows are not created in Smartsheet, we store the Smartsheet Row ID in a custom attribute in ION as seen in the last step in the Setup section!

[https://www.loom.com/share/2e3ec46b48604181b866a4a32e66e289?sid=6b170c47-954b-448f-930e-2adc7dd23679](https://www.loom.com/share/2e3ec46b48604181b866a4a32e66e289?sid=6b170c47-954b-448f-930e-2adc7dd23679)

## Set up

1. Navigate to the **Integrations** page designated by the two arrows in the bottom lefthand corner of your screen.<br />

   <figure><img alt="" /><figcaption><p>Select Integrations in the Bottom Left Hand Corner</p></figcaption></figure>
2. Select Smartsheet integration instance from the marketplace and hit Configure.
3. Hit **Next** and add your API credentials. You can find documentation on [API keys](/api-reference/authentication/api-keys) here.
   * IMPORTANT: Each API Key is associated with a specific environment, be sure to generate the API keys from the correct environment and configure the automation to the designated environment.<br />

     <figure><img alt="" /><figcaption><p>Set your Environment According to Where the API Keys were Generated</p></figcaption></figure>
4. Click connect and log in to Smartsheet under the Smartsheet OAuth Connection. For Gov Cloud Smartsheets, see [Gov Cloud additional setup](#gov-cloud-additional-setup).
   1. For those using ION Gov with Smartsheet Commercial, please set the following attributes to Commercial and continue following the instructions below. You will not need to perform the Gov Cloud Additional Setup!<br />

      <figure>
        <img alt="" />

        <figcaption />
      </figure>
5. Under the file tab in your Smartsheet sheet of choice, click on Properties. From there, copy and paste the Smartsheet Sheet ID into the blank, and select your preferred timezone.<br />

   <figure><img alt="" /><figcaption><p>Copy the Sheet ID into the Integration Setup</p></figcaption></figure>
6. Use the 'sync dates' toggle to choose whether you want the start and end dates to be synchronized between ION and Smartsheet. If you turn off this sync, ION's due date will be based on Smartsheet's end date. This setup permits ION's start and end dates to be set separately from Smartsheet, yet they can still be measured against the anticipated due date in Smartsheet.
7. Hit Finish to complete the integration configuration.
8. Once you have your integration set up, label the columns (type):
   * Run Title (Text/Numbers)
   * Run ID (Text/Numbers)
   * Status (Dropdown list with the following options):
     * TODO
     * IN PROGRESS
     * REDLINE
     * COMPLETE
     * PARTIAL COMPLETE
     * FAILED
     * HOLD
     * CANCELED
   * Start Date (Date Time)
   * End Date (Date Time)
   * Duration (Duration)
   * Batch (Text/Numbers)
   * Percent Complete (Text/Numbers)
   * Link (Text/Numbers)
9. To set up the Duration column, set it to “= End Date - Start Date”
10. Lock the following columns by right clicking the label and selecting “Lock column”:

    * Run Title
    * Run ID
    * Status
    * Duration
    * Batch
    * Percent Complete
    * Link

    <figure><img alt="" /><figcaption><p>Locking Columns</p></figcaption></figure>
11. Click on the gear on the bottom left of the screen to navigate to the Settings page.
12. Click on Organization and scroll down to Runs. Type in “Smartsheet Row ID” into the Attribute name and select “Number” for the type. Then click Add Attribute. As stated above, this will be used to update existing rows on changes in ION (for example, status) and will be taken care of automatically through the integration once the attribute is setup.<br />

    <figure><img alt="" /><figcaption><p>Setting up ION Custom Attribute Required for the Integration</p></figcaption></figure>

### Gov Cloud Additional Setup

1. In addition to the above, you will have the option to input a Smartsheet Client ID and Secret if you use Smartsheet Gov Cloud. The below instructions detail where to capture and input those attributes.<br />

   <figure><img alt="" /><figcaption><p>Input the Client ID and Secret that is Generated Below</p></figcaption></figure>

2. Navigate to Account > Developer Tools. If you do not have access to this, the Smartsheet team can grant you access to developer tools.<br />

   <div><figure><img alt="" /><figcaption><p>Developer Tools</p></figcaption></figure></div>

3. Select Create New App and input the details as shown below. After hitting save, an ID and Secret will be generated which you can use to input into the above dialog on step 4 above.<br />

   <figure><img alt="" /><figcaption><p>App instructions</p></figcaption></figure>

4. Once the ID and Secret are inputted, hit **Connect** to verify the connection with Smartsheet, and then finish the rest of the configuration and hit **Finish**.

### Error Handling

Error 1:

Execution of 'Add Row' failed with error: \{ "message": "Cannot destructure property 'id' of 'i\[t]' as it is undefined.", "name": "TypeError", "stack": "TypeError: Cannot destructure property 'id' of 'i\[t]' as ...}

* When you see this error it is likely that your smartsheet columns are named incorrectly.&#x20;

Solution:

* Please make sure your column names match exactly to what you see above in the configuration section. You can also create a new sheet and let the integration create all columns for you.


# SOLIDWORKS
Source: https://docs.firstresonance.io/automate-with-ion/integrations/solidworks

SOLIDWORKS Pro PDM Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/solidworks.md`.
</Note>

<Note>
  We've partnered with Hawk Ridge Systems to offer a SOLIDWORKS PDM integration **on request**. Please contact your First Resonance representative or [support@firstresonance.io](mailto:support@firstresonance.io) for pricing and deployment details.
</Note>

The integration syncs part (part number, revision, description, thumbnail) and BOM information from PDM to ION. This integration applies only to syncing assembly documents from SOLIDWORKS PDM to ION. All the part documents in that assembly will be brought over with the integration.

[Download file](/images/automate-with-ion/solidworks-workflow-ion-task.mp4)

## Setup instructions

1. Create an API key using the `createAPIKey` mutation shown in the [API keys](/api-reference/authentication/api-keys) documentation (recommend testing this integration out in the sandbox environment first)
2. Add *part* custom attributes to your ION instance. These will get populated by the integration and are used for updating thumbnails. These should both be number types.
   1. PDMID
   2. PDMVERSION
3. Download the .cex file for the add-in
   * In Windows 7 or newer, make sure to right-click on the CEX file, go to Properties and check the unblock checkbox at the bottom of the dialog. Confirm this operation by clicking on Apply, then OK. This will unblock the CEX and its content.
4. Go to SOLIDWORKS PDM Admin console and add the add-in to your vault
5. Right click on the add-in and go to "Web API settings":
   * populate an API Endpoint that should look like: https\://\<ION Endpoints>/graphql
   * populate an Authentication endpoint that should follow this format https\://\<AUTH\_SERVER>/auth/realms/api-keys/protocol/openid-connect/token
     * [see here](/api-reference/authentication) for ION API and authentication endpoint options
   * populate the `clientId` and `clientSecret` from your ION API key
6. Right click on the add-in again and go to "Add-in settings":
   * set a SOLIDWORKS Document Manager API Key after requesting with [these instructions](https://support.hawkridgesys.com/hc/en-us/articles/360037482172-Requesting-A-Document-Manager-API-License-Key). This is required in order to get access to thumbnails
   * configure property mappings for part number, description, and revision based on how they are set in PDM
   * choose a BOM template. Make sure your BOM template has a \<Reference Count> column for quantity in ION. To do that, login to the your vault from the Administration tool, right-click on the BOM template under "Bill of Materials" and then click "Open".
7. Right click on the add-in one final time and go to "Workflow settings"
   * Add a transition that you'd like to tie this integration to so that it will run every time a document transitions to this state
8. Conduct your normal workflow and you should see a pop-up when information is being synced over to ION .
   * To make sure the thumbnails sync, the assembly and its immediate children must be locally cached. This is generally done by getting the latest version of the assembly and its children.

<img alt="" />

<img alt="" />

## Loading new versions

To upgrade to a new version of the `.cex` file:

1. Download the new `.cex` file and install the new version of the add-in (it will replace the existing add-in).
2. Run the following commands in the command prompt to kill the task and start it new:

```
taskkill /f /im explorer.exe
taskkill /f /im edmserver.exe 
start explorer
```

The settings that you used in the previous version will still be there so no need to re-enter that information.


# Teamcenter
Source: https://docs.firstresonance.io/automate-with-ion/integrations/teamcenter

Teamcenter PLM Integration

<Note>
  This page was auto-migrated from the legacy ION manual. Some images and cross-links may need follow-up cleanup. Original: `_legacy-export/integrations/teamcenter.md`.
</Note>

Their are multiple options for integrating Teamcenter and ION.

1. For an out of the box integration, please refer to our partners [Violet Labs Teamcenter integration.](https://docs.violetlabs.com/apps/t/teamcenter)
2. Alternatively, work with the First Resonance team and your Teamcenter implementers to build an integration specific to your instance.


# ION Actions
Source: https://docs.firstresonance.io/automate-with-ion/ion-actions

Validation rules that allow, block, or warn on a change when an ION event fires, and how to write them.

**ION Actions** are validation rules you write to enforce your own business logic in ION. An action is triggered by an event, such as creating an issue, completing a run step, or changing a procedure's status. When triggered, it reads the data involved and can allow the change, block it with a message, or surface a non-blocking warning.

Actions run inside the change itself: a blocked change is rejected before it saves, so the rule is enforced whether the change comes from the ION UI or the API. That makes actions the right tool for hard requirements, such as required fields on creation, approval gates, and status-transition guards. For alerting people after something happens, use [notifications](/automate-with-ion/notifications/subscribe-to-notifications) instead.

You create and edit actions on the **Actions** page in ION, which has a built-in editor, or through the GraphQL API for programmatic deployment. For the create, edit, enable, and delete flows, and for enabling actions for your organization, see [Manage actions](/automate-with-ion/ion-actions/manage-actions).

## Action anatomy

An action is defined by these parts. Title, target, and event are form fields; context and code are tabs in the built-in editor.

* **Title**: identifies the action and appears in its toast notification and the audit log.
* **Target**: the entity to watch, such as **Run**, **Issue**, or **Procedure**, chosen from a dropdown. See [Action targets](/automate-with-ion/ion-actions/action-targets) for the full list.
* **Event** (labeled **Event Type** in the editor): when the action runs against the target, one of **Create**, **Update**, or **Delete**.
* **Context**: a GraphQL query for the data your code needs, such as the target's fields, related records, and custom attributes. Your code reads from the result.
* **Code**: a Python script that runs when the event fires. It reads the context and decides the outcome: raise `ValidationError` to block the change with a message, raise `ValidationWarning` to warn without blocking, or do neither to allow it. The code is read-only. It can't write data or call external systems.

## Context query

The context is a GraphQL query that fetches the data your code evaluates. ION runs it against the entity that triggered the action and passes the result to your code.

```graphql theme={null}
{
  run(id: $id) {
    id
    status
    Attributes { key value }
  }
}
```

Rules for the query:

* **One entity, plus an optional `me`.** Query exactly one top-level entity, matching your target. You can add `me { ... }` as a second top-level selection for data about the acting user.
* **Use the singular camelCase name** of the target as the query name, such as `run` for the `runs` target or `runStep` for `run_steps`. See [Action targets](/automate-with-ion/ion-actions/action-targets) for the name of every target. The fields each entity exposes are what GraphiQL introspection returns for it in your environment.
* **`$id` is resolved for you.** ION substitutes the triggering entity's ID, so `$id` is a convention you don't fill in. Compound-key entities take their composite ID parameters instead; see [Action targets](/automate-with-ion/ion-actions/action-targets).
* **No `edges` and one operation.** Don't use the connection or `edges` pattern, and define only one query.

### Custom attributes

Custom attributes come back as a list under `Attributes`. Request all of them with `Attributes { key value }`, or filter to one with `Attributes(filters: {key: {eq: "Pedigree"}})`. Each attribute object exposes these fields:

* `key`: the attribute name, such as "Pedigree" or "Release Date".
* `value`: the value, which can be a string, number, date, boolean, or select value.
* `id`: the attribute record ID.
* `type`: the attribute type.
* `allowedIonType`: the linked entity type, when the attribute links to one.
* `options`: the allowed values for a select attribute.

## Data your code receives

Your code gets one `context` dictionary. It always holds the entity you queried (under the target's singular camelCase key), a `changes` object, and a `currentUser` object. It also holds `me` when your query requested it.

```python theme={null}
context = {
    "run": { ... },          # the entity you queried; shape matches your query
    "changes": { ... },      # what this event modified
    "currentUser": { ... },  # who performed the change
}
```

### Changes object

`changes` describes what the event modified. It's keyed by the camel-cased table name, then by field, and each entry holds `{ "new": ..., "old": ... }`. The old value is `null` on a create and the new value is `null` on a delete. Field names are snake-cased, and custom-attribute tables are keyed by the attribute's name.

A `changes` object for a procedure update can look like this:

```json theme={null}
{
  "procedures": {
    "status": { "new": "released", "old": "in_review" }
  }
}
```

Other targets and event types produce different keys, one per table the event touched. A few examples:

<AccordionGroup>
  <Accordion title="Issue update">
    ```json theme={null}
    {
      "issues": {
        "status": { "new": "in_progress", "old": "pending" },
        "must_close_by_run_step_id": { "new": 2116, "old": null }
      },
      "issuesAttributes": {
        "Issue Origin": { "new": "Engineering", "old": null }
      },
      "issueApprovalRequests": {
        "status": { "new": "approved", "old": "pending" }
      }
    }
    ```
  </Accordion>

  <Accordion title="Inventory update">
    ```json theme={null}
    {
      "partsInventory": {
        "status": { "new": "unavailable", "old": "available" },
        "lot_number": { "new": "Lot Test 123", "old": null },
        "location_id": { "new": 19, "old": 67 }
      }
    }
    ```
  </Accordion>

  <Accordion title="Part kit update">
    ```json theme={null}
    {
      "partsKits": {
        "assigned_team_id": { "new": 2, "old": null },
        "delivery_location_id": { "new": 19, "old": null }
      },
      "partKitAttributes": {
        "Date Kitted": { "new": "2025-09-08T07:00:00", "old": null }
      }
    }
    ```
  </Accordion>

  <Accordion title="Run create">
    ```json theme={null}
    {
      "runs": {},
      "runsAttributes": {
        "Department": { "new": "Assembly", "old": null }
      },
      "runSteps": {},
      "buildRequirements": {}
    }
    ```
  </Accordion>
</AccordionGroup>

Use `changes` to branch on what actually changed rather than the final state. For example, to act only when a procedure's status changes to released:

```python theme={null}
procedure_changes = context.get('changes', {}).get('procedures', {})
if procedure_changes.get('status', {}).get('new') == 'released':
    # the procedure was just released; run your logic here
```

Custom attributes appear under the entity's `*Attributes` key, such as `partsInventoriesAttributes` or `runsAttributes`, keyed by the attribute's name.

A few things to know about `changes`:

* It's operation-wide. It holds changes for every entity the operation touched, not only your action's target.
* On a create or delete of the target itself, the target's own entry is an empty `{}`. Custom attributes saved during that same operation still carry their new values.
* When one operation changes several records of the same type, `changes` reports one set of values for that type.
* A custom attribute saved as blank, zero, or `false` is left out of `changes` entirely, so an empty value and an untouched one look the same.
* `step_id`, `run_step_id`, and a redline's `initial_state` and `final_state` never appear in it.

<Warning>
  `changes` reports only what the current operation modified. A missing or empty key means that operation didn't touch the field, not that the entity has no value for it. To confirm a record holds a value, request the field in your context query and read it off the entity instead.
</Warning>

To require that a run carries a Department custom attribute, request the attributes in your context query and check the entity:

```python theme={null}
attributes = {a['key']: a['value'] for a in context.get('run', {}).get('Attributes', [])}
if not attributes.get('Department'):
    raise ValidationError('Enter a Department before creating this run.')
```

Reading the same check from `changes` would let a run through whenever the operation left the attribute untouched, such as an edit that only moves the due date.

### Current user

`currentUser` is always present and describes who performed the change:

```python theme={null}
{
    "email": "jane.doe@company.com",
    "roles": ["admin", "engineer"],
    "teams": ["Assembly", "QA"]
}
```

Branch on `roles` to gate a change by permission:

```python theme={null}
if "admin" not in context.get("currentUser", {}).get("roles", []):
    raise ValidationError()
```

## Writing action code

Action code is the body of a Python function that receives `context`. You don't write the `def` line: ION wraps your code and passes in the context. Raise `ValidationError` to block the change, raise `ValidationWarning` to warn, or return without raising to allow it.

```python theme={null}
if context["run"]["status"] == "COMPLETE":
    raise ValidationError("Cannot modify a completed run")
```

The code runs in a sandboxed Python 3.6 environment:

* **Python 3.6 syntax only.** No walrus operator (`:=`), no f-string debug (`f"{x=}"`), no `match` statements, and no `X | Y` type unions.
* **No imports, no I/O.** You can't import modules or reach the file system, network, or database. `print()` output is discarded.
* **You can** use the built-ins (`len`, `any`, `all`, `sum`, `next`, `set`, and so on), comprehensions, `try`/`except`, and local helper functions.
* **A computation budget applies.** A very long computation is stopped with a user-visible error, so avoid deep loops over large collections.

The built-in editor checks these constraints before an action goes live. An action that fails validation is saved but set to an `error` status and doesn't run until you fix it.

### Blocking and warning

Raising `ValidationError` blocks the change; raising `ValidationWarning` lets it save and shows a non-blocking message. Use a validation action for hard requirements, such as a missing required field or an approval gate, and a warning action for soft ones, such as a skipped recommended step. An action raises one or the other, never both.

You can pass a message to either. ION shows it to the user as `[Rule {id}] {title}` followed by your message; with no message, the user sees just `[Rule {id}] {title}`.

<Warning>
  The message must be the first argument and a plain string literal. ION injects the action's ID and title automatically, and it silently drops a message built from an f-string, a variable, or any other expression, so the user sees only the title. Anything after the first argument, and any keyword argument, is dropped the same way even when the first argument is kept. This prevents dynamic strings from leaking internal data through a user-visible message.
</Warning>

```python theme={null}
# Preserved: a string literal
raise ValidationError("Run must have a QMS code before creation")

# Dropped: the custom message never reaches the user
msg = "Run must have a QMS code"
raise ValidationError(msg)
raise ValidationError(f"Run {run_id} is missing a QMS code")

# Partly dropped: the literal survives, the second argument does not
raise ValidationError("Run must have a QMS code: ", run_id)
```

## How multiple actions combine

When an event and target combination matches several actions, those actions are squashed together at run time. Squashing merges both the code and the requested context so every triggered action runs with the data it needs. They run in sequence in an order you don't control, with validation actions before warning actions so a block takes precedence, and they share one merged context. Keep each action self-contained.

<Note>
  When two actions on the same target and event filter the same field differently in their context (for example, both query `Attributes(filters: {...})` with different keys), the merged query fails. Give each filtered field an alias, such as `deptAttr: Attributes(filters: {key: {eq: "Department"}})`, and reference the alias in your code.
</Note>

For example, two actions are both configured with event `CREATE` and target `RUNS`:

<Frame>
  <img alt="ION Action 535 configuration: on create runs, selects dueDate in context and ensures it is filled out." />
</Frame>

<Frame>
  <img alt="ION Action 240 configuration: on create runs, selects procedureId in context and ensures it is filled out." />
</Frame>

When a run is created, both actions trigger and are squashed into a single execution flow, shown in the execution log:

<Frame>
  <img alt="Execution log code for creating a run with actions 535 and 240 squashed together." />
</Frame>

The squashed code includes a few standard pieces:

* **`ValidationError`**: a class defined in every execution log. If an action raises it, the action's ID and name are injected into the code so it's clear which action caused the failure.
* **`run_rule`**: wraps each triggered action into one executable unit and runs them in sequence, with validation actions before warning actions so a block takes precedence.
* **`ctx`**: the combined context for all squashed actions. Each action declares the fields it needs, and squashing merges them into one context object.

In the example, action 535 requests `dueDate` and action 240 requests `procedureId`, so the resulting context contains both:

<Frame>
  <img alt="Execution context combining dueDate and procedureId requested by both actions." />
</Frame>

## Common patterns

* **Read defensively.** A chained lookup like `context["run"]["procedure"]["type"]` throws if any level is `None`. Read one level at a time with a fallback: `context.get("run", {}).get("procedure", {}).get("type")`.
* **Skip early.** Return when the action doesn't apply, so the rest of the code only handles the relevant case.

  ```python theme={null}
  if context.get("run", {}).get("procedure", {}).get("type") != "BUILD":
      return
  ```
* **Detect a status change.** Compare the new and old values in `changes` rather than the final state.

  ```python theme={null}
  changes = context.get("changes", {}).get("runSteps", {}).get("status", {})
  if changes.get("new") == "canceled" and changes.get("old") != "canceled":
      raise ValidationError()
  ```
* **Find an attribute in a list.** Attributes come back as a list of `{key, value}`. Pull one with `next` and a default.

  ```python theme={null}
  pedigree = next(
      (attr.get("value") for attr in context.get("run", {}).get("Attributes", [])
       if attr.get("key") == "Pedigree"),
      None,
  )
  ```

## Seeing what an action did

Every time an action fires, ION records the run in its execution logs: what triggered it, the data it read, and the outcome. Use the logs to debug an action that blocks unexpectedly or never fires. See [View action execution logs](/automate-with-ion/ion-actions/view-action-execution-logs).

## Troubleshooting

<AccordionGroup>
  <Accordion title="An action never fires">
    Confirm the action is enabled and its status is active, that the target matches the entity being changed, and that the event matches the operation. Actions must also be enabled for the organization; see [Manage actions](/automate-with-ion/ion-actions/manage-actions#before-you-start). A custom-attribute change fires an `update` on the parent entity, not on a separate attribute target.
  </Accordion>

  <Accordion title="An action errors instead of running">
    Check the action's [execution logs](/automate-with-ion/ion-actions/view-action-execution-logs) for the error. Common causes are a context query that requests a field the entity doesn't have, or a Python syntax error in the code. An action with either problem is saved but sits in an `error` status and doesn't run until you fix it.
  </Accordion>

  <Accordion title="A custom message doesn't appear">
    `ValidationError` keeps only a plain string-literal message. A message built from an f-string, a variable, or any other expression is dropped, and the user sees just `[Rule {id}] {title}`. Pass a literal string.
  </Accordion>

  <Accordion title="Context data is missing">
    The context query must request every field your code reads. Field names are case-sensitive, so `partNumber` works and `partnumber` doesn't. Custom attributes use a capital `Attributes`. On a delete event, the query runs against the pre-deletion state.
  </Accordion>

  <Accordion title="An action stops with a fuel-limit error">
    The action exceeded its computation budget. Simplify the logic, filter attributes in the query with `Attributes(filters: {key: {eq: "..."}})` instead of fetching all of them and filtering in code, or split the work into several smaller actions.
  </Accordion>

  <Accordion title="A custom attribute change isn't detected">
    Attribute changes appear under the entity's `*Attributes` key in `changes`, such as `partsInventoriesAttributes` or `runsAttributes`. They fire an `update` on the parent entity and are keyed by the attribute's name, not a column name.
  </Accordion>
</AccordionGroup>

## Starting points

Most orgs start with a small set of high-value rules, such as requiring a defect type before an issue can save or blocking run closure while the aBOM is incomplete. The [example actions](/automate-with-ion/ion-actions/example-actions) collect working configurations you can copy and adapt.

## Related

* [Manage actions](/automate-with-ion/ion-actions/manage-actions)
* [Action targets](/automate-with-ion/ion-actions/action-targets)
* [Example actions](/automate-with-ion/ion-actions/example-actions)
* [View action execution logs](/automate-with-ion/ion-actions/view-action-execution-logs)


# Action targets
Source: https://docs.firstresonance.io/automate-with-ion/ion-actions/action-targets

The entity types an action can watch, with their context query names and changes keys.

An action's `target` field names the entity type whose create, update, or delete events trigger the action. This page lists the targets grouped by domain, then maps each target to the singular query name you use in a context query and the key that entity's changes appear under. It covers commonly-used entities and is not exhaustive. For how targets fit into an action's other fields, see the [ION Actions overview](/automate-with-ion/ion-actions).

<Note>
  The target and field catalogs here reflect commonly-used entities. The authoritative, current list is what the Actions editor dropdown offers and what GraphiQL introspection returns in your environment.
</Note>

## Available targets

### Core manufacturing

| Target                       | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `runs`                       | Work order / manufacturing run instances      |
| `run_steps`                  | Individual steps within a run                 |
| `run_steps_fields`           | Field values within run steps                 |
| `run_step_sessions`          | User check-in/check-out sessions on run steps |
| `run_step_field_validations` | Field validation configurations on run steps  |
| `run_batches`                | Batches grouping related runs                 |
| `run_steps_dags`             | Run step dependency graphs                    |

### Parts and inventory

| Target                 | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `parts`                | Part/component definitions                      |
| `parts_inventory`      | Physical inventory records (serial/lot tracked) |
| `parts_kits`           | Kitting containers for parts                    |
| `part_kit_items`       | Line items within a part kit                    |
| `part_kit_inventories` | Inventory assigned to kit items                 |
| `part_subtypes`        | Custom part classification types                |
| `part_procedures`      | Links between parts and their procedures        |

### Procedures and steps

| Target                   | Description                         |
| ------------------------ | ----------------------------------- |
| `procedures`             | Manufacturing procedure definitions |
| `steps`                  | Steps within a procedure definition |
| `steps_fields`           | Field definitions within steps      |
| `steps_dags`             | Step dependency graphs              |
| `step_part_requirements` | Part requirements per step          |
| `step_field_validations` | Field validation actions on steps   |

### Bill of materials

| Target                                    | Description                                                   |
| ----------------------------------------- | ------------------------------------------------------------- |
| `mboms`                                   | Manufacturing Bills of Materials                              |
| `mbom_item`                               | Line items in an mBOM                                         |
| `mbom_item_reference_designators`         | Reference designators for mBOM items                          |
| `mbom_substitute`                         | Approved substitute parts for mBOM items                      |
| `build_requirements`                      | Requirements generated from mBOMs for runs                    |
| `build_requirement_reference_designators` | Reference designators on build requirements                   |
| `build_requirement_substitutes`           | Substitutes on build requirements                             |
| `abom_installations`                      | As-built installations (tracking what was actually installed) |

### Issues and quality

| Target                    | Description                             |
| ------------------------- | --------------------------------------- |
| `issues`                  | Non-conformance / quality issue records |
| `issue_disposition_types` | Types of issue dispositions             |
| `issue_part_inventories`  | Inventory linked to issues              |
| `further_actions`         | Follow-up actions on issues             |

### Procurement

| Target                 | Description                        |
| ---------------------- | ---------------------------------- |
| `purchase_orders`      | Purchase order headers             |
| `purchase_order_lines` | Line items on purchase orders      |
| `purchase_order_fees`  | Fees/charges on purchase orders    |
| `receipts`             | Receiving records                  |
| `receipt_items`        | Individual items received          |
| `suppliers`            | Vendor/supplier records            |
| `supplier_parts`       | Supplier-specific part information |

### Approvals

| Target                                                                  | Description                     |
| ----------------------------------------------------------------------- | ------------------------------- |
| `approval_levels`                                                       | Approval gate configurations    |
| `procedure_approvals` / `procedure_approval_requests`                   | Procedure review approvals      |
| `step_approvals` / `step_approval_requests`                             | Step-level approvals            |
| `step_role_based_approvals` / `step_role_based_approval_requests`       | Role-based step approvals       |
| `issue_approvals` / `issue_approval_requests`                           | Issue review approvals          |
| `purchase_order_approvals` / `purchase_order_approval_requests`         | PO approvals                    |
| `purchase_order_approval_levels`                                        | PO approval gate configurations |
| `mbom_approvals` / `mbom_approval_requests`                             | mBOM approvals                  |
| `redline_approvals` / `redline_approval_requests`                       | Redline approvals               |
| `redline_role_based_approvals` / `redline_role_based_approval_requests` | Role-based redline approvals    |
| `further_action_approvals` / `further_action_approval_requests`         | Further action approvals        |

### Redlines

| Target     | Description                            |
| ---------- | -------------------------------------- |
| `redlines` | In-process change records on run steps |

### Planning

| Target              | Description                         |
| ------------------- | ----------------------------------- |
| `plans`             | Production planning records         |
| `plan_items`        | Items within a plan                 |
| `plan_inputs`       | Input parameters for plans          |
| `plan_constraints`  | Constraints on plans                |
| `plan_reservations` | Inventory reservations for plans    |
| `mrp_jobs`          | Material Requirements Planning jobs |

### Locations and organization

| Target              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `locations`         | Physical locations (buildings, rooms, stations) |
| `location_subtypes` | Custom location classifications                 |

### Users and teams

| Target              | Description                  |
| ------------------- | ---------------------------- |
| `users`             | User accounts                |
| `roles`             | Role definitions             |
| `teams`             | Team definitions             |
| `permission_groups` | Permission group assignments |

### Other entities

| Target                        | Description                     |
| ----------------------------- | ------------------------------- |
| `labels`                      | Tagging labels                  |
| `comments`                    | Comments on various entities    |
| `contacts`                    | Contact information records     |
| `currencies`                  | Currency definitions            |
| `units_of_measurements`       | Unit of measure definitions     |
| `requirements`                | Requirements tracking           |
| `entities_requirements`       | Entity-to-requirement links     |
| `reviews` / `review_requests` | Review workflow records         |
| `invites`                     | User invitations                |
| `intent_options`              | Intent/purpose classifications  |
| `validation_functions`        | Validation function definitions |
| `import_jobs`                 | Data import jobs                |

### Barcodes

| Target                                                      | Description            |
| ----------------------------------------------------------- | ---------------------- |
| `barcode_labels` / `barcode_patterns` / `barcode_templates` | Barcode configurations |
| `barcode_print_requests` / `barcode_scan_requests`          | Barcode operations     |

### Webhooks and notifications

| Target                                                                               | Description            |
| ------------------------------------------------------------------------------------ | ---------------------- |
| `webhook_events` / `webhook_headers` / `webhook_receivers` / `webhook_subscriptions` | Webhook configurations |
| `user_notifications` / `user_subscriptions`                                          | Notification settings  |

### Datagrid

| Target                               | Description                       |
| ------------------------------------ | --------------------------------- |
| `datagrid_columns` / `datagrid_rows` | Datagrid data (step field tables) |

## Context query names

A context query uses the singular camelCase form of the target as its top-level query name. The entity's changes appear in the `changes` dict under its own key. This table maps each target to both.

| Target                    | Context query name     | Changes key             |
| ------------------------- | ---------------------- | ----------------------- |
| `runs`                    | `run`                  | `runs`                  |
| `run_steps`               | `runStep`              | `runSteps`              |
| `parts`                   | `part`                 | `parts`                 |
| `parts_inventory`         | `partInventory`        | `partsInventory`        |
| `issues`                  | `issue`                | `issues`                |
| `purchase_orders`         | `purchaseOrder`        | `purchaseOrders`        |
| `purchase_order_lines`    | `purchaseOrderLine`    | `purchaseOrderLines`    |
| `procedures`              | `procedure`            | `procedures`            |
| `steps`                   | `step`                 | `steps`                 |
| `locations`               | `location`             | `locations`             |
| `receipts`                | `receipt`              | `receipts`              |
| `receipt_items`           | `receiptItem`          | `receiptItems`          |
| `redlines`                | `redline`              | `redlines`              |
| `parts_kits`              | `partKit`              | `partsKits`             |
| `part_kit_inventories`    | `partKitInventory`     | `partKitInventories`    |
| `abom_installations`      | `abomInstallation`     | `abomInstallations`     |
| `run_step_sessions`       | `session`              | `runStepSessions`       |
| `issue_approval_requests` | `issueApprovalRequest` | `issueApprovalRequests` |

## Composite-ID (joiner) entities

Some entities have compound primary keys instead of a single `$id`. For these, pass the composite ID parameters the entity expects.

The `abomInstallation` joiner takes a build requirement ID and a part inventory ID:

```graphql theme={null}
{
  abomInstallation(buildRequirementId: $buildRequirementId, partInventoryId: $partInventoryId) {
    quantity
    buildRequirement { quantity }
  }
}
```

The `partKitInventory` joiner takes a part inventory ID and a part kit item ID:

```graphql theme={null}
{
  partKitInventory(partInventoryId: $partInventoryId, partKitItemId: $partKitItemId) {
    partInventory { serialNumber }
  }
}
```

## Related

* [ION Actions overview](/automate-with-ion/ion-actions)


# Example actions
Source: https://docs.firstresonance.io/automate-with-ion/ion-actions/example-actions

Worked ION Action configurations for common validations across quality, procedures, purchases, and receipts.

Read [Create an action](/automate-with-ion/ion-actions/manage-actions#create-an-action) before working through these examples. Each one below gives the field values for one ION Action: its title, target, and event, followed by the context query it reads and the code it runs.

## Block a status transition based on a related collection

Stops an issue from moving to In Review while any of its redlines sit on a step that isn't complete or canceled. The technique: read a related collection from the context and require every record in it to be in an acceptable state.

| Field  | Value                                             |
| ------ | ------------------------------------------------- |
| Title  | Open redlines prevent moving issue into In Review |
| Target | `ISSUE`                                           |
| Event  | `UPDATE`                                          |

**Context**

```graphql theme={null}
{
  issue(id: $id) {
    title
    status
    redlines { id step { status } }
  }
}
```

**Code**

```python theme={null}
if (
    context.get('issue', {}).get('status') == 'IN_REVIEW'
    and context.get('issue', {}).get('redlines') is not None
    and not all(
        redline.get('step', {}).get('status') in ['COMPLETE', 'CANCELED']
        for redline in context.get('issue', {}).get('redlines')
    )
):
    raise ValidationError()
```

## Restrict an action to specific roles

Blocks moving an issue back to In Review from a resolved state unless the acting user holds a quality role. The technique: branch on the acting user's roles from `currentUser`, and read the prior value from `changes` to detect the reopen.

| Field  | Value                                  |
| ------ | -------------------------------------- |
| Title  | No permission to reopen a closed issue |
| Target | `ISSUE`                                |
| Event  | `UPDATE`                               |

**Context**

```graphql theme={null}
{
  issue(id: $id) {
    title
    status
  }
}
```

**Code**

```python theme={null}
allowed_roles = {'Quality Engineer', 'Quality Inspector', 'Reliability Engineer', 'admin'}
if (
    context.get('issue', {}).get('status') == 'IN_REVIEW'
    and context.get('changes', {}).get('issues', {}).get('status', {}).get('old') == 'resolved'
    and not set(context.get('currentUser', {}).get('roles', [])).intersection(allowed_roles)
):
    raise ValidationError()
```

## Check a custom attribute

Stops a part from being added to a kit when its `On CAPA?` attribute is set. The technique: scan a list of `{ key, value }` attributes on a related object for a specific key.

| Field  | Value                       |
| ------ | --------------------------- |
| Title  | Cannot add CAPA part to kit |
| Target | `PARTKITITEM`               |
| Event  | `CREATE`                    |

**Context**

```graphql theme={null}
{
  partKitItem(id: $id) {
    part {
      attributes { key value }
    }
  }
}
```

**Code**

```python theme={null}
if any(
    attr.get('key') == 'On CAPA?' and attr.get('value') is not None
    for attr in context.get('partKitItem', {}).get('part', {}).get('attributes', [])
):
    raise ValidationError()
```

## Require a field on every item in a collection

Blocks moving a procedure to In Review when any step has no upstream or downstream dependency. The technique: gate on a status change read from `changes`, then iterate the object's child collection and require a field on each.

| Field  | Value                          |
| ------ | ------------------------------ |
| Title  | Check if step has dependencies |
| Target | `PROCEDURE`                    |
| Event  | `UPDATE`                       |

**Context**

```graphql theme={null}
{
  procedure(id: $id) {
    id
    steps {
      upstreamStepIds
      downstreamStepIds
    }
  }
}
```

**Code**

```python theme={null}
status_change = context.get('changes', {}).get('procedures', {}).get('status', {})
if status_change.get('new') == 'in_review' and any(
    not (step.get('upstreamStepIds') or step.get('downstreamStepIds'))
    for step in context.get('procedure', {}).get('steps', [])
):
    raise ValidationError()
```

## Match records across a nested collection

For a Build procedure, blocks the move to In Review until reviewers from the Responsible Engineer, Production, and Mission Assurance teams have been added. The technique: flatten a nested collection (reviewers, then their teams) and confirm every required value is present.

| Field  | Value                                          |
| ------ | ---------------------------------------------- |
| Title  | Procedure requires the correct teams to review |
| Target | `PROCEDURE`                                    |
| Event  | `UPDATE`                                       |

**Context**

```graphql theme={null}
{
  procedure(id: $id) {
    attributes { key value }
    reviewRequests { id status reviewer { id teams { name } roles { name } } }
  }
}
```

**Code**

```python theme={null}
status_change = context.get('changes', {}).get('procedures', {}).get('status', {})
procedure = context.get('procedure', {})
is_build = any(
    attr.get('key') == 'Procedure Type' and attr.get('value') == 'Build'
    for attr in procedure.get('attributes', [])
)
required_teams = ['Responsible Engineer', 'Production', 'Mission Assurance']
reviewer_team_names = [
    team.get('name', '')
    for review in procedure.get('reviewRequests', [])
    for team in review.get('reviewer', {}).get('teams', [])
]
has_required = all(
    any(required in name for name in reviewer_team_names)
    for required in required_teams
)
if status_change.get('new') == 'in_review' and is_build and not has_required:
    raise ValidationError()
```

## Require a field before a status change

Blocks a purchase order line from moving to Requested when it has no need date. The technique: gate on a status change read from `changes`, then require a scalar field on the object.

| Field  | Value                                     |
| ------ | ----------------------------------------- |
| Title  | Purchase line items must have a need date |
| Target | `PURCHASEORDERLINE`                       |
| Event  | `UPDATE`                                  |

**Context**

```graphql theme={null}
{
  purchaseOrderLine(id: $id) {
    id
    needDate
  }
}
```

**Code**

```python theme={null}
status_change = context.get('changes', {}).get('purchaseOrderLines', {}).get('status', {})
if (
    status_change.get('new') == 'requested'
    and context.get('purchaseOrderLine', {}).get('needDate') is None
):
    raise ValidationError()
```

<Note>
  To enforce purchase order approval levels, use the built-in [purchase order approvals](/manage-supply-chain/purchasing/approve-purchase-orders) instead of an ION Action. It's easier to configure and maintain.
</Note>

## Require multiple fields on creation

Blocks creating a part of type Part until the required fields are filled in. The technique: run on the `CREATE` event, guard on the object's type, then check a list of required fields at once.

| Field  | Value                             |
| ------ | --------------------------------- |
| Title  | Required fields for part creation |
| Target | `PART`                            |
| Event  | `CREATE`                          |

**Context**

```graphql theme={null}
{
  part(id: $id) {
    id
    revision
    description
    trackingType
    sourcingStrategy
    partType
    unitOfMeasure { id }
  }
}
```

**Code**

```python theme={null}
part = context.get('part', {})
required_fields = ['revision', 'description', 'trackingType', 'sourcingStrategy', 'unitOfMeasure']
if part.get('partType') == 'PART' and any(not part.get(field) for field in required_fields):
    raise ValidationError()
```

## Related

* [Manage actions](/automate-with-ion/ion-actions/manage-actions)
* [View action execution logs](/automate-with-ion/ion-actions/view-action-execution-logs)


# Manage actions
Source: https://docs.firstresonance.io/automate-with-ion/ion-actions/manage-actions

Create, edit, enable, disable, and delete ION Actions from the Actions page in ION or through the GraphQL API.

You manage ION Actions two ways: on the **Actions** page in ION, a dedicated UI with a built-in code editor, or through the GraphQL API for programmatic deployment. For what an action is and how its parts fit together, see [ION Actions](/automate-with-ion/ion-actions).

## Before you start

Actions must be enabled at the organization level before any action can fire. Confirm the setting in the built-in GraphiQL editor:

1. In ION, select **GraphQL** in the sidebar to open the GraphiQL editor.

2. Run this query to check the current setting:

   ```graphql theme={null}
   {
     me {
       organization {
         id
         _etag
         settings {
           rules {
             enabled
           }
         }
       }
     }
   }
   ```

3. If `enabled` is `false`, an admin can turn it on with the `updateOrganization` mutation. See the [API reference](/api-reference) for the full mutation shape.

## Create an action

1. In ION, open **Actions**.
2. Click **Create Action**. The new-action form opens on its own page, grouped into **Identity**, **Trigger**, and **Logic**.
3. In **Identity**, enter a **Title**. It appears in the action's error and warning messages, so keep it meaningful.
4. In **Trigger**, set the **Target record** and the **Event**, and pick whether a violation blocks the save or warns under **On violation**.
5. Optional: in **Logic**, write the **Python code** and the **Context query**. See [Action anatomy](/automate-with-ion/ion-actions#action-anatomy) for what each part does. The **Context query** opens on a starting query that selects one record by id. Changing the **Target record** reshapes that starting query for the new target, but leaves a query you wrote yourself alone.
6. Optional: turn on **Enable on create**.
7. Click **Create Action**. The action's page opens.

**Title**, **Target record**, and **Event** are the only required fields, and they are what **Create Action** waits on. Code and a context query can be written later.

<Note>
  An action with no code matches every event on its target, so ION never arms one. **Enable on
  create** stays unavailable until code is written, and an action created without code is created
  paused.
</Note>

A written context query has to be structurally valid before ION will create the action. It must select exactly one record type at the top level, hold a single query, and leave out `edges` at that level, which ION adds for you. A query that breaks one of those rules reports it under the editor and holds **Create Action** back; an empty query does not.

To create an action programmatically, use the `createRule` mutation. See the [API reference](/api-reference) for the mutation shape, and the [example actions](/automate-with-ion/ion-actions/example-actions) for working configurations.

<Tip>
  ION Actions can block changes in production. Test a new action in your [sandbox](/api-reference/sandbox) before promoting it. For repeatable deployment, author through GraphQL and keep the action definition in your platform repo so you can re-deploy it from CI.
</Tip>

### Draft an action with ION Intelligence

Depending on your settings, the form carries a **Write with ION** control that drafts the action from a plain-language description.

1. On the new-action form, click **Write with ION**. ION Intelligence opens beside the form.
2. Describe the action you want, naming the fields you want filled in.
3. Wait for the answer to finish. The form is locked while ION writes into it, then unlocks with the fields it filled.
4. Review every field, then click **Create Action**.

A turn that never mentions a field leaves that field as you had it, so a follow-up such as "shorten the title" does not clear a query you wrote by hand. ION reports a **Coverage** list inside the answer, and checks each claim against the rules engine once the answer finishes. A claim it could not check stays **Generated, not verified** rather than becoming **Verified**, so read the rows rather than treating the draft as verified.

## Create a warning action

A warning action lets the change save and shows a non-blocking message instead of blocking it. To make an action warn, raise `ValidationWarning` instead of `ValidationError`. Keep `ruleType: VALIDATION`; the exception type drives the behavior. For when to warn rather than block, see [Blocking and warning](/automate-with-ion/ion-actions#blocking-and-warning).

```python theme={null}
if context.get('runStep', {}).get('status') == 'COMPLETE' and any(
    issue.get('status') != 'RESOLVED'
    for issue in context.get('runStep', {}).get('issues', [])
):
    raise ValidationWarning("This Run Step was completed while it still has open issues. Confirm the issues don't need to be resolved first.")
```

The run step still completes, and the operator sees the warning. Warnings return in the GraphQL response under `extensions.warnings` and appear as a non-blocking toast.

<Frame>
  <img alt="Orange warning toast in the New ION interface reading: 'Warning: [Rule 93] Warn when a Run Step is completed with open issues. This Run Step was completed while it still has open issues. Confirm the issues don't need to be resolved first.'" />
</Frame>

<Warning>
  If a warning action and a validation action both fire in the same transaction, the error wins and the warning isn't shown, though it's still written to the execution logs.
</Warning>

<Warning>
  Only one warning surfaces per change. If several warning actions fire for the same change, only the first appears; the next shows after the operator fixes it and resubmits.
</Warning>

## Edit an action

An action's page opens read-only, tagged **Read only**, with its values rendered as text. Everything on the **Configuration** tab is one form with one **Save changes**.

1. In ION, open **Actions**.
2. Click the action to open its page.
3. Click **Edit**. The fields become inputs, and **Discard changes** and **Save changes** appear.
4. Change what you need. The line under the title becomes an unsaved-changes count.
5. Click **Save changes**. The page returns to read-only.

To back out instead, click **Discard changes**. The confirmation names the fields that revert, and it is skipped when nothing changed. A context query you edited into something malformed holds **Save changes** back, though **Discard changes** stays available. A query that was already saved malformed doesn't block the save, so you can still fix the other fields.

To edit an action programmatically, use the `updateRule` mutation. See the [API reference](/api-reference) for the mutation shape.

<Warning>
  Editing a live action changes its behavior right away. Test your changes in your [sandbox](/api-reference/sandbox) before editing a production action.
</Warning>

### When someone else saved first

Because the whole form saves at once, a save that lost a race is refused as a whole. ION reports what happened, tells you nothing of yours was saved, and offers three ways out:

| Resolution                         | What it does                                                                                                                       |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Keep my edits on top of theirs** | Re-reads the saved action, re-applies your edits over it, and leaves you in edit mode. Click **Save changes** again to store them. |
| **Discard mine, load theirs**      | Drops your edits and loads what was saved.                                                                                         |
| **Overwrite with mine**            | Replaces what was saved with your version.                                                                                         |

If the re-read cannot reach ION, the dialog stays open with the reason and all three resolutions still available.

## Write a description with ION Intelligence

Depending on your settings, the **Description** field carries a **Describe with Intelligence** control that writes the description from the action's own code, context query, target, and event.

Click it on the action's page. From read mode the description is written and saved on its own, so you can generate one without entering edit mode. Generate it while editing and it becomes an unsaved change like any other, stored by **Save changes**.

Once ION has written one, the control reads **Regenerate**; click it to replace the description. Come back to the action later and it reads **Describe with Intelligence** again.

## Enable or disable an action

An action's page carries the switch, labeled **Action enabled** or **Action disabled**. It commits on its own rather than through **Save changes**. To change several at once, select them with the checkboxes in the Actions list and enable or disable them there.

A disabled action isn't evaluated, which lets you stage an action before turning it on in production.

<Warning>
  An action with no code matches every event on its target, so nothing in ION arms one. The switch
  stays unavailable on a paused action with no code, a bulk enable skips those rows and reports how
  many it left paused, and saving an action whose code you emptied disables it. Disabling is never
  filtered: an action already running with no code is exactly the one to switch off.
</Warning>

## Review an action's executions

Open the action and switch to the **Executions** tab, beside **Configuration**. It carries the action's execution metrics and its filterable log. For what each log holds, see [View action execution logs](/automate-with-ion/ion-actions/view-action-execution-logs).

## Share an action across environments

To copy an action to another environment, open it and select **Share** in the **More options** (⋯) menu. ION generates the action's `createRule` mutation; copy it and run it in the target environment's GraphiQL editor to recreate the action there.

The snippet is built from what is on the form, including any unsaved edits, so save first if you want to share what is stored.

## Delete an action

1. In ION, open **Actions**.
2. Find the action you want to remove.
3. Delete it and confirm. On the action's own page, **Delete** sits in the **More options** (⋯) menu. To remove several at once, select them with the checkboxes in the Actions list and delete them together.

To delete an action programmatically, use the `deleteRule` mutation. See the [API reference](/api-reference) for the mutation shape.

<Warning>
  Deleting an action is permanent. If you only want to stop it from running, [disable it instead](#enable-or-disable-an-action).
</Warning>

## Related

* [ION Actions](/automate-with-ion/ion-actions) for how actions work and how to write their code
* [View action execution logs](/automate-with-ion/ion-actions/view-action-execution-logs) to inspect and debug an action run
* [Example actions](/automate-with-ion/ion-actions/example-actions) for working action configurations


# View action execution logs
Source: https://docs.firstresonance.io/automate-with-ion/ion-actions/view-action-execution-logs

Inspect the exact code and context of an ION Action run to confirm behavior and debug failures.

Action execution logs show the exact code and context used during an ION Action run, along with the validation message, the actions that ran, and the target record. Use them to confirm correct behavior and troubleshoot failures while developing an action. Logs are scoped to one event and target combination during a change: when several actions share the same event and target, their execution is grouped into a single log.

<Note>
  Execution logs are kept for 30 days. After that, they are permanently deleted.
</Note>

## Open the logs

You can reach execution logs two ways:

* **From the Actions page**: select **View Execution Logs** in the header to open a table of all execution logs.
* **From a single action**: open the action and select the **Executions** tab, next to **Configuration**, to see that action's metrics and its logs only.

## Table actions

The **Actions** column on each row gives you quick ways to work with a log:

* **View Execution**: open the execution log page.
* **Copy Link**: copy a link to the execution log page.
* **Download Code**: download the executed code as a Python file.
* **Quick View**: open a dialog with a glimpse of the execution code.

<Frame>
  <img alt="Actions column menu showing View Execution, Copy Link, Download Code, and Quick View." />
</Frame>

### Download code and debug locally

Use **Download Code** to save the executed code as a Python file. To download several at once, select multiple rows and use the action bar at the bottom to get a Zip with one Python file per log.

<Frame>
  <img alt="Selected execution log rows with the bottom action bar to download a Zip of Python files." />
</Frame>

With Python 3 installed, run `python3 name_of_log_file.py` in your terminal to reproduce the action's exact output. Edit the file and run it again until you get the result you want, then move your changes back into the action.

### Quick view

**Quick View** opens a dialog with the executed code, the timestamp, and high-level metadata. Use the arrows, or the left and right arrow keys, to move to the next log. Navigation follows the logs shown in the table.

<Frame>
  <img alt="Quick View dialog showing an execution's code, timestamp, and metadata." />
</Frame>

## The execution log page

Open a log by selecting its timestamp or **View Execution**. The page shows all metadata along with the code and context that ran.

<Frame>
  <img alt="Execution log page showing metadata, the executed code, and the context." />
</Frame>

Select **Show Execution Context** to expand the context as formatted JSON.

<Frame>
  <img alt="Execution log page with the execution context expanded as formatted JSON." />
</Frame>

## Log fields

Each log contains the code, context, and metadata from the run:

| Field               | Description                                                                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created At          | When the log was created, matching when the action was triggered.                                                                                                     |
| Event               | The event that triggered the action.                                                                                                                                  |
| Target              | The type of record the action ran against, such as Part Inventory or Run Step.                                                                                        |
| Target Record ID    | The ID of the target record. An `UPDATE` event with target `PART` and target record ID `34` means the action was triggered by updating part `34`.                     |
| Validation Message  | The message raised by the action, either the expected validation message or a Python error such as a `SyntaxError` or `NameError` that occurred while the action ran. |
| Raised Action       | The action that raised the validation message.                                                                                                                        |
| Executed Action IDs | Every action that ran in the log.                                                                                                                                     |
| Execution Time      | How long the action took to run, in milliseconds.                                                                                                                     |
| ION Request ID      | The ID of the request during which the log was created. It also appears on the error toast shown when an action fails.                                                |
| Triggered By        | The person whose operation triggered the action.                                                                                                                      |

## Related

* [Manage actions](/automate-with-ion/ion-actions/manage-actions) to author the actions these logs come from


# Ask ION a question
Source: https://docs.firstresonance.io/automate-with-ion/ion-intelligence/ask-ion

Open the ION Intelligence companion, ground a question in the records you name, and reopen or delete an earlier conversation.

For what the assistant is and where it appears, see
[Overview](/automate-with-ion/ion-intelligence).

## Ask a question

1. Open the companion. On a desktop page, click the ION pill in the bottom-right corner, click
   **ION Intelligence** in the sidebar, or press `⌘I` (`Ctrl+I` on Windows and Linux). On a phone,
   open the **ION** tab in the bottom navigation.
2. Type your question in the composer. `Enter` sends it; `Shift+Enter` starts a new line.
3. Optional: in a browser that supports voice input, click **Dictate prompt** and speak instead of
   typing. Dictation writes plain text, so it is unavailable while a mention is attached; the
   control says so, and removing the mentions re-enables it.
4. Read the answer in the thread. Follow up in the same composer to keep the same conversation.

Position the companion from the controls in its header: **Float**, **Dock left**, **Dock right**, and
**Minimize** (or press `Esc`). It reopens in whichever of those you left it in.

<Note>
  A turn runs one at a time. While an answer is streaming, the composer is unavailable, so a second
  question cannot displace the answer you are waiting on. Opening a different conversation abandons
  the answer in flight.
</Note>

## Attach context to a question

The assistant already knows the record whose page you are on. Attach anything else it should read.

1. Click **Add** beside the composer.
2. Pick a category, or type into the search box to search across categories:
   * **People**, **Teams**, and **Roles** read **Browse** and open as a list.
   * **Issues**, **Parts**, **Runs**, **Procedures**, and **Steps** read **Search only**, because
     those collections are too large to list. Type to search them. Where you have attached that
     kind before, the picker opens on those recent picks instead.
3. Click a result. It becomes a chip above the composer and stays attached, across new
   conversations too, until you remove it.

To name a person inside the sentence rather than beside it, type `@` in the composer and pick them.
`@` searches people only; every other kind is attached from **Add**. A typed mention renders as a
pill in the text and as a chip above the composer, and removing either removes both.

To detach something, click **Remove** on its chip. A chip that came from the page you are on has no
**Remove** control, because it follows the page rather than the conversation.

## Reopen or delete a conversation

1. Click **Recent conversations** in the companion's header.
2. To pick up an earlier thread, click its row. To start over instead, click **New conversation**.
3. To remove a thread, hover or tab to its row and click **Delete conversation**.
4. Confirm with **Delete**.

<Warning>
  Deleting a conversation removes it from your history for good. Deleting the one you have open
  clears the thread and starts a new conversation.
</Warning>


# Overview
Source: https://docs.firstresonance.io/automate-with-ion/ion-intelligence/index

What ION Intelligence is, where it appears, what it can see about the page you are on, and who is allowed to reach it.

ION Intelligence is a conversational assistant that answers questions about the work in front of
you, grounded in your organization's own records.

The assistant is a **companion** rather than a page. It rests as a pill in the bottom-right corner
of every screen and expands into a floating box, or into a rail docked to the left or right edge
that the page reflows beside. Either way the record you are asking about stays on screen while you
talk about it. For the steps, see
[Ask ION a question](/automate-with-ion/ion-intelligence/ask-ion).

## Where the assistant appears

| Surface                                         | What it is                                                                                                                                                                                      |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The pill and the expanded companion             | On every desktop page. Open it from the pill, from **ION Intelligence** in the sidebar, or with `⌘I` (`Ctrl+I` on Windows and Linux).                                                           |
| The **ION** tab in the mobile bottom navigation | A full-screen conversation, with the same voice dictation as the desktop composer.                                                                                                              |
| Suggested-action cards                          | Tiles on **Kits**, **Purchases**, and **Inventory** that hand the assistant a set of findings. See [Suggested-action cards](#suggested-action-cards).                                           |
| Suggested prompts                               | Starting prompts for the page you are on, listed above the composer until you pick one or hide the row.                                                                                         |
| Suggestion pills on a draft procedure step      | Labels such as **Improve**, **Add safety warnings**, and **Add quality checkpoints** ask the assistant to rewrite the step. The answer arrives as a proposal you review rather than as an edit. |

## What the assistant can see

Two channels feed a question, and both render as chips above the composer.

**Page context** comes from the URL, so the assistant knows which record you are looking at without
you attaching it. Depending on your settings, it may not be released to your organization yet:

| Page                                                                                      | What it contributes                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------ |
| A procedure, and the step selected on it                                                  | The procedure, and the procedure step      |
| A run's **Overview**, **Steps**, or **Dependencies** tab, and the run step selected on it | The run, and the run step                  |
| A part in the parts library                                                               | The part                                   |
| An issue                                                                                  | The issue                                  |
| A purchase order                                                                          | The purchase order                         |
| A standard step                                                                           | The step                                   |
| A list page                                                                               | Nothing, because no single record is named |

**Attached context** is what you add yourself, from **Add** or by typing `@`. A page-derived chip
carries no remove control, so the two are told apart on sight.

<Note>
  A chip's label needs a lookup, but the record behind it does not. A label that loads slowly, or
  fails to load, costs the chip and never the record the question is grounded on.
</Note>

## Conversations

A conversation is a thread the assistant follows for its own duration. **New** starts a fresh one,
and **Recent conversations** lists the ones you have already had, so you can reopen or delete one.
Reopening replays the thread as it was, including the tables and cards a turn drew, rather than as
flat text.

Conversations are private to your account. The **Add** picker's recent picks are remembered in the
browser you used, so they do not follow you to another device.

## Suggested-action cards

Three tiles put a queue in front of you and hand the assistant the findings behind it, so the
conversation opens on specific records instead of on a blank question. Each shows a count and one
line of detail, and clicking it opens the companion with those findings already sent. The assistant
recommends and links; it changes nothing on its own. A tile appears on its page only when it has
something to show, and **Stale purchase orders** also needs in-app analytics turned on.

| Card                      | Page          | What it counts                                                                                                          |
| ------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Kits ready to build**   | **Kits**      | Your open, fully fillable kits whose parts cleared an inspection run in the last seven days                             |
| **Stale purchase orders** | **Purchases** | Open purchase orders past their expected arrival with overdue lines still awaiting receipt, ranked by outstanding value |
| **Released inventory**    | **Inventory** | Available inventory that became available because its run was canceled or partially completed                           |

Clicking **Kits ready to build** also filters the **Kits** table to exactly the kits it counted, so
the rows match the number on the tile.

<Note>
  **Released inventory** is a review queue rather than a defect list. Returning a canceled run's
  stock to **Available** is intended behavior, and a lot whose other run completed is legitimately
  available, so the assistant asks you to confirm before recommending a move or a scrap.
</Note>

## Getting help from a person

The support chat lives inside the companion. **Contact support** sits in the context row beside the
composer and opens the support panel over the conversation, so the thread you were describing stays
on screen. When you tell the assistant that something is broken, or ask for a person, it offers the
same control as a **Contact support** chip in the thread. The chip only offers, and dismissing it
stops it coming back for the same reason in that conversation.

## Availability

ION Intelligence is off until an admin turns it on for the organization, and which surfaces you see
then depends on what First Resonance has released to it. See
[Turn on ION Intelligence](/administration/organization-settings/enable-ion-intelligence).


# Overview
Source: https://docs.firstresonance.io/automate-with-ion/notifications/index

How ION notifies you about events on the objects you follow, in-app and by email, and how to control what you receive.

ION notifies you when something happens on an object you follow: a new comment, an `@`-mention, a status change, an approval or sign-off request, or an assignment. Every notification appears in your in-app inbox, and you also receive it by email if you [enable email notifications](/getting-started/ion-basics#account-switches).

<Tip>
  To push notifications to external systems such as Slack or an ERP, use [Webhooks](/api-reference/guides/webhooks) to deliver ION events outside the app.
</Tip>


# Subscribe to notifications
Source: https://docs.firstresonance.io/automate-with-ion/notifications/subscribe-to-notifications

Subscribe yourself to an object, unsubscribe, and add other people as subscribers so the right people get notified.

You receive notifications for the objects you subscribe to, such as issues, procedures, runs, part kits, and purchase orders. See [Notification events](/automate-with-ion/notifications/view-notifications#notification-events) for the full list of objects and the events that notify their subscribers. ION subscribes you automatically when you:

* Create an issue, procedure, run, or part kit.
* Get assigned to one of these objects, including a purchase order.

## Subscribe or unsubscribe yourself

On an object, select the bell to **Subscribe**. Once you're subscribed, the bell becomes **Unsubscribe**; select it to stop receiving that object's notifications.

Subscribing to a run also notifies you of its run-step changes and comments, so you don't need to subscribe to each step separately. When an issue is created from a run step, that run's and run step's subscribers are subscribed to the new issue as well.

## Add or remove other subscribers

Next to the bell, select **Subscribers** to open the people list, then add or remove users to control who gets the object's notifications.

<Note>
  A notification addressed to you personally goes only to you, not to the object's other subscribers. This covers assignments, requests to approve, review, or sign off, and `@`-mentions. Everything else, such as comments, status changes, and releases, goes to all of an object's subscribers. An object can also be assigned to a team instead of a person; the team's members then receive its assignment, sign-off, and approval-request notifications.
</Note>

## Related

* [View your notifications](/automate-with-ion/notifications/view-notifications) to open and manage your inbox
* [Personal settings](/getting-started/ion-basics#account-switches) to turn on email delivery


# View your notifications
Source: https://docs.firstresonance.io/automate-with-ion/notifications/view-notifications

Open your notification inbox, filter and search it, mark notifications read, and see which events ION notifies you about.

The **Notifications** bell in the sidebar opens your inbox and shows a badge with your unread count. The inbox lists your most recent notifications. Select **See all notifications** to open the full Notifications page.

On the Notifications page you can:

* Search notifications by text.
* Filter by type with the **All types** menu.
* Show only unread notifications.
* Mark a single notification read or unread, or select **Mark visible as read** to clear everything on screen.
* Select **Load more** to load older notifications.

Notifications are grouped by age: **Today**, **Yesterday**, **This week**, and **Earlier**. Selecting one opens the object it refers to and marks it read.

## Notification events

You can receive these notifications. Filter the list by type to narrow it to one of them.

| Object          | Events                                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Any object      | Comment, mention.                                                                                                                                   |
| Issues          | Created, status changed, assigned, approval request.                                                                                                |
| Further actions | Assigned, status changed (except to in progress or canceled), approval request.                                                                     |
| Procedures      | Status changed (except to draft or in review), released, approval request, review request, review rejected, redline approval request.               |
| mBOMs           | Status changed (except to draft or in review), released, approval request.                                                                          |
| Runs and steps  | Run assigned, run step assigned, run step failed, run step field assigned, datagrid value assigned, standard step approval request, inspection run. |
| Part kits       | Assigned, status changed to completed or canceled.                                                                                                  |
| Purchasing      | Purchase order assigned, approval request.                                                                                                          |
| System          | Import job completed.                                                                                                                               |

## Related

* [Subscribe to notifications](/automate-with-ion/notifications/subscribe-to-notifications) to control which objects notify you
* [Personal settings](/getting-started/ion-basics#account-switches) to turn on email delivery


# Create a flow
Source: https://docs.firstresonance.io/automate-with-ion/workflow-builder/create-a-flow

Trigger a flow from an ION event with the ion-webhooks component, then read or write ION data with the ion-api component.

A typical ION flow has two ION-specific pieces: a trigger that starts the flow when something happens in ION, and one or more steps that read or write ION data as the flow runs. This page covers both, then walks through a complete example.

## Trigger a flow from an ION event

Use the **ion-webhooks** component to start a flow when an ION event fires, such as a run being created or a purchase order changing state.

1. In Workflow Builder, create a new workflow and give it a name.
2. Add the **ion-webhooks** component and set it as the flow's trigger.
3. Configure the trigger's **Connection**. Select an existing ION connection, or add one:
   * Enter a name for the connection.
   * Enter the **Client ID** and **Client Secret** from your ION [API keys](/api-reference/authentication/api-keys).
   * Select the **Environment** your ION instance runs in, such as **Production** or **Sandbox**.
4. Set a **Webhook Receiver Name**. ION uses this name for the receiver it creates, so matching it to the flow name keeps the two easy to trace.
5. Add one or more trigger events as resource-and-action pairs, such as **Runs - Create** to fire whenever a run is created. A flow can trigger on more than one event.

<Note>
  ion-webhooks only triggers the flow. To read or write ION data once the flow is running, add the ion-api component as described below.
</Note>

## Read or write ION data with the ion-api component

Use the **ion-api** component to run a GraphQL query or mutation against ION from inside a flow, such as looking up a record the trigger referenced, or writing a value back to it.

1. Add a step to the flow and search for **ion-api**. You may also see **First Resonance ION** in the results: it's the same component, listed twice because one listing is public and the other is private to ION customers. Either works, but **ion-api** is the one kept up to date, so prefer it when both appear.
2. Choose the action for what you want to do. ion-api has a dedicated action for most common reads and writes, such as **Get Part** or **Update Part Attribute**, as well as a general **Run GraphQL Query** action for anything else. See the [ion-api actions reference](/automate-with-ion/workflow-builder/ion-api-actions) for the full list.
3. Configure the step's **Connection**. The first time you use ion-api in a flow, set this up the same way as the ion-webhooks connection above. Once a connection exists, later ion-api and ion-webhooks steps in the same flow can select it from the dropdown instead of creating a new one, since both components connect to ION the same way.
4. Fill in the action's fields, such as the record's ID. Reference a value from an earlier step, such as the ID the trigger received, instead of typing it in directly.

If you use **Run GraphQL Query** instead of a dedicated action, you also configure:

* **GraphQL Query**: the query or mutation to run.
* **GraphQL Variables**: a JSON object of the variables the query declares. Reference an earlier step's output for any variable that should come from the flow rather than be typed in, such as the ID of the record the trigger fired for.

## Example: set a custom attribute automatically when a part is created

This example builds a flow that sets a part's `Tracking Strategy` custom attribute whenever a part is created, based on its tracking level and sourcing strategy:

| Tracking level | Sourcing strategy | Tracking strategy |
| -------------- | ----------------- | ----------------- |
| None           | Make              | N/A               |
| None           | Buy               | N/A               |
| Lot            | Make              | Lot - Make        |
| Lot            | Buy               | Lot - Buy         |
| Serial         | Make              | Serial - Make     |
| Serial         | Buy               | Serial - Buy      |

1. Create a flow triggered by **Parts - Create**, following [Trigger a flow from an ION event](#trigger-a-flow-from-an-ion-event) above.
2. Add an **ion-api** step using the **Get Part** action to look up the new part's tracking and sourcing details. Set **Part ID** to the part ID from the trigger.
3. Add a branch step that checks whether the part's tracking level is set. Route parts with no tracking level to one branch, and every other part to another.
4. On the no-tracking branch, save the value `N/A` for use in a later step.
5. On the other branch, save a value built from the part's tracking level and sourcing strategy, such as `Lot - Make`.
6. Add an **ion-api** step using the **Update Part Attribute** action to write the saved value to the part's `Tracking Strategy` attribute. Set **Part ID** and **Etag** to the values Get Part returned, **Attribute Key** to `Tracking Strategy`, and **Attribute Value** to the value you saved.

The result: every new part gets its `Tracking Strategy` attribute set automatically, without anyone setting it by hand.

## Publish the flow

A flow doesn't run until you publish it. Before publishing, [test the flow](/automate-with-ion/workflow-builder/test-a-flow) to confirm it does what you expect.


# Overview
Source: https://docs.firstresonance.io/automate-with-ion/workflow-builder/index

What the Workflow Builder is, what you can build with it, and when to use it instead of ION Actions.

The **Workflow Builder** is ION's tool for building automation flows. A flow reacts to an ION event or a schedule, then runs a sequence of steps that can call external systems, transform data, and read or write ION through the [GraphQL API](/api-reference). You assemble a flow visually from prebuilt components instead of writing an integration from scratch.

## What you can build

* **External connections** move data between ION and another system, such as syncing an order to a supplier portal.
* **Timed automations** run a flow on a schedule, such as checking stock levels every hour.
* **Event-triggered flows** start when something happens in ION, such as a run being created or a purchase order changing state.

## When to use Workflow Builder versus ION Actions

The Workflow Builder and [ION Actions](/automate-with-ion/ion-actions) both automate ION, but they solve different problems:

|                  | Workflow Builder                                               | ION Actions                                                |
| ---------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
| **Purpose**      | Orchestrate automation across systems                          | Enforce a business rule on a change                        |
| **When it runs** | On a schedule or in response to an ION event                   | Inside a change, before it saves                           |
| **Typical use**  | Sync data to an ERP, replenish inventory, call an external API | Block an invalid change, require a field, gate an approval |
| **Reach**        | ION plus external systems                                      | ION data only                                              |

Use Actions to allow, block, or warn on a change as it happens, such as preventing R\&D parts from being kitted into a production run. Use the Workflow Builder to move data between systems or run automation on a schedule.

## The two components behind every flow

A flow combines two ION-specific components, each with its own connection:

* **ion-webhooks** triggers the flow. It subscribes to ION events and exposes them as a trigger, creating the webhook receiver, managing the subscription, and cleaning it up when you remove the flow.
* **ion-api** reads or writes ION data from inside the flow, through the same GraphQL API the rest of ION runs on.

A flow that only runs on a schedule doesn't need ion-webhooks; a flow that only reacts to an ION event without reading or writing more data doesn't need ion-api. Most flows use both: ion-webhooks to start the flow, ion-api to act on the data it carries. See [Create a flow](/automate-with-ion/workflow-builder/create-a-flow) for how to configure each, and the [ion-api actions reference](/automate-with-ion/workflow-builder/ion-api-actions) for everything ion-api can do.

## Open Workflow Builder

Open **Workflow Builder** from the left navigation, under **Developer Platform**. The entry appears only when your organization has Workflow Builder enabled, and it's enabled per organization rather than per role. To have it turned on, contact [support.firstresonance.io](https://support.firstresonance.io).

Once you're in, see [Create a flow](/automate-with-ion/workflow-builder/create-a-flow) to build one, or [Test a flow](/automate-with-ion/workflow-builder/test-a-flow) to run and monitor one you've built.


# ion-api actions reference
Source: https://docs.firstresonance.io/automate-with-ion/workflow-builder/ion-api-actions

Every action the ion-api component provides for reading, writing, and searching ION data from a Workflow Builder flow.

The **ion-api** component is how a Workflow Builder flow reads or writes ION data. See [Create a flow](/automate-with-ion/workflow-builder/create-a-flow) for how to add it to a flow and configure its connection. This page covers every action it provides, grouped by what they do. For anything not covered by a dedicated action, use **Run GraphQL Query** to run any query or mutation directly.

## Run a query or mutation directly

| Action            | What it does                                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Run GraphQL Query | Runs any GraphQL query or mutation against ION, with a **Connection**, **GraphQL Query**, and **GraphQL Variables** field. |

Reach for a dedicated action below when one exists: it gives you a real form to fill in instead of a hand-written query, and it already accounts for the behaviors described on this page. Run GraphQL Query is the fallback for anything a dedicated action doesn't cover.

## Set a custom attribute's value

Nine actions set one custom attribute's value on one record. Each takes a **Connection**, the record's numeric ID, the attribute's **Key**, a **Value**, and an **Etag**, and returns the updated attribute.

| Action                               |
| ------------------------------------ |
| Update Run Attribute                 |
| Update Purchase Order Attribute      |
| Update Purchase Order Line Attribute |
| Update Issue Attribute               |
| Update Part Attribute                |
| Update Part Inventory Attribute      |
| Update Supplier Attribute            |
| Update Run Step Attribute            |
| Update Part Kit Attribute            |

Leave **Etag** blank to create an attribute that doesn't exist yet.

These actions set an attribute's **value**. Which attributes exist on an entity type at all is separate, org-level configuration. Read it with **Get Organization** (under `settings.<entity>.attributes`) and change it with the two actions below.

<Note>
  **Update Run Step Attribute** only works while the run step is in **REDLINE** status; every other status rejects the write. Put the step into redline, set the attribute, then submit and approve the redline to make the step workable again.
</Note>

## Configure which attributes exist

Two actions change an entity type's attribute **schema**, which attributes exist and what type they are, not any one record's value.

| Action                                             | What it configures                                       |
| -------------------------------------------------- | -------------------------------------------------------- |
| Update Organization Purchase Order Attributes      | The custom attributes available on purchase orders.      |
| Update Organization Purchase Order Line Attributes | The custom attributes available on purchase order lines. |

<Warning>
  Run **Get Organization** first and pass its `id` and `_etag` into these actions, not the purchase order's. The etag these actions check is the **organization's**, and a stale one fails the step.
</Warning>

Leave **Options** blank to leave an attribute's existing choices alone. These actions send nothing for that field when it's blank, rather than an empty list, so an untouched field can never wipe out a live attribute's options.

## Get, create, update, and delete records

| Action                               | Type   | Notes                                                                                                                                                 |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get Run                              | Get    | By ID. Returns nothing if no such run exists.                                                                                                         |
| Create Run                           | Create | From a procedure, against existing inventory or with new inventory.                                                                                   |
| Update Run                           | Update | Requires the run's current **Etag**.                                                                                                                  |
| Get Run Step                         | Get    | By ID. Includes the statuses it can move to next.                                                                                                     |
| Update Run Step                      | Update | Changes the step's status. Requires the step's current **Etag**, and confirms the status actually changed.                                            |
| Get Issue                            | Get    | By ID.                                                                                                                                                |
| Create Issue                         | Create | Optionally linked to a run step, part inventory record, or purchase order line.                                                                       |
| Get Purchase Order                   | Get    | By ID. Includes its lines and attributes.                                                                                                             |
| Create Purchase Order                | Create | Add lines afterward with Create Purchase Order Line.                                                                                                  |
| Update Purchase Order                | Update | Requires the order's current **Etag**, and confirms a status change actually took effect.                                                             |
| Get Purchase Order Line              | Get    | By ID.                                                                                                                                                |
| Create Purchase Order Line           | Create | Also returns any sibling lines ION renumbered as a result.                                                                                            |
| Delete Purchase Order Line           | Delete | Requires the line's current **Etag**.                                                                                                                 |
| Get Part                             | Get    | By ID. The way to read a part's current **Etag** before using Update Part.                                                                            |
| Update Part                          | Update | Requires the part's current **Etag**.                                                                                                                 |
| Get Part Inventory                   | Get    | By ID.                                                                                                                                                |
| Get Receipt                          | Get    | By ID. Includes its receipt items.                                                                                                                    |
| Get Supplier                         | Get    | By ID. The way to read a supplier's current **Etag** before using Update Supplier.                                                                    |
| Create Supplier                      | Create | Only a name is required.                                                                                                                              |
| Update Supplier                      | Update | Requires the supplier's current **Etag**.                                                                                                             |
| Get MBOM                             | Get    | By ID. The way to read an mBOM's current **Etag** before using Update MBOM.                                                                           |
| Create MBOM                          | Create | Copies the part's previous mBOM by default.                                                                                                           |
| Update MBOM                          | Update | Changes the mBOM's status. Requires its current **Etag**, and confirms the status actually changed.                                                   |
| Create Multiple MBOM Items           | Create | Adds a batch of mBOM lines from a JSON array.                                                                                                         |
| Delete MBOM Item                     | Delete | Requires the item's current **Etag**. Deletes one mBOM line, not the whole mBOM.                                                                      |
| Get Rule                             | Get    | By ID.                                                                                                                                                |
| Create Rule                          | Create | Creates a validation rule.                                                                                                                            |
| Update Rule                          | Update | Requires the rule's current **Etag**.                                                                                                                 |
| Delete Rule                          | Delete | Requires the rule's current **Etag**. Consider Update Rule with **Enabled** set to No instead, to switch a rule off without losing it.                |
| List Rules                           | List   | No inputs required. Returns every rule as a flat array.                                                                                               |
| Get Organization                     | Get    | Your organization's settings, including its custom-attribute schema per entity. Leave the ID blank for your own organization.                         |
| Create File Attachment               | Create | Attaches a file to an ION record.                                                                                                                     |
| Delete File Attachment               | Delete | Removes a file attachment.                                                                                                                            |
| Dispatch Notification                | Create | Sends an in-app notification to one user.                                                                                                             |
| Get Part Kit                         | Get    | By ID. Includes its kit items.                                                                                                                        |
| Create Part Kit                      | Create | Creates an empty kit. Add contents with Create Part Kit Item or Create Part Kit Items.                                                                |
| Update Part Kit                      | Update | Requires the kit's current **Etag** (not one of its items' etags).                                                                                    |
| Delete Part Kit                      | Delete | Requires the kit's current **Etag**. Deletes the kit and its lines, not the parts in it.                                                              |
| Create Part Kit Item                 | Create | Adds one kit line: which part, and how many.                                                                                                          |
| Create Part Kit Items                | Create | Adds a batch of kit lines from a JSON array. Prefer this over repeating Create Part Kit Item when filling a new kit.                                  |
| Update Part Kit Item                 | Update | Requires the item's current **Etag**. Can't move an item to a different kit, see below.                                                               |
| Delete Part Kit Item                 | Delete | Requires the item's current **Etag**. Deletes the kit line, not the part.                                                                             |
| Create MRP Job                       | Create | Starts a material-requirements-planning run. This is asynchronous, so poll Get MRP Job for the result.                                                |
| Get MRP Job                          | Get    | By ID. Read **Status** to see whether it's still running, and **Failed Reason** if it ended in failure.                                               |
| Get Plan                             | Get    | By ID. Includes the plan's own fields, not its demand lines, which are unbounded.                                                                     |
| Create Plan                          | Create | Creates a demand plan. Add lines with Add Input To Plan.                                                                                              |
| Add Input To Plan                    | Create | Adds one demand line to a plan.                                                                                                                       |
| Get Redline                          | Get    | By ID.                                                                                                                                                |
| Get Purchase Order Approval Level    | Get    | By ID. Also returns the organization-level approval template it came from.                                                                            |
| Delete Purchase Order Approval Level | Delete | Requires the level's current **Etag**. Deletes the per-order approval level, not the organization template.                                           |
| Get ABOM Installation                | Get    | By **two** IDs: the build requirement and the part inventory record. See [Get ABOM Installation needs two IDs](#get-abom-installation-needs-two-ids). |
| Get User                             | Get    | By ID. Falls back to the user's email if they have no display name set.                                                                               |
| Get User Notifications               | Get    | A user's in-app notifications.                                                                                                                        |

## Search and list records

| Action                    | Returns                                       |
| ------------------------- | --------------------------------------------- |
| Search Parts              | Parts matching your filters.                  |
| Search Purchase Orders    | Purchase orders matching your filters.        |
| Search Suppliers          | Suppliers matching your filters.              |
| Search Part Inventories   | Part inventory records matching your filters. |
| Search Users              | Users matching your filters.                  |
| Get User Notifications    | One user's in-app notifications.              |
| List Locations            | Every location.                               |
| List Teams                | Every team, not including its members.        |
| List Roles                | Every role, not including who holds it.       |
| List Units Of Measurement | Every configured unit of measure.             |
| List Procedures           | Every procedure, not including its steps.     |

These twelve actions share the same conventions:

* **Every typed filter is an exact match.** Fill in a field and it becomes an exact-match filter; leave it blank and it's left out, so it never narrows the search. Date fields come as **After**/**Before** pairs.
* **Additional Filters** is a JSON field for anything the typed filters don't cover, such as partial matches or filtering on a related record. A key you set there overrides the matching typed filter.
* **Max Results** (default 100) caps how many records come back. Without a cap, a broad search could return an entire catalog in one step's output. List Rules has no such cap, since the number of rules an organization has is naturally bounded.
* **Sort** (blank means oldest-first by ID) sets the row order, picked from a live list of that record type's sortable fields. See [Sort your results safely](#sort-your-results-safely) for what it does and doesn't guarantee.

Every one of these actions also logs the exact filter it sent, in the step's execution log, useful for confirming what actually reached ION when a search returns fewer results than you expect.

<Note>
  **Max Results keeps the OLDEST N by default, not the newest.** Set **Sort** to `_CREATED_DESC` (or `ID_DESC`) to cap the newest N instead. A `_DESC` on any other field only reverses that field's own order. For "everything that changed since my last run," filter on **Created After** or **Updated After** instead of sorting; it needs no multi-page read at all, which matters most on Get User Notifications, since that feed only ever grows.
</Note>

A few relations are deliberately left out of these actions, since they'd make the response unbounded: List Teams and List Roles don't include membership (use Search Users with a team or role filter instead), List Procedures doesn't include step content, and List Locations doesn't include its parent, all descendants, or its inventory.

<Info>
  **Locations, Teams, and Units Of Measurement** each also back a dropdown elsewhere in this component, separate from their List action here: the dropdown is for picking one value on another action's field, while the List action returns full records for your flow to use. You'll likely use both, for different purposes.
</Info>

## How inputs behave

A few conventions apply across most actions on this page:

* **Blank means "leave alone."** An optional field you don't fill in is left out of the update entirely, so it never clears an existing value. The one exception is **Attribute Value** on the attribute actions above: there, blank clears the attribute, since setting its value is the entire point of those actions.
* **Yes/No fields have a third option: "leave unchanged."** These render as a dropdown rather than a toggle, specifically so an untouched field doesn't get sent as an explicit "No" and overwrite an existing value.
* **Additional Fields** is a JSON field on most create and update actions, for any field this page's typed inputs don't expose. A key you set there overrides the matching typed field. A handful of actions don't have this field at all: those are the ones whose typed inputs already cover every field ION accepts.
* **Custom attributes can only be set on create, not on update.** Create actions take an **Attributes** field. To change an attribute afterward, use that entity's own Update Attribute action (in [Set a custom attribute's value](#set-a-custom-attributes-value) above) instead of its Update action.
* **Etags.** Every update and delete action requires the record's current etag. Read it from the matching Get or Search action immediately beforehand; an out-of-date etag fails the step with a concurrency error.
* **Values are checked, not guessed at.** An ID must be a whole number, a date must be a real date, and a Yes/No field must be an actual yes or no. Each fails the step with a clear message rather than silently being reinterpreted into something ION happens to accept.

## Things to know before you build

### File attachments are rejected on a run that's already complete

Create File Attachment fails if the run it's attaching to has already reached **Complete** status. There's no override. Attach the file while the run is still open, or reopen the run first if you need to attach one afterward.

### A status change that's accepted isn't always a status change that happened

Update Run Step, Update Purchase Order, and Update MBOM can each report success while the record's status doesn't actually move: an approval rule or validator can silently refuse the transition. All three actions check the record's status after the call and fail the step by name if it didn't change as asked. Update Run Step and Update Purchase Order also return the statuses each record can move to next, so you can check what's valid before attempting a transition.

### Some deletes are deliberately not exposed

ION's API can delete more record types than this component exposes. Deleting a supplier, a purchase order, or an entire mBOM outright is left out on purpose: each is destructive to master data, a financial record, or an entire bill of materials, and the judgment was that this class of delete should happen in ION's own UI, where the consequences are visible, rather than from an unattended flow. Use Run GraphQL Query if you deliberately need one of these.

### A part kit's items can't move between kits

There's no action that reparents a kit item to a different kit. To move one, delete it from its current kit with Delete Part Kit Item and re-create it on the other with Create Part Kit Item.

### Get ABOM Installation needs two IDs

Unlike every other Get action on this page, Get ABOM Installation is identified by a pair of IDs, the build requirement and the part inventory record, rather than one. An as-built installation doesn't have a single-column identity of its own: it's defined by which inventory went into which build requirement.

### Sort your results safely

Every List and Search action's **Sort** input appends the record's ID as a tiebreaker automatically, in the same direction you picked. This makes tied rows come back in a consistent order, but it does **not** make every sort safe across a multi-page read: only the default (blank, oldest-first by ID) guarantees that a record created while your flow is still reading won't be skipped or duplicated. A non-default sort is safe on a single page (Max Results at 100 or below) or on data nothing is actively changing. For "everything that changed since my last run" over an actively-changing set of records, filter on **Created After** or **Updated After** instead of changing Sort.

## Reading Run GraphQL Query's output

Run GraphQL Query doesn't fail the step when ION returns a GraphQL error. It always succeeds, so your flow can inspect the error and decide what to do next rather than the step aborting outright.

The response places the query's own data at the top level of the output, alongside two extra fields: `errors` and `extensions`.

A successful query has `errors` set to nothing:

```json theme={null}
{
  "purchaseOrders": [{ "id": "1" }],
  "errors": null,
  "extensions": null
}
```

A failed one has entries under `errors`, each with a `code` you can branch on, for example, refetching a record's latest etag and retrying on a concurrency error, or surfacing the message to whoever's watching the flow on a validation error:

```json theme={null}
{
  "updatePurchaseOrderLine": null,
  "errors": [
    {
      "message": "Etag does not match the server's.",
      "path": ["updatePurchaseOrderLine"],
      "extensions": { "code": "CONCURRENCY_ERROR" }
    }
  ],
  "extensions": null
}
```

## Related

* [Create a flow](/automate-with-ion/workflow-builder/create-a-flow)
* [Test a flow](/automate-with-ion/workflow-builder/test-a-flow)
* [Workflow Builder overview](/automate-with-ion/workflow-builder)


# Test a flow
Source: https://docs.firstresonance.io/automate-with-ion/workflow-builder/test-a-flow

Run a flow manually or watch its live executions in Workflow Builder before you rely on it.

Test a flow before publishing it, and check its executions afterward to confirm it's running as expected.

## Run a flow manually

In Workflow Builder, open the flow and click **Run** to trigger it manually with sample input. Use this to check a flow's logic without waiting for a real ION event.

The **Run history** tab shows every manual and live run of the flow. Click a run to see each step's output and logs.

## Watch live executions

The **Live** view on **Run history** shows every execution the flow's trigger has fired, as ION events happen.

To confirm a flow is working end to end, trigger the event it reacts to and watch for a new execution. For example, if a flow triggers on **Purchase Orders - Create**, create a purchase order in ION and check that a new execution appears.

Click through each step of an execution to see its output and logs, which is the fastest way to find where a flow is failing.

## Related

* [Create a flow](/automate-with-ion/workflow-builder/create-a-flow)
* [Workflow Builder overview](/automate-with-ion/workflow-builder)


# As-built BOM (aBOM)
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/as-built-bom

How the as-built BOM captures what was actually installed at run time, including parent/child hierarchy, traceability queries, and the relationship between aBOM and mBOM.

The aBOM is the per-unit record of what physically went into an assembly. See [Bills of materials overview](/build-hardware/bills-of-materials) for how it relates to the mBOM and build requirements. This page covers how ION generates it, reads it, and traverses it.

## How the aBOM is generated

A run instantiates an aBOM from the parent part's [mBOM](/build-hardware/bills-of-materials/manufacturing-bom):

1. The run starts against a `PartInventory`, the unit being built.
2. ION snapshots the parent part's released mBOM into a per-run aBOM.
3. As operators install components during the run (scan a serial, scan a lot, confirm a count), each install creates an `Installation` record linking the consumed `PartInventory` to the build requirement it satisfied.
4. When the run completes, the aBOM is the full, attested tree of what went in.

The aBOM lives on the parent part inventory. Open the unit's record to see its build genealogy.

## aBOM hierarchy

Sub-assemblies are part inventories that themselves have aBOMs. For example, a top-level assembly such as `ASM-00012 (BRKT-ASSY-001)` contains:

* `SN-00001 (BRKT-001)`.
* `LOT-2026-0123 (FAST-M3, qty 4)`.
* `ASM-00099 (PCB-001)`, a sub-assembly with its own aBOM, containing its own installed inventory.

To traverse the full tree, recurse through each `installedPartInventory` in the API. For more information, see [Get an aBOM with full hierarchy](/api-reference/examples).

## Reading an aBOM in the UI

From a part inventory page:

1. Click the **aBOM** tab.
2. The tree renders top-down: the parent assembly at the top, build requirements as branches, installed inventory as leaves.
3. Click any installed unit to drill in. If it's a sub-assembly, you see its aBOM too.
4. Use the breadcrumb at the top of the dialog to walk back up.

The aBOM Part Manager, which you launch from a part inventory or run, is the interactive surface for this. For the editing flow, see [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements). To explore a unit's full genealogy interactively, including which parent assemblies contain a given serial or lot, see [Trace as-built inventory](/build-hardware/bills-of-materials/trace-as-built).

## What the aBOM is for

The aBOM answers three common traceability queries directly.

### What went into this delivered unit?

Open the unit's aBOM. The full tree, down to every serial and lot consumed during its build, is the record.

### Where did this lot end up?

Use reverse traversal. Given a `LOT-2026-0123` of FAST-M3, find every parent assembly it was installed into through the `parentPartInventory` relationship on the consumed inventory in the API.

### Are we shipping any units that contain this recalled supplier lot?

Apply the same reverse traversal to a problematic supplier lot. Run it against open inventory, work-in-progress, and delivered units to scope the recall.

## Shared installs after a lot split

An install that was in place before a lot split is linked to every lot that resulted from the split, so the same install shows on each lot's aBOM. Editing that install from any of the sharing lots affects all of them: adding an install, changing a quantity, or removing an install applies to the whole sharing set, not just the lot on screen. ION flags a shared install on the build requirement row and confirms before you remove one, because removing it clears the install from every sharing lot at once. After you confirm, the removal is held for about 10 seconds, and a countdown toast lets you cancel before it applies. For the affected-lot grouping and the confirm-and-cancel behavior, see [Split inventory on a run](/build-hardware/runs-and-execution/split-inventory-on-a-run).

## When the aBOM completes

When the run transitions to `Complete` (see [Run completion and review](/build-hardware/runs-and-execution/completion-and-review)), the aBOM locks. Downstream traceability reports, inventory state updates, and customer documentation consume the locked tree. Editing a locked aBOM requires reopening the run.

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Made on assembly (MOA)](/build-hardware/bills-of-materials/made-on-assembly)
* [Run completion and review](/build-hardware/runs-and-execution/completion-and-review)
* [Get an aBOM with full hierarchy](/api-reference/examples)


# Edit build requirements
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/editing-build-requirements

Add, remove, and configure build requirements on an aBOM, including quantities, substitutes, reference designators, and Made on Assembly parts.

The Part Installs (aBOM) dialog lets you edit an aBOM's [build requirements](/build-hardware/bills-of-materials) directly: add a part to the build, delete one, set the quantity, configure substitutes, and call out Made on Assembly (MOA) parts.

## Prerequisites

* Permission to edit aBOMs on the part inventory you're working with.
* An existing aBOM. ION creates one automatically when a part inventory is staged for a build.
* The **Part Installs (aBOM)** dialog is open. You can launch it from a part inventory page or from inside an active run.

## Open Part Installs (aBOM)

The dialog shows the parent assembly card at the top, then a searchable list of build requirements for that assembly. If you're working inside a sub-assembly, breadcrumbs at the top of the dialog let you navigate back up the assembly tree.

## Turn on Edit Mode

Toggle the **Edit Mode** switch in the bar at the top of the dialog. In edit mode you see a **You are in edit mode.** banner with a **Learn More** link, and the **Add New Build Requirement** dropdown becomes available. Add, delete, and quantity changes are available only while edit mode is on.

## Add a part

1. With edit mode on, open the **Add New Build Requirement** dropdown under the edit-mode banner.
2. Optional: To mark the part Made on Assembly, turn on the **Add as MOA** switch before selecting. See [Made on assembly (MOA)](/build-hardware/bills-of-materials/made-on-assembly).
3. Select the part to add. ION creates a new build requirement with a quantity of 1.

The dropdown excludes parts that are already on the aBOM, so you can't add the same part twice.

## Set the quantity

In edit mode, each build requirement card has a **quantity** input representing the count of that part required to complete one parent assembly. ION multiplies this by the parent assembly's quantity to compute total demand for the build. When the run builds more than one parent unit, the input is labeled **/ assembly** to make the per-assembly unit clear.

<Note>
  Quantity is per one parent unit. If the parent has a quantity of 5, ION calculates total demand as `quantity × 5`.
</Note>

## Configure substitutes

Expand a build requirement card and open the **Substitutes** dropdown to add alternate parts that can be installed in place of the primary part. When operators install against this build requirement during a run, they can scan any of the listed substitutes to satisfy the requirement. For more information, see [Alternates and substitutes](/build-hardware/bills-of-materials/substitutes).

## Add reference designators

For build requirements that need positional callouts, such as `R12` or `U7` on a PCB, expand the card and open the **Reference Designators** dropdown to enter them. Each designator must be unique within the build requirement and counts toward the total quantity required. For more information, see [Reference designators](/build-hardware/bills-of-materials/reference-designators).

## Edit or remove an installation

Each build requirement lists the inventory already installed against it. To adjust or remove a recorded installation, click **Uninstall** on that installation. A popover opens with these controls:

* **Quantity to Remove**: the amount of the installed quantity to take back off the assembly. Enter less than the full installed quantity to reduce the installation and keep the remainder installed. Enter the full quantity to remove the installation entirely.
* **Move to Location**: optionally move the removed inventory to a chosen location.
* **Scrap item**: optionally scrap the removed inventory instead of returning it to stock.

Click **Submit** to apply the change, or **Cancel** to close the popover without changes.

<Warning>
  When the same part inventory is installed across a shared aBOM, removing it clears it from every lot it's shared with, not only the one you're on. ION shows a confirmation before applying the removal. After you confirm, the removal is held for about 10 seconds, and a countdown toast lets you cancel before it applies.
</Warning>

## See and change which steps a part installs at

A build requirement card shows a **N steps** badge next to its availability badge when the requirement is assigned to run steps. Click the badge to list every assigned step with its required and installed quantities and its status. A requirement assigned to no step shows no badge and reads **Not assigned to a step**, which is a normal state rather than a problem.

Depending on your settings, edit mode replaces a card's install controls with an **Assigned steps** surface, so you can map a part to steps without leaving the dialog. This surface appears when your organization enforces mBOM parts assigned to steps. For more information, see [Enforce mBOM parts assigned to steps](/administration/production-settings/enforce-mbom-parts-assigned-to-steps).

1. With edit mode on, expand the build requirement card and click **Assign to step** in the **Assigned steps** section.
2. Pick the run step. The picker leaves out steps the requirement is already assigned to.
3. Set the **Quantity** for that step.
4. Click **Assign**.

A step must be in **Redline** to be assigned. When the selected step isn't, the row says so and offers **Put in redline**; a step that's already complete offers **Reopen step** first, then **Put in redline**.

Per-step quantity is editable, and the unassign control (**X**) is offered, only while that step is in redline. Outside redline the row shows a static `installed/required` quantity, states the gate, and offers **Enter redline**, or **Reopen step** when the step is already complete. Unassigning takes effect immediately with no confirmation, and the part stays on the aBOM.

## Delete a build requirement

In edit mode, click the trash icon on a build requirement card. ION shows a **Delete Build Requirement** confirmation; click **Delete** to confirm. Any build requirement can be deleted, whether it came from the mBOM or was added by hand.

When the requirement is assigned to run steps, the confirmation previews the cascade: **Steps losing this requirement** lists each step with its required quantity and any installed quantity, and **Existing installs, by step** lists the steps that hold installs. With nothing installed, the dialog confirms that it's safe to delete.

<Warning>
  You can't delete a build requirement that already has installed inventory. **Delete** stays disabled and the dialog states the reason next to the button. Remove the recorded installations first, then delete the requirement.
</Warning>

## Install a run's kitted parts

When the run has a kit holding inventory, the dialog's toolbar shows a banner counting the kitted parts, such as **3 parts kitted for this run**, with an **Install all from kit** button that installs them against this assembly in one action. The banner is hidden while edit mode is on, and a run whose kit holds nothing shows no banner.

When the run has no kit at all, the toolbar offers **Request All Parts** instead, which creates the kit request.

<Tip>
  The **Hide complete** switch at the top of the dialog hides build requirements that already have full installations recorded, which helps when working through a long aBOM late in a build. An as-required requirement (quantity 0) stays visible until something is installed against it. The layout control next to it switches between a compact and a comfortable row layout, and ION remembers your choice.
</Tip>

<Tip>
  The **Expand All** / **Collapse All** button toggles every build requirement card open or closed in one click, so you can review substitutes, MOA settings, and installations across the whole aBOM at once.
</Tip>

<Tip>
  Click **Expand aBOM** on a build requirement whose part is itself an assembly to drill into that sub-assembly's aBOM. The breadcrumbs at the top of the dialog let you walk back up the assembly tree at any point.
</Tip>

<Tip>
  Use the **Search** box to narrow the build requirement list by part number or description while editing.
</Tip>

## Related

* [Bills of materials](/build-hardware/bills-of-materials)
* [Parts](/build-hardware/parts)
* [Runs and execution](/build-hardware/runs-and-execution)


# Overview
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/index

How ION models a build's parts list: the mBOM plan, the aBOM record, and the build requirements that bridge them at run time.

ION splits a bill of materials into a plan and a record. The **manufacturing BOM (mBOM)** hangs off a [part](/build-hardware/parts) and holds engineering's planned structure. The **as-built BOM (aBOM)** hangs off a [part inventory](/manage-supply-chain/inventory) and holds the serial-and-lot record of what actually went into one unit. A **build requirement** is the shared line item: on the mBOM it states what should be installed, and on the aBOM it accumulates the installations that satisfy it.

When a run starts against a part inventory, ION snapshots the parent part's released mBOM into that run's aBOM, one build requirement per line, and locks the run to that mBOM version. Operators install against the aBOM during execution. The aBOM can diverge from the mBOM through substitutes, quantity deviations, redlines, and made-on-assembly installs, and that divergence is the traceability signal ION preserves. For the steps to edit requirements mid-run, see [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements).

## Manufacturing BOM

The mBOM is the parent part's planned parts list. Each line is a build requirement carrying a child part and revision, a per-assembly quantity, approved substitutes, reference designators, and a made-on-assembly flag. ION multiplies the line quantity by the parent run quantity to compute demand. You maintain the mBOM on the **mBOM** card on the part page while its version is in **Draft**, and edits save inline. For the build and consumption flow, see [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom).

If your engineering team keeps an eBOM in a PLM system such as Solidworks PDM, Arena, or Teamcenter, the ION mBOM is the manufacturing counterpart of it. Keeping the two in sync is a separate export/import or integration workflow.

## As-built BOM

The aBOM is a parent/child tree of part inventories that compose one finished unit. Sub-assemblies are part inventories with their own aBOMs, so traversal recurses through each `installedPartInventory`. Each install writes an `Installation` record linking the consumed inventory to the build requirement it satisfied. The tree answers traceability queries in both directions: what went into a delivered unit (top-down) and every parent a given lot reached (reverse traversal on `parentPartInventory`). For UI navigation and query patterns, see [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom). For batch traversal, see [Get an aBOM with full hierarchy](/api-reference/examples).

The aBOM is a work-in-progress until the run completes, at which point every required build requirement has an installation or an explicit issue-based exception, and the tree locks. Reopening the run is the only way to edit it afterward.

## Build requirement fields

| Field                     | Notes                                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Part Number / Rev**     | The required child part, shown with its revision.                                                                                                            |
| **Quantity**              | Count per one parent assembly. Multiplied by parent run quantity at execution.                                                                               |
| **Substitutes**           | Approved interchangeable parts for the line. See [Alternates and substitutes](/build-hardware/bills-of-materials/substitutes).                               |
| **Reference Designators** | Positional identifiers such as `R12` and `U7`. See [Reference designators](/build-hardware/bills-of-materials/reference-designators).                        |
| **Made on Assembly**      | Whether ION builds the child inside the parent's run instead of as its own run. See [Made on assembly](/build-hardware/bills-of-materials/made-on-assembly). |

Substitutes and reference designators are line metadata: you can edit substitutes without revising the whole mBOM, while adding or changing designators is a structural change. A reference designator is unique within its build requirement, and an approved substitute applies to every designator on the line.

## Divergence and versioning

The mBOM and aBOM carry independent version histories. A structural mBOM change (add or remove a line, change a part, change a designator, toggle MOA, or a significant quantity change) needs a new mBOM version; metadata changes such as notes and substitute edits are in-place. Releasing a new version archives the prior one, and only one version is **Released** at a time. In-flight runs keep the version they started against: to apply a structural change to a running build, use a [redline](/build-hardware/runs-and-execution/redlines-and-deviations) rather than a new version. For version states and the release flow, see [Manage BOM versions](/build-hardware/bills-of-materials/versions).

An mBOM version is distinct from a part revision. The revision tracks what the part is; the mBOM version tracks how to build a given revision. A new part revision usually implies a new mBOM, but an mBOM can also change on its own for routing or substitute updates.


# Made on assembly (MOA)
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/made-on-assembly

Sub-assemblies that get built directly onto the parent rather than as separate runs, including when to use MOA, how it changes the workflow, how it preserves traceability, and how to fix missing installs.

**Made on Assembly (MOA)** is a flag on a build requirement that marks a child part as constructed directly onto the parent during the parent's run, rather than as its own separate run. See [Bills of materials overview](/build-hardware/bills-of-materials) for how the flag sits on the line.

## How MOA changes the workflow

| Aspect                  | Normal sub-assembly                                           | MOA sub-assembly                                                                   |
| ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Run for the sub**     | Separate run, completes independently                         | No separate run; the sub is built within the parent's run                          |
| **Inventory pre-build** | Sub exists as a standalone `PartInventory` row before install | Sub is created during the parent's build                                           |
| **Operator handoff**    | One operator finishes the sub, another installs it            | Same operator builds and installs in one flow                                      |
| **aBOM record**         | Parent's aBOM references the sub's existing aBOM              | Sub's aBOM is created and rolled up into the parent's aBOM during the parent's run |
| **Scheduling**          | Sub appears on its own schedule                               | Sub doesn't appear in scheduling; its work lives within the parent's run           |

## Configuring MOA on a build requirement

From the **mBOM** card on the part page, with the version in **Draft**:

1. Find the build requirement's row.
2. Select the **Made on Assembly** checkbox in that row. The change saves automatically.

The build requirement now executes via the MOA flow at run time.

<Note>
  You can also flag a part as MOA when adding it to an aBOM: turn on the **Add as MOA** switch before selecting the part in Edit Mode. See [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements).
</Note>

## How operators install MOA build requirements

During the parent's run:

1. The MOA build requirement renders inline with the parent's other build requirements.
2. Instead of scanning an existing sub, the operator gets a **build flow** that walks through the sub's own procedure, or a sub-sequence inside the parent's procedure.
3. As the operator completes the MOA build steps, ION does the following:
   * Creates a new `PartInventory` for the sub, with a serial or lot depending on the sub part's tracking type.
   * Creates the sub's aBOM as a child of the parent's aBOM.
   * Records installations against the sub's build requirements as the operator works.
4. When the MOA sequence is complete, the sub is installed into the parent in a single atomic act: the new sub-assembly is created and installed at the same time.

## A serial-tracked MOA part at a quantity above one

When a made-on-assembly build requirement is for a serial-tracked part at a quantity above one, that quantity is that many separate physical assemblies. ION treats them that way:

* Each unit is created with its own serial number, and each serial is unique for the part number.
* Each unit carries its own set of child build requirements, so an install is attributable to the unit that received it.
* Progress is measured per unit. Over-filling one unit doesn't cover a unit that's still empty, so the requirement reads short until every unit meets its own demand.

Each unit is serialized inventory in its own right: you can find it by its serial number, and it can't be split or merged into other inventory.

### Install child parts into a specific unit

In the **Part Installs (aBOM)** dialog, click **Show installs** on the made-on-assembly requirement. It lists one sub-assembly section per minted unit, headed by that unit's serial and followed by how many of that unit's requirements are complete. A unit with everything installed reads **Built** instead, and a unit with no child requirements of its own reads **No sub-components**. Install into the section for the unit you are holding; each section reads and writes its own inventory, so the install is attributed to that unit. Each section collapses on its own, and a unit that has child requirements carries an **Expand ABOM** control for drilling into that unit's tree.

The run step's **Part installs** right rail also lists the units, grouped under a **Sub-assemblies** heading that counts them. Each unit there collapses on its own and shows the same completion status, but drilling into a unit's own tree is done from the **Part Installs (aBOM)** dialog.

Requirements that aren't serial-tracked don't split by unit. Their child parts list once, under the requirement itself.

A run step that still has an unmet requirement on any unit can't be completed, unless your organization turns on **Allow run steps to complete without required install**. For more information, see [Configure run enforcement](/administration/production-settings/configure-run-enforcement).

<Note>
  A run created before per-unit requirements were introduced keeps the shape it started with: one shared set of child requirements across the units. In the **Part Installs (aBOM)** dialog those units collapse into a single shared section. Only new runs get per-unit requirements.
</Note>

## Assign an MOA child to a run step

A made-on-assembly child requirement can be assigned to a run step in the same run, like any other build requirement, from the **Part Installs (aBOM)** dialog. The step must be in **Redline**. For the steps, see [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements).

## MOA and traceability

MOA preserves full traceability in both directions:

* **Top-down**: the parent's aBOM leads to the MOA sub's aBOM, then to the leaf installations. This is the same recursive tree as a normal sub-assembly.
* **Bottom-up**: a leaf part inventory, such as a fastener, installed in an MOA sub still has a `parentPartInventory` chain that walks up through the MOA sub to the top-level parent.

The only difference is when the work happened and which operator did it, not what the data records.

## MOA and Autoplan

In Autoplan, MOA components surface as `Placeholder` items in the plan. Placeholders represent the hierarchy of the BOM but **can't be converted into runs or purchases directly**. The parent's run produces them as a side effect of the parent build. Treat them as informational rows in plan output, not as actionable demand.

## MOA and run batches

When the parent is part of a [run batch](/build-hardware/runs-and-execution/run-batches), MOA build requirements:

* Render once per batched run, one MOA build per parent unit.
* Don't propagate as redlines across siblings the way step-level changes do. Each MOA build is its own piece of work even within a batch.
* Still inherit the batch's procedure version and shared-step sign-off behavior for any non-MOA steps.

<Tip>
  If a sub-assembly might eventually be batched separately or stocked, build it standalone. Switching from MOA to standalone after the fact reorganizes your routing.
</Tip>

<Tip>
  When sub-assemblies are MOA, you don't need to kit them separately ahead of the parent build. The components flow into the parent's kit.
</Tip>

<Note>
  A parent run with several deep MOA sub-assemblies can become a large run for one operator. If the work splits naturally between operators, separate runs can be cleaner even if the sub doesn't get stocked.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="A sub-assembly's installs are missing after the run">
    An MOA sub-assembly's inventory, its aBOM, and its installations are created only as the operator completes the MOA build flow during the parent's run.

    **Cause:** The MOA build flow wasn't completed. The sub exists only once its build steps are done.

    **Fix:** Complete the remaining MOA build steps on the parent's run.

    **Cause:** **Made on Assembly** was turned on after the run was created. A run builds against the mBOM version it was created from, so the line runs as a normal sub-assembly that expects an existing sub to install.

    **Fix:** Set **Made on Assembly** on the mBOM before you create the run. Changing it on an in-progress run doesn't convert installs that already exist.
  </Accordion>

  <Accordion title="A made-on-assembly part has no manual install option">
    **Cause:** MOA sub-assemblies are created and installed by the parent's build flow, not through a manual install, so no manual install control appears for them.

    **Fix:** Complete the MOA build flow on the parent's run to create and install the sub.
  </Accordion>
</AccordionGroup>

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Run and run step states](/build-hardware/runs-and-execution#states)


# Manufacturing BOM (mBOM)
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/manufacturing-bom

How the manufacturing BOM defines the planned structure of a build, including line items, quantities, alternates, and how runs consume it.

The mBOM is a part's planned parts list. See [Bills of materials overview](/build-hardware/bills-of-materials) for how it relates to the aBOM and build requirements. This page covers building and consuming it.

## mBOM line items

The mBOM table shows these columns per build requirement line:

| Column                    | Notes                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Part Number / Rev**     | The required part, shown with its revision                                                                                                             |
| **Quantity**              | How many of the part go in. Multiplied by the parent's run quantity at execution time                                                                  |
| **Substitutes**           | Approved alternate parts. See [Alternates and substitutes](/build-hardware/bills-of-materials/substitutes)                                             |
| **Reference Designators** | Positional identifiers such as `R12`, `U7`, and `Q1`. See [Reference designators](/build-hardware/bills-of-materials/reference-designators)            |
| **Made on Assembly**      | Whether this part is built directly onto the parent. See [Made on assembly](/build-hardware/bills-of-materials/made-on-assembly)                       |
| **Exclude from Kit**      | Whether to leave this line out when a kit is built from this mBOM. See [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits) |

For the GraphQL shape, see [mBOMs API](/api-reference/guides/mboms).

## Creating an mBOM

1. Open the parent **part** in the Parts Library.
2. Find the **mBOM** card on the part page. If the part has no mBOM yet, click **Create mBom**.
3. With the version in **Draft**, click **New Part** and pick the child part. ION adds a line with a quantity of 0.
4. For each line, set the **Quantity** and optionally add substitutes, reference designators, and the **Made on Assembly** and **Exclude from Kit** checkboxes directly in the row.

Select **Exclude from Kit** for a line you never want kitted, such as a consumable you draw from line-side stock. ION skips the line when building a kit from this mBOM and when building a kit from a run's aBOM, so its parts aren't requested.

Edits save as you make them; there's no separate save step. mBOM lines are editable only while the version is in **Draft**. For version states and the release flow, see [Manage BOM versions](/build-hardware/bills-of-materials/versions).

<Note>
  The mBOM card on the part page is a quick editor. For the full mBOM, including its complete version history, use the **Go to full mBom** link in the card header.
</Note>

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Alternates and substitutes](/build-hardware/bills-of-materials/substitutes)
* [BOM versions and change management](/build-hardware/bills-of-materials/versions)
* [Parts](/build-hardware/parts)


# Reference designators
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/reference-designators

Positional identifiers on a build requirement, including when to use them, how operators install against specific positions, and why they matter for traceability.

A reference designator pins a build requirement to a specific location in the assembly, such as `R7` or `U3`. See [Bills of materials overview](/build-hardware/bills-of-materials) for how designators sit on the line. When a build requirement has reference designators, operators install per designator rather than satisfying a count, and ION treats a requirement with no designators as quantity-only.

## Configuring reference designators

On the build requirement's row in the **mBOM** card, with the version in **Draft**:

1. Open the **Reference Designators** dropdown in the row.
2. Type a designator and press **Enter** (or click **Add**). The input keeps focus so you can add them in sequence, for example `R1`, `R2`, through `R12`.
3. To remove one, click the trash icon next to it in the dropdown.

Keep the number of designators aligned with the quantity, one per position.

Each designator is unique within the build requirement. Two build requirements on the same assembly can both have an `R7`, but within one build requirement `R7` appears once.

## How operators install with reference designators

At run time:

1. The build requirement renders with one row per designator instead of a single quantity counter.
2. For each designator, the operator selects (or scans) the part inventory to install at that position.
3. ION records the (designator, installed part inventory) pair on the aBOM.
4. The build requirement is satisfied when every designator has an installation.

Operators can install in any order, because designators don't impose sequencing. If the assembly's procedure has a specific order, that's enforced at the procedure-step level.

### Reading the designators on a run step

On a run step, the **Part installs** panel in the right rail lists a build requirement's designators under a **Ref Designators** heading, with a progress figure on the right:

* `n/m assigned` shows how many of the `m` designators assigned to this run step have an installation.
* `n installed` replaces that count when no designator is assigned to the run step, because there is nothing to measure against.
* `n/m assigned · k installed` appears when the requirement holds both kinds. `k` counts the designators that reached the run step through an installation rather than an assignment.

A designator that reaches the run step through an installation rather than an assignment is marked **not assigned to this step**. Assign it to the run step to have it count toward the assigned progress.

## Manage a designator's run step

Assigning a designator to a run step claims it for that step, so the operator working the step knows which positions belong to them. One dropdown assigns, removes, and moves. Reach it in the **Part Installs (aBOM)** dialog:

1. In the run, open the **Part Installs (aBOM)** dialog: on a run step, click **View all** in the **Part installs** panel of the right rail.
2. Turn on **Edit Mode**.
3. On the build requirement's row, open the designator control. It reads **Reference Designators** until the requirement has one, then shows the first designator with a badge counting the rest.
4. On the designator's row, open its step dropdown. Its trigger reads **Assign step** while nothing holds the designator, the holding step's number (**Step 2**) once one does, and `<n>` **steps** when several do.
5. Pick a step. Picking an unheld step assigns or moves the designator to it; picking the row that already holds it removes it. Search the list by typing.

A run step's row carries a marker when picking it would do more than a plain assignment:

| Marker                             | What it means                                                                                                                                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assigned** and **remove**        | This step holds the designator. Picking it takes the designator off the step.                                                                                                                     |
| **Assigned** and **needs redline** | This step holds the designator but has no open redline, so the designator can be neither removed nor moved. Put the step into redline first.                                                      |
| **starts redline**                 | The step has no open redline. Picking it asks you to confirm, then starts the redline and assigns the designator, or moves it when another step holds it. A complete step is reopened on the way. |
| **resets approvals**               | A redline involved is already approved. Picking it asks you to confirm, then clears the approvals.                                                                                                |
| **remove from a step first**       | The designator is on more than one step, so there is no single step to move it from.                                                                                                              |

### What a move does

There is no single operation that moves a designator, so ION removes it from its current step and assigns it to the new one. Both ends are redline-gated, so the confirmation names each run step whose approved redline will be cleared, one or two, and nothing is cleared until you confirm the whole move. An approval that lands after that confirmation stops the move rather than being overwritten.

<Warning>
  The removal and the assignment are separate, so a move can fail after the removal has already
  succeeded, leaving the designator on no step. ION says so when it happens: an error appears,
  followed by a **Move incomplete** message naming the step the designator left and the step it did
  not reach. Reassign it from the same dropdown, which is back in its unassigned state.
</Warning>

A designator marks one physical position, so ION refuses to assign one that another run step already holds. That refusal is why a move is two writes rather than one. The same rule applies when a redline is canceled: if the designator has since moved to another run step, ION refuses the cancel rather than restoring the designator onto two steps.

A run cut or an import can still land the same designator on two run steps. The dropdown shows both holders rather than picking one: each reads **Assigned** and is removable on its own step's redline, and every other step reads **remove from a step first** until the designator is down to one.

Deleting a designator removes its run-step assignment along with it, and the delete confirmation names the step that loses the assignment.

## Substitutes and reference designators

Substitutes are configured at the build-requirement level, not per designator, so an approved substitute applies to every position the requirement covers. At install time, for each designator the operator can install the primary or any approved substitute, independently per position. So `R1` can take the primary while `R3` takes a substitute, and the aBOM records which part went into which position.

Because substitutes can't be scoped to individual designators, if `R3` and `R7` need different alternates, make them different build requirements.

## Designator naming conventions

ION doesn't enforce a designator format, so it's free text. Your downstream traceability is more useful if designators are consistent. Common patterns:

| Asset class                            | Convention                         |
| -------------------------------------- | ---------------------------------- |
| Resistors                              | `R1`, `R2`, …                      |
| Capacitors                             | `C1`, `C2`, …                      |
| Integrated circuits                    | `U1`, `U2`, …                      |
| Connectors                             | `J1`, `J2`, …                      |
| Transistors / FETs                     | `Q1`, `Q2`, …                      |
| Diodes                                 | `D1`, `D2`, …                      |
| Mechanical fasteners (when positional) | `S1`, `S2`, … or `M3-1`, `M3-2`, … |

If you use schematic or PCB designations from your design package, mirror them in ION. The alignment makes engineering and manufacturing handoffs easier.

<Tip>
  Include reference designators when there's a chance you'll need positional traceability. Adding them later requires reinstalling every affected unit.
</Tip>

<Tip>
  Match the engineering source of truth. If your PCB layout calls a position `U3`, the build requirement should call it `U3`. Renaming for clarity introduces drift.
</Tip>

<Note>
  Don't use reference designators for sequential count tracking. A torque pattern that needs fastener 1, then fastener 2, then fastener 3 is a procedure-step concern, not a designator.
</Note>

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Alternates and substitutes](/build-hardware/bills-of-materials/substitutes)


# Alternates and substitutes
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/substitutes

How to configure interchangeable parts on the mBOM, and how operators install substitutes during runs without filing deviations.

A substitute is an interchangeable part configured against a build requirement on the mBOM. See [Bills of materials overview](/build-hardware/bills-of-materials) for how substitutes sit on the line. When a substitute is approved, operators can scan it during install in place of the primary and ION accepts it without flagging a deviation. This page covers configuring substitutes and how they behave at install time.

A different revision of the same part is a revision-interchangeability question, not a substitute. Set that on the part record instead. See [Enable part interchangeability](/administration/supply-chain-settings/enable-part-interchangeability).

## Configure a substitute

From the **mBOM** card on the part page, with the version in **Draft**:

1. Find the build requirement's row.
2. Open the **Substitutes** dropdown in that row.
3. Pick one or more substitute parts. Selections save as you make them.

To remove a substitute, reopen the dropdown and deselect it. You can add or remove substitutes without revising the mBOM as a whole, since they're metadata on the line. Significant substitution changes, such as flipping the primary, typically warrant a new mBOM revision.

## How substitutes behave during install

When an operator installs against a build requirement at run time:

1. The Part Installs (aBOM) dialog shows the **primary part** prominently.
2. The configured substitutes are listed under the primary part.
3. The operator can scan or pick any of the listed parts (primary or substitute).
4. ION validates the scan against the primary and substitutes together, then accepts the install.
5. The aBOM line records what was installed, whether primary or substitute.

If the operator scans a part that's neither the primary nor an approved substitute, ION rejects the scan. From there, the path is one of these: configure the unexpected part as a substitute and retry, file an issue and document a deviation, or source the correct part.

## Substitutes vs revision interchangeability

Two related-but-different concepts:

| Concept                         | When to use                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Substitute**                  | Different part numbers that are functionally equivalent (for example, `FAST-M3-A` and `FAST-M3-B` from two suppliers)     |
| **Revision interchangeability** | Same part number, different revisions (for example, `BRKT-001 Rev A` and `BRKT-001 Rev B`), configured on the part itself |

ION treats these separately because they have different controls. Substitutes need explicit per-line approval. Revision interchangeability is set at the Parts Library level. For more information, see [Enable part interchangeability](/administration/supply-chain-settings/enable-part-interchangeability).

## mBOM substitutes and aBOM installations

A substitute is a plan that says "this is acceptable to install." The aBOM records what was installed. The two together let you answer questions such as:

* How often is the primary used compared to each substitute? Aggregate over installations.
* Does any unit contain the substitute you just recalled? Filter installations on `installedPartInventory.partId`.

You don't lose traceability when substitutes are used. The aBOM is precise about which part went in, even when the build requirement allowed several choices.

## Substitutes and reference designators

When a build requirement has both substitutes and reference designators, the operator picks a position and then scans the primary or any approved substitute for it. For the full positional rule, see [Reference designators](/build-hardware/bills-of-materials/reference-designators#substitutes-and-reference-designators).

<Tip>
  When you add a substitute, capture why it's equivalent in the build requirement notes, such as matching datasheet specs, finish, or plating. ION's analytics can surface how often each substitute is used compared to the primary.
</Tip>

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Reference designators](/build-hardware/bills-of-materials/reference-designators)


# Trace as-built inventory
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/trace-as-built

Explore a unit's as-built genealogy interactively: what was installed into it, and which parent assemblies contain it.

In ION, go to **Quality** > **Trace (as-built)**.

## Start a trace

1. Under **Part**, search by part number and select the part.
2. Under **Inventory Instance**, select the serial or lot number to trace.
3. Click **View aBOM Trace**.

Units you traced before are listed under **Recent Searches**, so you can reopen one in a click.

You can also jump straight into a trace from a record: click **View aBOM** on a part inventory, in an inventory table, or on a received unit on a receipt.

## Read the trace

The trace shows the unit's as-built tree from the top down: the selected inventory at the root, its build requirements as branches, and the installed serials and lots beneath them, recursively through every sub-assembly.

* Switch between the **Graph** and **Table** views. The table adds **Status**, **Quantity**, and **Completion** columns per row, and build requirements show installed versus required counts.
* The **Used in** strip lists the parent assemblies this unit is installed in. Click a parent to re-root the trace on that assembly, which is how you answer "where did this lot end up?" for a recall or supplier escape.
* Click **Search** (or press **Cmd+K**) to find a part, serial, or lot inside the trace and focus it.
* Click any node to open its detail panel, with **Overview**, **Runs**, **Quality**, and **Supply** tabs covering the unit's install progress, origin and installation runs, related issues, and the supplier and purchase order it was received on. **View Inventory Details** opens the full inventory record.
* Click **Export** and choose **Export as CSV** or **Export as JSON** to take the whole tree with you.

## Related

* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Split inventory on a run](/build-hardware/runs-and-execution/split-inventory-on-a-run)
* [Get an aBOM with full hierarchy](/api-reference/examples)


# Manage BOM versions
Source: https://docs.firstresonance.io/build-hardware/bills-of-materials/versions

How mBOMs are versioned over time, what triggers a new version, and how in-flight runs handle BOM changes.

ION tracks mBOM changes through explicit versions. See [Bills of materials overview](/build-hardware/bills-of-materials) for how versioning relates to part revisions and in-flight runs. This page covers what triggers a new version, the version states, and the release flow.

## When a new version is needed

| Change                              | Action                                                   |
| ----------------------------------- | -------------------------------------------------------- |
| Add a new build requirement         | New version                                              |
| Remove a build requirement          | New version                                              |
| Change a part on an existing line   | New version                                              |
| Change a quantity                   | New version (significant); in-place edit (clarification) |
| Add or remove a substitute          | In-place edit                                            |
| Add or change reference designators | New version                                              |
| Toggle MOA on a line                | New version                                              |
| Edit a note or instruction          | In-place edit                                            |

In general, structural changes (what gets installed, where, and how many) need a new version. Metadata changes (notes, alternates, and clarifications) can be in-place edits.

## Version states

mBOM versions move through:

| State         | Meaning                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Draft**     | Editable; not used by any new run                                                                |
| **In Review** | Submitted for review before release                                                              |
| **Released**  | Locked structure; new runs against the parent part instantiate from this version                 |
| **Archived**  | No longer current; preserved for historical reference and in-flight runs that started against it |

Only one version of an mBOM is **Released** at a time. Releasing a new version automatically archives the previously released version.

## Release a new version

1. Open the **mBOM** card on the part page with the version in **Draft**.
2. Make the structural changes.
3. Use the status dropdown to move the version through **In Review** and then **Released**.

The new version becomes **Released**, and the previous version moves to **Archived**. To start the next version once the current one is released, click **Create new mBom version** in the card header.

<Tip>
  Group related changes from an Engineering Change Notice into one release rather than several incremental ones. Write a specific release note, such as "Updated R3 to 10kΩ per ECN-2026-0042", rather than "minor updates". Don't edit archived versions, even for typo fixes, since the historical record is part of the audit trail.
</Tip>

## Review and approve a version

A **Draft** version can go through review before it's released. Reviewers are assigned per role, and each role can require a set number of approvals.

Open the review panel from the **mBOM** card:

1. On a **Draft** version, open the review panel and expand the **Reviews** section.
2. Click the add-reviewer control to add a reviewer row. Pick a role, then pick the reviewer (a user or team that holds that role). ION creates an approval request for that reviewer.
3. Resolve any open feedback and assign every required reviewer.
4. Click **Move to In Review** to submit the version. The button is enabled only when all feedback is resolved and every required reviewer is assigned.

Once the version is **In Review**, each assigned reviewer sees the review controls next to a **Review required for role:** prompt naming their role. A reviewer approves or rejects with the approve (check) and reject (X) controls. A reviewer can act only on their own assigned review, and can't change it after approving.

When the required approvals are in, move the version to **Released** with the status dropdown. A reviewer who approved sees a **You approved this as** confirmation with their role on the released version.

## In-flight runs

When you release a new mBOM version, in-flight runs are unaffected:

* Each run captures the mBOM version it was started against at create time.
* Mid-flight runs continue running the old version even after the new one is released.
* New runs started after the release pick up the new version.
* The transition is handled per-run. There's no way to upgrade an existing run to the new mBOM.

<Note>
  To apply a structural change to an in-flight run, use a [redline](/build-hardware/runs-and-execution/redlines-and-deviations).
</Note>

## Switch between versions

The **mBOM** card on the part page has a version dropdown (for example, `v1`, `v2`) in its header. Pick a version to view its lines. Each option shows the version's status, and **Draft** versions can be deleted from the dropdown. To see a version's full line items, open the full mBOM with the **Go to full mBom** link in the card header.

## Programmatic comparison

ION has no built-in page that diffs two mBOM versions. For integrations or scripts, adapt the [Compare two aBOM versions](/api-reference/examples) query template: fetch the line items for both versions and diff them client-side.

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Redlines and deviations](/build-hardware/runs-and-execution/redlines-and-deviations)
* [Compare two aBOM versions](/api-reference/examples)


# Overview
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/index

How ION labels physical material and turns scans into traceable transactions: barcode format, print paths, templates, and scan-to-action workflows.

Labels bind ION's records to the physical material on your floor. A part inventory, kit, or location carries a printed barcode, and scanning it in ION resolves back to that exact record. Every scan that drives an action, such as a move, kit, or install, becomes a traceable transaction against the record.

You print labels from the entity you want to tag and scan them downstream during receiving, kitting, install, location moves, and run-step kiosk operations.

## Barcode format

An ION barcode encodes a JSON payload with the record's `uid` (Universal Identification), for example `{"uid":"24daeec708d84908af9beba707a5241b"}`. When you scan it, ION recognizes characters typed quickly that match the ION ID specification and resolves the `uid` to its record. Because the payload is compact, an ION QR code stays scannable at small label sizes: with the ZPL magnification factor, a `uid` QR code prints reliably at 0.25 x 0.25 inches on a 300 DPI printer. Preview a template's size and density with [Labelary](http://labelary.com/viewer.html).

If your material already carries barcodes from another system, you can map those formats to ION records with a regular expression or a JSON field mapping. See [Scan barcodes from other systems](/build-hardware/labels-and-scanning/scanning/scan-barcodes-from-other-systems).

## Print paths

ION prints over one of two paths, set once for the org by the **Use print server** toggle in **Settings → Organization → Barcode Labels**, not per print:

* **Browser** (Zebra Browser Print) drives a Zebra printer attached to the operator's workstation. ION talks to the local service over `https://localhost:9101`. See [Configure Zebra Browser Print](/build-hardware/labels-and-scanning/printing/configuring-printing-in-ion).
* **Print server** (for example, PrintNode) sends jobs to a central service that manages shared printers across the floor. See [Configure PrintNode server printing](/build-hardware/labels-and-scanning/printing/server-based-barcode-printing-printnode).

The **Barcode Label** dialog shows the printer picker for whichever path is configured. For printing a label, see [Print a label](/build-hardware/labels-and-scanning/printing).

## Templates

Each label is rendered from a ZPL template scoped to an entity type: inventory, kits, or locations. A template defines the field layout and what the barcode encodes, and you can define many templates per entity type for different purposes, such as a shipping label separate from an internal movement label. Templates inject record data through variables like `${part.partNumber}` and `${serialNumber}`. For authoring, see [Create label templates](/build-hardware/labels-and-scanning/templating), and for starting points, see [Sample templates](/build-hardware/labels-and-scanning/templating/sample-templates).

<Tip>
  Templates are defined at the org level in **Settings → Organization → Barcode Labels**. An admin adds or changes them. See [Create label templates](/build-hardware/labels-and-scanning/templating).
</Tip>

## Scan-to-action workflows

Scanning is enabled on every page in ION. You scan three object types: inventory, locations, and kits. After a scan, ION confirms it occurred and offers actions that fit the scanned object, and an action can chain to another scan or a click. Scanning an inventory then a location moves that inventory; scanning an inventory then a kit kits it. One workflow is page-bound: scanning a part inventory on the run execution page installs it if the part is on the aBOM. For the full set of workflows and scanner setup, see [Scanning](/build-hardware/labels-and-scanning/scanning).


# Print a label
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/printing

Pick a label template, choose a printer, and print barcode labels over the browser or print-server path.

The **Barcode Label** dialog lets you pick a barcode template, choose a printer, set the number of copies, preview the rendered label, and submit the print job. ION prints over one of two paths, set once for the org; see [print paths](/build-hardware/labels-and-scanning#print-paths). The dialog shows the printer picker for whichever path is configured.

## Prerequisites

Before you print a label, make sure you have:

* Permission to print labels for the entity type you're working with.
* A printer reachable from the printing mode your org uses.
* At least one barcode template configured for the entity type. An admin can add templates in **Settings > Organization > Barcode Labels**.

## Print a label

The **Barcode Label** dialog opens from the entity you want a label for. A part inventory record has a **Print Barcode** action, and a kit has a **Print kit label** action. On a run, a run step, or a run's created part inventory, the label printer opens on the **Print label** tab of a QR-code dialog, covered in [Print and share labels from a run](#print-and-share-labels-from-a-run). The dialog shows these controls and a preview:

* **Barcode Template** picks the barcode format and field layout. Templates are scoped to the entity type, so only valid templates appear.
* **Printer** picks which printer to send to. The picker varies based on org print mode.
* **Number of Label Copies** sets the number of duplicate labels to print (minimum 1).
* The preview has a **QR Code** tab and a **Full Label** tab so you can verify the encoding and the rendered label before submitting.

To print a label:

1. Set **Number of Label Copies**. The default is 1. Use copies when you need multiple identical labels, such as one per kit container or one per face of a packaged unit.
2. Open the **Barcode Template** dropdown and select the format you want. ION pre-selects the first available template. Adjust it if your downstream process expects a different one.
3. Open the **Printer** picker and choose the destination printer. The picker pulls printers from the active mode (browser or print server). If no printers appear, see [Troubleshooting](#troubleshooting).
4. Check the preview. The **Full Label** tab renders the label as the printer produces it, and the **QR Code** tab shows the encoded barcode. Confirm that the barcode and any human-readable fields look right.
5. Click **Print**. The button is disabled until a template with content, a printer, and at least one copy are all selected.

On success, ION shows a `Print job successful` toast. If a print is sent over Zebra Browser Print but the printer doesn't report its status (common over USB), ION shows a `Sent to printer (print not confirmed)` warning instead.

<Tip>
  Set **Number of Label Copies** to 1 for a verification print, then reopen the dialog and print the full quantity. This saves wasted stock when a template is wrong.
</Tip>

## Print and share labels from a run

A run, a run step, and a run's created part inventory each have a QR-code button. Click it to open a dialog with a **QR code** tab and a **Print label** tab.

* On the **QR code** tab, scan or copy the value. On a run or run step, the QR code links to the run or run step so a phone camera opens it in the browser. On a created part inventory, the QR code holds the serial number, and the copy control reads **Copy serial number**. When the part has no serial number, the code falls back to the lot number, then the part number.
* On the **Print label** tab, print a barcode label the same way as the **Barcode Label** dialog. A run or run step prints a **Runs** label, and a created part inventory prints an **Inventory** label. An admin configures these templates in **Settings > Organization > Barcode Labels**.

## Print labels for several records at once

Selecting rows in a table reveals a floating toolbar with a **Print Barcodes** action, which opens the **Barcode Label** dialog for the whole selection.

On the **Runs** page, **Print Barcodes** is a menu with two options, because a run and the inventory it produces take different templates:

* **Run labels** prints a **Runs** template for every selected run.
* **Part inventory labels (N)** prints an **Inventory** template for the selected runs that have a part inventory. N is that count, and the option is disabled when it's zero, so the label count always matches what you selected.

## Barcode formats

Each template encodes a specific format. If your scanners need a specific encoding, have an admin configure a template that produces it rather than reformatting it by hand. See [Create label templates](/build-hardware/labels-and-scanning/templating).

<Tip>
  When an admin adds a new template, scan a printed label with the scanner the floor uses. Encoding compatibility isn't always obvious from the preview.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to reach printer">
    If the **Printer** picker is disabled and shows **Failed to reach printer**, follow the steps for your print mode:

    * **Browser mode**: Confirm Zebra Browser Print is running on the workstation. Click the **Check the status** link next to the picker, which opens `https://localhost:9101/available` in a new tab, to verify the local print service is responding. If the page errors, restart Zebra Browser Print and reload ION.
    * **Print server mode**: Confirm the print server is reachable and the printer is registered with the print server. On persistent failure, escalate to an admin to verify print server health.
  </Accordion>

  <Accordion title="Labels print but barcodes won't scan">
    This is most often a template mismatch, where the template encoding doesn't match what your scanner expects. Try a different template. If no template scans correctly, request a template change from your admin.
  </Accordion>

  <Accordion title="Print started but nothing prints">
    If ION shows `Sent to printer (print not confirmed)`, check that the printer is powered on and connected. In print server mode, check the print server's job queue to see whether the job is queued, printing, or errored.
  </Accordion>
</AccordionGroup>


# Configure Zebra Browser Print
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/printing/configuring-printing-in-ion

Download Zebra Browser Print and connect it to ION for workstation-attached Zebra printer support.

1. Download [Zebra Browser Print](https://developer.zebra.com/products/printers/browser-print), available for both PCs and Macs.
2. Follow Zebra's [Browser Print installation instructions](https://supportcommunity.zebra.com/s/article/Installing-Zebra-Browser-Print-for-Mac?language=en_US). The article covers Mac, and the steps are nearly identical on a PC.
3. Select a default printer in the Browser Print settings.
4. In ION, go to **Settings > Organization > Barcode Labels** and make sure **Use print server** is off.
5. Open the **Barcode Label** dialog and select a printer in the **Printer** picker. Printers populate from the Zebra app. If you have not created a template yet, follow the steps in [Create label templates](/build-hardware/labels-and-scanning/templating).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Printers do not appear in the Barcode Label dialog">
    1. Make sure your computer and printer are on the same network. The browser can only reach printers on the same network.
    2. When the printers appear in the Zebra Browser Print application but not in the ION **Barcode Label** dialog, open the [Browser Print status page](https://localhost:9101/available) in a new tab. You might need to authorize the browser to connect to Zebra Browser Print. When the printer can't be reached, the **Printer** picker shows a **Check the status** link to this page.
  </Accordion>

  <Accordion title="Printers appear but printing errors">
    Printing to the default printer with Zebra Browser Print can fail. When printers show in the **Printer** picker but printing returns an error:

    * Add the printer manually in Zebra Browser Print under a different name.
    * Leave the printer unset as the default.
    * Select the printer you just added in the **Printer** picker when you print.
  </Accordion>
</AccordionGroup>


# Configure PrintNode server printing
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/printing/server-based-barcode-printing-printnode

Connect ION to PrintNode so printers are managed centrally and operators can print from any workstation without local setup.

Server printing connects the ION app to your printers via an online service called PrintNode. Configuration lives on a central server, so printers can be managed and updated centrally and new printers or users can be added without client-side changes.

This process requires configuring your printers, creating a PrintNode account, installing the PrintNode client, and entering an API key in your Org settings. You only need to set up the PrintNode client on the computer that will manage the printers once. If you prefer, you can also install the client on multiple computers to manage different parts of your printer fleet.

<Note>
  Please contact [support](https://support.firstresonance.io/) for details
  on activating the server printing option. You will not have access to this
  part of the setup until the First Resonance team has activated that option for
  you.
</Note>

<Note>
  The integration available through the ION Marketplace is intended for non-ITAR
  use only. ITAR-regulated customers may use this integration solely upon
  acknowledging that no ITAR-controlled data will be transmitted, stored, or
  printed, including on barcode labels. First Resonance assumes no
  responsibility for any unauthorized inclusion or handling of ITAR-controlled
  information.
</Note>

## Steps to set up

#### 1. Create a PrintNode Account

* Sign up at [PrintNode](https://www.printnode.com/).
* Start with a one-month free trial. A payment plan is available if you add your card.

#### 2. Install PrintNode Client

* Download and install the client on the machine that will manage the printers.
* Installation guides for different operating systems:
  * [Windows](https://www.printnode.com/en/docs/installation#windows)
  * [Mac](https://www.printnode.com/en/docs/installation#mac)
* When running the client, you should see the list of printers under the printers tab.

#### 3. Set Up Printers

Ensure to set up printers on the computer that will run the PrintNode client.

#### Internet Connection

* Obtain the printer's IP address by holding the feed and cancel buttons on the printer for 2 seconds and examining what’s printed out.

#### Windows Users

* Follow this [Windows guide ](https://supportcommunity.zebra.com/s/article/Adding-a-networked-Zebra-Printer-to-a-Windows-10-PC?language=en_US)to set up the printer over the network.

#### macOS Users

* Follow the [macOS guide](https://www.printnode.com/en/docs/raw-printing-for-osx) to set up the printer. Ensure the printer is set as **RAW**, not Zebra.

* Note: The guide assumes a USB connection. For step 5, choose **Internet Printing Protocol** within Other Network Printers instead:

* Input the IP address in the format `ipp://<printer-ip>/ipp/print`, for example `ipp://192.168.1.111/ipp/print`

* Follow the rest of the guide, ensuring to select **RAW** for the Make, not **Zebra**.

#### 5. Obtain API Key

* Go to your API keys page, log in, and find your API key.

#### 6. Configure ION App

* Navigate to **Settings → Organization → Barcode Labels**.

* Turn on the **Use print server** toggle.

* Enter your PrintNode API key in the **Print server API key** field.

Once these steps are completed, server-based printing will be enabled in your ION app across all pages.

#### 7. Support

* PrintNode is a separate service from First Resonance. For issues with your PrintNode account, the client, or printer connectivity, contact [PrintNode support](https://www.printnode.com/en/contact).
* For issues with the print server settings in ION, contact [First Resonance support](https://support.firstresonance.io/).


# Scanning
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/scanning

How barcode scanning works in ION and the scan-to-action workflows it enables.

ION listens for barcode scanner input across every screen. Scanning a barcode immediately identifies the object, a piece of inventory, a location, or a kit, and presents the actions available for it. Most workflows require only one or two scans.

## How scanning works

Barcode scanners that use the [HID specification](https://docs.microsoft.com/en-us/windows-hardware/drivers/hid/) send keystrokes to whatever window is active. ION detects scanner input by watching for keystrokes that arrive much faster than a human can type and treating the resulting string as a barcode.

For scanning to work:

* An ION tab must be open and focused in the browser.
* The scanner must be connected (USB or Bluetooth HID).
* The cursor must not be inside a text field when you scan. If the cursor is in a field, ION does not intercept the input.

Most USB and Bluetooth scanners work without any driver installation. A scanner that emulates a keyboard and appends a carriage return or line feed after each barcode is the standard expectation.

## Recommended scanners

Any HID-compliant barcode scanner works with ION. For evaluation and testing, the NADAMOO Wireless QR Code Scanner is a straightforward option.

## What can be scanned

ION recognizes three types of objects from a scan:

| Object        | What it identifies                                      |
| ------------- | ------------------------------------------------------- |
| **Inventory** | A specific part inventory record, serial or lot tracked |
| **Location**  | A bin, rack, or other location in the factory           |
| **Kit**       | A kit ready for delivery to a run                       |

Scanning a run barcode navigates you to that run but does not start a workflow.

## Scan feedback

Every scan produces immediate feedback. A banner appears showing what was recognized, the inventory status, and the current location. From the banner you can navigate directly to the scanned object's detail page.

After each scan, an audio chime confirms success or signals an error.

## Scan workflows

Scan workflows are intent-based: scan one object to set the intent, then scan a second object to execute. ION shows which scan to do next.

When a location or kit is held as the active selection, the workflow is **sticky**: you can scan additional inventories one after another without rescanning the location or kit each time. Scan the location again to exit the workflow.

### Move inventory to a location

Scan an inventory, then scan a destination location. The inventory moves to that location.

Scan more inventory before the location scan to move several at once. Each scanned item waits in a queue in the scan overlay, and the location scan commits them all.

To move several inventories to the same location in one pass, scan the destination location first to hold it as the active selection. Then scan each inventory. Each scan moves that inventory immediately. Scan the location again to release it.

#### Move part of a lot

When you scan the inventory first, each queued row carries an editable quantity, prefilled with the whole lot and showing the quantity available next to it. Type a lower number to move only part of that lot, then scan the destination location to commit. The field releases the cursor shortly after you stop typing, so your next scan registers without clicking away first.

* A row you leave alone moves its whole lot.
* A row you lowered splits: the quantity you entered moves to the destination, and the remainder stays where it was as a new lot. The moved piece keeps the barcode you scanned, so the label on it stays correct.
* A serial-tracked row is locked at one, since a serial number identifies a single unit.

A toast reports the new remainder lot and offers **Print barcode** for it, so the inventory left behind gets a label.

<Note>
  The quantity field is only offered in the inventory-first order. When you hold a
  location as the active selection and scan items into it, each scan still moves
  the whole lot immediately.
</Note>

### Move a kit to a location

Scan a kit, then scan a destination location. The kit moves to that location.

You can also scan a location first and then scan a kit. The kit moves to the held location.

The move sets the kit's own location, so it holds after a refresh, and it carries the kit's **Kitted** inventory with it. Inventory that has already been installed or consumed stays where it is. A kit that is **Delivered**, **Completed**, or **Canceled** can't be moved, and the scan reports that instead of reporting success.

### Add inventory to a kit

Scan an inventory, then scan a kit. The inventory is added to the kit.

To add several inventories to the same kit, scan the kit first to hold it as the active selection. Then scan each inventory. Scan the kit again to release it.

Inventory in **WIP** status cannot be kitted and will produce an error. Depending on your settings, WIP inventory linked to a purchase order line through an outside-processing run step is an exception and can be scanned into a kit. For more information, see [Allow kitting of WIP inventory for outside processing](/administration/supply-chain-settings/allow-wip-osp-kitting).

### Move a location (nest it under another location)

Scan a location to set it as the active selection. Then scan a different location as the destination. ION shows a confirmation prompt. Scan the destination location a second time to confirm, or scan anything else to cancel.

### Install inventory on a run (run execution screen only)

On the run execution screen, scanning an inventory automatically installs it on the as-built BOM (aBOM) for the active run step. No second scan is required.

This workflow only works when a run step with build requirements is selected. If no run step is active, the scan fails with an error.

For lot-tracked inventory, ION prompts you to confirm the quantity before completing the installation.

ION also supports [requiring barcode scanning for all installations](/administration/production-settings/require-barcode-scanning-for-installations), which disables manual inventory selection.

### Kit inventory on the kitting screen

On the kitting screen with an active kit open, scanning an inventory automatically adds it to the active kit. No second scan is required.

### Navigate to open runs from an inventory scan

Scanning an inventory anywhere in ION shows a link to any open runs that include that part. This is useful in queue-based workflows, such as a receiving inspection or NDE lab, where you scan a part from an incoming rack, navigate to the associated run, complete the run step, and move the part to the outgoing rack.

## Workflow reference

| Workflow                          | First scan | Second scan        | Notes                                                      |
| --------------------------------- | ---------- | ------------------ | ---------------------------------------------------------- |
| Move one inventory                | Inventory  | Location           | Lower the queued quantity to move part of a lot            |
| Move multiple inventories         | Location   | Inventory (repeat) | Scan location again to exit; each scan moves the whole lot |
| Move a kit                        | Kit        | Location           | Or scan location first, then kit                           |
| Add one inventory to a kit        | Inventory  | Kit                |                                                            |
| Add multiple inventories to a kit | Kit        | Inventory (repeat) | Scan kit again to exit                                     |
| Move a location                   | Location   | Different location | Requires scan-to-confirm                                   |
| Install inventory on a run        | Inventory  | None               | Run execution screen only; run step must be active         |
| Kit inventory from kitting screen | Inventory  | None               | Kitting screen only; kit must be active                    |

## Scanning barcodes from other systems

If your inventory carries barcodes from a supplier, ERP, or other system, you can configure ION to recognize those barcode formats. See [Scan barcodes from other systems](/build-hardware/labels-and-scanning/scanning/scan-barcodes-from-other-systems).


# Scan barcodes from other systems
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/scanning/scan-barcodes-from-other-systems

Configure ION to recognize barcodes from external systems using regex patterns or JSON field mappings.

By default, ION expects a specific format for internally defined barcodes, but you can also scan barcodes from other systems with some basic configuration.

Configuration is done through the API using the `createBarcodePattern` mutation. Each barcode pattern defines an `entityType` and either an `expression` (regex) or a `barcodePatternJson` (JSON field mapping). You cannot set both on the same pattern.

<Note>
  The two pattern types are also exclusive at scan time. When the scanned text is valid JSON, ION matches it against `barcodePatternJson` patterns only and skips every regex `expression` pattern, so a regex written against a JSON payload never matches. If your scanner emits JSON, use a JSON field mapping.
</Note>

## Using a regex expression

Use `expression` when your external barcode encodes data as a formatted string. ION uses [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) with named capture groups to extract field values from the scanned string.

### Regex example

Suppose you have an inventory barcode that follows a pattern similar to a [GS1 barcode](https://www.gs1.org/standards/barcodes/databar):

```
(01)<Part number>(17)(10)<Serial number>
```

The equivalent regular expression is:

```
\(01\)(?P<part_partNumber>.*)\(17\)\(10\)(?P<serialNumber>.*)
```

<Note>
  If your regex includes escape characters, double every backslash when passing the value as a JSON string. For example, `\(01\)` becomes `\\(01\\)` in the API input.
</Note>

Use the GraphQL explorer in ION to run this mutation:

```graphql theme={null}
mutation CreateBarcodePattern($input: CreateBarcodePatternInput!) {
    createBarcodePattern(input: $input) {
        barcodePattern {
          id
          _etag
          entityType
          expression
        }
    }
}
```

With these variables:

```json theme={null}
{
  "input": {
    "entityType": "PARTS_INVENTORY",
    "expression": "\\(01\\)(?P<part_partNumber>.*)\\(17\\)\\(10\\)(?P<serialNumber>.*)"
  }
}
```

## Using a JSON field mapping

Use `barcodePatternJson` when your external barcode scanner emits structured JSON rather than a formatted string. The value is a JSON string where each key is an ION field name and each value is the corresponding key in the scanned barcode's JSON payload.

Use the `part_` prefix to reference a field on the related part. For example, `part_partNumber` refers to the `partNumber` field of the inventory item's part.

### JSON field mapping example

Suppose your scanner emits:

```json theme={null}
{"pn": "EX-PART-001", "lot": "L-42"}
```

To map this to `PARTS_INVENTORY`, create a pattern that maps the scanner's keys to ION's field names:

```graphql theme={null}
mutation CreateBarcodePattern($input: CreateBarcodePatternInput!) {
    createBarcodePattern(input: $input) {
        barcodePattern {
          id
          _etag
          entityType
          barcodePatternJson
        }
    }
}
```

```json theme={null}
{
  "input": {
    "entityType": "PARTS_INVENTORY",
    "barcodePatternJson": "{\"part_partNumber\": \"pn\", \"lotNumber\": \"lot\"}"
  }
}
```

When ION scans a barcode that emits `{"pn": "EX-PART-001", "lot": "L-42"}`, it looks up the inventory item whose part number is `EX-PART-001` and lot number is `L-42`.

### Partial matching

Append a match mode suffix to an ION field name to match partial values:

| Suffix       | Behavior                                  |
| ------------ | ----------------------------------------- |
| `__prefix`   | Field value starts with the scanned value |
| `__suffix`   | Field value ends with the scanned value   |
| `__contains` | Field value contains the scanned value    |

For example, to match any part number that contains the scanned value:

```json theme={null}
{
  "input": {
    "entityType": "PARTS_INVENTORY",
    "barcodePatternJson": "{\"part_partNumber__contains\": \"pn\", \"lotNumber\": \"lot\"}"
  }
}
```

Match mode suffixes also work in regex patterns. Add the suffix to the field name inside the named capture group, for example `(?P<part_partNumber__prefix>.*)`.

### Ignoring barcode keys

A JSON pattern matches only when the scanned payload's keys, after removing the `_ignored` keys, exactly equal the set of keys you mapped. If your scanner emits keys that you don't use for matching, list them in the `_ignored` array:

```json theme={null}
{
  "input": {
    "entityType": "PARTS_INVENTORY",
    "barcodePatternJson": "{\"part_partNumber\": \"pn\", \"lotNumber\": \"lot\", \"_ignored\": [\"checksum\"]}"
  }
}
```

ION ignores the `checksum` key in the scanned JSON and matches only on `pn` and `lot`.

<Warning>
  Account for every key in the payload. A key you neither map nor add to `_ignored` causes the pattern to silently fail to match. When your scans don't resolve, first check that the mapped keys plus `_ignored` cover the full set of keys in the scanned JSON.
</Warning>

<Note>
  The `iuid` key is reserved for ION's own barcode labels and can't appear in a JSON field mapping. When a scanned payload contains an `iuid` key, in any letter case, ION uses it to look up the matching ION label directly and doesn't evaluate custom patterns. If the `iuid` value isn't exactly 32 characters, the scan fails with a validation error, so don't use `iuid` as a key name in external barcodes.
</Note>

## List existing patterns

To retrieve all barcode patterns configured for your organization:

```graphql theme={null}
{
  barcodePatterns {
    edges {
      node {
        expression
        barcodePatternJson
        entityType
        id
        _etag
      }
    }
  }
}
```


# Create label templates
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/templating

Author ZPL barcode label templates in organization settings using variables to inject entity data like serial numbers, part numbers, and run IDs.

1. Go to **Settings → Organization → Barcode Labels** and use the **Inventory**, **Kits**, **Locations**, and **Runs** tabs under **Label templates** to choose which entity type a template applies to.
2. Render your ZPL with the open source [Labelary](http://labelary.com/viewer.html) service to get the sizing and spacing correct.
3. Insert variables to inject record data. Templates use a syntax like `${serialNumber}`; the **Available Fields** panel to the left of the **ZPL Template** editor lists every variable you can use, and clicking a field inserts it at the cursor.
4. Set the template's name, print density (DPI), and label height and width under **Template Settings**.
5. Click **Create Template** for a new template or **Save Template** for an existing one.

Use **Deactivate** to retire a template you no longer need.

<Frame>
  <img alt="Barcode Labels editor showing a ZPL template with variable placeholders, the Available Fields variable list, and Template Settings for print density and label dimensions." />
</Frame>


# Sample templates
Source: https://docs.firstresonance.io/build-hardware/labels-and-scanning/templating/sample-templates

Starting-point ZPL label templates for inventory, kit, and location labels to copy and adapt for your org.

These are a few basic templates built with a barcode and text. Copy one and adapt it for your org:

<Tabs>
  <Tab title="Inventory Labels">
    ```
    ^XA
    ^PW211^FO55,30^BQN,2,3^FDQA,S1033^FS
    ^FT0,170^A0,30^FB211,1,0,C,0^FH\^FDPN:${part.partNumber}^FS
    ^XZ
    ```

    ```
    ^XA

    Logo:
    ^FO520,35^GFA,2470,2470,13,Q01F8,Q0IF,P07IFE,O01KF8,O03KFC,O0MF,N01MF8,N03MFC,:N07MFE,N0OF,:M01OF8,:M03OFC,::::M07OFE,::::M03OFC,:::M01OF8,:N0OF,:N07MFE,:N03MFC,N01MF8,O0MF,O07KFE,O01KF8,P0KF,P01IF8,Q03FC,,::::::::::::N0IFE07IF,O0306001C3,O0106I083,::O0306I083,O0706I083,O0F06I083,N0398CJ03,N070FC,N0C078,,S07IF,,N0IFE,N0E38E,N0C106,N0C10607IF,:N0C106I083,:::T0183,T0783,T0EC3,N03830038E6,N070FC0707C,N040CC,N0C186,:N0C10601C3C,N0C1060307E,N0C30602043,N0430C060C3,N07E1C060C3,N03C1006083,S06083,S06183,O07C00318E,N01FF003F0C,N0301800E,N0600C,N0C004J03,N0C006J03,:::N0C00407IF,N0600C03IF,N03838J03,N01FFK03,O038K03,V03,,:N0IFE,P01E,P018,P07,O01C,O038,O0E,N01C,N07,N0F,N0IFE,,::N0E,N07C,O0F8,O0DE,O087C,O081E,:O08F8,O0FC,N01F,N078,N0C,,:N0IFC,N0IFE,P01C,P038,P0F,O01C,O07,O0E,N038,N07,N0IFE,:,::O0FE,N03FF8,N0701C,N0600C,N0C006,::::N0600C,N0701C,N03818,,::N0IFC,N0IFE,N0C106,:::::::,::::::::::^FS

    ^PW576^FO12,75^BQN,2,3^FDQA,S1033^FS
    ^FO12,35^A0,45^FD${part.partNumber}^FS
    ^FO130,85^A0,32^FDRev: ${part.revision}^FS
    ^FO130,125^A0,25^FD${part.description}^FS
    ^FO130,155^A0,25^FDSN: ${serialNumber}^FS
    ^FO330,155^A0,25^FDLot: ${lotNumber}^FS
    ^XZ
    ```

    ```
    ^XA
    ^PW576
    ^CFA,15
    ^FX Company Logo
    ^FO0,2
    ^GFA,2470,2470,13,Q01F8,Q0IF,P07IFE,O01KF8,O03KFC,O0MF,N01MF8,N03MFC,:N07MFE,N0OF,:M01OF8,:M03OFC,::::M07OFE,::::M03OFC,:::M01OF8,:N0OF,:N07MFE,:N03MFC,N01MF8,O0MF,O07KFE,O01KF8,P0KF,P01IF8,Q03FC,,::::::::::::N0IFE07IF,O0306001C3,O0106I083,::O0306I083,O0706I083,O0F06I083,N0398CJ03,N070FC,N0C078,,S07IF,,N0IFE,N0E38E,N0C106,N0C10607IF,:N0C106I083,:::T0183,T0783,T0EC3,N03830038E6,N070FC0707C,N040CC,N0C186,:N0C10601C3C,N0C1060307E,N0C30602043,N0430C060C3,N07E1C060C3,N03C1006083,S06083,S06183,O07C00318E,N01FF003F0C,N0301800E,N0600C,N0C004J03,N0C006J03,:::N0C00407IF,N0600C03IF,N03838J03,N01FFK03,O038K03,V03,,:N0IFE,P01E,P018,P07,O01C,O038,O0E,N01C,N07,N0F,N0IFE,,::N0E,N07C,O0F8,O0DE,O087C,O081E,:O08F8,O0FC,N01F,N078,N0C,,:N0IFC,N0IFE,P01C,P038,P0F,O01C,O07,O0E,N038,N07,N0IFE,:,::O0FE,N03FF8,N0701C,N0600C,N0C006,::::N0600C,N0701C,N03818,,::N0IFC,N0IFE,N0C106,:::::::,::::::::::^FS
    ^FX Text Part Detail Section
    ^FO 80,2  ^FD ${part.description} ^FS
    ^FO 80,22  ^FD P/N: ${part.partNumber} ^FS
    ^FO 80,47  ^FD UOM: ${unitOfMeasure.type} ^FS
    ^FO 80,72  ^FD PO: ^FS
    ^FO 80,97 ^FD S/N: ${serialNumber} ^FS
    ^FO 80,122 ^FD Lot: ${lotNumber} ^FS
    ^FO 80,147  ^FD Custom Attribute: XX"^FS
    ^FO 80,172 ^FD Custom Attribute: XX^FS
    ^FX Status and Part Revision
    ^FO 380,20^GB50,50,6^FS
    ^FO 380,38 ^FD XX^FS
    ^FO 380,75^GB50,50,3^FS
    ^FO 380,85 ^FD Rev^FS
    ^FO 380,105 ^FD ${part.revision}^FS
    ^FX QR Code
    ^FO 450,20 ^BQN,2,3,Q,7 ^FDQA,${iuid}^FS
    ^FO 380, 135 ^FD Qty: ${quantity} ^FS
    ^FO 380, 155 ^FD UID: ${id} ^FS
    ^XZ
    ```
  </Tab>

  <Tab title="Kit Labels">
    ```
    ^XA
    ^PW211^FO55,30^BQN,2,3^FDQA,S1033^FS
    ^FT0,170^A0,30^FB211,1,0,C,0^FH^FDKit #:${id}^FS
    ^XZ
    ```

    ```
    ^XA

    Logo:
    ^FO520,35^GFA,2470,2470,13,Q01F8,Q0IF,P07IFE,O01KF8,O03KFC,O0MF,N01MF8,N03MFC,:N07MFE,N0OF,:M01OF8,:M03OFC,::::M07OFE,::::M03OFC,:::M01OF8,:N0OF,:N07MFE,:N03MFC,N01MF8,O0MF,O07KFE,O01KF8,P0KF,P01IF8,Q03FC,,::::::::::::N0IFE07IF,O0306001C3,O0106I083,::O0306I083,O0706I083,O0F06I083,N0398CJ03,N070FC,N0C078,,S07IF,,N0IFE,N0E38E,N0C106,N0C10607IF,:N0C106I083,:::T0183,T0783,T0EC3,N03830038E6,N070FC0707C,N040CC,N0C186,:N0C10601C3C,N0C1060307E,N0C30602043,N0430C060C3,N07E1C060C3,N03C1006083,S06083,S06183,O07C00318E,N01FF003F0C,N0301800E,N0600C,N0C004J03,N0C006J03,:::N0C00407IF,N0600C03IF,N03838J03,N01FFK03,O038K03,V03,,:N0IFE,P01E,P018,P07,O01C,O038,O0E,N01C,N07,N0F,N0IFE,,::N0E,N07C,O0F8,O0DE,O087C,O081E,:O08F8,O0FC,N01F,N078,N0C,,:N0IFC,N0IFE,P01C,P038,P0F,O01C,O07,O0E,N038,N07,N0IFE,:,::O0FE,N03FF8,N0701C,N0600C,N0C006,::::N0600C,N0701C,N03818,,::N0IFC,N0IFE,N0C106,:::::::,::::::::::^FS

    ^PW576^FO12,105^BQN,2,2^FDQA,S1033^FS
    ^FO12,35^A0,45^FDKit #: ${id}^FS
    ^FO330,35^A0,45^FDRUN-${runId}^FS
    ^FO12,85^A0,25^FD${run.title}^FS
    ^FO100,125^A0,25^FDCreated By: ${createdBy.name}^FS
    ^FO100,155^A0,25^FDDeliver To: ${deliveryLocation.name}^FS

    ^XZ
    ```
  </Tab>

  <Tab title="Location Labels">
    ```
    ^XA
    ^PW211^FO55,30^BQN,2,3^FDQA,S1033^FS
    ^FT0,170^A0,30^FB211,1,0,C,0^FH^FD${name}^FS
    ^XZ
    ```

    ```
    ^XA

    Logo:
    ^FO520,35^GFA,2470,2470,13,Q01F8,Q0IF,P07IFE,O01KF8,O03KFC,O0MF,N01MF8,N03MFC,:N07MFE,N0OF,:M01OF8,:M03OFC,::::M07OFE,::::M03OFC,:::M01OF8,:N0OF,:N07MFE,:N03MFC,N01MF8,O0MF,O07KFE,O01KF8,P0KF,P01IF8,Q03FC,,::::::::::::N0IFE07IF,O0306001C3,O0106I083,::O0306I083,O0706I083,O0F06I083,N0398CJ03,N070FC,N0C078,,S07IF,,N0IFE,N0E38E,N0C106,N0C10607IF,:N0C106I083,:::T0183,T0783,T0EC3,N03830038E6,N070FC0707C,N040CC,N0C186,:N0C10601C3C,N0C1060307E,N0C30602043,N0430C060C3,N07E1C060C3,N03C1006083,S06083,S06183,O07C00318E,N01FF003F0C,N0301800E,N0600C,N0C004J03,N0C006J03,:::N0C00407IF,N0600C03IF,N03838J03,N01FFK03,O038K03,V03,,:N0IFE,P01E,P018,P07,O01C,O038,O0E,N01C,N07,N0F,N0IFE,,::N0E,N07C,O0F8,O0DE,O087C,O081E,:O08F8,O0FC,N01F,N078,N0C,,:N0IFC,N0IFE,P01C,P038,P0F,O01C,O07,O0E,N038,N07,N0IFE,:,::O0FE,N03FF8,N0701C,N0600C,N0C006,::::N0600C,N0701C,N03818,,::N0IFC,N0IFE,N0C106,:::::::,::::::::::^FS

    ^PW576^FO12,25^BQN,2,3^FDQA,S1033^FS

    ^FO120,35^A0,45^FD${locationSubtype.name}: ${name}^FS
    ^FO120,85^A0,25^FD${parent.type}: ${parent.name}^FS
    ^FO120,115^A0,25^FD ${address}^FS
     

    ^XZ
    ```
  </Tab>
</Tabs>

Use [Labelary](http://labelary.com/) to add an image for your logo or any other image. The image is encoded as a Base64 string. To understand the code, see the Zebra [ZPL programming guide](https://www.zebra.com/content/dam/zebra_new_ia/en-us/manuals/printers/common/programming/zpl-zbi2-pm-en.pdf).

<Note>
  The QR code field includes "QA," so all characters show up in the barcode. For details, see [QR code missing first three characters in ZPL](https://www.zebra.com/us/en/support-downloads/knowledge-articles/ait/QR-code-missing-first-three-characters-when-using-ZPL-language.html).
</Note>


# Overview
Source: https://docs.firstresonance.io/build-hardware/locations-and-work-centers/index

How ION models your factory: locations, their types and hierarchy, and the work center as a location that executes runs.

A location is a place where inventory sits or where work happens. Locations model the physical map of your factory, and every [inventory](/manage-supply-chain/inventory) transaction records the location it happened at. You manage locations from the **Factory** area in the **Production** section of the sidebar. For the steps, see [Manage locations](/build-hardware/locations-and-work-centers/manage-locations). Together, the location tree is your factory in ION.

## Types and hierarchy

Each location has a **Type**: Warehouse, Rack, Shelf, Tote, or Workcenter. The type tags what a location is; it does not restrict nesting.

Locations nest into a tree through the **Parent Location** field, mirroring your building: a warehouse contains racks, a rack contains shelves, a shelf contains totes. Root locations sit at the top of the Factory tree, and each child rolls up under its parent. To build and reorganize the tree, see [Organize locations into a hierarchy](/build-hardware/locations-and-work-centers/manage-locations#organize-locations-into-a-hierarchy).

## Work centers

A work center is a location whose **Type** is **Workcenter**. There is no separate work-center record, so you create one by creating or editing a location. A work center is where runs and run steps are executed: run steps route to a work center, its capacity feeds scheduling, and operators work its queue of due steps. To designate one and run work there, see [Set up a work center](/build-hardware/locations-and-work-centers/set-up-a-work-center).

## Fields

| Field                                | Notes                                                                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                             | Location name. Required. Sort order drives the kit picklist pick path, so sortable names such as `A1-01` produce a sensible sequence. |
| **Type**                             | `Warehouse`, `Rack`, `Shelf`, `Tote`, or `Workcenter`.                                                                                |
| **Description**                      | Free text.                                                                                                                            |
| **Parent Location**                  | Sets the location's place in the hierarchy.                                                                                           |
| **Supervisor**                       | The person responsible for the location.                                                                                              |
| **Inventory Available**              | Controls whether inventory can be stored here.                                                                                        |
| **Exclude from Inventory Merge**     | Keeps this location's inventory from auto-merging.                                                                                    |
| **Address**                          | Optional. Postal address, used for bill-to and ship-to on purchase orders.                                                            |
| **Geolocation Latitude / Longitude** | Optional coordinates.                                                                                                                 |
| **Image**                            | Optional. A thumbnail for visual identification.                                                                                      |

A location's status (**Active** or **Archived**) shows as a badge and changes with the **Archive** or **Unarchive** action, not as a field.

<Tip>
  Your org can add **custom attributes** to locations for data the built-in fields don't cover. See [Custom attributes](/administration/custom-attributes).
</Tip>

## How locations are used

* **Inventory**: every inventory transaction has a location, so on-hand quantity is always tied to a place. **Inventory Available** and **Exclude from Inventory Merge** govern what can rest and merge there.
* **Runs and execution**: run steps are worked at a work center, and its queue buckets steps into Overdue, Now, Next, and Blocked. See [Run steps at a work center](/build-hardware/runs-and-execution/workcenter-execution).
* **Scheduling**: work-center capacity feeds [run scheduling](/build-hardware/runs-and-execution/scheduling).
* **Kitting**: kits are addressed to a destination location.
* **Barcodes**: locations carry barcode labels for scanning. See [Print a label](/build-hardware/labels-and-scanning/printing).

## Lifecycle

ION never deletes a location that carries history: archiving hides it from active use while keeping its transactions intact, and you can unarchive it later. Deletion is permanent, requires the `DeleteLocation` permission, and is blocked for a location set as your org's default bill-to or ship-to. For the actions, see [Archive or delete a location](/build-hardware/locations-and-work-centers/manage-locations#archive-or-delete-a-location).


# Manage locations
Source: https://docs.firstresonance.io/build-hardware/locations-and-work-centers/manage-locations

Create locations, organize them into a hierarchy, edit their details, and archive or delete them from the Factory area.

You manage locations from the **Factory** area: in the **Production** section of the sidebar, click **Factory**. The Factory page lists your locations as an expandable tree, with root locations at the top.

## Create a location

1. On the **Factory** page, click **Create Location**.
2. Enter a **Name** (required). Optionally fill in **Description**, **Address**, **Image**, **Geolocation Latitude**, and **Geolocation Longitude**.
3. Choose a **Type**: Warehouse, Rack, Shelf, Tote, or Workcenter.
4. Optionally pick a **Supervisor** and a **Parent Location**.
5. Set **Inventory Available** to control whether inventory can be stored here, and **Exclude from Inventory Merge** to keep this location's inventory from auto-merging.
6. Click **Create Location**.

ION opens the new location's detail page.

## Organize locations into a hierarchy

Set a location's place in the tree with the **Parent Location** field, either when you create it or later from its detail page.

To add a child under an existing location, open that location and use the **Create Location** button in its **Sub Locations** card. The new location's parent is filled in for you. On the Factory page, expand a row to see its children.

<Tip>
  Names that sort cleanly hold up as the factory grows. Use sortable names such as `A1-01` through `A1-99` so the kit picklist, which relies on sort order, produces a sensible pick path. Match the hierarchy to the building (warehouse, zone, rack, shelf, bin), and reserve recurring special names once, such as In-transit, Receiving dock, Quarantine, and Scrap.
</Tip>

## Edit a location

Open a location from the Factory page to reach its detail page. Fields in the **Location Information** card are editable in place and save automatically as you change them. You can update the name, description, address, image, geolocation, type, supervisor, parent, and the inventory toggles.

If your org has defined location custom attributes, their values are editable at the bottom of the **Location Information** card. To define which custom attributes exist, see [Custom attributes](/administration/custom-attributes).

To print barcode labels for one or more locations, select them on the Factory page and click **Print Barcodes**. For label setup, see [Print a label](/build-hardware/labels-and-scanning/printing).

## Archive or delete a location

On a location's detail page, open the **Location actions** menu (the **...** menu):

* **Archive Location** hides the location from active use without removing its history. An archived location shows an **Archived** badge; use **Unarchive Location** to restore it.
* **Delete Location** removes the location permanently. Deletion requires the `DeleteLocation` permission and can't be undone. You can't delete a location that's set as your organization's default bill-to or ship-to in the purchase order settings.

## Related

* [Set up a work center](/build-hardware/locations-and-work-centers/set-up-a-work-center)
* [Custom attributes](/administration/custom-attributes)


# Set up a work center
Source: https://docs.firstresonance.io/build-hardware/locations-and-work-centers/set-up-a-work-center

Designate a location as a work center so operators can execute runs and run steps there.

A work center is a location whose **Type** is set to **Workcenter**. Because there is no separate work-center record, you set one up by creating or editing a location. See the [Locations and work centers overview](/build-hardware/locations-and-work-centers#work-centers) for how work centers fit the location model.

## Designate a work center

1. In the **Production** section of the sidebar, click **Factory**.
2. Create a new location with **Create Location**, or open an existing one.
3. Set **Type** to **Workcenter**, then save. (On a new location, click **Create Location**; on an existing one, the change saves automatically.)

Give work centers names that distinguish them from broad areas. "Final Assembly" is an area, while "Final Assembly Cell A" is a work center. Conflating the two muddles scheduling.

## Run work at a work center

Once a location is a work center, operators can execute against it:

* From the work center's detail page, click **Go to Execution** to open its run-step queue.
* From the run workspace, use the **Workcenter** shortcut to open a work center's queue. The picker groups work centers under **My Workcenter**, **Recent**, and **All Workcenters**.

The queue buckets the work center's run steps into **Overdue**, **Now**, **Next**, and **Blocked**. For how operators work this queue, see [Run steps at a work center](/build-hardware/runs-and-execution/workcenter-execution).

## Related

* [Manage locations](/build-hardware/locations-and-work-centers/manage-locations)
* [Run steps at a work center](/build-hardware/runs-and-execution/workcenter-execution)


# Manage parts
Source: https://docs.firstresonance.io/build-hardware/parts/creating-managing

Add a part to the Parts Library, edit it through its lifecycle, manage revisions, and archive parts that are out of production.

## Create a part

1. Navigate to **Parts Library** from the main nav.
2. Click **Create Part**.
3. Fill in the fields in the **Create Part** dialog:
   * **Part Number** (required): your org's identifier for the part.
   * **Description**: a short description of the part.
   * **Revision Scheme** (required): the scheme that governs how this part's revision values increment, such as `A`, `B`, `C` or `1`, `2`, `3`. See [Set a part's revision scheme](/build-hardware/parts/revision-schemes).
   * **Revision**: the starting revision value. Leave it blank to start at the scheme's first value.
   * **Purchase Type** (required): how the part behaves when purchased. Options are **Creates inventory**, **Does Not Create Inventory, Physically Received**, and **Does Not Create Inventory, Digitally Received**.
   * **Sourcing Strategy**: **Buy**, **Make**, **Dual source**, or **None**.
   * **Tracking**: **LOT**, **SERIAL**, or **None**. See [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking) before you pick.
   * **Unit of Measure**: the unit the part is counted or measured in.
4. Click **Create Part**. The new part has the status **Released**, and ION opens the new part's page.
5. On the part page, fill in the remaining fields you need, such as **Cost**, **Lead Time**, **Reorder Point Minimum**, **Reorder Point Maximum**, and an **Image** for visual identification. Each field saves on its own as you edit it.

<Note>
  To create a second part that shares a part number, create it under a different revision.
</Note>

## Read a part page

A part page opens with its identity and a set of counts, then the sections that carry the part's relationships.

* The identity header holds the part image, the part number, the part's status, its tracking type, an editable description, and the revision strip. The revision strip lists the part's revisions in order and marks the current one **· current**. Past six revisions the middle collapses; open it to see them all. **New revision** sits at the end of the strip.
* The vitals strip is six counts, each a link into the section it summarizes: **On hand** (with whether it's above or below the reorder minimum), **PO lines**, **Runs**, **Where-used**, **Suppliers**, and **mBOM**. **mBOM** counts the part's own mBOM versions; **Where-used** counts the assemblies whose mBOM lists this part.
* **On this part** is a jump list of the page's sections with a count on each: **Overview**, **Part Information**, **mBOM**, **Parent Assemblies**, **Procedures**, **Quality Clauses**, **Suppliers**, **Inventory**, **Purchase Orders**, **Kits**, **Issues**, and **Runs**.
* The context panel holds **Attachments**, **Comments**, and **Labels**, each with a count. On a part that has an mBOM, a **Reviews** section joins them with that mBOM version's approval summary; **Open Review Panel →** opens the mBOM review drawer for approvals and feedback.

The mBOM section's parts table is editable only while the mBOM version is in **Draft**. In any other status it carries a **Read-only** badge whose tooltip names the reason, and the table and **New Part** control are disabled.

## Edit a part

Open the part from the Parts Library. **Part Information** and the part's custom attributes render as label and value rows; click a value to edit it in place, and each field saves on its own. Empty custom attributes collapse behind **Show all**. **Part Information** includes **Part Number**, **Description**, **Revision Scheme**, **Purchase Type**, **Lead Time**, **Unit of Measurement**, **Cost**, **Tracking**, **Sourcing Strategy**, **Reorder Point Minimum**, **Reorder Point Maximum**, and **Image**. Some fields have downstream consequences:

* **Tracking**: changing this after inventory exists is constrained. ION blocks switches that would invalidate existing inventory.
* **Sourcing Strategy**: **Buy**, **Make**, or **Dual source** determines how procurement and planning treat the part.
* **Cost**: propagates to BOM cost rollups and inventory valuation.

The **Revision** field is read-only on the part page. To change a revision, create a new revision or [change the revision scheme](/build-hardware/parts/revision-schemes).

If two people edit the same part at the same time, ION rejects the second save. Reload the part and reapply your change.

## Create a revision

To create a new revision:

1. Open the existing part.
2. Click **Create New Revision**.
3. ION creates the new part record at the next revision in the scheme, links it to the previous revision, copies forward editable fields, and opens the new revision's page. Edit anything that the design change requires.

## Archive a part

When a part is out of production:

1. Open the part.
2. Click **Archive**.

The part's status changes to **Archived**, and the button becomes **Release** so you can reverse it. The part stays searchable and historical references stay intact, but by default it's filtered out of active-part pickers, such as BOM line creation and PO line creation.

<Warning>
  Don't delete parts. ION archives parts instead of deleting them because runs, issues, BOMs, POs, and inventory all reference the part. Deleting a part would orphan years of history.
</Warning>

## Bulk operations

For large-scale changes, such as importing a thousand parts from an ERP, use [ION Importers](/administration/ion-importers). It gives you a dry-run mode to preview the effect before you apply it.

For programmatic part management, see [Common queries: create a part](/api-reference/examples).

## Related

* [Set a part's revision scheme](/build-hardware/parts/revision-schemes)
* [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking)
* [Bills of Materials](/build-hardware/bills-of-materials)
* [ION Importers](/administration/ion-importers)


# Overview
Source: https://docs.firstresonance.io/build-hardware/parts/index

How ION models a part: its identity, revisions, fields, tracking type, and link to physical inventory.

A part is a definition, not a physical object. The physical units that exist against it are [inventory](/manage-supply-chain/inventory), and one part can back many inventory records across locations, each a serial, a lot, or a plain quantity.

You curate the definition in the Parts Library and act on the physical units in Inventory. Bills of materials, procedures, runs, purchase orders, and issues all reference parts. To reach a part's on-hand stock, see [Search parts and reach inventory](/build-hardware/parts/inventory-search).

## Identity and revisions

A part number and its revision together identify a part. The same part number can repeat only under a different revision.

A revision captures an engineering change. Creating one makes a new part record linked to the old, so history stays intact: runs and BOMs already built against the earlier revision keep pointing to it, while new builds pick up the latest. You retire an old revision by archiving it once nothing in flight still needs it.

A revision scheme sets how revision values count up, such as `A`, `B`, `C`; `1`, `2`, `3`; or `00-1`, `00-2`. You define schemes once for the org and assign one to each part, and a new part starts at the scheme's first value. To move a part onto a different scheme, either cast it to carry the current revision into the new sequence, or reset it to start over at the new scheme's first value. For the steps, see [Set a part's revision scheme](/build-hardware/parts/revision-schemes).

## Fields

| Field                               | Notes                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Part Number**                     | Org-unique within revision. Required.                                                                                                |
| **Revision**                        | Engineering revision value from the part's revision scheme. Read-only on the part page.                                              |
| **Description**                     | Free text.                                                                                                                           |
| **Revision Scheme**                 | Governs how this part's revision values increment. Required.                                                                         |
| **Tracking**                        | `LOT`, `SERIAL`, or `None`. See [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking).                                |
| **Purchase Type**                   | `Creates inventory`, `Does Not Create Inventory, Physically Received`, or `Does Not Create Inventory, Digitally Received`. Required. |
| **Sourcing Strategy**               | `Make`, `Buy`, or `Dual source`. Drives MRP and procurement.                                                                         |
| **Cost**                            | Optional. Feeds BOM rollups and inventory valuation.                                                                                 |
| **Lead Time**                       | Optional. Drives reorder timing and Autoplan.                                                                                        |
| **Maintenance Interval**            | Optional. Shown only for `Tool` parts that need scheduled maintenance.                                                               |
| **Unit of Measurement**             | Optional. The unit the part is counted or measured in.                                                                               |
| **Reorder Point Minimum / Maximum** | Optional. Triggers reorder workflows when on-hand drops below the minimum.                                                           |
| **Image**                           | Optional. A thumbnail for visual identification.                                                                                     |

A part's status (**Released** or **Archived**) shows in the page header and changes with the **Archive** or **Release** action, not as a field. Supplier part numbers live in the **Suppliers** section of the part page; see [Manage parts](/build-hardware/parts/creating-managing).

<Tip>
  Your org can add **custom attributes** to parts for data the built-in fields don't cover. See [Custom attributes](/administration/custom-attributes).
</Tip>

## Tracking types

A part's tracking type, set in the **Tracking** field, decides how ION identifies and traces each unit:

* **Serial**: every unit gets a unique serial number.
* **Lot**: units move in batches under a shared lot number.
* **Untracked**: ION tracks only the count.

Tracking type reaches into receiving, inventory, installs, run history, issues, and traceability, and each type behaves differently across all of them. Set it before any inventory exists, because switching once stock is on hand is constrained. For the downstream differences, number generation, and switching rules, see [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking).

## Lifecycle

A part is **Released** when you create it and **Archived** when it leaves production. ION never deletes a part, because runs, issues, BOMs, purchase orders, and inventory all point back to it. Archiving preserves that history and hides the part from active pickers, such as BOM and PO lines. You can release an archived part again at any time.


# Search parts and reach inventory
Source: https://docs.firstresonance.io/build-hardware/parts/inventory-search

Search and filter the Parts Library, then navigate from a part to its on-hand inventory.

The Parts Library lets you search across a part's identifying fields, filter by fields such as status and tracking type, and navigate from a part to its on-hand inventory.

## Search the Parts Library

The **search bar** at the top of the Parts Library, with the placeholder `Search part #, description, revision, supplier part #...`, matches against:

* Part number.
* Description.
* Revision.
* The part's supplier part number.
* Any supplier part number on the part's linked suppliers.

Search matches a substring anywhere in any of those fields and is case-insensitive, and a part matching in any one of them is returned. To filter on custom attributes or other fields, use the filter panel instead.

<Tip>
  Typing a partial value works: `BRKT` returns every part with `BRKT` anywhere in
  one of the fields above, such as its part number or its description.
</Tip>

## Filter the Parts Library

Open the filter panel from the Parts Library toolbar. Common filters:

| Filter                                        | Use for                                                                 |
| --------------------------------------------- | ----------------------------------------------------------------------- |
| **Status**                                    | Show only `RELEASED` or only `ARCHIVED` parts.                          |
| **Part Type**                                 | Separate `PART` from `TOOL`.                                            |
| **Tracking Type**                             | Find all serialized parts (`SERIAL`), or all lot-tracked parts (`LOT`). |
| **Sourcing Strategy**                         | `MAKE`, `BUY`, or `DUAL_SOURCE`.                                        |
| **Purchase Type**                             | Narrow by how the part behaves when purchased.                          |
| **Cost** / **Lead Time**                      | Numeric ranges for planning and procurement.                            |
| **Reorder Point Min** / **Reorder Point Max** | Find parts by their reorder thresholds.                                 |
| **Attributes**                                | Filter on the org's custom part attributes.                             |
| **Parts Inventory**                           | Filter parts by their inventory, including supplier.                    |
| **Created** / **Updated**                     | Recently added or recently changed parts.                               |
| **Created By** / **Updated By**               | Who created or last changed the part.                                   |

Filters compound. Each filter you add narrows the list further.

### Build a filter

The filter panel is the same builder ION uses on most of its tables, including Inventory, Runs, Issues, Procedures, Kits, Purchases, Suppliers, Tools, Standard Steps, and the user list in Settings. What you learn here carries over.

Each condition takes a full-width line for the field, with the operator, the value, and the remove control on the line beneath it. A nested field shows its leaf name with the path to it as a muted prefix, so a long path can't crowd out the value.

1. Click **Add condition** and pick the field to filter on.
2. Pick the operator, then enter or select the value.
3. Repeat for each condition you need.
4. Click **Filter** to apply the set. The panel closes and the table updates.

Nothing you build takes effect until you click **Filter**, so you can add, edit, and remove conditions freely and the table stays as it was. Closing the panel without clicking **Filter** discards the conditions you staged.

### Enter several values with Is in

The **Is in** operator matches a field against a list of values. On a field with no picker, such as a serial number or another free-text identifier, the value control reads **Add values...** and opens a box for entering them:

* Type a value and press **Enter**, or type a comma, to add it as a removable chip. The field keeps focus, so you can enter values one after another.
* Paste a comma-separated list to add several at once.
* Remove a chip with its **X**, or press **Backspace** in an empty field to drop the last one.
* Blank and duplicate values are ignored.

The control's trigger reads **Selected (N)** once values are in. On a whole-number field, only whole numbers within the 32-bit range are accepted, and anything else stays in the field for you to correct. On a per-column filter, **Apply** stays disabled while the list is empty, because an empty list matches nothing.

### Combine conditions

The **Match** control at the top of a group decides how its conditions combine: **All** requires every condition, **Any** requires at least one. The rail beside the conditions reflects the choice, reading **Where** on the first condition and then **and** or **or**.

To express something the flat list can't, click **Add condition group** for a nested group with its own **Match** control and its own remove control. Separate groups always combine with **All**.

<Frame>
  <img alt="Filter panel titled Filters with Clear All, a Match All of the following control, a Part Type Equals PART condition, an Attributes Lifecycle Phase Is null condition with True and False options, a nested condition group with its own Match All control containing Tracking Type Equals LOT, Add condition and Add condition group buttons, and a Filter button" />
</Frame>

**Clear All** is the exception to that. It empties the whole set and applies the change straight away, closing the panel and returning the table to unfiltered.

### Save a filter view

You can save a filter combination as a view. With a filter set applied, open the bookmark dropdown in the table toolbar and click **Save Current View**, then name it. The view appears in that same dropdown for reuse. To manage a saved view, use **Edit View**, **Duplicate View**, **Share View**, or **Delete View** in the same dropdown.

## Reach inventory from a part

Every part page has an **Inventory** card. It opens with summary counts (**Quantity Available**, **Quantity Installed**, **Quantity WIP**, and **Quantity On Order**) above a table of that part's inventory:

* **ID**: the inventory line's identifier.
* **Status**: the inventory line's state, such as available, installed, or WIP.
* **Location**: where the inventory sits.
* **Quantity**: the on-hand quantity for that line.

Click the **ID** of any row to open that inventory record on the Inventory page, where you can move, adjust, split, merge, or print it. For more information, see [Manage inventory records](/manage-supply-chain/inventory/manage-inventory-records).

## Navigate from inventory to part

Every inventory line references its part. From the Inventory page, such as when you scan a serial number on the floor, you can navigate up to the part record to see its specs, BOM relationships, and procedures.

## Export a selected set

Filter or search to the parts you want, then select rows with their checkboxes. A toolbar appears showing how many items are selected. Click **Export CSV** in the table toolbar to download the selected rows as a CSV file for an external workflow. The export includes the table's visible columns; the button is disabled until at least one row is selected.

To change many parts at once, such as reclassifying, re-pricing, or importing in bulk, use [ION Importers](/administration/ion-importers), which previews the effect before applying it.

## Search over the API

For integrations and scripts, [Search parts](/api-reference/examples) covers the GraphQL surface. The API exposes the same filter fields as the UI, but the search bar's match across several fields at once is assembled by the app: over the API you combine the fields you want yourself, such as part number, description, revision, and supplier part number.

## Related

* [Creating and managing parts](/build-hardware/parts/creating-managing)
* [Inventory](/manage-supply-chain/inventory)
* [Search parts](/api-reference/examples)


# Set a part's revision scheme
Source: https://docs.firstresonance.io/build-hardware/parts/revision-schemes

Assign a revision scheme when creating a part, or move an existing part to a different scheme by casting or resetting.

A part's [revision scheme](/build-hardware/parts) sets how its revision values increment. You assign a scheme when you create the part, and you can move the part to a different scheme later. To create, edit, or delete the schemes available to your org, see [Configure part revision schemes](/administration/supply-chain-settings/configure-part-revision-schemes).

## Assign a scheme to a part

When creating a part, pick the scheme from the **Revision Scheme** dropdown in the **Create Part** dialog. You can set a starting value in the **Revision** field, or leave it blank to start at the scheme's first value, for example `A`, `1`, or `00-1`. Subsequent revisions auto-increment along the scheme.

## Change the scheme on an existing part

Change the **Revision Scheme** field in the part's **Part Information** card to move the part to a different scheme. Two strategies map the current revision into the new scheme:

* **Cast**: change the scheme and map the current revision into the new scheme's sequence. A part at revision `D` cast into a `NN-N` scheme becomes `00-4`.
* **Reset**: change the scheme through a new revision and start over at the scheme's initial value. A part at revision `D` reset into a `NN-N` scheme becomes `00-1`.

For the API equivalents (`updatePart` to cast, `createPartRevision` to reset), see [Parts and Part Revisioning](/api-reference/guides/parts-and-part-revisioning#convert-the-revision-scheme-of-an-existing-part).

## Related

* [Manage parts](/build-hardware/parts/creating-managing)
* [Configure part revision schemes](/administration/supply-chain-settings/configure-part-revision-schemes)


# Serial and lot tracking
Source: https://docs.firstresonance.io/build-hardware/parts/serial-lot-tracking

The three part tracking types and how to pick the right one for each part.

A part's tracking type (serial, lot, or untracked) is set through the **Tracking** field on the part. For what each type means and how to choose, see [Parts](/build-hardware/parts). This page covers how each type behaves downstream, how serial and lot numbers are generated, and the rules for switching a part's tracking type.

## What each tracking type changes downstream

| Surface                 | Serial                                                         | Lot                                              | Untracked                                            |
| ----------------------- | -------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- |
| **Receiving**           | Each unit gets a serial; ION generates labels per unit.        | Receive against a lot number; one label per lot. | Receive a count; no per-unit identifier.             |
| **Inventory**           | One inventory row per unit.                                    | One inventory row per location and lot.          | One inventory row per location, with quantity.       |
| **BOM install**         | Operator scans the specific serial being installed.            | Operator scans the lot; quantity counts down.    | Operator confirms count.                             |
| **Run history**         | Per-unit history: scan the serial to see every run it touched. | Per-lot history, with a lot-level rollup.        | Aggregate counts only.                               |
| **Issues**              | Issues can attach to a specific serialized unit.               | Issues attach to a lot.                          | Issues attach to a part inventory row at a location. |
| **Traceability report** | Full chain of custody per unit.                                | Lot-level genealogy.                             | Quantity-level only.                                 |

## Serial number generation

When a part is serial-tracked, ION generates serial numbers in one of two ways:

* **Automatically** from the part's revision scheme, recommended for in-house manufactured parts.
* **From the supplier** at receive time, for purchased serialized components. Scan or enter the vendor's serial.

Serial numbers are unique within the org. ION rejects a duplicate serial scan during install or receive, which protects against a common operator error.

## Lot number generation

Lot numbers come from one of three sources:

* **Generated** by ION at receive time using a configured pattern.
* **Entered** from the supplier's lot label.
* **Captured** from your manufacturing batch identifier when you produce a lot internally.

Lots are scoped to the part. `LOT-2026-0123` on part A is different from `LOT-2026-0123` on part B.

## Switch tracking type

Switching tracking type after inventory exists is constrained:

* **Serial to Lot or Untracked** is blocked while serialized inventory rows exist. Consume or archive every serial unit first.
* **Lot to Serial or Untracked** is blocked while lot-tracked inventory rows exist.
* **Untracked to Serial or Lot** is allowed, but existing untracked inventory stays untracked. New receipts use the new tracking type.

## Made on Assembly and tracking

When a serialized sub-assembly is installed onto a parent assembly through Made on Assembly (see [Editing build requirements](/build-hardware/bills-of-materials/editing-build-requirements)), ION still tracks the sub-assembly's serial. The Made on Assembly flag changes the workflow, so the sub-assembly is built into the parent rather than as a separate run, but it doesn't change the identity. The serial trail is preserved.

<Tip>
  Every serial scan is an operator action. If your downstream traceability
  doesn't need per-unit identity, lot tracking is faster on the floor and is a
  reasonable middle ground. To catch inventory drift early, schedule cycle
  counts through [inventory adjustments](/manage-supply-chain/inventory).
</Tip>

## Related

* [Creating and managing parts](/build-hardware/parts/creating-managing)
* [Search parts and reach inventory](/build-hardware/parts/inventory-search)
* [Inventory](/manage-supply-chain/inventory)
* [Editing build requirements](/build-hardware/bills-of-materials/editing-build-requirements)


# Create and release a procedure
Source: https://docs.firstresonance.io/build-hardware/procedures/create-and-release-a-procedure

Create a procedure, edit its metadata, version it, and move it through review to Released.

A procedure is authored as a draft, moved through review, and reaches **Released** once its reviewers approve. For what a procedure is and how a run copies it, see the [procedure overview](/build-hardware/procedures).

## Create a procedure

1. On the procedures page, click **Create Procedure**.
2. In the **Create New Procedure** dialog, enter a **Title**, an optional **Description**, and a **Type**.
3. Optional: to start from a copy of an existing procedure, choose one in **Start from existing procedure**. ION prefills the title with the source title followed by `(Copy)` and carries over the source procedure's description and type, all of which you can change.
4. Click **Create Procedure**.

The new procedure opens in **Draft**, where you author its steps. To add and arrange steps, see [Manage procedure steps](/build-hardware/procedures/manage-procedure-steps).

## Edit procedure metadata

You can edit a procedure's title, description, and type while it is in **Draft**. Once the procedure moves past Draft, these become read-only.

* **Title**: click the title in the procedure header and type a new one.
* **Description**: on the **Overview** tab, edit the **Description** section.
* **Type**: on the **Overview** tab, set **Type** in the **Configuration** section.

## Create a new version

To revise a released procedure, create a new version rather than editing the released one.

1. Open the latest released version of the procedure.
2. Click **Create New Version**.

ION opens a new **Draft** version that carries over the released version's steps and setup. Runs already created against the earlier version are unaffected, because a run copies the procedure at the moment it starts. The **Create New Version** button is available on the latest released version.

## Submit for review and approve

A procedure moves from **Draft** to **In Review** to **Released**. Reviews are tracked in the **Reviews** section of the procedure.

1. In the **Reviews** section, click the add button to add a reviewer row, then choose a reviewer (a user or team) and a role for each row. Roles your org requires appear as reviewer rows automatically.
2. With at least one reviewer assigned, click **Move to In Review**.
3. Each reviewer opens the procedure and clicks **Approve**, or adds a comment first and clicks **Approve with comment**. A reviewer can instead click **Reject** or **Reject with comment**.
4. When the required approvals are in, click **Move to Released**.

<Note>
  Which reviewer roles are required is configured per org. See [Configure procedure reviewer roles](/administration/production-settings/configure-procedure-reviewer-roles).
</Note>

Depending on your settings, unassigned mBOM parts block these transitions. When your org enforces mBOM parts assigned to steps, **Move to In Review**, **Move to Released**, and a reviewer's **Approve** are disabled until every part, including the components inside sub-assemblies, is assigned to a step. The blocked control states how many components are unassigned and names the first few part numbers. **Reject** stays available. For more information, see [Enforce mBOM parts assigned to steps](/administration/production-settings/enforce-mbom-parts-assigned-to-steps).

## Labels and subscribers

Apply labels to organize procedures and subscribe users to be notified of a procedure's changes. Both live in the procedure's side panel.

* **Add a label**: open the labels control and select a label. **Remove a label**: clear it from the same control.
* **Add a subscriber**: open the subscribers control and select the users to subscribe. **Remove a subscriber**: remove a user from the same control.

## Related

* [Manage procedure steps](/build-hardware/procedures/manage-procedure-steps)
* [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship)
* [Configure procedure reviewer roles](/administration/production-settings/configure-procedure-reviewer-roles)


# Improve a step with ION
Source: https://docs.firstresonance.io/build-hardware/procedures/improve-a-step-with-ion

Ask ION Intelligence to rewrite a draft procedure step, then review, preview, accept, or undo the proposal it returns.

Depending on your settings, a draft procedure's steps carry a row of improvement pills that ask ION
Intelligence to rewrite the step you are editing. ION never writes the step itself. It returns a
**proposal**: what it would change, why it wrote it that way, and the run history behind it. You
decide whether the step takes it.

Proposals are only made on a **draft** procedure, so revise a released procedure before asking. For
more information on revisions, see
[Create and release a procedure](/build-hardware/procedures/create-and-release-a-procedure).

## Ask for a proposal

1. Open a draft procedure's **Steps** tab and select the step you want to improve.
2. In the pill row above the step content, click the angle you want, such as **Improve**, **Add
   safety warnings**, or **Specify tolerances**. The row scrolls sideways to reach the rest.
3. The ION Intelligence companion opens and the ask lands in it as your own message. Wait for the
   answer.

Clicking a second pill on the same step continues the same conversation, so the second ask sees the
first proposal. Moving to another step starts a fresh one.

<Note>
  The same pills appear on a draft standard step. There, ION answers in the conversation instead of
  returning a proposal — proposals are only made on a procedure's own steps.
</Note>

A pill is repeatable: clicking it again after you have edited the step asks against the step as it
now reads. Pills are unavailable while any answer is still streaming.

## Read the proposal

The proposal arrives as a card in the conversation, headed **Proposal · current**. It carries the
proposed title, a summary of the changes it makes, a **Why** line, any safety callouts and open
questions ION raised, and an **Evidence** block linking the runs, issues, and comments the proposal
rests on. To read the proposed wording itself, click **Preview in step** or **Edit**.

Two headings mean the proposal is worth less than it looks:

| Heading                       | What it means                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Proposal · no run history** | The step has never been run, so there are no issues, comments, or measurements behind the proposal.                                  |
| **No longer applies**         | The step changed after ION read it, so the proposal cannot be accepted. Click **Ask again** to ask against the step as it now reads. |

<Note>
  Execution history follows a step into later revisions of the same procedure, so a step revised
  from a released version is grounded in what happened on that version's runs. Procedures revised
  before this shipped have no link back to the steps they were copied from, so their steps are
  grounded only in their own runs.
</Note>

ION declines rather than guessing when it cannot support a revision. The decline says why, such as
that the procedure is not a draft, that the supporting records could not be read, or that a claim
could not be tied back to a record.

## Preview a proposal in the step

To read a long revision where it will actually live, click **Preview in step**. The step content area
renders the proposal as a read-only difference against the current content, marked **Proposed**, and
the editor is untouched underneath. Click **Exit preview** to go back.

If the proposal is accepted, dismissed, or superseded while the preview is open, the preview closes
itself. A proposal the step has already outrun stays readable in the preview.

## Accept, edit, or dismiss a proposal

* **Accept** writes the proposed title and content into the step. The card becomes **Accepted into
  the draft** with an **Undo** beside it.
* **Edit** opens the proposed content in a text box so you can revise it first. Accepting your
  version records it as a proposal of its own that supersedes ION's, so the step carries exactly
  what was written. Click **Cancel edit** to drop the revision.
* **Dismiss** collapses the card to a single line and leaves the step alone. Expand it again to see
  the changes it would have made.

**Undo** returns the step to what it said before and reopens the proposal, so it can be accepted
again. It refuses when the step has changed since the accept, when the proposal has been removed
from the list, and when what the proposal replaced is no longer recorded, which is what a later
accept on the same step leaves behind. ION says which, and nothing is written.

<Note>
  A proposal whose content already matches the step offers no **Accept**, because accepting it would
  change nothing. The card says so and offers **Ask again** instead.
</Note>

Accepting a proposal invalidates the step's other pending proposals: each was written against a
different version of the step, so they no longer describe what it says.

## Review every proposal on a procedure

A conversation is chronological, so a card scrolls away. To work through a procedure's proposals
instead, use the rail.

1. Click **Review all**, which carries a count, in the procedure's action bar. The companion's proposals strip has the same control.
2. The rail opens beside the page, headed **Proposals** with a live count. It lists the procedure's
   proposals oldest first, up to the 100 most recent.
3. A row offers **Accept** and **Dismiss**. A row you settle collapses in place, so the list does not
   reshuffle under you. To edit a proposal before accepting it, preview it in the step, or undo an
   accept, use its card in the companion.
4. Click **Hide proposals** in the action bar, or the close control in the rail's header, to give the
   space back.

A dot on each step in the step list marks the steps carrying live proposals, and carries a number
when one step holds several. **Review all** counts proposals; the dots count steps, so the
companion's strip reports both when they differ.

The rail needs a desktop-width column and is hidden below that width. On a narrower screen, act on
proposals through the card in the companion.

## Follow-up questions

An answer can also come back with up to three grounded follow-up questions under the proposal, drawn
from the same evidence. Clicking one asks it about the same step. They go **Out of date** together
with the proposal once the step changes, rather than disappearing.


# Overview
Source: https://docs.firstresonance.io/build-hardware/procedures/index

How ION models a procedure: its steps, step types, fields, standard steps, part links, and review lifecycle.

A procedure is a versioned sequence of steps used to build, inspect, maintain, or test a part. You author and revise it in the procedure editor, release it through a controlled review, then create [runs](/build-hardware/runs-and-execution) against it on the floor. A run is a copy of the procedure at the moment it starts. Later procedure revisions do not flow into runs already in progress, so each run stays an accurate record of what was done.

Steps hold the work instructions and capture operator input inline through structured fields. You reuse shared work through [standard steps](/build-hardware/procedures/standard-steps), link a procedure to the [parts](/build-hardware/parts) it produces or inspects, and constrain execution order through [step dependencies](/build-hardware/procedures/procedure-dependency-manager).

## Procedure types

Every procedure has a type, chosen when you create it: **Build**, **Inspection**, **Maintenance**, or **Test**. The type records what the work is for, and parts of ION read it to decide what a procedure can carry and which rules apply to its runs.

| Type            | Use it for                              | What the type changes                                                                                                                                                                                                                      |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Build**       | Making a part.                          | The only type that can carry [installation requirements](/build-hardware/procedures/installation-requirements-beta). On every other type the **Assigned Parts** section is unavailable, and a part assigned to a step never reaches a run. |
| **Maintenance** | Servicing a unit that already exists.   | Subject to the same installed-parts completion check as **Build**.                                                                                                                                                                         |
| **Inspection**  | Checking a part against a standard.     | A part linked to an inspection procedure can generate an inspection run on receipt, set per link as **Required** or **Optional**. See [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship).                |
| **Test**        | Verifying that a part performs to spec. | Nothing on its own. It classifies the procedure and scopes the settings below.                                                                                                                                                             |

Two organization settings read the type:

* **Enforce all aBOM parts installed for completion** applies to **Build** and **Maintenance** runs only. Runs of the other types complete without that check. See [Configure run enforcement](/administration/production-settings/configure-run-enforcement).
* An Intent control policy names the procedure types it applies to, so you can require intent on inspection runs without requiring it on builds. See [Configure Intent control policies](/administration/quality-settings/configure-intent-control-policies).

<Note>
  A run creates its part inventory when you create the run, not when you complete it. If you choose a new part inventory in the create-run dialog, ION creates that inventory record straight away and records that a run made it. While the run is open the inventory sits at **WIP**, so it does not count as available quantity, and it becomes **Available** when the run completes. A failed run holds it at **WIP** as well. See [Inventory](/manage-supply-chain/inventory) for what each status means. The procedure type does not change any of this.
</Note>

## Steps

A step is the unit of work in a procedure. Each step is one of two types, chosen when you create it:

* **Content**: written instructions in a rich-text box, with attachments and inline fields.
* **Datagrid**: a table of typed cells an operator fills in when the procedure runs.

When a run starts, ION copies each step into a run step that operators execute and complete in dependency order. A change to an in-progress run step goes through a [redline](/build-hardware/runs-and-execution/redlines-and-deviations).

Steps nest up to five levels deep to group related actions, such as inspecting each part of an assembly under one parent. Depth 0 is the root level, depth 1 its direct children, and so on to the five-level limit, which also caps how deep the API can nest steps. ION numbers steps automatically from 0 by order, with dot notation for children (the first child of step 1 is 1.0, then 1.1). You can tag each step with a [location](/build-hardware/locations-and-work-centers) to show where the work is done. To add, copy, reorder, and nest steps, see [Manage procedure steps](/build-hardware/procedures/manage-procedure-steps).

## Fields

Both step types collect operator input through data-collection fields. A field defined on a procedure step becomes an input the operator fills in during the run.

| Field type      | Notes                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Datetime**    | A date and time for an event, such as when a part entered a thermal oven.                                                               |
| **Boolean**     | A checkbox for a true/false or pass/fail response.                                                                                      |
| **String**      | Free text. No length limit, all UTF-8 characters.                                                                                       |
| **Number**      | Enforces a numeric value. Supports validations.                                                                                         |
| **Select**      | One option from a list.                                                                                                                 |
| **Multiselect** | One or more options from a list.                                                                                                        |
| **Signoff**     | A role-gated digital signature. Enforced by role during the run. Can require peer review (**Peer review required**).                    |
| **File**        | A required file, such as a machine CSV export. Maximum 5 GB.                                                                            |
| **Tool**        | Links use of a [tool](/build-hardware/tools) to the step for traceability. Can be limited by part number, type, and calibration status. |
| **ION User**    | Links an ION user to the step.                                                                                                          |
| **ION Part**    | Links an ION part to the step.                                                                                                          |

Fields are optional by default. A **Required** field blocks step completion until filled, and a required field can also allow a **Not Applicable** entry for positive confirmation. **Number** fields support validations that check a reading against limits during the run and can trigger issue creation. For the full reference, see [Step field types](/build-hardware/procedures/step-field-types).

## Custom attributes

Beyond the built-in fields, your org can add [custom attributes](/administration/custom-attributes) to procedures and steps for data the built-ins don't cover.

* **Procedure attributes** appear in the **Configuration** section of the procedure's **Overview** tab and stay editable at any time. When a run is created, a run attribute of the same name inherits the procedure attribute's value.
* **Step attributes** appear inline in the step editor while the procedure is a draft. Their values copy to run steps, where you can edit them through a [redline](/build-hardware/runs-and-execution/redlines-and-deviations).

## Standard steps

A standard step is a step whose work instructions are shared across procedures and revisioned independently. When you release a new version, every procedure and not-yet-started run that references it picks up the latest released version automatically, so shared work such as a torque sequence or ESD check stays in sync without redlining each procedure.

A standard step disconnects from its source once its run status advances (in progress, redline, canceled, failed, or completed), freezing the run's record at the version in use. Standard steps can be nested inside other steps and standard steps but cannot themselves take a standard step as a child. For creation, reuse, and run behavior, see [Manage standard steps](/build-hardware/procedures/standard-steps). For nesting patterns, see [Procedure best practices](/build-hardware/procedures/procedure-best-practices).

## Part links

A procedure links to one or more parts to declare which work instructions produce or inspect a given part. This is not a parts list of the assembly. With the **Require part-procedure relationship** org setting enabled, ION blocks run creation unless the selected part is linked to the selected procedure.

For inspection-type procedures, each part link is **Required** or **Optional**, which controls whether receiving a part auto-creates an inspection run. To set up links, see [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship).

## Dependencies

Step dependencies define the execution order between steps at the same depth in a procedure. You draw the dependency graph in the procedure's **Dependencies** tab, and ION enforces it during the run so operators know which step is available, blocked, or being redlined. See [Manage step dependencies](/build-hardware/procedures/procedure-dependency-manager).

## Installation requirements

Build-type procedures can carry installation requirements on their steps, tying [mBOM](/build-hardware/bills-of-materials/manufacturing-bom) items to the steps that install them. A run step cannot close until its required installs are satisfied, which keeps the [aBOM](/build-hardware/bills-of-materials/made-on-assembly) an accurate digital record of the physical build. This feature is in beta. See [Assign installation requirements](/build-hardware/procedures/installation-requirements-beta).

## Review and lifecycle

A procedure moves through a controlled change process: you author it as a draft, move it **In Review**, and it reaches **Released** once reviewers sign off. For the steps to create a procedure, version it, and move it through review, see [Create and release a procedure](/build-hardware/procedures/create-and-release-a-procedure). Standard steps use the same review flow and can be revisioned on their own. You configure which reviewer roles are required per org. See [Configure standard step reviewer roles](/administration/production-settings/configure-standard-step-reviewer-roles).

Because a run copies the procedure at start, released changes reach only runs that have not started. To hold work until instructions are final, place the run or step on hold. For patterns that combine nesting, standard steps, and holds, see [Procedure best practices](/build-hardware/procedures/procedure-best-practices).

## Procedure actions

The procedure header carries actions beyond editing and review, in its **More options** menu and side panel:

* **Clone Procedure** creates a new draft copy you can edit independently.
* **Print** opens a print-ready preview of the whole procedure. See [Print a procedure report](/build-hardware/procedures/print-a-procedure-report). **Preview width** shows the procedure at a chosen device width to check how it reads on a shop-floor tablet.
* **Copy Procedure Family Link** copies a link that always opens the latest released version of the procedure.
* **Archive Procedure** removes a procedure from active use. It's available in any status except already archived. **Delete Procedure** permanently removes a procedure and is available only while it's in Draft.
* Subscribe to a procedure to be notified of its changes, and apply labels to organize it. Both live in the procedure's side panel.


# Assign installation requirements
Source: https://docs.firstresonance.io/build-hardware/procedures/installation-requirements-beta

Add installation-requirement steps that tie build requirements to procedure steps with traceability.

<Info>
  Installation requirements are in beta. Review the best practices on this page
  before you use them.
</Info>

You assign required installations at each step in a procedure. A run step can't close until all of its required installations are complete, the same way it can't close while a required field is empty.

## Assign installs to a step

Open the procedure's **Steps** tab, select a step in the step queue, then open the **Assigned Parts** section in the right rail. This is where you assign installation requirements to the selected step.

<Note>
  Parts can only be assigned to steps on build-type procedures. On other
  procedure types, the Assigned Parts section is unavailable.
</Note>

The Assigned Parts section has two parts. The top shows the installation requirements assigned to the step currently selected in the procedure step queue. Below it, a part selector and **mBOM** version picker let you choose which associated part's [mBOM](/build-hardware/bills-of-materials/manufacturing-bom) version you assign from, followed by that mBOM's items.

To add an assigned install to the step shown in the procedure window, click the **+** button next to the mBOM item.

<Note>
  The quantity you assign is the minimum installation quantity required to
  complete a run step.
</Note>

Installation requirements assigned to a step appear in the upper half of the panel. You can partially assign an mBOM item to a step. Each assigned part shows the quantity assigned to the step, a slash, then the total mBOM quantity (for example, `2/5`). While the procedure is editable, the assigned quantity is an editable field you can adjust directly.

To remove an installation requirement from the step, click the remove control on its row in the assigned list. The requirement removes immediately. The control is available while the procedure is editable.

<Note>
  You don't choose an mBOM version when you create a run. You select a
  procedure, and ION resolves the version. When [Enforce mBOM parts assigned to
  steps](/administration/production-settings/enforce-mbom-parts-assigned-to-steps)
  is on, a run's aBOM comes from the mBOM version pinned to that part on the run's
  procedure. You set the pin while authoring the procedure; it can only point at a
  released version (not a draft) and doesn't have to be the latest released
  version. If the part isn't pinned on the procedure, ION falls back to the part's
  latest released version. When the setting is off, pinning is ignored and a run
  always uses the part's latest released mBOM version. Release mBOMs as needed
  before you use them in runs.
</Note>

You can release a procedure for a released mBOM while you draft a future version of the same mBOM.

Once you fully assign an mBOM item, it is shaded green on the mBOM panel. Turn on the **Hide assigned** toggle to remove fully assigned mBOM items from the view for a more streamlined assignment process. With **Hide assigned** off (the default), every mBOM item stays visible, with fully assigned ones shaded green.

### Substitutes

The crossing arrows highlight [substitutes](/build-hardware/bills-of-materials/substitutes) on the mBOM, showing which other parts are listed as substitutes.

### Reference designators

Just as you set a minimum quantity to close a step, you can assign [reference designators](/build-hardware/bills-of-materials/reference-designators) that must be satisfied before the step closes. Assign them per installation requirement from the reference-designator dropdown in the **Assigned Parts** section; the badge shows how many of the requirement's designators are assigned. At run time, the operator assigns each installed unit to a specific reference designator, and the step can't complete until every assigned designator has an install.

## Switch the pinned mBOM version

Move the procedure's pin from the **mBOM** row in **Assigned Parts**. The version shown there is read-only until you start a switch:

1. Click **Switch** on the **mBOM** row. The version picker becomes editable.
2. Pick the version you want. Each option lists its status, such as **Released**.
3. Click **Confirm**.

When a newer released version exists, the row also offers a shortcut: a notice naming that version, with an **Update** button that moves the pin straight to it.

The pin stays editable while the procedure is in draft, even when the step's content is locked.

When the procedure already has assignments to reconcile, ION asks you to confirm the switch before it commits the pin. Assignments that still fit the new version carry over. Under **Reconciliation impact**, the confirmation lists each part that does not, and why:

* A part is **Reduced** on a step when the new version needs fewer of it than you've assigned across steps. ION can't choose which step to reduce, so it unassigns the part from all of them.
* A part is **Removed** from a step when the part isn't in the new version at all.

Click **Switch & reconcile** to commit, or **Cancel** to keep the current pin. Reassign any unassigned part from the new version once the switch completes.

<Frame>
  <img alt="Confirmation dialog asking whether to switch the pinned mBOM version to v2, with a Reconciliation impact list showing one part reduced on a step because it exceeds the new version's quantity and another removed because it is not in the new version, above Cancel and Switch and reconcile buttons." />
</Frame>

The switch clears this procedure's assignments on every revision of the part, then recreates the ones that carry over on the version you pinned. That means the dialog can open with nothing to carry over: it's telling you the target version holds assignments left behind by an earlier revision copy, and confirming clears them.

<Note>
  When **Enforce mBOM parts assigned to steps** is on, creating a new mBOM
  revision no longer copies part-step assignments onto the new revision for
  procedures that pin the part, so a fresh revision starts with nothing to clear.
  With the setting off, the latest released revision governs and assignments carry
  forward to the new revision as before.
</Note>

## Install inventory on a run step

You can install inventory from the run step itself, the same way you install inventory on the aBOM.

You can't complete a step until all run step build requirements have their minimum quantities and reference designators satisfied. The inventory list includes any available substitutes. To require mBOM parts to be assigned to steps before a procedure can be released, see [Enforce mBOM parts assigned to steps](/administration/production-settings/enforce-mbom-parts-assigned-to-steps).

## Permissions

To create, update, and delete installation requirements on procedures, grant yourself a role with the `CreateStepPartRequirement`, `UpdateStepPartRequirement`, and `DeleteStepPartRequirement` permissions.

## How ION handles mBOM changes

Your mBOM can change after you release a procedure. For more on changing build requirements, see [Editing build requirements](/build-hardware/bills-of-materials/editing-build-requirements). The following changes don't require a procedure revision:

* **Removing a part** removes the associated installation requirements from associated procedures, so you can remove parts without revising the procedure.
* **Updating the part number on an existing mBOM requirement** updates all installation requirements in associated procedures automatically with the new part number.
* **Updating the name of a reference designator** updates all installation requirements in associated procedures automatically with the new reference designator where it is called out.
* **Adding substitutes** shows the new substitutes on all installation requirements.
* **Increasing the quantity of an mBOM requirement** has no effect on associated procedures.

The following changes require a procedure revision:

* **Adding a part.** A newly added mBOM part isn't associated with any procedure until you revise the procedure to assign it to a step.
* **Reducing the quantity of an mBOM requirement.** You can't reduce the quantity below what is assigned to a procedure. To reduce it, create a new procedure, then up-version the mBOM.

<Note>
  In every case, there is no effect on existing runs and aBOMs at the time of the
  change.
</Note>

## Best practices

* **Installs don't propagate across batches.** Each batch ensures traceability for every run within it. Because you select the specific inventory you install, ION restricts installs to individual runs to keep inventory tracking accurate.
* **Assign installation requirements while the procedure is in draft.** You can add, edit, or remove a step's installation requirements only while its procedure is in draft; once the procedure is released, its requirements are locked, so up-version to a new draft to change them. You can't add installation requirements to a standard step in the step library on its own. Assign them on a build-type procedure that calls out the standard step.
* **Train technicians on installation requirements.** The installation requirements on a step are a minimum. Installing a part through the aBOM counts toward that minimum: ION attributes the install to a run step, selecting the step automatically when the part is required on only one step, or prompting you to choose the step when it's required on more than one. If you aren't confident your procedures will stay stable, set the minimum installation quantity to zero and list the needed quantity in the step content, so you can make changes as needed.
* **Build requirement quantities on run steps can't be redlined**, and you can't add or remove a run step's build requirements mid-run. If your organization has enabled editable run-step build requirements, you can swap a required part for an approved substitute. To allow run steps to complete without required installs, enable `Allow run steps to complete without required install` in your [run enforcement settings](/administration/production-settings/configure-run-enforcement).

### As-required, continuous-usage, and consumable parts

Associate a build requirement to a step only when it will always be installed.

Add a part as a **0-quantity build requirement** to associate it with a step without requiring an install to close the step. A 0-quantity requirement doesn't block step completion. Use it to surface an optional or as-needed part, and record any actual usage in the step content. To make an install required, set the quantity to any value greater than zero. For example, if you always apply epoxy but the amount differs each time, set the requirement to a quantity greater than zero and note the amount used in the step content.

When a part is not always installed, don't attach it to a step. Instead, you can:

* Keep it in the mBOM without a step association.
* Add the build requirement to the aBOM during the run when needed.

For example, if a shim is only occasionally required to level a plate, leave it unassociated in the mBOM and add it to the aBOM only on runs where it is required.

If a run is blocked because a required install was assigned incorrectly, you can temporarily allow steps to complete without it:

1. Have an admin enable **Allow run steps to complete without required install** in the [run enforcement settings](/administration/production-settings/configure-run-enforcement).
2. Update your procedure and build-requirement associations following the best practices in this section to prevent future disruptions.


# Manage procedure steps
Source: https://docs.firstresonance.io/build-hardware/procedures/manage-procedure-steps

Add steps to a procedure, configure them as content or datagrid steps, and copy, nest, reorder, and locate them.

Steps are the units of work in a procedure. You add and arrange them while editing the procedure. For what a step is and how it becomes a run step on the floor, see the [procedure overview](/build-hardware/procedures#steps).

## Add a step

1. While editing a procedure, click **Add Step** at the bottom of the steps list, or hover over an existing step and use its **...** actions menu to **Add step below** or **Add child step**. The **Add Step** dialog opens on the **Create New** tab.
2. Enter the **Step Name** and choose the **Step Type**, Content or Datagrid. Optionally set a **Location** and toggle **Outside Processing Step**.
3. Click **Create Step**.

## Create a step from a PDF

You can turn a PDF into procedure steps instead of authoring them by hand.

1. While editing a procedure, click **Add Step** to open the **Add Step** dialog on the **Create New** tab.
2. Set **Step Type** to **PDF**.
3. Upload the PDF, then enter the pages to use in the **Pages** field, such as `1,2,3-5`.
4. Enter a **Step Name**, then click **Create Step**.

ION creates one step whose content is parsed from the pages you entered.

## Configure the step

Configure the step based on the type you chose.

<Tabs>
  <Tab title="Content">
    Content steps hold written instructions. The content box supports text formatting: colors, lists, fonts, pictures, and tables.

    <Note>
      To add a table, build it in Google Sheets and paste it in. Pasting from Excel copies the content but not the formatting.
    </Note>

    ### Attachments

    Attach reference files to a step from the **Attachments** panel. Click **Browse files** to upload a file, or **Take a photo** to capture one. A STEP file (3D CAD model) can be previewed in place, so an operator can inspect the model without downloading it. On an image attachment, **Copy image** copies the image to your clipboard.
  </Tab>

  <Tab title="Datagrid">
    Datagrid steps collect tabular data. Each cell is a field an operator fills in when the procedure runs. You edit the grid's columns and rows while the procedure is a draft.

    <Frame>
      <img alt="Datagrid step editor showing columns with data-type icons, three rows with Required toggles, and the Add Column and Add Row controls" />
    </Frame>

    ### Columns

    A datagrid supports any number of columns.

    * **Add a column**: click **Add Column** to add one at the end, or open a column's menu and choose **Insert column left** or **Insert column right**.
    * **Name a column**: click the column header and enter a name.
    * **Set the column type**: in the same header editor, choose the data type. Number columns take an optional unit, select and multiselect columns take a list of options, and signoff columns take a role.
    * **Set a column read-only**: turn on **Read only?** so its cells can't be edited when the step runs.
    * **Delete a column**: open the column's menu and choose **Delete column**.
    * **Reorder columns**: drag a column by the handle in its header.

    ### Rows

    A datagrid supports any number of rows.

    * **Add a row**: click **Add Row** to add one at the end. With a row selected, click **Insert Above** or **Insert Below**.
    * **Delete a row**: select the row and click **Delete**.
    * **Reorder rows**: drag a row by its handle.
    * **Require a row**: turn on the row's **Required** toggle to require it be filled in when the step runs.

    ### Cell values

    While authoring, you can prefill text and number cells by editing them directly. Cells of other types are filled in when the step runs.
  </Tab>
</Tabs>

## Add fields to a step

Both step types collect operator input through data-collection fields, edited in the **Step Fields** section for the selected step while the procedure is a draft. For each field type and how number validations behave, see [Step field types](/build-hardware/procedures/step-field-types).

1. In the **Step Fields** section, click **Add Field**.
2. Choose the field's type from the type list, such as **Boolean**, **Number**, or **Signoff**.
3. Enter a field name, and optionally a description.
4. Set the field's behavior:
   * Turn on **Required** to block step completion until the field is filled.
   * Turn on **Allow "Not Applicable"** on a required field to let the operator confirm the field doesn't apply.
5. Configure any type-specific settings, such as a signoff role or select options.

To reorder fields, drag a field by its handle. To copy or delete a field, use the controls on the field.

### Set a step's lead time

Set a **Lead Time** on a step to record how long the work should take, entered as a duration such as `1d 2h 20m`. Step lead times roll up into the procedure's total. During a run, the step's time tracking compares logged time against this lead time.

## Copy a step

In the **Add Step** dialog, open the **Add Existing Step** tab and type the name of the step you want to copy into the **Search steps...** box. ION fetches existing steps that match, along with the procedure each will be copied from. Click a result to copy it into the procedure.

You can also duplicate a step in place. Hover over a step in the step list, open its **...** actions menu, and choose **Duplicate**.

To share one step across procedures and revise it in one place instead of copying it, use a [standard step](/build-hardware/procedures/standard-steps).

## Nest child steps

Create child steps by hovering over a step, opening its **...** actions menu, and choosing **Add child step**, or by dragging an existing step under another step. Steps show the number of child steps they have on a badge next to the step title. Click the badge to expand or collapse the child steps.

<Warning>
  Steps can be nested up to five levels deep.
</Warning>

## Reorder steps

Drag a step by its handle to reorder the steps.

## Delete a step

Hover over a step in the step list, open its **...** actions menu, and choose **Delete step**. A step that has a dependency can't be deleted: remove its [step dependencies](/build-hardware/procedures/procedure-dependency-manager) first.

## Tag a step's location

Set a step's [location](/build-hardware/locations-and-work-centers) from the **Location** field when creating the step, such as "Testing Lab" or "Paint booth 1".

## Old ION compatibility

Content steps support rich formatting, such as to-do lists, headers, tables with merged and colored cells, toggles for hidden content, code blocks, block quotes, callouts, and a table of contents.

<Frame>
  <img alt="Content step showing a checkbox to-do list, formatted headings, a table with a colored cell, a toggle, and a code block" />
</Frame>

<Warning>
  A procedure you draft here, along with its runs, can behave differently in Old ION. Rich formatting does not carry over: to-do lists lose their checkboxes, headers and tables lose their formatting, and toggles, code blocks, block quotes, callouts, and the table of contents do not appear.
</Warning>

<Frame>
  <img alt="Same content step in Old ION where the to-do list is a plain numbered item, the table and toggle lose formatting, and other blocks show as plain text" />
</Frame>

<Tip>
  If your team still works in Old ION, check how a procedure renders there before relying on this formatting in production work instructions.
</Tip>

## Related

* [Step field types](/build-hardware/procedures/step-field-types)
* [Improve a step with ION](/build-hardware/procedures/improve-a-step-with-ion)
* [Manage standard steps](/build-hardware/procedures/standard-steps)
* [Manage step dependencies](/build-hardware/procedures/procedure-dependency-manager)


# Link a part to a procedure
Source: https://docs.firstresonance.io/build-hardware/procedures/part-procedure-relationship

Associate a procedure with the parts it produces or inspects, then approve the association so the procedure can start a run.

Link a part and a procedure from the **Associated Parts** section on a procedure's **Overview** tab. Click **Add Part**, then pick the part to associate.

You can also set up the relationship from the part's page in the library. Open the part, go to its **Procedures** section, and click **Associate to Procedure**.

A new association starts in **Pending**. To use it for a run, approve it first.

## Approve or reject an association

You can approve from either surface. Each row carries an **Approval** column with the association's current state:

* On the part's page in the library, in its **Procedures** section.
* On the procedure's **Overview** tab, in the **Associated Parts** section.

The controls are the same on both:

* To approve a pending association, click **Approve**. The state changes to **Approved**.
* To reject a pending association, click **Reject**. The state changes to **Rejected**.
* To move an approved or rejected association back to **Pending**, click the reset control on that row.

Hovering an approved or rejected association shows who last updated it and when.

<Frame>
  <img alt="Associated Parts table listing three parts. The Approval column shows Approve and Reject buttons on the first row, a green Approved state on the second, and a red Rejected state on the third." />
</Frame>

<Note>
  Only an approved association can start a run when the **Require part-procedure relationship** setting is on. See [Block a run until the association is approved](#block-a-run-until-the-association-is-approved).
</Note>

## Unlink a part from a procedure

To remove a part-procedure link, click **Remove** on the row for that link. The link is removed without a confirmation prompt. You can unlink from either surface:

* On the part's **Procedures** section, click **Remove** on the row.
* On the procedure's **Overview** tab, in the **Associated Parts** section, remove the part from the list.

## Block a run until the association is approved

To require an approved association before a run can be created, turn on the **Require part-procedure relationship** org setting. See [Configure run enforcement](/administration/production-settings/configure-run-enforcement).

With the setting on, creating a run for a part and procedure that have no approved association is blocked. A missing, **Pending**, or **Rejected** association all block the run. The rule covers both ways of choosing the part: building new inventory, and attaching an item already in inventory.

Where the block appears differs between the two:

* **Building new inventory.** The run wizard checks the association as you pick, so the **Part** step explains the problem and you can't advance to **Review**.
* **Attaching an existing item.** The wizard doesn't check ahead, so the block arrives when you create the run. The error names the part number and revision you chose, and the procedure title and version it isn't approved for. Approve the association, then create the run again.

The run wizard's **Part** step surfaces the approval state as you pick, so you can tell the cases apart:

* An **Approved** association is listed plainly in the pickers' associated group.
* A **Pending** association is still selectable and carries a **Pending** badge. Selecting the pair shows a message naming the part and procedure, with a **Review** link that opens the procedure in a new tab so you can approve it there.
* A **Rejected** association is left out of the associated group.
* Any other pair that isn't approved, such as a part with no association to the procedure, shows the message "The selected part must be associated with and approved for the selected procedure."

<Frame>
  <img alt="Procedure picker dropdown with an Associated Procedures group listing one procedure version tagged with a Pending badge." />
</Frame>

<Frame>
  <img alt="Run wizard Part step with a part and procedure selected, showing a message that the part is pending approval for the procedure alongside a Review link." />
</Frame>

In each blocked case you can't advance to **Review**.

## Required and optional inspection procedures

When you link a part to an inspection procedure, the **Required** or **Optional** setting on the association controls whether an inspection run is created on receipt. It applies to inspection procedures only.

* **Required**: when you receive the part, ION creates an inspection run for it from the associated procedure.
* **Optional**: when you receive the part, ION creates no inspection run. You can still start an inspection manually.

## Related

* [Create a run](/build-hardware/runs-and-execution/starting-a-run)
* [Configure run enforcement](/administration/production-settings/configure-run-enforcement)
* [Procedures](/build-hardware/procedures)


# Print a procedure report
Source: https://docs.firstresonance.io/build-hardware/procedures/print-a-procedure-report

Produce a complete printed or PDF copy of a procedure, choosing which sections to include.

The procedure print preview renders a procedure as a paginated report you can print or save as a PDF. It carries the procedure's data, including every step's content, fields, custom attributes, part requirements, and datagrids.

## Print a procedure

1. Open the procedure and choose **Print** from its **More options** menu. The print preview opens.
2. In **Print options**, clear any section you don't want in the report. Every section is on by default:
   * **Description**
   * **Procedure Information**
   * **Steps**
   * **Step Fields**
   * **Step Attributes**
   * **Step Part Requirements**
   * **Associated Parts**
3. Click **Print or download PDF**, then use your browser's print dialog to send it to a printer or save it as a PDF.
4. Click **Back to procedure** to return.

Your section choices are remembered for the next time you open a preview.

## What the report contains

Steps are numbered as an outline (`1`, `1.1`, `1.1.1`) and nest to any depth. Per step, the report renders:

* The step's content.
* Data-entry fields, read-only, labeled with the field type as the procedure editor names it.
* Custom attributes as key/value rows, with dates in your organization's date format.
* Part requirements, with the part number, description, quantity, and reference designators.
* Datagrids in full, with their columns and rows.

A step added from a standard step renders the current standard step's content.

<Note>
  File attachments are listed by filename; their contents aren't rendered into the report.
</Note>

A datagrid wider than the printed page is split into column groups, each labeled with the columns it covers, so nothing is cut off. A long datagrid repeats its header on each page.

## Related

* [Overview](/build-hardware/procedures)
* [Create and release a procedure](/build-hardware/procedures/create-and-release-a-procedure)
* [Print a run report](/build-hardware/runs-and-execution/print-a-run-report)


# Procedure best practices
Source: https://docs.firstresonance.io/build-hardware/procedures/procedure-best-practices

Patterns for combining steps, standard steps, and nesting to build procedures that scale.

These patterns keep procedures maintainable as they grow in size and reuse.

## Nesting and standard steps

* **Use standard steps for reusable or critical instructions.** When a set of instructions appears across many procedures, or when updates to it must reach in-progress work before execution, make it a [standard step](/build-hardware/procedures/standard-steps). A revision to the standard step reaches every procedure, standard step, and not-yet-started run that references it.
* **Group related steps under one parent.** Nest steps that share an intent under a single parent step, such as a "Perform standard torque operation" step that contains each torque action. This clarifies the procedure and simplifies its dependency graph.
* **Edit a standard step's dependencies at its own root level.** When you nest standard steps within each other, create and edit dependencies for a standard step in its own procedure, not in the parent that calls it. Editing "Torque bolts" within its own root keeps its dependencies consistent everywhere it's used.
* **Keep nesting within five levels.** ION allows up to five levels of nesting. The limit also protects procedure creation through the API, which could otherwise create hundreds of levels and degrade performance. As procedures get deeper, reassess whether the structure stays readable.

## Hold work until instructions are final

Combining nested standard steps with the run **On hold** status lets planners schedule work before every instruction is finalized, while preventing operators from starting a step whose instructions aren't ready.

1. Build a top-level procedure from standard steps, each covering a group of work such as torquing, sealing, and inspecting.
2. Release the standard steps whose instructions are complete so technicians can start them.
3. For a standard step whose instructions are still in progress, put its run step [on hold](/build-hardware/runs-and-execution/redlines-and-deviations). The hold blocks work until the instructions are ready.
4. When the instructions are finalized, release the updated standard step and take the run step off hold. The run picks up the latest released version automatically.

## mBOM structure

* **Build subassemblies in their own procedures.** Tie a procedure to a single parent assembly and give each subassembly its own procedure. A procedure tied to a lower-level subassembly can't also be tied to the parent, which avoids circular loops in the dependency graph.
* **Keep the mBOM to real inventory.** Model only physical parts that can be installed, uninstalled, or held in inventory, rather than manufacturing states. This keeps parallelization and uninstall behavior predictable and brings your eBOM closer to your mBOM.


# Manage step dependencies
Source: https://docs.firstresonance.io/build-hardware/procedures/procedure-dependency-manager

Manage which steps depend on others so changes propagate correctly.

## The dependency manager

The dependency manager lives within a given procedure. Open the **Dependencies** tab to view and edit the procedure's step dependency graph.

Steps appear as nodes you can drag to arrange. Draw a connection between two steps to make one depend on the other, and select a connection or node and press **Delete** to remove it. Use the **Vertical layout** and **Horizontal layout** buttons to switch the graph orientation.


# Manage standard steps
Source: https://docs.firstresonance.io/build-hardware/procedures/standard-steps

Create, review, and reuse standard steps so shared instructions stay in sync across every procedure and run that uses them.

<Note>
  A standard step is marked with a blue **S** chip wherever it appears in a procedure or run step tree, next to a **ver.** badge carrying the version in use.
</Note>

## Create a standard step

Standard steps are listed in a table and use the same review process as procedures.

1. In the **Production** section of the sidebar, click **Standard Steps**.
2. Click **Create Standard Step**.
3. In the **Create New Standard Step** dialog, enter a **Title**, pick a **Type** of **Content** or **Datagrid**, and optionally add a **Description**. **Title** and **Type** are required.
4. Click **Create Standard Step**. ION opens the new standard step.
5. Edit it as you would a regular step. You can add child steps for longer, more complicated operations, but a standard step can't take another standard step as a child.
6. Click **Move to In Review** and add reviewers as required.
7. When all reviewers have signed off, the step moves to **Released** and can be copied into procedures and runs.

## Create a new version of a standard step

To revise a released standard step, create a new version rather than editing the released one.

1. Open the standard step and click **Create New Version**. The button is available once the standard step is **Released** or **Archived**.
2. Edit the new **Draft** version's steps and fields.
3. Click **Move to In Review**, add reviewers, and release it the same way you released the first version.

When the new version is released, every procedure and not-yet-started run that references the standard step picks it up automatically.

## Standard step dependencies

A standard step has its own **Dependencies** tab, where you set the execution order between its child steps. Edit those dependencies from the standard step itself, so every procedure that calls it picks up the same order. See [Manage step dependencies](/build-hardware/procedures/procedure-dependency-manager).

## Use a standard step

You can use a standard step anywhere a regular step can be used, including as a child step to standardize one part of a larger action. The tab you search from depends on where you're adding it:

* In a procedure, open the **Add Step** dialog and switch to its **Add Existing Step** tab. See [Copy a step](/build-hardware/procedures/manage-procedure-steps#copy-a-step).
* In a [redline](/build-hardware/runs-and-execution/redlines-and-deviations) on a run, open a neighboring run step's **More actions** menu, click **Add Step Before**, **Add Step After**, or **Add Child Step**, then switch the **Create New Step** dialog to its **Copy from Library** tab.

On either tab, search for the standard step by name and select it to copy it in.

## Execute a standard step in a run

You execute a standard step the same way you execute a regular step in a run.

<Note>
  **Initializing** is when the run step takes on the details of the latest released version of the standard step and stops receiving further updates.
</Note>

A standard step initializes when its run step's status moves to **In progress**, **Redline**, **Canceled**, **Failed**, or **Complete**. At that point the run step's details update to the latest released version, and the version it locked to is the one shown in the **ver.** badge in the step queue and next to the step title.

Initializing also happens when a standard step is redlined into a run. Adding version 2 of the standard step "Torque Bolt" to a run keeps it at version 2 for good, even if the redlined step is never started.

### Approvals

<Note>
  Contact your Customer Success Manager to enable role-based reviews.
</Note>

When you finish updating a new version of a standard step, submit it for review. Click **Move to In Review** on the standard step, then add the roles, users, or teams that should review it. Reviewers get a standard step approval request in their [notifications](/automate-with-ion/notifications/view-notifications). Opening the request takes them to the standard step to leave a review. Once every reviewer approves, the standard step moves to **Released** on its own.

Reviewers live in the **Reviews** section of the standard step's review panel, with a progress bar over the requests. When your org configures required reviewer roles, each required role gets a row in that section with its **Role:** locked and an **Action Required** badge, and the row stays open until you pick the user who fills it. To configure which reviewer roles are required, see [Configure standard step reviewer roles](/administration/production-settings/configure-standard-step-reviewer-roles).

You can also configure required approvers through the API:

```graphql theme={null}
mutation createStepApprovalRole($input: CreateStepApprovalRoleInput!) {
  createStepApprovalRole(input: $input) {
    approvalRole {
      _created
      _etag
      _updated
      count
      createdById
      gateType
      roleId
      updatedById
    }
  }
}
```

With this input, one user holding the role whose `roleId` is 3 must approve the standard step before it can be released:

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

## Labels

Labels are shared tags you apply across ION to group related records. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

To add a label to a standard step, click **Add labels** in the header panel, then type in the **Search or create labels...** box and select a label. To create a new label, type its name and select the create option.

## Attachments

Attach reference files to a standard step, such as images, PDFs, and STEP/STP files, up to 100 MB each.

1. On the standard step, open the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking **Browse files**, or clicking **Take a photo** on a device with a camera.

To remove a file, use its delete control and confirm in the **Delete attachment?** dialog.


# Step field types
Source: https://docs.firstresonance.io/build-hardware/procedures/step-field-types

Reference for the data-collection field types you can add to a step to capture operator input, readings, signatures, and files.

## Data collection fields

The field types below capture operator input during a run. You pick a field's type when you add it to a step. For the steps to add and configure a field, see [Manage procedure steps](/build-hardware/procedures/manage-procedure-steps#add-fields-to-a-step).

### Datetime

A date and time for an event, used to track when something happened in production, such as when a part entered a thermal oven.

### Boolean

A checkbox for a true or false response, such as a pass/fail check.

### String

A text field for freeform responses from the floor.

<Note>
  String fields have no length limit and support all UTF-8 characters.
</Note>

### Number

A numeric value. Number fields are the only type that supports validations, which check a reading against limits automatically during the run. See [Field validations](#field-validations).

### Select

A list of options where the operator picks one. To let the operator pick more than one, use Multiselect.

### Multiselect

A list of options where the operator can pick more than one. Use it to capture several conditions at once, such as when a part is scratched, bent, and discolored.

### Signoff

A role-gated digital signature. You define the role required to sign off, and ION enforces it during the run. For example, a step can require a user with the Quality Inspection role to sign off before work continues. ION records who signed off with a digital signature.

Turn on **Peer review required** to restrict the signoff to users who have not worked on the run connected to the field.

You manage which roles exist and who holds each role in [Users and permissions](/administration/users-and-permissions).

### File

A file upload. Use it when you need one specific file, such as a CSV export from a machine. For general reference files on a step, the [step attachments](/build-hardware/procedures/manage-procedure-steps#attachments) panel is more flexible.

<Note>
  A File field accepts a file up to 5 GB.
</Note>

### Tool

Links use of a [tool](/build-hardware/tools) to the run step for traceability and containment. You can limit a Tool field to specific tool part numbers, types, and calibration status.

### ION User

Links an ION user to the step.

### ION Part

Links an ION part to the step.

## Required fields

Fields are optional by default. Leaving an optional field blank does not block step completion. Turn on **Required** to force the operator to fill in the field before completing the step.

A required field can also allow a **Not Applicable** entry, which lets the operator confirm the field does not apply rather than leaving it blank.

## Field validations

Number fields support validations that check a reading against limits automatically when an operator enters a value during a run. Use them to set the conditions for a passing value. For a torque value that must fall between 5 ft-lb and 10 ft-lb, add one validation for the lower limit and one for the upper limit.

To author validations on a number field:

1. In the **Step Fields** section, on a number field, click **Add Validation**.
2. Choose the comparison operator: less than (`<`), less than or equal to (`≤`), greater than (`>`), greater than or equal to (`≥`), equal to (`=`), or not equal to (`≠`).
3. Enter the value to compare against.

Add a validation for each limit. To require a value inside a range, add a greater-than validation for the lower bound and a less-than validation for the upper bound.

A validation runs when the operator enters a value during the run. With the [issue creation settings](/administration/quality-settings/configure-issue-creation-and-approvals) configured to create an issue when a value fails its criteria, ION creates an issue automatically when a reading is out of limits.


# Manage run and run step attributes
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/attributes

Add user-defined data fields to a run or a run step with custom attributes, set at run creation or edited from the run Overview and the run step right rail.

Runs support [custom attributes](/administration/custom-attributes) that let you add user-defined data fields. Run custom attributes can be set while creating a run and changed at any time on the run's **Overview** tab.

## Set run step custom attributes

Individual run steps also support custom attributes, shown in the **Attributes** section of the run step's right rail. Expand the section to view the run step's custom attributes.

Run step custom attributes are editable only while the run step is in redline. When the run step is in any other state, the section is read-only. To edit them, put the run step in redline, update the values, then submit the redline. For how to start and submit a redline, see [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations).


# Complete and review a run
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/completion-and-review

Move a run to complete, run the data-review checklist, close open redlines and issues, and produce the records downstream consumers will need.

The completion review reconciles the run's accumulated state, such as step results, measurements, attachments, build requirements installed, redlines applied, and issues filed, into the records that downstream consumers such as auditors, customers, and planners rely on. For how completion fits the run lifecycle, see the [Overview](/build-hardware/runs-and-execution). This page covers the completion checklist, the review surfaces, and what happens to the run's data after completion.

## Prerequisites for completion

ION enforces these structural prerequisites:

* Every required step is signed off.
* Every required field on every required step has a value.
* Every build requirement is installed, or excepted through an issue.
* Every required approval gate is satisfied.

If any of those isn't met, the **Complete run** button is disabled and ION shows what's blocking it.

There are also organizational prerequisites that ION can warn on but doesn't always block:

* Open issues filed against the run. Disposition these before completion in most workflows.
* Open redlines. Accept or reject these before the run's record is locked.
* Out-of-range measurements without an issue. These usually require either an issue and disposition or a deliberate deviation acknowledgement.

## The completion review

When prerequisites are met:

1. Open the run.
2. Click **Complete run**.
3. Review the checklist in the **completion review** dialog:
   * **Steps**: count of steps completed, and any steps that failed and were then resolved.
   * **Build requirements**: every required part installed, and any exceptions.
   * **Redlines**: count of open versus closed redlines, with a warning if any are still open.
   * **Issues**: open, dispositioned, and resolved counts.
   * **Approvals**: every required gate satisfied.
4. Optional: add a free-text completion note.
5. Confirm.

ION then:

* Records who completed the run and when.
* Transitions the run to **Complete**.
* Updates the target inventory's state to reflect the build outcome, typically **available** for the produced unit.
* Closes any run-level approval gates.
* Locks all step records. No further edits are possible without reopening the run.

## Justify uninstalled aBOM parts

When your organization requires it, completing a run (or a run step) whose aBOM has parts that aren't fully installed prompts you to justify finishing anyway. ION opens the **Complete with Uninstalled aBOM Parts** dialog, which lists each under-installed part with its installed-versus-required quantity. An as-required part (quantity 0) with nothing installed is listed too, as **As required** followed by the quantity installed. When that as-required part is made on assembly, it's listed by the percentage installed on its sub-assembly instead.

1. Read the list of parts that aren't fully installed.
2. In the **Justification** field, explain why it's acceptable to complete the run with those parts uninstalled. The field is required.
3. Click **Complete Anyway** to record the justification and continue, or **Go Back** to return without completing.

ION records the justification, along with who entered it and when, on the run.

## Review run data after completion

A completed run is the canonical record of what was built. The review surfaces are described below.

### Run summary

The top of the run page shows headline stats:

* Steps completed.
* Cycle time, from start to completion.
* Operators involved.
* Issues opened during the run, with dispositions.
* Redlines applied.
* Build requirements installed, with counts and parts.

### Step-by-step view

Scroll the steps in their execution order. Each step shows:

* The operator who signed off, with a timestamp.
* Field values and measurement evidence, in-range or out-of-range.
* Files attached.
* Build requirement installs, including which units went where, with serials and lots.
* Comments.

### Transaction history

The transaction history is the audit trail. It surfaces every change to the run: status transitions, sign-offs, redline applications, issue links, and approvals.

### Part Installs (aBOM)

The completed aBOM is the parent and child tree of inventory records that compose the finished assembly. Open it from the run with the **Part Installs (aBOM)** tool. For the structure, see [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements). The aBOM is the input to traceability reports and downstream service and repair workflows.

## Reopen a run

You can reopen a run after completion to fix data, add a missed sign-off, or adjust an installed build requirement that was incorrect. Reopening requires admin permission and is recorded in the transaction history. For the reopening rules, see [Run and run step states](/build-hardware/runs-and-execution#states).

## What downstream systems get

After a run completes, several downstream surfaces consume its data:

* **Inventory**: the produced unit's state updates, and consumed inputs are marked accordingly.
* **Traceability reports**: the aBOM is part of the genealogy of the produced unit.
* **Analytics**: cycle time, step times, issue rates, and scrap rates aggregate into dashboards.
* **External integrations**: webhooks fire on run completion for ETL pipelines, ERP sync, and customer notification systems. See [Webhooks](/api-reference/guides/webhooks).
* **Customer documentation**: for customer-witnessed builds, the run record is the source for end-of-line reports.

## Cycle time analytics

Run cycle time, from start to completion, and per-step times propagate to dashboards under [Analytics and dashboards](/automate-with-ion/analytics-and-dashboards). For how run timestamps are set, see [Run and run step states](/build-hardware/runs-and-execution#states).

<Tip>
  If you have an ETL or ERP that depends on a run's data, set up a webhook on run completion rather than polling. See [Webhooks](/api-reference/guides/webhooks).
</Tip>

## Related

* [Run and run step states](/build-hardware/runs-and-execution#states)
* [Execute a run step](/build-hardware/runs-and-execution/step-execution)
* [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Webhooks](/api-reference/guides/webhooks)
* [Analytics and dashboards](/automate-with-ion/analytics-and-dashboards)


# Export run data
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/export-runs-data

Export a run's data, optionally bundled with its attachments, from the run's More options menu.

## Export a run

Export run data from an individual run using the **More options** menu in the run header. ION emails you a zip file containing the export.

1. Open the run.
2. Click the **More options** menu in the run header, then click **Export**.
3. In the **Export Run** dialog, choose what to include. Both are off by default and independent of each other:
   * **Include file attachments**
   * **Include assets**
4. Click **Export**. ION emails you a zip file when it's ready.

To print the run or save it as a PDF instead, see [Print a run report](/build-hardware/runs-and-execution/print-a-run-report).

## Export multiple runs to CSV

To export a set of runs at once, use the **Runs** page in **Table** view:

1. Select the runs to export.
2. Click **Export** in the toolbar.
3. ION downloads a CSV with a row per run, covering identity, status, part, procedure, quantity, progress, assignment, schedule, and batch.


# Overview
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/index

How ION models a run: its steps, states and rollups, batches, and the as-built record it produces.

A run is one execution of a procedure against a specific part inventory. It binds three things that travel through the rest of the build: the [procedure](/build-hardware/procedures) that defines the work, the part inventory the run produces or builds against, and the assignment of who does the work. The output is the as-built BOM (aBOM), the auditable record of what was built and what went into it. For a guided tour, see the [interactive walkthrough](https://firstresonance.storylane.io/share/yjkyllpxnor6).

A run holds an ordered set of **run steps**, each instantiated from a procedure step with the same fields and validations. Operators work steps at a work center, capture readings, install parts, and sign off. The run does not carry its own start action: it moves to `In Progress` when the first step starts, and rolls its status up from its steps.

## The Runs page

The **Runs** page lists your runs and is the entry point to everything below. A toggle in the header switches between two views: **Table**, the default sortable and filterable list, and **Timeline**, which plots every scheduled run (see [Schedule a run](/build-hardware/runs-and-execution/scheduling)). Shortcut cards above the table filter it to **My Runs** or **Overdue Runs**, jump you to a **Workcenter** queue, or open **Create Run**. The timer button in the header carries a count of your open check-ins and opens **My Active Check-ins**, so you can review or close them from one place (see [Time tracking](/build-hardware/runs-and-execution/time-tracking)).

The table's search box, with the placeholder `Search run #, title, batch, part #, procedure...`, matches a substring against the run's number, title, and description, its batch's number and title, the part's number, description, and revision, the procedure's number and title, and the run's labels. A run matching in any one of those is returned.

The **Due Date** column counts down instead of showing a calendar date, in the two largest units that apply: **Due in 3 days 5 hours** while the run is in flight, **Overdue by 2 days** once the date has passed, and **Due now** or **Overdue** when less than a minute separates the two. A run near its date or past it is colored to flag urgency, an on-track run stays muted, and a run that has settled shows the plain date. The control in the column header switches the whole column between the countdown and the exact date, and the urgency color carries over either way. Hovering a cell shows the other form: the exact date and time in your org's date format when the column shows the countdown, and the countdown when it shows the date.

Selecting runs in the table reveals a toolbar of bulk actions:

* **Batch** and **Unbatch** group or ungroup the selected runs. See [Manage run batches](/build-hardware/runs-and-execution/run-batches).
* **Export** downloads the selected runs as a CSV. See [Export run data](/build-hardware/runs-and-execution/export-runs-data).
* **Print Barcodes** opens a menu offering **Run labels** for every selected run and **Part inventory labels (N)** for the selected runs that have a part inventory. See [Print labels](/build-hardware/labels-and-scanning/printing).
* **Archive** removes the selected runs from the main list.
* **Cancel** cancels the selected runs and their steps. Runs that are already complete or canceled are skipped.

## Run steps

A run step is the unit of floor work. Each has a header, typed [fields](/build-hardware/runs-and-execution/step-execution), build requirements (parts to install onto the parent assembly), and action buttons. Steps render in procedure order, and dependencies between them gate which are available to work. To create a run and instantiate its steps, see [Create a run](/build-hardware/runs-and-execution/starting-a-run). To work a step through fields, measurements, sign-offs, and failure paths, see [Run a step](/build-hardware/runs-and-execution/step-execution). Operators can also process a queue of open steps for one location; see [Run steps at a work center](/build-hardware/runs-and-execution/workcenter-execution).

A run opens into three tabs: **Overview**, **Steps**, and **Dependencies**. The **Dependencies** tab shows the run's step dependency graph, the same view the [dependency manager](/build-hardware/procedures/procedure-dependency-manager) uses on a procedure. On a run, changing dependencies is a redline: both steps must be in `Redline` to draw a link between them. See [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations).

## States

Each run step carries a state. The run has no state of its own. Its status is derived from its steps.

| State           | What it means for a step                                                                                                                                                                                                                      | When the run shows it                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Todo**        | No work done yet. Initial state on creation.                                                                                                                                                                                                  | All steps `Todo`.                                                                        |
| **In Progress** | Started by a user, which records the run's start time on the first transition. A step can start only once its upstream dependencies are `Complete`. Leaving this state checks out anyone checked in.                                          | Any step `In Progress`.                                                                  |
| **Hold**        | Administrative pause that blocks work, shown in yellow.                                                                                                                                                                                       | Any step `Hold`.                                                                         |
| **Redline**     | Editable and cannot be run, shown in light red. Takes precedence over `Hold`. See [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations).                                                                                | Any step `Redline`.                                                                      |
| **Complete**    | All required fields filled and all work done.                                                                                                                                                                                                 | All steps `Complete`; the run reads `Complete` once the last required step signs off.    |
| **Failed**      | A part or process found non-conforming, or a failed inspection, shown in dark red. Set it with **Fail Step** after the step starts, and move it back to `Todo` or `Redline` to rework. Creates an issue automatically if your org enables it. | Any step `Failed`.                                                                       |
| **Canceled**    | Skipped work, shown in dark gray. Can move back to `Todo`.                                                                                                                                                                                    | All steps `Canceled`; a mix of `Complete` and `Canceled` rolls up as `Partial Complete`. |

**Available to work** is a separate calculation: a step is available when it is in `Todo` or `In Progress`, all upstream dependencies are `Complete`, and its parent step, if any, is `In Progress`.

Canceling a step removes it from the dependency graph, which rewires so downstream steps are not blocked by skipped work. Batched runs rewire each run's graph the same way.

A run never moves backward through completed states on its own. Reopening a `Complete` run requires admin permission and is recorded in the run's transaction history with the user, timestamp, and reason.

## Batches

A run batch groups runs that share steps so a sign-off, redline, or state change on one step propagates to every sibling step across the batch. Only sibling steps propagate; a step unique to one run is unaffected. Part installs do not cascade automatically. Batch at creation to avoid divergence between batched and unbatched siblings, or manage membership later. See [Manage run batches](/build-hardware/runs-and-execution/run-batches).

## Scheduling

A run carries a scheduled start, scheduled end, and due date, and each step carries its own schedule and lead time. When step schedules are set but the run's are not, the run takes the earliest start and latest end of its steps. The **Timeline** view on the Runs page plots every scheduled run. See [Schedule a run](/build-hardware/runs-and-execution/scheduling).

## Splitting inventory

When a subset of units on a run develops a problem, you split those units off onto an issue and into a separate location while the rest of the run continues. ION divides inventory by how far each unit has progressed: uninstalled parts allocate to each group independently, while already-installed parts link to both groups as shared until traceability resolves them. See [Split inventory on a run](/build-hardware/runs-and-execution/split-inventory-on-a-run).

## Outside processing

A procedure step flagged as an outside process links to a purchase order so you can send the part and operation to a supplier and receive it back into the run. Outside-process steps are not batched. See [Send a step to outside processing](/build-hardware/runs-and-execution/outside-processing).

## Time tracking

ION captures operator labor as check-in / check-out **sessions** on each step. Starting a step checks the operator in; completing, holding, redlining, or failing it checks them out. Operators cannot check into a step that is not available to work. Session data feeds cost and cycle-time analytics and can be edited. See [Time tracking](/build-hardware/runs-and-execution/time-tracking).

## Redlines and deviations

A redline is an in-flight modification to the procedure made on one run: add a step, edit a field, correct an instruction, or build a procedure as you fly. It lives on the run, not the procedure template, so it keeps the audit trail intact and can be reviewed, approved, and merged back into the procedure or other runs. A deviation is an accepted out-of-range measurement recorded with a rationale. See [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations).

## Labels

Labels are shared tags you apply across ION to group related records. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

To label a run, click **Labels** in the run header, then type in the **Search or create labels...** box and select a label. To create a new label, type its name and select the create option.

## Completion and review

Completing a run reconciles its accumulated state into the records downstream consumers rely on. ION blocks completion until every required step is signed off, every required field has a value, every build requirement is installed or excepted, and every required approval gate is satisfied. On completion, ION locks all step records, updates the produced inventory's state, and feeds the aBOM, traceability, and analytics. See [Complete and review a run](/build-hardware/runs-and-execution/completion-and-review). To pull a run's record out for analytics, see [Export run data](/build-hardware/runs-and-execution/export-runs-data).

<Tip>
  Your org can add **custom attributes** to runs for data the built-in fields don't cover. See [Manage run attributes](/build-hardware/runs-and-execution/attributes).
</Tip>


# Send a step to outside processing
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/outside-processing

Send a part and an in-process operation out to a supplier on a purchase order, then receive it back into the run.

Mark a procedure step as an outside process, and ION links it to a purchase order so you can send the part and the operation out and track the work alongside the run.

## Send an outside process out on a PO

1. In the procedure, turn on **Outside Processing** for the step.
2. Start a run that uses the procedure. The run step's right rail shows an **Outside Processing** section.
3. In the **Outside Processing** section, open the **Select a Purchase Order** dropdown and pick an existing purchase order, or click **Create PO** to make a new one. Either way ION links the purchase order to the run step.
4. Track the PO's live status from the run. The PO line's description records the run step it came from.

To swap the purchase order, clear the linked one first, then link another. Clearing the link leaves the purchase order and its line in place.

<Note>
  Run steps flagged as an outside process are not batched: a sign-off or redline on one does not propagate to sibling runs.
</Note>

<Note>
  When the run is part of a batch, linking, clearing, or creating a purchase order prompts **Apply to Batch?**. Choose **Just this run** to change only the current run, or **All runs** to apply the same purchase order to the matching step across every run in the batch.
</Note>

## Add an outside process step to a running run

To add an outside process to a run already in progress, add the step with a redline:

1. On the step you want to add the outside process after, open the **More actions** menu and choose **Add Step After**.
2. Enter a **Step Title** and turn on **Is Outside Processing**. You can also switch to **Copy from Library** to select an existing step.
3. Click **Put in redline and create** to redline the parent step and add the new step. If the parent is already in redline, the button reads **Create**.

<Note>
  Inventory out at the supplier sits in **WIP**, which is normally not kittable. Depending on your settings, WIP inventory linked to an outside-processing purchase order line is an exception. See [Allow kitting of WIP inventory for outside processing](/administration/supply-chain-settings/allow-wip-osp-kitting).
</Note>

## Related

* [Create a purchase order](/manage-supply-chain/purchasing/create-a-purchase-order)
* [Allow kitting of WIP inventory for outside processing](/administration/supply-chain-settings/allow-wip-osp-kitting)
* [Purchase consigned parts](/manage-supply-chain/purchasing/purchase-consigned-parts)
* [Run incoming inspections](/manage-supply-chain/receiving/run-incoming-inspections)


# Print a run report
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/print-a-run-report

Produce a printed or PDF record of a run, choosing which sections to include.

The run print preview renders a run as a paginated report you can print or save as a PDF. It's the as-executed record: what each step captured, what was installed, what was redlined, and what issues were raised. For a machine-readable copy of the same run, see [Export run data](/build-hardware/runs-and-execution/export-runs-data).

## Print a run

1. Open the run and choose **Print** from its **More options** menu. The print preview opens.
2. In **Print options**, clear any section you don't want in the report:
   * **Run Information**
   * **Batch**
   * **Progress**
   * **Run Attributes**
   * **Steps**
   * **Step Fields**
   * **Step Attributes**
   * **Step Timing & Work Sessions**
   * **Step Part Installations**
   * **Step Attachments**
   * **Step Comments**
   * **As-Built Parts (aBOM)**
   * **Issues**
   * **Redline History**
3. Click **Print or download PDF**, then use your browser's print dialog to send it to a printer or save it as a PDF. The button reads **Loading report…** until every section's data is in, so nothing prints half-loaded.
4. Click **Back to run** to return.

Your section choices are remembered for the next time you open a preview.

## What the report contains

The report opens with the run's title and status, then the sections you left on:

* **Batch** lists the run's sibling runs with their status and serial or lot number.
* **Progress** carries the run's completion and its labor-time rollup.
* Step cards nest to any depth and carry each step's fields (with validation pass or fail), custom attributes, timing and work sessions, datagrids, part installations, attachments, comments, and procedure feedback.
* **As-Built Parts (aBOM)** is the run's as-built bill of materials, including made-on-assembly descendants.
* **Redline History** lists each redline with its approval decisions: the reviewer, the outcome, the role, and the timestamp.

A step that came from a standard step renders the version the run is working from.

## Related

* [Export run data](/build-hardware/runs-and-execution/export-runs-data)
* [Complete and review a run](/build-hardware/runs-and-execution/completion-and-review)
* [Print a procedure report](/build-hardware/procedures/print-a-procedure-report)


# Redline a run
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/redlines-and-deviations

Modify a procedure mid-run when reality diverges from the plan, adding steps, editing fields, and documenting deviations without losing traceability or breaking parallel batched runs.

A redline is an in-flight modification to a procedure made during a specific run: split a step, add a field measurement, correct an instruction, add a missing step, or build a procedure as you fly. It lives on the run rather than the procedure template, so it edits the build with full traceability and can be reconciled back into the template later. For where redlines sit among the other run concepts, see the [Overview](/build-hardware/runs-and-execution).

<Note>
  Redlining a run needs a role that holds the **UpdateRedline** permission, in the **Redline** permission family. Resetting a redline's reviews needs **ResetRedlineApprovals** from the same family. See [Manage role permissions](/administration/users-and-permissions/manage-role-permissions).
</Note>

## When to use a redline versus an issue

These two are easy to confuse:

| Use a **redline** when…                                                                                            | Use an **[issue](/track-quality/issues)** when…                                |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| The procedure needs to change for this run, such as adding a step, modifying a field, or correcting an instruction | The part has a problem, such as a nonconformance, defect, or supplier issue    |
| The change is procedural: what work happens, in what order                                                         | The change is dispositional: what to do with the affected inventory            |
| You want to update the procedure template afterward                                                                | You want to disposition the affected unit, such as use as is, rework, or scrap |

Redlines and issues often go together: an issue might trigger a redline when a step missed something and you need to add a verification step. Both are recorded, both have reviewers, and both contribute to the build's history.

## Redline versus procedure revision

Redlines are for this build; procedure revisions are for the future. If the same change keeps recurring across runs, escalate to engineering and revise the procedure rather than redlining each run individually. A redline that should apply to every future build belongs in a procedure revision.

## Deviations

A **deviation** is an accepted out-of-range measurement: the team acknowledges a value fell outside its tolerance and records the rationale. The in-step mechanic for capturing an out-of-range value is covered in [Execute a run step](/build-hardware/runs-and-execution/step-execution).

## Start a redline

Both entry points are on a run step's **More actions** menu, in the run's **Steps** tab:

* To redline an existing step, open its **More actions** menu and click **Put Step into Redline**.
* To add a new step as a redline, open a neighboring step's **More actions** menu and click **Add Step Before**, **Add Step After**, or **Add Child Step**. The **Create New Step** dialog opens with **New Step Position** pre-filled from the step you started from, and you can edit that position before you create the step.

In the **Create New Step** dialog, set **Link to Issue** to tie the new step to an issue, then pick how to fill the step:

* On the **Create New** tab, enter a **Step Title**, pick a **Step Type** of **Content** or **DataGrid**, and turn on **Is Outside Processing** if a supplier does the work. This lets you build an entire run from scratch without a procedure, in a build-as-you-fly manner, then save the steps back to a procedure later through the merge process.
* On the **Copy from Library** tab, search for an existing step and select it. ION copies the step's title and content into the run at that position. Use the search box and the filters to narrow the results, so you can pull steps from a standard rework procedure in quick succession and approve them all at once.

Click **Create** or **Copy** to finish. When the parent step isn't already in redline, the button reads **Put in redline and create** or **Put in redline and copy** instead, and the dialog warns that the parent step will be put into redline. As with any redline, the new step must be approved and submitted.

## Edit a step in redline

Steps in redline are indicated with a warning at the top of the step and a red pencil icon on the step queue. While a step is in redline, you can edit, add, duplicate, or remove its content, fields, datagrid rows and columns, and values.

* Redline steps cannot be completed or failed.
* Canceling a redline at any time returns the step to its previous actionable condition.
* Dependencies attached to a redline step can be deleted. Both steps must be in redline to add a dependency between them.

## Redline a standard step

Redlining a standard step works the same way. Open the run step's **More actions** menu and click **Put Step into Redline**.

## Approve redlines

Assign reviewers to a redline, then each reviewer approves, rejects, or adds feedback for the editor to act on. The **Redlines** button in the run header carries a badge counting the run's redlines you can review, and its menu opens **Bulk Review** and **History**.

### Approve a single redline

The **Submit** button on the run step approves and submits in one click whenever you're permitted to approve. If you can approve the redline yourself, the button assigns you as the reviewer, records your approval, and submits the redline together, and its tooltip reads **Approve & submit**. If the redline is already approved, the button only submits, and the tooltip reads **Submit**. When a reviewer's approval is still required, the button is disabled with a **Pending reviewer approval** tooltip.

To always submit redlines automatically, enable [auto-submit redlines](/administration/quality-settings/enable-auto-submit-redlines) in settings.

### Review redlines in bulk

**Bulk Review** lists every redline on the run you can review beside a diff of the selected one, so a sequence of connected redlines can be reviewed together. This helps when a redline has been merged to many other runs.

1. In the run header, click **Redlines**, then click **Bulk Review**.
2. Click a redline in the list to read its diff.
3. Select the redlines to act on with their checkboxes, or click **Select all (N)**, where N is the number you can review.
4. Optional: type a comment in the box at the bottom of the panel.
5. Click **Approve all (N)** or **Reject all (N)**, or click **Leave feedback** to record the comment without a decision.

With one redline active and nothing selected, the same controls read **Approve** and **Reject** and act on that redline alone. To put reviewers on the selected redlines first, click **Assign**.

### Reset a redline's reviews

Once a reviewer approves a redline, the run step locks and the redline can't be edited. To make more changes without pushing the redline through a rejection, reset its reviews and start the review over.

1. Open the redline's review panel and expand the reviewers section.
2. Click **Reset Reviews**. Once any reviewer has approved, a warning above the button explains that the approval is in progress and blocks editing.
3. Confirm in the **Reset Approvals** dialog.

Every review request returns to pending and the redline becomes editable again. **Reset Reviews** appears once at least one reviewer has approved or rejected, and it works for both user-based and role-based approvals.

<Note>
  The number of approvers required and the roles allowed to review are configurable. See [set the redline approver count](/administration/production-settings/set-redline-approver-count), [configure procedure reviewer roles](/administration/production-settings/configure-procedure-reviewer-roles), and [configure standard step reviewer roles](/administration/production-settings/configure-standard-step-reviewer-roles).
</Note>

## Merge redlines

A redline improvement made on one run can be duplicated into other similar runs and into procedures. If 20 other runs use the same instructions, merging brings them all up to date in one push. Run steps and procedure steps you merge to automatically update to be identical to the source step when the merge is accepted.

A redline must be submitted before it can be merged. Merge it from **Redline History**, which the **History** item on the run header's **Redlines** menu opens, and which also holds the complete history of changes and feedback for each step. You have two merge targets:

* **Merge to Procedure Step**: merge to an existing step or to a new step at the end of the procedure. If the procedure is not in a draft state, ION creates a new draft version to merge into.
* **Merge to Run Step**: select many runs and steps to merge to. Before merging, assign a reviewer so they can approve all the merges at once instead of approving each merged redline independently. Once the merge completes, each destination run step is placed in redline and mirrors the source step. As with any redline, you still have to approve and submit them, so assign the reviewer before merging.

## Related

* [Run and run step states](/build-hardware/runs-and-execution#states)
* [Execute a run step](/build-hardware/runs-and-execution/step-execution)
* [Manage run batches](/build-hardware/runs-and-execution/run-batches)
* [Procedures](/build-hardware/procedures)
* [Issues](/track-quality/issues)


# Manage run batches
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/run-batches

Group runs that share steps so a single sign-off, redline, or status change propagates to every batched run at once.

A run batch groups runs that share steps so a sign-off, redline, or state change on one step propagates to every sibling step across the batch. For what propagates and when to batch, see the [Overview](/build-hardware/runs-and-execution).

A batch is identified by its title, and a title can belong to only one batch. Reusing a title therefore adds the runs to the batch that already holds it, which ION calls a merge. The runs table, the batch manager, and the run creation form each warn before that happens.

## Prerequisites

* The runs you want to batch must follow procedures whose step structure matches enough to have shared ("sibling") steps. Two runs of the same procedure version are the canonical case.
* Permission to modify run batch membership.

## Batch runs from the runs table

Both entry points open the same picker:

* **One run**: click **Add to batch** in the run's **Batch** column.
* **Several runs**: select them, then click **Batch** in the floating toolbar.

In the picker:

1. Search **Existing batches** by name. Each option shows the batch number and how many runs it holds. Select one to add the runs to it.
2. To create a batch instead, type a name and select the **Create ""** row. Leave the box empty and select **Create new batch** to create one with no title.
3. If the name you typed is already taken, the create row warns **Merges into Batch #**, and selecting it opens a **Merge into Batch #?** confirmation stating how many runs are already there and how many you're adding. Click **Add to Batch #** to go ahead, or **Cancel**.

From that point, changes to shared steps propagate across the batched runs.

A batch created without a title displays as **Batch #**. Its title stays empty, so the number isn't a name another batch can collide with.

To open a batched run's batch from the runs table, click its **Batch** column.

## Open the batch manager

Once a run is in a batch, open the batch manager from inside the run: click the batch pill in the run header, then click **Manage batch**. The dialog header reads **Batch&#x20;**&#x20;(or **Batch :&#x20;**&#x20;once a title is set). If the run is no longer in a batch, the dialog shows "This run is no longer in a batch." Inside the dialog you'll see:

* A title row below the header. Click it to set or edit the batch title.
* **Search runs in batch**: filter the runs list by run ID or run title.
* **Add a run to the batch** dropdown: multi-select picker for runs not yet in the batch.
* **Expand all** / **Collapse all**: toggle the run cards open or closed.
* **Unbatch all**: footer action to remove every run from the batch.

## Add runs to a batch

1. In the batch manager, click **Add a run to the batch**.
2. Search runs by title or ID in the dropdown. Before you search, the list holds only runs that aren't in a batch yet. Searching also reaches runs held by other batches, each labeled **in&#x20;**, so you can move one here without going to the other batch first. Runs that are complete or canceled never appear.
3. Multi-select the runs you want, then click **Add N to batch** in the dropdown footer. Use **Clear selection** to reset.
4. If any selected run is leaving another batch, a confirmation asks whether to move the runs between batches and lists each one with where it moves from and to. Click **Move runs** to go ahead. Unbatched runs in the same selection are added with no prompt.

After ION updates the batch, those runs immediately participate in propagation for any future changes on shared steps.

## Set or rename the batch title

Click the title row below the dialog header to enter edit mode. Type the new title, then click **Submit**. Cancelling reverts to the previous title. The title shows up alongside the batch ID in the run header and run list.

If another batch already uses the title, the field warns that **Batch #** already uses it and that saving will move this batch's runs into it. Submitting opens a **Merge into Batch #?** confirmation before anything is written. Confirming moves this batch's runs into the other batch, and the batch you renamed stays behind with no runs. The confirmation says so before you commit to it.

## Remove a run from a batch

In the runs list, click **Remove** on the run you want out, or **Remove & go to run** to remove it and open it. ION asks you to confirm. After you confirm, the run continues independently from that point forward. It keeps any sign-offs and redlines it accumulated while batched.

## Unbatch every run

Click **Unbatch all** in the dialog footer. ION asks you to confirm before clearing the batch. After confirming, every run leaves the batch and continues independently. The batch itself is dissolved.

## Batch propagation

When you change a step inside a run that belongs to a batch, ION looks at every other run in the batch and finds **sibling steps**: steps in those runs that match the same step in the batched procedure. The change propagates to every sibling found:

* **Sign-offs**: completing or signing a step propagates the same completion to every sibling step.
* **Redlines**: redline changes propagate to siblings. For how redlines are merged across runs, see [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations).
* **State changes**: skipping, failing, or reopening a step propagates to siblings.

If a step is unique to the current run, with no siblings, only the current run changes.

### Cascade an aBOM install across the batch

Part installs are not cascaded automatically. Adding a build requirement to a run that belongs to a batch adds it to that run alone, and its card in the **Part Installs (aBOM)** tool carries a **This run only** badge. To cascade it, turn on **Edit Mode** and click **Apply to N runs in batch** on the card; one action adds the requirement to every sibling unit that doesn't already carry it, and a toast reports how many runs received it. The count on the button is the number of siblings still missing the requirement, so the button disappears once every sibling has it. Cascading is a deliberate click, so an edit to a single run stays the default.

Cascading is offered only on the top-level aBOM of a batched run opened from a run step. Inside a sub-assembly's aBOM, a requirement stays on the run you added it to.

## Assign aBOM parts across the batch

On a run that belongs to a batch, the **Part Installs (aBOM)** tool installs parts into every batched run at once, so you assign inventory one time for the whole batch instead of opening each run.

Open the tool from the run step's **Part Installs (aBOM)** panel: click **View all**. Each build requirement card carries a **Batch assignment** section in place of the single-run installer. Expand the card to work with it. A card shows this section whenever the run is batched, for serial-tracked, lot-tracked, and non-tracked parts.

The section header reads **Batch assignment** until you install anything, then switches to **Batch results**. A count sits next to it: **N assigned** and **N unassigned** before you install, and **N installed** (plus **N failed** and **N still unassigned** when either applies) afterward.

### Pick an anchor and auto-assign

The section opens on an anchor picker and an **Auto-assign** button. The picker's label depends on how the part is tracked:

* **Anchor lot** for a lot-tracked part.
* **Starting serial** for a serial-tracked part.
* **Anchor inventory** for a non-tracked part.

Search the picker and select the inventory to spread across the batch. For lot and non-tracked parts, each option shows its available quantity, such as `LOT-A · 372 available`. Once you pick an anchor, a preview line states how many slots or runs will fill.

To fill every run's requirement from the anchor onward, click **Auto-assign**. The anchor takes priority: each run's primary assignment draws from the anchor lot or inventory first, and the assignment spreads to other available inventory only after the anchor runs out. A confirmation bar reads "Auto-assigned from anchor. Edit any row before installing." To assign each run by hand instead, open the caret next to **Auto-assign** and choose **Assign manually**.

<Note>
  If the anchor holds less than every run needs, a warning states how much is available and confirms that Auto-assign fills what it can while the rest needs manual assignment.
</Note>

### Stage each run's kit inventory

When runs in the batch have their own reserved kit inventory for the part, a callout reads "Kit inventory is available for N of M runs." Click **Assign from kits** to stage each run's reserved lot or serial into that run's row. Each run draws only from its own kit, so one run's kit can't fill another run's row. If a kit holds less than the run requires, ION stages what the kit has and leaves the rest for manual assignment. Review and edit the staged rows before installing.

The callout appears both on the anchor picker and in the assignment table toolbar whenever any batched run has an open kit for the part.

### Review and adjust the assignment table

After assigning, the table lists one row per batched run under the columns **Run**, **Inventory**, **Qty** (for lot and non-tracked parts), and **Actions**. Each row carries a status pill: **Unassigned**, **Assigned**, **Partially assigned**, **Installing**, **Partially installed**, **Installed**, or **Errored**.

Change any row before installing:

* In the **Inventory** cell, pick a different lot, inventory record, or serial. Clear an assignment with its **X**.
* For lot and non-tracked parts, edit the quantity in the **Qty** cell against the run's requirement, shown as **of N**.
* Assign more inventory to one run through additional legs, or add a serial to a serial row.

<Note>
  For a lot or non-tracked part, you can assign more than a run requires as long as real stock covers it. The quantity cell shows an **Over-installing (N required)** hint, where N is the requirement. Over-installation is available only when the run's requirement lives on a single run step. If a quantity exceeds available stock, the cell shows **Only N available** and blocks the install instead.
</Note>

A run whose build requirement does not match the current one shows an **Unavailable** pill and a message that its aBOM does not match. Install that run's part from its own run instead. Use **Open run** to go there.

### Assign by reference designator

When the build requirement carries [reference designators](/build-hardware/bills-of-materials/reference-designators), each run's row lists one entry per designator in place of the **Inventory** and **Qty** cells. This applies to lot-tracked parts as well as serial-tracked ones.

* Pick the inventory for each designator separately.
* Installing writes one unit against each designator, tagged with that position, so the run step reads every designator as assigned.
* The row's status pill follows how many designators are filled.
* Uninstalling targets the install behind a single designator.

<Frame>
  <img alt="Batch assignment table with Run, Inventory, and Actions columns. Each of the two run rows carries an Assigned pill and three designator entries, F1, F2, and F3, each holding the same lot." />
</Frame>

### Install and uninstall across the batch

Install the staged assignments from the table footer:

* Click **Install N assigned** to install every assigned row. While installs run, the button reads **Installing… (X of Y)**. A results bar then reports the installed, failed, and still-unassigned counts.
* Install a single run with the download action in its **Actions** cell.

To undo assignments or installs:

* Click **Unassign all** to clear every staged assignment that is not yet installed. Installed rows are not affected. ION asks you to confirm.
* Click **Uninstall all** to remove every install in the batch. ION asks you to confirm. Installed serials return to an editable **Assigned** state with their serial numbers kept. Installed lot and non-tracked rows return to unassigned.
* Uninstall a single run with the trash action in its **Actions** cell.

## Related

* [Runs and execution](/build-hardware/runs-and-execution)
* [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations)
* [Procedures](/build-hardware/procedures)
* [Bills of materials](/build-hardware/bills-of-materials)


# Place a run step on hold
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/runs-best-practices

Put a run step on hold and comment the reason so others can see why work is paused.

Place a run step on **Hold** to pause work on it, and add a comment so anyone looking at the run step can see why.

1. Navigate to the target run step within the run.

2. Open the run step's **More actions** menu and choose **Put Step on Hold**.

3. Add a comment describing the reason for the hold, for example, "Step placed on hold due to lack of part availability."

The comment is attached to the run step and visible in the run step sidebar, so others can understand the context of the hold.

<Note>
  Step cards show symbols indicating comments on the procedure, run step, and redline objects, giving a single reference point for hold-related documentation.
</Note>


# Schedule a run
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/scheduling

How to schedule runs in ION and view your factory schedule.

## Scheduling a step

To schedule a step, open it (**Runs**, click a run, then **Steps**), open the step's **More actions** menu, and click **Schedule**. Pick a start and end date in the panel that appears. The menu item shows the scheduled range once it's set. For how step schedules roll up to the run, see the [Overview](/build-hardware/runs-and-execution).

## Viewing the production schedule

From the **Runs** page, switch the view toggle in the header from **Table** to **Timeline**, marked **Preview**. The timeline plots every scheduled run in your factory. Runs without a schedule show a **No schedule** marker.

Controls along the timeline toolbar shape the view:

* **Group by** arranges runs into swimlanes by a property such as status, assignee, or part.
* **Sort** orders the runs, for example by scheduled end or due date.
* **Properties** chooses which fields show on each row and on the run bars.
* The zoom control sets the time scale to **Day**, **Week**, or **Month**, and **Today** scrolls back to the current date.

Clicking a run on the timeline opens a side panel where you can set its scheduled start, scheduled end, and due date. The timeline reflects your changes automatically.


# Split inventory on a run
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/split-inventory-on-a-run

Split a subset of in-process units off a run into a separate inventory location while the rest of the run continues.

When a subset of units on a run develops a problem, you can split those units off into a separate location and keep the rest of the run moving. You create an issue ticket for the affected units, assign them a location such as an MRB cage, and continue running the remaining units. For how ION divides inventory by install state, see the [Overview](/build-hardware/runs-and-execution).

For example, during receiving you inspect 10 parts from a supplier and find that 3 have visual defects. You split those 3 parts onto an issue, move them to a separate location, and let the other 7 continue through your process.

For more information, see [Issues](/track-quality/issues).

## How inventory splits by install state

When you split units off a run, ION divides inventory based on how far each unit has progressed: no installs, full or partial installs, or a mix. The final locations of child inventory reflect the locations of the child parts after the split.

### No parts installed yet

Nothing has been installed onto the units being produced. When you split off some units, ION divides all required parts between the two groups. Each split-off group gets its own list of parts to install, and because nothing was installed beforehand, each group's requirements are independent.

### Some or all parts installed

Work has started and some parts are installed. When you split off a few units, ION cannot tell which installed parts belong to which group. ION links both sets of units, the ones staying in production and the ones you split off, to the already-installed parts. Each group shows the installed parts as shared, meaning the parts could belong to either set. This keeps every part accounted for and gives both groups the components they need.

### Mix of installed and uninstalled parts

Some parts are installed and others are not. ION handles the installed parts as in the previous case, linking them to both groups and showing them as shared. ION allocates the uninstalled parts separately to each group based on the split. Production continues for the unaffected units while the split-off units stay accounted for.

## aBOM installation sharing among parent assemblies

When aBOM installations are shared across split parent assemblies, calculate how much quantity and cost to attribute to one aBOM by dividing the shared installation across the parent assemblies it could belong to.

A build requirement that was already installed before the split becomes a single install record linked to every lot that resulted from the split. Each of those lots shows the part as installed, and the [aBOM](/build-hardware/bills-of-materials/as-built-bom) for each lot lists the same install. This keeps the original build history intact for lots that share upstream work, rather than duplicating an install that only one lot could physically own.

Because the sharing lots point at one record, an edit made from any of them reaches all of them. Adding an install, changing an installed quantity, or removing an install applies to every lot the build requirement is linked to, not only the lot on screen. A build requirement that was empty at the time of the split is instead copied independently to each lot, so later installs on one lot stay on that lot.

ION marks a shared install on the build requirement row so you can tell before you edit. The row shows a **Shared with N lots** indicator, and opening it lists the lots the install is linked to, grouped as:

* **Direct siblings**: the lots produced together in the same split as the lot you are viewing.
* **Other related lots**: lots that share the install through an earlier or later split in a multi-generation chain, such as a lot split once into LOT-AB, then split again into LOT-ABC.

### Remove a shared install

Removing an install from a shared build requirement removes it from every lot in the sharing set at once, so ION confirms the action first.

1. On the build requirement, start the uninstall.
2. In the **Warning: Removing from a shared aBOM** dialog, review the affected lots, grouped into **Direct siblings** and **Other related lots**.
3. Click **Cancel** to keep the install, or **Continue** to remove it from every listed lot.
4. After you confirm, the removal is held for about 10 seconds. A countdown toast lets you **Cancel** before it applies. If you don't cancel within that window, the install is removed from every sharing lot.

<Note>
  Install and quantity changes on a shared build requirement apply to every linked lot without a separate confirmation. Only removing an install opens the confirmation dialog, because it clears the install from all sharing lots at once. Read the affected-lot list before you continue, and click **Cancel** on the countdown toast if you started the removal on the wrong set.
</Note>

Per-lot divergence, where each lot after a split can carry a fully independent aBOM, is a separate capability under development. Today, an install that existed before a split stays shared across the resulting lots until you uninstall it.

## Related

* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Trace as-built inventory](/build-hardware/bills-of-materials/trace-as-built)
* [Issues](/track-quality/issues)


# Create a run
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/starting-a-run

Create a run by binding a procedure to a part inventory, configure pre-run options, and assign it to an operator or work center.

Starting a run moves a build from planned to actively producing, binding a procedure to a part inventory and an assignment. For how ION models those pieces, see the [Overview](/build-hardware/runs-and-execution). This page covers creating a run from each of the common entry points.

## Prerequisites

* A released procedure for the target part.
* For an attach run, an existing part inventory record for the unit (created automatically when the part is staged from receiving, kitting, or a parent run). For a build run, ION creates the inventory on completion.
* Permission to create runs in your organization.

## Where to start a run

| You're starting from…     | Use this entry point                                                                    |
| ------------------------- | --------------------------------------------------------------------------------------- |
| The Runs page             | **Create Run** button in the header, or the **Create Run** shortcut card                |
| The procedure             | **Create Run** button on the procedure page (the procedure is pre-filled in the wizard) |
| A schedule (planned work) | The timeline view: see [Schedule a run](/build-hardware/runs-and-execution/scheduling)  |

Each path opens the same run wizard and ends with a run in **Todo**, ready for an operator to pick up.

## The run wizard

The wizard walks top to bottom through five steps: **Source**, **Part**, **Identify**, **Details**, and **Review**. The stepper at the top tracks your position, and you can click a step to jump to it.

<Frame>
  <img alt="New Run wizard showing the Source, Part, Identify, Details, and Review stepper, with the Source step asking where the inventory comes from and the Part fields below." />
</Frame>

<Steps>
  <Step title="Source">
    Choose where the run's output inventory comes from:

    * **Build a new item**: the run creates a new part that becomes inventory on completion.
    * **Use an item already in inventory**: attach existing stock instead of creating new. This is the path for a kit or sub-assembly already on the floor.
  </Step>

  <Step title="Part">
    Pick the **Part** this run produces. Optionally pick a **Procedure** (released procedures only), or leave it blank to add one later. When you open the wizard from a procedure page, the procedure is already selected here.

    The run's steps come from the procedure's steps, in the same order and with the same fields and validations.

    When the **Require part-procedure relationship** setting is on, the selected part and procedure must have an approved association. If they don't, this step shows the message "The selected part must be associated with and approved for the selected procedure," and you can't advance to **Review**. See [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship).

    <Warning>
      The procedure revision is locked when the run is created. If you revise the procedure while a run is in progress, that run continues on the version it was created with, and new runs pick up the new revision.
    </Warning>
  </Step>

  <Step title="Identify">
    In **Build a new item** mode, choose how completed units are tracked:

    * **Serialized**: one unit per serial number.
    * **Lot-tracked**: units grouped under a lot number, with a quantity.
    * **Quantity only**: a count, with no serial or lot.

    ION pre-selects the tracking type the part is configured for. For serial and lot numbers you can enter a value or check **Auto-generated** to have ION assign one.

    In **Use an item already in inventory** mode, this step instead asks you to pick the existing **Inventory item** to attach.
  </Step>

  <Step title="Details">
    Name the run and set who's responsible:

    * **Run name**: enter a name, or check **Auto-generated**. The auto-generated name encodes the run and target part. Enter your own if your org tracks builds by a different identifier, such as a customer PO, lot, or build number. The run name is the first thing operators see in any list.
    * **Due date** (optional).
    * **Export controlled** toggle.
    * **Assigned to** (optional): a user or team. Assigning the run makes it show up on their work view. Leave it unassigned to let anyone pick it up. Depending on your settings, this field is pre-filled with you and an unassigned run lands on its creator. See [Auto-assign runs to their creator](/administration/production-settings/auto-assign-runs-to-their-creator).
    * Any organization-defined custom attributes.
  </Step>

  <Step title="Review">
    Each run you've authored appears as a row. Click **Edit details** on a run to reopen the wizard and change its details. You can also set a number of **Copies** and **Duplicate** it, or remove it. Use **Add another run** to author more in the same session. To batch the runs together, check **Batch runs** and name the batch. If another batch already uses that name, the field warns that the runs will be added to the existing batch, and creating opens a merge confirmation first. Steps in batched runs share sign-offs and redlines. For more information, see [Manage run batches](/build-hardware/runs-and-execution/run-batches). You can also add a run to a batch later.

    Click **Create run** (or **Create N runs** / **Create batched run**) to create everything in the list.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No procedures available for this part">
    The part has no procedures associated. Either link the procedure to the part, or open the wizard from the procedure page so the procedure is pre-filled. See [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship).
  </Accordion>

  <Accordion title="The selected part must be associated with and approved for the selected procedure">
    The **Require part-procedure relationship** setting is on, and the part and procedure have no approved association. A missing, **Pending**, or **Rejected** association all block the run. Approve the association on the part's **Procedures** section, then continue. See [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship).
  </Accordion>

  <Accordion title="Part inventory is not in a state that allows a new run">
    When you attach an existing inventory item, the unit is **Consumed**, **Installed**, or **Scrapped**. You can't start a run on inventory that's already been used. Check the inventory's state on the inventory page.
  </Accordion>

  <Accordion title="Procedure has unreleased steps">
    The procedure isn't **Released**, or some of its steps aren't approved. Release the procedure first, then start the run.
  </Accordion>
</AccordionGroup>

## Programmatic creation

For integrations that schedule runs from an external system (MES, ERP, custom dispatcher), see [Common Queries → Create a Run](/api-reference/examples).

## Related

* [Run and run step states](/build-hardware/runs-and-execution#states)
* [Execute a run step](/build-hardware/runs-and-execution/step-execution)
* [Manage run batches](/build-hardware/runs-and-execution/run-batches)
* [Link a part to a procedure](/build-hardware/procedures/part-procedure-relationship)
* [Procedures](/build-hardware/procedures)
* [Common Queries → Create a Run](/api-reference/examples)


# Run a step
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/step-execution

Run a step through fields, measurements, pass/fail, approval gates, sign-off, and the failure paths.

To run a step, open the run step, fill in the required fields, record measurements, attach evidence, and complete it. ION captures the result, propagates it to the relevant data downstream, such as analytics, traceability, and batched siblings, and unlocks the next run step. For the full set of step states and their transitions, see [Run and run step states](/build-hardware/runs-and-execution#states).

## Check into a run step

On a **Todo** run step, click **Start / Check In** to move it to **In Progress** and begin capturing your labor time. Starting the run step also moves the WIP assembly, and any inventory installed on it, to the run step's location. While it's in progress, **Check In** and **Check Out** let you start and stop your own session. Completing, holding, failing, or redlining it checks you out. For how check-in and check-out sessions are recorded and edited, see [Time tracking](/build-hardware/runs-and-execution/time-tracking).

This location move is on by default. To keep inventory where it is when a step starts, turn on **Disable auto location update on run start**. See [Disable auto location update](/administration/supply-chain-settings/disable-auto-location-update).

## Fill in fields

Each run step can have any number of fields defined on the procedure. Common field types:

* **Number**: a measurement, often paired with a validation (`min`, `max`, `target ± tolerance`).
* **Pass/Fail**: a single-select with two options, the simplest quality gate.
* **Text**: free-form notes or values that don't have a structured type.
* **Date**: when something happened, such as an inspection date.
* **Single-select / Multi-select**: pick one or many from a controlled list.
* **File**: attach an image, drawing, or document. For more information, see [File upload](/api-reference/guides/file-upload).
* **Boolean**: yes or no.

Fields can be marked **required**. ION blocks run step completion if any required field is empty.

## Measurements and validation

When a numeric field has a validation (target, min, or max), ION evaluates your input as soon as you save the field:

* **In range**: the field shows green, and you can complete the run step.
* **Out of range**: the field shows red, and completion is blocked unless the run step's policy allows out-of-range values with an [issue](/track-quality/issues) attached.

Out-of-range measurements that the team accepts with a rationale become **deviations**. For more information, see [Redlines and deviations](/build-hardware/runs-and-execution/redlines-and-deviations).

## Build requirements (parts to install)

If the run step has build requirements, the parts to install onto the parent assembly during this run step, they list on the **Part installs** tab in the run's right rail. Each requirement shows:

* The part to install.
* The required quantity.
* Substitutes, if configured.
* The current install state, incomplete or complete.
* An **Installed** count of the units installed against it, summing the installed quantity across every recorded install rather than the number of installs.

A requirement whose quantity is 0 is an as-required part, such as adhesive or a shim. In place of a required count it reads **As required**, followed by the quantity installed so far. ION treats it as outstanding until something is installed against it, so it stays in the list and counts as not yet installed in the panel's progress figure. Because there's no target to reach, an as-required part never blocks completing the run step or the run, and its install control stays available after it reads complete.

You install a part by scanning its part inventory serial or lot, or by selecting from a picker. Your organization can require a barcode scan for installs. For more information, see [Require barcode scanning for installations](/administration/production-settings/require-barcode-scanning-for-installations). ION does the following:

* Validates that the scanned unit matches the required part or an approved substitute.
* Confirms the part inventory is installable. A scan is accepted when the status is **Available**, **Kitted**, or **Safety reviewed**, and **Kitted** stock only when it is kitted to this run.
* Records the install and links the part inventory to the parent's aBOM.
* Moves the installed inventory to the assembly's location. Afterward, moving the assembly moves all installed inventory with it, through the full depth of the aBOM.
* Counts down the requirement's remaining quantity.

The install picker asks a wider question: it offers inventory with available quantity, plus stock kitted to this run. Scrapping stock, or kitting it to another run, reduces the quantity available to install, so once nothing is left the picker stops offering it. Kit stock reserved for a different run isn't shown either.

When the list holds at least one lot **Kitted** to this run, the picker splits into two groups: **From kit** at the top, followed by the kit's name when only one kit is involved, and **Other inventory** below. With no kitted stock to show, the list is ungrouped.

<Warning>
  Stock kitted to this run is offered whatever its status, so a lot that was kitted and then scrapped
  or marked unavailable still appears. It never groups under **From kit**, since only **Kitted** stock
  does. Read each candidate's status badge before selecting it.
</Warning>

To narrow a long list, click the search control and type a part number, description, or an installed serial or lot to filter the requirements. The **Hide complete** toggle hides requirements that are fully installed, and an as-required requirement stays visible until something is installed against it. **View all** opens the full aBOM in the **Part Installs (aBOM)** dialog. For editing the aBOM there, see [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements).

When all build requirements on a run step are satisfied or explicitly excepted, the run step is ready to complete.

### Edit a run step's build requirements

Depending on your settings, the **Part installs** section becomes editable while the run step is in **Redline**, so a change to what the step installs is captured as a redline like any other run step change. Putting the step into redline and taking it out is done from the run step's own actions, not from this section. For more information, see [Redlines and deviations](/build-hardware/runs-and-execution/redlines-and-deviations).

While the step is in redline, you can:

* Change a requirement's quantity for this step, in place on the requirement.
* Remove a requirement from the step, which leaves the part on the aBOM.
* Add a part with the add-part control (**+**) in the section header. The picker separates the two outcomes into groups, and one search box narrows both:

  * **On this assembly** lists the assembly's existing build requirements that this run step doesn't already carry. Picking one only maps it to the run step.
  * **All other parts** carries the note *Adding one also adds it to the assembly's requirements*. Picking one creates the build requirement on the aBOM first, then maps it to the run step.

  To create the new requirement as made on assembly, turn on the **Made on assembly** switch in the picker's footer before you pick. It applies only to parts added to the assembly, so an existing requirement keeps how it was created, and the switch resets each time the picker closes. For more information, see [Made on assembly (MOA)](/build-hardware/bills-of-materials/made-on-assembly).
* Add a substitute that applies to this step only, from the **Substitutes** section header.

The install controls are hidden while the section is editable, because the step is locked for execution during an edit.

## Sign-off fields

Approval gates are configured on the procedure as **sign-off fields**, an extra check before the run step can be completed. Common patterns:

* **Quality Engineer sign-off** on critical inspection steps.
* **Witness sign-off** on irreversible operations, such as fastener torque, sealing, and lid close.
* **Customer sign-off** for customer-witnessed builds.

Each sign-off field is tied to a role and shows **Expecting approval by:** that role. Only a member of that role can act on it, using **Approve** or **Reject**. A required sign-off field blocks completion until it's approved, the same as any other required field.

## Complete a run step

When fields are filled, build requirements installed, and any sign-off fields approved:

1. Check in to the run step, then click **Complete**.
2. ION records who completed the run step and when, checks you out, and updates the run step status to **Complete**.
3. The next run step, if any, becomes the active run step for the run.

If the **Complete** button is disabled, ION lists what's still outstanding (empty required fields, unapproved sign-offs, or uninstalled build requirements) so you can resolve it first. Completion is logged in the run's transaction history with the user and timestamp.

### When required installs block completion

When a build requirement is what's holding the run step back, the error names each one and what's unmet:

* The part is short on quantity, with how much is required and how much is installed.
* Reference designators have no install, listed by designator.
* Reference designators are installed on only some of the parent units, with the count for each.
* A [made-on-assembly](/build-hardware/bills-of-materials/made-on-assembly) sub-assembly isn't fully installed, with its percentage and which of its children are incomplete.

<Note>
  The percentage the aBOM shows counts quantity only. A requirement whose quantity
  is fully installed can still read 100% and block the run step, because one of its
  reference designators has no install against it. The error names the designators
  in that case.
</Note>

<Frame>
  <img alt="Error message stating a step cannot be completed because it still has unfulfilled required installs, listing for each of two units the part short on quantity and the reference designators with no install." />
</Frame>

In a [run batch](/build-hardware/runs-and-execution/run-batches), the requirement blocking the run step often belongs to a sibling unit rather than the one in front of you, so each part of the error names the unit it came from. Serialized units are named by serial number and lot-tracked units by lot number. A unit with neither is identified only as another unit in the batch, so if your units aren't serialized or lot-tracked, open the batch to find the one that's short.

## Fail a run step

When you hit an outcome that can't be passed, open the run step's **More actions** menu and:

1. Click **Fail Step**.
2. Provide a reason as free text, with an optional issue link.
3. The run step transitions to **Failed**.

A failed run step doesn't fail the run automatically. The run stays **In Progress**. Common follow-ups:

* **Rework**: fix the failure and re-run the run step. Depending on the procedure config, the run step can be reopened or a duplicate inserted.
* **Disposition via issue**: open an issue against the run step, capture the disposition (Use As Is, Rework, or Scrap), and let the issue lifecycle drive the next action. See [Issue states](/track-quality/issues).
* **Fail the run**: if the failure can't be resolved at all, transition the run to **Failed**.

## Attachments

Attach files to a run step, such as images, PDFs, and STEP/STP files, up to 100 MB each. These are separate from any file captured in a File field.

1. On the run step, open the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking **Browse files**, or clicking **Take a photo** on a device with a camera.

To remove a file, use its delete control and confirm in the **Delete attachment?** dialog.

## Run step redlines

Mid-run, you can redline the procedure: add a run step, modify a run step's fields, or correct an instruction. For more information, see [Redlines and deviations](/build-hardware/runs-and-execution/redlines-and-deviations).

## Related

* [Run and run step states](/build-hardware/runs-and-execution#states)
* [Create a run](/build-hardware/runs-and-execution/starting-a-run)
* [Redline a run](/build-hardware/runs-and-execution/redlines-and-deviations)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Disable auto location update](/administration/supply-chain-settings/disable-auto-location-update)
* [Line-side inventory](/manage-supply-chain/inventory/line-side-inventory)
* [Issues](/track-quality/issues)
* [Submit a run step result](/api-reference/examples)


# Time tracking
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/time-tracking

Review and edit the check-in and check-out sessions that capture labor time on run steps.

ION captures the labor time operators spend on run steps as check-in and check-out **sessions**, which feed cost and cycle-time estimates in [Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards). For how sessions open and close with step transitions and the availability rules, see the [Overview](/build-hardware/runs-and-execution).

## Review session data

To see how long you've been checked into a step and the total labor time for that step, click the timer indicator on the step in run execution mode. This opens the **Checked-In Duration** dialog, which lists each session's user, check-in time, check-out time, and labor time, along with the total labor time for the step.

The timer indicator on the run header opens the **Run Check-In History** dialog, which groups sessions by run step and totals the labor time across the whole run.

## Edit session times

You can correct a recorded check-in or check-out time when you have the `UpdateSession` permission or the admin role. Editing is available only on a completed session, one that has already checked out. You cannot edit an active session.

1. Open the **Checked-In Duration** or **Run Check-In History** dialog from the timer indicator.
2. On the row for the session, click the edit control.
3. Set the check-in and check-out times in the two time pickers. The check-in time must be before the check-out time. Otherwise ION blocks the save and shows **Check-out must be after check-in**.
4. Click the save control to commit the change, or the cancel control to discard it.

You can also update session durations through the API. For more information, see [Edit time-tracking session data](/api-reference/guides/edit-time-tracking-session-data).

## End an active session

With the `UpdateSession` permission or the admin role, you can check out another user who is still checked into a step. In the session dialog, click **End Session** on the active session's row, then confirm. ION checks that user out immediately.

## See your active check-ins

A user who is checked into a step is highlighted with a ring around their avatar.

The timer button in the run workspace header shows a count of your active sessions and opens **My Active Check-ins**, a table of every step you're currently checked into. Each row lists the **Run**, **Step**, when you checked in (**Checked In**), and the **Elapsed** time. Click **Check Out** on a row to close that session, or **Check Out from All Sessions** to close them all at once.

## Get checked out after inactivity

While you're checked into a step, ION watches for activity. After 10 minutes with none, it opens the **Are you still there?** dialog. Click **Yes, I'm still here** to stay checked in, or **No, check me out** to close the session. This keeps an idle session from inflating a step's labor time.

## Use a smart card badge to log in

Badge authentication lets several users log in with a badge and check into run steps quickly. The following example configures badge authentication to Windows 10 hosts, using these components:

* Smart card: Taglio PIVKey C910.
* Smart card reader: HID Omnikey 5422.
* Smart card certificate: Smart Card Logon.

To set up badge authentication:

1. Configure a Smart Card Logon certificate template on your internal Windows Certificate Authority (ADCS).
2. Grant a predefined security group read and enroll access in the template's permissions.
3. Write a PowerShell script to request a certificate (certreq), set a PIN on the badge (PivKeyTool), and write the certificate to the badge (certutil).
4. Run the PowerShell script. The badge can then log in to a Windows 10 device.
5. Insert or touch the badge to the reader, then enter the PIN.

Once the badge authenticates to the operating system, the browser (Chrome or Edge) can carry that authentication to your identity provider, which signs the user in to ION. To reduce ongoing maintenance, you can automate the certificate request and set up certificate revocation on your certificate authority so a user does not accumulate certificates across badges.


# Run steps at a work center
Source: https://docs.firstresonance.io/build-hardware/runs-and-execution/workcenter-execution

Work a queue of open run steps for a single work center, completing them in sequence and delivering each to its next location.

Working at a work center lets you process a queue of open run steps in one place rather than jumping between individual runs. From the **Runs** page, open the **Workcenter** shortcut card and pick a work center. ION opens the work center workspace, showing every open run step for that location grouped into queue sections.

## Step queue

The queue groups the work center's run steps into collapsible sections:

* **Overdue**: steps past their scheduled end.
* **Now**: steps you (or someone) are currently checked into.
* **Next**: ready, unblocked steps to pick up next.
* **Blocked**: steps waiting on a dependency or other blocker.

Select a step to open it in the center pane. The step header, the linked inventory card if any, and the work instructions appear there.

## Work a step

For fields, measurements, build requirements, sign-off fields, and failure paths, see [Run a step](/build-hardware/runs-and-execution/step-execution). The same action buttons apply here: **Start / Check In**, **Check In**, **Check Out**, **Complete**, and **Create Issue**.

The action bar shows the step's location, which you can change with the location picker. Use the arrow next to it to switch lenses: **View in Run** jumps to the same step inside its run, so you can see where it sits in the full sequence.

## Related

* [Run a step](/build-hardware/runs-and-execution/step-execution)
* [Run and run step states](/build-hardware/runs-and-execution#states)


# Overview
Source: https://docs.firstresonance.io/build-hardware/tools/index

How ION models a tool: a tool model as a part, its serialized inventory, subtypes, maintenance interval, and derived maintenance status.

A tool in ION is a kind of [part](/build-hardware/parts). A tool model is a part with type `Tool`, and its physical units are tool inventory: individual, serialized instances of that model. One model can back many units. Tools are always serialized; there are no lot-tracked or untracked tools.

You curate the definition in the [Tools Library](/build-hardware/tools/manage-tool-models) and act on the physical units in [Tools Inventory](/build-hardware/tools/manage-tool-inventory). Both surfaces live in the **Supply Chain** section of the sidebar. Procedure steps reference tools to record which unit an operator used.

## Subtypes

A subtype groups tool models beyond their tool number. Torque wrenches of several models can share a `Torque Wrench` subtype, which lets a run step call out a class of tool without naming one model. You set subtypes in the **Subtypes** field on a tool model, and a model can carry more than one. A step's [tool field](/build-hardware/tools/record-tool-usage) can then validate against a subtype to accept any unit spanning those models. For the steps, see [Manage tool models](/build-hardware/tools/manage-tool-models#categorize-tools-with-subtypes).

## Fields

A tool model carries the part fields plus a few tool specifics.

| Field                    | Notes                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| **Tool Number**          | Identifies the tool model. Required.                                                          |
| **Revision**             | Engineering revision value. Required. Revising creates the next revision as a new record.     |
| **Description**          | Free text.                                                                                    |
| **Subtypes**             | One or more groupings the model belongs to.                                                   |
| **Maintenance Interval** | How long a unit stays in service after each service date. Applies to every unit of the model. |

A tool unit carries the model reference plus its own fields.

| Field                 | Notes                                                                    |
| --------------------- | ------------------------------------------------------------------------ |
| **Serial Number**     | Unique identifier for the unit. Required.                                |
| **Tool / Part**       | The tool model this unit instances. Required.                            |
| **Location**          | Where the unit sits. An unavailable location makes the unit unavailable. |
| **Last Service Date** | When the unit was last serviced. Drives the service due date.            |
| **URI**               | Optional link, such as a calibration certificate.                        |

<Tip>
  Your org can add **custom attributes** to tool models for data the built-in fields don't cover. See [Custom attributes](/administration/custom-attributes).
</Tip>

## Maintenance interval and status

The maintenance interval lives on the tool model; each unit carries its own last service date. ION adds the interval to a unit's last service date to derive a **Service Due** date, and from that a **Maintenance Status** of **Available** or **Unavailable**. A unit past its service due date reads **Overdue** and **Unavailable**; a unit in an unavailable location also reads **Unavailable** regardless of its service schedule. If the interval or the last service date is missing, service due reads `N/A`. See [track maintenance status](/build-hardware/tools/manage-tool-inventory#track-maintenance-status-and-service-due).

## Tool usage on runs

A procedure step can require a tool through a **Tool** field. When the step runs, the operator selects the unit they used, creating an auditable usage log. The field can restrict input to a subtype or a single model, and can accept only units that are currently available. See [Record tool usage on a run](/build-hardware/tools/record-tool-usage).

## Best practices

### Plan tool requirements

Before you add tools to your procedures, map what each operation needs:

* List every operation in your process and the tools each one requires, then map each operation to its tool requirement.
* Record the maintenance cycle and criteria for each tool.

Then add a **Tool** field to each step that needs one, set its validations and whether the tool is required, and specify which tools are valid for the operation. See [Record tool usage on a run](/build-hardware/tools/record-tool-usage). This surfaces gaps between tool inventory and operation requirements, and enforces tool use at the operation level.

### Report on tools

Pull tool data into reports to manage tools proactively. Reports can draw on any tool unit [field](#fields), such as its service due date, last service date, and status. Automate delivery on a cadence or by condition, for example:

* A weekly report on all tools, sent to your tool manager.
* A report of tools two weeks before their service due date, so a calibration or maintenance date is never missed.
* A report of tool inventory that is currently unavailable and needs maintenance or recalibration.
* A report of tools that have been unavailable for a set period.


# Manage tool inventory
Source: https://docs.firstresonance.io/build-hardware/tools/manage-tool-inventory

Add individual serialized tool units, record their last service date, and track maintenance status and service due dates.

You manage [tool inventory](/build-hardware/tools) units in **Tools Inventory**: in the **Supply Chain** section of the sidebar, click **Tools Inventory**.

## Add a tool to inventory

1. On the **Tools Inventory** page, click **Create Tool Inventory**.
2. Enter a **Serial Number** and pick the **Tool / Part** (the tool model). Both are required.
3. Optionally set a **Location**, a **Last Service Date**, and a **URI**.
4. Click **Create**.

## Record a tool's last service date

Open a tool unit to reach its detail page. In the **Tool Information** card, set the **Last Service Date** with the date picker. The change saves automatically. The **Service Interval** shown next to it is read-only and comes from the tool model's maintenance interval.

## Track maintenance status and service due

Each tool unit shows a **Maintenance Status** badge and, while in service, its **Service Due** date. ION [derives both](/build-hardware/tools#maintenance-interval-and-status) from the model's maintenance interval and the unit's last service date.

<Note>
  For additional tool-availability behavior, such as integration with a tool management system, contact your Customer Success Manager.
</Note>

## Move, print, or view history

On a tool unit's detail page, click **Actions** to open the **Tools Inventory Actions** dialog, which has **Move**, **Print**, and **History** tabs. To print barcode labels, use the **Print** tab; for label setup see [Print a label](/build-hardware/labels-and-scanning/printing). To remove a unit, open the **...** menu and click **Delete**.

## Add labels to a tool unit

Labels are shared tags you apply across ION to group related records. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

To add a label, click **Labels** (or **Add labels** when the tool unit has none), then type in the **Search or create labels...** box and select it. To remove one, click the **X** on the label.

## Attach files to a tool unit

Attach files such as images, PDFs, and STEP/STP files, up to 100 MB each.

1. On the tool unit, find the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking to browse, or taking a photo on a device with a camera.

To remove a file, click its delete control and confirm.

<Note>
  When a file is attached through a file-type custom attribute, the delete dialog offers **Remove from attribute** (keeps the file but detaches it) and **Delete permanently**.
</Note>

## Related

* [Manage tool models](/build-hardware/tools/manage-tool-models)
* [Record tool usage on a run](/build-hardware/tools/record-tool-usage)
* [Print a label](/build-hardware/labels-and-scanning/printing)


# Manage tool models
Source: https://docs.firstresonance.io/build-hardware/tools/manage-tool-models

Create tool models in the Tools Library, categorize them with subtypes, set maintenance intervals, revise them, and delete them.

You manage [tool models](/build-hardware/tools) in the **Tools Library**: in the **Supply Chain** section of the sidebar, click **Tools Library**.

## Create a tool model

1. On the **Tools Library** page, click **Create Tool**.
2. Enter a **Tool Number** and **Revision** (both required).
3. Optionally add a **Description**, one or more **Subtypes**, and a **Maintenance Interval**.
4. Click **Create Tool**.

ION opens the new tool model's detail page.

## Categorize tools with subtypes

Add [subtypes](/build-hardware/tools#subtypes) in the **Subtypes** field when you create a tool model or from the tool model's detail page; type a name and select an existing subtype, or create a new one on the spot.

## Set a maintenance interval

Enter the [maintenance interval](/build-hardware/tools#maintenance-interval-and-status) as a list of `{number}{unit}` segments using this shorthand:

| Shorthand | Unit   |
| --------- | ------ |
| `d`       | Day    |
| `h`       | Hour   |
| `m`       | Minute |

For example, `1d 2h 20m` is an interval of 1 day, 2 hours, and 20 minutes.

## Edit a tool model

Open a tool model from the Tools Library to reach its detail page. Fields in the **Tool Information** card edit in place and save automatically, including subtypes and any custom attributes.

* To revise the model, click **Create New Revision**. ION creates the next revision and opens it.
* To remove the model, open the **...** menu and click **Delete**. Deletion can't be undone.

## Comment on a tool

Comments let you discuss a tool model with your team.

1. On the tool model, find the **Comments** section.
2. In the **Add a comment...** field, type your comment. You can format the text and `@`-mention a user to notify them directly.
3. Click **Comment**.

To reply to a comment, use its reply control. To close a thread, resolve it; a resolved comment can be reopened later.

## Attach files to a tool

Attach files such as images, PDFs, and STEP/STP files, up to 100 MB each.

1. On the tool model, find the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking to browse, or taking a photo on a device with a camera.

To remove a file, click its delete control and confirm.

<Note>
  When a file is attached through a file-type custom attribute, the delete dialog offers **Remove from attribute** (keeps the file but detaches it) and **Delete permanently**.
</Note>

## Related

* [Manage tool inventory](/build-hardware/tools/manage-tool-inventory)
* [Record tool usage on a run](/build-hardware/tools/record-tool-usage)
* [Manage parts](/build-hardware/parts/creating-managing)


# Record tool usage on a run
Source: https://docs.firstresonance.io/build-hardware/tools/record-tool-usage

Require a tool on a procedure step with a Tool field, then log which tool was used during run execution.

To [capture which tool an operator used](/build-hardware/tools#tool-usage-on-runs), add a **Tool** field to a procedure step.

## Require a tool on a procedure step

1. While editing a step, add a field and choose the **Tool** field type.
2. Set the field name and help text as you would for any data-collection field.
3. To accept only tools that are currently available, select **Only accept "Available" tools**.
4. Use the **Validations** menu to constrain valid input:
   * **Type** restricts input to a tool [subtype](/build-hardware/tools/manage-tool-models#categorize-tools-with-subtypes), spanning multiple models.
   * **Part Number** restricts input to one specific tool model.

For the full list of step field types, see [Step field types](/build-hardware/procedures/step-field-types).

## Select a tool during a run

When an operator reaches the step in a run, the Tool field shows a **Select a tool...** picker listing tool inventory that meets the field's validations. The operator picks the tool they used to complete the field.

## Related

* [Step field types](/build-hardware/procedures/step-field-types)
* [Manage tool inventory](/build-hardware/tools/manage-tool-inventory)
* [Run a step](/build-hardware/runs-and-execution/step-execution)


# ION basics
Source: https://docs.firstresonance.io/getting-started/ion-basics

Global tools for working in ION: the dashboard, Search, personal settings, chat support and tickets, the sandbox, and supported browsers and devices.

The basics every ION user needs before diving into their role's workflows: where you land after signing in, how to find anything, personal setup, and where to get help.

## The dashboard

When you sign in, ION opens the dashboard. This is the landing page for your account. It shows a **Factory Dashboard** header with two controls:

* **ION Marketplace**: opens the [ION Marketplace](https://marketplace.firstresonance.io/) in a new tab.
* **Refresh**: reloads the dashboard.

You can return here at any time from **Dashboard** in the sidebar. To move into your work, use [Search](#search) or the sidebar.

<Note>
  The dashboard shows a placeholder in place of factory metrics.
</Note>

## Browser and device compatibility

### Supported devices

ION is tested and supported on:

* **iPads** (up to two major iOS versions before the latest release)
* **Microsoft Surface Pro**
* **Mac computers** (laptops and desktops)
* **Windows computers** (laptops and desktops)

ION is built for tablets and desktop-sized monitors. Some areas may work on mobile, but the full application is not supported on mobile devices.

### Supported browsers

ION is tested primarily on **Google Chrome**. Edge, Firefox, and Safari are also supported.

## Search

ION Search lets you navigate and find records from anywhere in ION. Open it from any page with **Ctrl+K** (Windows/Linux) or **⌘+K** (Mac), or click the magnifying glass in the sidebar.

Navigate the bar with the arrow keys and press **Enter** to select. Close it by clicking outside the popup, pressing the same key combination, or pressing **Escape**. You can find main pages, help documents, and specific records within ION.

### Command list

When you open the search bar with nothing selected, it lists every command available to you. Navigate the list with the mouse or keyboard.

<Note>
  The key combinations shown on each command are keyboard shortcuts. You can run them without opening the search bar.
</Note>

Opening it while rows are selected in a table narrows the resting list to the commands that act on that selection, so a bulk edit isn't buried in the full list. Start typing and the search covers every command again. Some tables have no commands of their own; those open the full list as usual.

Dismissing the bar, by clicking outside it, pressing **Escape**, or closing it, also clears the row selection. Running a command leaves the selection in place, so you can run several commands against the same rows.

### Search records

Search also does keyword search of ION records like runs, procedures, issues, locations, purchases, and parts. It runs automatically as you type.

### Help docs

Scroll to the **Help** section of the command bar to browse the manual. You can also search the manual directly by typing your query into the command bar.

## Chat support and tickets

The chat bubble at the bottom right of ION connects you to the support team, and every conversation becomes a tracked ticket.

### Start a chat

1. Click the chat bubble icon at the bottom right of your ION environment.
2. Select **Start New Chat**.
3. Type the details of your issue and send the message.

ION creates a support ticket from the conversation automatically.

<Note>
  If you don't see the chat bubble, an ad-blocker may be hiding it. Disable your ad-blocker and it will appear.
</Note>

### Track your company's tickets

To see the tickets reported by your company's team, go to the [support portal](https://support.firstresonance.io/):

1. Enter your email address to receive a login code. The code scopes the portal to your company's tickets only.
2. Enter the code and click **Continue**.

You land on a page listing every conversation started by ION users at your company. Click a ticket to open the conversation; you can continue a ticket started by someone else.

## Personal settings

Personal settings apply only to your own account: your profile details, your account-level switches, and how ION looks to you.

### Edit your profile

1. In ION, go to **Settings > My Profile**.
2. Click **Edit profile**.
3. Change your **Name**, or click your profile picture to set a new image by URL.
4. Click **Save changes**, or **Cancel** to discard.

The page also lists the teams and roles you belong to. Those are managed by an admin; see [Manage team members](/administration/users-and-permissions/manage-team-members) and [Manage user roles](/administration/users-and-permissions/manage-user-roles).

### Account switches

Under **Settings** on the **My Profile** page, two toggles control your account:

* **Enforce MFA**: require multi-factor authentication for this account.
* **Email notifications**: also receive your notifications by email. You always receive them in the app; this switch adds email delivery, per user. Which objects notify you is driven by your subscriptions, see [Subscribe to notifications](/automate-with-ion/notifications/subscribe-to-notifications).

### Choose a theme

1. In ION, go to **Settings > Appearance**.
2. Under **Theme**, pick one of the cards:
   * **Light**: bright, high-contrast.
   * **Dark**: the classic dark theme.
   * **Slate**: cool blue-gray, with depth.
   * **Graphite**: warm neutral, easy on the eyes.
   * **System**: match your device.

The theme applies immediately and only affects your own account.

## Practice in the sandbox

ION offers a sandbox environment where you can practice your workflows and try out features without affecting your production environment. Sandbox access is provisioned separately from production and uses its own credentials, so your production login won't work there. To set up a sandbox for your team, contact [support](https://support.firstresonance.io).

Once your sandbox is provisioned, sign in at the sandbox URL that matches your production URL:

| If your production URL is   | Your sandbox URL is                 |
| --------------------------- | ----------------------------------- |
| app-v2.buildwithion.com     | app-v2.staging.buildwithion.com     |
| app-v2.gov.buildwithion.com | app-v2.staging.gov.buildwithion.com |
| app-v2.ap.buildwithion.com  | app-v2.staging.ap.buildwithion.com  |

For building and testing integrations against the ION API in a sandbox, see [Sandbox and dev environments](/api-reference/sandbox).


# CXOs
Source: https://docs.firstresonance.io/getting-started/role-guides/cxos

How executives and cross-functional leaders use ION: analytics, the data spine, and the questions ION can answer about your operation.

## What ION does for you

If you run a hardware company, or run a function inside one, ION is the source of truth about what your factory is actually doing. Not what you projected, not what the spreadsheets last updated showed: what's running right now, what's stuck, what's been built, what shipped, where defects came from. It's the operational system underneath the metrics, not just the metrics layer on top.

The point isn't that you'll be in the product day-to-day. The point is that your analysts, your VP of Ops, your VP of Quality, and your VP of Engineering all share *one* underlying system, with one model. The questions you ask cross-functionally have one answer instead of three.

## Where to start

1. **[What is ION?](/)**: the 5-minute orientation. Read this once.
2. **[Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards)**: the built-in reporting surface.
3. **[API reference](/api-reference)**: for the analyses your team will inevitably want to run outside the UI.

## The questions ION can answer

These aren't all the questions, but they're the ones that come up most.

| Question                                                           | Where the answer lives                                                                |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| What's our as-built configuration on serial #ASM-00427?            | [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)                |
| Which suppliers had the highest defect rate last quarter?          | [Quality reporting](/track-quality/quality-reporting) + supplier issues               |
| How long is a unit really sitting at each work center?             | [Runs and Step States](/build-hardware/runs-and-execution#states)                     |
| What's our open NCR backlog by disposition?                        | [Issues and NCRs](/track-quality/issues)                                              |
| What inventory is committed to in-flight runs vs. truly available? | [Inventory](/manage-supply-chain/inventory)                                           |
| Which procedures have the highest redline rate?                    | [Redlines and Deviations](/build-hardware/runs-and-execution/redlines-and-deviations) |

## What to ask your team for

* **A live dashboard of in-flight runs by program**: easy to build off the API, useful for the weekly operating review.
* **A monthly aBOM-vs-mBOM divergence report**: catches drift between design intent and what's actually shipping.
* **A supplier scorecard derived from receiving inspections + run-time NCRs**: see [Issues](/track-quality/issues).
* **An open-issue aging report**: anything in containment or open disposition that's been there too long.

<Tip>
  - **Don't ask for the metric. Ask where the metric comes from.** Metrics out of context are misleading; the same query in ION can be sliced six different ways and produce six different answers. Have your team document the query.
  - **Trust the aBOM.** When something goes wrong in the field, the aBOM is the legally-defensible record of what was actually built. Make sure your team is generating clean aBOMs *before* you need them.
  - **The API is more powerful than the UI.** Anything you can do in the dashboards, you can do (and automate) over [GraphQL](/api-reference). Make sure your analytics team has access.
</Tip>

## Related

* [What is ION?](/)
* [Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards)
* [API reference](/api-reference)


# Design Engineering
Source: https://docs.firstresonance.io/getting-started/role-guides/design-engineering

How design engineers use ION: releasing parts and BOMs, authoring procedures, and keeping the design intent connected to what actually gets built.

## What ION does for you

If you spend your time in CAD, drawings, and release packages, ION is where your design intent meets the factory. You release parts and BOMs into the part library, you author the procedures that build them, and version control means you always know which revision of which procedure is in production right now, without chasing engineers, operators, or supervisors.

You probably won't be in the manual every day. The point is that when you change a part, a BOM, or a procedure, ION makes the consequences visible: which runs are in flight against the old version, which need to migrate, what's already built that you can't change. No more silently shipping the wrong revision.

## Where to start

1. **[Parts](/build-hardware/parts)**: the part library. Understand part vs. part inventory and how revisions work.
2. **[Bills of Materials](/build-hardware/bills-of-materials)**: the planned structure. The mBOM is your design intent; the aBOM is what actually got built. Understanding both is the heart of traceability.
3. **[Procedures](/build-hardware/procedures)**: the work instructions. Steps, fields, attributes, version control, and how procedures attach to parts.
4. **[Runs and Execution](/build-hardware/runs-and-execution)**: see what your procedures look like in operation, even if you're not the one running them.

## The handful of pages that matter most

| Page                                                                                  | Why it matters to you                                                         |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Parts](/build-hardware/parts)                                                        | How the part library is structured; the difference between part and inventory |
| [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)      | The shape of the planned structure you release                                |
| [BOM Versions and Change Management](/build-hardware/bills-of-materials/versions)     | What happens when you change a BOM mid-program                                |
| [Procedure Best Practices](/build-hardware/procedures/procedure-best-practices)       | Patterns for procedures that age well and don't fight the floor               |
| [Reference Designators](/build-hardware/bills-of-materials/reference-designators)     | Position-coded build requirements for assemblies, quality-relevant            |
| [Alternates and Substitutes](/build-hardware/bills-of-materials/substitutes)          | Letting the floor swap supplier-equivalent parts without filing a deviation   |
| [Redlines and Deviations](/build-hardware/runs-and-execution/redlines-and-deviations) | What floor changes to your design look like coming back at you                |

<Tip>
  * **Configure alternates upfront.** If you know two part numbers are interchangeable, encode it on the BOM. Otherwise every supplier swap is a deviation.
  * **Use reference designators when position matters.** A reference-designated build requirement makes "the wrong part went in slot R7" detectable; an unpositioned one makes it forensic-only.
  * **Don't make procedures too granular too early.** Each step adds floor friction. Author at the level the operator actually needs to confirm, and refine after watching real runs.
  * **Read aBOMs, not just mBOMs.** Spending an hour comparing what got built vs. what you specced is the fastest route to understanding where your design and the factory disagree.
</Tip>

## Related

* [Build Hardware](/build-hardware): the section you'll spend the most time in
* [API reference](/api-reference): if you need to push designs from PLM/PDM programmatically
* [What is ION?](/): for the broader product spine


# Manufacturing Engineering
Source: https://docs.firstresonance.io/getting-started/role-guides/manufacturing-engineering

How manufacturing engineers use ION: process design, scheduling, NPI, resource planning, and turning floor signal into upstream improvements.

## What ION does for you

You own the flow. ION lets you author procedures, set up work centers and locations, build the schedule, and then watch, in something close to real time, how the plan is meeting reality on the floor. When a run blocks, when a step takes 3× expected, when an operator files a redline, you see it. That's the signal you use to tune the process, push back upstream on bad designs, and improve cycle time.

Most days you'll bounce between three things: authoring or revising procedures, looking at run progress, and handling exceptions (parts on hold, issues that need disposition, scheduling collisions).

## Where to start

1. **[Procedures](/build-hardware/procedures)**: your primary authoring surface. Steps, fields, standard steps, dependencies.
2. **[Runs and Execution](/build-hardware/runs-and-execution)**: how the procedures you authored play out on the floor. Run states, batches, scheduling.
3. **[Locations and Work Centers](/build-hardware/locations-and-work-centers)**: the physical map of your factory. Get this right and scheduling gets dramatically easier.

## The handful of pages that matter most

| Page                                                                                    | Why it matters to you                                               |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Procedure Best Practices](/build-hardware/procedures/procedure-best-practices)         | Patterns that scale and don't generate floor friction               |
| [Standard Steps](/build-hardware/procedures/standard-steps)                             | Reuse step content across procedures so you fix things in one place |
| [Procedure Dependency Manager](/build-hardware/procedures/procedure-dependency-manager) | What changes when you change a procedure, and what's safe to change |
| [Run Batches](/build-hardware/runs-and-execution/run-batches)                           | Lot/batch builds and their gotchas                                  |
| [Runs and Step States](/build-hardware/runs-and-execution#states)                       | The state machine you'll be debugging when runs stall               |
| [Redlines and Deviations](/build-hardware/runs-and-execution/redlines-and-deviations)   | The floor's primary signal back to you                              |
| [Issues and NCRs](/track-quality/issues)                                                | Quality events on parts you handle every day                        |

<Tip>
  * **Standard steps over copy-paste.** When the same instruction appears in five procedures, make it a standard step. The day you need to change it, you'll thank yourself.
  * **Watch runs, not just procedures.** A clean procedure document and a messy real run are common; the gap is your improvement opportunity.
  * **Treat redlines as the symptom, not the bug.** A redline means the spec didn't match reality. Fix the spec.
  * **Plan for parallel work.** ION's scheduling and run-batch features assume you'll have multiple runs of multiple parts overlapping. Lean into that, don't model your factory as one queue.
</Tip>

## Related

* [Build Hardware](/build-hardware): your home section
* [Track Quality](/track-quality): the other end of your day
* [Automate with ION](/automate-with-ion): automations you can wire into runs and procedures
* [What is ION?](/)


# Production Technicians and Operators
Source: https://docs.firstresonance.io/getting-started/role-guides/production-technicians-and-operators

How floor operators use ION: run execution, scanning parts, capturing data, and raising issues without leaving your workstation.

## What ION does for you

ION is your daily tool. You execute procedures step-by-step on the runs your supervisor (or scheduling) routed to your work center. You scan in parts, capture readings, attach photos, and when something's wrong on the floor, you file an issue *from inside the run*, no chasing supervisors, no separate paper form.

The goal is that you spend your time *building*, not navigating tools. If you find yourself doing more clicking than building, something is misconfigured upstream and your manufacturing engineer should hear about it.

## Where to start

1. **[Runs and Execution](/build-hardware/runs-and-execution)**: the operator-facing flow: open a run, work the steps, install parts, hit done.
2. **[Workcenter Execution](/build-hardware/runs-and-execution/workcenter-execution)**: kiosk mode and shared workstation patterns for teams.
3. **[Issues and NCRs](/track-quality/issues)**: how to raise a quality issue mid-run when something's wrong with a part or step.

## The handful of pages that matter most

| Page                                                                                        | Why it matters to you                                                            |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [Runs and Execution](/build-hardware/runs-and-execution)                                    | The exact flow of executing a run on the floor                                   |
| [Runs and Step States](/build-hardware/runs-and-execution#states)                           | What "in progress", "blocked", "done" actually mean                              |
| [Editing Build Requirements](/build-hardware/bills-of-materials/editing-build-requirements) | Add or swap a part mid-run when the BOM is wrong for what you have on hand       |
| [Label Printing and Barcodes](/build-hardware/labels-and-scanning/printing)                 | Print serial labels and scan-in installs                                         |
| [Issue Lifecycle](/track-quality/issues)                                                    | What happens to an issue you raise: states, dispositions, who owns the next step |
| [Redlines and Deviations](/build-hardware/runs-and-execution/redlines-and-deviations)       | When the procedure doesn't match reality, this is the right channel              |

<Tip>
  * **Scan, don't type.** If your work center has a scanner, every install should be a scan. Typing serial numbers is the #1 source of bad data.
  * **File the issue *now*, not after the shift.** Issues filed in-context (right from the run step) carry the run, the step, the part, and the operator, all auto-populated. Issues filed after the fact need all that re-entered.
  * **Don't fight the procedure silently.** If a step is wrong, missing, or in the wrong order, file a redline. Quietly working around it leaves engineering with no signal that the procedure needs to change.
</Tip>

## Related

* [Runs and Execution](/build-hardware/runs-and-execution)
* [Issues and NCRs](/track-quality/issues)
* [Labels and Scanning](/build-hardware/labels-and-scanning)
* [What is ION?](/)


# Purchasing and Supply Chain Specialists
Source: https://docs.firstresonance.io/getting-started/role-guides/purchasing-and-supply-chain-specialists

How purchasing and supply chain teams use ION: POs, receiving, inventory, supplier data, and feeding real consumption signal into MRP.

## What ION does for you

You buy the parts that the factory consumes, and you do it in the same system the factory builds in. That means real consumption, actual run-by-run usage, not stale snapshots, flows directly into MRP and reorder logic. Receiving feeds inventory, inspection drives supplier scorecards, and the issues raised on the floor against a specific lot are visible to you when you talk to that supplier next.

Day-to-day you'll work POs and receiving, manage inventory locations and transactions, and watch supplier performance signals coming back from production.

## Where to start

1. **[Purchasing](/manage-supply-chain/purchasing)**: purchase orders, approvals, supplier records.
2. **[Receiving](/manage-supply-chain/receiving)**: receipt against POs, inspection, and turning shipments into part inventory.
3. **[Inventory](/manage-supply-chain/inventory)**: locations, lots, serials, transactions, and the merging/splitting/transferring you'll do daily.
4. **[Kitting](/manage-supply-chain/kitting)**: pulling parts ahead of a run.

## The handful of pages that matter most

| Page                                                                                | Why it matters to you                                                                     |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Purchase Order Approvals](/manage-supply-chain/purchasing/approve-purchase-orders) | Multi-step approval flows for higher-value buys                                           |
| [Receiving and Inspection](/manage-supply-chain/receiving)                          | The handoff from supplier shipment to usable inventory                                    |
| [Inventory Merging](/manage-supply-chain/inventory/merge-inventory)                 | Combining like inventory and the constraints                                              |
| [Alternates and Substitutes](/build-hardware/bills-of-materials/substitutes)        | Letting the floor consume an approved alternate without a deviation, saves you firefights |
| [Issues and NCRs](/track-quality/issues)                                            | Quality events on supplier parts: your scorecard input                                    |
| [API reference](/api-reference)                                                     | Pulling consumption data into your existing reporting                                     |

<Tip>
  * **Pre-configure alternates.** If two supplier part numbers are interchangeable for an assembly, configure them as alternates on the BOM. Otherwise every "we ran out, used the other one" is a deviation that lands on your desk.
  * **Inspect at receiving, not at install.** Floor operators discovering bad parts in the middle of a run is the most expensive way to find a quality issue. Catch it at the dock.
  * **Use serial-and-lot tracking on the parts that matter.** Critical components, traceable parts, and anything subject to recall should be lot-tracked at minimum. Untracked simplifies bookkeeping but kills traceability.
  * **Watch the supplier score, not just the PO state.** A supplier that ships on time but generates 3× the NCR rate is a problem; ION's data lets you see both axes.
</Tip>

## Related

* [Manage Supply Chain](/manage-supply-chain)
* [Build Hardware → BOMs](/build-hardware/bills-of-materials): particularly substitutes and reference designators
* [Track Quality](/track-quality): issues attached to supplier parts
* [What is ION?](/)


# Quality Engineering
Source: https://docs.firstresonance.io/getting-started/role-guides/quality-engineering

How quality engineers use ION: issues and NCRs, dispositions, CAPA workflows, and turning manufacturing data into upstream improvements.

## What ION does for you

ION gives you data: engineering data (torques, voltages, dimensions captured during build), production data (shifts, machines, operators, sensors), and quality data (issues, dispositions, CAPAs), all in one model, all queryable. Instead of stitching exports from MES, QMS, and ERP every audit cycle, you point at one system. The same data is in the API, so you can build dashboards, reports, and statistical analyses without waiting on someone to extract a CSV.

Day-to-day you'll be working issues: triaging incoming NCRs, pushing parts through their disposition workflow, owning CAPAs, and feeding root-cause findings back into design and process.

## Where to start

1. **[Issues and NCRs](/track-quality/issues)**: the heart of your day. Lifecycle, dispositions, resolutions.
2. **[Containment](/track-quality/containment)**: what to do the moment a defect surfaces.
3. **[Further Actions (CAPA)](/track-quality/further-actions)**: corrective and preventive action, tracked through to verification.
4. **[Quality reporting](/track-quality/quality-reporting)**: yield, escape, NCR-by-cause analytics.

## The handful of pages that matter most

| Page                                                                                  | Why it matters to you                                                       |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Issue Lifecycle](/track-quality/issues)                                              | The state machine your tickets live in                                      |
| [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)                | The traceability record. Every quality investigation starts here.           |
| [Redlines and Deviations](/build-hardware/runs-and-execution/redlines-and-deviations) | A leading indicator of defects, and a recurring one means a process problem |
| [Reference Designators](/build-hardware/bills-of-materials/reference-designators)     | Position-coded installs make "wrong part in R7" detectable, not forensic    |
| [Further Actions (CAPA)](/track-quality/further-actions)                              | The feedback loop into process and design                                   |
| [Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards)               | Build the reports you need without IT involvement                           |
| [API reference](/api-reference)                                                       | When the dashboards aren't enough and you need raw data                     |

<Tip>
  * **The aBOM is your forensic tool.** Every field failure investigation starts at the as-built BOM of the failing unit. Get fluent with how to walk it from a serial number all the way down to lot codes of the components installed.
  * **Watch redline rate, not just NCR rate.** A high redline rate on a procedure means floor reality and the spec disagree, even if no NCRs have been filed yet. That's a leading indicator.
  * **Close the CAPA loop.** Verification is the only step that proves the corrective action actually worked. Skipping it means the CAPA is theater.
  * **Data lives in the API.** When the built-in dashboards stop fitting, GraphQL is the next stop. See [API reference](/api-reference) → [Common Queries](/api-reference/examples).
</Tip>

## Related

* [Track Quality](/track-quality)
* [Build Hardware](/build-hardware): to understand the data you'll be analyzing
* [API reference](/api-reference)
* [What is ION?](/)


# Introduction
Source: https://docs.firstresonance.io/index

What ION is, how this manual is organized, and where to start by role.

## What is ION?

ION is the Factory OS for hardware companies: the system of record for your manufacturing process. Parts, the procedures that build them, the runs that execute those procedures, the BOMs they produce, the inventory they consume, the purchase orders that replenish it, and the issues raised along the way all live in one data model, with traceability from design release to the serial number of the unit that shipped.

Hardware manufacturing is usually split across disconnected systems: PLM for designs, ERP for inventory and finance, MES for the floor, QMS for quality. The handoffs between them are where cost, delay, and recall risk live. ION consolidates the process into one product, so an operator scanning a serial sees its procedure and open issues, an engineer sees which in-flight runs a procedure change affects, and a quality engineer traces a field failure back to the exact lot and the operator who installed it.

## The product spine

These load-bearing concepts appear throughout ION and this manual.

| Concept               | What it is                                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Part**              | The Parts Library entry: a part number, a revision, and fields. Not a physical unit.                                  |
| **Part inventory**    | A physical instance of a part: a serial, a lot, or an untracked quantity at a location.                               |
| **BOM (mBOM / aBOM)** | The mBOM is the planned parts list for a build; the aBOM is the serial-and-lot record of what was actually installed. |
| **Procedure**         | A versioned sequence of steps that builds, tests, or inspects a part.                                                 |
| **Run**               | One execution of a procedure against a specific part inventory, where floor work happens.                             |
| **Purchase order**    | A buy of parts from a supplier. Receiving turns them into part inventory.                                             |
| **Issue**             | A defect, deviation, or quality event tied to a part, inventory, or run.                                              |

Design intent flows into a part, parts roll up into a BOM, a procedure says how to build that BOM, a run executes the procedure against real inventory, and the run produces an aBOM: your auditable record of what was built.

```mermaid theme={null}
flowchart LR
  D[Design intent] --> P[Part] --> M[mBOM] --> Proc[Procedure] --> Run --> A[aBOM]
  PO[Purchase order] --> Rec[Receiving] --> Inv[Inventory] --> Run
  Run --> Iss[Issues and Further Actions]
```

## What ION isn't

ION connects to CAD, ERP, and CRM systems but doesn't replace them. It ingests design releases without authoring CAD geometry, owns inventory and consumption truth while the ERP keeps the financial ledger, and builds what sales has already ordered. That boundary keeps ION focused on manufacturing.

## How this manual is organized

| Section                                     | What it covers                                                                                 |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Build Hardware](/build-hardware)           | Parts, BOMs, procedures, runs, locations, tools, and labels.                                   |
| [Manage Supply Chain](/manage-supply-chain) | Purchasing, receiving, inventory, and kitting.                                                 |
| [Track Quality](/track-quality)             | Issues, containment, Further Actions, and quality reporting.                                   |
| [Automate with ION](/automate-with-ion)     | ION Actions, ION Intelligence, integrations, notifications, analytics, and the Data Connector. |
| [Administration](/administration)           | Users and permissions, authentication, settings, and importers.                                |
| [API Reference](/api-reference)             | The GraphQL API, guides, and examples.                                                         |

## Start with your role

<CardGroup>
  <Card title="CXOs" href="/getting-started/role-guides/cxos">
    Analytics, the data spine, and the questions ION answers about your operation.
  </Card>

  <Card title="Design engineering" href="/getting-started/role-guides/design-engineering">
    Releasing parts and BOMs, authoring procedures, and keeping design intent connected to the build.
  </Card>

  <Card title="Manufacturing engineering" href="/getting-started/role-guides/manufacturing-engineering">
    Process design, scheduling, NPI, resource planning, and acting on floor signal.
  </Card>

  <Card title="Production technicians and operators" href="/getting-started/role-guides/production-technicians-and-operators">
    Run execution, scanning, capturing data, and raising issues.
  </Card>

  <Card title="Purchasing and supply chain" href="/getting-started/role-guides/purchasing-and-supply-chain-specialists">
    Purchase orders, receiving, inventory, supplier data, and feeding consumption into MRP.
  </Card>

  <Card title="Quality engineering" href="/getting-started/role-guides/quality-engineering">
    Issues, dispositions, Further Actions, and upstream improvement.
  </Card>
</CardGroup>

## Practice and get help

See [ION basics](/getting-started/ion-basics) for the tools you use everywhere: Search, chat support and tickets, the sandbox for practicing without affecting production, and supported browsers and devices.


# Cycle counting
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/cycle-counting

A standard operating procedure for cycle counting part inventory so your digital counts match the floor.

Cycle counting is how you get on the floor, count, and adjust inventory so your physical and digital counts match. This page is a recommended best-practice procedure, not a required ION workflow: it describes an approach to cycle counting and how to use ION to pull the data you need and reconcile it quickly.

## Types of cycle counting

There are two main approaches. Both aim to keep inventory records accurate; they differ in what they target.

* **Location-based cycle counting** audits specific storage locations at regular intervals, verifying the accuracy of whatever inventory sits there, regardless of part.
* **Part-based cycle counting** targets specific parts across all locations, chosen by criteria such as value, movement frequency, or historical accuracy.

## Location-based cycle counting

A successful location-based cycle count needs four things:

1. A cycle counting schedule.
2. Trained cycle count staff.
3. Cycle count sheets.
4. The location closed off from inventory changes during the count.

### Create a cycle count schedule

A regular schedule brings consistency to inventory management and lets you target high-value items and frequently accessed locations more often. Base the cadence on two attributes: the consumption rate of the inventory and the value of the parts in each location.

The example schedule below includes a column that calculates each location's next cycle count date from its cadence and most recent count. A schedule also spreads the workload across the year instead of forcing a year-end scramble, and it documents your inventory-accuracy practice.

[Download the example schedule](/images/manage-supply-chain/cycle-count-schedule.csv)

### Train your staff

Everyone who counts needs clear training on both the concepts behind cycle counting and how to do it in ION. Use hands-on exercises and real examples so staff can handle common issues, and refresh the training periodically to keep skills current.

### Generate your cycle count sheets

To count accurately, you need the part inventory data for the location you're working on. Use the ION API to generate a pick sheet. If you're new to the API, see the [API reference](/api-reference) and generate [API keys](/api-reference/authentication/api-keys) if needed.

Use the [Python examples on GitHub](https://github.com/FirstResonance/ion-examples) to input a cycle count location and generate a CSV of all inventory in that location, excluding installed items. The file includes columns for part number, revision, total quantity, and floor count. Record the quantities you observe in the floor-count column, on screen or printed. To keep the count unbiased, hide the total-quantity column while counting.

### Close off a location

Closing off a location temporarily restricts inventory movement in the area so the count stays accurate. Tell the relevant personnel about the schedule and affected areas, then secure the location to prevent adjustments during the count, with signage, locked entry points, or restricted transactions in your inventory system.

## Adjust inventory after a cycle count

Adjusting inventory is the most important step: you make the digital match the physical through manual adjustment.

1. Keep the location closed until adjustments are finalized.
2. Use the count sheet to reconcile digital and physical inventory.
3. Record major discrepancies.

| Observed discrepancy | Potential causes                                                                                                                                             | Fixes                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Digital > physical   | Parts not consumed onto aBOMs; part status incorrect (installed, on order, unavailable); parts scanned to a location accidentally; parts not moved correctly | Confirm higher-level assemblies are consumed; move MRB parts to the correct location; as a last resort, move extra parts to a cycle-count discrepancy location |
| Digital \< physical  | Parts not put into kits correctly; parts in a status that makes them unavailable; parts moved physically but not digitally                                   | Find part inventory at MRB locations and move it to the lineside location; return excess parts to inventory                                                    |


# Overview
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/index

How ION models physical material as serials, lots, and untracked quantities at locations, its statuses, and the operations that keep it accurate.

Inventory is ION's record of physical material: what sits on a shelf, in a kit cart, at a workstation, or installed in a unit. A [part](/build-hardware/parts) is the library definition; inventory is what physically exists against it. One inventory record is a single serialized unit, a lot of fungible material under a lot code, or an untracked quantity at a location. Whether a part is serial tracked, lot tracked, or untracked is set on the part, not on the inventory. See [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking).

Every floor action against material is an inventory transaction. Receive, move, split, merge, scrap, kit, install, and consume each record a timestamp, an actor, and a location, so you can always ask how many of a part you have and where. An inventory record always sits at a location, and that location's availability setting decides whether the material counts as consumable. To add, move, adjust, and review records, see [Manage inventory records](/manage-supply-chain/inventory/manage-inventory-records).

<Tip>
  Use [importers](/administration/ion-importers) for bulk bring-up and corrections, and rely on scanning for the day-to-day record.
</Tip>

## Statuses

Every inventory record carries a calculated status. ION derives it from the record's quantity, location, and links to runs, kits, installs, purchases, and holds. You never set it directly.

The statuses evaluate in the order below, and the first that applies wins. For example, a record that is both installed and kitted shows as **Installed**.

| Status      | Meaning                                                          | How it's determined                                                                                                      |
| ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Installed   | Quantity is zero, but the record was installed onto an assembly. | Quantity is zero and the record has installations on its aBOM.                                                           |
| Unavailable | Quantity is zero.                                                | Quantity is zero with no installation history.                                                                           |
| Scrapped    | The full quantity is scrapped.                                   | The scrapped quantity equals the inventory quantity.                                                                     |
| Installed   | Installed onto an assembly.                                      | The full quantity is installed onto a parent aBOM.                                                                       |
| WIP         | Linked to an active or failed run.                               | Attached to a run in a status of todo, in progress, redline, hold, or failed.                                            |
| Unavailable | On a quality hold.                                               | The record has a quality hold.                                                                                           |
| Kitted      | Actively kitted.                                                 | The full quantity is kitted to an open kit, and the record is either fully received or has no open purchase order lines. |
| Available   | Physically available to consume.                                 | Received, with inventory availability turned on at its location.                                                         |
| Unavailable | Physically present but not consumable.                           | Received, but the location has inventory availability turned off.                                                        |
| On Order    | Linked to an active purchase.                                    | Attached to a purchase line in a status of draft, requested, approved, or ordered.                                       |
| Unavailable | Every related purchase was canceled.                             | All of the record's purchase order lines are canceled.                                                                   |
| Unavailable | Not at an available location.                                    | The location has inventory availability turned off.                                                                      |
| Available   | Physically available to consume.                                 | None of the above applies.                                                                                               |

## Merge and split

Merging consolidates identical records from different receipts and purchase orders into one, so a part you stock in a single bin shows as one barcode, one location, and one quantity. Only untracked or lot-tracked records that match on part, lot, location, status, unit of measure, and intent are eligible, and a record in use elsewhere never merges. Merging is an org setting. See [Merge inventory](/manage-supply-chain/inventory/merge-inventory).

Splitting is the inverse. It decreases the original record's quantity and creates a new record for the difference, linked back to the original so traceability holds. ION also splits automatically whenever you act on part of a quantity, such as kitting one unit of a quantity-two record, so the affected quantity carries its own status and location. See [Split inventory](/manage-supply-chain/inventory/split-inventory).

## Scrap

Scrapping makes inventory unavailable for use. Scrap the full quantity and the record's status becomes **Scrapped**; scrap part of it and ION splits the record so the scrapped quantity becomes its own line while the remainder keeps its status. Lot traceability stays linked to the scrapped line. Scrap directly on the inventory page, or scrap as the resolution of a quality issue. See [Scrap inventory](/manage-supply-chain/inventory/scrap-inventory) and [Scrap inventory from an issue](/track-quality/issues/scrap-inventory).

## Automatic movement

ION moves inventory to the right location as work happens, so locations stay accurate without manual updates. [Kitting](/manage-supply-chain/kitting/create-and-fulfill-kits) moves the kitted inventory to the kit's location, while [installing parts and starting a run step](/build-hardware/runs-and-execution/step-execution) move parts to the assembly and move the WIP assembly and everything installed on it to the step's location.

## Line-side consumption

Line-side inventory is stock you keep at or next to a work center so an operator grabs it without a trip to the stockroom, such as fasteners, adhesives, and lubricants. You model the line-side bin as a real location, stock it with real inventory, and deploy the Auto-consumption ION automation so running a step at that work center deducts the consumed parts and records the installs automatically. Line-side does not replace kitting for parts traced through the aBOM. See [Line-side inventory](/manage-supply-chain/inventory/line-side-inventory).


# Line-side inventory
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/line-side-inventory

Stock high-velocity consumables at the work center and let runs consume them automatically.

You model the line-side bin as a real location, stock it with real inventory, and deploy the [Auto-consumption of line-side inventory](/automate-with-ion/integrations/automations) ION automation so running a step at that work center deducts the consumed parts automatically. A work cell typically runs both: a kit cart with the discrete kitted parts for the next run, and line-side bins of the consumables that flow into every run the station executes.

## When to use line-side vs kitting

| Part profile                                                      | Use                                                                      |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Serial tracked, lot tracked, or otherwise traced through the aBOM | Kit it.                                                                  |
| High-cost, scarce, or program-controlled                          | Kit it.                                                                  |
| Cheap, high-velocity, interchangeable, untracked                  | Line-side.                                                               |
| Cheap and high-velocity but needs lot-level recall                | Line-side, lot tracked. Auto-consumption still records the lot consumed. |

## The location hierarchy

Auto-consumption keys off the location hierarchy around the work center:

* **Workstation**: the location attached to the run step.
* **Child**: a tote or rack whose parent is the workstation, pulled from directly.
* **Parent**: a work area or cell that contains one or more workstations.
* **Sibling**: a line-side rack that shares the same parent as the workstation. Multiple workstations under one parent can pull from the same sibling rack, the most common pattern for shared consumables.

For how to model the hierarchy, see [Locations and work centers](/build-hardware/locations-and-work-centers).

<Warning>
  Assign the line-side rack to the correct parent location. A rack under the
  wrong parent is never consumed from.
</Warning>

## How automatic consumption works

Automatic consumption is set up through the [Auto-consumption of line-side inventory](/automate-with-ion/integrations/automations) ION automation, deployed from the ION Marketplace like any other prebuilt automation. You configure which run step triggers it and which locations it pulls from. When it runs, it reads the run's mBOM, finds available line-side inventory in the configured locations, deducts the required quantity, and records the installs onto the run's aBOM. Configure it to match how your line operates, and confirm its behavior in your environment before you rely on it.

## Replenishment

Refill line-side inventory before it runs out, using one of these patterns:

* **Reorder points**: set a reorder min and max on the part. When on-hand drops below the min, the part surfaces in Autoplan as demand.
* **Supplier-managed**: build a flow in the [Workflow Builder](/automate-with-ion/workflow-builder), or subscribe to ION [webhooks](/api-reference/guides/webhooks) from your own service, that watches a location's inventory level and triggers an outbound action such as a message to the supplier or a draft PO line. Reaching an external system is the Workflow Builder's job; an [ION Action](/automate-with-ion/ion-actions) only allows, blocks, or warns on a change to ION data.
* **Manual refill**: move quantity from the master stock location to the line-side bin with the standard inventory-move action, ideally on a fixed cadence.

## Truly untracked items

For materials you don't track at all, such as masking tape or shop towels, you have two options:

* Create the part as untracked, stock the line-side bin with a high quantity, and let auto-consumption deduct against it. When the physical bin runs out, reset the quantity with an inventory adjustment rather than a receipt.
* Leave the part off the mBOM entirely, and treat it as shop overhead rather than a part.

<Tip>
  Model the item as a part when it appears on a drawing or contributes to
  traceability. Otherwise leave it off. When you stock a high arbitrary
  quantity, the on-hand number drifts from physical reality over time, so
  reconcile it periodically.
</Tip>

## Related

* [Auto-consumption of line-side inventory](/automate-with-ion/integrations/automations)
* [Locations and work centers](/build-hardware/locations-and-work-centers)
* [Run a step](/build-hardware/runs-and-execution/step-execution)
* [Kanban kitting](/manage-supply-chain/kitting/kanban-kitting)
* [Serial and lot tracking](/build-hardware/parts/serial-lot-tracking)


# Manage inventory records
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/manage-inventory-records

Add, move, adjust, and review inventory records on the Inventory page, and act on several at once.

Day-to-day inventory work happens on the **Inventory** page. Adding a record, moving it, adjusting its quantity, and reviewing its history each run from there. For consolidating, dividing, and scrapping stock, see [Merge inventory](/manage-supply-chain/inventory/merge-inventory), [Split inventory](/manage-supply-chain/inventory/split-inventory), and [Scrap inventory](/manage-supply-chain/inventory/scrap-inventory).

Most single-record actions open from the same place: on the **Inventory** page, click a record to open the **Part Inventory Actions** dialog, then pick a tab: **Split**, **Move**, **Change**, **Adjust**, **Print**, **Merge**, or **History**. **Split** is hidden for a serial-tracked record, **Change** appears only on a part record and not on a tool, and **Merge** appears only when your organization has inventory merge turned on.

<Frame>
  <img alt="Part Inventory Actions dialog open on an inventory record, with Split, Move, Adjust, Print, Merge, and History tabs" />
</Frame>

## Add inventory

Add stock that didn't come through receiving, such as an opening balance or a manual correction.

1. On the **Inventory** page, click **Add Inventory**.
2. In **Create New Inventory Item**, set the **Part Number** and **Quantity**.
3. Set the **Location**. For a lot-tracked part, enter a **Lot Number**; for a serial-tracked part, enter a **Serial Number**.
4. If your org uses intent options, set the intent. Depending on your settings, intent can be required.
5. Click **Create Item**.

## Move inventory

1. On the **Inventory** page, open a record and select **Move**.
2. Search for and select the destination location.
3. Confirm the move. The record's location updates, and the move is recorded in its history.

## Change a record's part

Repoint a record at a different part when the stock on the shelf was recorded against the wrong one.

1. On the **Inventory** page, open a record and select **Change**.
2. In **Changing to this part**, select the new part.
3. Confirm the change.

The unit of measure follows the new part. The quantity, location, lot, and serial stay as they are,
and the record's current part is left out of the picker so a change is always a real one.

The picker offers only parts that track the same way as the record, so a serial-tracked record can
only move to a serial-tracked part, a lot-tracked record to a lot-tracked part, and an untracked
record to an untracked part. The hint under the picker names the restriction in force.

<Note>
  A record's part can be changed only while it is **Available** and untouched. ION blocks the change
  and names the reason when the record is installed on a build requirement, issued to a kit, partly
  scrapped, allocated to an open run, or at any other status. Repointing consumed stock would rewrite
  what its build, kit, run, order, and scrap records mean.
</Note>

## Adjust a quantity

Use an adjustment to correct a record's on-hand count.

1. On the **Inventory** page, open a record and select **Adjust**.
2. Set the **New Total Quantity**. To scrap part of the record instead, set the **Quantity to Scrap**.
3. Record a reason, then save. For scrapping stock as a workflow, see [Scrap inventory](/manage-supply-chain/inventory/scrap-inventory).

## Delete a record

Deleting a record removes all of its units from inventory. It doesn't scrap them or record a transaction, so use it for a record created in error rather than for stock you've consumed or scrapped.

1. On the **Inventory** page, open a record and select **Adjust**.
2. Click **Delete All Inventory**, then confirm. The record is removed permanently and can't be recovered.

<Warning>
  Deleting a record permanently removes it and every unit on it. This can't be undone.
</Warning>

The **Delete All Inventory** control appears only if your permissions allow deleting inventory.

## Filter the Inventory page

Open **Filters** in the **Inventory** page toolbar to narrow the list. It's the same filter builder the rest of ION's tables use; for how to build and save a condition set, see [Build a filter](/build-hardware/parts/inventory-search#build-a-filter).

Alongside the inventory's own fields, the field picker offers **Issues**, so you can narrow to the inventory an issue touches. Searching for `issues` in the picker surfaces the whole issue filter surface as paths, such as **Issues > ID**, **Issues > Title**, and **Issues > Issue disposition type > Title**. To list only inventory that has an issue, filter on **Issues > ID** with **Is null** set to **False**.

The same field set appears on the Tools inventory table, which shares the inventory filter definition.

## View transaction history

To see every transaction against a record, open it on the **Inventory** page and select **History**. The history lists each action, such as received, moved, split, merged, installed, and uninstalled, with its actor, timestamp, and location.

## Act on several records at once

Selecting records on the **Inventory** page reveals a toolbar of bulk actions:

* **Move** sends the selected records to one location.
* **Print Barcodes** prints labels for the selected records. See [Print labels](/build-hardware/labels-and-scanning/printing).
* **Generate SNs** generates serial numbers for the selected records.


# Merge inventory
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/merge-inventory

Consolidate identical inventory records from multiple receipts and purchase orders into a single record.

Merging is an org setting. To turn it on or off, see [Configure inventory merge behavior](/administration/supply-chain-settings/configure-inventory-merge-behavior).

## When merging happens

After you edit an inventory record on the **Inventory** page, ION checks for matching records. When it finds any, a **Merge candidates detected** prompt appears and the matching records merge after a short delay. To stop the merge, select **Cancel** on the prompt before it completes.

Several operations leave a record eligible for merge, so editing it afterward can trigger the prompt:

* Partially kitting a record, which leaves the remaining un-kitted quantity eligible.
* Unkitting a record.
* Partially installing or uninstalling inventory.
* Removing inventory from an issue.

Every path that moves a record runs the same check: editing a row's **Location** on the **Inventory** page, the **Move** tab of the **Actions** dialog, and scanning a record and then a destination location. Scanning several records into one location covers all of them under a single prompt.

The prompt belongs to the app rather than to the page that raised it, so closing the dialog you moved from doesn't cancel the merge it promised. Only **Cancel** on the prompt does. Starting another move replaces the pending merge with the new one.

Scanning a record without moving it doesn't trigger a merge. Merging can also run through the ION API, so some orgs reconcile inventory in bulk on a schedule, such as an hourly integration.

## Merge criteria

Two inventory records can merge only when they share all of the following:

* The same part, which must be a part (not a tool) that is untracked or lot tracked. Serial-tracked parts, and any record with an assigned serial number, never merge.
* The same lot number, or no lot number on either record. This applies whether or not the part is lot tracked.
* The same location, which must be set and must not have [**Exclude from Inventory Merge**](/build-hardware/locations-and-work-centers/manage-locations) turned on.
* The same status, which must be Available or Unavailable.
* The same unit of measure.
* The same intent, if your org uses [intent options](/administration/quality-settings/manage-intent-options).

A record can't merge while it's in use elsewhere: installed onto another assembly, holding parts installed on its own aBOM, or tied to a related run or origin run, a related issue, a related kit, a plan reservation, a canceled purchase order line, or a kitted or installed quantity above zero. A record also can't merge if it's used to fix an issue on another inventory, or if the part is built on the assembly line (its released mBOM contains made-on-assembly items).

Merging won't occur when the same part appears on different purchase order lines within the same receipt.

## What happens on merge

* ION creates a new inventory record and deletes the merged records. Merging can't be undone.
* Custom attribute values that match across all merged records carry to the new record; comments, file attachments, and labels are combined onto it.
* The new record links every purchase order line from the merged records and preserves each line's and receipt's received quantities, so traceability to purchase orders and receipts holds. It has no transaction history from before the merge.
* The new record inherits the earliest creation date among the merged records, so FIFO kit picking still selects the oldest stock first.
* Old barcodes for the merged records point to the new record. You have the option to print a new barcode label, which reflects the new quantity.

When merged records came from purchase orders with different suppliers, the new record's supplier is cleared, because no single supplier applies. The contributing suppliers stay discoverable through the related purchase order lines.

## Related

* [Configure inventory merge behavior](/administration/supply-chain-settings/configure-inventory-merge-behavior)
* [Split inventory](/manage-supply-chain/inventory/split-inventory)


# Scrap inventory
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/scrap-inventory

Scrap inventory directly to make it unavailable for use, including partial quantities.

This page covers scrapping inventory directly. To scrap inventory as the resolution of a quality issue, see [Scrap inventory from an issue](/track-quality/issues/scrap-inventory).

## Scrap from the inventory page

1. On the **Inventory** page, show the **Scrap Quantity** column if it's hidden (it's hidden by default): open the column toggles and turn on **Scrap Quantity**.
2. Edit the **Scrap Quantity** column for the record.

* Marking the entire quantity as scrapped changes the line's status to **Scrapped**.
* Marking part of the quantity as scrapped splits the record, creating a new line for the scrapped quantity.

## Scrap with the Adjust action

1. On the **Inventory** page, open the row's **Actions** menu and select **Adjust**.
2. Enter the amount in the **Quantity to Scrap** field.
3. Submit.

## Scrap on uninstall

When you know inventory will be scrapped as you remove it, scrap it directly in the uninstall dialog:

1. Select the quantity to uninstall.
2. Check **Scrap item**.
3. Submit.

## Related

* [Scrap inventory from an issue](/track-quality/issues/scrap-inventory)
* [Split inventory](/manage-supply-chain/inventory/split-inventory)
* [Inventory statuses](/manage-supply-chain/inventory#statuses)


# Split inventory
Source: https://docs.firstresonance.io/manage-supply-chain/inventory/split-inventory

Break a lot or quantity into smaller inventory records, manually or automatically.

The new record copies nearly all of the original's fields and keeps a link back to the original, so traceability holds.

## Split manually

1. On the **Inventory** or **Receipts** page, select **Split** to open the split dialog.
2. Choose a **Distribution** method:
   * **Even**: divide the quantity equally across the lines you add. For example, split a quantity of 10 into 10 lines of 1.
   * **Custom**: enter the quantity for each line yourself. For example, split a quantity of 10 into a 3 and a 7.
3. Add a line for each record you want.
4. Set each line's quantity and location, then select **Split Inventory**.

You can't split a record down to 0 quantity, so every resulting line keeps at least some quantity.

## Automatic splitting

ION splits inventory automatically when you partially act on a quantity, so each part keeps the correct location and status. For example, kitting one unit of a quantity-2 record splits it, so the kitted unit shows a Kitted status and can move independently.

Automatic splits create a new record for the affected quantity in each of these cases:

| Action                      | New record holds                     |
| --------------------------- | ------------------------------------ |
| Partial kit / unkit         | The kitted / unkitted quantity       |
| Partial install / uninstall | The installed / uninstalled quantity |
| Partial scrap / unscrap     | The scrapped / un-scrapped quantity  |
| Partial receive             | The received quantity                |
| Direct split                | The quantity you split off           |

## How a run or issue follows a split

A run or issue can relate to only one inventory record. When you split a record tied to a run or issue, the new record stays linked to that run or issue through its link back to the original record, so it still appears on the run and any related issues, including in the aBOM trace view.

For splitting a record that has inventory installed on its aBOM, see [Split inventory on a run](/build-hardware/runs-and-execution/split-inventory-on-a-run).

## Related

* [Merge inventory](/manage-supply-chain/inventory/merge-inventory)
* [Scrap inventory](/manage-supply-chain/inventory/scrap-inventory)


# Create and fulfill kits
Source: https://docs.firstresonance.io/manage-supply-chain/kitting/create-and-fulfill-kits

Request parts into a kit, then fulfill it with specific inventory.

## Create a kit

1. In ION, go to the **Kits** page.
2. Click **Create Kit**. ION creates the kit in **Draft** and opens it on the **Kitting** page.
3. In **Request info**, set the **Destination**, where the parts go once the kit is delivered. A destination is required before picking can start. Setting it doesn't move any parts; the kit's location updates to the destination when the kit is delivered.
4. Optional: set the **Current location**, where the kit's parts physically are. Setting it moves the parts to that location.
5. Add the parts you need with **Add Part to Kit**. Its menu also offers **Add Multiple Parts to Kit**, **Add All from mBOM**, and **Import Parts from CSV**. Set each line's quantity inline.
6. Click **Submit Request** to hand the kit to the inventory team. A kit needs at least one part before it can be requested.

Parts can be added, edited, or removed only while the kit is in **Draft**. To remove parts, select their lines and click **Remove from Kit**.

After the kit leaves **Draft**, its parts and quantities lock. Its kit-level custom attributes don't: they stay visible and editable in every status, in **Request info**, and an attribute nobody has filled in renders as an empty field rather than disappearing. A rich-text attribute gets its own full-width **Additional Information** card lower down the pane, editable in every status too. You can also still change the **Destination** and **Current location** in **Request info** at any status.

Kit-level attributes are defined for the whole organization under **Settings > Supply Chain > Part Kits**. For more information, see [Custom attributes](/administration/custom-attributes).

An mBOM line marked **Exclude from Kit** is left out when a kit is built from an mBOM or from a run's aBOM. For more information, see [Manufacturing BOM](/build-hardware/bills-of-materials/manufacturing-bom).

<Note>
  When there isn't enough inventory to fulfill the kit, ION shows a shortage
  alert. While the kit is in Draft, you can select the short lines and click
  **Split Kit** to move them into a new Draft kit, so the rest of the kit can
  proceed.
</Note>

## Fulfill a kit

The **Kitting** page pairs the kit request queue with the selected kit's details. Reach it with **Kitting** on the **Kits** page, or open one kit directly by clicking its kit number. Filter the queue with **Open**, **My kits**, or **All**.

<Frame>
  <img alt="Kitting page showing the kit request queue on the left and a selected In Progress kit with Request info, Pick from location, the Lines and Pick list toggle, and kit line items" />
</Frame>

1. Click **Start Picking**. The kit must have a **Destination** first; if it's missing, clicking the button takes you to the field.
2. Optional: set **Pick from location** to limit manual picks and **Auto-FIFO** to one location and its sub-locations. Lines you can fulfill there float to the top; check **Only available here** to hide the rest.
3. For each line, click **Kit**. Set the quantity, pick the lots or serials to use in **Pick from inventory**, and click **Add to pending**. Each candidate shows its part number, revision, status, description, and purchase order, which matters when a line lists substitute parts. Choose a **Pick strategy**:

   * **FIFO** (*Oldest first by receipt date*) preselects candidate inventory to cover the quantity, drawing on the same pick list **Auto-FIFO** uses so the two controls select the same physical units. Preselected rows carry a **Pre-selected** chip and float to the top of the list, and they stay put as you check and uncheck rows. When no inventory is pickable, nothing is preselected.
   * **Manual** (*You choose row-by-row*) preselects nothing and leaves the list in its default order.

   Switching between the two clears the selection. Toggling a single row changes only that row.
4. Pending picks collect in a bar at the bottom of the pane. Click **Finalize pick · create pick session** to commit them, or **Discard** to drop them.
5. To fill every open line with the oldest inventory first instead, click **Auto-FIFO** in the lines toolbar, which kits immediately with no pending step. See [Auto-FIFO coverage](#auto-fifo-coverage).
6. When every line is fully kitted, click **Deliver**. The button reads **Complete** for a kit that isn't tied to a run, and stays disabled until the kit is 100% kitted.

Once picking has started, a **Lines** / **Pick list** toggle sits above the lines. **Pick list** groups the kitted rows into stops by their location, so a picker can walk the warehouse in order, check rows off, and deliver from the same view. It shows whatever is picked so far, so you can switch to it at any point during picking.

Stops read in natural order, so `Aisle 2` comes before `Aisle 10` rather than after it, and rows with no location come last. The same order applies to the printed sheet and the CSV export.

Its toolbar carries three controls:

* **Select all** ticks every row currently in view.
* The search box filters rows by part number, revision, lot or serial, inventory label, and location. A stop left with no matching rows drops out, and a search that matches nothing keeps the toolbar so you can clear it.
* **Print list** opens a paper walk sheet in a new window, grouped by stop with an empty checkbox per row. It prints the rows you have checked, or every row currently in view when nothing is checked.

<Note>
  The row checkboxes are the kit's pick-tracking state, so **Select all** marks every visible row
  picked. On a fully kitted kit that surfaces the ready-to-deliver banner.
</Note>

The lines toolbar carries the rest of the controls for working a long kit:

* **Sort** defaults to **% complete (low first)**, so unkitted lines rise to the top. **Line #**, **Part # (A → Z)**, and **Shortage (high first)** are the other options.
* **Show** filters the list to **All** or **Open** lines.
* **Expand all** / **Collapse all** opens every line's kitted inventory. It appears only once the kit is fully kitted, where it's a review affordance rather than a picking control.

Both views export to CSV. On **Lines**, click **Export** to download the kit list with each line's required, kitted, and short quantities. If you select lines first, only those export; otherwise all listed lines do, in the current sort order. On **Pick list**, click **Export** to download the walk sheet, ordered by location then part number.

### Auto-FIFO coverage

**Auto-FIFO** tells you how far it can get before you commit it. When available inventory covers every open line, the button reads **Auto-FIFO** and one click kits the whole kit.

When some lines fall short, the button carries a count of the lines it can fully kit, such as **Auto-FIFO (4/8)**, and clicking it opens a confirmation instead of kitting straight away. The confirmation lists each short line with its part number, how much of the line's outstanding quantity will be kitted, and why it falls short: **No available inventory** when the line has none, or **Only N of M available** when there's some but not enough. Setting **Pick from location** narrows what Auto-FIFO can draw on, and the reason says so. Click the confirm button to kit the lines it can and leave the rest short, or **Cancel** to change something first.

Once the run finishes, a toast reports the result by line: how many were fully kitted, and how many still need inventory.

<Note>
  **Auto-FIFO** appears only while the kit is **In Progress**. It's unavailable
  when there's no inventory left for it to pick, and the tooltip says whether that
  applies everywhere or only in the location you're picking from.
</Note>

### What inventory can be picked

Candidates are inventory that is **Available** or **On Order** with quantity available. Anything else is listed with a **Not pickable** badge and can't be checked.

Inventory in **WIP** is not pickable, with one exception: depending on your settings, WIP inventory linked to a purchase order line through an outside-processing run step can be kitted, both in the picker and by scanning. For more information, see [Allow kitting of WIP inventory for outside processing](/administration/supply-chain-settings/allow-wip-osp-kitting) and [Send a step to outside processing](/build-hardware/runs-and-execution/outside-processing).

## See where a line's inventory is

Each kit line carries an availability summary: the total available quantity and the first locations holding it, or **No inventory available** when there's none. Click the summary to open the inventory breakdown, which groups the stock behind the line by status: **Available** by location, **WIP · In Active Runs** by run, **On Order** by purchase order, and **Kitted** by kit. The breakdown covers the line's part and any substitutes it can draw on, and it opens in every kit status, so on-order and WIP stock stays visible after the kit leaves **Draft**.

While the kit is in **Draft**, a line also offers **View inventory**, a read-only viewer for its lots, locations, and quantities.

## Un-kit inventory

To return kitted inventory to where it came from, expand a line's kitted rows with the chevron, then remove a single row or click **Remove all**. **Replace** removes a row and reopens the picking form so you can pick different inventory. To delete whole lines, select them and click **Remove from Kit**; any inventory kitted to them is un-kitted back to its source location.

## Batch fulfill several kits

To fulfill several kits at once, select them on the **Kits** page and click **Batch Fulfill**. The table shows a row per part and a column per kit. Click a kit's fulfillment cell, pick the inventory to use, and confirm with **Apply Selection**.

## Auto-FIFO several kits

To run Auto-FIFO across a set of kits, select them with the checkboxes on their cards in the kit request queue, then click **Auto-FIFO `<n>` kits** in the bar at the foot of the queue.

The confirmation states what the run will do, then ION kits every open line across those kits from the oldest available inventory, consolidated into one walk-ordered pick list. As with the single-kit button, picks commit immediately and skip the pending cart. A results dialog reports every kit in the selection: fully kitted, short, failed, or nothing to kit.

The count on the button is the **In Progress** kits in the selection, because Auto-FIFO assigns stock to kits already being picked. If the selection holds none, the button says so. To route the rest of the selection instead, plan a [pick run](/manage-supply-chain/kitting/pick-runs).

If the pick list itself can't be built, nothing is committed and your selection is kept so you can retry.

## Bulk edit several kits

To change the same field on several kits at once, select them on the **Kits** page and click **Edit**.

1. Click **Add field** and pick the field to set: **Current location**, **Delivery location**, **Assignee**, or **Status**.
2. Set its value. Repeat for each field you want to change.
3. Click **Apply to `<n>` kits**.

The write is all-or-nothing, so ION checks the selection before you submit and names any kit that can't take a change, along with why. Completed, canceled, and delivered kits can't be moved, and a status change ION can't make on a kit is reported against that kit rather than attempted.

Two changes carry a side effect the dialog states before you apply it: setting **Current location** moves each kit's kitted inventory to that location, and setting **Status** to **Delivered** moves each kit and its kitted inventory to its delivery location. Setting an **Assignee** on a kit assigned to a team replaces that team assignment.

<Note>
  ION won't reopen a kit and move it in the same action, and won't set a delivery location in the
  same action that marks kits **Delivered**. Apply the first change, then the second.
</Note>

## Track a kit's inventory

The **Current Location** column on the **Kits** page shows where a kit's inventory sits. To move all of the kit's inventory to one location, set **Current location** in **Request info** on the **Kitting** page; the kit's parts move to that location. Delivering the kit moves the inventory to its **Destination**.

## Comment on a kit line item

Comments let you discuss a specific line with your team.

1. On the line, open its comments to display the **Comments** panel.
2. In the **Add a note for this line item...** field, type your comment. You can format the text and `@`-mention a user to notify them directly.
3. Post the comment.

To reply to a comment, use its reply control. To close a thread, resolve it; a resolved comment can be reopened later.

## Add labels to a kit

Labels are shared tags you apply across ION to group related records. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

To add a label, click **Labels** (or **Add labels** when the kit has none), then type in the **Search or create labels...** box and select it. To remove one, click the **X** on the label.

## Attach files to a kit

Attach files such as images, PDFs, and STEP/STP files, up to 100 MB each.

1. On the kit, find the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking to browse, or taking a photo on a device with a camera.

To remove a file, click its delete control and confirm.

<Note>
  When a file is attached through a file-type custom attribute, the delete dialog offers **Remove from attribute** (keeps the file but detaches it) and **Delete permanently**.
</Note>

## Related

* [Kit statuses](/manage-supply-chain/kitting#statuses)
* [Kit parts to a run](/manage-supply-chain/kitting/kit-parts-to-a-run)


# Overview
Source: https://docs.firstresonance.io/manage-supply-chain/kitting/index

How ION models a kit: the parts it requests, the inventory that fulfills it, its statuses, and its link to a run.

A kit is a request for a defined set of parts pulled from inventory and delivered together to a location. It records what should be in it, the specific lots and serials that fulfill it, where it stages and delivers, and its status. A kit does not create or consume parts. It reserves existing [inventory](/manage-supply-chain/inventory) and moves it, so a kitted unit is unavailable to other demand until the kit completes.

Most kits go to a [run](/build-hardware/runs-and-execution), where the kit reserves components against that run's build. A kit can also serve engineering testing, line-side replenishment, or any workflow that needs a known set of parts in one place.

## Requesting versus fulfilling

A kit has two sides that different people work. The requester defines what the kit needs and where it goes. The inventory team fulfills it by assigning specific lots and serials to each requested part, and can pull the oldest inventory first across the whole kit. Picking can be partial, but a kit can't be delivered until every line is fully kitted. For a single kit, see [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits). To fill several kits at once along a pick route, see [Claim kits, create a pick run, and walk the route](/manage-supply-chain/kitting/pick-runs).

A kit tracks two locations. The **Current location** is where the kit's parts physically are; setting it moves them there. The **Destination** (the kit's delivery location) is where they end up once the kit is delivered, and setting it moves nothing until then.

## Statuses

A kit moves through the statuses below to coordinate the requester and the inventory team. Each status offers one forward action (**Submit Request**, **Start Picking**, then **Deliver** or **Complete**), and each status drives what happens to the kitted inventory. A kit tied to a run passes through **Delivered** on its way to **Completed**; a kit with no run goes straight to **Completed**.

| Status          | What it's for                                                                                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Draft**       | The default for a new kit, and the only status where parts can be added, edited, or removed. The requester fills in the parts needed and sets the kit's **Destination**.                                      |
| **Requested**   | The requester has finished defining the kit. Inventory teams filter for requested kits to action, and the kit can be assigned to a team member or a team. A destination is required before picking can start. |
| **In Progress** | The kit is being fulfilled. Kitted inventory takes the [Kitted](/manage-supply-chain/inventory#statuses) status.                                                                                              |
| **Delivered**   | The kit has been delivered. Its **Current Location** updates to the **Destination**, so all inventory in it moves there automatically.                                                                        |
| **Completed**   | Returns a kit, or part of it, to the warehouse. Inventory that wasn't installed is marked available. To move that inventory to one location in a single action, set the kit's **Current location**.           |
| **Canceled**    | The kit is no longer needed.                                                                                                                                                                                  |

To move a kit backward, use its **More actions** (⋯) menu on the **Kitting** page: **Return to Draft** for a requested or in-progress kit, **Reopen as In Progress** for a delivered kit, **Reopen as Delivered** for a completed kit tied to a run, and **Reopen as Draft** for a canceled kit. **Cancel Kit** is available until the kit is completed or canceled.

## Kitting to a run

When a kit is tied to a run, the parts it reserves are subtracted from inventory and attached to that run as soon as they are kitted, so you can plan assemblies without double-counting inventory. You can auto-fill the request from the run's aBOM, and a single request creates one kit per destination. See [Kit parts to a run](/manage-supply-chain/kitting/kit-parts-to-a-run).

## Kanban kitting

A kanban kit is a reusable container that cycles between inventory and the line for high-volume repeat builds. The same kit pattern is pre-assembled into the container, sent to the line, emptied, and returned to inventory to be refilled. This fits discrete BOM-controlled parts consumed in a repeatable pattern, not high-velocity consumables. See [Kanban kitting](/manage-supply-chain/kitting/kanban-kitting).


# Kanban kitting
Source: https://docs.firstresonance.io/manage-supply-chain/kitting/kanban-kitting

Run a reusable kit container that cycles between inventory and the line for high-volume repeat builds.

## Cycle a kanban kit

1. Pre-assemble the kit into a container in inventory.
2. Send it to the production line and install the parts.
3. When the kit is empty, de-kit any parts still attached to it: on the **Kitting** page, expand each line's kitted rows and click **Remove all**, which un-kits the inventory back to its source location and keeps the line for the next cycle. To move all of the kit's inventory to one location at once, use **Stage Inventory** in the kit's **More actions** (⋯) menu.
4. Reopen the kit from the **More actions** (⋯) menu to request a refill: **Reopen as In Progress** (a completed kit tied to a run reopens as **Delivered** first). Then send the container back to the warehouse.

As the rate of installations rises, increase the inventory per kit until you reach the container's limit, then add more kits to the cycle.

<Tip>
  Keep at least two kits at the line-side location so one is always available for technicians while the other is refilled.
</Tip>

<Note>
  Kanban kitting is for discrete BOM-controlled parts consumed in a repeatable kit pattern. For high-velocity consumables that don't need kit-level handling, such as fasteners, adhesives, and lubricants, see [Line-side inventory](/manage-supply-chain/inventory/line-side-inventory) instead.
</Note>

## Related

* [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits)
* [Line-side inventory](/manage-supply-chain/inventory/line-side-inventory)


# Kit parts to a run
Source: https://docs.firstresonance.io/manage-supply-chain/kitting/kit-parts-to-a-run

Reserve parts against a specific run by requesting kits from the run, then install them on run steps straight from the kit.

In ION, open the run and click **Kits** in the run header. The dialog lists every kit tied to the run with its status, destination, and fulfillment progress, and each kit number links to the kit on the **Kitting** page.

## Request a kit from a run

1. In the run's **Kits** dialog, click **New Kit Request**.
2. Add the parts you need:
   * To pull them from the run's aBOM, pick an **Auto-fill** source, either **All unfulfilled parts** or a single run step, and click **Apply**.
   * To add one part at a time, click **Add part...** and search the aBOM. Check **Include substitutes** to also list substitute parts, marked **SUB**.
3. Check each row's **Destination**, the location the kit is delivered to. ION prefills it from the run step's location, falling back to the run inventory's location when the run step has none. Parts added outside a run step use the run inventory's location directly. A row with no prefill shows **Select destination...** and blocks **Submit Request** until you set one.
4. Click **Submit Request**.

ION creates one kit per destination. Rows that share a destination go into the same kit, and the footer states the result before you submit, such as **Creates 2 kits (2 destinations)**.

To apply one destination to many rows at once, select the rows and click **Set destination** in the toolbar. Rows for the same part that end up sharing a destination collapse into one row with their quantities summed.

<Frame>
  <img alt="New Kit Request dialog with two auto-filled parts, each assigned a destination, and a footer reading Creates 2 kits (2 destinations)" />
</Frame>

As soon as parts are kitted, they're subtracted from inventory and reserved for the run, so you can plan assemblies without double-counting. You don't have to fully kit every part.

The inventory team fulfills the kits on the **Kitting** page. See [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits).

## What Auto-fill adds

**Auto-fill** saves you from adding each line by hand. The source you pick decides what it pulls in:

* **All unfulfilled parts** adds every aBOM build requirement that isn't fully installed, filling each part's outstanding quantity (required minus what's already installed). Parts already complete are skipped.
* A single run step adds only that run step's build requirements.

**Auto-fill** then subtracts what an existing kit already holds for the run, plus anything you've already staged in the dialog, so it never re-requests a part that's covered. A part the run's kits fully cover is dropped from the fill, and a partly covered part is filled at its remaining shortfall. A badge reports how many parts were filled, so you can tell a skipped part from a missing one. **Apply** stays unavailable until the run's kit inventory finishes loading.

Each [made-on-assembly](/build-hardware/bills-of-materials/made-on-assembly) part carries an **MOA** badge, and serial- and lot-tracked parts carry **S/N** and **Lot** badges. On a run with a large aBOM, some parts might not appear in the list or auto-fill; a notice appears when that happens, so add any missing parts by hand.

## Link an existing kit to a run

You can also associate a kit with a run after the fact: open the kit on the **Kitting** page and set **For run** in the kit header. The kit then appears in the run's **Kits** dialog.

## Install kitted parts on a run step

When a run has kits, you can install their contents against a run step's part install requirements in one action.

Open the run step and find the **Part installs** section in its right rail. When the run's kits hold parts for that step, a banner reads **N parts kitted for this step**. Click **Install all from kit** on the banner. ION installs the kitted inventory against the run step's open build requirements and counts each install toward that run step. Once everything the run step requires is installed from the kit, the run step's install requirement is satisfied.

The same banner appears in **Part Installs (aBOM)**, which **View all** in the **Part installs** section opens. There it reads **N parts kitted for this run** and installs against the run's part rather than one step. Turning on **Edit Mode** hides it.

## Related

* [Create and fulfill kits](/manage-supply-chain/kitting/create-and-fulfill-kits)
* [Kit statuses](/manage-supply-chain/kitting#statuses)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)


# Claim kits, create a pick run, and walk the route
Source: https://docs.firstresonance.io/manage-supply-chain/kitting/pick-runs

Claim kits from the queue, plan a pick run, and fill several at once along an ordered route with scan-to-confirm and label printing.

A **pick run** is one walk of the floor that fills several kits at once. Instead of picking each kit
separately and revisiting the same bin each time, ION groups the demand into **stops** (one stop per
bin) and orders them into a route.

Use it when several released kits need parts from overlapping locations. For a single kit, the
[Kitting page](/manage-supply-chain/kitting/create-and-fulfill-kits) is still the shorter path.

## Claim a kit from the queue

The **Kit request queue** on `/kitting` lists the kits waiting to be filled.

1. Filter the queue with **Open**, **My kits**, or **All**.
2. Search by kit number, run, or part number with **Search kit #, run, or part #**.
3. Click **Claim** on a kit to take it. It moves into your **My kits** filter, so the rest of the team
   can see it is being handled.

Each card shows the kit number, its run, its destination (or **No destination set**), how much of it is
already kitted, and a fillability badge.

### What the fillability badge means

The badge reads **Fillable** when every line can be picked from available stock, or
**`<n>`% · Short** when it cannot. The percentage is the share of the kit's *remaining* need that free
inventory can cover.

Two things it deliberately does not tell you:

* **It is scored for that kit alone.** Kits picked together in one run share the same inventory, so a
  batch can fill less than the individual badges suggest.
* **It is advisory.** The score is recalculated when its inputs change, so another transaction can
  consume stock the score still counts. The pick list at allocation time is the authority.

<Note>
  Sorting the queue by **Priority** sorts on a custom attribute, not a built-in field, so it only
  appears once your organization defines a Priority attribute on kits. **Use recommended** returns the
  rail to its default order.
</Note>

## Create a pick run

1. Select the kits you want to pick together using their checkboxes.
2. In the action bar, click **Pick run for `<n>` kits**.

ION plans the route immediately and opens the run. Planning happens before anything is written, so a
run that would pick nothing is refused rather than created empty. If every selected kit needs stock
another live run already holds, ION tells you so instead of opening a run you cannot walk.

## Walk the run

On the **Pick run** page, each stop is one bin. Its rows are the inventory to pull there, and each row is split per kit, so you
can see how many units of that lot belong to which kit before anything leaves the shelf.

### How the route is ordered

Stops follow **`pickSequence`** on each location: a numeric walk order that matches your floor's aisle layout. When a location has no pick sequence set, it comes after every sequenced location, ordered by a natural sort of the bin name, so `Bin-2` precedes `Bin-10` rather than following it. Stock with no location sorts last.

Pick sequences are what make the route match the physical floor. Until they are set, the order is a reasonable guess from bin names, not your aisle layout.

<Note>
  There is no screen for editing pick sequences today. `pickSequence` is set through the API, on
  the location record. Ask your ION contact if you want your bins sequenced.
</Note>

### Confirm a stop

1. Tick each row as you pull it. The **Confirm pick** button's tooltip reads *Tick every row to confirm this stop*.
2. Adjust a split's quantity inline if you pulled less than planned. The kits keep the shortfall as
   remaining need.
3. Click **Confirm pick** to issue that bin's stock into the kits and move to the next stop.

### Scan to confirm

Scanning a part's inventory label ticks its row without a tap. Both a wedge (HID) barcode gun and the
phone camera work.

If you scan stock that is not on the open stop, ION opens a mismatch prompt rather than accepting it
silently: it shows what you scanned alongside the stop's rows, and you choose which row it should
count against. The divergence is recorded, so the difference between what was planned and what the
floor actually did is reportable later.

### Skip a stop

Click **Skip stop** when a bin cannot be picked. ION asks for a reason:

| Reason                       | Use when                                              |
| ---------------------------- | ----------------------------------------------------- |
| Not enough stock at this bin | The bin holds less than the plan expected             |
| Stock damaged or unusable    | The units are there but cannot be used                |
| Picked from a different bin  | You filled the need somewhere else                    |
| Other                        | Anything else. ION asks you to describe what happened |

Nothing is issued from a skipped bin. The kits keep their remaining need, and the reason is recorded
so the plan can be improved.

## Print labels

When a stop splits one lot across several kits, each split needs a label at the moment of the split.
Do not leave labels for a printer station to apply later.

* Confirming a stop offers to print labels for what that stop just issued.
* **Print all labels** on a completed run prints labels for everything the whole run kitted.

If a completed run kitted nothing, the button reports **No labels to print** rather than opening an
empty print dialog.

## When a run expires

A pick run expires after **24 hours** without picks. Your organization can set a different window to
match its shift pattern. The clock is re-armed by activity, so the rule is *no picks for 24 hours*,
not *24 hours old*.

An expired run becomes read-only and shows:

> This run expired and is read-only. Its stock claims were released, so re-plan it before picking.

Its claims on inventory are released when it expires, so the stock is free for other kitters
immediately rather than being held by an abandoned walk.


# Overview
Source: https://docs.firstresonance.io/manage-supply-chain/planning/index

How Autoplan turns a demand into a supply plan: netting against inventory and open orders, proposed purchase orders and runs, and the plan lifecycle.

Autoplan is ION's supply-planning workspace. You give it a demand, a quantity of a top-level part needed by a due date, and it explodes the part's released bill of materials, nets every component against on-hand inventory and open orders, and proposes the supply actions that close the gaps: draft purchase orders for buy parts and draft runs for make parts. You find it under **Supply Chain > Autoplan**.

Autoplan never changes your factory on its own. Everything it proposes is a draft inside the plan until you review it and commit it, at which point ION creates real draft purchase orders and runs. See [Create and apply a plan](/manage-supply-chain/planning/create-and-apply-a-plan).

## Demand and supply

A plan starts from a single demand: the top-level part, the quantity, and the due date. Autoplan derives everything else from that demand and the part's released BOM, rolling the required quantity down through every level of the assembly.

Supply is what already covers that demand: available inventory, on-order purchase orders, and runs linked to the plan. Your organization's demand settings control how demand is calculated and what counts as supply, for example whether uncommitted purchase orders count. See [Configure demand settings](/administration/supply-chain-settings/configure-demand-settings).

## How Autoplan proposes supply

For each component in the plan, Autoplan compares the requirement against supply and assigns an action:

| Action           | Meaning                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Use existing** | On-hand inventory already covers the requirement. Nothing to buy or build.              |
| **Purchase**     | The part is a buy part with a shortfall. Autoplan proposes a draft purchase order line. |
| **Manufacture**  | The part is a make part with a shortfall. Autoplan proposes a draft run.                |

Each line also carries a coverage verdict that tells you how urgent it is:

| Coverage    | Meaning                                                         |
| ----------- | --------------------------------------------------------------- |
| **Covered** | On-hand plus on-order supply meets the requirement.             |
| **At risk** | Covered, but with no schedule slack.                            |
| **Short**   | There is a real shortfall, and it can still be ordered in time. |
| **Overdue** | There is a shortfall and the order-by date has already passed.  |

Autoplan schedules each line backward from the due date using lead times, producing an order-by date, slack, and a critical-path flag. In the plan's **Build tree** view, each assembly also shows a **Clear to build** read: **Clear** when every child component is covered, **Blocked** when at least one is not. That is your signal for whether an assembly can start today.

## Plan lifecycle

A plan moves through a small set of states, shown as a status pill on the plan:

1. **Ready**: the plan is staged. Autoplan has resolved the BOM, and you review the demand, planning assumptions, and [part policies](/manage-supply-chain/planning/part-policies) before running it.
2. **Running**: the engine is computing the plan.
3. **In progress**: results are ready. You work the plan, staging proposals into a draft package and committing them to ION.
4. **Failed**: the plan could not be generated. The reason is shown, and you can retry.
5. **Archived**: the plan is closed and read-only. Archiving lets you release the plan's unconsumed inventory allocations back to available supply, or keep them reserved.

Two actions move a plan forward inside that lifecycle:

* **Refresh** re-pulls live supply from ION and recomputes the same plan in place. The plan header shows a "Supply as of" timestamp so you know how current the picture is. Refresh after anything changes in your supply chain or on the floor.
* Committing the staged package creates the proposed purchase orders and runs in ION. Purchase orders are created in draft status, so nothing is issued to a supplier until you take the normal [purchasing](/manage-supply-chain/purchasing) steps.

## Planning assumptions and part policies

Every plan carries a set of planning and purchasing assumptions: spare quantity, minimum stock, attrition rate, minimum batch quantity, buffer lead days, and more. Plan-wide defaults are set when you create the plan, and each part can override them individually. These policies change the quantities and dates Autoplan proposes, and the plan shows you the exact effect of each value. See [Edit part policies in a plan](/manage-supply-chain/planning/part-policies).


# Approve purchase orders
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/approve-purchase-orders

Run the approval workflow on a purchase order and review approvals in ION.

Configure approval levels in Settings before submitting a PO for review. See [Configure PO approval workflow](/administration/supply-chain-settings/configure-purchase-order-approval).

## Submit a PO for review

1. Open the PO.
2. Optional: click **Open Review Panel**, then use **Manage Reviews** to assign the reviewers for each level.
3. Click **Submit for Review**.

When your org has no approval policy configured, a submitted PO shows an **Approve** button so you can approve it directly without a review chain.

## Review a PO

1. Open the PO then click **Open Review Panel**.
2. Optional: To leave a note, add a comment first; the button then reads **Approve with comment** or **Reject with comment**.
3. In the review panel, click **Approve** or **Reject** for your level.

Levels are enforced in order: each level opens for approval only after the levels before it are approved.

## Approval Stack

<Note>
  The Approval Stack is in beta. The workflow may change or be removed.
</Note>

To work through pending approvals one PO at a time, go to the **Purchases** page and click **Approval Stack**.

The page counts what's **Awaiting approval**, how many **You can approve**, and the queue's **Total committed value**. Each card shows one PO: its supplier, line items, total cost, and its approval chain with your level marked.

1. Review the card. When it's your turn, click **Approve** or **Reject**. To leave a note, write a comment first; the button then reads **Approve with comment** or **Reject with comment**. Type `@` in a comment to mention a teammate.
2. Click **Skip** to move on without deciding, or **Back** to return to the previous PO.
3. When a PO is waiting on another level, the card is view only, but you can still comment.

Whether you can approve a card depends on your roles, teams, and direct assignment on the applicable level.

You can also work the queue from the keyboard: **A** approves, **R** rejects, **S** skips, and the left arrow goes back.

## Re-approval after changes

If a PO is changed by an amount that meets your org's [reset threshold](/administration/supply-chain-settings/configure-purchase-order-approval) during or after approval, ION requires reapprovals.
Editing the org's approval policy does not affect existing reviews. You can use **Reset Reviews** on the PO to clear the current approvals.

## Related

* [Configure PO approval workflow](/administration/supply-chain-settings/configure-purchase-order-approval)
* [PO statuses](/manage-supply-chain/purchasing#statuses)


# Create a purchase order
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/create-a-purchase-order

Place an order with a supplier in ION, add lines and parts, and reuse common orders with templates.

## Create a purchase order

1. In ION, go to the **Purchases** page.
2. Click **Create Purchase Order**. ION creates the purchase order and opens its detail page.
3. Set the supplier on the purchase order using the **Supplier** field.
4. In the **Purchase Order Lines** card, click **Add Line**. For each line, set the part, quantity, cost, and any other details for the purchase.
5. Optional: attach a quality clause to a line so the supplier delivers against it. See [Attach a quality clause to a line](#attach-a-quality-clause-to-a-line).

To buy a good or service you don't track in inventory, leave the **Part** field empty on the line, or pick a part whose purchase type doesn't create inventory. See [Purchase types](/manage-supply-chain/purchasing#purchase-types).

You can print the PO at any status, including Draft. Use **Print** in the **More options** menu. See [Manage a purchase order](#manage-a-purchase-order).

## Edit purchase order lines

You edit lines directly in the **Purchase Order Lines** card. Line editing is available while the PO is in Draft. Once the PO moves past Draft, the lines card is read-only, so [return the PO to Draft](#manage-a-purchase-order) to change a line.

To edit a cell, click it and enter the value. These cells edit inline: **Part**, **Description**, **Supplier Part #**, **Labels**, **Qty**, **Unit Cost**, **Fee Exempt**, **Quality Clauses**, **Need Date**, and **ETA**. **Total Cost**, **Qty Received**, and **Receipts** are calculated and not editable.

The **Supplier Part #** cell lists the part's supplier parts with the supplier's name and cost under each supplier part number, so you can tell dual-sourced options apart. Picking one doesn't change the line's **Unit Cost**. For how a supplier part's cost is set, see [Manage suppliers](/manage-supply-chain/purchasing/manage-suppliers).

The **Status** cell shows each line's status. While the PO is in Draft, the cell opens a menu to **Cancel** a line or return a canceled line to **Draft**. You can't set a line to any other status.

<Note>
  The line-level **Paid** and PO-level **Paid** toggles stay editable even after the PO leaves Draft. See [Mark a purchase order paid](#mark-a-purchase-order-paid).
</Note>

### Act on selected lines

Select one or more line checkboxes to open a toolbar with bulk actions:

* **Copy** duplicates each selected line on the same PO. Available only while the PO is in Draft.
* **Change Attributes** opens a command bar to set a field or custom attribute across all selected lines at once.
* **Add OSP Run** links the line to an outside-process run step. Available when you select one line whose quantity is zero.
* **Cancel Line** cancels the selected lines. Available only when every selected line is in Draft.
* **Delete** permanently removes the selected lines. Available only while the PO is in Draft.

### Delete a line

To remove a single line, select its checkbox and click **Delete** in the toolbar. Deleting is permanent and available only while the PO is in Draft.

## Attach a quality clause to a line

A quality clause is a requirement the supplier must deliver against. You attach clauses per line in the **Quality Clauses** cell.

1. In the **Purchase Order Lines** card, click the **Quality Clauses** cell on the line.
2. Search for a clause by its reference name or title, then select it to attach it. Repeat to attach more than one.
3. To remove a clause, reopen the cell and clear the clause from the selection.

Quality clauses are defined in Settings. See [Manage requirements](/administration/supply-chain-settings/manage-requirements).

## Comment on a purchase order

Use comments to leave notes on the PO or on a specific line. Type `@` in a comment to mention a teammate.

* To comment on the whole order, use the **Comments** card on the PO detail page. Enter your note and post it.
* To comment on a line, click the message icon in the line's **Comments** column. A **Comments** panel opens on the side where you can read and add notes for that line. The icon shows a count when a line has comments.

## Add labels to a purchase order

Labels are shared tags you apply across ION to group related records. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

To add a label, click **Labels** (or **Add labels** when the purchase order has none), then type in the **Search or create labels...** box and select it. To remove one, click the **X** on the label.

## Attach files to a purchase order

Attach files such as images, PDFs, and STEP/STP files, up to 100 MB each.

1. On the purchase order, find the **Attachments** section.
2. Add a file by dragging it onto the upload area, clicking to browse, or taking a photo on a device with a camera.

To remove a file, click its delete control and confirm.

<Note>
  When a file is attached through a file-type custom attribute, the delete dialog offers **Remove from attribute** (keeps the file but detaches it) and **Delete permanently**.
</Note>

## Mark a purchase order paid

The **Paid** toggle sits in the **Purchase Order Lines** card header, next to **Add Line**. Turning it on records the order as paid. Each line also carries its own **Paid** toggle in its row. Both stay editable regardless of the PO's status.

## Add fees to a purchase order

Fees cover charges that aren't tied to a single line, such as tax or shipping.

1. On the PO, find the **Fees** card and click **Add Fee**.
2. In **Add New Fee**, enter a **Fee Name**.
3. Choose **Fixed Amount** or **Percentage**, then enter the amount or percentage.
4. Save the fee. It joins the **Fees Total** in the **Cost Summary**.

Fees can be added or removed only while the PO is editable. To remove one, delete its row in the **Fees** card.

## Add supplier instructions and custom attributes

The **Additional Information** card holds a **Supplier Instructions** field for notes the supplier should see, along with any [custom attributes](/administration/custom-attributes) your org defines for purchase orders.

## Set an external reference

Set the **External Reference** field in the purchase order's **Purchase Order Information** section to link the PO to an identifier from another system, such as an ERP PO number.

<Frame>
  <img alt="Purchase Order Information section showing the External Reference field alongside Supplier and Currency" />
</Frame>

## Reuse an order

To start a new purchase from an existing one instead of building it line by line, open the source PO and click **Duplicate** in the **More options** menu. ION copies the order into a new Draft PO you can adjust and submit. See [Manage a purchase order](#manage-a-purchase-order).

## Manage a purchase order

The **More options** menu in the PO header carries actions beyond the status buttons:

* **Email** opens an email to the supplier with the PO details.
* **Print** opens the print preview, where you can print or save the PO as a PDF. The printed header carries your organization's name, or its domain when no name is set, and the sidebar's checkboxes choose what else prints. **Company Logo** adds the logo from [general settings](/administration/organization-settings/configure-general-settings) beside the name; with no logo set, the option is unavailable and says where to add one.
* **Duplicate** creates a copy of the PO you can adjust and submit as a new order.
* **Return to Draft** reopens a submitted PO for editing. It's available once the PO is submitted and before it's received or canceled.
* **Cancel PO** cancels the order and all its lines, under the same conditions as **Return to Draft**.
* **Delete** permanently removes the PO. It's available only while the PO is in Draft.

## Related

* [Purchase order statuses](/manage-supply-chain/purchasing#statuses)
* [Approve purchase orders](/manage-supply-chain/purchasing/approve-purchase-orders)
* [Receive parts](/manage-supply-chain/receiving/receive-parts)


# Overview
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/index

How ION models a purchase order: its lines, statuses, purchase types, and links to suppliers, receiving, inventory, and runs.

A purchase order is one order placed with a supplier, made up of one or more **lines**. Each line names a part (or a free-text good or service), a quantity, a cost, and delivery details. The line, not the PO, is the unit ION tracks: a PO's status rolls up from its lines, receiving happens line by line, and line quantities can be received in parts.

Purchase orders connect to the rest of the build. A supplier owns the order. Each line's part sets whether receiving creates [inventory](/manage-supply-chain/inventory) and how it converts units. Receiving turns ordered lines into on-hand stock, and runs consume that stock, so floor consumption feeds back into demand and reorder planning. Every purchase traces to the inventory that arrived and the run that consumed it.

## Purchase order lines

A line carries the part, quantity, unit cost, ETA, and paid status, plus any quality clauses or term requirements the supplier must deliver against. Editability is governed by the PO's status, not the line's own status: see the [statuses](#statuses) table. To place an order and build its lines, see [Create a purchase order](/manage-supply-chain/purchasing/create-a-purchase-order). To reuse a common order, copy a purchase template.

A line with no part behaves like a physically received part that creates no inventory. Use it for one-off goods and services you don't stock.

## Fees and totals

Beyond line costs, a PO can carry **fees**, each a fixed amount or a percentage of the order. The **Cost Summary** rolls the order up into **Lines Subtotal**, **Fees Total**, and **Grand Total**. To add fees, see [Add fees to a purchase order](/manage-supply-chain/purchasing/create-a-purchase-order#add-fees-to-a-purchase-order).

## Statuses

A PO's status is calculated from the statuses of its lines. It controls what stays editable and where the order sits in the approval and receiving workflow.

| Status        | Meaning                                                                                             | Editable                                                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Draft**     | Any line is in Draft.                                                                               | Every field on every line, regardless of the line's own status. You can increase a line's quantity even if it's already fully received. |
| **In Review** | A line has been requested for approval. Reviewers approve level by level.                           | ETA, Paid status, and custom attributes only.                                                                                           |
| **Approved**  | All reviewers have approved. The buyer can move the PO to Ordered and send the PDF to the supplier. | ETA, Paid status, and custom attributes only.                                                                                           |
| **Ordered**   | The PO has been placed. Stays Ordered even after some lines are received.                           | ETA, Paid status, and custom attributes only.                                                                                           |
| **Received**  | All lines are received or canceled.                                                                 | ETA, Paid status, and custom attributes only.                                                                                           |
| **Canceled**  | All lines are canceled.                                                                             | ETA, Paid status, and custom attributes only.                                                                                           |

To edit a line on a PO that has moved past Draft, return the PO to Draft. You can't manually set a line to any status other than **Canceled**, and a canceled line can be uncanceled only while its PO is in Draft.

## Approvals

When your org has an approval policy, a PO routes to reviewers level by level: each level is notified in sequence, and the PO reaches **Approved** once every level approves. A change past your org's reset threshold triggers reapproval. See [Approve purchase orders](/manage-supply-chain/purchasing/approve-purchase-orders).

<Tip>
  Approval levels and the reset threshold are configured in Settings, not on the PO. See [Configure PO approval workflow](/administration/supply-chain-settings/configure-purchase-order-approval).
</Tip>

## Purchase types

A part's **Purchase Type** decides whether buying it has a physical receiving step and whether receiving creates inventory. You set it on the part record when you [create or edit the part](/build-hardware/parts/creating-managing).

| Purchase type                                      | Receipt? | Creates inventory?                         | Use it for                                                                                    |
| -------------------------------------------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| **Creates inventory**                              | Yes      | Yes, in **On Order** status until received | Parts you track, move, install, and raise issues against.                                     |
| **Does Not Create Inventory, Physically Received** | Yes      | No                                         | Repeated purchases of goods or services you don't stock, such as anodizing or heat treatment. |
| **Does Not Create Inventory, Digitally Received**  | No       | No                                         | Purchases where nothing physical arrives, such as software.                                   |

A PO line with no part behaves like **Does Not Create Inventory, Physically Received**; use it for a one-off good or service instead of creating a part. Changing a part's purchase type applies to future PO lines only and doesn't alter lines already created.

<Tip>
  If a PO shows received but the part has no inventory, confirm the purchase type is **Creates inventory**, the line has a part, the receipt is fully rather than partially received, and the inventory isn't hidden by a status filter (it may be **On Order** or **Unavailable**). See [Statuses](#statuses).
</Tip>

## Unit of measure conversions

A part can be bought in the supplier's pack unit while stocked and consumed in your floor's unit: buy wire by the roll, stock and consume feet. The conversion lives on the supplier part number, the link between an ION part and a specific supplier's SKU, so the same part can carry different conversions from different suppliers. Receiving applies the conversion, so the PO line reads in the purchase unit while the inventory it creates reads in the stock unit. See [Unit of measure conversions](/manage-supply-chain/purchasing/unit-of-measure-conversions).

## Consigned parts

You can provide parts to a supplier or assembler that you own until they're consumed in production. ION ties the purchase, a run, and a kit together so the supplier receives the consigned parts and they install onto the assembly's aBOM once received. See [Purchase consigned parts](/manage-supply-chain/purchasing/purchase-consigned-parts).

## External reference

The **External Reference** field links a PO to an identifier from another system, such as an ERP PO number. The reference shows in place of the ION PO number wherever the purchase appears and is searchable on the **Purchases** page.


# Manage suppliers
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/manage-suppliers

Create suppliers, edit their contact details, and link supplier part numbers and costs to the parts you buy.

A supplier is a company you buy parts from. Purchase orders reference a supplier, and supplier part numbers connect a supplier's SKU, units, and cost to a part in your Parts Library.

## Create a supplier

1. In ION, go to **Supply Chain > Suppliers**.
2. Click **Create Supplier**.
3. Enter a **Name**. This field is required.
4. Optional: Fill in **Contact Name**, **Email**, **Phone**, **Address**, and **Description**.
5. Click **Create Supplier**.

The new supplier appears in the table and is available to pick on purchase orders.

<Tip>
  To create or update many suppliers at once from a CSV file, use the Suppliers importer. See [Supplier imports](/administration/ion-importers/suppliers).
</Tip>

## Edit a supplier

1. In ION, go to **Supply Chain > Suppliers**. Use the search box to filter by supplier, contact, email, or phone.
2. Click into the **Contact**, **Email**, **Phone**, **Address**, or **Description** cell and type. ION saves the change automatically.

If your org has added custom attributes to suppliers, they show as extra columns in the table by default, and you edit them the same way. See [Custom attributes](/administration/custom-attributes).

## View a supplier's related records

The Suppliers table shows counts that open a summary when you click them:

* **Supplier Parts**: the supplier part numbers linked to this supplier, listed by **Part Number** and **Cost**. Click a row to open the part in the Parts Library.
* **Purchase Orders**: the purchase orders placed with this supplier.
* **Parts Inventories**: the inventory received from this supplier.

Clicking a supplier's name shows its contact details: **Description**, **Address**, **Phone**, **Contact**, and **Email**.

## Add a supplier part number

A supplier part number links a part to a specific supplier's SKU, and carries the supplier's unit of measure, conversion factor, and cost. You add it from the part, not from the Suppliers page.

1. In ION, open the part in the **Parts Library**.
2. Open the **Suppliers** card on the part.
3. Click **Add Supplier Part**.
4. In the **Create Supplier Part** dialog, fill in:
   * **Select Supplier**: pick the supplier. This field is required.
   * **Supplier Part Number**: the supplier's SKU. This field is required.
   * **Supplier Part Units**: the unit the supplier ships in, such as Reel, Drum, or Each. This field is required.
   * **Unit of Measure Conversion Factor**: how many of the part's stock units are in one supplier unit. This field is required.
   * **Cost**: what this supplier charges per supplier unit, in your org's default currency. This field is optional.
5. Click **Save**.

The **Suppliers** card lists each entry by **Supplier**, **Supplier Part #**, **Supplier UoM**, **Conversion (to part UoM)**, and **Cost**, where you can edit the units, factor, and cost inline or delete an entry. Clearing the **Cost** field leaves the entry with no cost rather than setting it to 0, and a negative cost is rejected. For how the conversion flows through purchasing, receiving, and inventory, see [Unit of measure conversions](/manage-supply-chain/purchasing/unit-of-measure-conversions).

The cost also shows in the **Supplier Part #** picker on a purchase order line, beneath each supplier part number along with the supplier's name, which tells dual-sourced options apart while you pick. Selecting a supplier part doesn't fill in the line's unit cost.

## Related

* [Unit of measure conversions](/manage-supply-chain/purchasing/unit-of-measure-conversions)
* [Supplier imports](/administration/ion-importers/suppliers)
* [Create a purchase order](/manage-supply-chain/purchasing/create-a-purchase-order)


# Purchase consigned parts
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/purchase-consigned-parts

Track parts you provide to a supplier or assembler that you own until they're consumed in production.

## Run a consigned part flow

1. Create a purchase order for the work.
2. Create a run for the assembly.
3. Create a kit tied to the run.
4. Kit the inventory the supplier needs and deliver the kit. Mark the corresponding steps complete. To track the parts at the supplier, tie the kit to a location that represents the vendor, so inventory shows at the vendor's location.
5. Tie the PO line to the run step using an [outside processing](/build-hardware/runs-and-execution/outside-processing) step.
6. When the assembly is received, complete the receiving inspection step.
7. In **Part Installs (aBOM)** on the run, click **Install all from kit** to install the kitted parts onto the assembly, then complete the run. See [Kit parts to a run](/manage-supply-chain/kitting/kit-parts-to-a-run#install-kitted-parts-on-a-run-step).

## Related

* [Outside processing](/build-hardware/runs-and-execution/outside-processing)
* [Kit parts to a run](/manage-supply-chain/kitting/kit-parts-to-a-run)
* [Run incoming inspections](/manage-supply-chain/receiving/run-incoming-inspections)


# Unit of measure conversions
Source: https://docs.firstresonance.io/manage-supply-chain/purchasing/unit-of-measure-conversions

Buy parts in the supplier's pack quantity while stocking and consuming them in the unit your floor uses.

A unit of measure (UOM) conversion lets you buy in the supplier's unit while stocking and consuming in your floor's unit. For how the conversion flows across purchasing, receiving, and inventory, see the [Purchasing overview](/manage-supply-chain/purchasing#unit-of-measure-conversions).

Three units commonly coexist on a purchase:

| Unit         | What it's for                                                               |
| ------------ | --------------------------------------------------------------------------- |
| Stock UOM    | How the part is tracked in inventory and consumed on a BOM, such as `feet`. |
| Purchase UOM | How the supplier sells it, such as `roll`.                                  |
| Cost UOM     | The unit the unit cost is expressed in, such as per `roll`.                 |

## Configure a conversion

A conversion lives on the supplier part number; the link between an ION part and a specific supplier's SKU. The same part can come from two suppliers in two pack quantities, so each conversion is stored independently.

1. In ION, open the part in the **Parts Library**.
2. Open the **Suppliers** section on the part.
3. Click **Add Supplier Part** to open the **Create Supplier Part** dialog, then provide:
   * **Supplier**: pick from your supplier list.
   * **Supplier Part Number**: the supplier's SKU.
   * **Supplier Part Units**: the unit the supplier ships in.
   * **Unit of Measure Conversion Factor**: how many stock-UOM units are in one supplier-UOM unit.
4. Save.

To manage the list of available units, see [Manage units of measure](/administration/supply-chain-settings/manage-units-of-measure).

## On a purchase order

1. Add the ION part to a PO line. ION offers a **Supplier Part** picker, populated from that part's supplier part numbers for the PO's supplier.
2. Pick the supplier part. The line switches into the supplier UOM.
3. Enter the quantity in the supplier UOM.
4. Enter the unit cost in the supplier UOM.

If you don't pick a supplier part, the line falls back to the stock UOM. The **On Order** inventory ION creates is recorded in the stock UOM (500 feet, On Order) even though the line shows 5 rolls.

## On receiving

1. The receiver opens the receipt for the PO. The receipt line shows the supplier UOM.
2. As each unit is received, ION applies the conversion.
3. The resulting inventory carries the stock UOM.

## Changing a conversion

When a supplier changes pack quantity, for example from 100-foot rolls to 250-foot rolls, create a new supplier part number with the new conversion factor rather than editing the old one.
Old POs reference the old supplier part number and need its conversion to reconcile correctly. ION does not re-apply a changed conversion to receipts already received.

## Related

* [Manage units of measure](/administration/supply-chain-settings/manage-units-of-measure)
* [Receive parts](/manage-supply-chain/receiving/receive-parts)


# Overview
Source: https://docs.firstresonance.io/manage-supply-chain/receiving/index

How ION models receiving: a receipt turns a PO shipment into part inventory and can trigger incoming inspection.

Receiving turns a supplier shipment into part inventory. You receive against an ordered [purchase order](/manage-supply-chain/purchasing), and ION opens a receipt that captures the identity of the arriving units: serial number, lot number, and put-away location. Completing the receipt creates the [inventory](/manage-supply-chain/inventory) records that the rest of ION draws on.

A receipt is also where incoming inspection begins. When a received part requires an inspection, ION holds the new inventory and creates the inspection run automatically, so the two steps stay linked on the same record.

## Receipts and PO status

One PO can produce many receipts, and one receipt can cover many PO lines. As you receive lines, the PO status advances on its own to **Partially Received** while lines remain and to **Received** once every line is received or canceled. For the flow, see [Receive parts](/manage-supply-chain/receiving/receive-parts).

The fields a receipt asks for depend on the part's tracking type: serial number for serial parts, lot number for lot parts, and location for anything that lands in inventory. Purchases with no part, such as services, skip these fields because nothing physical is tracked. See [Purchase types](/manage-supply-chain/purchasing#purchase-types).

## Incoming inspection

A part requires incoming inspection through its part-procedure relationship, where you mark an inspection run as required and approve the relationship. From then on, receiving that part creates an inspection run on the receipt. While the run is open the inventory sits at **WIP**, and it becomes **Available** when the run completes. Inspection results stay on the inventory record for traceability. For the steps, see [Run incoming inspections](/manage-supply-chain/receiving/run-incoming-inspections).


# Receive parts
Source: https://docs.firstresonance.io/manage-supply-chain/receiving/receive-parts

Process a receipt against a purchase order and capture serial, lot, and location.

To start receiving, click **Receive** on an ordered PO. The receiving page opens with that PO's lines and a queue of the other receivable POs. For how receipts relate to PO status and inventory, see [Overview](/manage-supply-chain/receiving).

**Receiving** on the **Receipts** page opens the same workspace without picking a PO first. On a receipt's own page it opens the workspace on that receipt's purchase order.

<Frame>
  <img alt="Receiving page showing the receivable purchase order queue and a selected partially received PO with the Receiving location control and five lines with completion progress" />
</Frame>

## Receive against a purchase order

A line joins the receipt you're building the moment you open it, and one **Finalize receipt** commits every line at once.

1. Open a purchase order in **Ordered** status and click **Receive**.
2. Optional: set the **Receiving location** at the top of the PO to put every line away in the same place. You can override it on an individual line.
3. Click **Receive** on a line and, for each unit, specify the following:
   * **Serial number**, if the part is serial tracked.
   * **Lot number**, if the part is lot tracked.
   * **Location**, unless the receiving location already applies.
4. Click **Receive** on the next line in the shipment. The line you finished collapses to an **Added** summary; a line still missing details stays open and shows **Needs details**.
5. Click **Finalize receipt** to create one receipt covering every line you added.

As lines are received, the PO status advances automatically to **Partially Received** while some lines remain, and to **Received** once all lines are received or canceled.

### Track and adjust the receipt before finalizing

A bar at the bottom of the page summarizes what the receipt holds so far: **N lines ready** with a unit total, or **N lines need attention** when a line is still incomplete. Each line appears as a chip with the part number and quantity.

* To reopen a line, click the edit control on its chip or **Edit** on the line.
* To take a line back off the receipt, click the remove control on its chip or on the line.
* To abandon the whole receipt, click **Discard**.

**Finalize receipt** stays unavailable while any line needs attention, so a partial receipt can't be committed by mistake.

### Receive several lines at once

Select the lines you want with their checkboxes, or click **Select all open**, then use the toolbar above the lines:

* **Receive N lines** opens every selected line at once.
* **Update N lines** applies one field across the selection: a location lands on every selected line, and a lot number lands on the lot-tracked ones. Either action adds those lines to the receipt, so they flow into the same **Finalize receipt**.

## Flag a problem while receiving

If a unit arrives damaged or non-conforming, click **Report** on that unit to open an issue against it. The unit then shows the linked issue. See [Create an issue](/track-quality/issues/create-an-issue).

## Add attachments and receipt details

Before finalizing, you can attach files to the receipt, such as a packing slip or a certificate, and fill in any receipt [custom attributes](/administration/custom-attributes) your org defines. Both sit below the PO's lines.

<Tip>
  Create one receipt per delivery. A PO that arrives in three shipments gets three receipts, and a single shipment that covers two POs gets two receipts, one per PO.
</Tip>

## Receive non-part purchases

You can also receive purchases that have no part, such as services. The flow is the same, except the inventory fields (serial, lot, location) don't appear, because there's nothing physical to track. See [Purchase types](/manage-supply-chain/purchasing#purchase-types).

## Find a receipt

To find a receipt for a PO, type the PO number in the search box on the **Receipts** page.

## Edit a receipt after finalizing

A finalized receipt's custom attributes and attachments stay editable on the **Receipts** page. The received serials, lots, and locations don't change here.

1. On the **Receipts** page, open the receipt.
2. To change a value, edit the receipt [custom attributes](/administration/custom-attributes) in the receipt's detail pane. To attach a file, use the attachments area in the same pane.
3. To set the same attribute value on several receipts at once, select them on the **Receipts** page and click **Change Attributes**.

When your org defines custom attributes on parts inventory, those attributes show as columns on the receipt's unit table, in both the **By PO line** and **All units** views. Edit a unit's value inline in its column.

## Comment on a receipt

A **Comments** card at the bottom of the receipt's detail pane holds a discussion thread for the whole receipt, below its attachments and custom attributes.

1. On the **Receipts** page, open the receipt.
2. In the **Comments** card, write your note in the **Add a comment on this receipt...** field. You can format the text and `@`-mention a user to notify them directly.
3. Click **Comment**.

To reply to a comment, use its reply control. To close a thread, resolve it; a resolved comment can be reopened later.

## Act on a received unit

You can work on the inventory a receipt created without leaving the receipt. On the receipt's unit table, in both the **By PO line** and **All units** views, each unit row has an **Inventory actions** menu:

* **Split** breaks the unit into separate inventory records. See [Split inventory](/manage-supply-chain/inventory/split-inventory).
* **Move** puts the unit away in a different location.
* **Adjust** sets a new total quantity, scraps part of the unit, and records a reason for the adjustment.
* **History** shows the unit's audit trail.

Each action opens the same dialog you get from the **Inventory** page, on the matching tab, and the receipt refreshes once the action completes.

<Note>
  **Split** isn't available on a serial-tracked unit, since a serial number
  identifies a single unit.
</Note>

## Related

* [Run incoming inspections](/manage-supply-chain/receiving/run-incoming-inspections)
* [Purchase order statuses](/manage-supply-chain/purchasing#statuses)
* [Inventory statuses](/manage-supply-chain/inventory#statuses)


# Run incoming inspections
Source: https://docs.firstresonance.io/manage-supply-chain/receiving/run-incoming-inspections

Inspect incoming parts at the dock with inspection runs that ION creates automatically on receipt.

Incoming inspection runs are created on the receipt. For how they fit the receiving flow, see [Overview](/manage-supply-chain/receiving).

## Require an inspection on receipt

You set whether a part needs an inspection on its part-procedure relationship. Mark the inspection run as **required**, and approve the relationship. To link a procedure to a part and set this, see [Part-procedure relationship](/build-hardware/procedures/part-procedure-relationship).

## Complete an inspection at receiving

1. Receive the part. ION creates an inspection run for the received part.
2. Run the inspection steps and capture results.
3. Complete the run. The inventory becomes **Available**, and the inspection results stay on the inventory record for traceability.

<Tip>
  Require inspection on critical parts so a defect is caught at the dock rather
  than mid-run, where it can halt a line.
</Tip>

## Related

* [Receive parts](/manage-supply-chain/receiving/receive-parts)
* [Part-procedure relationship](/build-hardware/procedures/part-procedure-relationship)
* [Issues](/track-quality/issues)


# Containment
Source: https://docs.firstresonance.io/track-quality/containment

Stop suspect inventory or work from moving forward while you investigate a quality problem.

In ION you contain through issues: an open issue can hold the affected inventory, and you can hold the run step where the problem surfaced.

## Hold affected inventory

To stop suspect inventory from being used, file an issue against it with a disposition whose availability behavior holds it. The inventory shows **Unavailable** while the hold is in effect: until the issue resolves with **Release on Resolve**, or for good with **Permanently Unavailable**.

1. In the inventory table, filter to the affected parts, for example by lot or serial number, and select the rows.
2. Press **Cmd+K**, then choose **Create Issue** to attach the selected inventory.
3. Give the issue a **Title** and submit it.
4. Set a disposition type whose availability behavior holds the inventory: **Release on Resolve** holds it until the issue resolves; **Permanently Unavailable** holds it for good.

<Note>
  A hold only pauses the inventory while you investigate. The decision to rework, scrap, or use it as-is comes later, through the disposition.
</Note>

## Put a run step on hold

Putting a run step on hold stops work on it and prevents the run steps that depend on it from starting, which contains a problem to the point where it surfaced.

1. On the run step, open the more actions (**⋯**) menu.
2. Click **Put Step on Hold**.

The run step shows **On hold**, and the run steps that depend on it can't start until you take it off hold. To take it off hold, open the more actions menu again and move the run step to another status, such as **Move to To-Do**.

<Info>
  Receiving inspection can also automatically create an inspection run for incoming inventory, based on its intent. That's configured per intent option in [Manage intent options](/administration/quality-settings/manage-intent-options).
</Info>

## Related

* [Create an issue](/track-quality/issues/create-an-issue)
* [Issue states, dispositions, and resolutions](/track-quality/issues)


# Create a further action
Source: https://docs.firstresonance.io/track-quality/further-actions/create-a-further-action

Open a further action on its own or from one or more issues, and describe the problem you're tracking.

You can create a further action on its own or directly from the issues that prompted it.

## Create a standalone further action

1. On the **Further Actions** page, click **New Further Action**.
2. In the **Create Further Action** dialog, enter a **Title**.
3. Optional: set **Assigned To**, **Expected Completion**, the **Problem Statement**, and any **Associated Issues**.
4. Click **Create Further Action**.

## Create a further action from issues

1. On the **Issues** page, select the issues the further action addresses.
2. In the actions bar, click **Create Further Action**.
3. Fill in the **Create Further Action** dialog. The selected issues are linked automatically.

<Tip>
  Group the related issues under one further action so a single root-cause investigation covers all of them. See [Link records to a further action](/track-quality/further-actions/link-records-to-a-further-action).
</Tip>

## Related

* [Resolve a further action](/track-quality/further-actions/resolve-a-further-action)
* [Link records to a further action](/track-quality/further-actions/link-records-to-a-further-action)


# Overview
Source: https://docs.firstresonance.io/track-quality/further-actions/index

How ION models a Further Action (CAPA): its three working fields, its states, and its two-way link to the issues it addresses.

A Further Action (CAPA) is ION's record of a root-cause investigation and its corrective and preventive actions. It links the [issues](/track-quality/issues) that prompted it, so several related or recurring issues are investigated and resolved under one root cause rather than one at a time. The link is two-way: a linked issue lists the further action, and the further action lists the issue.

You work a further action through three fields as the investigation progresses: **Problem Statement** (what went wrong and its impact), **Analysis Notes** (the root-cause investigation), and **Resolution** (the corrective and preventive actions taken). Your organization can [rename these fields](/administration/quality-settings/rename-fields).

A further action also carries an optional **expected completion date**, a target you set from the date picker on the further action. It reads **No expected completion date** until you set one.

## States

A further action moves through four states. **Canceled** is a terminal alternative to resolving.

| State           | What it means                                                                         |
| --------------- | ------------------------------------------------------------------------------------- |
| **In Progress** | You are investigating and recording the analysis and resolution. Fields are editable. |
| **In Review**   | Submitted for approval. The configured roles must approve before it can resolve.      |
| **Resolved**    | Approved and closed. Fields are read-only.                                            |
| **Canceled**    | Closed without resolving. Fields are read-only.                                       |

You [move a further action through review to resolution](/track-quality/further-actions/resolve-a-further-action), and you can cancel or reopen one from these states.

## Linked issues

A further action groups the issues it addresses, and a single investigation covers all of them. You can open a further action [directly from selected issues](/track-quality/further-actions/create-a-further-action) so those issues are linked at creation, or [link issues to an existing further action](/track-quality/further-actions/link-records-to-a-further-action) from either side of the relationship.

To comment on, label, or attach files to a further action, see [Work with a further action](/track-quality/further-actions/work-with-a-further-action).


# Link records to a further action
Source: https://docs.firstresonance.io/track-quality/further-actions/link-records-to-a-further-action

Link the issues, parts, and runs a further action addresses, so related records are investigated under one root cause.

A further action can link the issues that prompted it, the parts it concerns, and the runs that carry out the investigation. Each record type has its own section on the further action, and you link or unlink from there. You can also link an issue from the issue itself.

## Link an issue from the further action

1. On the further action, find the **Related Issues** section.
2. Click **Add Issue** and select one or more issues to link.

To unlink an issue, click the remove control on that issue in the **Related Issues** section.

## Link a further action from an issue

1. On the issue, find the **Further Actions** section.
2. Click **Add Further Action** and select the further action to link.

## Link parts

1. On the further action, find the **Parts** section.
2. Click **Add Part** and select one or more parts to link.

To unlink a part, click the remove control on that part in the **Parts** section.

## Link runs

1. On the further action, find the **Runs** section.
2. Click **Add Run** and select one or more runs to link. To start a new run for the investigation instead, click **New Run**.

To unlink a run, click the remove control on that run in the **Runs** section.

## Related

* [Create a further action](/track-quality/further-actions/create-a-further-action)
* [Resolve a further action](/track-quality/further-actions/resolve-a-further-action)


# Resolve a further action
Source: https://docs.firstresonance.io/track-quality/further-actions/resolve-a-further-action

Move a further action through review and approval to resolution, and cancel or reopen one when needed.

## Resolve a further action

1. While the further action is **In Progress**, record your **Analysis Notes** and **Resolution**.
2. Click **Submit for Review**. The further action moves to **In Review** and approval requests go to the configured roles.
3. Once the required approvals are in, click **Resolve**.

To send a further action in review back for more work, click **Return to In Progress**, which clears its approvals.

## Cancel or reopen a further action

* To close a further action without resolving it, click **Cancel**.
* To return a **Resolved** or **Canceled** further action to **In Progress**, click **Reopen**.

## Related

* [Create a further action](/track-quality/further-actions/create-a-further-action)
* [Link issues to a further action](/track-quality/further-actions/link-records-to-a-further-action)


# Work with a further action
Source: https://docs.firstresonance.io/track-quality/further-actions/work-with-a-further-action

Comment on, label, and attach files to a further action as you investigate and resolve it.

Comments, labels, and file attachments let you collaborate on a further action and keep supporting material with it. For the further action's fields, states, and links, see the [further action overview](/track-quality/further-actions).

## Comments

The **Comments** section on a further action holds a running discussion of the investigation and its reviews. Type in the comment box, then send the comment. To reply to a comment, use its reply control. To close a thread, resolve it; a resolved thread can be reopened later. Filter the feed by **Further Action** and **Reviews**.

## Labels

Labels are shared tags you apply across ION to group related records. To add one, click **Labels** (or **Add labels** when the further action has none), then type in the **Search or create labels...** box and select it. To remove one, click the **X** on the label. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

## Attachments

The **Attachments** section holds files such as images, PDFs, and STEP/STP files attached to the further action. Add a file by dragging it onto the section, clicking **Browse files**, or, on a device with a camera, clicking **Take a photo**. To remove a file, click its delete control and confirm in the **Delete attachment?** dialog.

## Related

* [Overview](/track-quality/further-actions)
* [Resolve a further action](/track-quality/further-actions/resolve-a-further-action)
* [Labels](/administration/labels)
* [Subscribe to notifications](/automate-with-ion/notifications/subscribe-to-notifications)


# Associate inventory to an issue
Source: https://docs.firstresonance.io/track-quality/issues/associate-inventory-to-an-issue

Link the inventory an issue affects and the inventory used to resolve it, for full traceability.

You manage both the affected inventory and the resolution inventory on the issue's **Parts** tab.

<Frame>
  <img alt="Issue Parts tab showing a Problem Part with an attached part and an empty Resolution Part" />
</Frame>

## Add the affected inventory

1. On the **Issues** page, open the issue.
2. Open the **Parts** tab.
3. Under **Problem Part**, click **Add Parts** and choose the affected part inventory.
4. Repeat for each additional affected part.

## Set the resolution inventory

1. On the issue's **Parts** tab, under **Resolution Part**, click **Add Part**.
2. Choose the part inventory used to resolve the issue.

## Remove inventory from an issue

On the issue's **Parts** tab, click the remove control on the inventory you want to take off the issue. This works under both **Problem Part** and **Resolution Part**.

Removing inventory is blocked while the issue is read-only: when it's **Pending** with approvals configured, when it's **In Review**, and when it's **Resolved**.

## Related

* [Create an issue](/track-quality/issues/create-an-issue)
* [Issue states, dispositions, and resolutions](/track-quality/issues)


# Create an issue
Source: https://docs.firstresonance.io/track-quality/issues/create-an-issue

Raise a quality issue in ION, attach the affected parts, runs, and run steps, and route it to the right person.

## Start creating an issue

You can start an issue from several places in ION. Use the one that fits where you are:

* Press **Cmd+Shift+I** (Mac) or **Ctrl+Shift+I** (Windows) from any page.
* On the **Issues** page, click **New Issue**.
* On a run step, click **Create Issue** to attach that run and step automatically.
* Select one or more rows in an inventory, receipt, or purchase order table, press **Cmd+K** to open the command palette, and choose **Create Issue** to attach the selected parts.

<Tip>
  Starting from the record where you found the problem prefills its context, which saves time: from a run step, the run and step are attached; from selected inventory, receipts, or purchase orders, the selected parts are added to **Related Parts**.
</Tip>

## Fill in the issue details

Fill in the fields you need. **Title** is the only field that's always required; others can become required from what you enter, such as a **Run Step** once you pick a **Run**.

<Frame>
  <img alt="Create New Issue form showing the Title field, Found on Step, Resolve by, and Related Parts" />
</Frame>

1. Enter a **Title**.
2. Optional: under **Found on Step**, select the **Run** and **Run Step** where the problem appeared. Selecting a run requires selecting its step.
3. Optional: under **Resolve by**, select the **Run** and **Run Step** that must be completed to resolve the issue.
4. Optional: add the affected inventory under **Related Parts**. For a part tracked by quantity, enter the number of affected units.
5. Optional: describe the problem in **Cause Condition** and what the result should have been in **Expected Condition**.
6. Optional: attach photos, measurements, or documents under **Attachments**.
7. Optional: set **Move to Location** to send the affected inventory to a location such as a quarantine area, and **Assign to** to assign the issue to a user or team.
8. Set any custom **Additional Attributes** your organization configures. Some can be required before you can submit.
9. Click **Submit Issue**. To raise another issue right away, click **Submit & Create New** instead.

<Note>
  Your organization can rename **Cause Condition**, **Expected Condition**, and **Disposition**, so the labels you see may differ. See [Rename fields](/administration/quality-settings/rename-fields).
</Note>

## Related

* [Issue states, dispositions, and resolutions](/track-quality/issues)
* [Split or clone an issue](/track-quality/issues/split-or-clone-an-issue)
* [Configure issue creation and approvals](/administration/quality-settings/configure-issue-creation-and-approvals)


# Find and export issues
Source: https://docs.firstresonance.io/track-quality/issues/find-and-export-issues

Narrow the Issues page with shortcut cards and filters, read the matching total, and export the results to CSV.

The **Issues** page lists every issue in your organization. Shortcut cards and the **Filters** panel narrow that list, a total in the table toolbar tells you how many issues match, and **Export CSV** writes either your selection or the whole match to a file.

## Narrow the list with a shortcut card

Four cards sit above the table. The first three apply a filter and show a count:

| Card                  | What it filters to                     |
| --------------------- | -------------------------------------- |
| **My Issues**         | Open issues assigned to you.           |
| **Created this week** | Issues created in the last seven days. |
| **Open**              | All open issues.                       |

"Open" means **Pending**, **In Progress**, or **In Review**. Each card counts the same set it filters to, so once a card is the only filter active, its badge and the toolbar total agree.

Click a card to apply its filter; the card highlights while it's active, and clicking it again removes the filter. Toggling a card off clears only the conditions the cards themselves use: status, assignee, and creation date. Other conditions you built in the **Filters** panel stay. **My Issues** and **Open** share the status condition, so clicking **Open** while **My Issues** is active drops the assignee condition and widens the list to all open issues. The fourth card, **Create Issue**, opens the create dialog instead of filtering. When any filter is active, a **Clear** control appears alongside the cards to remove them all.

Large counts are abbreviated (`47.3K`). Hover a badge to read the exact number.

## Read the matching total

The table toolbar shows the number of issues matching the current filter, as **N rows**. It tracks the shortcut cards, the **Filters** panel, and the search box together, so it always describes what's on screen.

## Select issues

The header checkbox selects the rows that are currently loaded, not every issue that matches. The floating toolbar names which one you have:

* **N of M selected** after selecting all, when more issues match than are loaded. M is the matching total, and the gap tells you the selection is partial.
* **N items selected** in every other case: a hand-picked selection, or a selection that already covers every matching issue.

Scroll to load more rows, then select again to widen the selection.

## Export to CSV

Click **Export CSV** in the table toolbar and choose:

* **Export selected (N)**: writes only the rows you selected.
* **Export all matching (N)**: pages through every issue matching the current filter, not just the rows already loaded. The button reports progress as **Exporting… X of Y** while it runs.

The export writes the columns you have visible, in their current order.

<Note>
  **Export all matching** covers at most 50,000 rows. Past 500 rows the menu warns that it will take a while; past 50,000 it says up front that only the first 50,000 rows are written. If an export stops short, a toast names how many rows were written and tells you to narrow the filter to get the rest.
</Note>

## Related

* [Overview](/track-quality/issues)
* [Create an issue](/track-quality/issues/create-an-issue)
* [Quality reporting](/track-quality/quality-reporting)


# Overview
Source: https://docs.firstresonance.io/track-quality/issues/index

How ION models an issue: its lifecycle states, dispositions, approval gates, and links to inventory, runs, and steps.

An issue (NCR) is ION's record of a quality event and the affected material. It links to the [parts and inventory](/manage-supply-chain/inventory), [runs](/build-hardware/runs-and-execution), and [run steps](/build-hardware/runs-and-execution/step-execution) it touches, and it carries the disposition, approvals, and resolution that decide what happens to that material.

Every issue shows across ION as an orange warning badge with a count on each object it affects. Click the badge to open the linked issues. You [raise an issue](/track-quality/issues/create-an-issue) from a run step, from selected inventory, or from the Issues page, and it moves through a fixed lifecycle until it resolves.

## States

An issue moves through four states in order. You advance it with the status button in its header.

| State           | What it means                                                  |
| --------------- | -------------------------------------------------------------- |
| **Pending**     | Open with no disposition set yet.                              |
| **In Progress** | A disposition is set and the work it calls for is underway.    |
| **In Review**   | The work is done and the issue is waiting on closure approval. |
| **Resolved**    | All required approvals are in and the issue is closed.         |

**Move to In Progress**, then **Ready for Review** (which moves it to **In Review**), then **Resolved** once reviews approve. **Return to In Progress** and **Reopen Issue** move it back when an issue needs more work. When an issue leaves **Pending**, any open redlines linked to it are released, returning their run step to **To-Do**.

For the end-to-end procedure, see [Resolve an issue](/track-quality/issues/resolve-an-issue).

## Dispositions

A disposition is the decision applied to the affected inventory. Your org defines the set of disposition types, along with each type's approval roles and availability behavior, in [Administration](/administration/quality-settings/manage-disposition-types). You must set a disposition before the issue can leave **Pending**, and changing the disposition type later returns the issue to **Pending** so it goes through approval again.

Each disposition type carries an availability behavior that governs when the affected inventory becomes usable again:

| Availability behavior       | Effect                                                                                                                 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Available Immediately**   | Inventory is available as soon as the disposition is applied.                                                          |
| **Release on Resolve**      | Inventory becomes available only when the issue reaches **Resolved**.                                                  |
| **Permanently Unavailable** | Inventory stays locked out. This is how you [scrap inventory](/track-quality/issues/scrap-inventory) through an issue. |

Depending on your org's settings, the disposition can lock once its approval is in.

## Approval gates

Two gates govern progression, and the disposition type's roles define who signs off at each:

* **Leaving Pending**: the disposition type's approver roles must approve before the issue becomes **In Progress**.
* **Reaching Resolved**: the disposition type's closure roles must approve before the issue resolves.

Each role requires a set number of approvers, and a person can approve once per role. Approvals happen in the **Reviews** view on the issue. If a disposition type is set to resolve automatically, an approved disposition moves the issue straight to **Resolved**, skipping **In Review** unless an extra Resolved-gate approval was added. The number of approvals required is set in [Administration](/administration/quality-settings/configure-issue-creation-and-approvals).

## Editing and locking

You can fully edit an issue while it's **Pending** with no approvals yet, and while it's **In Progress**. Once an approval is recorded, or the issue reaches **In Review** or **Resolved**, the issue becomes read-only.

Custom attributes follow a separate rule from the rest of the issue: they stay editable in every state except **Resolved**. A setting can keep them editable on a resolved issue too.

## Affected and resolution inventory

An issue tracks two kinds of inventory on its **Parts** tab: the **Problem Part** inventory the event affected, and the **Resolution Part** inventory used to resolve it. Linking both keeps a traceable record of which material a problem touched and which material closed it out. See [Associate inventory to an issue](/track-quality/issues/associate-inventory-to-an-issue).

When an issue covers material that needs different handling, you [split or clone it](/track-quality/issues/split-or-clone-an-issue) into separate issues, each with its own disposition and share of the inventory. Splitting units off a run onto an issue is driven from the run itself; see [Split inventory on a run](/build-hardware/runs-and-execution/split-inventory-on-a-run).

## Further Actions

When an issue points to a systemic problem, you escalate it to a Further Action, ION's corrective and preventive action (CAPA) record. See [Further Actions](/track-quality/further-actions).

To comment on, label, or attach files to an issue, see [Work with an issue](/track-quality/issues/work-with-an-issue). To narrow the Issues page and export what matches, see [Find and export issues](/track-quality/issues/find-and-export-issues).

<Note>
  Your organization can rename the **Cause Condition**, **Expected Condition**, and **Disposition** fields, so the labels you see may differ.
</Note>


# Resolve an issue
Source: https://docs.firstresonance.io/track-quality/issues/resolve-an-issue

Move an issue through its states to resolution, get the required approvals, and reopen it if more work is needed.

Resolving an issue moves it from **Pending** through to **Resolved**. For how the states, dispositions, and approval gates work, see the [Issues overview](/track-quality/issues).

1. Set a disposition on the issue.
2. Click **Move to In Progress**. If the disposition type requires approvers, they sign off first.
3. Do the work the disposition calls for, then click **Ready for Review**.
4. The closure roles approve in the **Reviews** view.
5. The issue moves to **Resolved**.

If the issue was created with a **Resolve by** run step, that run step can't be completed until the issue resolves.

## Change the disposition

1. On the issue, open the **Disposition** card.
2. In the **Disposition** dropdown, select a different disposition type.
3. In the **Confirm Disposition Change** dialog, click **Yes, change disposition**. To keep the current disposition, click **No, do not change disposition**.

Changing to a different disposition type returns the issue to **Pending**, so its approvers must sign off on the new disposition again before it can move forward.

## Reopen a resolved issue

To reopen a resolved issue and return it to **In Progress**, click **Reopen Issue**.

## Related

* [Issue states, dispositions, and resolutions](/track-quality/issues)
* [Create an issue](/track-quality/issues/create-an-issue)


# Scrap inventory with integrated traceability
Source: https://docs.firstresonance.io/track-quality/issues/scrap-inventory

Scrap nonconforming inventory through an issue so the reason and approvals are recorded.

## Scrap nonconforming inventory

1. Identify the inventory to scrap, for example from a cycle-count discrepancy or a defect found during a run.
2. [Create an issue](/track-quality/issues/create-an-issue) against that inventory.
3. Apply a disposition type your organization configured for scrapping, with the **Permanently Unavailable** availability behavior. Record the reason and any handling notes in the disposition.
4. Route the issue through review and resolve it.

Once the scrap disposition is applied, the affected inventory stays permanently unavailable.

## Related

* [Manage disposition types](/administration/quality-settings/manage-disposition-types)
* [Issue states, dispositions, and resolutions](/track-quality/issues)
* [Resolve an issue](/track-quality/issues/resolve-an-issue)


# Split or clone an issue
Source: https://docs.firstresonance.io/track-quality/issues/split-or-clone-an-issue

Copy or divide one issue into separate issues, each with its own inventory, disposition, and assignee.

Each new issue you create has its own disposition, notes, assignee, and share of the affected inventory.

## Clone vs Split

The difference is what happens to the inventory on the original issue when you assign it:

* **Clone**: the inventory stays on the original issue and is also added to the new issue. Use this when the new issues track related investigations of the same parts.
* **Split**: the inventory moves to the new issue and is removed from the original issue. Use this when you're dividing the affected inventory so each portion gets its own disposition.

Choose between the two with the assign control in step 4.

## Create the new issues

1. On the issue, open the **More options** menu and select **Clone / Split** to open the **Split into Detail Tickets** dialog. It has two areas: **Associate Inventory** for picking parts, and **Detail Tickets** for the new issues.
2. Click **Add Ticket** for each new issue you want. For each one, set a **Title**, a **Disposition Type**, **Disposition Notes**, and an assignee.
3. In **Associate Inventory**, select the parts for the new issue. For a lot-tracked part, adjust the quantity to assign.
4. Assign the selected inventory using one of:
   * **Assign to Ticket** to clone it (keep it on the original issue).
   * **Remove & Assign** to split it (move it off the original issue).
5. Optional: use **Copy Settings** to choose which fields carry over from the original issue to the new issues.
6. Click **Create Issues**.

Each new issue links back to the original under **Related Issues**.

<Frame>
  <img alt="Split into Detail Tickets dialog with an Associate Inventory panel and a Detail Tickets panel" />
</Frame>

## Link related issues

Splitting or cloning links the new issues automatically, but you can link any existing issue by hand.

1. On the issue, find the **Related Issues** section.
2. Click **Add Related Issue** and select the issue to link.

To unlink a related issue, click the remove control on that issue in the **Related Issues** section.

## Related

* [Create an issue](/track-quality/issues/create-an-issue)
* [Issue states, dispositions, and resolutions](/track-quality/issues)


# Work with an issue
Source: https://docs.firstresonance.io/track-quality/issues/work-with-an-issue

Comment on, label, and attach files to an issue as you investigate and resolve it.

Comments, labels, and file attachments let you collaborate on an issue and keep supporting material with it. For the issue lifecycle, dispositions, and approval gates, see the [issue overview](/track-quality/issues).

## Summary

Depending on your settings, an issue carries a **Summary** card above **Details**, collapsed until you open it. Expanding it writes a summary of the issue, and **Regenerate** replaces it with a fresh one. If a summary can't be generated, the card reads **Couldn't generate a summary. Try regenerating.**

The summary is drawn from the issue as a whole: what you wrote in **Cause**, **Expected**, and **Disposition**; its title, status, disposition type, assignee, and assigned team; the parts it was raised against, with part number, revision, serial, lot, quantity, and location; the run, run step, and procedure it came from; its Further Actions with their status, problem statement, and resolution; its redline count by status; related issues with their status; attachment filenames; and the most recent comments on it, each with its author.

Each of those is capped, so a long issue contributes its most recent comments rather than all of them. On an issue big enough to exceed what one summary can read, ION drops the associations first and the written content last, so the summary always has something to describe.

An issue holding no written content anywhere reads **Add more information to this issue to generate a summary.** rather than being summarized. Associations alone don't count: a title, a part, and a step with no prose is nothing to summarize. Prose in a Further Action or in the comment thread does count, so an issue whose **Cause**, **Expected**, and **Disposition** are all empty is still summarized when its thread carries the story.

## Comments

The **Comments** section on an issue holds a running discussion of the issue and its reviews. Type in the comment box, then send the comment. To reply to a comment, use its reply control. To close a thread, resolve it; a resolved thread can be reopened later. Filter the feed by **Issue**, **Reviews**, and, when the issue links a run step's procedure, **Procedure**.

## Labels

Labels are shared tags you apply across ION to group related records. To add one, click **Labels** (or **Add labels** when the issue has none), then type in the **Search or create labels...** box and select it. To remove one, click the **X** on the label. For creating and deleting labels in the shared library, see [Labels](/administration/labels).

## Attachments

The **Attachments** section holds files such as images, PDFs, and STEP/STP files attached to the issue. Add a file by dragging it onto the section, clicking **Browse files**, or, on a device with a camera, clicking **Take a photo**. To remove a file, click its delete control and confirm in the **Delete attachment?** dialog.

## Related

* [Overview](/track-quality/issues)
* [Resolve an issue](/track-quality/issues/resolve-an-issue)
* [Labels](/administration/labels)
* [Subscribe to notifications](/automate-with-ion/notifications/subscribe-to-notifications)


# Quality reporting
Source: https://docs.firstresonance.io/track-quality/quality-reporting

See quality metrics in the Analytics Quality tab, and build your own reports from quality data.

Quality data shows up in two places: a prebuilt **Quality** tab in Analytics, and the underlying tables you can query for custom reports.

## The Quality tab

In **Analytics**, the **Quality** tab shows prebuilt, read-only views of your open quality work:

* Open issues, and the average days to resolve them.
* Issues by **status**, and an **age distribution**.
* A breakdown of issues by **disposition type**.
* Open **redline** and **further action** counts.

<Frame>
  <img alt="Analytics Quality tab with open-issue, average-days-to-resolve, redline, and further-action metric cards above Issues by Status, Age Distribution, and Disposition Types charts" />
</Frame>

## Build your own quality reports

For anything beyond the Quality tab, query the quality data yourself. The **`quality_metrics`** and **`issue_details`** data products pre-join issue data (status, disposition, redlines, further actions, parts, and lifecycle timestamps) so you don't have to assemble it. Reach them through the [Data Connector](/automate-with-ion/analytics-and-dashboards/data-connector), a read-only SQL analytics layer you point a BI tool at, or query the [GraphQL API](/api-reference).

For the full data model, available tables, and refresh cadence, see [Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards).

## Related

* [Analytics and Dashboards](/automate-with-ion/analytics-and-dashboards)
* [Issues](/track-quality/issues)
* [Further Actions (CAPA)](/track-quality/further-actions)