Uipath API Workflow

UiPath API Workflow Assistant

<!--skill-flavor:surface-summary:start-->

Build, run, and publish UiPath API Workflows: JSON conforming to CNCF Serverless Workflow DSL 1.0.0 with UiPath activity extensions. Workflows run through @uipath/api-workflow-executor and uip api-workflow run, and package as Type: "Api" projects through uip solution pack.

<!--skill-flavor:surface-summary:end-->

<!--skill-flavor:host-command-contract:start-->

<!--skill-flavor:host-command-contract:end-->

TDD gate — read first (rule 22). For create/edit requests, check <project>/evals/ beside Workflow.json, never at workspace or solution root. If absent, Evaluations is off: do not ask about tests or loop mode; author normally. If present, stop before authoring and ask whether existing rows remain/change or empty tests should be added, and whether to run/retry until all pass or author once. After both answers, declare schemas, write/update evals first, then author. A request not to ask skips these questions, not runtime consent; run rows only when requested. Later behavior changes require asking whether affected expectations should change.

When to Use This Skill

Use for API workflow JSON creation/editing and activities including Sequence, Assign, JavaScript, If, ForEach, DoWhile, Break, TryCatch, Wait, Response, HTTP Request, and connector activities. Use the connector and testing references for Studio Web connector workflows and project evals/ layouts.

<!--skill-flavor:surface-lifecycle-scope:start-->

• Local runs, validation, build/packaging, publishing

<!--skill-flavor:surface-lifecycle-scope:end-->

• User wants to handle a file in an API workflow — take a file input, send a file as base64 to an API, turn a base64 payload back into a file, or asks about JobAttachment, $helpers.file, serializeData(), --input-file / --output-dir. See references/files-and-base64.md
• Starting a workflow from a connector event (Slack button clicked, new Outlook calendar entry), or inspecting/changing an existing trigger (call: "UiPath.IntSvcEvent"). See references/trigger-authoring-guide.md

<!--skill-flavor:surface-operations-scope:start-->

• Operating published workflows

<!--skill-flavor:surface-operations-scope:end-->

Do not use for .flow Maestro flows (uipath-maestro-flow), .xaml or coded RPA (uipath-rpa), coded agents (uipath-agents), or Coded Web Apps (uipath-coded-apps). API-workflow evals are only evals/ beside Workflow.json using evals/<scope>/eval-sets/; evals/eval-sets/ is for low-code agents and Flow evals for uipath-maestro-flow.

Core Principles

0. Escalate judgment-based forks before building. If a connection is unavailable, no curated activity exists, an undocumented HTTP fallback is needed, an assumed input is missing, or structurally different workflows are plausible, perform only shared discovery, then stop with trade-offs and a recommendation. Do not build every branch. Mechanical choices need no escalation.
1. Know before writing. Read an existing workflow before editing and the relevant template before creating.

<!--skill-flavor:runtime-validation-contract:start-->

2. Start minimal, iterate to correct. Add one activity at a time. Run with --no-auth --output json after each addition. Fix what breaks. Repeat.
3. Validate before running. uip api-workflow validate is autonomous/offline. run is runtime validation, may access HTTP or connections, and requires consent.

<!--skill-flavor:runtime-validation-contract:end-->

4. Fix by category: Structure > Expression > Activity Config > Logic.

Critical Rules

1. Workflow JSON. Top level has document with dsl: "1.0.0", evaluate with language: "javascript" and mode: "strict", and do containing one root sequence. Root sequence names may vary; read the file. See references/workflow-file-format.md.

2. WorkflowStart. It is first in the root sequence, hydrates variable defaults into $context.variables, forwards inputs to $input, and must not be removed, renamed, or modified. Only it uses isTransparent: true.

3. Activity objects and keys. Each activity is one single-key object in a do array. Keys are globally unique, including wrapper suffixes such as #Wrapper, #Then, #Else, and #Body.

4. Exports. Every activity should export output. Assign uses { ...$context, variables: { ...$context.variables, ...$output } }; all others use { ...$context, outputs: { ...$context?.outputs, "<ActivityKey>": $output } }. See references/expressions-and-context.md.

<!--skill-flavor:designer-literal-runtime-comparison:start-->

5. Literal expressions. In Assign set, Response, If when, and variable contexts, string literals must be expressions such as "${'literal'}", because Studio Web rewrites a bare "literal" into "${literal}" on save and that fails at runtime; numbers, booleans, and references need no wrapping. Connector bodyParameters, queryParameters, and pathParameters instead use bare literals; references remain expressions. See references/connector-activity-discovery.md and references/troubleshooting.md.

<!--skill-flavor:designer-literal-runtime-comparison:end-->

6. Assign. Each Assign sets exactly one variable. Studio Web collapses multi-key set; use sequential Assign activities and merge each single key through the variables export.

7. If. Use If_N#Wrapper containing If_N, If_N#Then, and If_N#Else. Both branches end with then: "exit"; when is wrapped in ${...}. See references/control-flow-patterns.md.

