netbox-asset-lifecycle

NetBox Asset Lifecycle

NetBox Asset Lifecycle は、機器の調達ライフサイクル（計画 → BOM → 発注書 → 出荷 → 設置）と、交換用の予備品在庫を追跡する、商用の NetBox Labs 機能（NetBox Cloud / NetBox Enterprise）です。NetBox DCIM ですでにモデル化している機器を基盤とします。計画済みのラック／デバイス／モジュール／ケーブルを部品表にまとめ、発注、出荷、受領、設置することで、各設置済みオブジェクトを、それを充当した出荷または予備品プールまで追跡できます。

Asset Lifecycle に関する知識は古くなっている可能性があります。 これは初期段階（0.x）の機能です。v0.3.0 はモデルと REST エンドポイントの名称を変更した破壊的変更を含むリリースであり、0.2.x 以前のすべてのリリースは評価専用でした。エンドポイント、フィールド、ステータスのルールは、今後も変更される可能性があります。事前学習済みの知識よりも情報の取得を優先し、コードを生成する前に実際の API を確認してください。

バージョンに関する注意： このスキルの対象は、NetBox 4.5.4–4.7 上のプラグイン v0.3.x（v0.3.1、2026-08-20）です。0.2.x からのアップグレードパスはありません。0.3.0 でマイグレーションが再初期化されました。0.2 から 0.3 への名称変更については、バージョンに関する注意を参照してください。

情報の取得元

取得元	URL / 方法	用途
Asset Lifecycle のドキュメント	https://netboxlabs.com/docs/asset-lifecycle/	機能、モデルごとのフィールドリファレンス、ワークフロー、リリース
リリースノート	.../asset-lifecycle/releases/	破壊的変更、NetBox の最小バージョン
NetBox DCIM モデル	https://netboxlabs.com/docs/netbox/models/dcim/	コアの Device/Rack/Module/Cable とタイプモデル
ライブ API スキーマ	GET /api/schema/（asset-lifecycle で絞り込み）	実行中のバージョンにおける正確なフィールド名とアクションエンドポイント
NetBox MCP / Platform MCP	設定されている場合は、asset-lifecycle のエンドポイントを一覧表示／確認	実際のエンドポイントとフィールドスキーマを確認

最初に：機能が利用可能か確認する

インスタンスで機能が有効になっていること、トークンにアクセス権があること、0.3 API を利用していることを確認してください。

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" \
  "$NETBOX_URL/api/plugins/asset-lifecycle/assets/?limit=1" | python -m json.tool

• ページ分割されたリストが返る（空の場合もあります）→ 機能が有効で、v0.3 以降です（assets/ が存在します）。
• assets/ が 404 で、boms/ が 200 → 0.2.x のインストールです。このスキルの前身で扱っていた bom-objects/ エンドポイントと spare_item フィールドが該当し、以下で説明する割り当て、アーカイブ、コネクターフィールドは存在しません。
• boms/ も 404 → 機能が有効になっていません。403 → トークンに asset-lifecycle オブジェクトの権限がありません。

---

対象範囲

このスキルでは、asset-lifecycle の REST/GraphQL API と、調達／予備品管理のワークフローを扱います。以下は対象外です。

• サイト／デバイス／IPAM のモデル化 → netbox-data-modeling を使用
• コアの REST/GraphQL パターン、認証、ページネーション、一括操作 → netbox-api-integration を使用
• 在庫の一括取り込み → netbox-diode を使用

前提条件： 調達する機器は、通常、タイプが割り当てられた status=planned のオブジェクトとして、すでに NetBox DCIM に存在している必要があります（Device の device_type、Rack の rack_type、Cable の type）。Asset Lifecycle は計画済みの Device/Rack を作成するものではなく、それらの調達と設置を追跡します。（例外は予備品から新しいオブジェクトを設置する場合です。）

API の規約

