Name: managing-integrations
Author: celigo

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

<! TIER:1 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, 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: Organization and access grouping related work so it can be named, permissioned, and reported on as a unit. The integration boundary is the permission boundary . Plain vs Integration App customer built integrations you own end to end, vs template driven apps installed from the Marketplace. Hierarchy parent/child integrations for multi store, multi tenant, or per environment splits. Lifecycle and promotion cloning across environments and running the ILM workflow (snapshots, pulls, reverts) to evolve integrations safely. Composition what lives inside, and how to move a resource from one integration to another. Per integration knobs aliases and settings, which live on the integration record, and notification subscriptions and run statistics, which don't. What Lives Inside an Integration An integration is a container for the resources that do the work: Flows the body of the integration's automation; every flow belongs to exactly one integration (its integrationId ), and each is enabled or disabled independently. APIs HTTP endpoints the integration exposes to external callers. Tools reusable processing blocks invoked by flows, APIs, and AI agents. Registered connections, lookup caches and topics attached to the integration's lists (registration is organizational, not binding see Gotchas). Scripts JavaScript attached to the integration or its resources. Settings and custom forms the integration record holds the settings values ; a custom form controls their shape ([writing settings forms](../writing settings forms/SKILL.md)). Integration records carry no health counts the error and offline connection totals on the dashboard tiles aren't part of the integration API, so celigo integrations list can't rank by them. For "which of my integrations have problems," read celigo integrations errors <id (one row per flow: flowId , its open error count numError , and lastErrorAt ) and check offline on the connections in the record's registeredConnectionIds ( celigo connections list shows offline ). Plain Integrations vs Integration Apps Two flavors share the integration resource shape but behave differently: Plain integrations are built from scratch by the customer, who owns the structure entirely. Adding, removing, or modifying inner resources is normal CRUD, and cloning preserves the full structure. Integration Apps (IAs) are template driven integrations, typically installed from the Marketplace . IA resources carry a connectorId the only marker of an app: mode , install , installSteps and templateId appear on plain integrations too (clones and template installs carry them). 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. Cloning, snapshots, pulls, reverts, and ignore fields are for plain integrations: the platform refuses lifecycle calls on an Integration App ( not supported ) and refuses to clone resources installed from one. To run an Integration App in another environment, install it there from the Marketplace (one license covers every environment) and set up its connections and settings again; a few apps offer their own clone utility, so check the app's documentation. Add a store or tenant through the app's own Add store flow, not a clone. Operating an installed app its settings, what it locks, switching its flows, versions and updates, editions and licenses, uninstalling is in [references/integration apps.md](references/integration apps.md). Marketplace install and template upgrade operations are a separate concern from managing the integration record. Parent / Child Integrations 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 ). Quick Reference Add to Existing vs New Integration 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 Clone Decision Matrix Intent Clone type Notes Backup before a risky change A snapshot, not a clone ( celigo integrations create snapshot ) Same integration and ids; revert to it in the Revisions tab "A copy to play with", or a copy that won't be kept in sync CLI or API clone ( celigo integrations clone ), same or another environment Standalone: carries sourceId , but snapshots and pulls refuse it "Develop changes in sandbox" / "clone to prod" Cross environment clone through the UI clone flow Entry point to the ILM workflow (a CLI or API clone is standalone see below) Copy but keep future changes in sync UI clone (lifecycle linked) Enables pulls between the two; a standalone CLI or API clone can't pull Keep the integration in Git and promote files The CLI tree workflow, not a clone [references/cli tree workflow.md](references/cli tree workflow.md); promoted copies aren't lifecycle linked Cross environment clones remap connections via a connection map at clone time see the Reference Index. Moving a Resource Three Tiers Tier Resources How it changes integration Owned (movable) flows, APIs, Tools Move re homes it: a save with the target integrationId keeps id /history/errors (a flow must drop flowGroupingId in the same save) Registered (not owned) connections, lookup caches, Event Streams topics 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. Syncs can't move either: a sync stays in the integration it was created in, which must have been created with syncs: true . Whole integration relocation across accounts is the separate Integration transfer operation. Minimum Required Fields 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. readme (optional) long form notes, up to 51,200 characters. Write one only from the user's own content. A clone copies it, so update the copy's. syncs: true only for an integration that will hold syncs. It's fixed at creation: a sync created in any other integration is refused (422 integration not for sync ), and an update can't add or remove the flag ([building syncs](../building syncs/SKILL.md the sync integration)). Integration Apps are not created this way they are installed from the Marketplace. Reference Index Deep ILM detail lives in [references/lifecycle management.md](references/lifecycle management.md): Clone family & linked vs standalone clones why a pull can report "no changes to pull" Revisions snapshot / pull / revert semantics, diffs, and what a revert restores Ignore fields the specific fields per resource type (an export's http.body , a flow's disabled ) that pulls and reverts leave alone Connection remap on clone the connection map object, and replacing a connection after the clone Move vs clone vs transfer owned / registered / inherited resource tiers [references/cli tree workflow.md](references/cli tree workflow.md) covers the CLI's file tree workflow ( pull , status , diff , lint , push , promote , resolve ) for keeping an integration in Git and promoting it as files. Settings forms have their own skill: [writing settings forms](../writing settings forms/SKILL.md). Related Skills [building flows How to Build a Flow](../building flows/SKILL.md how to build a flow) flows are the body of an integration's automation [building syncs The sync integration](../building syncs/SKILL.md the sync integration) integrations created with syncs: true hold syncs, and can't be deleted while they do [configuring connections Quick Reference](../configuring connections/SKILL.md quick reference) connections are registered to integrations and remapped on cross environment clone [configuring topics](../configuring topics/SKILL.md) Event Streams topics are registered to integrations like connections and lookup caches [building apis Quick Reference](../building apis/SKILL.md quick reference) APIs live inside integrations [building tools Tool Concepts](../building tools/SKILL.md tool concepts) Tools live inside integrations [managing users Access Strategy Decision Matrix](../managing users/SKILL.md access strategy decision matrix) the integration boundary is the permission boundary; grant manage/monitor per integration [troubleshooting flows Diagnostic Workflow](../troubleshooting flows/SKILL.md diagnostic workflow) diagnosing the open errors celigo integrations errors reports per flow [using marketplace templates](../using marketplace templates/SKILL.md) Integration Apps install from the Marketplace as their own integration; templates seed a new one <! TIER:2 How to Manage Integrations 1. Discover existing integrations Before creating anything, understand the current state: celigo integrations list returns the records only no error counts. Use celigo integrations errors <id for open errors per flow, and celigo flows error summary <flowId to drill into one flow's steps. To count an integration's flows before a move or a delete, list them with celigo flows list integration <id include instances : without the flag, the instance flows of a multi instance (abstract) flow are left out. 2. Decide: add to an existing integration or create a new one Use the [Add to Existing vs New Integration]( ad