Skip to content

Various Connect docs updates #14990

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 2 commits into from
Dec 14, 2024
Merged

Various Connect docs updates #14990

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b019595
Various Connect docs updates
dannyroosevelt Dec 14, 2024
7ef2c0b
Fixing bad links
dannyroosevelt Dec 14, 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
8 changes: 4 additions & 4 deletions docs-v2/pages/connect/_meta.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export default {
"title": "Use cases",
},
"quickstart": {
"title": "Quickstart",
"title": "Managed auth",
},
"workflows": {
"title": "Running workflows",
Expand All @@ -32,12 +32,12 @@ export default {
"connect-link": {
"title": "Connect Link",
},
"troubleshooting": {
"title": "Troubleshooting",
},
"customize-your-app": {
"title": "Customize your app",
},
"troubleshooting": {
"title": "Troubleshooting",
},
"migrating-from-project-keys-to-oauth": {
"display": "hidden",
},
Expand Down
62 changes: 26 additions & 36 deletions docs-v2/pages/connect/components.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,35 @@
import { Steps, Tabs } from 'nextra/components'
import ArcadeEmbed from '@/components/ArcadeEmbed'
import Callout from '@/components/Callout'
import Image from 'next/image'

# Running components for your end users

Pipedream Connect provides you with the ability to pre-configure, deploy and
invoke [components](/components) **on behalf of [your end
users](/connect/api#external-users)**.
Pipedream Connect provides APIs to embed [pre-built components](/components) directly in your application
or AI agent, unlocking access to thousands of pre-built API operations. Enable [your end users](/connect/api#external-users) to
configure, deploy, and invoke Pipedream triggers and actions for more than {process.env.PUBLIC_APPS} APIs.

## What are components?

In the context of Pipedream Connect, components are self-contained executable
units of code. They are usually provided with some arbitrary input and produce a
result that's exported as output. These components are developed by the
Pipedream community and their source code is available in our [public Github
repository](https://github.com/PipedreamHQ/pipedream/tree/master/components).

To learn more about components in detail, please visit our [Components
guide](/components).
In Pipedream, [components](/components) are self-contained executable units of code. Your end users configure the inputs and the components produce a
result that's exported as output. These components are developed and maintained by Pipedream
and our community and their source code is available in our [public Github repo](https://github.com/PipedreamHQ/pipedream/tree/master/components).

<Callout type="info">
Running components for your end users via Pipedream Connect is in **beta**, and we're looking for feedback. Please [let us know](https://pipedream.com/support) how you're using it, what's not working, and what else you'd like to see.
</Callout>

## How to run components for your end users
## Getting stated

<Callout type="info">
Refer to the [Connect API docs](/connect/api) for the full API reference. Below is a quickstart with a few specific examples.

You can skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components).
</Callout>

<Steps>

### Find the app you want to use

<Callout type="info">
You can also skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components).
</Callout>

In order to find the right trigger or action to configure and run, you first need to find the app. For this example, we'll search for `gitlab`.
In order to find the right trigger or action to configure and run, you first need to find the app. In this example, we'll search for `gitlab`.

```text
GET /v1/connect/apps?q=gitlab
Expand Down Expand Up @@ -145,7 +136,7 @@ Here's the response:
```
### Retrieve the component's definition

In order to run a component for your end users, you need to understand
To configure and run a component for your end users, you need to understand
the component's definition. Now that you have the component's key from the previous step,
you can retrieve its structure from the Pipedream API. See the [component
structure](/components/api#component-structure) section in our docs for more
Expand All @@ -158,11 +149,10 @@ Commits** action for Gitlab:
GET /v1/connect/components/gitlab-list-commits
```

The response will contain the component's structure, including its
(human-understandable) name, version, and most importantly, the configuration
options that the component accepts (also known as [props](/components/api#props)
or "properties"). Here's an example of the response for the component in the
example above:
The response will contain the component's structure, including its user-friendly name,
version, and most importantly, the configuration options the component accepts
(also known as [props](/components/api#props) or "properties").
Here's an example of the response for the component in the example above:

```json
{
Expand Down Expand Up @@ -213,9 +203,8 @@ Component execution on behalf of your end users requires a few preliminary
steps, focused on getting the right input parameters (aka
[props](/workflows/using-props)) to the component.

Configuring each prop for a component usually involves an API call to our
backend to retrieve the possible values, unless the values that a prop can take
are static/free-form. The endpoint is accessible at:
Configuring each prop for a component often involves an API call to retrieve the possible values,
unless the values that a prop can take are static or free-form. The endpoint is accessible at:

```text
POST /v1/connect/components/configure
Expand All @@ -224,7 +213,7 @@ POST /v1/connect/components/configure
Typically, the options for a prop are linked to a specific user's account. Each
of these props implements an `options` method that retrieves the necessary
options from the third-party API, formats them, and sends them back in the
response for the end user to select.
response for the end user to select. Examples are listing Slack channels, Google Sheets, etc.

The payload for the configuration API call must contain the following fields:

Expand All @@ -235,7 +224,7 @@ The payload for the configuration API call must contain the following fields:
configured. The initial configuration call must contain the ID of the account
(aka `authProvisionId`) that your user has connected to the target app (see
[this section](workflows#configure-accounts-to-use-your-end-users-auth) for
more details on how to create these accounts)
more details on how to create these accounts).

We'll use the [**List Commits** component for
Gitlab](https://github.com/PipedreamHQ/pipedream/blob/master/components/gitlab/actions/list-commits/list-commits.mjs#L4)
Expand Down Expand Up @@ -344,7 +333,7 @@ For example, to retrieve the configuration options for the `refName` prop:

### Configure dynamic props (optional)

The set of props that a component can accept might not be static, and can change
The set of props that a component can accept might not be static, and may change
depending on the values of prior props. Props that behave this way are called
[dynamic props](/components/api#dynamic-props), and they need to be configured
in a different way. Props that are dynamic will have a `reloadProps` attribute
Expand All @@ -361,7 +350,7 @@ The payload is similar to the one used for the configuration API, but it
excludes the `prop_name` field since the goal of this call is to reload and
retrieve the new set of props, not to configure a specific one.

Using the **Add Single Row** component for Google Sheets as an example, the
Using the [Add Single Row action for Google Sheets](https://pipedream.com/apps/google-sheets/actions/add-single-row) as an example, the
request payload would look like this:

```json
Expand Down Expand Up @@ -455,7 +444,8 @@ Actions are components that perform a task by taking an input either during
produce a result. Sources are very similar, but the difference is that they are
not invoked directly by Pipedream users, but rather by events that happen on a
third-party service. For example, the "New File" source for Google Drive will be
triggered every time a new file is created in a specific folder in Google Drive.
triggered every time a new file is created in a specific folder in Google Drive,
then will emit an event for you to consume.

All this means is that actions can be invoked manually on demand, while sources
are instead deployed and run automatically when the event they are listening for
Expand Down Expand Up @@ -545,7 +535,7 @@ look something like this:

```json
{
"external_user_id": "jverce",
"external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9",
"id": "gitlab-new-issue",
"prop_name": "http",
"configured_props": {
Expand Down Expand Up @@ -608,7 +598,7 @@ this:
"type": "$.service.db"
},
"http": {
"endpoint_url": "https://39643dc2c8ff98a019f3fdc9078d6db9.m.pipedream.net"
"endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
},
"projectId": 45672541
},
Expand All @@ -625,7 +615,7 @@ In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete
the source in the future:

```text
DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=jverce
DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9
```

</Steps>
4 changes: 2 additions & 2 deletions docs-v2/pages/connect/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Pipedream customers on any plan can use all of the Connect features in `developm
</Callout>


## How to specify environment
## How to specify the 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 the account credentials (API key, access token, etc) for that `external_user_id` in the specified environment.

Expand Down Expand Up @@ -41,7 +41,7 @@ curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \
```

<Callout type="warning">
When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use the `development` environment with your own accounts when testing and developing, and not with your end users.**
When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use `development` with your own accounts when testing and developing, and not with your end users.**
</Callout>

<br />
Expand Down
8 changes: 4 additions & 4 deletions docs-v2/pages/connect/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ You have full, code-level control over how these integrations work in your app.

Connect lets you:

1. Handle authorization or accept API keys on behalf of your users, for any of Pipedream's [{process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps). Use the [Client SDK](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk) or [Connect Link](/connect/quickstart#use-connect-link) to accept auth in minutes.
1. Handle authorization or accept API keys on behalf of your users, for any of Pipedream's [{process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps). Use the [Client SDK](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk) or [Connect Link](/connect/quickstart#or-use-connect-link) to accept auth in minutes.
2. Securely retrieve OAuth access tokens, API keys, and other credentials for your end users with Pipedream's [REST API](/connect/api)
3. Run workflows for your end users with Pipedream's [workflow builder](/workflows), [serverless runtime](/), and thousands of no-code [triggers](/workflows/triggers) and [actions](/workflows/actions). Build complex integrations in minutes, writing code when you need it and using no-code components when you don't. Pipedream workflows are easy to modify, debug, and scale.
4. Run [any Pipedream action](https://pipedream.com/explore) or [deploy any Pipedream trigger](https://pipedream.com/explore) on behalf of your users, directly from within your application.
3. [Run workflows](/connect/workflows) for your end users with Pipedream's [workflow builder](/workflows), [serverless runtime](/), and thousands of no-code [triggers](/workflows/triggers) and [actions](/workflows/actions). Build complex integrations in minutes, writing code when you need it and using no-code components when you don't. Pipedream workflows are easy to modify, debug, and scale.
4. [Embed any Pipedream action or trigger](/connect/components) to run on behalf of your users, directly from within your application.

<br />

Expand Down Expand Up @@ -61,7 +61,7 @@ So if user `abc-123` in your application connects their Slack account in `produc

## Plans and pricing

**Connect is free to use for up to 1,000 connected accounts for any workspace**.
**Managed authentication with Connect is free to use for up to 1,000 connected accounts for any workspace**. Check out our [pricing page](https://pipedream.com/pricing?plan=Enterprise) for details on running workflows and embedding components in your app.

## Security

Expand Down
2 changes: 1 addition & 1 deletion docs-v2/pages/connect/oauth-clients.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ For any OAuth app that supports it, **you can always use your own client.** Your

1. Follow the steps [here](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) to create an OAuth client in Pipedream.
2. When connecting an account either via the [frontend SDK](/connect/quickstart#use-the-pipedream-sdk-in-your-frontend), make sure to include the `oauthAppId` in `pd.connectAccount()`.
3. If using [Connect Link](/connect/quickstart#use-connect-link), make sure to include the `oauthAppId` in the URL.
3. If using [Connect Link](/connect/quickstart#or-use-connect-link), make sure to include the `oauthAppId` in the URL.

### Finding your OAuth app ID

Expand Down
Loading
Loading