• ベース URL： /api/plugins/asset-lifecycle/
• 認証： Authorization: Bearer nbt_<key>.<secret>（v2 トークン。v1 の Token <key> も v5.0 まで引き続き使用できます）。標準の NetBox ページネーション（?limit=、?offset=）、?brief=true、?fields=、?q= による検索、__ によるフィルター検索がすべて適用されます。
• オブジェクト権限： モデルごとの標準的な view_*／add_*／change_*／delete_*（例：netbox_asset_lifecycle.change_bom）。アクションエンドポイント（generate/、install/）では、書き込みが有効なトークンも必要です。また、インストールの場合は、対象オブジェクトに対する対応する dcim.change_*／dcim.add_* 権限も必要です。
• ジェネリックリレーション（明細行／予備品／割り当て／資産が参照する機器）は、2 つのフィールドで記述します。*_type の ContentType（{"app_label": "dcim", "model": "devicetype"} または pk）と、整数の *_id です。統合フィールド item／assigned_object は読み取り専用です。
• ネストされた FK には、整数の pk を直接指定できます。
• variant は JSON オブジェクトであり、null にはなりません (0.3.1)。「バリアントなし」の場合は {} を送信するか、省略してください。空の属性は保存時に削除されるため、{"airflow": ""} は {} として保存されます。
• アーカイブ済みオブジェクトはデフォルトで返されます。?archived=false で絞り込んでください。

クイックリファレンス

エンドポイント（/api/plugins/asset-lifecycle/ 配下）	用途
boms/ · POST boms/<id>/generate/	BOM コンテナー。スコープルールをアセットと明細行に展開します
bom-scope-rules/	BOM のスコープを定義する包含／除外フィルタールール
bom-line-items/	タイプ＋バリアント＋数量の行（自動生成または手動）
assets/ · POST assets/<id>/install/	インスタンスごとの、計画オブジェクトと BOM を結び付ける中間テーブル。出荷品または予備品からインストールします
cable-types/	プラグイン固有のケーブルタイプ（type＋profile＋connector_a＋connector_b）
vendors/、vendor-accounts/	仕入先とアカウント
purchase-orders/ · GET purchase-orders/<id>/export-line-items/?format=	注文。明細行を json／csv／yaml としてエクスポートします
po-line-items/	BOM 明細行ごとの注文数量＋価格（PO が draft の間のみ編集可能）
couriers/、courier-accounts/	配送業者（UPS／FedEx／DHL は初期登録済み）とアカウント
shipments/、shipment-line-items/	配送と明細行（qty_shipped／qty_received）
spares-pools/、spare-items/ · POST spare-items/<id>/install/	在庫を確保します。予備品から新しい DCIM オブジェクトを作成します
spare-item-allocations/	プール＋アイテム＋バリアントごとの最小／最大在庫しきい値 (0.3)
status-transition-rules/ · GET .../status-choices/?object_type_id=	BOM／PO／Shipment 用の編集可能な FSM。初期ステータスも含みます

GraphQL：すべてのモデルは、コアタイプとともに /graphql/ でクエリできます。bom_list、purchase_order_list、shipment_list、asset_list、spare_item_list、spare_item_allocation_list などがあります。型名には AssetLifecycle の接頭辞が付きます (0.3.1)：AssetLifecycleBOM、AssetLifecyclePurchaseOrder、AssetLifecycleShipment、AssetLifecycleAsset、AssetLifecycleSpareItem、…

データモデル

オブジェクトグラフ全体、各モデルの全フィールド、ユニーク制約については、references/data-model.md を参照してください。リクエストの作成時やバリデーションエラーのデバッグ時に読み込んでください。

Vendor ─ VendorAccount
   │
BOM ─ BOMScopeRule / BOMLineItem / Asset       (BOM rolls planned DCIM objects up into line items;
   │                                             one Asset per matched planned object)
PurchaseOrder ─ POLineItem                     (PO requires a BOM + Vendor)
   │
Shipment ─ ShipmentLineItem                    (Shipment requires a PO + Courier + tracking_number)
   │
Asset.shipment  ◄── install from shipment      (records which delivery fulfilled the planned object)
Asset.spares_pool ◄── install from spare       (records which pool it was drawn from)

SparesPool ─ SpareItem / SpareItemAllocation   (reserve inventory + min/max stock thresholds)

