Managing Integrations

<!-- 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, 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:

• 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 -- notifications, aliases, analytics, and settings that live on the integration record itself.

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; each is enabled/disabled independently.
• APIs -- HTTP endpoints the integration exposes to external callers.
• Tools -- reusable processing blocks invoked by flows, APIs, and AI agents.
• Registered connections -- connections attached to the integration's connection list (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.

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.

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 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.

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:

Clone Decision Matrix

Cross-environment clones remap connections via a connection map at clone time -- see the Reference Index.

Moving a Resource -- Three Tiers

Integration-App resources (_connectorId) cannot be freely moved. 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.

Integration Apps are not created this way -- they are installed from the Marketplace.

Reference Index

Deep ILM detail lives in 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 auto-snapshots
• Ignore fields -- per-resource-type fields (flow.*, export.*, import.*, connection.*) that stay per-environment
• Connection remap on clone -- the connection-map object and why a post-clone update cannot remap
• Move vs clone vs transfer -- owned / registered / inherited resource tiers

Related Skills

• building-flows > How to Build a Flow -- flows are the body of an integration's automation
• configuring-connections > Quick Reference -- connections are registered to integrations and remapped on cross-environment clone
• building-apis > Quick Reference -- APIs live inside integrations
• building-tools > Tool Concepts -- Tools live inside integrations