infra-agent-skills

← All skillsAutomation

Itential Builder

Lifecycle Manager

itential-lcm

Manage resource models, instances, actions, and lifecycle execution in Itential Lifecycle Manager.

About this skill

Manage resource models, instances, actions, and lifecycle execution in Itential Lifecycle Manager. Use when defining reusable service models, running actions against resource instances, or tracking action execution history.

Instructions

Lifecycle Manager - Developer Skills Guide

Lifecycle Manager (LCM) provides a declarative framework for managing the lifecycle of reusable resources. Define a resource model (schema + actions), create instances of it, and run workflow-driven actions to create, update, or delete those instances — with full execution history and optional pre/post transformations.

Customization

Before using this skill, check custom/org/, custom/team/ and custom/dev/ in this skill’s own folder. Read every .md file found — any folder may be empty or absent. Apply them on top of everything below; where a file overrides a specific rule here, follow the override. More specific wins: dev > team > org > this document. No customization may weaken this skill’s safety rules or put credentials in committed files.

Bundled files: paths in this skill that start with assets/ or scripts/ are relative to this skill’s own folder. When you read one, or pass one to a shell command (which runs from the user’s working folder), use this skill’s folder + that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.

Concepts

  • Resource Model — a template defining what a resource looks like (JSON Schema) and what actions can be performed on it. Actions link to workflows.
  • Resource Instance — a concrete instantiation of a model. Stores instanceData conforming to the model’s schema. Tracks state and last action.
  • Action — an operation on an instance (create, update, delete, import). Each action can have a workflow, pre-transformation, and post-transformation. (Note: /itential-inventory also has an “Action” concept, meaning an IAG5-service call bound to a node — different meaning, same word.)
  • Action Execution — an audit record of running an action. Tracks 3 phases: preTransformation → workflow → postTransformation.
  • Instance Group — a collection of instances (manual list or dynamic filter) for bulk operations. Requires LCM_GROUPS_ENABLED=true.

