Skip to content

(docs) Invoke workflows for external users #14589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Nov 22, 2024
Merged

(docs) Invoke workflows for external users #14589

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
6f1eadb
Initial commit of workflow invoke docs
dylburger Nov 7, 2024
b2b0c51
More example fixes
dylburger Nov 7, 2024
7c104c4
Small changes
dylburger Nov 7, 2024
b529c0a
small patch
dannyroosevelt Nov 7, 2024
2572abe
First cut of workflow invoke errors
dannyroosevelt Nov 12, 2024
c9e6a0b
Workflow errors, WIP Connect troubleshooting
dannyroosevelt Nov 12, 2024
b8e1a7a
Troubleshooting info
dannyroosevelt Nov 13, 2024
8e73fa8
Fixing `environment` references
dylburger Nov 19, 2024
32f098e
small edits to troubleshooting page
dylburger Nov 19, 2024
c065eb4
Merge remote-tracking branch 'origin/master' into docs/invoke-workflo…
dylburger Nov 20, 2024
95975b4
Fixing bad merge
dylburger Nov 20, 2024
d0032bd
Info on testing workflows
dannyroosevelt Nov 22, 2024
40c73de
Merge branch 'master' into docs/invoke-workflows-for-external-user
dannyroosevelt Nov 22, 2024
83ba7e1
Update index.mdx
dannyroosevelt Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs-v2/pages/connect/_meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
"quickstart": {
"title": "Quickstart"
},
"workflows": {
"title": "Running workflows"
},
"api": {
"title": "API & SDK Reference"
},
Expand All @@ -26,6 +29,9 @@
"connect-link": {
"title": "Connect Link"
},
"troubleshooting": {
"title": "Troubleshooting"
},
"migrating-from-project-keys-to-oauth": {
"display": "hidden"
}
Expand Down
185 changes: 79 additions & 106 deletions docs-v2/pages/connect/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}",
}
});

Expand Down Expand Up @@ -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**.

<Tabs items={['TypeScript', 'Node.js']}>
<Tabs.Tab>
```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
)
```
</Tabs.Tab>
<Tabs.Tab>
```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
)
```
</Tabs.Tab>
</Tabs>

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

Expand Down Expand Up @@ -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
});
```
</Tabs.Tab>
Expand All @@ -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
});
```
</Tabs.Tab>
Expand All @@ -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}"
}'
```
</Tabs.Tab>
Expand Down Expand Up @@ -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({
Expand All @@ -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({
Expand Down Expand Up @@ -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, {
Expand All @@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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);
Expand All @@ -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
Expand Down Expand Up @@ -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}",
});
```
</Tabs.Tab>
Expand All @@ -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}",
});
```
</Tabs.Tab>
Expand Down
14 changes: 12 additions & 2 deletions docs-v2/pages/connect/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix typos in environment specification

There are two typos in this line:

  • "enviromment" should be "environment"
  • "succesfully" should be "successfully"
-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. By default, the environment is set to `production`. When users successfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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. By default, the environment is set to `production`. When users successfully 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.

<Callout type="warning">
`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`.
</Callout>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Missing referenced documentation file

  • The file docs-v2/pages/connect/api/.mdx referenced in /connect/api/#create-a-new-token does not exist.
🔗 Analysis chain

Verify documentation cross-references

Let's ensure all referenced documentation sections exist and are accessible.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Verify that referenced documentation sections exist

# Check for referenced documentation files
echo "Checking for referenced documentation files..."
for path in "/connect/workflows" "/connect/api/#create-a-new-token"; do
  # Remove the hash part for file checking
  file_path="docs-v2/pages${path%#*}.mdx"
  if ! fd -t f "${file_path##*/}" | grep -q "$file_path"; then
    echo "Warning: Referenced file not found: $file_path"
  fi
done

Length of output: 602

Loading