From 6bc53441fe896ae5e17b061535044d1afdac83f0 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Mon, 1 Jun 2026 07:37:36 +0000 Subject: [PATCH] docs(TSP-1263): add migration wizard documentation for legacy integrations Add a new page explaining how to migrate Pipedream-based tool integrations to native integrations using the migration wizard. Update the integrations introduction and add-integrations pages to reference the new guide, and add the page to the navigation in docs.json. Co-Authored-By: Claude Sonnet 4.6 --- docs.json | 1 + integrations/add-integrations.mdx | 4 + integrations/introduction.mdx | 4 + integrations/migrate-legacy-integrations.mdx | 81 ++++++++++++++++++++ 4 files changed, 90 insertions(+) create mode 100644 integrations/migrate-legacy-integrations.mdx diff --git a/docs.json b/docs.json index 64bda239..5bc6f544 100644 --- a/docs.json +++ b/docs.json @@ -391,6 +391,7 @@ "pages": [ "integrations/introduction", "integrations/add-integrations", + "integrations/migrate-legacy-integrations", "integrations/remove-integrations" ] }, diff --git a/integrations/add-integrations.mdx b/integrations/add-integrations.mdx index 238ac97d..3e8aabe9 100644 --- a/integrations/add-integrations.mdx +++ b/integrations/add-integrations.mdx @@ -10,6 +10,10 @@ The **Integrations & API Keys** browser displays all available integrations. Use ## Setting Up Integrations + +If a tool you're working with has a legacy Pipedream-based integration, a migration banner will appear on its configuration page. See [Migrate legacy integrations](/integrations/migrate-legacy-integrations) to learn how to upgrade it to a native integration. + + To begin using integrations with your AI agents: 1. Navigate to the **Integrations & API Keys** page from the left-hand menu of your Relevance AI account. diff --git a/integrations/introduction.mdx b/integrations/introduction.mdx index 29670704..7d751419 100644 --- a/integrations/introduction.mdx +++ b/integrations/introduction.mdx @@ -28,6 +28,10 @@ Integrations fall into two types: Start with native integrations when available — they come with ready-made actions and triggers that require less configuration. + +If you have existing tools that use legacy Pipedream-based integrations, you can upgrade them using the migration wizard. See [Migrate legacy integrations](/integrations/migrate-legacy-integrations) for the step-by-step process. + + ## 1. Connecting Integrations The first step in leveraging integrations is connecting your external services to Relevance AI: diff --git a/integrations/migrate-legacy-integrations.mdx b/integrations/migrate-legacy-integrations.mdx new file mode 100644 index 00000000..bea758df --- /dev/null +++ b/integrations/migrate-legacy-integrations.mdx @@ -0,0 +1,81 @@ +--- +title: 'Migrate legacy integrations' +description: 'Use the migration wizard to upgrade tools from Pipedream-based integrations to native integrations.' +sidebarTitle: 'Migrate legacy integrations' +--- + +## Overview + +Legacy tool integrations are tools that connect to external services using Pipedream-based transformations. These were created before Relevance AI introduced native integrations, and they rely on Pipedream as an intermediary layer to handle authentication and API calls. + +Native integrations are built directly by Relevance AI and offer several improvements over Pipedream-based ones: + + + + Native integrations communicate directly with external services, reducing latency and improving reliability. + + + Native integrations come with ready-made tool steps so you can get started without manual configuration. + + + Native integrations support trigger events that can automatically activate your agents when something happens in a connected platform. + + + Native integrations are maintained by the Relevance AI team, so issues are resolved faster. + + + + + The migration wizard is rolling out gradually to eligible tools. If your tool has a legacy Pipedream-based integration, you may see the migration banner on its configuration page. + + +## When you'll see the migration banner + +If you have a tool that uses a legacy Pipedream-based transformation, a banner notification will appear at the top of that tool's configuration page. The banner indicates that a native integration is now available for that service. + +Click the banner to open the migration wizard modal. The wizard guides you through the migration process step by step and does not require any manual re-configuration of your tool settings. + +## Migration process + + + + The wizard first prompts you to connect your account for the native integration. Click **Connect account** to be redirected to the third-party service's authentication page. Grant the necessary permissions, then you'll be redirected back to the wizard to continue. + + If you have already connected a native integration account for this service on your **Integrations & API Keys** page, the wizard may allow you to select that existing connection instead. + + + + The wizard displays a side-by-side comparison of your current Pipedream-based configuration and the equivalent native integration configuration. Review how your existing parameters map to the new integration's fields. + + Check that all settings carry over correctly before proceeding. If a parameter does not have a direct equivalent, the wizard will indicate this so you can decide how to handle it. + + + + Once you've reviewed the parameter mapping, click **Complete migration** to finalize the process. Your tool will be updated to use the native integration, and the legacy Pipedream transformation will be replaced. + + + +## After migration + +After the migration completes, test your tool to confirm it behaves as expected. Run it with representative inputs and verify the outputs match what you'd receive before migration. + +Your existing tool run history is preserved. Agents that use the tool continue to work without requiring reconfiguration — the migration updates the tool's underlying integration while keeping its interface and parameters intact. + +The tool now has access to all features available in the native integration, including any pre-built actions and trigger events added in the future. + +## Frequently asked questions (FAQs) + + + + The migration wizard maps your existing Pipedream-based parameters to their native integration equivalents. The wizard shows you this mapping before you finalize the migration, so you can review any differences. Your tool's name, description, and overall structure remain unchanged. + + + Migration is applied at the tool level, not the agent level. During the migration process, avoid running the tool until the migration is complete. Once finished, your agents can use the tool immediately — no changes to your agent configuration are needed. + + + Migrations cannot be reversed automatically. If you need to revert to the previous Pipedream-based integration, contact the [Relevance AI support team](/get-started/support) for assistance. + + + If the wizard encounters a problem — such as an authentication failure or an unmappable parameter — it will display an error message explaining what went wrong. You can retry the relevant step or reach out to the [Relevance AI support team](/get-started/support) for help. + +