Automations Toolkit

LeanIX Automation Assistant

Comprehensive help for LeanIX Run Script automations: create, debug, design, optimize, and learn.

CRITICAL: API Access

All LeanIX API calls use MCP tools. No shell commands, no token exchange, no curl.

• Authentication is handled internally by the MCP server
• No bearer tokens need to be managed in the skill workflow
• No .mcp.json parsing is required — MCP handles credentials automatically

Anti-Patterns (Don't Do This)

Quick Reference

Trigger limitations:

• Relation is removed - The removed relation's other-end fact sheet id IS available at data.metadata.triggerData.previousRelatedFactSheetId (id only; best-effort/undocumented path — not part of the vendor's author API, may change). GraphQL-fetch by that id to read the removed fact sheet's fields. Reconciliation (or triggering on the target fact sheet) is optional, not required merely to identify the removed relation
• Lifecycle state reached - Nightly only
• Completion score changed - Fires on almost any edit

Common patterns:

// Safe edge/node access
const items = (fs.rel?.edges || []).map(e => e?.node).filter(Boolean);

// Idempotency check
if (newValue === currentValue) return {};

// Revision tracking
currentRev = mutJson?.data?.updateFactSheet?.factSheet?.rev ?? currentRev;

Greeting

When this skill is invoked, display this welcome message:

SAP LeanIX Automation Assistant

Welcome! I help you build, debug, and optimize LeanIX automations—using built-in actions when possible, scripts only when needed.

Reference Files (Progressive Disclosure)

Load these files only when needed for specific workflow steps:

Workflow

Step 0: Determine Intent

When invoked, use a two-tier AskUserQuestion flow to determine the user's intent:

IMPORTANT: AskUserQuestion supports 2-4 options only. Never pass more than 4 options. If more choices exist, group them or use a follow-up question.

Question 1: What type of help do you need?

Question 2 (based on selection):

Branch to the appropriate workflow based on final response.

Step 0.1: Verify Automations Toolset

Run immediately after determining intent (before any other MCP call):

Call mcp__leanix__list_automations(). This is a lightweight check that confirms the automations toolset is active.

If the call succeeds: Continue to the next step silently (no message needed).

If mcp__leanix__list_automations is not directly available (PTD may be enabled): Before concluding the toolset is missing, try the PTD proxy path — call_tool(tool_name='list_automations', arguments={}), or search_mcp_tools('automations') then call_tool. If that succeeds, PTD is working; continue silently.

If both the direct call and the PTD proxy path fail:

The automations toolset is optional and hidden by default. Display this message to the user:

Automation tools are not available. Your MCP connection is missing the automations toolset.

Fix: Add ?toolsets=inventory,automations to your MCP server URL.

Claude Code (OAuth):

claude mcp remove leanix
claude mcp add --transport http leanix "https://mcp.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,automations"

Claude Code (.mcp.json): Change the URL to:

https://{SUBDOMAIN}.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,automations

After updating, restart Claude Code and re-invoke /automations-toolkit.

Then stop the workflow — do not continue without automation tools, as deployment will fail.

If MCP is not connected at all (no mcp__leanix__* tools available):

No LeanIX MCP connection detected. This skill requires the LeanIX MCP server.

Quickest setup:

claude mcp add --transport http leanix "https://mcp.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,automations"

See MCP Setup for full instructions.

Step 0.5: Schema Reference Check (Optional)

After the user selects a workflow, optionally verify schema awareness:

Run: mcp__leanix__get_automation_schema()

This returns the live trigger, condition, and action type reference from the API. Compare against references/API-REFERENCE.md if discrepancies are suspected.

Key principle: Never block the user. Schema checking is informational only.

[Create New Automation] Workflow

Step 1: Workspace Context (Automatic)

MCP handles authentication and workspace connection automatically. No credential extraction or token exchange needed.

Verify connection:

1. Call mcp__leanix__get_overview() to confirm workspace access and get basic statistics (deprecated-but-working — still directly callable; may not appear in tool-discovery catalogs)

Get owner ID (when needed for deployment):

