managing-stacks

Managing Stacks

A stack is a pointer to your own compute environment where Celigo runs extension code -- the script hooks and connector wrappers that would otherwise run on Celigo's hosted JavaScript runtime. A stack holds the address and credentials of that environment, not the logic. At runtime, when a hook or wrapper is configured to use a stack, Celigo dispatches that function's execution to the stack instead of running it on its own managed runtime.

Concerns when managing stacks:

• Necessity -- most accounts never need a stack; the hosted runtime handles the vast majority of extension logic. A stack is for a real trigger (see the decision matrix).
• Type and config -- server (a self-hosted HTTP endpoint) or lambda (an AWS Lambda function), each with its own config block.
• Credentials -- a server carries an auto-generated systemToken; a lambda carries AWS keys. Both are masked in responses and demand credential discipline.
• References -- a stack does nothing on its own. It matters only once a hook (via _stackId on an export/import) or a wrapper connection (via _stackId) points at it.

Stacks are a resource type in their own right. They are referenced by script hooks and by wrapper connections.

The Stack Is the Runtime, Not the Code

The distinction the whole domain hangs on:

• The code is the logic: a hook (a JavaScript function on an export/import -- preMap, postSubmit, etc.) or a connector wrapper (the server-side JavaScript that implements a custom adaptor). Hook logic is a script resource; wrapper logic belongs to the wrapper connection.
• The stack is where that code runs. A hook or wrapper points at a stack via _stackId. When set, Celigo dispatches that function's execution to the stack instead of its managed runtime.

So "edit what the hook does" is script work; "change where the hook runs" (managed runtime <-> a stack, or one stack <-> another) is what touches _stackId. A stack is bring-your-own-compute: it supplies the environment, not the behavior.

Stack vs On-Premise Agent

Both put "your own infrastructure" in the loop, but for opposite reasons -- keep the boundary straight:

• A stack is about compute -- running your extension code (hooks/wrappers) on your server or Lambda.
• An on-premise agent is about connectivity -- a tunnel that lets Celigo reach private apps or networks behind your firewall (a database or app with no public endpoint).

"Run our code" -> stack. "Reach our private system" -> on-premise agent. A single flow can use both: an agent to reach a private database, and a stack to run a custom hook.

Quick Reference

Do You Need a Stack?

Default: no. Celigo's hosted JavaScript runtime runs hooks out of the box. Reach for a stack only on a real trigger:

server vs lambda

Neither is "better" -- it's a fit question based on where the team already runs infrastructure.

Minimum Required Fields

Every stack needs name and type. framework is twoDotZero (the only supported version). The rest depends on type:

• awsRegion is an enum (e.g. us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ...).
• functionName accepts a Lambda function name or full ARN.
• Both secrets (systemToken, secretAccessKey) are masked as ****** in responses.

Referencing a Stack (_stackId)

A stack is inert until something points at it:

• Hooks -- an export/import hook definition carries an optional _stackId alongside its _scriptId and function. Set it to dispatch that hook to the stack.
• Wrapper connections -- a wrapper-type connection sets _stackId to the stack whose server-side JavaScript implements the connection. Required by the connection form for standalone wrappers.

To confirm what actually runs on a stack, list its dependents (GET /v1/stacks/{id}/dependencies) -- the hooks and wrapper connections pointing at it.

Related Skills

• configuring-connections > Connection Types -- wrapper connections whose custom-connector code runs on a stack referenced by _stackId
• writing-scripts > How to Write a Script -- the hook logic dispatched to a stack; a hook points at one via _stackId
• managing-on-premise-agents -- the connectivity counterpart: a stack runs your code, an on-premise agent reaches your private systems
• getting-started > Core Concepts -- where stacks fit among the core resource types

How to Manage a Stack

1. Confirm you actually need one

Use the Do You Need a Stack? matrix. When a user asks "should I set up a stack for this hook," the honest first answer is usually "probably not -- the managed runtime handles it," then escalate only if heavier/specialized code, a compliance requirement, or a custom connector wrapper is genuinely in play. If the real need is reaching a private system, that's an on-premise agent, not a stack.

2. Choose the type

Use the server vs lambda matrix. Pick by where the team already runs infrastructure and how they want to operate it.

3. Check for existing stacks

Before creating a new one, look for a stack you can reuse:

celigo stacks list
celigo account search "stack"
celigo account search "<keyword related to the extension>"

4. Create the stack

Data blocks differ by type. Create the metadata; the runtime code is deployed and owned separately.

Example lambda-stack.json (use a placeholder here and supply the real key only in a local file or the UI):

5. Wire up authentication

• server -- the systemToken is generated on creation. Retrieve the unmasked value from the UI (the stack's "Show token" action) or via GET /v1/stacks/{id}/systemToken, then set it as the INTEGRATOR_EXTENSION_SYSTEM_TOKEN environment variable on every server that runs the extension code. To rotate it, use DELETE /v1/stacks/{id}/systemToken (the old token is invalidated immediately) and re-fetch the new one.
• lambda -- the AWS IAM user behind accessKeyId / secretAccessKey must have the lambda:InvokeFunction permission for the target function, and awsRegion must match where the function is deployed.

6. Point a hook or wrapper at the stack

The stack only runs code once referenced:

• Hook -- add _stackId to the hook definition on the export/import (alongside _scriptId and function). See writing-scripts > How to Write a Script for hook wiring.
• Wrapper connection -- set _stackId on the wrapper connection. See configuring-connections > Connection Types. A wrapper stack must expose a ping function so Celigo can health-check the connection.

7. Verify

Confirm the expected hooks and wrapper connections reference the stack before relying on it:

CLI Commands

UI/API alternatives worth knowing (no dedicated CLI subcommand -- use the UI or the API directly):

• Retrieve the server system token: GET /v1/stacks/{id}/systemToken (or "Show token" in the UI).
• Rotate the server system token: DELETE /v1/stacks/{id}/systemToken.
• List dependents: GET /v1/stacks/{id}/dependencies.

Pre-Submit Checklist

• Confirmed a stack is genuinely needed (heavier/specialized code, compliance, or a custom connector wrapper) -- not a routine hook the hosted runtime could handle.
• Correct type chosen (server vs lambda) based on where the team operates infrastructure.
• framework set to twoDotZero.
• server: hostURI is reachable over HTTPS; if ipRanges is set, Celigo's egress IPs are included.
• server: systemToken retrieved (not set) and configured as INTEGRATOR_EXTENSION_SYSTEM_TOKEN on the runtime.
• lambda: awsRegion, functionName, and AWS keys supplied; IAM user has lambda:InvokeFunction.
• No secret pasted into chat or a tracked file; AWS secretAccessKey entered via the UI or a local, untracked file only.
• The consuming hook (_stackId on the export/import hook) or wrapper connection (_stackId) actually points at this stack.
• Dependents verified so you know exactly what runs on the stack.

Gotchas

1. A stack is the runtime, not the code. It does nothing visible until a hook or wrapper references it via _stackId. Creating a stack alone changes no behavior.
2. Most accounts don't need one. Hooks run on Celigo's hosted JavaScript runtime by default. Only escalate to a stack on a real trigger.
3. The server systemToken is auto-generated -- you don't set it. Retrieve it via GET /v1/stacks/{id}/systemToken (or the UI), store it as INTEGRATOR_EXTENSION_SYSTEM_TOKEN on your server, and rotate with DELETE /v1/stacks/{id}/systemToken when needed.
4. Never paste secrets into chat. Both the systemToken and the AWS secretAccessKey are secrets returned masked as ******. A secret pasted into a logged conversation is compromised -- rotate it (recycle the system token, or rotate the AWS key) and re-enter it via the UI.
5. Don't write the masked ****** back as a real credential. secretAccessKey is write-only; to change it, send the real value. To keep the existing value, supply the real value again or edit through the UI -- never persist the literal ******.
6. PUT clears omitted optional fields. Updating a stack replaces it: for example, omitting framework on update clears a previously set value. GET the stack, modify, then PUT the full object.
7. twoDotZero is the only supported framework version. There is no other valid value.
8. lambda needs lambda:InvokeFunction. The IAM user must be allowed to invoke the function, functionName (name or ARN) must exist in the specified awsRegion, and language must match the deployed function.
9. Stack != on-premise agent. Don't create a stack to reach a private database -- that's connectivity, which is an on-premise agent's job. A stack is compute for your code.
10. Delete is a soft delete (30-day recycle bin), and dependents block it. A stack still referenced by hooks or wrapper connections cannot be deleted until those references are repointed or removed.

Common Errors