From 6f1eadb9cdd54369441a52a0739662a6a721e87e Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Wed, 6 Nov 2024 16:13:59 -0800 Subject: [PATCH 01/12] Initial commit of workflow invoke docs --- docs-v2/pages/connect/_meta.json | 3 + docs-v2/pages/connect/workflows.mdx | 119 ++++++++++++++++++++++++++++ docs-v2/pages/rest-api/index.mdx | 10 +-- docs-v2/pages/workflows/index.mdx | 2 +- 4 files changed, 126 insertions(+), 8 deletions(-) create mode 100644 docs-v2/pages/connect/workflows.mdx diff --git a/docs-v2/pages/connect/_meta.json b/docs-v2/pages/connect/_meta.json index 5034e6bc7e4a0..3c3a7d1a52df0 100644 --- a/docs-v2/pages/connect/_meta.json +++ b/docs-v2/pages/connect/_meta.json @@ -8,6 +8,9 @@ "quickstart": { "title": "Quickstart" }, + "workflows": { + "title": "Running workflows" + }, "api": { "title": "API & SDK Reference" }, diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx new file mode 100644 index 0000000000000..a50fbd40611d3 --- /dev/null +++ b/docs-v2/pages/connect/workflows.mdx @@ -0,0 +1,119 @@ +import { Steps, Tabs } from 'nextra/components' + +# Running workflows for your end users + +Just like you can build and run internal [workflows](/docs/workflows/) for your team, **you can run workflows for [your end users](/connect/api#external-users), too**. + +Whether you're building well-defined integrations or more-autonomous AI agents, workflows provide a powerful set of tools for running [code](/code) or [pre-defined actions](/workflows/actions) on behalf of your users. Pipedream's UI makes it easy to build, test, and [debug](/workflows/inspect) workflows. + +## What are workflows? + +
+ +
+ +Workflows are sequences of [steps](/workflows/steps) [triggered by an event](/workflows/triggers), like an HTTP request, or new rows in a Google sheet. + +You can use [pre-built actions](/workflows/actions/) or custom [Node.js](/code/nodejs/), [Python](/code/python/), [Golang](/code/go/), or [Bash](/code/bash/) code in workflows and connect to any of our {process.env.PUBLIC_APPS} integrated apps. + +Workflows also have built-in: + +- [Flow control](/workflows/control-flow) +- [Concurrency and throttling](/workflows/concurrency-and-throttling) +- [Key-value stores](/data-stores) +- [Error handling](/workflows/errors) +- [VPCs](/workflows/vpc) +- [And more](https://pipedream.com/pricing) + +Read [the quickstart](/quickstart/) to learn more. + +## How to run workflows for your end users + + + +### Create an OAuth client + +To run workflows for end users, you'll need to first [create an OAuth client](/rest-api/auth#creating-an-oauth-client). This client will be used to authenticate requests to your workflow. + +### Create a workflow + +[Create a new workflow](/workflows#how-do-i-create-a-new-workflow) or open an existing one. + +### Add an HTTP trigger, configure OAuth + +1. Add an [HTTP trigger](/workflows/triggers#http) to your workflow +2. [Configure **OAuth** authorization](/workflows/triggers#oauth) on the trigger + +### Configure accounts to use your end users' auth + +When you configure [pre-built actions](/workflows/actions) or [custom code that connects to third-party APIs](/code/nodejs/auth), you can link accounts in one of two ways: + +1. **Use your own account**: If you're connecting to an API that uses your own app's API key or developer account — for example, a workflow that connects to the OpenAI API — click the **Connect an [app] account** button to link your own, static account. + +
+ +
+ +2. **Use your end users' auth**: If you're building a workflow that connects to your end users' accounts — for example, a workflow that sends a message to a user's Slack account — you can select the option to **Use end user's auth via Connect**: + +
+ +
+ +This looks up the end user's account for this app, based on the user ID you provide [when invoking the workflow](#invoke-the-workflow). + +When you're done with the workflow, **Deploy** it. + +### Connect a test account + +You can connect a static account to the workflow step to test it, but to run an end-to-end test as an end user, you'll need to [invoke the workflow](#invoke-the-workflow) with a user ID that has linked a Connect account. + +You'll see all accounts by end user ID in [the **Users** tab](/connect#users) of your Connect dashboard. If you already have a test account linked, get the external user ID and [invoke the workflow](#invoke-the-workflow). + +If you've don't have a test account, create one: + +- If you've already [added Connect to your app](/connect), run through your own app's integrations flow and link test accounts for the apps you're using. +- You can also run [the Connect example app](/connect/quickstart) to quickly connect an account for any app. + +### Invoke the workflow + +If you haven't already, [install the Pipedream SDK](/connect/api#installing-the-typescript-sdk): + +```bash +npm install @pipedream/sdk +``` + +To invoke workflows, you'll need: + +1. The OAuth client ID and secret from **Step 1** +2. Your [Project ID](/projects#finding-your-projects-id) +3. Your workflow's HTTP endpoint URL +4. The [external user ID](/connect/api#external-users) of the user you'd like to run the workflow for + +```javascript +import { createBackendClient } from "@pipedream/sdk"; + +const client = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production + credentials: { + clientId: "your-client-id", + clientSecret: "your-client-secret" + }, + projectId: "your-project-id" +}); + +const response = await client.invokeWorkflowForExternalUser( + "your-workflow-endpoint-url", + "your-external-user-id", + { + method: "POST", + body: { + message: "Hello World" + } + } +) +``` + + + +## Errors \ No newline at end of file diff --git a/docs-v2/pages/rest-api/index.mdx b/docs-v2/pages/rest-api/index.mdx index d6b42a1f78b6e..ac661836ca5cd 100644 --- a/docs-v2/pages/rest-api/index.mdx +++ b/docs-v2/pages/rest-api/index.mdx @@ -684,7 +684,7 @@ Pass `debug=true` to return additional data in the response, useful for inspecti #### Example Request ```shell -curl https://api.pipedream.com/v1/components/search\?query\="When someone sends a tweet mentioning my brand, send me an SMS" \ +curl https://api.pipedream.com/v1/components/search\?query\="When a new Hubspot contact is added, send me an SMS"&limit=1 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` @@ -694,14 +694,10 @@ curl https://api.pipedream.com/v1/components/search\?query\="When someone sends ```json { "sources": [ - "twitter-new-mention-received-by-user", - "twitter-new-tweet-posted-by-user", - "twitter-new-tweet-posted-matching-query" + "hubspot-new-contact" ], "actions": [ - "sms-send-sms", - "sms_fusion-send-sms", - "sms_alert-send-sms" + "twilio-send-sms" ] } ``` diff --git a/docs-v2/pages/workflows/index.mdx b/docs-v2/pages/workflows/index.mdx index e13914b644599..5515ade0a3c77 100644 --- a/docs-v2/pages/workflows/index.mdx +++ b/docs-v2/pages/workflows/index.mdx @@ -4,7 +4,7 @@ import VideoPlayer from '@/components/VideoPlayer'; -Workflows make it easy to integrate your apps, data, and APIs - all with no servers or infrastructure to manage. They're sequences of linear [steps](/workflows/steps) [triggered by an event](/workflows/triggers), like an HTTP request, or new rows in a Google sheet. +Workflows make it easy to integrate your apps, data, and APIs - all with no servers or infrastructure to manage. They're sequences of [steps](/workflows/steps) [triggered by an event](/workflows/triggers), like an HTTP request, or new rows in a Google sheet. You can use [pre-built actions](/workflows/actions/) or custom [Node.js](/code/nodejs/), [Python](/code/python/), [Golang](/code/go/), or [Bash](/code/bash/) code in workflows and connect to any of our {process.env.PUBLIC_APPS} integrated apps. From b2b0c51c46c8ca1f51b58ae686454aab0109b18d Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Wed, 6 Nov 2024 16:58:51 -0800 Subject: [PATCH 02/12] More example fixes --- docs-v2/pages/connect/api.mdx | 185 ++++++++++++--------------- docs-v2/pages/connect/quickstart.mdx | 16 ++- docs-v2/pages/connect/workflows.mdx | 73 +++++++++-- docs-v2/pages/workflows/triggers.mdx | 33 ++++- 4 files changed, 181 insertions(+), 126 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index df9d031209eeb..1c9837bf09707 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -55,8 +55,8 @@ import { createBackendClient } from "@pipedream/sdk"; // These secrets should be saved securely and passed to your environment const pd = createBackendClient({ credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", } }); @@ -123,62 +123,7 @@ If you need higher rate limits, please [reach out](https://pipedream.com/support ### Invoke workflows -You can use the SDK to invoke workflows on behalf of any end user. **Write one workflow, run it for all of your users**. - - - -```typescript -import { createBackendClient, HTTPAuthType } from "@pipedream/sdk"; - -// These secrets should be saved securely and passed to your environment -const pd = createBackendClient({ - credentials: { - clientId: "YOUR_CLIENT_ID", - clientSecret: "YOUR_CLIENT_SECRET", - }, -}); - -await pd.invokeWorkflowForExternalUser( - "enabc123", // pass the endpoint ID or full URL here - "external_user_id" // The end user's ID in your system - { - method: "POST", - body: { - key: "value", - } - }, - HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token -) -``` - - -```javascript -import { createBackendClient } from "@pipedream/sdk"; - -// These secrets should be saved securely and passed to your environment -const pd = createBackendClient({ - credentials: { - clientId: "YOUR_CLIENT_ID", - clientSecret: "YOUR_CLIENT_SECRET", - }, -}); - -await pd.invokeWorkflowForExternalUser( - "enabc123", // pass the endpoint ID or full URL here - "external_user_id" // The end user's ID in your system - { - method: "POST", - body: { - key: "value", - } - }, - "oauth" // Will automatically send the Authorization header with a fresh token -) -``` - - - -See the [workflow invocation docs](/workflows/triggers#oauth) for more details. +You can use the SDK to [invoke workflows on behalf of any end user](/connect/workflows). **Write one workflow, run it for all of your users**. ### Tokens @@ -245,15 +190,17 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const { token, expires_at } = await pd.createConnectToken({ - project_id: "your-project-id", - external_user_id: "your-external-user-id" // The end user's ID in your system + project_id: "{your_project_id}", + external_user_id: "{your_external_user_id}" // The end user's ID in your system }); ``` @@ -262,15 +209,17 @@ const { token, expires_at } = await pd.createConnectToken({ import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", }, + projectId: "{your_project_id}" }); const { token, expires_at } = await pd.createConnectToken({ - project_id: "your-project-id", - external_user_id: "your-external-user-id", // The end user's ID in your system + project_id: "{your_project_id}", + external_user_id: "{your_external_user_id}", // The end user's ID in your system }); ``` @@ -291,7 +240,7 @@ curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {access_token}" \ -d '{ - "external_user_id": "your-external-user-id" + "external_user_id": "{your_external_user_id}" }' ``` @@ -349,10 +298,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const accounts = await pd.getAccounts({ @@ -368,10 +319,12 @@ const accounts = await pd.getAccounts({ import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const accounts = await pd.getAccounts({ @@ -513,10 +466,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const account = await pd.getAccount(accountId, { @@ -532,10 +487,12 @@ const account = await pd.getAccount(accountId, { import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const accountId = "{account_id}"; // Replace with your account ID @@ -653,10 +610,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); await pd.deleteAccount(accountId); @@ -669,10 +628,12 @@ await pd.deleteAccount(accountId); import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); await pd.deleteAccount(accountId); @@ -733,10 +694,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); await pd.deleteAccountsByApp(appId); @@ -749,10 +712,12 @@ await pd.deleteAccountsByApp(appId); import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); await pd.deleteAccount(accountId); @@ -813,10 +778,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); await pd.deleteExternalUser(externalId); @@ -829,10 +796,12 @@ console.log("All accounts associated with the external ID have been deleted."); import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const externalId = "{external_user_id}"; // Replace with your external user ID @@ -889,14 +858,16 @@ GET /{project_id}/info import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const info = await pd.getProjectInfo({ - project_id: "your-project-id", + project_id: "{your_project_id}", }); ``` @@ -905,14 +876,16 @@ const info = await pd.getProjectInfo({ import { createBackendClient } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); const info = await pd.getProjectInfo({ - project_id: "your-project-id", + project_id: "{your_project_id}", }); ``` diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx index eb305fdd118fa..c37f30e755ff0 100644 --- a/docs-v2/pages/connect/quickstart.mdx +++ b/docs-v2/pages/connect/quickstart.mdx @@ -174,10 +174,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); async function getUserAccounts(external_user_id: string, include_credentials: boolean = false) { @@ -198,10 +200,12 @@ import { } from "@pipedream/sdk"; const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-oauth-client-id", - clientSecret: "your-oauth-client-secret", - } + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" }); async function getUserAccounts(external_user_id, include_credentials = false) { diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index a50fbd40611d3..ee48cea8d14a3 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -77,10 +77,10 @@ If you've don't have a test account, create one: ### Invoke the workflow -If you haven't already, [install the Pipedream SDK](/connect/api#installing-the-typescript-sdk): +If you're using TypeScript or a JavaScript runtime, [install the Pipedream SDK](/connect/api#installing-the-typescript-sdk). Pipedream also provides an HTTP API for invoking workflows (see example below). ```bash -npm install @pipedream/sdk +npm i @pipedream/sdk ``` To invoke workflows, you'll need: @@ -89,22 +89,55 @@ To invoke workflows, you'll need: 2. Your [Project ID](/projects#finding-your-projects-id) 3. Your workflow's HTTP endpoint URL 4. The [external user ID](/connect/api#external-users) of the user you'd like to run the workflow for +5. The [Connect environment](/connect/environments) tied to the user's account (defaults to `production`) +Then invoke the workflow like so: + + + +```typescript +import { createBackendClient, HTTPAuthType } from "@pipedream/sdk"; + +// These secrets should be saved securely and passed to your environment +const pd = createBackendClient({ + environment: "development", // change to production if running for a test production account, or in production + credentials: { + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" +}); + +await pd.invokeWorkflowForExternalUser( + "{your_endpoint_url}", // pass the endpoint ID or full URL here + "{your_external_user_id}" // The end user's ID in your system + { + method: "POST", + body: { + message: "Hello World" + } + }, + HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token +) +``` + + ```javascript import { createBackendClient } from "@pipedream/sdk"; +// These secrets should be saved securely and passed to your environment const client = createBackendClient({ environment: "development", // change to production if running for a test production account, or in production credentials: { - clientId: "your-client-id", - clientSecret: "your-client-secret" + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}" }, - projectId: "your-project-id" + projectId: "{your_project_id}" }); const response = await client.invokeWorkflowForExternalUser( - "your-workflow-endpoint-url", - "your-external-user-id", + "{your_endpoint_url}", // pass the endpoint ID or full URL here + "{your_external_user_id}" // The end user's ID in your system { method: "POST", body: { @@ -113,7 +146,31 @@ const response = await client.invokeWorkflowForExternalUser( } ) ``` - + + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. + +curl -X POST https://{your-endpoint-url} \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {access_token}" \ + -H 'X-PD-External-User-ID: {your_external_user_id}' \ + -H 'X-PD-Environment: development' \ # 'development' or 'production' + -d '{ + "message": "Hello, world" + }' +``` + + ## Errors \ No newline at end of file diff --git a/docs-v2/pages/workflows/triggers.mdx b/docs-v2/pages/workflows/triggers.mdx index 7b97886f6993d..1a7c0a3b3a246 100644 --- a/docs-v2/pages/workflows/triggers.mdx +++ b/docs-v2/pages/workflows/triggers.mdx @@ -141,9 +141,9 @@ When making HTTP requests, pass the OAuth access token as a `Bearer` token in th curl -H 'Authorization: Bearer ' https://myendpoint.m.pipedream.net ``` -You can use the Pipedream SDK to automatically refresh access tokens and invoke workflows: +You can use the Pipedream SDK to automatically refresh access tokens and invoke workflows, or make HTTP requests directly to the workflow's URL: - + ```typescript import { createBackendClient, HTTPAuthType } from "@pipedream/sdk"; @@ -151,8 +151,8 @@ import { createBackendClient, HTTPAuthType } from "@pipedream/sdk"; // These secrets should be saved securely and passed to your environment const pd = createBackendClient({ credentials: { - clientId: "YOUR_CLIENT_ID", - clientSecret: "YOUR_CLIENT_SECRET", + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", }, }); @@ -175,8 +175,8 @@ import { createBackendClient } from "@pipedream/sdk"; // These secrets should be saved securely and passed to your environment const pd = createBackendClient({ credentials: { - clientId: "YOUR_CLIENT_ID", - clientSecret: "YOUR_CLIENT_SECRET", + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", }, }); @@ -192,6 +192,27 @@ await pd.invokeWorkflow( ) ``` + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. + +curl -X POST https://{your-endpoint-url} \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "message": "Hello, world" + }' +``` + From 7c104c49e66a4f1679ad4c02343476c572f7b429 Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Wed, 6 Nov 2024 20:17:34 -0800 Subject: [PATCH 03/12] Small changes --- docs-v2/pages/connect/workflows.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index ee48cea8d14a3..95c7bfa1e2be9 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -33,7 +33,7 @@ Read [the quickstart](/quickstart/) to learn more. ### Create an OAuth client -To run workflows for end users, you'll need to first [create an OAuth client](/rest-api/auth#creating-an-oauth-client). This client will be used to authenticate requests to your workflow. +To run workflows for end users, you'll need to first [create a Pipedream OAuth client](/rest-api/auth#creating-an-oauth-client). Pipedream uses OAuth to authenticate requests to the Pipedream API and workflows. ### Create a workflow From b529c0a7bc79ef9b6741ea5f00c3508b77865cd0 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 6 Nov 2024 21:17:57 -0800 Subject: [PATCH 04/12] small patch --- docs-v2/pages/connect/workflows.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index 95c7bfa1e2be9..147f0004fd4db 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -2,7 +2,7 @@ import { Steps, Tabs } from 'nextra/components' # Running workflows for your end users -Just like you can build and run internal [workflows](/docs/workflows/) for your team, **you can run workflows for [your end users](/connect/api#external-users), too**. +Just like you can build and run internal [workflows](/workflows/) for your team, **you can run workflows for [your end users](/connect/api#external-users), too**. Whether you're building well-defined integrations or more-autonomous AI agents, workflows provide a powerful set of tools for running [code](/code) or [pre-defined actions](/workflows/actions) on behalf of your users. Pipedream's UI makes it easy to build, test, and [debug](/workflows/inspect) workflows. @@ -85,7 +85,7 @@ npm i @pipedream/sdk To invoke workflows, you'll need: -1. The OAuth client ID and secret from **Step 1** +1. The OAuth client ID and secret from **[Step 1](/connect/workflows#create-an-oauth-client)** 2. Your [Project ID](/projects#finding-your-projects-id) 3. Your workflow's HTTP endpoint URL 4. The [external user ID](/connect/api#external-users) of the user you'd like to run the workflow for From 2572abe160553b6e52caca844de98ae4a7086e83 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Tue, 12 Nov 2024 11:52:31 -0800 Subject: [PATCH 05/12] First cut of workflow invoke errors --- docs-v2/pages/connect/_meta.json | 3 +++ docs-v2/pages/connect/environments.mdx | 14 ++++++++++++-- docs-v2/pages/connect/troubleshooting.mdx | 0 docs-v2/pages/connect/workflows.mdx | 18 +++++++++++++++++- 4 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 docs-v2/pages/connect/troubleshooting.mdx diff --git a/docs-v2/pages/connect/_meta.json b/docs-v2/pages/connect/_meta.json index 3c3a7d1a52df0..a192560fb2b18 100644 --- a/docs-v2/pages/connect/_meta.json +++ b/docs-v2/pages/connect/_meta.json @@ -29,6 +29,9 @@ "connect-link": { "title": "Connect Link" }, + "troubleshooting": { + "title": "Troubleshooting" + }, "migrating-from-project-keys-to-oauth": { "display": "hidden" } diff --git a/docs-v2/pages/connect/environments.mdx b/docs-v2/pages/connect/environments.mdx index f9355690d47f6..bf7116c15ce21 100644 --- a/docs-v2/pages/connect/environments.mdx +++ b/docs-v2/pages/connect/environments.mdx @@ -1,10 +1,20 @@ +import Callout from '@/components/Callout' + # Environments Pipedream Connect projects support two environments: `development` and `production`. 1. Connected accounts and credentials stored in `development` remain separate from `production`. -2. In `development`, you can use the official Pipedream OAuth apps, so you can test integrations without creating your own OAuth client. +2. In `development`, you can use the official Pipedream OAuth clients, so you can test integrations without creating your own OAuth client, and you can also use features that are typically only available on higher paid tiers, like [running workflows on behalf of your end users](/connect/workflows). ## How to specify environment -You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `project_environment`. +You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. + +## Using development mode + +When connecting an account in `development` mode, the end user who is connecting their account must be signed in to pipedream.com. + + +`development` mode should only be used by you and your team for testing. When you're ready to test with real users, switch to `production`. + \ No newline at end of file diff --git a/docs-v2/pages/connect/troubleshooting.mdx b/docs-v2/pages/connect/troubleshooting.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index 147f0004fd4db..cda38c8823dc3 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -173,4 +173,20 @@ curl -X POST https://{your-endpoint-url} \ -## Errors \ No newline at end of file +## Errors + +#### No external user ID passed, but one or more steps require it +- One or more steps in the workflow are configured to **Use end user's auth via Connect**, but no `external_user_id` was passed when invoking the workflow. +- [Refer to the docs](#invoke-the-workflow) to make sure you're passing `external_user_id` correctly when invoking the workflow. + +#### No matching external user ID +- There was an external user ID passed and is accessible via `steps.trigger.context.external_user_id`, but it didn't match any users in the project. +- Double-check that the `external_user_id` that you passed when invoking the workflow matches one either [in the UI](/connect#users) or [via the API](/connect/api#accounts). + +#### Required account not found for external user ID +- The `external_user_id` was passed when invoking the workflow, but the user hasn't connected an account one or more of the apps that are configured to use it in this workflow execution. +- You can check which accounts that user has connected [in the UI](/connect#users) or [via the API](/connect/api#accounts). + +#### The Business plan is required to run this workflow for production users +- Running workflows for your end users is available for users in `development`, but a Business plan is required to run on behalf of `production` users. +- Schedule a call with our sales team and learn more about pricing [here](https://pipedream.com/pricing?plan=Enterprise). \ No newline at end of file From c9e6a0bf28e6f67c97ed8f791b922c85f3d3e9df Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Tue, 12 Nov 2024 13:25:50 -0800 Subject: [PATCH 06/12] Workflow errors, WIP Connect troubleshooting --- docs-v2/pages/connect/troubleshooting.mdx | 9 +++++++++ docs-v2/pages/connect/workflows.mdx | 12 ++++++------ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/docs-v2/pages/connect/troubleshooting.mdx b/docs-v2/pages/connect/troubleshooting.mdx index e69de29bb2d1d..bb3375f02f89c 100644 --- a/docs-v2/pages/connect/troubleshooting.mdx +++ b/docs-v2/pages/connect/troubleshooting.mdx @@ -0,0 +1,9 @@ +# Troubleshooting + +## Common errors + +#### This link has expired. Please request a new one from the app developer. + +#### This session has expired. Please refresh the page to try again. + +#### Connection failed. Please retry or contact support. \ No newline at end of file diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index cda38c8823dc3..042ab47a2f205 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -176,16 +176,16 @@ curl -X POST https://{your-endpoint-url} \ ## Errors #### No external user ID passed, but one or more steps require it -- One or more steps in the workflow are configured to **Use end user's auth via Connect**, but no `external_user_id` was passed when invoking the workflow. -- [Refer to the docs](#invoke-the-workflow) to make sure you're passing `external_user_id` correctly when invoking the workflow. +- One or more steps in the workflow are configured to **Use end user's auth via Connect**, but no external user ID was passed when invoking the workflow. +- [Refer to the docs](#invoke-the-workflow) to make sure you're passing external user ID correctly when invoking the workflow. #### No matching external user ID -- There was an external user ID passed and is accessible via `steps.trigger.context.external_user_id`, but it didn't match any users in the project. -- Double-check that the `external_user_id` that you passed when invoking the workflow matches one either [in the UI](/connect#users) or [via the API](/connect/api#accounts). +- There was an external user ID passed, but it didn't match any users in the project. +- Double-check that the external user ID that you passed when invoking the workflow matches one either [in the UI](/connect#users) or [via the API](/connect/api#accounts). #### Required account not found for external user ID -- The `external_user_id` was passed when invoking the workflow, but the user hasn't connected an account one or more of the apps that are configured to use it in this workflow execution. -- You can check which accounts that user has connected [in the UI](/connect#users) or [via the API](/connect/api#accounts). +- The external user ID was passed when invoking the workflow, but the user doesn't have a connected account for one or more of the apps that are configured to use it in this workflow execution. +- You can check which connected accounts are available for that user [in the UI](/connect#users) or [via the API](/connect/api#accounts). #### The Business plan is required to run this workflow for production users - Running workflows for your end users is available for users in `development`, but a Business plan is required to run on behalf of `production` users. From b8e1a7a397b5c3bb78e9ed750e307f6e9e044c59 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Tue, 12 Nov 2024 21:17:39 -0800 Subject: [PATCH 07/12] Troubleshooting info --- docs-v2/pages/connect/tokens.mdx | 6 +++++ docs-v2/pages/connect/troubleshooting.mdx | 32 ++++++++++++++++++++--- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs-v2/pages/connect/tokens.mdx b/docs-v2/pages/connect/tokens.mdx index fe86a0ba3c41c..2353c162f4693 100644 --- a/docs-v2/pages/connect/tokens.mdx +++ b/docs-v2/pages/connect/tokens.mdx @@ -1,3 +1,5 @@ +import Callout from '@/components/Callout' + # Connect tokens When you initiate account connection for your end users, you must either: @@ -9,6 +11,10 @@ Here, we'll show you how to generate tokens for your users and return that to yo Use tokens when you want to handle the account connection flow yourself, in your app's UI. For example, you might want to show a **Connect Slack** button in your app that triggers the account connection flow for Slack, or launch the flow in a modal. + +Connect tokens currently have a 4-hour expiry, and can only be used once. + + ## Creating a token See docs on [the `/tokens` endpoint](/connect/api/#create-a-new-token) to create new tokens. diff --git a/docs-v2/pages/connect/troubleshooting.mdx b/docs-v2/pages/connect/troubleshooting.mdx index bb3375f02f89c..2d6a9fd707ffb 100644 --- a/docs-v2/pages/connect/troubleshooting.mdx +++ b/docs-v2/pages/connect/troubleshooting.mdx @@ -1,9 +1,33 @@ # Troubleshooting -## Common errors +Below are some common errors when connecting your users' accounts via Pipedream Connect. -#### This link has expired. Please request a new one from the app developer. +### Error creating a Connect token +>Error creating token: Error: Failed to obtain OAuth token: Response Error: 401 Unauthorized +- Authorization to the Pipedream API failed when creating the Connect token. +- Double-check the client ID or secret for your [Pipedream OAuth client](/connect/api#authentication). -#### This session has expired. Please refresh the page to try again. +### Error connecting an account +Most errors when connecting an account are related to the [Connect token](/connect/tokens), which Pipedream validates from the Connect iFrame. + +#### Possible errors +>- This link has expired. Please request a new one from the app developer.
+>- This session has expired. Please refresh the page to try again. + +#### Troubleshooting steps +- Pipedream typically returns an explicit error message in the HTTP response of the token validation network call directly from the iFrame in the client. +- To check for errors, start the account connection flow in a browser and open the developer console to view the network requests. +- Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id{app_slug}` and check the response for any error messages. + +#### Token validation errors + +>The Pipedream Connect token is invalid. Please generate a new one and try again. +- Connect tokens have explicit expiries, and are only able to be used once. Try generating a new token and trying again. + +>App not found. Please check your app id. +- Double-check the app slug you're passing [when connecting your user's account](/connect/quickstart#connect-a-users-account). + + +### Connection failed. Please retry or contact support. +- The user may have closed the OAuth popup window without completing authorization. -#### Connection failed. Please retry or contact support. \ No newline at end of file From 8e73fa858e9b355a48c7d672a0f16ed685722740 Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Mon, 18 Nov 2024 20:38:31 -0800 Subject: [PATCH 08/12] Fixing `environment` references --- docs-v2/pages/connect/api.mdx | 12 ++++++------ docs-v2/pages/connect/environments.mdx | 4 ++-- docs-v2/pages/connect/tokens.mdx | 4 ++-- docs-v2/pages/connect/workflows.mdx | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index 1c9837bf09707..a72271a7909b5 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -151,6 +151,12 @@ The ID of your end user. Use whatever ID uniquely identifies the user in your sy --- +`environment` **string** + +Specify the environment (`production` or `development`) to use for the account connection flow. + +--- + `success_redirect_uri` **string** (_optional_) When using [Connect Link](/connect/connect-link), you can optionally redirect your end user to the `success_redirect_uri` on successful completion of the auth flow. @@ -167,12 +173,6 @@ When using [Connect Link](/connect/connect-link), you can optionally redirect yo Pipedream will send events on successful auth, or any errors, to this URL via webhook. [See the webhooks docs](/connect/webhooks) for more information. ---- - -`project_environment` **string** (_optional_) - -Specify the environment (`production` or `development`) to use for the account connection flow. Defaults to `production`. - ##### Examples To create a short-lived token via TypeScript / JavaScript SDK, you'll need to create a Pipedream API client and call the `createConnectToken` method. In our example app, this code is in `app/server.ts`. diff --git a/docs-v2/pages/connect/environments.mdx b/docs-v2/pages/connect/environments.mdx index bf7116c15ce21..fc1cc2e059b64 100644 --- a/docs-v2/pages/connect/environments.mdx +++ b/docs-v2/pages/connect/environments.mdx @@ -9,11 +9,11 @@ Pipedream Connect projects support two environments: `development` and `producti ## How to specify environment -You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. +You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. ## Using development mode -When connecting an account in `development` mode, the end user who is connecting their account must be signed in to pipedream.com. +When connecting an account in `development` mode, the end user who is connecting their account must be signed in to [https://pipedream.com](https://pipedream.com). `development` mode should only be used by you and your team for testing. When you're ready to test with real users, switch to `production`. diff --git a/docs-v2/pages/connect/tokens.mdx b/docs-v2/pages/connect/tokens.mdx index 2353c162f4693..edc8949cabe73 100644 --- a/docs-v2/pages/connect/tokens.mdx +++ b/docs-v2/pages/connect/tokens.mdx @@ -27,6 +27,6 @@ When you generate a token, you can specify a `webhook_uri` where Pipedream will ## Tokens are scoped to end users and project environments -When you [create a new Connect token](/connect/api/#create-a-new-token), you pass an `external_user_id` and an optional `project_environment` parameter. By default, the environment is set to `production`. See the docs on [environments](/connect/environments) for more information. +When you [create a new Connect token](/connect/api/#create-a-new-token), you pass an `external_user_id` and an `environment` parameter. See the docs on [environments](/connect/environments) for more information. -Tokens are scoped to this user and environment. When the user successfully connects an account with that token, it will be saved for that `external_user_id` in the specified `project_environment`. \ No newline at end of file +Tokens are scoped to this user and environment. When the user successfully connects an account with that token, it will be saved for that `external_user_id` in the specified `environment`. \ No newline at end of file diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index 042ab47a2f205..7828235163b77 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -89,7 +89,7 @@ To invoke workflows, you'll need: 2. Your [Project ID](/projects#finding-your-projects-id) 3. Your workflow's HTTP endpoint URL 4. The [external user ID](/connect/api#external-users) of the user you'd like to run the workflow for -5. The [Connect environment](/connect/environments) tied to the user's account (defaults to `production`) +5. The [Connect environment](/connect/environments) tied to the user's account Then invoke the workflow like so: From 32f098e8ce935d680d3ad122e963119760a6cdb4 Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Mon, 18 Nov 2024 20:51:40 -0800 Subject: [PATCH 09/12] small edits to troubleshooting page --- docs-v2/pages/connect/troubleshooting.mdx | 38 +++++++++++++++-------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/docs-v2/pages/connect/troubleshooting.mdx b/docs-v2/pages/connect/troubleshooting.mdx index 2d6a9fd707ffb..8a81d5195f990 100644 --- a/docs-v2/pages/connect/troubleshooting.mdx +++ b/docs-v2/pages/connect/troubleshooting.mdx @@ -3,31 +3,43 @@ Below are some common errors when connecting your users' accounts via Pipedream Connect. ### Error creating a Connect token ->Error creating token: Error: Failed to obtain OAuth token: Response Error: 401 Unauthorized -- Authorization to the Pipedream API failed when creating the Connect token. -- Double-check the client ID or secret for your [Pipedream OAuth client](/connect/api#authentication). + +_Error creating token: Error: Failed to obtain OAuth token: Response Error: 401 Unauthorized_ + +Authorization to the Pipedream API failed when creating the Connect token. Double-check the client ID or secret for your [Pipedream OAuth client](/connect/api#authentication). ### Error connecting an account + Most errors when connecting an account are related to the [Connect token](/connect/tokens), which Pipedream validates from the Connect iFrame. #### Possible errors ->- This link has expired. Please request a new one from the app developer.
->- This session has expired. Please refresh the page to try again. + +_This link has expired. Please request a new one from the app developer._ + +_This session has expired. Please refresh the page to try again._ #### Troubleshooting steps -- Pipedream typically returns an explicit error message in the HTTP response of the token validation network call directly from the iFrame in the client. -- To check for errors, start the account connection flow in a browser and open the developer console to view the network requests. -- Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id{app_slug}` and check the response for any error messages. + +Pipedream typically returns an explicit error message in the HTTP response of the token validation network call directly from the iFrame in the client. To check for errors, start the account connection flow in a browser and open the developer console to view the network requests. + +Filter for requests to + +``` +https://api.pipedream.com/v1/connect/tokens +``` + +and check the response for error messages. #### Token validation errors ->The Pipedream Connect token is invalid. Please generate a new one and try again. -- Connect tokens have explicit expiries, and are only able to be used once. Try generating a new token and trying again. +_The Pipedream Connect token is invalid. Please generate a new one and try again._ + +Connect tokens expire, and are only able to be used once. Try generating a new token and try again. ->App not found. Please check your app id. -- Double-check the app slug you're passing [when connecting your user's account](/connect/quickstart#connect-a-users-account). +_App not found. Please check your app id._ +Double-check the app slug you're passing [when connecting your user's account](/connect/quickstart#connect-a-users-account). ### Connection failed. Please retry or contact support. -- The user may have closed the OAuth popup window without completing authorization. +The user may have closed the OAuth popup window without completing authorization. \ No newline at end of file From 95975b4963d23f39e8d50ef30ab8bb946ccbd3ac Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Tue, 19 Nov 2024 19:54:19 -0800 Subject: [PATCH 10/12] Fixing bad merge --- docs-v2/pages/connect/tokens.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs-v2/pages/connect/tokens.mdx b/docs-v2/pages/connect/tokens.mdx index 8671cb3ae6e50..4ffafc9ad03b1 100644 --- a/docs-v2/pages/connect/tokens.mdx +++ b/docs-v2/pages/connect/tokens.mdx @@ -1,10 +1,6 @@ -<<<<<<< HEAD import Callout from '@/components/Callout' # Connect tokens -======= -# Connect Tokens ->>>>>>> origin/master When you initiate account connection for your end users, you must either: @@ -31,6 +27,6 @@ When you generate a token, you can specify a `webhook_uri` where Pipedream will ## Tokens are scoped to end users and project environments -When you [create a new Connect token](/connect/api/#create-a-new-token), you pass an `external_user_id` and an `environment` parameter. See the docs on [environments](/connect/environments) for more information. +When you [create a new Connect token](/connect/api/#create-a-new-token), you pass an `external_user_id` and an `environment`. See the docs on [environments](/connect/environments) for more information on passing environment in the SDK and API. -Tokens are scoped to this user and environment. When the user successfully connects an account with that token, it will be saved for that `external_user_id` in the specified `environment`. +Tokens are scoped to this user and environment. When the user successfully connects an account with that token, it will be saved for that `external_user_id` in the specified environment. From d0032bdeda0086e120469c2434f209e1bbdd80f3 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Thu, 21 Nov 2024 16:50:20 -0800 Subject: [PATCH 11/12] Info on testing workflows --- docs-v2/pages/connect/workflows.mdx | 55 +++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index 7828235163b77..de41d24ae06ba 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -1,4 +1,7 @@ import { Steps, Tabs } from 'nextra/components' +import ArcadeEmbed from '@/components/ArcadeEmbed' +import Callout from '@/components/Callout' +import Image from 'next/image' # Running workflows for your end users @@ -33,7 +36,8 @@ Read [the quickstart](/quickstart/) to learn more. ### Create an OAuth client -To run workflows for end users, you'll need to first [create a Pipedream OAuth client](/rest-api/auth#creating-an-oauth-client). Pipedream uses OAuth to authenticate requests to the Pipedream API and workflows. +**This step is optional but strongly recommended.** To securely run workflows for end users, you'll need to first [create a Pipedream OAuth client](/rest-api/auth#creating-an-oauth-client). Pipedream uses OAuth to authenticate requests to the Pipedream API and workflows. + ### Create a workflow @@ -41,39 +45,60 @@ To run workflows for end users, you'll need to first [create a Pipedream OAuth c ### Add an HTTP trigger, configure OAuth -1. Add an [HTTP trigger](/workflows/triggers#http) to your workflow -2. [Configure **OAuth** authorization](/workflows/triggers#oauth) on the trigger +1. Add an [HTTP trigger](/workflows/triggers#http) to your workflow. +2. [Configure **OAuth** authorization](/workflows/triggers#oauth) on the trigger. Again, this step is optional **but strongly recommended.** ### Configure accounts to use your end users' auth When you configure [pre-built actions](/workflows/actions) or [custom code that connects to third-party APIs](/code/nodejs/auth), you can link accounts in one of two ways: -1. **Use your own account**: If you're connecting to an API that uses your own app's API key or developer account — for example, a workflow that connects to the OpenAI API — click the **Connect an [app] account** button to link your own, static account. +1. **Use your own account**: If you're connecting to an API that uses your own API key or developer account — for example, a workflow that connects to the OpenAI API or a PostgreSQL database — click the **Connect account** button to link your own, static account.
-2. **Use your end users' auth**: If you're building a workflow that connects to your end users' accounts — for example, a workflow that sends a message to a user's Slack account — you can select the option to **Use end user's auth via Connect**: +2. **Use your end users' auth**: If you're building a workflow that connects to your end users' accounts — for example, a workflow that sends a message with your user's Slack account — you can select the option to **Use end user's auth via Connect**:
-This looks up the end user's account for this app, based on the user ID you provide [when invoking the workflow](#invoke-the-workflow). - -When you're done with the workflow, **Deploy** it. +When you trigger the workflow, Pipedream will look up the corresponding account for the end user whose user ID you provide [when invoking the workflow](#invoke-the-workflow). ### Connect a test account -You can connect a static account to the workflow step to test it, but to run an end-to-end test as an end user, you'll need to [invoke the workflow](#invoke-the-workflow) with a user ID that has linked a Connect account. +To run an end-to-end test as an end user, you need to have users and connected accounts in your project. If you already have a **development** account linked, you can skip this step. + +If you don't, the fastest way to do this is [on the **Users** tab](/connect#users) in your Pipedream project: +- You'll see there's a button to **Connect account** +- Go through the flow and make sure to create the account in **development** mode +- Note the **external user ID** of the account you just connected, you'll need it in the next step + + + + +### Generate a test request + +Test events are critical for developing workflows effectively. Without a test event, you won't be able to test your workflow end to end in the builder, see the shape of the event data that triggers the workflow, and the lookup to use your end user's auth won't work. + +To generate a test event, click **Send Test Event** in the trigger, and fill in the event data. This will trigger the workflow and allow you to test the workflow end to end in the builder. + + +Make sure to include these headers in your test request: +- `x-pd-environment: development` +- `x-pd-external-user-id: {your_external_user_id}` + + +
-You'll see all accounts by end user ID in [the **Users** tab](/connect#users) of your Connect dashboard. If you already have a test account linked, get the external user ID and [invoke the workflow](#invoke-the-workflow). +Invoke workflow headers -If you've don't have a test account, create one: +### Deploy your workflow -- If you've already [added Connect to your app](/connect), run through your own app's integrations flow and link test accounts for the apps you're using. -- You can also run [the Connect example app](/connect/quickstart) to quickly connect an account for any app. +When you're done with the workflow, click **Deploy** at the top right. ### Invoke the workflow @@ -187,6 +212,6 @@ curl -X POST https://{your-endpoint-url} \ - The external user ID was passed when invoking the workflow, but the user doesn't have a connected account for one or more of the apps that are configured to use it in this workflow execution. - You can check which connected accounts are available for that user [in the UI](/connect#users) or [via the API](/connect/api#accounts). -#### The Business plan is required to run this workflow for production users -- Running workflows for your end users is available for users in `development`, but a Business plan is required to run on behalf of `production` users. +#### Running workflows for your users in production requires a higher tier plan +- Anyone is able to run workflows for your end users in `development`. The Business plan is required to run on behalf of `production` users. - Schedule a call with our sales team and learn more about pricing [here](https://pipedream.com/pricing?plan=Enterprise). \ No newline at end of file From 83ba7e11d425ab76972b8ed39493ced9357c43fa Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Thu, 21 Nov 2024 19:40:13 -0800 Subject: [PATCH 12/12] Update index.mdx --- docs-v2/pages/connect/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs-v2/pages/connect/index.mdx b/docs-v2/pages/connect/index.mdx index f0c722bd9fb53..1090173fb36ee 100644 --- a/docs-v2/pages/connect/index.mdx +++ b/docs-v2/pages/connect/index.mdx @@ -53,6 +53,12 @@ To view or delete your users' connected accounts: You'll see a list of all users, their connected accounts, and the option to delete any accounts from the UI. You can also retrieve and delete all your users via the API ([see the docs for reference](/connect/api)). + +Connect currently supports one connected account per user / app / environment combination. + +So if user `abc-123` in your application connects their Slack account in `production`, then that same user connects a different Slack workspace (also in `production`), the first connected account will get overwritten in Pipedream and replaced by the second. + + ## Plans and pricing **Connect is free to use for up to 1,000 connected accounts for any workspace**.