Workato Recipes

Workato Recipes Base Skill - Agent Instructions

This document provides foundational knowledge for AI agents to generate valid Workato recipe JSON. This is the base skill that connector-specific skills (stripe-recipes, salesforce-recipes, etc.) extend.

---

CRITICAL: Pre-Generation Checklist

For EXISTING projects (recipes already exist):

1. Read 1-2 existing .recipe.json files to understand project structure and patterns
2. Verify connection names - ask user for exact connection names in their workspace
3. Follow established folder structure - match where recipes and connections are organized

For GREENFIELD projects (no existing recipes):

1. Use skill templates as reference - see templates/ directory in each skill
2. Use standard file naming - {recipe_name}.recipe.json (lowercase, underscores for spaces)
3. Start recipe names with action verbs - "Create...", "Search...", "Update...", "Process..."
4. Ask user for connection names - exact names from their Workato workspace

ALWAYS (both scenarios):

1. Use descriptive UUIDs - {action}-{number} format (e.g., search-contact-001, return-success-005)
2. Use API endpoint triggers for testability (unless callable recipe is specifically needed)
3. Define all response codes upfront in the trigger (200, 400, 500 at minimum)

---

UUID Format (MANDATORY)

ALWAYS use descriptive UUIDs, regardless of what existing recipes in a project use:

search-contact-001
create-customer-002
if-found-003
return-success-004
return-error-005

NEVER use random hex UUIDs:

a1b2c3d4-e5f6-7890-abcd-ef1234567890  ← ANTI-PATTERN
11111111-1111-1111-1111-111111111111  ← ANTI-PATTERN

> NOTE: Recipes created in Workato's declarative UI have random hash UUIDs. This is a platform limitation, NOT a pattern to follow. When you see random UUIDs in existing recipes, do NOT copy them. Always use descriptive UUIDs for new recipes and actions.

---

Recipe JSON Structure (CRITICAL)

The code field is an OBJECT (the trigger itself), NOT an array wrapped in a recipe object.

Key points:

• code is the trigger object directly, not wrapped in recipe
• code is NOT an array - actions go inside code.block
• Trigger number starts at 0, not 1
• Trigger as should be "trigger" for callable recipes

See: [fundamentals/recipe-structure.md](fundamentals/recipe-structure.md) for full structure with examples.

---

Action Numbering (CRITICAL)

Every block must have a sequential number field:

| Block | Number | |-------|--------| | Trigger | 0 | | First action | 1 | | Second action | 2 | | ... | ... |

Non-sequential numbers cause "out of sequence" errors that block recipe activation. When modifying recipes, always renumber all actions sequentially.

---

Built-in Providers

The workato provider is built-in and should NOT be in the recipe's config array. Only include config entries for external connectors requiring authentication (e.g., salesforce, stripe, gmail).

---

Connection Configuration (CRITICAL)

DO NOT put config blocks inside actions. Connections are defined ONLY in the top-level config array. Actions reference connections implicitly through the provider field.

WRONG (config inside action):

{
  "provider": "gmail",
  "name": "adhoc_http",
  "config": {
    "account_id": {"name": "My Gmail"}
  }
}

CORRECT (top-level only):

{
  "code": { ... },
  "config": [
    {
      "keyword": "application",
      "provider": "gmail",
      "account_id": {"name": "My Gmail"}
    }
  ]
}

---

Filename Convention

Recipe filenames must match the recipe's name field, converted to lowercase with spaces replaced by underscores. Workato normalizes filenames on pull, so mismatches cause filename changes.

| Recipe Name | Correct Filename | |-------------|------------------| | "name": "Search Contact By Email" | search_contact_by_email.recipe.json | | "name": "Create Stripe Customer" | create_stripe_customer.recipe.json | | "name": "Handle Dialog Submit" | handle_dialog_submit.recipe.json |

---

CRITICAL: REST Connector Action Name

> WARNING: The rest provider MUST use make_request_v2 as its action name — NOT __adhoc_http_action. Using the wrong action name causes Workato to silently strip all input config on import. See [patterns/adhoc-http-actions.md](patterns/adhoc-http-actions.md) for the full make_request_v2 structure and examples.

---

Quick Reference

