document one-time admin package install step (#5941)

* docs: document one-time admin package install step The previous revision described a manual "install in Salesforce first, then connect from AMP" flow that nobody actually follows, and linked to a private repo customers can't access. * docs: point Integrations link at crewai_plus/unified_tools
2026-07-02 13:48:09 +00:00 · 2026-05-26 20:06:51 -03:00
parent 3a52919a35
commit 1bac7d3afb
4 changed files with 204 additions and 17 deletions
--- a/docs/ar/enterprise/integrations/salesforce.mdx
+++ b/docs/ar/enterprise/integrations/salesforce.mdx
@@ -17,15 +17,62 @@ mode: "wide"
 - حساب Salesforce بالصلاحيات المناسبة
 - ربط حساب Salesforce الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations)

+<Note>
+  يتطلب Salesforce **تثبيتًا واحدًا يقوم به مسؤول النظام (admin)** لحزمة
+  CrewAI في مؤسستك قبل أن يتمكن أي مستخدم من الاتصال. هذا متطلب من منصة
+  Salesforce لجميع التكاملات المعتمدة على ExternalClientApp اعتبارًا من
+  إصدار Spring '26 — وليس خطوة خاصة بـ CrewAI. تدليلك خطوة Connect
+  Salesforce في CrewAI AMP خلال هذه العملية عند المحاولة الأولى.
+</Note>
+
 ## إعداد تكامل Salesforce

 ### 1. ربط حساب Salesforce الخاص بك

-1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
-2. ابحث عن **Salesforce** في قسم تكاملات المصادقة
-3. انقر على **Connect** وأكمل عملية OAuth
-4. امنح الصلاحيات اللازمة لإدارة CRM والمبيعات
-5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations)
+1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/unified_tools).
+2. ابحث عن **Salesforce** في قسم تكاملات المصادقة.
+3. انقر على **Connect**.
+
+ما يحدث بعد ذلك يعتمد على ما إذا كان مسؤول Salesforce في مؤسستك قد ثبّت
+حزمة CrewAI بالفعل:
+
+- **الحزمة مثبتة بالفعل:** سيتم نقلك مباشرة إلى شاشة موافقة OAuth في
+  Salesforce — اعتمدها وسيكتمل الاتصال.
+- **الحزمة غير مثبتة بعد:** سترى صفحة **Install CrewAI in Salesforce**.
+  اتبع خطوات التثبيت لمرة واحدة أدناه، ثم عُد إلى CrewAI AMP وانقر على
+  **Connect** مرة أخرى.
+
+4. امنح الصلاحيات اللازمة لإدارة CRM والمبيعات.
+5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations).
+
+#### تثبيت لمرة واحدة بواسطة المسؤول (مسؤول Salesforce فقط)
+
+عند أول نقرة على **Connect Salesforce** من أي مستخدم في مؤسستك، تقوم CrewAI
+بإعادة توجيهك إلى صفحة تثبيت تُشير إلى حزمة CrewAI المُدارة. يحتاج مسؤول
+Salesforce إلى تثبيتها مرة واحدة فقط لكامل المؤسسة.
+
+1. في صفحة التثبيت داخل CrewAI، انقر على **Install in Salesforce**. (يمكنك
+   أيضًا مشاركة عنوان URL لتلك الصفحة مع المسؤول — رابط التثبيت يعمل لأي
+   شخص يفتحه.)
+2. سجّل الدخول إلى Salesforce بصلاحيات مسؤول. لبيئات Sandbox، استبدل
+   `login.salesforce.com` بـ `test.salesforce.com` في الرابط قبل فتحه.
+3. اختر **Install for All Users**، ووافق على إشعار تطبيقات الجهات
+   الخارجية، ثم انقر **Install**.
+4. من Setup في Salesforce، ابحث عن **External Client App Manager** ←
+   **CrewAI App** ← افتح علامة التبويب **Policies** ← **Edit**، واضبط
+   القيم التالية:
+   - **Permitted Users:** All users may self-authorize
+   - **IP Relaxation:** Relax IP restrictions
+   - **Refresh Token Policy:** Refresh token is valid until revoked
+5. احفظ التغييرات.
+6. عُد إلى CrewAI AMP وانقر على **Connect Salesforce** مرة أخرى. سيكتمل
+   OAuth هذه المرة.
+
+<Note>
+  **لست مسؤول Salesforce؟** أعِد توجيه عنوان URL لصفحة التثبيت (أو رابط
+  التثبيت نفسه) إلى مسؤول Salesforce لديكم واطلب منه إكمال الخطوات أعلاه.
+  بمجرد انتهائه، عُد إلى CrewAI AMP وانقر على **Connect** مرة أخرى.
+</Note>

 ### 2. تثبيت الحزمة المطلوبة

