Generates the Salesforce OAuth2 authorization URL for a Connected App. Open the returned URL in a browser to approve access. After approving, Salesforce redirects to the redirect_uri with a 'code' query parameter — pass that code to sf_exchange_oauth_code to obtain your refresh token.

Set sandbox=true to use test.salesforce.com instead of login.salesforce.com.

Exchanges an OAuth2 authorization code for tokens. Set sandbox=true if the code was obtained from test.salesforce.com.

Returns the refresh_token (save this — it's long-lived!) and instance_url. The short-lived access_token is intentionally masked in the output to keep it out of MCP transcripts; you don't need it directly — pass refresh_token to the other tools and they obtain fresh access tokens on demand.

Error Handling:

• "invalid_grant": code expired or already used — re-run sf_get_oauth_auth_url

• "invalid_client": wrong client_id / client_secret (or Connected App still activating; wait 2-10 min after creating it)

Tests that the provided Salesforce credentials are valid by making a live API call to the org. Use this before scaffolding a project to confirm credentials work.

Returns:

• connected: boolean

• org_id: Salesforce Org ID

• username: Authenticated username

• instance_url: Confirmed org URL

Lists SObjects (standard and/or custom) available in the org. Supports filtering and pagination.

Returns JSON with: total, count, offset, has_more, next_offset (when more), sobjects[].

Returns full field-level metadata for a specific SObject. Use this to inspect available fields, their types, and relationships before generating typed Ballerina record definitions.

Errors:

• "NOT_FOUND": Object does not exist or is not accessible to this user

Returns a step-by-step guide for first-time users: how to create a Salesforce Connected App, where to find the Consumer Key/Secret, how to get a refresh token via sf_get_oauth_auth_url + sf_exchange_oauth_code, and which tool to call next. Call this when the user says "I'm new" / "where do I start" / "how do I get credentials".

Verifies that the 'bal' CLI is installed and reports its version. Run this first to catch missing prerequisites before scaffolding.

End-to-end setup in a single call:

1. Validates your Salesforce credentials.

2. Auto-detects sandbox vs. production from sf_base_url hostname.

3. Scaffolds a Ballerina project in your WSO2 BI workspace.

   • Standard SObjects use pre-built types from ballerinax/salesforce.types (no describe API calls, no generated boilerplate).

   • Custom (__c) objects are described and typed automatically.

4. Optionally runs 'bal build' to verify compilation.

This is the recommended entry point — most users only need to call this tool.

If you don't yet have credentials, call sf_setup_guide first.

All inputs except the 4 credential fields have sensible defaults:

• project_name: salesforce_integration

• org_name: wso2bi

• bi_path: ~/WSO2Integrator (mac/linux) or %USERPROFILE%\WSO2Integrator

• target_objects: ["Account", "Contact", "Lead", "Opportunity"]

• port: 9090

• build: false (set true to compile after scaffolding)

Creates a Ballerina integration project in your WSO2 Integrator (BI) workspace.

For most users, prefer 'sf_quickstart' — it wraps this plus credential validation and an optional build step.

Standard SObjects use pre-built types from ballerinax/salesforce.types (no describe call needed). Custom (__c) objects are described from your org and typed in types.bal.

Pre-conditions:

• 'bal' CLI installed (sf_check_prerequisites)

• target_objects exist in your org (custom objects fail loudly if missing)

Overwrites Config.toml in an existing Ballerina project with fresh Salesforce OAuth2 credentials. Useful for rotation. Sandbox is auto-detected from sf_base_url. File is written with mode 0600 (owner read/write only).

Adds a new SObject to an already-scaffolded project. For standard SObjects: creates a .bal file that uses the pre-built type from ballerinax/salesforce.types (no types.bal change needed). For custom (__c) objects: also appends a typed record to types.bal.

Returns the resource-route snippet to paste into main.bal.

Adds an event-driven listener to an existing scaffolded project.

A Salesforce listener can subscribe to:

• Object CDC: /data/ChangeEvent (set 'sobject')

• All CDC events: /data/ChangeEvents (set 'all_changes': true)

• Platform events: /event/__e (set 'platform_event')

CDC listeners get onCreate/onUpdate/onDelete/onRestore stubs (you can narrow this via 'events'). Platform-event listeners get onMessage.

The listener reuses the OAuth2 credentials already configured in main.bal — no extra Config.toml entries required.

Runs 'bal build' inside the project directory and reports the result.

Starts the Ballerina service in the background via 'bal run'. The port is passed through as a Ballerina configurable override so the reported service_url matches the actual listener.

Returns started=true when the listener has actually come up, plus a PID you can pass to sf_stop_project to terminate the service later.

Stops a 'bal run' process previously started by sf_deploy_project. Only PIDs tracked by this server (started via sf_deploy_project during the current session) can be stopped — for safety we won't kill arbitrary host PIDs.

Creates a complete, import-ready Postman collection for your Salesforce org:

1. Auto-obtains a refresh token using the username+password flow (no browser).

2. Bakes ALL credentials into the collection (collection variables + OAuth2 config).

3. Saves the .postman_collection.json to disk.

4. Returns a ready_for_quickstart block — call sf_quickstart immediately after, or save the file path and use sf_import_postman_credentials any time later.

The generated collection includes: • Password flow, auth-code flow (Steps 1–3), and refresh-token requests • Test scripts that auto-save tokens to collection variables on every response • Salesforce REST API folder (validate, list SObjects, SOQL, create Account) • Ballerina service folder (health check, Account CRUD via local service)

This is the recommended first step — run it once, reuse the collection forever.

Reads a Postman collection (.postman_collection.json) — including ones generated by sf_generate_postman_collection — and extracts Salesforce OAuth2 credentials (clientId, clientSecret, refreshToken, instanceUrl, username, password) so you don't have to type them out manually.

If a refresh_token is found it is returned immediately (no browser auth needed). If only username + password are found, tells you to call sf_get_token_password_flow.

Returns a ready_for_quickstart block to pass directly to sf_quickstart.

Obtains Salesforce OAuth2 tokens using the username+password grant — no browser, no auth-code redirect required.

Requirements on the Connected App (one-time Salesforce Setup):

1. Scope: "Perform requests at any time (refresh_token, offline_access)"

2. Setup → Identity → OAuth and OpenID Connect Settings → "Allow OAuth Username-Password Flows" = ON

Append security token to password if required: myPasswordABC123

Returns refresh_token and a ready_for_quickstart block for sf_quickstart.