Unit 0: Environment Setup

Hands-On Session (45 minutes)

Learning Objectives

  • Successfully deploy Salesforce metadata and seed data
  • Configure Workato connection and start recipes
  • Verify end-to-end connectivity
  • Troubleshoot common setup issues

Step 1: Run the Setup Script (15 min)

Copy and paste the appropriate command for your operating system. The script clones the repository, checks for required prerequisites (Git, Node.js, make), installs any that are missing, and sets up the Salesforce CLI.

1.1 Run relevant setup script for your machine

Mac/Linux 

curl -fsSL https://raw.githubusercontent.com/workato-devs/dewy-resort/main/bootstrap.sh | bash

Windows 

powershell -ExecutionPolicy Bypass -Command "Invoke-Expression (curl https://raw.githubusercontent.com/workato-devs/dewy-resort/main/bootstrap.ps1 -UseBasicParsing)"
Windows Manual Setup (Alternative) — if you prefer not to run the bootstrap script

Install each dependency via Scoop:

# Install Scoop if not already installed
irm get.scoop.sh | iex

# Install dependencies
scoop install git
scoop bucket add versions
scoop install versions/nodejs20
scoop install make
scoop bucket add workato-devs https://github.com/workato-devs/scoop-bucket
scoop install wk

# Verify all tools
git --version          # Any recent version
node --version         # Must show v20.x.x
make --version         # Any version
wk version             # Any version

Then clone the repo manually:

git clone https://github.com/workato-devs/dewy-resort.git
cd dewy-resort

Once the script completes, change into the project directory:

cd dewy-resort

Watch for any errors and flag a facilitator or assistant for help.

1.2 Verify CLIs 

make status

This checks that the Workato CLI (wk) and Salesforce CLI (sf) are both installed and shows their authentication status.

If wk is not found: Install it now — brew install workato-devs/tap/wk (macOS/Linux) or scoop install wk (Windows).

CHECKPOINT: make status shows both CLIs installed

Windows note: If make status shows an interactive “Reinstall anyway? [y/N]” prompt, press N and Enter — the Salesforce CLI is already installed. Verify directly with sf --version.

1.3 Create an .env file

The app/ directory includes a .env.example file with placeholder values for all of the application’s environment variables. Copy it to app/.env:

Mac/Linux 

cp app/.env.example app/.env

Windows 

Copy-Item -Path app\.env.example -Destination app\.env

Important: This .env file will be used throughout the workshop. Future setup steps will have you update its values as you configure each service.

1.4 Initialize Local Database

Windows users: Confirm node --version shows v20.x.x before running npm install. If you see v24+ or v26+, run scoop reset nodejs20 first. Native modules (bcrypt, better-sqlite3) will fail silently on newer Node versions without Visual Studio Build Tools.

cd app
npm install
npm run db:setup

Expected Output:

Database initialized successfully
Tables created: users, conversations, messages, devices...

Navigate back to the dewy-resort folder:

cd ..

CHECKPOINT: app/.env file exists with placeholder values

Step 2: Initialize CLIs & Deploy Salesforce Metadata (10 min)

2.1 Verify CLIs

From the dewy-resort directory, verify that both CLIs are available:

make setup

This checks for the Workato CLI (wk) and installs the Salesforce CLI (sf) if needed.

2.2 Authenticate to Salesforce 

sf org login web --alias myDevOrg

A browser window will open. Log in to your Salesforce Developer Edition org.

Tip: If you have multiple Salesforce accounts, make sure to use the correct username for your Developer Edition org (the one you noted during pre-workshop setup).

2.3 Deploy Metadata + Seed Data 

make sf-deploy org=myDevOrg

Expected Output:

Deploying Salesforce metadata to myDevOrg...
[x] Deployed 4 custom objects
[x] Deployed Lightning application
[x] Assigned permission set
[x] Imported seed data (23 accounts, 24 contacts, 10 rooms)

2.4 Verify in Salesforce 

sf org open --target-org myDevOrg
  1. Click App Launcher (9 dots, top left)
  2. Search for “Dewy Hotel Management”
  3. Click Hotel Rooms tab
  4. Verify room records appear

If the list appears empty: Don’t worry—Salesforce defaults to “Recently Viewed” which only shows records you’ve opened. The data is there. Use the list view search box or global search and type “Oceanview” to confirm hotel room records exist.

CHECKPOINT: Hotel room records visible in Salesforce

Step 3: Configure Workato (10 min)

