OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add celigo/ai --skill managing-integrations
Manage Celigo integrations -- the named containers that group flows, APIs, Tools, connections, scripts, and settings so a body of automation is organized, secured, and evolved as one unit. Covers plain integrations vs Integration Apps, parent/child hierarchies, cloning with connection remap, moving resources between integrations, notifications, aliases, and Integration Lifecycle Management (ILM) revisions/snapshots/pulls/reverts across environments. Use when creating, organizing, cloning, promoting, or versioning integrations, or deciding whether new work belongs in an existing integration or its own.
npx skills add celigo/ai --skill managing-integrations
An integration is a first-class Celigo resource that represents a named group of related resources -- flows, APIs, Tools, registered connections, scripts, settings, notification subscriptions, aliases, and revision history. It is the organizational layer that says "this body of automation goes together," typically because it serves a specific business purpose (the "Shopify-NetSuite integration", the "customer-onboarding integration"). The actual work is done by the resources inside; the integration coordinates how they are managed, deployed, and evolved.
Users may call integrations tiles, workspaces, or integration folders -- treat these as equivalent vocabulary for the same resource type.
Concerns when managing integrations:
An integration is a container for the resources that do the work:
Integration listings surface computed fields useful for "which of my integrations have problems": numFlows, numError (open errors across all flows), numRegisteredConnections, numOfflineConnections, and lastErrorAt (ISO timestamp of the most recent error). Rank by numError / numOfflineConnections to triage.
Two flavors share the integration resource shape but behave differently:
_connectorId; the template controls which flows exist, what settings are exposed, and how children are organized. Customer edits are bounded by the template, and the app can ship upgrades that propagate from the template author to every installed instance. Adding a flow to an IA may be limited to a "Custom flows" area.Marketplace install and template-upgrade operations are a separate concern from managing the integration record.
Some integrations support children: a parent integration with multiple child integrations underneath it. This shows up most often in multi-store / multi-tenant setups (one IA supporting several Shopify stores or business units, each a child) and in per-environment splits inside a single IA.
Children inherit structure from the parent (the flows, the settings schema, the connection requirements) but carry their own configuration values (the actual connections, settings values, and per-child flow customizations). Integration listings return both parent and child entries, so the full tree is visible.
Child integrations are generally available only when the parent is an Integration App. For a plain integration, use sibling integrations or per-flow naming instead (e.g. Order sync -- Store A, Order sync -- Store B).
Default: add to an existing integration. Spawning a new one per flow defeats the purpose of grouping. Reach for a new integration when:
| Situation | Choice |
|---|---|
| A different group of people must manage or monitor it (contractor scope, partner visibility, ops vs IT split) | New integration -- the boundary is the access boundary |
| The work is conceptually separate (different business problem, audience, lifecycle) | New integration |
| Installing from a Marketplace template | New integration (IAs come as their own integration) |
| An existing integration is at its scale ceiling (rare) | New integration |
| Same team, same access needs, related work | Add to existing |
| Intent | Clone type | Notes |
|---|---|---|
| "A copy to play with" / backup before risky changes | Same-environment clone | Parallel copy in the same environment |
| "Develop changes in sandbox" / "clone to prod" | Cross-environment clone | Entry point to the ILM workflow |
| Copy but keep future changes in sync | Clone (preserves clone-family lineage) | Enables pulls between the two |
| Copy with no intention of keeping in sync | Duplicate from scratch | Loses lineage; ILM unavailable |
Cross-environment clones remap connections via a connection map at clone time -- see the Reference Index.
| Tier | Resources | How it changes integration |
|---|---|---|
| Owned (movable) | flows, APIs, Tools | Move re-homes it: swaps _integrationId, preserves _id/history/errors (flows also clear _flowGroupingId) |
| Registered (not owned) | connections, lookup caches | Register/deregister to the integration's list (can belong to several at once) |
| Inherited (move the parent) | exports, imports, AI agents, guardrails | No per-step move -- move the parent flow/API/Tool |
Integration-App resources (_connectorId) cannot be freely moved. Whole-integration relocation across accounts is the separate Integration transfer operation.
Creating an integration requires at minimum:
name -- the display name; name it after the business purpose, not a single operation.description (optional) -- helpful context for the team.Integration Apps are not created this way -- they are installed from the Marketplace.
Deep ILM detail lives in references/lifecycle-management.md:
snapshot / pull / revert semantics, diffs, and auto-snapshotsflow.*, export.*, import.*, connection.*) that stay per-environmentnumErrorBefore creating anything, understand the current state:
Review the computed fields (numFlows, numError, numRegisteredConnections, numOfflineConnections, lastErrorAt) to spot integrations that need attention.
Use the Add-to-Existing vs New Integration matrix. The key question is almost always about access: do the people who will manage or monitor this work differ from the people who already have access to an existing integration? If yes, it needs its own integration so Custom permissions can be granted independently. If no, add it to the existing one.
Name it after the business purpose, not a single operation. Integration Apps are not created here -- install them from the Marketplace instead.
Build the inner resources bottom-up (connections, then exports/imports, then flows/APIs/Tools) using their own skills. To change which integration a resource belongs to:
_id, history, and errors while swapping _integrationId). Moving is done in the Celigo UI or via the public API -- not via celigo integrations update, which only mutates the parent record.configuring-connections).To develop safely or promote work, clone the integration into another environment. Cloning copies the integration record, its flows, APIs, Tools, registered connections, scripts, and settings, and joins the copy to the original's clone family.
{"<oldConnectionId>": "<newConnectionId>"}). This is the only place the binding change can happen -- see the Reference Index.Cloning and connection remap are performed in the Celigo UI or via the public API. (The flow-level equivalent, celigo flows clone, is documented in building-flows and uses the same connectionMap.)
Run the git-style ILM workflow to evolve integrations across environments:
Configure ignore fields first so environment-specific values (URLs, sandbox vs prod IDs) do not cross during a pull. These operations run in the Celigo UI's Revisions tab or via the public API. See references/lifecycle-management.md for full semantics.
These features live on the integration record and are managed in the Celigo UI or via the public API:
_id. Use them when scripts must reference resources by name, because _ids change when an integration is cloned to a new environment but aliases can stay stable.Deleting removes the integration and is destructive -- confirm nothing is still running and that the resources inside are no longer needed. Prefer moving resources out first if any should be kept.
UI / API alternatives. The CRUD CLI mutates only the integration record. Operations that touch the integration's inside resources or lifecycle are performed in the Celigo UI or via the public API, not the CRUD CLI:
Before creating, cloning, or promoting an integration, verify:
name describing the business purpose, not a single operation_connectionId that must point at a target-environment connection_id/history), not clone, when the same resource should change integrationsEverything up to date -- no changes to pull even with real edits. Check for a standalone source before debugging a "no changes" pull. It cannot be linked after the fact -- recreate it via the UI clone flow.{"<oldConnectionId>": "<newConnectionId>"}) during the clone. Updating the integration afterward cannot remap connections on the inner flows/exports/imports -- celigo integrations update only mutates the parent record._connectionId on an export/import is what actually binds a connection to work. Register/deregister never changes which connections the inner resources use._id, history, and errors and just swaps _integrationId (flows also clear _flowGroupingId). If the user says "move," "reassign," or "relocate," do not clone._connectorId cannot be freely moved or restructured; their shape and upgrades come from the connector/template author. Custom additions may be limited to a "Custom flows" area.| Error / Symptom | Likely Cause | Fix |
|---|---|---|
Pull reports Everything up to date -- no changes to pull (but edits exist) | Source clone is standalone, not lifecycle-linked | Recreate the clone through the Celigo UI clone flow; standalone clones cannot be linked after the fact |
clone must be linked to source integration on snapshot | Snapshot attempted on a standalone clone | Use a lifecycle-linked clone (created via the UI clone flow) |
| Pull stops with conflicts | Both sides changed the same fields | Resolve manually in the Celigo UI Revisions tab |
| Cloned flows still point at the source environment's connections | Connection map not supplied (or wrong IDs) at clone time | Re-clone with a connection map linking each old _connectionId to the target-environment connection |
| Environment-specific values overwritten by a pull | Those field paths are not in the integration's ignore fields | Add the paths (e.g. connection.*, export.*) to ignore fields, then re-pull |
| Cannot move a flow/API/Tool into an integration | Resource is Integration-App-owned (_connectorId set) | IA resources are managed by the connector; use a Custom-flows area or a plain integration |
403 Forbidden on integration edit | Token lacks manage/admin access to that integration | Use a token with manage or admin access (see managing-users) |
404 Not Found on integration get/update | Wrong integration _id, or it was deleted | Verify the ID with celigo integrations list |
| Integration listing is missing integrations you expect | Token has Custom access and only sees granted integrations | Use an admin/owner token, or grant Custom access to those integrations (see managing-users) |