• Use mcp__leanix__search_users(email=...) to find a specific user's UUID
• Or use set_owner_to_current_user=True on update_automation (this flag exists ONLY on update_automation) to assign the authenticated user as owner. For create_automation, omit owner_id (it defaults to the authenticated user) or pass an explicit owner_id UUID

Display: Connected to LeanIX workspace - Ready for automatic deployment.

Step 2: Understand the Goal

Ask using AskUserQuestion:

"What do you want this automation to accomplish?"

Step 2.5: Evaluate Action Strategy

Decision Tree:

1. Does goal require reading data from OTHER fact sheets? → Script required
2. Does goal require modifying OTHER fact sheets? → Script required
3. Does goal require conditional logic based on related data? → Script required
4. Can goal be achieved with built-in actions? → Proceed to Step 3
5. Otherwise → Skip to Step 4 (Trigger Strategy for scripts)

Built-in Actions Available:

If built-in actions suffice → Step 3 If script needed → Step 4

Step 3: Configure Actions (Built-in Only)

Use AskUserQuestion with multiSelect to select actions, then gather parameters for each.

Email placeholders use triple braces: {{{factsheet.displayName}}}, {{{link.factsheet}}}

Action ordering: Use startsAfter to chain actions. For approvals, use onResolution: "ACCEPTED" or "REJECTED".

See API Reference for detailed action configuration.

After configuring → Select trigger → Step 7.5 (Deploy)

Step 4: Recommend Trigger Strategy

Goal → Trigger Mapping (Common Patterns):

Key insight: For the "Relation is removed" trigger, the removed relation's other-end fact sheet id IS delivered at data.metadata.triggerData.previousRelatedFactSheetId (note data.trigger itself does not exist — the trigger context lives under data.metadata.triggerData). Only the id string is provided, not the removed fact sheet's fields, so GraphQL-fetch by that id to read them. This is a best-effort/undocumented path (discoverable by inspecting the injected data; it may change). Reconciliation (or triggering on the target fact sheet) is a robust option for reading full fields but is not required merely to identify the removed relation.

See LeanIX Model for complete trigger reference.

Step 5: Gather Remaining Details

Collect:

1. Fact Sheet Type(s)
2. Tag IDs, role IDs, field names (use MCP to discover)
3. Business logic rules (tie-breaker, edge cases)
4. Whether GraphQL API calls are needed

Step 6: Find Similar Examples

Search examples/INDEX.md for patterns:

• tagging/ - Tag manipulation
• subscription-*/ - Subscription sync
• relation-*/ - Relation-based logic
• initiative-management/ - Multi-relation aggregation

Step 7: Generate Script

Critical Rules Checklist:

• main is exported directly (not via re-export or default export)
• main takes zero parameters (data and context are injected globals)
• If main is async, it contains at least one await
• No import statements — only fetch, data, context, JS built-ins
• Wrap relations in type fragments: ... on Application { relApplicationTo... }
• Track currentRev after each mutation
• Include idempotency checks
• Use throw new Error(...) for visible failures (not console.log — captured to stdout, not surfaced in UI)

Return Object Limitations: Can update description, name, tags, lifecycle, custom fields. Cannot update relations, subscriptions, or other fact sheets (use GraphQL).

See Templates for script templates.

Step 8: Provide Automation Setup

Document the configuration for manual setup if needed.

Step 7.5: Deploy Action-Only Automation

When no script needed, create automation directly via POST /templates. Requires name, description, factSheetType, ownerId, trigger, conditions, actions, and active: false.

See API Reference for action payload examples and complete DTO structure.

Step 8.5: Pre-Deployment Checklist

Before deploying, verify ALL items:

See API Reference — Ownership for details.

Step 9: Deploy Automation (Script Path)

Two MCP calls:

1. mcp__leanix__create_automation_script(name="Script Name", code=SCRIPT_CODE) — Create script, returns script ID
2. mcp__leanix__create_automation(name="Automation Name", template_json=TEMPLATE_JSON) — Create automation referencing script ID

Before deploying: Call mcp__leanix__get_automation_schema() to validate payload against live schema

Success: Report the automation name and ID. The user can find it in LeanIX Admin → Automations.

See API Reference for deployment details and error patterns.

Step 9.5: Verify Deployment

After deployment, verify the automation works:

1. Check deployment succeeded

   • Confirm automation appears in LeanIX Admin → Automations
   • Verify trigger and conditions are configured correctly

2. Test if possible

   • If safe to test: trigger the automation manually on a test fact sheet with mcp__leanix__trigger_automation(template_id, entity_ids=[…]). Confirm first — it is side-effecting and NOT idempotent (re-running re-runs the actions), so state what will run on how many fact sheets and get an OK. Also confirm the automation is active (an inactive one returns 202 but produces no runs).
   • The 202 means QUEUED, not executed — do NOT report success off it. Poll mcp__leanix__list_automation_runs(automation_ids=[id], fact_sheet_ids=[submitted], run_after=[just before trigger]) with backoff until the matched run count is stable across two consecutive polls, then mcp__leanix__get_automation_run(run_id) for per-action detail. Report per fact sheet by NAME.
   • A submitted fact sheet may produce no run for two silent reasons: automation inactive, or condition not met (e.g. WITH_TAGS). A manual run skips the trigger event entirely — you do NOT need to reproduce the triggering change — so it jumps straight to conditions + actions. Nothing stuck ever shows as IN_PROGRESS; zero rows in every state means it never ran, not that it's queued.
   • Verify expected outcome matches design

3. Review for edge cases Before marking complete, consider:

   • What happens if the automation triggers on itself? (idempotency)
   • What if related fact sheets don't exist?
   • What if values are already set correctly?
   • Can this be simpler?

Ask: "Would you like me to review edge cases before we finalize?"

Step 10: Ask for Refinements

Offer:

• Add edge case handling
• Add companion automation (for remove triggers)
• Generate additional scripts for multi-trigger scenarios

[Debug Failing Script] Workflow

Step 1: Collect Information

Request: script code, trigger config, observed behavior, error messages.

If the automation is already deployed, pull its run history first — it's the fastest source of truth for "what actually happened":

• mcp__leanix__list_automation_runs(automation_ids=[id], states=["FAILED"]) — find failed runs
• mcp__leanix__get_automation_run(run_id) — per-action outcomes and the error message on the failing action

A deployed automation with an active: true status but zero runs on fact sheets that should have triggered it points at a trigger/condition mismatch rather than a script bug.

Step 2: Automated Diagnostic Checks

Step 3: Provide Diagnosis

Generate diagnostic report with issues found and recommended fixes.

Step 4: Offer Corrected Script

Ask if user wants fully corrected script generated.

[Understand Capabilities] Workflow

Can automate:

• Update fields, tags on triggering fact sheet
• Query/update other fact sheets via GraphQL
• Manage subscriptions, relations, relation attributes
• Send webhooks, emails, create to-dos

Cannot automate:

• Scheduled triggers (use external schedulers)
• Access to "before" state
• Bulk operations on unrelated fact sheets
• User archive events

See LeanIX Model for detailed capabilities.

[Refactor/Optimize Script] Workflow

1. Collect current script and desired improvements
2. Check for: unnecessary API calls, missing idempotency, inefficient loops, missing error handling
3. Provide refactored version with explanations

[Convert Azure Function] Workflow

Key conversions:

For scheduled functions: Convert to event-driven, or keep external scheduler.

External Documentation

• references/CRITICAL-RULES.md - Critical rules, common errors, key patterns
• references/TEMPLATES.md - Script templates & GraphQL patterns
• references/LEANIX-MODEL.md - Triggers, actions, capabilities
• references/API-REFERENCE.md - API endpoints & deployment
• examples/INDEX.md - Production scripts

[Analyze Workspace Automations] Workflow

Audit existing automations, update descriptions, and standardize naming conventions.

Speed: Load references/WORKSPACE-ANALYSIS.md + references/NAMING-CONVENTION.md + call mcp__leanix__get_overview() (deprecated-but-working — still directly callable; may not appear in tool-discovery catalogs) + mcp__leanix__list_automations() all in one parallel message to avoid sequential round-trips.

See Workspace Analysis for the full workflow.

[Manage Existing Automations] Workflow

Transfer ownership, enable/disable, troubleshoot, or bulk update existing automations.

See Manage Automations for the full workflow.