8. Loops. ForEach and DoWhile require #Body. ForEach uses index-aware accumulation, resetting on iteration 0; DoWhile uses simple accumulation. each and at are plain names, not expressions.

9. DoWhile. for.in is always "${ [1] }"; doWhile controls repetition. The body must update the condition variable or the loop may be infinite.

10. Nested loops. Use distinct iterator and index names for each loop.

11. Loop/catch bindings. Declare for.each, for.at, and catch.as without $, but reference them in expressions/scripts with $: "row" binds $row, "idx" binds $idx, and "err" binds $err. Omitting $ causes an undefined-name error.

12. Break. It exits only the innermost loop and is valid only inside #Body. Put it inside an If; break must be string "true", with then: "exit" and set: "${$input}". To exit nested loops, set a flag and check it in the outer loop. See references/control-flow-patterns.md.

13. Workflow inputs. Use $workflow.input.<name>, never $input.<name> from a non-first activity; $input is current task input and may be prior output.

14. JavaScript. Scripts read $context, $workflow, and $input as globals and must return a value. Keep standard Studio Web run.script.arguments scaffolding: "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"; runtime ignores it.

15. Response. markJobAsFailed is a sibling of response. Always use then: "end"; then: "exit" is for branches/loops. Object responses use one expression, e.g. "${{ key: $context.variables.value }}", not independently interpolated fields. Single values may use "${$context.outputs.Activity}" or "${'done'}". ${ { ... } } and ${{ ... }} are both valid; stay consistent.

<!--skill-flavor:response-roundtrip-validation:start-->

- **On-disk is authoritative.** After Studio Web saves, treat disk as authoritative and rerun `uip api-workflow run --no-auth` after reapplying needed workarounds.

<!--skill-flavor:response-roundtrip-validation:end-->

16. Connectors and HTTP are registry-generated only. Run uip api-workflow registry resolve then stub; never guess uiPathActivityTypeId, metadata.configuration, activity kind, endpoint, SlotKey, or ExportBucketKey; use stub output verbatim.

• A keyword resolve miss is not proof of no curated activity because it AND-matches tokens. Identify product/vendor with uip is connectors list --filter, then enumerate with uip is activities list <connector-key> before fallback.
• IntSvc/vendor activities require successful uip is connections ping <uuid>. If listing is empty/fails, try unfiltered listing, then --all-folders, and ping another matching connection.
• If none ping successfully, stop and ask whether to continue with explicit placeholder consent or wait for a fixed connection. Never silently choose.
• Never put replacement sentinels in with.connectionId, connectionResourceId, or an HTTP URL. Re-stub with a real value before writing.
• After every stub, check required fields using resource description or stub inputs, then re-stub with --inputs if needed.
• Connector parameters use flat dotted keys and bare literals; do not use ${'literal'}.
• Do not use UiPath.Http with a vendor connection UUID. IntSvc results are wrapped; read $context.outputs.<ExportBucketKey>.content.<field>.

<!--skill-flavor:connector-solution-registration:start-->

• In Solutions mode, sync IntSvc bindings with uip api-workflow bindings sync --workflow <Workflow.json> and refresh with uip solution resources refresh --solution-folder <path>. Skip for HTTP, non-connectors, and standalone projects.

<!--skill-flavor:connector-solution-registration:end-->

• See references/connector-activity-discovery.md for the discovery flow, field-shape rules, and multipart.

16a. A connector-event trigger is a separate catalog, a separate activity shape, and a second artifact. When the workflow must start from an event (Slack button clicked, new Outlook calendar entry), run uip api-workflow registry resolve "<keyword>" --kind trigger then registry stub — never hand-author. Place the stub in exactly one slot: the root Sequence's do array, directly after WorkflowStart (do[0].Sequence_1.do[1]) — never inside an If / ForEach / TryCatch, never after another activity, never a second trigger. validate rejects a misplaced or second trigger. A GenericTrigger needs --object-name. Full flow, filter syntax, anti-patterns: references/trigger-authoring-guide.md.

<!--skill-flavor:trigger-binding-registration:start-->

- **Run `uip api-workflow bindings sync` after every trigger add or edit.** It writes the `EventTrigger` entry in `bindings_v2.json` that registers the Orchestrator event trigger on deploy. **Without it the workflow validates, packs, publishes and deploys clean — and never fires.** No gate catches this. In Solutions mode follow with `uip solution resources refresh` (rule 16).

<!--skill-flavor:trigger-binding-registration:end-->

<!--skill-flavor:trigger-debug-contract:start-->

- **A `webhooks` trigger cannot run locally without input.** `uip api-workflow run` replays a live event only for `polling` (side-effecting under rule 21); for either mode, `--input-arguments` shaped like the event payload exercises the rest of the workflow offline.

<!--skill-flavor:trigger-debug-contract:end-->

<!--skill-flavor:runtime-invocation-io:start-->

17. CLI input. Pass JSON as a string: --input-arguments '{"key":"value"}'; invalid JSON exits 1.

18. CLI output. Parse with --output json. Success: { "Result": "Success", "Code": "WorkflowRun", "Data": {...} }; failure: { "Result": "Failure", "Message": "...", "Instructions": "..." } with exit 1.