| Topic | Documentation | |-------|---------------| | Recipe Structure | [fundamentals/recipe-structure.md](fundamentals/recipe-structure.md) | | Config Section | [fundamentals/config-section.md](fundamentals/config-section.md) | | Datapill Syntax | [fundamentals/datapill-syntax.md](fundamentals/datapill-syntax.md) | | Variables & Lists | [patterns/variables-and-lists.md](patterns/variables-and-lists.md) | | If/Else | [control-flow/if-else.md](control-flow/if-else.md) | | Try/Catch | [control-flow/try-catch.md](control-flow/try-catch.md) | | Foreach Loops | [control-flow/foreach.md](control-flow/foreach.md) | | Repeat While Loops | [control-flow/repeat-while.md](control-flow/repeat-while.md) | | Stop Action | [control-flow/stop.md](control-flow/stop.md) | | API Endpoint Trigger | [triggers/api-endpoint.md](triggers/api-endpoint.md) | | Callable Recipe Trigger | [triggers/callable-recipe.md](triggers/callable-recipe.md) | | Messaging Topic Trigger | [triggers/messaging-topic.md](triggers/messaging-topic.md) | | Publish to Topic Action | [triggers/messaging-topic.md](triggers/messaging-topic.md) | | Adhoc HTTP Actions | [patterns/adhoc-http-actions.md](patterns/adhoc-http-actions.md) | | JWT Bearer Auth | [patterns/jwt-auth.md](patterns/jwt-auth.md) | | API Platform Artifacts | [patterns/api-platform-artifacts.md](patterns/api-platform-artifacts.md) |

---

Table of Contents