3.1 Get Workato API Token

  1. Log in to your Workato Developer Edition
  2. Go to Workspace Admin -> API Clients -> Client roles [https://app.trial.workato.com/members/api/clients]
  3. Click Create Client Role tab
  4. Set permissions:
    • Projects tab -> Project Assets — select: Projects & folders, Connections, Recipes, Skills, MCP servers, Recipe Versions, Jobs
    • Projects tab -> Recipe Lifecycle Management — select: Recipe lifecycle management, Export manifests
    • Tools tab -> Workspace data — select: Environment properties
    • Tools tab -> API Platform — select: API portal, Collections & endpoints, Clients & access profiles
    • Admin tab -> Workspace Details — select: Workspace details
    • Admin tab -> Developer API clients — select: API Clients, API client roles
  5. Click Save Changes
  6. Click API Clients tab [https://app.trial.workato.com/members/api/roles]
  7. Click Create API Client button
  8. Enter “My CLI Client” in the Name field
  9. Select “New client role” from the Client Role dropdown
  10. Select “All Projects” in the Project Access drop-down menu
  11. Click Create Client
  12. Copy the token (you won’t see it again)

3.2 Add Token to Environment

First create the project-root .env from its template. This file is separate from app/.env — it is read only by the wk CLI:

Mac/Linux 

cp .env.example .env

Windows 

Copy-Item -Path .env.example -Destination .env

Then open the project-root .env (not app/.env) and paste the token you just copied:

WORKATO_API_TOKEN=your_token_here

3.3 Authenticate and Deploy Recipes 

make workato-login

This reads the token from .env and creates an authenticated CLI profile. Verify with wk auth status.

Next, initialize the local project and push all recipes to your workspace:

make workato-init
make push

Expected output: A list of .recipe.json files with created status. Lint warnings are expected and will not block the push.

3.4 Configure Salesforce Connector in Workato

  1. Go to Projects → Workspace Connections
  2. Click the Salesforce connection
  3. Click Connect
  4. Authenticate to your Salesforce Developer Edition org
  5. WARNING: DO NOT rename the connection

3.5 Configure Stripe Connection (Optional)

  1. Go to Projects → Workspace Connections
  2. Click the Stripe connection
  3. Click Connect
  4. Select API key as the authentication type
  5. Get your Stripe Secret API Key:
    • Open the Stripe Dashboard in a new tab
    • Stripe is in Test mode by default when you don’t fill out a profile. You must be in Sandbox mode:
      • Click your account drop-down menu (upper left)
      • Select “Switch to Sandbox” → choose your sandbox environment
      • Close any pop-ups
    • Click the “Developers” toolbar (bottom of page)
    • Select “API keys”
    • Under “Standard keys”, find the Secret key
    • Click Reveal test key to show the full key
    • Copy the key (starts with sk_test_)
  6. Paste the Secret API Key into Workato’s connection field
  7. Click Connect to complete authentication
  8. WARNING: DO NOT rename the connection

Always use test mode keys for workshop environments. Never use live/production keys (sk_live_).

3.6 Start Recipes 

make start-recipes

NOTE: If you did not set up or activate Stripe, some Stripe recipes will fail to start — that’s expected.

CHECKPOINT: All Salesforce recipes showing “Running” status

A Salesforce recipe stayed "Inactive"? (rare)

Occasionally a recipe with a dynamic SOQL query won’t pick up the Salesforce connection on its own. If any remain Inactive after make start-recipes:

  1. On the Recipes page, use the Inactive filter to find them (searching behalf surfaces the usual culprits).
  2. Open each one → Connections tab → under “Showing active connections” click your Salesforce connection so the red “Requires connection” warning clears.
  3. Re-run make start-recipes.

3.7 Set Up API Platform 

make setup-api

This creates two API collections (dewy-resort-guest and dewy-resort-manager), their endpoints, and an API client with credentials written to app/.env.

3.8 Enable API Endpoints 

make enable-api-endpoints

This activates all API endpoints so they can receive traffic. All recipes must be running first.

3.9 Set Up MCP Servers 

make setup-mcp

This creates two MCP servers (dewy-resort-guest and dewy-resort-manager) and writes the MCP URLs and tokens to app/.env.

CHECKPOINT: API endpoints enabled, MCP servers created, app/.env populated with URLs and tokens

Step 4: Verify End-to-End (5 min)

4.1 Start the Application

macOS / Linux 

app/scripts/dev-tools/server.sh start

Windows

The server.sh script is macOS/Linux only. On Windows, start the dev server directly:

cd app
npm run dev

Leave this terminal running and open a new terminal for any subsequent commands. To stop the server later, press Ctrl+C.

4.2 Verify the Dashboard

  1. Open http://localhost:3000
  2. All indicators should show Mock Mode enabled

Setup Complete!

You now have:

  • Salesforce org with hotel data model
  • Workato workspace with all recipes running
  • API collections and MCP servers configured
  • Local application connected to all services

Common Issues & Solutions

Issue Solution
wk not found Install: brew install workato-devs/tap/wk (macOS/Linux) or scoop install wk (Windows)
wk auth fails Re-run make workato-login, check token in root .env
Salesforce login timeout Re-run sf org login web --alias myDevOrg
Recipes won’t start Link the Salesforce connection (see the note under Step 3.6), then re-run make start-recipes
“Connection not configured” Verify Workspace Connections authenticated
API Collection 401 Check WORKATO_API_TOKEN in .env
Room search returns empty Verify SF seed data imported
API call fails silently Check Tools → Logs in Workato for error details
Recipe returns error Expand the job in Logs to see error message and code
wk CLI command errors Ensure API client scopes match guidance in Step 3.1
npm install succeeds but db:setup fails with Cannot find module ...bcrypt_lib.node (Windows) You’re on Node 24/26. Switch to Node 20: scoop reset nodejs20, delete node_modules, re-run npm install
server.sh: command not found (Windows) Use cd app && npm run dev instead — the .sh scripts are macOS/Linux only
wk plugins install . fails with “Incorrect function” (Windows) Use the real versioned path instead of Scoop’s current symlink — see Unit 3 instructions
make setup hangs with “Reinstall anyway?” prompt (Windows) Press N + Enter. The CLI is already installed. Verify with sf --version

Facilitator Notes

Support Ratio: 1 facilitator per 8-10 attendees for this unit

Time Buffer: This unit often runs 5-10 minutes over. Build buffer into break if needed.

Fallback: If attendee can’t complete setup, pair them with someone who did for remaining units.