Aller au contenu

Services externes — Vue d'ensemble

Les services externes sont les intégrations OAuth que Forra peut appeler au nom des utilisateurs : Google (Gmail, Drive, Calendar), Microsoft (Outlook, SharePoint, OneDrive), Slack, GitHub, Jira, Notion, Figma, etc.

Chaque service est :

  • Activé au niveau du locataire (l'admin choisit lesquels sont disponibles) ;
  • Connecté individuellement par chaque utilisateur (chaque utilisateur autorise Forra à accéder à son compte) ;
  • Utilisé par les assistants et compétences ayant été configurés pour s'y connecter.

Clients OAuth partagés vs personnalisés

Forra fournit des clients OAuth partagés pour la plupart des services courants. Vous n'avez pas à créer votre propre application OAuth — il suffit d'activer le service. Les services actuellement fournis incluent :

  • Google (Gmail, Drive, Calendar, Analytics, Play Developer)
  • Microsoft (Outlook, SharePoint, OneDrive, Teams)
  • Slack
  • GitHub
  • Atlassian (Jira)
  • Notion
  • Figma
  • HubSpot
  • Harvest
  • Mural
  • Airtable
  • Basecamp
  • Forra (API)

Pour tout autre service, ou pour utiliser votre propre application OAuth d'entreprise, voir Service personnalisé.

Les clients partagés sont préconfigurés par l'équipe Forra sur demande : les identifiants OAuth (client_id, client_secret) restent gérés par Forra et ne sont pas exposés dans l'interface du locataire. Côté admin du locataire, vous contrôlez uniquement l'activation, la visibilité et les instructions du service.

Activer un service

Pour les services à client partagé, l'activation se fait en deux temps :

  1. Demander la préconfiguration à l'équipe Forra en précisant le ou les services voulus. Forra active le service avec une visibilité restreinte par défaut (admin uniquement), pour permettre la validation sans exposer le service aux utilisateurs finaux avant qu'il ne soit prêt.
  2. Élargir la visibilité une fois la configuration validée : voir Visibilité d'un service.

Pour un service personnalisé, l'activation se fait directement depuis l'interface — vous fournissez vous-même les identifiants OAuth.

Visibilité d'un service

Chaque service a un contrôle de visibilité indépendant de son activation. Ce contrôle détermine qui peut connecter son compte à ce service depuis Forra.

Options disponibles dans la carte du service :

  • Public — tous les utilisateurs du locataire peuvent se connecter au service.
  • Utilisateurs spécifiques — accès limité à une liste de comptes (par courriel).
  • Groupes spécifiques — accès limité aux membres des groupes choisis. Les groupes proviennent de l'onglet Groupes d'utilisateurs.

Un service nouvellement ajouté est invisible tant qu'une visibilité n'a pas été définie. Penser à mettre la visibilité à Public (ou à attribuer les groupes/utilisateurs voulus) puis enregistrer, sinon personne ne verra le service.

Migration de domaine

Si votre instance Forra change de domaine (ex. passage de monclient.scout.mirego.com vers scout.mirego.com), les Redirect URIs des applications OAuth créées chez les fournisseurs (Google, Microsoft, etc.) doivent être mis à jour. Contacter l'équipe Forra pour la liste des URIs à modifier.

Référence : structure JSON d'un service

À titre indicatif, voici la forme du JSON stocké en interne pour un service OAuth à client partagé. Cette représentation est gérée par l'équipe Forra lors de la préconfiguration ; les administrateurs du locataire ne saisissent pas directement ces valeurs (sauf dans le cas d'un service personnalisé).

{
  "name": "slack",
  "display_name": "Slack",
  "icon_url": "https://files.scout.mirego.com/external-services/slack-icon.png",
  "authorize_url": "https://slack.com/oauth/v2/authorize",
  "access_token_url": "https://slack.com/api/oauth.v2.access",
  "api_base_url": "https://slack.com/api/",
  "client_id": "...",
  "client_secret": "...",
  "client_kwargs": {"scope": ""},
  "authorize_url_params": {
    "user_scope": "channels:history channels:read chat:write users:read"
  },
  "additional_instructions": "Never post to #general unless explicitly asked to.",
  "api_documentation_url": "https://files.scout.mirego.com/external-services/slack.md"
}

Les champs additional_instructions et api_documentation_url influencent directement le comportement des assistants utilisant ce service.