function-creator

Function Creator

Create new Datex Studio functions or modify existing ones on a Datex Studio branch.

See also: db-query — $db predicate DSL and storage access patterns for flow code that reads/writes from *-storage.json components. function-creator owns the function lifecycle (dxs function generate / validate / dxs configuration upsert flow); db-query owns the $db predicate mechanics.

References

• ../datex-studio-shared/branch-setup.md -- Branch & connection selection (shared across skills)
• references/command-syntax.md -- All dxs function commands with examples
• references/flag-guide.md -- When/why/how for each flag
• references/code-patterns.md -- Common patterns for function code
• references/functions.md -- Function platform reference: purpose, file shape, configurationTypeId=9, parameter-descriptor boilerplate, UI→action bridge, runtime globals, invocation contract
• ../datex-studio-shared/context-navigation.md -- How to retrieve & navigate designer context responses

Dependencies

• requirements-gathering skill — invoked to produce a requirements brief if one doesn't already exist in the conversation context
• impact-analysis skill — invoked when modifying input/output parameters of an existing function

Workflow

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO
  |            |
 use it    invoke `requirements-gathering` skill
  |            |
  +-----+------+
        |
[determine intent: create or modify?]
        |
  +-----+-----+
  |             |
CREATE        MODIFY
  |             |
 determine    dxs function get <ref> --branch <id>
 ref name     extract code from nodes[0].stepConfig.executeCodeConfig.code
 + params     write to temp .ts file
  |             |
  +------+------+
         |
[Phase 2: Intellisense]
dxs function context <config.json> --branch <id>
         |
[Phase 3: Signature Safety -- modify only]
If input/output params are changing:
  invoke impact-analysis skill
  only continue if no callers or user approves
         |
[Phase 4: Code]
Write or update TypeScript code in temp .ts file
         |
[Phase 5: Generate + Validate + Upload]
dxs function generate ... --code-file <file.ts> -o <config.json>
dxs function validate <config.json> --branch <id>   # exits 0 even on errors — READ the output
dxs configuration upsert flow -D <config.json> --branch <id>

Phase Details

Phase 1: Setup + Requirements

1. Follow branch-setup.md for branch/connection selection
2. Check whether a requirements brief already exists in the conversation context (produced by requirements-gathering or another calling skill)
   • Requirements brief exists — use it. The brief provides the intent, expected inputs/outputs, and business rules.
   • No requirements brief exists — invoke the requirements-gathering skill first. This ensures the agent understands what the function should do (create) or what changes are needed (modify) before touching code.
3. Determine intent: create new or modify existing?

Create flow (continued): 4. Determine reference name (valid JS identifier — must end with _flow suffix, e.g., sum_flow, process_order_flow) 5. Determine input/output parameters from the requirements brief

Modify flow (continued): 4. Fetch the existing function: dxs function get <ref_name> --branch <id> 5. Extract the current code from nodes[0].stepConfig.executeCodeConfig.code in the response JSON 6. Write the code to a temporary .ts file for editing 7. Note the current input/output parameters for signature change detection

Phase 2: Intellisense

See context-navigation.md for the full guide on retrieving and reading context responses, including the backend vs frontend symbol filtering rules. To quickly confirm a $types.<Package>.* custom type or enum member exists (e.g. before referencing $types.Utilities.e_awi_scopes.Cartonization in flow code) without parsing the full context blob, use the nomenclature registry described there.

For create: Run dxs function generate --code-file <placeholder.ts> -r <name> -t "<title>" -d "<desc>" --in-param <params> --out-param <params> -o <config.json> with a placeholder code file (e.g., containing just // placeholder), then run context on the resulting JSON to get the type system before writing actual code.

For modify: The fetched config JSON from dxs function get can be saved to a file and used directly with the context command.

Retrieval:

dxs -O json function context <config.json> --branch <id>

Read defaultContext.imports to determine which $-symbols are actually available — not every symbol in appContext.vars is usable in backend function code. Look up type definitions in appContext.text for imported symbols only. The global_context provides ambient utilities ($utils, enums).

Phase 3: Signature Safety (modify only)

If the modification changes input or output parameters:

1. Invoke the impact-analysis skill with the function's reference name
2. If callers exist, present them and ask the user whether to proceed
3. If proceeding, the agent must update all affected callers after modifying the function

Phase 4: Code

Write or update the TypeScript code in a temp .ts file. Use the intellisense data from Phase 2 to:

• Reference other functions, datasources, reports, etc. with correct types
• Use $flow.inParams.* and $flow.outParams.* correctly
• Access runtime services ($utils, $services, etc.)

See code-patterns.md for common patterns.

Phase 5: Generate, Validate, Upload

# Generate the config (local file operation — does not take --branch)
dxs function generate \
  --code-file <file.ts> \
  -r <reference_name> \
  -t "<title>" \
  -d "<description>" \
  --in-param <name>:<type> \
  --out-param <name>:<type> \
  -o <config.json>

# Validate. NOTE: unlike `dxs configuration validate`, this command exits 0 even when it
# finds errors — a zero exit means "the command ran", NOT "the function is valid".
# Read the payload: proceed only on `status: "valid"`; a `validation_errors` list means stop.
dxs function validate <config.json> --branch <id>

# Upload
dxs configuration upsert flow -D <config.json> --branch <id>

dxs function validate does not gate on its exit code. dxs configuration validate and dxs datasource validate exit 1 when they report errors; dxs function validate still exits 0 and reports validation_errors in its output (verified against the CLI source, 0.4.18). An agent that has learned "validate fails loudly" from the other skills will read this command's success exit as a green light and upload a broken function. Always inspect the output, not the exit status. Full exit-code matrix: ../datex-studio-shared/configuration-roundtrip.md.

Naming Convention

• Reference names must be valid JS identifiers (start with letter/_/$, no spaces/hyphens)
• Must end with _flow suffix (e.g., sum_flow, validate_order_flow, boolean_array_to_mask_flow)
• Title (-t) is a human-readable display name — can differ from reference name

Common Mistakes

Mistake	Fix
Using return to set output	Assign to $flow.outParams.* instead — functions don't use return values
Wrong scoping on $datasources or $flows	Module code requires module prefix ($datasources.ModuleName.ds_name). App code referencing its own configs does not ($datasources.ds_name). Always check the appContext types from dxs function context to determine the correct path.
Changing params without checking callers	Always invoke impact-analysis skill first when modifying input/output params
Guessing available services from memory	Always run dxs -O json function context and read defaultContext.imports — see context-navigation.md.
Referencing a frontend-only symbol ($shell, $frontendFlows)	Functions are backend-only. If a symbol is not in defaultContext.imports, you cannot use it — see context-navigation.md.
Using $item instead of $entity	The expression variable is $entity in Datex Studio
Code file exceeding 512 KB	Split logic into multiple functions or extract helpers
New flow fails to save (DXS-API-500 / DbUpdateException) even though validate passes	Check description length first — over 256 characters produces exactly this error on every configuration type, and validate does not catch it (bisected 2026-08-13; see configuration-roundtrip.md). If the description is within the cap, fall back to the wide-signature bug observed 2026-08-11 (PrintManager, ~19 inParams + 8 outParams + code in one body): the single-shot create/update 500s while every subset saves fine — and a failed save deletes the flow from the branch. Workaround: compose incrementally — upsert a minimal body (referenceName + placeholder code, no params), then add inParams + code, then add outParams a few at a time, re-upserting each step; verify the final branch state with a fresh get afterwards.

---

After your edit, invoke post-edit-verification to surface description/JSON/schema violations. For a final review, invoke component-validator.