BOM、PurchaseOrder、Shipment には、ルールで管理される status と archived フラグがあります。

ステータスと遷移ルール

BOM、PO、Shipmentのステータスを変更できるのは、一致するStatusTransitionRuleが存在する場合のみです。不正な遷移は400を返します（Cannot transition from X to Y）。from_statusが空欄のルールは初期ステータスルールです。オブジェクトをそのステータスで作成できることを示し、それ以外のステータスで作成すると400を返します（… is not a valid initial status）。SpareItem.statusは自由形式であり、ルールによる制約はありません。

モデル	ステータス値	デフォルトの初期ステータス
BOM	draft、approved、ordered、fulfilled、cancelled	draft
PurchaseOrder	draft、approved、ordered、fulfilled、cancelled	draft
Shipment	prepared、shipped、received、cancelled、returned、lost	prepared または shipped (0.3)
SpareItem（自由形式）	serviceable、damaged、missing	任意

デフォルトのルール：BOM/POはdraft ↔ approved ↔ ordered ↔ fulfilledの間で遷移します（さらにapproved ↔ fulfilledもあります）。キャンセルへの遷移はapproved/orderedからのみの一方向です。Shipmentはprepared ↔ shipped ↔ received、shipped ↔ lost、lost ↔ received、received ↔ returnedの間で遷移します。キャンセルへの遷移はprepared/shippedからのみの一方向です。デフォルトではdraft → ordered、draft → fulfilled、draft → cancelledへの遷移はありません。

# Discover valid status strings for an object type
GET status-transition-rules/status-choices/?object_type_id=<contenttype_id>

# Allow an otherwise-illegal jump by adding a rule first
POST status-transition-rules/
{"object_type": {"app_label":"netbox_asset_lifecycle","model":"purchaseorder"},
 "from_status": "draft", "to_status": "ordered", "allow_reverse": false}

# Allow shipments to be created directly as "received" (initial-status rule)
POST status-transition-rules/
{"object_type": {"app_label":"netbox_asset_lifecycle","model":"shipment"},
 "from_status": "", "to_status": "received"}

デフォルトの完全なルールセットとモデル固有のロック（BOMの「最新ではない」、POのorder_id、受領済みShipmentのサイト、アーカイブ済み）については、references/status-transitions.mdを参照してください。ステータス変更で400が返された場合に読み込んでください。

アクションエンドポイント（以前はUIのみだった手順）

生成、設置、エクスポートには0.2.0以降RESTエンドポイントがあり、受領は通常のフィールド編集で行います。影響を手作業で再現せず、これらを使用してください。これらのエンドポイントは、この機能が存在する目的である整合性（ロールアップの正確性、予備品の減算、Shipmentからオブジェクトへの追跡可能性）を確保します。

アクション	リクエスト	必要条件	戻り値
BOMを生成	POST boms/<id>/generate/（空のボディ）	change_bom；BOMがdraftで、有効なスコープルールが1件以上	BOM（last_generated、is_current=true）；それ以外は400
Shipmentから設置	POST assets/<id>/install/ {"shipment": <id>}	change_asset + dcim.change_<model>；Shipmentがreceivedで、このBOMのPOに属している；Assetが未設置	shipment + installedが設定されたAsset
予備品から設置	POST assets/<id>/install/ {"spare_item": <id>}	上記と同じ；予備品がserviceableで、quantity ≥ 1、item_type/item_id/variantが完全一致	spares_pool + installedが設定されたAsset；予備品のquantityが減算される；同時処理で在庫切れになった場合は409
予備品から新規オブジェクトを作成	POST spare-items/<id>/install/ {<DCIM object fields>}	change_spareitem + dcim.add_<model>；予備品がserviceableで、quantity ≥ 1；デバイス／ラック／モジュールのタイプのみ	201 + 新しいDCIMオブジェクト；予備品が減算される
PO明細をエクスポート	GET purchase-orders/<id>/export-line-items/?format=json	view_purchaseorder	ファイル本文（デフォルトはjson；csv、yaml）