--- a/docs/en/enterprise/integrations/salesforce.mdx
+++ b/docs/en/enterprise/integrations/salesforce.mdx
@@ -17,15 +17,61 @@ Before using the Salesforce integration, ensure you have:
 - A Salesforce account with appropriate permissions
 - Connected your Salesforce account through the [Integrations page](https://app.crewai.com/integrations)

+<Note>
+  Salesforce requires a **one-time admin install** of the CrewAI package in
+  your org before any user can connect. This is a Salesforce platform
+  requirement for all ExternalClientApp-based integrations as of the Spring
+  '26 release — not a CrewAI-specific step. The Connect Salesforce flow in
+  CrewAI AMP walks you through it the first time.
+</Note>
+
 ## Setting Up Salesforce Integration

 ### 1. Connect Your Salesforce Account

-1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
-2. Find **Salesforce** in the Authentication Integrations section
-3. Click **Connect** and complete the OAuth flow
-4. Grant the necessary permissions for CRM and sales management
-5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)
+1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/unified_tools).
+2. Find **Salesforce** in the Authentication Integrations section.
+3. Click **Connect**.
+
+What happens next depends on whether a Salesforce admin in your org has
+already installed the CrewAI package:
+
+- **Package already installed:** you're taken straight to the Salesforce
+  OAuth consent screen — approve it and you're connected.
+- **Package not installed yet:** you'll see an **Install CrewAI in
+  Salesforce** page. Follow the one-time install steps below, then come
+  back to CrewAI AMP and click **Connect** again.
+
+4. Grant the necessary permissions for CRM and sales management.
+5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations).
+
+#### One-time admin install (Salesforce admin only)
+
+The first time anyone in your org clicks **Connect Salesforce**, CrewAI
+redirects them to an install page that points at the CrewAI managed package.
+A Salesforce admin needs to install it once for the whole org.
+
+1. On the install page in CrewAI, click **Install in Salesforce**. (You can
+   also share the page URL with your admin — the install link works for
+   anyone who opens it.)
+2. Sign in to Salesforce as an admin. For sandboxes, swap `login.salesforce.com`
+   for `test.salesforce.com` in the URL before opening it.
+3. Choose **Install for All Users**, acknowledge the third-party app prompt,
+   and click **Install**.
+4. In Salesforce Setup, search **External Client App Manager** → **CrewAI
+   App** → open the **Policies** tab → **Edit** and set:
+   - **Permitted Users:** All users may self-authorize
+   - **IP Relaxation:** Relax IP restrictions
+   - **Refresh Token Policy:** Refresh token is valid until revoked
+5. Save.
+6. Return to CrewAI AMP and click **Connect Salesforce** again. OAuth will
+   complete this time.
+
+<Note>
+  **Not a Salesforce admin?** Forward the install page URL (or the install
+  link itself) to your Salesforce admin and ask them to complete the steps
+  above. Once they're done, return to CrewAI AMP and click **Connect** again.
+</Note>

 ### 2. Install Required Package

--- a/docs/ko/enterprise/integrations/salesforce.mdx
+++ b/docs/ko/enterprise/integrations/salesforce.mdx
@@ -17,16 +17,60 @@ Salesforce 통합을 사용하기 전에 다음을 확인하세요:
 - 적절한 권한이 있는 Salesforce 계정
 - [통합 페이지](https://app.crewai.com/integrations)를 통해 Salesforce 계정 연결

+<Note>
+  Salesforce는 사용자가 연결하기 전에 **관리자가 CrewAI 패키지를 한 번 설치**
+  해야 합니다. 이는 Spring '26 릴리스부터 모든 ExternalClientApp 기반 통합에
+  적용되는 Salesforce 플랫폼의 요구 사항이며, CrewAI 고유의 단계가 아닙니다.
+  CrewAI AMP의 Connect Salesforce 플로우가 첫 연결 시 이 과정을 안내합니다.
+</Note>
+
 ## Salesforce 통합 설정

 ### 1. Salesforce 계정 연결

-1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다.
+1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/unified_tools)으로 이동합니다.
 2. 인증 통합 섹션에서 **Salesforce**를 찾습니다.
-3. **연결**을 클릭하고 OAuth 과정을 완료합니다.
+3. **연결**을 클릭합니다.
+
+이후 동작은 관리자가 조직에 CrewAI 패키지를 이미 설치했는지에 따라 달라집니다:
+
+- **패키지가 이미 설치된 경우:** 곧바로 Salesforce OAuth 동의 화면으로
+  이동합니다. 승인하면 연결이 완료됩니다.
+- **패키지가 아직 설치되지 않은 경우:** **Install CrewAI in Salesforce**
+  페이지가 표시됩니다. 아래의 일회성 설치 단계를 따른 뒤, CrewAI AMP로
+  돌아와 **연결**을 다시 클릭하세요.
+
 4. CRM 및 영업 관리에 필요한 권한을 부여합니다.
 5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.

