Write Celigo JavaScript hook scripts -- preSavePage, preMap, postMap, postSubmit, postResponseMap, filter, transform, branching, handleRequest. Use when creating or editing scripts, choosing the right hook point, understanding input/output data shapes, or debugging script behavior.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Write Celigo JavaScript hook scripts -- preSavePage, preMap, postMap, postSubmit, postResponseMap, filter, transform, branching, handleRequest. Use when creating or editing scripts, choosing the right hook point, understanding input/output data shapes, or debugging script behavior.
Writing Scripts
A script is a JavaScript function that runs at a specific hook point in the Celigo data pipeline. Scripts handle logic that expressions, filters, and visual mappings cannot -- complex conditionals, cross-record calculations, API calls within the pipeline, and custom routing.
Concerns when writing a script:
Choosing the right hook point -- which function type matches what you're trying to accomplish
Input/output contracts -- what options contains and what the function must return (array length rules are strict)
Expression alternative -- filter, transform, and output filter have expression-based alternatives that don't require a script; prefer expressions when possible
Available modules -- scripts can import three built-in modules: integrator-api (call Celigo APIs), dayjs (date/time manipulation), and sjcl (Stanford JavaScript Crypto Library for hashing/encryption)
One script, many functions -- a single script resource can contain multiple exported functions, each wired independently to different hook points
Used across flows, APIs, and tools.
Hook Points
Every script function runs at a specific point in the pipeline. Choose based on when you need to act and what data you need access to.
filter and transform have expression-based alternatives. Only use a script when the logic is too complex for an expression (multi-field conditionals, date math, external lookups).
Flow-Level Hook
Hook
Runs on
When
Input
Must return
postResponseMap
Page processor (flow/API/tool)
After response mapping merges results
options.postResponseMapData[], responseData[]
postResponseMapData[] (same length)
Configured on the flow's pageProcessors[] entry, not on the export/import. Plan this hook when building the resource, but wire it at the flow level.
Filter, transform, and output filter all have expression-based alternatives. Expressions are simpler to maintain and don't require a script resource. Use a script only when you need:
Multi-step logic or loops
Cross-record calculations (totals, deduplication)
External API calls via integrator-api
Error handling with retry data
Access to preMapData alongside postMapData
3. Check for existing scripts in the account
celigo scripts list
celigo scripts get <id> # content is only returned on individual GET
4. Create the script resource
Build the script with the correct function name matching the hook point. A single script can contain multiple functions.
Hook point is correct -- the function name matches the hook type being wired (e.g., preSavePage function for a hooks.preSavePage reference)
Return value matches contract -- batch hooks (preMap, postMap, postSubmit, postResponseMap) return arrays that match the input array length exactly
Error handling uses return pattern, not throw -- per-record errors use { errors: [...] } return values, not thrown exceptions (which fail the entire page)
Expression alternative considered -- filter, transform, and output filter can use expressions; only use a script when expressions cannot handle the logic
content field is included on PUT -- omitting content on update erases the code; always GET first, modify, then PUT
Debug mode is disabled after testing -- celigo scripts disable-debug <id> to avoid log noise in production
Gotchas
Array length contracts are strict.preMap, postMap, and postResponseMap return arrays MUST match the input array length. Returning fewer or more elements fails the entire page silently or with cryptic errors.
abort: true stops pagination, not the flow. In preSavePage, setting abort: true tells the export to stop generating new pages. It does NOT stop the flow or cancel processing of the current page's records.
Script content is not returned in list responses.celigo scripts list shows metadata only. You must celigo scripts get <id> to see the actual JavaScript code.
PUT erases content if omitted. Always GET the script first, modify, then PUT the complete object. The set command handles this automatically.
One script resource can contain multiple functions. A single script with both preSavePage and preMap functions can be wired to different resources by specifying the function name in each hook reference.
Throwing an exception fails the entire page. In batch hooks (preSavePage, preMap, postMap, postSubmit), an unhandled exception fails ALL records on that page, not just one. Use the error return pattern ({ errors: [...] }) for per-record errors.
postResponseMap lives on the flow, not the resource. The hook is configured on the pageProcessors[] entry in the flow/API/tool, even though it processes export or import response data.
filter/transform scripts replace expression-based alternatives. Wiring a script filter replaces any existing expression filter. They cannot coexist on the same resource.
console.log() output goes to script logs, not stdout. Use celigo scripts debug-logs to see output. Logs require debug mode to be enabled for debug-level messages.
Common Errors
Error / Symptom
Cause
Fix
"The number of elements in the return value must match the input"
Batch hook return array length differs from input
Ensure return array has exactly data.length (preMap) or postMapData.length (postMap) elements; use {} for skipped records
All records on a page fail with no per-record detail
Unhandled exception thrown in batch hook
Wrap logic in try/catch; return { errors: [...] } per record instead of throwing
Script content is empty after update
PUT omitted the content field
Always GET first, modify, then PUT the complete object (or use celigo scripts set)
abort: true set but flow keeps running
abort only stops pagination; current page still processes
This is expected behavior; use error returns or filter to skip individual records
Script not executing / no logs
Script not wired to any resource, or debug mode not enabled
Verify _scriptId + function reference on the export/import/flow; enable debug with celigo scripts enable-debug
"Function not found" or similar
function name in hook reference doesn't match an exported function in the script
Check the function name matches exactly (case-sensitive) between the hook config and the script's export
Filter always returns all/no records
Filter function returns truthy/falsy value instead of strict boolean
Return explicit true or false; avoid returning objects or undefined
postResponseMap not firing
Hook wired on the import/export instead of the flow's pageProcessors[] entry
Move the hook config to the pageProcessors[] entry in the flow, not the resource