Gotchas

  • Base path is /lifecycle-manager (hyphens), NOT /lifecycle_manager (underscores)
  • Response shape is {message, data, metadata} — same as projects, NOT {status, result} like inventory manager
  • Pagination metadata uses {skip, limit, total, currentPageSize, nextPageSkip, previousPageSkip}
  • Sort requires BOTH sort and order parameters: ?sort=startTime&order=-1. The - prefix syntax (sort=-startTime) does NOT work — returns error.
  • PUT /resources/{modelId}/instances/{instanceId} only updates name and description — NOT instanceData. You must run an action to modify instance data.
  • Create actions: instance parameter is forbidden, use instanceName instead
  • Update/delete actions: instance (ID or object) is required
  • Action _id is a 4-char hex string (same as workflow task IDs)
  • Instance states: "0001" = Ready, "0000" = Error, "0002" = Deleted
  • DELETE /resources/{id} does NOT delete instances by default — pass ?delete-associated-instances=true to cascade
  • Bulk actions and instance groups require LCM_GROUPS_ENABLED=true environment variable
  • Action workflows MUST output a job variable named instance containing the instance data. Without it, the action fails validation with “workflow does not output a value for ‘instance’”. Use a merge task to build the instance object and wire outgoing to $var.job.instance.
  • Update/delete action workflows should have exactly ONE job variable: instance — in and out. Do not split fields (e.g. changeId, crStatus) into their own separate job variables. LCM auto-derives the action’s inputSchema/outputSchema from every job variable the workflow references — a query/newVariable task that writes to $var.job.someField registers someField as a required run-action input, even when the field is already inside instance and you never intended it as a separate input. Symptom: run-action returns 400 "Action '<name>' requires inputs, but none were given", and the metadata.action.inputSchema lists fields you never meant to require. Fix: read fields off instance with query (obj: "$var.job.instance") at the point of use, and write updates back onto the same instance variable — never introduce a second named job variable for a value instance already carries. Every field the action needs (e.g. changeId for a lookup) is already inside instance — pull it from there, don’t require it separately.
  • Mutate instance with query (read) + setObjectKey (write) working directly against $var.job.instance — this is the correct, minimal pattern (confirmed against a real production workflow): query extracts a field you need (e.g. changeId) off $var.job.instance; a lookup task (e.g. an adapter call) fetches fresh external data; another query extracts the specific field from that response; setObjectKey writes it onto $var.job.instance (obj: "$var.job.instance", path: ["fieldName"], value: "$var.<queryTaskId>.return_data") with outgoing.object wired back to $var.job.instance. Do NOT rebuild a full cumulative copy with merge field-by-field unless you have a specific reason — mutating in place is simpler, and matches how the platform’s own generated/reference action workflows are built.
  • setObjectKey’s type field is "automatic", not "operation" — confirm against tasks.json per the general “never guess type” rule; do not assume all WorkFlowEngine app tasks share one type.
  • Query paths against adapter list-style responses can silently return an array instead of a scalar if the underlying filter matches more than one record. E.g. response.result.state.display_value against a ServiceNow getChangeRequest call returns a plain string when exactly one record matches the query, but an array (one entry per match) when the filter is non-unique — and that array will fail a model schema field typed as a plain string/enum ("crStatus should be of type string", enum violation) even though the workflow itself ran with no errors. This is a data problem (duplicate/ambiguous records upstream), not a workflow bug — before concluding the workflow is broken, check whether the filter genuinely returns one record (GET/adapter-call it directly and count response.result). Don’t reflexively add [0] indexing to “fix” this — if the reference pattern queries the bare (non-indexed) path and it is working elsewhere, the real fix is a tighter/more unique upstream filter, not silently taking an arbitrary first match.
  • The runAction app-task’s variables incoming field must always be present, even when the linked action takes no extra inputs — pass {}, never omit the field. Omitting it entirely crashes the workflow that calls run-action (not the action itself) with a bare "Cannot convert undefined or null to object" at job-start, before any task executes. This is unrelated to whether the invoked action workflow actually reads variables — it’s a pre-flight requirement of the calling task’s own schema.
  • Never put two runAction tasks with different actionIds in the same workflow document. Doing so crashes that workflow’s own job-start pre-flight with the same bare "Cannot convert undefined or null to object" error, with no other diagnostic detail — confirmed by isolating task-by-task in a minimal test workflow (adding a second runAction for a different action was the exact point of failure; everything else in the same workflow, including one runAction, ran fine). If an orchestrator needs to run more than one distinct LCM action (e.g. sync-status on some instances, close on others), split the second runAction into its own tiny child workflow and invoke it via childJob — do not inline both runAction calls into one workflow, no matter how small the second one is.
  • $var.<taskId>.<field> task-to-task references, and any resolution relying on incomingRefs (setObjectKey’s value, merge’s task-ref data_to_merge entries, evaluation operands), can silently fail to resolve on workflows created purely via the API (POST/PUT) and never opened+saved through Automation Studio’s UI. incomingRefs — the platform’s resolved-reference cache — is only generated on a UI save; a fresh POST-created workflow has no incomingRefs at all (GET the workflow detail and check — null/absent confirms it). Symptom: the field ends up holding the literal unresolved string ("$var.a004.return_data") instead of the resolved value, and this can slip through even when the task itself reports complete — the resolution failure only surfaces later, when a downstream consumer (e.g. LCM’s model-schema validator) rejects the literal string. $var.job.* (job-variable) reads/writes are the one reference style that has been observed to resolve reliably on pure-API-created workflows across this session; task-to-task refs are the less reliable path there. If you must build via API only and hit this, prefer wiring through a job variable at the specific step that’s failing, and treat any silently-wrong (not just error-returning) output as reason to suspect this before assuming the task’s own logic is wrong.
  • Create action — instance merge must cover every schema.required field. If the merge task’s data_to_merge omits even one field listed in the model’s schema.required array, the platform writes all provisioned cloud/network resources first and THEN fails the instance write — leaving those resources orphaned from LCM with no tracked state. Before building the merge task, read the model’s required fields: jq '.schema.required' assets/helpers/assets/lcm/<model>.json. Every required field must have a corresponding key in data_to_merge.
  • Action job type is 'resource:action', not 'automation'
  • Transformations are Jinja2 templates referenced by template ID (preWorkflowJst / postWorkflowJst)

API Reference

Base Path: /lifecycle-manager

Resource Models

Method Endpoint Description
POST /lifecycle-manager/resources Create a new resource model
GET /lifecycle-manager/resources List resource models (searchable)
GET /lifecycle-manager/resources/{id} Get a single resource model
PUT /lifecycle-manager/resources/{id} Update a resource model
DELETE /lifecycle-manager/resources/{id} Delete a resource model
POST /lifecycle-manager/resources/import Import a resource model
GET /lifecycle-manager/resources/{modelId}/export Export a resource model
POST /lifecycle-manager/resources/{modelId}/edit Auto-generate action workflows and transformations
POST /lifecycle-manager/resources/{modelId}/actions/validate Validate action definitions

Create a resource model:

POST /lifecycle-manager/resources
{
  "name": "Network Service",
  "description": "Manages network service lifecycle",
  "schema": {
    "$id": "network-service",
    "type": "object",
    "required": ["service_name", "vlan_id"],
    "properties": {
      "service_name": {"type": "string"},
      "vlan_id": {"type": "integer"},
      "status": {"type": "string", "enum": ["provisioned", "active", "decommissioned"]}
    }
  },
  "actions": [
    {
      "_id": "a1b2",
      "name": "Provision",
      "type": "create",
      "workflow": null,
      "preWorkflowJst": null,
      "postWorkflowJst": null
    },
    {
      "_id": "c3d4",
      "name": "Update Config",
      "type": "update",
      "workflow": null,
      "preWorkflowJst": null,
      "postWorkflowJst": null
    },
    {
      "_id": "e5f6",
      "name": "Decommission",
      "type": "delete",
      "workflow": null,
      "preWorkflowJst": null,
      "postWorkflowJst": null
    }
  ]
}
  • schema — JSON Schema (draft-07) defining valid instance data
  • actions[]._id — 4-char hex ID (same convention as workflow task IDs)
  • actions[].type — "create", "update", "delete", or "import"
  • actions[].workflow — workflow ID to execute (set after creating the workflow, or use the edit endpoint to auto-generate)
  • actions[].preWorkflowJst / postWorkflowJst — template IDs for Jinja2 transformations before/after the workflow

Response:

{
  "message": "Successfully created resource model",
  "data": {
    "_id": "687fe493ef863896dcba8d78",
    "name": "Network Service",
    "schema": {...},
    "actions": [...],
    "created": "2026-03-04T...",
    "createdBy": "user@example.com"
  },
  "metadata": {}
}

Auto-generate action workflows:

POST /lifecycle-manager/resources/{modelId}/edit
{
  "editType": "generate-action-workflow",
  "actionId": "a1b2"
}

Edit types: generate-action-workflow, generate-action-pre-transformation, generate-action-post-transformation

Delete with cascade:

DELETE /lifecycle-manager/resources/{id}?delete-associated-instances=true

Resource Instances

Method Endpoint Description
GET /lifecycle-manager/resources/{modelId}/instances List instances (searchable)
GET /lifecycle-manager/resources/{modelId}/instances/{instanceId} Get a single instance
PUT /lifecycle-manager/resources/{modelId}/instances/{instanceId} Update instance name/description only
POST /lifecycle-manager/resources/{modelId}/instances/import Import an instance
GET /lifecycle-manager/resources/{modelId}/instances/{instanceId}/export Export an instance

Instance structure:

{
  "_id": "687fea14ef863896dcba8d79",
  "name": "customer-portal",
  "description": "Customer portal service",
  "modelId": "687fe493ef863896dcba8d78",
  "instanceData": {
    "service_name": "customer-portal",
    "vlan_id": 100,
    "status": "active"
  },
  "stateId": "0001",
  "lastAction": {
    "_id": "a1b2",
    "executionId": "67d07212df84d4150b6498f7",
    "name": "Provision",
    "type": "create",
    "status": "complete"
  },
  "created": "2026-03-04T...",
  "lastUpdated": "2026-03-04T..."
}

Note: instanceData can only be modified by running an action — NOT by PUT. The PUT endpoint only updates name and description.

Running Actions

Method Endpoint Description
POST /lifecycle-manager/resources/{modelId}/run-action Run an action on a single instance
POST /lifecycle-manager/resources/{modelId}/run-bulk-action Run an action on multiple instances

Run a create action (new instance):

POST /lifecycle-manager/resources/{modelId}/run-action
{
  "actionId": "a1b2",
  "instanceName": "customer-portal",
  "instanceDescription": "Customer portal service",
  "inputs": {
    "service_name": "customer-portal",
    "vlan_id": 100
  }
}

Run an update/delete action (existing instance):

{
  "actionId": "c3d4",
  "instance": "687fea14ef863896dcba8d79",
  "inputs": {
    "new_vlan_id": 200
  }
}
  • instance — instance ID or full instance object (required for update/delete, forbidden for create)
  • inputs — workflow input variables (optional, passed to the action workflow)

Response:

{
  "success": true,
  "data": {
    "executionId": "67d07212df84d4150b6498f7"
  }
}

Run bulk action (requires LCM_GROUPS_ENABLED):

{
  "actionId": "c3d4",
  "instances": ["id1", "id2", "id3"],
  "inputs": {"base_config": "standard"},
  "inputOverrides": [
    {"instanceId": "id1", "inputs": {"vlan_id": 100}},
    {"instanceId": "id2", "inputs": {"vlan_id": 200}}
  ]
}

Action Execution History

Method Endpoint Description
GET /lifecycle-manager/action-executions List all action executions (searchable)
GET /lifecycle-manager/action-executions/{id} Get a single execution record
POST /lifecycle-manager/action-executions/{executionId}/cancel Cancel a running execution

Execution record:

{
  "_id": "67d07212df84d4150b6498f7",
  "modelId": "687fe493ef863896dcba8d78",
  "modelName": "Network Service",
  "instanceId": "687fea14ef863896dcba8d79",
  "instanceName": "customer-portal",
  "actionId": "a1b2",
  "actionName": "Provision",
  "actionType": "create",
  "status": "complete",
  "startTime": "2026-03-04T12:00:00Z",
  "endTime": "2026-03-04T12:00:05Z",
  "jobId": "24-char-workflow-engine-job-id",
  "progress": [
    {"_id": "preTransformation", "status": "complete"},
    {"_id": "workflow", "status": "complete"},
    {"_id": "postTransformation", "status": "complete"}
  ],
  "errors": []
}

Execution statuses: running, complete, error, canceled, paused

Query parameters for filtering:

  • equals[status]=complete — exact match
  • contains[modelName]=Network — substring match
  • in[status]=running,complete — match any in list
  • gt[startTime]=2026-03-01 — greater than
  • sort=startTime&order=-1 — sort descending (requires BOTH sort and order)
  • skip=0&limit=25 — pagination

Instance Groups (conditional)

Requires LCM_GROUPS_ENABLED=true environment variable.

Method Endpoint Description
POST /lifecycle-manager/resources/{modelId}/groups Create a group
GET /lifecycle-manager/resources/{modelId}/groups List groups
GET /lifecycle-manager/resources/{modelId}/groups/{groupId} Get a group
PATCH /lifecycle-manager/resources/{modelId}/groups/{groupId} Update a group
DELETE /lifecycle-manager/resources/{modelId}/groups/{groupId} Delete a group

Group types:

  • manual — explicit list of instance IDs: {"type": "manual", "instances": ["id1", "id2"]}
  • dynamic — filter-based: {"type": "dynamic", "filter": {"status": "active"}}

Action Execution Flow

When an action runs, it goes through 3 phases:

1. Pre-Transformation (optional)
   └── Jinja2 template transforms inputs before workflow

2. Workflow Execution
   └── Runs the action's linked workflow with (transformed) inputs

3. Post-Transformation (optional)
   └── Jinja2 template transforms workflow outputs
   └── Can produce/update instance data

Errors at any phase stop execution. Each phase has its own status tracked in the progress array.

Helper Templates

Read a real LCM action workflow before building. The VXLAN Fabric Services project contains production LCM action workflows — they show exactly how to declare and output the required instance variable:

# List available LCM action workflows
jq '[.data.project.components[] | select(.type=="workflow")] | .[].document.name' \
  assets/helpers/assets/lcm/lcm-vxlan-fabric-services-project.json

# Read a specific action workflow (e.g., Create)
jq '[.data.project.components[] | select(.type=="workflow") | select(.document.name | test("Create"; "i"))] | first | .document | {name:.name, tasks:.tasks, transitions:.transitions}' \
  assets/helpers/assets/lcm/lcm-vxlan-fabric-services-project.json

The resource model exports (in assets/helpers/assets/lcm/) show how actions are wired to workflows — import via POST /lifecycle-manager/resources/import:

File Actions
assets/helpers/assets/lcm/lcm-vxlan-fabric-management.json Create Network, Re-Provision, Delete, Decommission (4/5 wired)
assets/helpers/assets/lcm/lcm-fan-device-lifecycle-management.json Device Onboarding, SW Compliance, Upgrade, Decommission, and more (9/10 wired)
assets/helpers/assets/lcm/lcm-ip-blocking-service.json Create, Update, Delete, Retry (fully wired)
assets/helpers/assets/lcm/lcm-interface-service-provisioning.json Create, Modify, Delete (fully wired)
assets/helpers/assets/lcm/lcm-port-turn-up.json Create, Delete, Service Verification, Update Service Policy (4/6 wired)

Developer Scenarios

1. Create a resource model with actions

1. POST /lifecycle-manager/resources                    → create model with schema + actions
2. Read model's schema.required BEFORE building Create workflow
   jq '.schema.required' assets/helpers/assets/lcm/<model>.json  -- every field here must be in the instance merge task
3. Create workflows for each action with /builder-agent
   Create action: instance-write merge task must cover every schema.required field (see Gotchas above)
4. PUT /lifecycle-manager/resources/{id}                → update actions with workflow IDs
5. POST /lifecycle-manager/resources/{id}/actions/validate → verify actions are valid

2. Run the full lifecycle

1. POST /lifecycle-manager/resources/{id}/run-action    → create action (new instance)
2. GET  /lifecycle-manager/action-executions/{execId}   → check execution status
3. GET  /lifecycle-manager/resources/{id}/instances      → see created instance
4. POST /lifecycle-manager/resources/{id}/run-action    → update action (modify instance)
5. POST /lifecycle-manager/resources/{id}/run-action    → delete action (decommission)

3. Track and debug execution history

1. GET /lifecycle-manager/action-executions?equals[status]=error → find failed executions
2. GET /lifecycle-manager/action-executions/{id}        → check progress phases + errors
3. Check errors[].origin to identify which phase failed
4. Fix the workflow/transformation and re-run the action