REST経由の設置ではDCIMオブジェクトに変更を加えません。Assetをリンクし（予備品の場合は）在庫を消費します。その後、通常のPATCH /api/dcim/devices/<id>/ {"status": "staged", "serial": "..."}を実行してオブジェクト自体を更新してください。UIの設置フォームでは、1回の送信で両方が行われます。

受領はフィールド編集で行います。PATCH shipments/<id>/ {"status": "received", "site": <id>, "date_received": "..."}を実行します（receivedにするには、siteおよび／またはlocationが必須です）。続けて、各明細に対してPATCH shipment-line-items/<id>/ {"qty_received": N}を実行します。qty_receivedをqty_shippedより少なくすることは、不足や破損を記録する方法としてドキュメントに記載されています。UIの受領済みにするボタンは、同じ書き込みをまとめて行うフォームにすぎません。

グリーンフィールド調達ワークフロー

ペイロードと検証に関する注意事項を含む詳細な手順については、references/workflow-greenfield.md を参照してください。

1. ベンダー（アカウントは任意）

   POST vendors/          {"name": "Acme Networks", "code": "ACME"}
   POST vendor-accounts/  {"vendor": <vendor_id>, "account_number": "ACC-001"}
   

2. BOM + スコープルール → 生成 → 承認。 明細ではなくスコープルールを作成してください。BOM が draft を離れると、スコープルールと明細はロックされます。

   POST boms/             {"name": "DC1 Spine Refresh"}                       # status defaults to draft
   POST bom-scope-rules/  {"bom": <bom_id>, "action": "include",
                           "object_types": [{"app_label":"dcim","model":"device"}],
                           "parameters": {"site_id":[3], "role_id":[5], "status":["planned"]}}
   POST boms/<bom_id>/generate/
   GET  bom-line-items/?bom_id=<bom_id>                                       # collect line item ids
   PATCH boms/<bom_id>/   {"status": "approved"}
   

3. 発注書 + 発注明細（明細を編集できるのは draft の間だけです。ordered／fulfilled にするには order_id が必要です。currency が省略された場合、プラグイン設定の default_currency が適用されます）：

   POST purchase-orders/  {"vendor": <vendor_id>, "vendor_account": <acct_id>, "bom": <bom_id>, "currency": "USD"}
   POST po-line-items/    {"purchase_order": <po_id>, "bom_line_item": <bli_id>, "qty_ordered": 16, "unit_price": "1200.00"}
   PATCH purchase-orders/<po_id>/  {"status": "approved"}
   PATCH purchase-orders/<po_id>/  {"order_id": "PO-7788", "status": "ordered"}
   

4. 出荷 + 出荷明細（prepared または shipped として作成します。UPS／FedEx／DHL は初期登録済みです）：

   POST shipments/        {"purchase_order": <po_id>, "courier": <courier_id>, "tracking_number": "1Z...",
                           "status": "shipped", "site": <site_id>, "date_shipped": "2026-09-01", "date_expected": "2026-09-05"}
   POST shipment-line-items/  {"shipment": <ship_id>, "bom_line_item": <bli_id>, "qty_shipped": 16}
   

5. 受領： PATCH shipments/<ship_id>/ {"status": "received", "date_received": "..."} を実行し、続いて PATCH shipment-line-items/<id>/ {"qty_received": 16} を実行します。
6. 設置： BOM 上の各資産（GET assets/?bom_id=<bom_id>&installed__isnull=true）について、POST assets/<id>/install/ {"shipment": <ship_id>} を実行し、次に DCIM オブジェクト自体の status／serial を更新します。
7. 完了処理： 発注書と BOM を fulfilled にします。必要に応じて、出荷、発注書、BOM に対して PATCH … {"archived": true} を実行します。

ブラウンフィールド予備品ワークフロー

詳細については、references/workflow-sparing.md を参照してください。

POST spares-pools/  {"name": "HQ Cold Storage", "site": <site_id>, "location": <loc_id>}
POST spare-items/   {"pool": <pool_id>, "item_type": {"app_label":"dcim","model":"devicetype"},
                     "item_id": <devicetype_id>, "variant": {"airflow":"front-to-rear"},
                     "quantity": 5, "status": "serviceable"}