+#### 일회성 관리자 설치 (Salesforce 관리자 전용)
+
+조직 내 누군가 **Connect Salesforce**를 처음 클릭하면, CrewAI는 CrewAI
+관리형 패키지의 설치 페이지로 리디렉션합니다. Salesforce 관리자가 조직
+전체를 위해 한 번만 설치하면 됩니다.
+
+1. CrewAI 내 설치 페이지에서 **Install in Salesforce**를 클릭합니다.
+   (해당 페이지 URL을 관리자에게 공유해도 됩니다. 설치 링크는 누구든 열 수
+   있도록 동작합니다.)
+2. 관리자 권한으로 Salesforce에 로그인합니다. 샌드박스 환경에서는 URL의
+   `login.salesforce.com`을 `test.salesforce.com`으로 바꾼 뒤 엽니다.
+3. **Install for All Users**를 선택하고, 서드파티 앱 동의 항목을 확인한 뒤
+   **Install**을 클릭합니다.
+4. Salesforce Setup에서 **External Client App Manager** → **CrewAI App** →
+   **Policies** 탭 → **Edit**로 이동하여 다음과 같이 설정합니다:
+   - **Permitted Users:** All users may self-authorize
+   - **IP Relaxation:** Relax IP restrictions
+   - **Refresh Token Policy:** Refresh token is valid until revoked
+5. 저장합니다.
+6. CrewAI AMP로 돌아가 **Connect Salesforce**를 다시 클릭합니다. 이번에는
+   OAuth가 정상적으로 완료됩니다.
+
+<Note>
+  **Salesforce 관리자가 아니신가요?** 설치 페이지의 URL(또는 설치 링크 자체)
+  을 Salesforce 관리자에게 전달하고 위 단계를 진행해 달라고 요청하세요.
+  관리자가 완료하면 CrewAI AMP로 돌아와 **연결**을 다시 클릭하면 됩니다.
+</Note>
+
 ### 2. 필수 패키지 설치

 ```bash
--- a/docs/pt-BR/enterprise/integrations/salesforce.mdx
+++ b/docs/pt-BR/enterprise/integrations/salesforce.mdx
@@ -17,15 +17,65 @@ Antes de usar a integração Salesforce, certifique-se de que você possui:
 - Uma conta Salesforce com permissões apropriadas
 - Sua conta Salesforce conectada via a [página de Integrações](https://app.crewai.com/integrations)

+<Note>
+  O Salesforce exige uma **instalação única feita por um administrador** do
+  pacote CrewAI na sua organização antes que qualquer usuário possa se
+  conectar. Isso é uma exigência da plataforma Salesforce para todas as
+  integrações baseadas em ExternalClientApp a partir da release Spring '26 —
+  não é uma etapa específica da CrewAI. O fluxo Connect Salesforce na CrewAI
+  AMP guia você por esta etapa na primeira vez.
+</Note>
+
 ## Configurando a Integração Salesforce

 ### 1. Conecte sua Conta Salesforce

-1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors)
-2. Encontre **Salesforce** na seção Integrações de Autenticação
-3. Clique em **Conectar** e complete o fluxo OAuth
-4. Conceda as permissões necessárias para gerenciamento de CRM e vendas
-5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
+1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/unified_tools).
+2. Encontre **Salesforce** na seção Integrações de Autenticação.
+3. Clique em **Conectar**.
+
+O que acontece em seguida depende de o administrador Salesforce já ter
+instalado o pacote CrewAI na sua organização:
+
+- **Pacote já instalado:** você será levado diretamente à tela de consentimento
+  OAuth do Salesforce — aprove e a conexão estará feita.
+- **Pacote ainda não instalado:** você verá uma página **Install CrewAI in
+  Salesforce**. Siga as etapas de instalação única abaixo e, depois, volte à
+  CrewAI AMP e clique em **Conectar** novamente.
+
+4. Conceda as permissões necessárias para gerenciamento de CRM e vendas.
+5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations).
+
+#### Instalação única pelo administrador (apenas admin Salesforce)
+
+Na primeira vez que alguém na sua organização clica em **Connect Salesforce**,
+a CrewAI redireciona para uma página de instalação que aponta para o pacote
+gerenciado CrewAI. Um administrador Salesforce precisa instalá-lo uma única
+vez para toda a organização.
+
+1. Na página de instalação dentro da CrewAI, clique em **Install in
+   Salesforce**. (Você também pode compartilhar a URL dessa página com seu
+   administrador — o link de instalação funciona para qualquer pessoa que o
+   abra.)
+2. Entre no Salesforce como administrador. Para sandboxes, troque
+   `login.salesforce.com` por `test.salesforce.com` na URL antes de abrir.
+3. Escolha **Install for All Users**, confirme o aviso sobre aplicativos de
+   terceiros e clique em **Install**.
+4. No Setup do Salesforce, busque **External Client App Manager** → **CrewAI
+   App** → abra a aba **Policies** → **Edit** e configure:
+   - **Permitted Users:** All users may self-authorize
+   - **IP Relaxation:** Relax IP restrictions
+   - **Refresh Token Policy:** Refresh token is valid until revoked
+5. Salve.
+6. Volte à CrewAI AMP e clique em **Connect Salesforce** novamente. Desta vez
+   o OAuth será concluído.
+
+<Note>
+  **Não é administrador Salesforce?** Encaminhe a URL da página de instalação
+  (ou o link de instalação em si) para o seu administrador e peça que ele
+  conclua as etapas acima. Quando ele terminar, volte à CrewAI AMP e clique
+  em **Conectar** novamente.
+</Note>

 ### 2. Instale o Pacote Necessário