1. [Trigger Types](#trigger-types)
2. [Calling Other Recipes](#calling-other-recipes)
3. [Response Actions](#response-actions)
4. [Block Requirements](#block-requirements)
5. [Extended Schemas](#extended-schemas)
6. [Formula Syntax](#formula-syntax)

---

Trigger Types

Workato supports multiple trigger types. Choose based on how the recipe will be invoked.

API Endpoint Trigger (Recommended for Testing)

Use when: Recipe should be callable via external HTTP request (curl, webhooks, third-party systems).

Provider: workato_api_platform Action: receive_request

> RECOMMENDATION: Use API endpoint triggers for most recipes. They're easier to test via curl and more practical for real integrations than callable recipes. > > Note: API endpoint recipes require companion .api_endpoint.json and .api_group.json files in addition to the recipe JSON. See [patterns/api-platform-artifacts.md](patterns/api-platform-artifacts.md) for the complete artifact set and file formats.

Complete API Endpoint Example

{
  "number": 0,
  "provider": "workato_api_platform",
  "name": "receive_request",
  "as": "trigger",
  "keyword": "trigger",
  "input": {
    "request": {
      "content_type": "json",
      "schema": [
        {
          "name": "email",
          "label": "Email",
          "type": "string",
          "control_type": "text",
          "optional": false,
          "hint": "Customer email address"
        },
        {
          "name": "name",
          "label": "Name",
          "type": "string",
          "control_type": "text",
          "optional": false
        },
        {
          "name": "company",
          "label": "Company",
          "type": "string",
          "control_type": "text",
          "optional": true,
          "hint": "Optional company name"
        }
      ]
    },
    "response": {
      "content_type": "json",
      "responses": [
        {
          "name": "Success",
          "http_status_code": "200"
        },
        {
          "name": "Created",
          "http_status_code": "201"
        },
        {
          "name": "Bad Request",
          "http_status_code": "400"
        },
        {
          "name": "Server Error",
          "http_status_code": "500"
        }
      ]
    }
  },
  "extended_output_schema": [
    {
      "label": "Request",
      "name": "request",
      "type": "object",
      "properties": [
        {
          "name": "email",
          "label": "Email",
          "type": "string",
          "control_type": "text"
        },
        {
          "name": "name",
          "label": "Name",
          "type": "string",
          "control_type": "text"
        },
        {
          "name": "company",
          "label": "Company",
          "type": "string",
          "control_type": "text"
        }
      ]
    }
  ],
  "block": [
    // Actions go here
  ]
}

Request Schema Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Field identifier (used in datapills) | | label | Yes | Display label in UI | | type | Yes | Data type: string, integer, boolean, date, date_time | | control_type | Yes | UI control: text, number, checkbox, date, select | | optional | Yes | true for optional, false for required | | hint | No | Help text for the field |

Multiple Response Codes

Define all possible HTTP responses in the trigger. The return_response action references these by name:

"responses": [
  { "name": "Success", "http_status_code": "200" },
  { "name": "Created", "http_status_code": "201" },
  { "name": "Bad Request", "http_status_code": "400" },
  { "name": "Conflict", "http_status_code": "409" },
  { "name": "Server Error", "http_status_code": "500" }
]

Datapill Paths for Request Fields

Access request fields directly (no body wrapper):

"path": ["request", "email"]
"path": ["request", "name"]
"path": ["request", "company"]

WRONG:

"path": ["request", "body", "email"]

Testing with curl

curl -X POST "https://apim.workato.com/your-workspace/your-endpoint" \
  -H "API-TOKEN: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "name": "Test User"}'

See: [triggers/api-endpoint.md](triggers/api-endpoint.md)

Callable Recipe Trigger

Use when: Recipe should be called by other Workato recipes (internal).

Provider: workato_recipe_function Action: execute

{
  "provider": "workato_recipe_function",
  "name": "execute",
  "keyword": "trigger",
  "input": {
    "parameters_schema_json": "[...]",
    "result_schema_json": "[...]"
  }
}

See: [triggers/callable-recipe.md](triggers/callable-recipe.md)

Choosing a Trigger Type

| Scenario | Trigger Type | |----------|--------------| | External API access needed | API Endpoint | | Called by other recipes only | Callable Recipe | | React to messages from other recipes | Messaging Topic (subscriber) | | Receive external webhooks | Webhook | | Time-based execution | Scheduler |

---

Calling Other Recipes

When a recipe needs to call another callable recipe, use the workato_recipe_function provider with action type call.

CRITICAL: flowid Requires zipname

The flow_id object MUST include ALL fields, including zip_name.

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Recipe display name | | folder | Yes | Folder containing the recipe | | folder_full_path | Yes | Full path from Home | | zip_name | YES | Path to recipe JSON file |

> CRITICAL WARNING: Missing zip_name causes RECIPE MUTATION AT RUNTIME. Without zip_name, Workato will unpredictably modify the recipe's metadata during execution. This corruption persists and breaks all future invocations. The recipe will appear valid during import/testing but will corrupt itself when actually invoked. This is worse than a silent failure - it permanently corrupts the recipe.

WRONG (missing zip_name - WILL CORRUPT THE RECIPE):

"flow_id": {
  "name": "Search contact by email",
  "folder": "atomic-salesforce-recipes",
  "folder_full_path": "Home/atomic-salesforce-recipes"
}

CORRECT (includes zip_name):

"flow_id": {
  "name": "Search contact by email",
  "folder": "atomic-salesforce-recipes",
  "folder_full_path": "Home/atomic-salesforce-recipes",
  "zip_name": "atomic-salesforce-recipes/search_contact_by_email.recipe.json"
}

Complete call action example:

{
  "provider": "workato_recipe_function",
  "name": "call",
  "as": "call_search_contact",
  "keyword": "action",
  "input": {
    "flow_id": {
      "name": "Search contact by email",
      "folder": "atomic-salesforce-recipes",
      "folder_full_path": "Home/atomic-salesforce-recipes",
      "zip_name": "atomic-salesforce-recipes/search_contact_by_email.recipe.json"
    },
    "parameters": {
      "email": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"workato_api_platform\",\"line\":\"api_trigger\",\"path\":[\"request\",\"email\"]}')}"
    }
  }
}

---

Response Actions

Workato provides different actions for returning data based on the trigger type.

API Endpoint Response Action (return_response)

Use when: Recipe uses workato_api_platform trigger and needs to return HTTP response.

Provider: workato_api_platform Action: return_response

How pick_list Maps Response Names to HTTP Codes

The pick_list in extended_input_schema maps the response names (defined in trigger) to HTTP status codes:

"pick_list": [
  ["Success", "200"],      // "Success" from trigger → HTTP 200
  ["Created", "201"],      // "Created" from trigger → HTTP 201
  ["Bad Request", "400"],  // "Bad Request" from trigger → HTTP 400
  ["Server Error", "500"]  // "Server Error" from trigger → HTTP 500
]

CRITICAL: The first element (e.g., "Success") must match exactly the name field from the trigger's responses array.

Complete return_response Example

{
  "number": 5,
  "provider": "workato_api_platform",
  "name": "return_response",
  "as": "return_success",
  "keyword": "action",
  "uuid": "return-success-005",
  "input": {
    "http_status_code": "200",
    "response": {
      "customer_id": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"stripe\",\"line\":\"create_customer\",\"path\":[\"body\",\"id\"]}')}",
      "success": "true",
      "error_message": "=null"
    }
  },
  "extended_input_schema": [
    {
      "change_on_blur": true,
      "control_type": "select",
      "extends_schema": true,
      "label": "Response",
      "name": "http_status_code",
      "pick_list": [
        ["Success", "200"],
        ["Created", "201"],
        ["Bad Request", "400"],
        ["Server Error", "500"]
      ],
      "type": "string"
    },
    {
      "label": "Response body",
      "name": "response",
      "type": "object",
      "properties": [
        {
          "control_type": "text",
          "label": "Customer ID",
          "name": "customer_id",
          "type": "string"
        },
        {
          "control_type": "checkbox",
          "label": "Success",
          "name": "success",
          "type": "boolean"
        },
        {
          "control_type": "text",
          "label": "Error Message",
          "name": "error_message",
          "type": "string"
        }
      ]
    }
  ],
  "extended_output_schema": [
    {
      "change_on_blur": true,
      "control_type": "select",
      "extends_schema": true,
      "label": "Response",
      "name": "http_status_code",
      "pick_list": [
        ["Success", "200"],
        ["Created", "201"],
        ["Bad Request", "400"],
        ["Server Error", "500"]
      ],
      "type": "string"
    },
    {
      "label": "Response body",
      "name": "response",
      "type": "object",
      "properties": [
        {
          "control_type": "text",

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [workato-devs](https://github.com/workato-devs)
- **Source:** [workato-devs/recipe-skills](https://github.com/workato-devs/recipe-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.