# Target stock level for that item in that pool (advisory; surfaces low/excess stock)
POST spare-item-allocations/  {"pool": <pool_id>, "item_type": {"app_label":"dcim","model":"devicetype"},
                     "item_id": <devicetype_id>, "variant": {"airflow":"front-to-rear"},
                     "min_quantity": 2, "max_quantity": 8}
GET  spare-item-allocations/?pool_id=<pool_id>     # read-only current_quantity / below_minimum / above_maximum / is_fulfilled

• 在庫監査の不一致を示すには、status を damaged／missing に設定します（自由入力）。
• シリアル番号付きの単品では、quantity=1 として serial／asset_tag を設定します（シリアル番号または asset_tag が設定されている状態で quantity >1 にすると拒否されます）。
• 在庫から、計画済みの故障ユニットを交換する： POST assets/<id>/install/ {"spare_item": <id>} — 予備品の数を減らし（0 になってもレコードは保持されます）、資産にプールを記録します。その後、DCIM オブジェクトのステータスを更新します。
• 予備品から新しいオブジェクトを設置する（BOM は不要）：POST spare-items/<id>/install/ {"name": "...", "site": <id>, "role": <id>, "status": "active"} — 予備品のタイプ、シリアル番号、asset tag、バリアントを使って Device／Rack／Module を作成します。この方法ではケーブルを設置できません。
• 割り当ての対象となるのは、完全に同じ variant を持つ serviceable アイテムのみです。プールには、アイテムとバリアントの組み合わせごとに 1 つの割り当てが保持されます。

アーカイブ (0.3)

BOM、PurchaseOrder、Shipment には、書き込み可能な archived ブール値があります。オブジェクトの処理が完了したら（通常は fulfilled／cancelled／received）、削除せずにリストビューから非表示にするためアーカイブします：PATCH boms/<id>/ {"archived": true}。false に戻すと解除できます。ルール：

• オブジェクトは archived: true の状態では作成できません。作成後にアーカイブしてください。
• アーカイブ中は、子オブジェクト（スコープルール、明細）への書き込みが拒否され、UI 上でもオブジェクトは読み取り専用になります。編集する前にアーカイブを解除してください。
• REST では、デフォルトでアーカイブ済みのオブジェクトもリストに返されます。UI のデフォルト表示を使うには ?archived=false を指定します。

アンチパターン