<!--skill-flavor:runtime-invocation-io:end-->

<!--skill-flavor:project-creation:start-->

19. Project creation and publishing. Scaffold with uip api-workflow init <name>; do not hand-assemble project files. Project commands include build <projectDir> and pack <projectDir> <outputDir>. Use uip solution pack and uip solution publish; there is no uip api-workflow publish. Solution type is "Api".

19a. Init shape and registration. Run uip api-workflow init <name> --output json inside the solution directory. It creates project.uiproj, Workflow.json, entry-points.json, and bindings_v2.json, and registers the project in the nearest .uipx. Use --skip-solution-registration only when explicitly requested for a standalone CLI/local project. Always create a full project, never a lone workflow file. Do not use solution projects add/remove or change existing project IDs. For legacy project.json, initialize a fresh sibling and move content into its Workflow.json, or convert in place; see references/troubleshooting.md. Runtime success does not prove Studio Web compatibility; init-produced shape does.

<!--skill-flavor:project-creation:end-->

20. Static validation. Run uip api-workflow validate <Workflow.json> --output json as the last autonomous command in every author/edit cycle. On Result: "Failure", read Instructions, fix the activity at its JSON path, and repeat until Data.Status: "Valid". Prioritize semantic-tail errors over duplicate oneOf noise.

<!--skill-flavor:runtime-validation-limit:start-->

Validation catches malformed JSON, unknown types, required-field errors, bad evaluate settings, duplicate/empty variables, and empty task lists; not broken connections, wrong resource IDs, runtime expression errors, unwrapped literals, or multi-key Assign sets — those need `uip api-workflow run` once the user consents.

<!--skill-flavor:runtime-validation-limit:end-->

<!--skill-flavor:runtime-execution-consent:start-->

21. Runtime consent. Never run uip api-workflow run without explicit consent. After validation, ask whether to skip, run --no-auth, or run with auth. Recommend --no-auth for control-flow-only workflows and HTTP with ImplicitConnection; recommend authenticated execution only for IntSvc after confirming real side effects. Authenticated calls may send emails, create tickets, or upload files. Loop-mode consent authorizes eval rows with --no-auth, but authenticated connector runs still require explicit consent. This gates only uip api-workflow run, never uip solution pack/publish: a build/package/publish request proceeds without the run question; a local run is a separate request, done only when asked.

<!--skill-flavor:runtime-execution-consent:end-->

22. TDD gate. Check <project>/evals/ on every create/edit. Without it, do not offer tests, create the folder, or mention loop mode. With it, stop before modifying Workflow.json or evals and ask whether existing cases change or new cases are added, and whether to run/retry until all pass or author once. If rows exist, report their count and summarize each; if empty, propose 2–3 cases. After answers, declare input.schema and output.schema, update evals, author, then run rows only in loop mode or hand over in author-once mode. Behavior changes require identifying affected rows and asking whether expectations should change. A request not to ask keeps existing tests and does not authorize runtime. See references/testing-and-evals.md §3.

23. Files are references, not bytes — and base64 is a file too. File inputs and outputs are JobAttachment references ({ ID, FullName, MimeType, Metadata? }) to Orchestrator blobs; $workflow.input.<file> is never the bytes.

    • The two activities. Both are run.script tasks identified by their $helpers.file.* call (what validate checks): File to Base64 returns a new reference containing base64 text; Base64 to File returns a binary reference. The script must be exactly one return expression and nothing else. Studio Web silently drops preceding/trailing statements, a second argument, or an extra option key; validate catches only extra statements, so an extra argument or key can still break the activity. Put preprocessing in a separate JavaScript activity. See references/files-and-base64.md for exact shapes and examples.
    • Reading results. Use $context.outputs.<Key>.output.
    • Inlining content. Use <ref>.serializeData() directly in an HTTP body or Response field; it is a deferred-read marker, so do not store it or use it in script logic. Nested in a JSON body, it works only for a base64 reference (the File to Base64 output); nesting a binary file's marker or a bare reference is a send-time error. Send a binary file as the whole body or convert it first.
    • Naming. fileName and mimeType apply only to a raw base64 string. References keep their name, and the engine sniffs type from bytes; a .txt round-trip can therefore become extensionless.
    • Running. Both helpers need Orchestrator blob storage:

<!--skill-flavor:file-run-cli:start-->

`uip api-workflow run --no-auth` refuses such a workflow up front; run it signed in (`uip login`, no `--no-auth`) — it still needs the rule-21 "yes". Pass local files with `--input-file <name>=<path>` (uploaded, arriving as `$workflow.input.<name>`), collect returned files with `--output-dir <dir>` (each reference in the output gains a `LocalPath`), and `--folder-key <guid>` if the tenant's Attachments API requires a folder. In the printed output the CLI PascalCases keys (`ID` → `Id`).

<!--skill-flavor:file-run-cli:end-->

Shapes, worked examples, and pitfalls: [references/files-and-base64.md](references/files-and-base64.md).