1. 0.2 時代のパス／フィールドを使用する。 bom-objects/ → assets/、アセットの spare_item → spares_pool です。どちらも 0.3 では 404／400 を返します。
2. 生成の代わりに明細項目を手作業で作成する。 スコープルールを作成し、POST boms/<id>/generate/ を実行してください。手動の明細項目は単発の場合のみ使用します。自動生成された行は変更できず、生成のたびに再構築されます。
3. インストールを偽装する。 assets/<id>/ {"shipment": …} を PATCH したり、spare-items/<id>/ quantity を手作業で減らしたりしないでください。代わりに assets/<id>/install/ を使用します。これは出荷品／スペアを検証し、在庫をアトミックに消費して、installed を記録します。インストールの代わりに DCIM オブジェクトを active に PATCH してはいけません。インストールの後に行ってください。
4. 必須の親を省略する。 PO には bom と vendor が必要です。Shipment には purchase_order、courier、tracking_number が必要です。明細項目には親と bom_line_item が必要です。
5. 不正なステータス遷移や初期ステータスを使用する。 draft→ordered、received として Shipment を作成する場合などは、デフォルトで 400 を返します。使用可能な値を確認するには status-choices/ を、新しい遷移や初期ステータスを許可するには status-transition-rules/ を使用してください。
6. PO が ordered になる前に発注する。 Shipment を作成する前に order_id を設定し、PO を ordered にしてください。UI では ordered の PO にのみ Create Shipment が表示されます。
7. ロックされた子オブジェクトを編集する。 スコープルールと BOM 明細項目は BOM が draft の間のみ書き込み可能です。PO 明細項目は PO が draft の間のみ書き込み可能です。親がアーカイブされると、すべての子オブジェクトがロックされます。ステータスを戻す（ルールで許可されている場合）か、先にアーカイブを解除してください。
8. 宛先なしで received にする。 site および／または location がなければ、Shipment は received にできず、400 を返します。
9. アカウント／ロケーション／日付の不一致。 vendor_account.vendor は PO の vendor と一致する必要があります。courier_account.courier は Shipment の courier と一致する必要があります。location.site は site と一致する必要があります。date_expected／date_received は date_shipped より前の日付にできません。
10. 一意性に関する落とし穴。 BOM の name、Vendor／Courier の name（設定されている場合は code も）、(vendor, account_number)、設定されている場合の (vendor, order_id)、(courier, tracking_number)、(purchase_order, bom_line_item)、SparesPool の name、SpareItem の asset_tag（グローバル）と (item_type, item_id, serial)、シリアル番号のない SpareItem の (pool, item_type, item_id, variant, status)、Allocation の (pool, item_type, item_id, variant)、CableType の (type, profile, connector_a, connector_b) は一意である必要があります。
11. 汎用リレーションに誤ったコンテンツタイプを指定する。 明細項目、スペア、割り当てはタイプモデル（dcim.devicetype／moduletype／racktype または netbox_asset_lifecycle.cabletype）を参照します。アセットはインスタンスモデル（dcim.device／rack／module／cable）を参照します。
12. インストール時のバリアント不一致。 スペアがアセットの要件を満たすのは、正規化後に item_type、item_id、variant が完全に一致する場合のみです。エアフローが設定された計画デバイスには、{"airflow":"front-to-rear"} のスペアを在庫登録してください。{} では一致しません。
13. 受け取りによって在庫が有効化されると思い込む。 受け取りでは有効化されません。アセットをリンクするには別途インストールが必要です。DCIM オブジェクトのステータスは自分で更新してください。

バージョンに関する注意

Plugin 0.3.1（2026-08-20）— NetBox 4.5.4–4.7

• Shipment の詳細画面に BOM が表示されます。
• GraphQL の型／列挙型に AssetLifecycle… のプレフィックスが付きます（既存の GraphQL クエリとの互換性を損なう変更です）。
• BOM 明細項目、スペア項目、割り当ての variant は null にできなくなりました。

Plugin 0.3.0（2026-06-29）— NetBox 4.5.4–4.6 — 破壊的変更

• マイグレーションを再初期化しました。0.2.x からのアップグレードはできません。以前のリリースは評価専用でした。
• BOMObject → Asset、REST の bom-objects/ → assets/。
• Asset.spare_item → Asset.spares_pool（消費したユニットではなく、プールを記録します）。
• 新機能：SpareItemAllocation（spare-item-allocations/、最小／最大しきい値）、default_currency プラグイン設定、CableType の connector_a／connector_b、複数の Shipment 初期ステータス（prepared または shipped）、BOM／PO／Shipment の archived。

Plugin 0.2.x（2026-06）— NetBox 4.5.3–4.6（評価専用）

• REST アクション boms/<id>/generate/、assets/<id>/install/（bom-objects/ として）、spare-items/<id>/install/；GraphQL API；PO 明細のエクスポート；スペア優先のインストール；下書きではない BOM ではスコープルールがロックされます；数量 0 でもスペアは保持されます。

参考資料

• references/data-model.md — オブジェクトグラフ全体、モデルごとのフィールド、制約、フィルター。リクエストの作成時や検証エラーの解析時に読み込んでください。
• references/status-transitions.md — デフォルトの遷移ルールと初期ステータスのルール一式、およびモデル固有の 400 ロックすべて。ステータス 400 が発生したときに読み込んでください。
• references/workflow-greenfield.md — ペイロード付きの調達ワークフロー全体の手順：生成、発注、出荷、受領、インストール、アーカイブ。
• references/workflow-sparing.md — スペアプール、割り当てと在庫アラート、監査、スペアからのインストール、スペアからの新規オブジェクト作成。