Documentation · Opengency

Démarrage rapide

Inscrivez-vous et connectez-vous à l’application Web.
Créez un workflow : le canevas contient déjà un nœud « Déclencheur », qui en est le point de départ.
Ajoutez un nœud « Action » par glisser-déposer, choisissez un connecteur (par exemple, e-mail) et renseignez ses paramètres.
Reliez le nœud de déclencheur au nœud d’action, puis enregistrez.
Cliquez sur Exécuter, saisissez des données de test et consultez le résultat de chaque nœud dans le journal d’exécution.

Guide de création des workflows

Un workflow comprend trois types de nœuds :

Déclencheur : point de départ — chaque workflow en possède exactement un. Les données reçues au moment de l’exécution deviennent sa sortie.
Condition : prend une décision et propose les sorties « Oui » et « Non » ; seule la branche correspondante est exécutée.
Action : appelle un connecteur, par exemple pour envoyer un e-mail, appeler une API ou écrire dans une base de données.

À l’enregistrement, les vérifications portent sur la présence d’un seul déclencheur, le raccordement des deux extrémités de chaque connexion, l’absence de cycles, les sorties Oui/Non des conditions et le renseignement des champs obligatoires de chaque action. Les problèmes sont listés un par un.

À l’exécution, le workflow suit les connexions à partir du déclencheur. Si un nœud échoue, l’exécution entière s’arrête immédiatement et est marquée comme échouée.

Conditions

Une condition comprend une valeur de gauche, un opérateur et une valeur de droite ; chaque valeur peut être fixe ou être une référence (voir la section suivante).

Opérateur	Signification	Exemple
eq / ne	égal à / différent de	$.input.status eq "paid"
gt / gte	supérieur à / supérieur ou égal à	$.input.amount gt 1000
lt / lte	inférieur à / inférieur ou égal à	$.input.stock lt 10
in	la valeur de gauche figure dans la liste de droite	$.input.city in ["北京", "上海"]
contains	la valeur de gauche contient la valeur de droite	$.input.tags contains "VIP"
exists	le champ existe et n’est pas vide	$.input.coupon exists

Si le champ référencé n’existe pas, l’opérateur exists renvoie « Non » ; tous les autres opérateurs renvoient également « Non ».

Transférer des valeurs entre les nœuds

Dans les paramètres d’une condition ou d’une action, toute valeur commençant par $. est remplacée par les données au moment de l’exécution :

$.input.amount          运行时传入数据的 amount 字段
$.query.data.0.name     节点 query 输出中 data 列表第 1 项的 name
$.notify.status         节点 notify 输出的 status

Si la valeur entière d’un champ est exactement une référence, le type d’origine est conservé (nombres, listes et objets fonctionnent). Pour insérer des données au milieu d’un texte, utilisez {{$.path}} :

大额订单 {{$.input.order_id}}：金额 {{$.input.amount}}，请风控复核

Les chaînes sont insérées telles quelles ; les nombres, listes et objets sont convertis en JSON ; les valeurs vides restent vides.
Si le chemin n’existe pas, rien n’est inséré (une référence utilisée seule devient vide). Le nœud ne passe pas en échec, mais l’absence est signalée à l’étape correspondante dans le journal d’exécution.
Seules les valeurs commençant par $. sont considérées comme des références ; « 100 $ de réduction », par exemple, reste du texte brut.
L’objet et le corps des e-mails prennent aussi en charge les modèles {{variable}} ; les variables proviennent de la sortie d’un nœud en amont.

Guide des connecteurs

Où trouver l’adresse et les identifiants de chaque connecteur, consulter sa documentation officielle et résoudre les erreurs courantes. Le panneau « Où trouver ces informations ? » au-dessus de chaque formulaire de connecteur dans l’application présente une version abrégée de ce guide.

HTTP

Étapes de configuration

Préparez l’URL du point de terminaison (url) et la méthode de requête (GET, POST, …).
Si l’API nécessite une authentification, choisissez basic ou bearer dans auth_type, puis saisissez le nom d’utilisateur et le mot de passe ou le jeton. Ne placez pas de secrets directement dans les en-têtes : ils seraient enregistrés en texte brut.

Documentation officielle ↗

Obligatoire: url
Facultatif: method (GET par défaut), headers, body, query_params, auth_type (none / basic / bearer), timeout, retries

Si body est vide, la sortie du nœud précédent est envoyée. Seules les adresses publiques sont accessibles.

Erreurs courantes

« Adresse non publique » : l’adresse cible est interne ou locale (y compris après une redirection) et a été bloquée pour des raisons de sécurité.
Seules les URL http et https sont prises en charge.
Si body est vide, la sortie du nœud précédent est envoyée.
Le délai d’expiration est de 30 secondes par défaut et ne peut pas dépasser 60 secondes.

DingTalk

Étapes de configuration

Dans le groupe DingTalk, ouvrez Paramètres du groupe → Assistant de groupe → Ajouter un robot → Personnalisé (via webhook).
Pour sécuriser le robot, choisissez Signature ou Mots-clés personnalisés (vous pouvez activer les deux). Avec Signature, copiez dans secret la clé commençant par SEC. Avec les mots-clés, indiquez un mot qui figurera toujours dans les messages et ajoutez aussi Opengency comme mot-clé, car « Tester la connexion » envoie le texte fixe « Opengency 连接测试 ».
Copiez l’URL webhook générée dans webhook_url.

Documentation officielle ↗

Obligatoire: webhook_url
Facultatif: secret (clé de signature), msg_type (text / markdown / link / card), message, at_mobiles, at_all

Récupérez webhook_url dans les paramètres du groupe DingTalk → Assistant de groupe → Ajouter un robot. « Tester la connexion » envoie réellement un message au groupe, avec le texte fixe « Opengency 连接测试 ». Si le robot utilise des mots-clés personnalisés, Opengency doit en faire partie ; sinon, le test échouera à cause d’une incompatibilité de mot-clé. Cette exigence ne s’applique pas si seule la signature est activée.

Erreurs courantes

Échec de signature (sign not match) : le robot utilise une signature, mais secret est vide ou incorrect. Saisissez la clé de signature commençant par SEC, et non l’access_token figurant dans l’URL webhook.
Incompatibilité de mot-clé : le message ne contient aucun des mots-clés du robot. Ajoutez un mot-clé au message ou configurez le robot avec un mot-clé qui y figurera.
Horodatage invalide : l’horloge du serveur Opengency diffère de celle de DingTalk de plus d’une heure. Corrigez l’heure du serveur.
« Tester la connexion » n’est pas une simulation : le message « Opengency 连接测试 » est réellement envoyé au groupe.

WeCom

Étapes de configuration

Dans le groupe WeCom, ouvrez « … » en haut à droite → Robots de groupe → Ajouter un robot.
L’URL webhook s’affiche dès que le robot est créé.
Copiez cette URL dans webhook_url.

Documentation officielle ↗

Obligatoire: webhook_url
Facultatif: msg_type (text / markdown / card), message, at_mobiles, at_all, url et title (pour les cartes)

Récupérez webhook_url dans votre groupe WeCom → Robot de groupe. La clé incluse dans l’URL est l’identifiant secret. Les mentions @ ne fonctionnent qu’avec le type text. « Tester la connexion » envoie réellement un message au groupe.

Erreurs courantes

La clé incluse dans l’URL webhook est l’identifiant secret : toute personne qui possède cette URL peut écrire dans le groupe. En cas de fuite, supprimez le robot du groupe et créez-en un nouveau.
Les mentions @ ne fonctionnent qu’avec le type text. Le type card nécessite aussi url (destination du lien de la carte) ; sans ce champ, l’enregistrement échoue.
WeCom limite la fréquence des messages des robots ; s’ils publient trop souvent, les envois sont interrompus. Évitez de planifier des exécutions trop rapprochées.
« Tester la connexion » envoie réellement un message au groupe.

Feishu

Étapes de configuration

Dans le groupe Feishu, ouvrez Paramètres → Robots de groupe → Ajouter un robot → Robot personnalisé.
Pour renforcer la sécurité, activez Vérification de signature et saisissez dans secret le secret affiché sur cette page. Les mots-clés personnalisés sont également pris en charge ; ajoutez-y Opengency.
Copiez l’URL webhook générée dans webhook_url.

Documentation officielle ↗

Obligatoire: webhook_url
Facultatif: secret (si la vérification de signature est activée), msg_type (text / post / markdown / card), message, title, at_open_ids, at_all

Récupérez webhook_url dans les paramètres du groupe Feishu → Robots de groupe → Robot personnalisé. « Tester la connexion » envoie réellement un message au groupe.

Erreurs courantes

La vérification de signature est activée, mais secret est vide ou incorrect : Feishu rejette le message (échec de la vérification). Vous pouvez consulter de nouveau le secret dans les paramètres du robot.
Des mots-clés personnalisés sont définis, mais le message n’en contient aucun : il est rejeté.
at_open_ids attend des open_ids commençant par ou_, et non des numéros de téléphone ou des noms.
« Tester la connexion » envoie réellement un message au groupe.

Slack

Étapes de configuration

Ouvrez https://api.slack.com/apps, créez une application (ou choisissez-en une existante), puis activez Incoming Webhooks dans Features.
Cliquez sur Add New Webhook to Workspace, choisissez le canal de destination et autorisez la connexion.
Copiez l’URL webhook générée (elle commence par https://hooks.slack.com/services/) dans webhook_url.

Documentation officielle ↗

Obligatoire: webhook_url
Facultatif: message, username, icon_emoji, channel

webhook_url est lui-même un identifiant secret : toute personne qui le possède peut publier dans ce canal. Opengency le stocke chiffré et le masque dans l’interface et les journaux. Un webhook créé avec une application Slack actuelle publie toujours dans le canal choisi lors de sa création ; username, icon_emoji et channel sont donc ignorés. Pour publier ailleurs, créez un autre webhook. « Tester la connexion » publie réellement un message dans le canal.

Erreurs courantes

no_service : le webhook a été supprimé ou désactivé, ou l’adresse est incorrecte. Vérifiez la page Incoming Webhooks de l’application, recréez le webhook si nécessaire et mettez à jour la connexion.
channel_not_found : le canal n’existe pas ou le webhook n’y a pas accès. Vérifiez le nom du canal ou recréez le webhook pour le bon canal.
channel_is_archived : le canal est archivé. Désarchivez-le ou utilisez un webhook associé à un autre canal.
action_prohibited : un administrateur de l’espace de travail a limité les actions possibles avec ce webhook. Contactez votre administrateur Slack.
invalid_payload ou no_text : le message est vide ou mal formé. Vérifiez que message n’est pas vide.
HTTP 429 : vous publiez trop souvent et Slack limite la fréquence. Réessayez plus tard et évitez de planifier des exécutions trop rapprochées.
« Tester la connexion » n’est pas une simulation : le message « Opengency connection test » est réellement publié dans le canal.

Teams

Étapes de configuration

Dans Teams, ouvrez le canal de destination → « … » à côté du nom du canal → Workflows.
Choisissez le modèle « Send webhook alerts to a channel », sélectionnez l’équipe et le canal lorsque vous y êtes invité, puis enregistrez.
Après la création, copiez l’URL webhook depuis la page de détails du flux dans webhook_url.

Documentation officielle ↗

Obligatoire: webhook_url
Facultatif: message, title

webhook_url est lui-même un identifiant secret (sig dans l’adresse est la signature du flux) ; Opengency le stocke chiffré et le masque dans l’interface et les journaux. Seuls les webhooks Workflows (Power Automate) sont pris en charge. Les anciens webhooks du connecteur Office 365 (outlook.office.com/webhook/…) sont retirés par Microsoft et ne sont pas pris en charge. Les messages sont envoyés sous forme d’Adaptive Card : title est le titre en gras en haut de la carte et message en constitue le corps (le Markdown de base est pris en charge). Un message ne peut pas dépasser 28 Ko ; un corps trop long est tronqué. « Tester la connexion » publie réellement un message de test dans le canal.

Erreurs courantes

HTTP 401 / 403 (adresse invalide ou révoquée) : la signature de l’URL webhook est incorrecte ou a été régénérée. Ouvrez le flux dans Teams, copiez l’adresse la plus récente et mettez à jour la connexion.
HTTP 404 (flux introuvable) : le flux a peut-être été supprimé. Recréez-le à partir du modèle et mettez à jour l’adresse dans la connexion.
Message indiquant que le flux est désactivé ou arrêté : réactivez-le dans l’application Teams Workflows ou Power Automate. Un flux appartient à son créateur et peut être désactivé si celui-ci quitte l’organisation ou si son compte est désactivé ; demandez à un administrateur de le transférer à quelqu’un d’autre.
HTTP 400 (le déclencheur a refusé le message) : vérifiez que le flux a été créé à partir du modèle « Send webhook alerts to a channel », que son déclencheur est When a Teams webhook request is received et que le format des messages acceptés n’a pas été modifié.
HTTP 429 : Teams limite la fréquence des webhooks (environ quatre requêtes par seconde) et rejette les envois trop fréquents. Réessayez plus tard et évitez de planifier des exécutions trop rapprochées.
« Tester la connexion » n’est pas une simulation : le message « Opengency connection test » est réellement publié dans le canal.

E-mail

Étapes de configuration

Activez SMTP dans les paramètres de votre fournisseur de messagerie.
Générez un mot de passe d’application (certains fournisseurs l’appellent code d’autorisation). La plupart des fournisseurs, notamment Gmail, Outlook et Yahoo, n’autorisent pas les applications tierces à envoyer des e-mails avec votre mot de passe de connexion.
Notez le serveur SMTP et le port, par exemple smtp.gmail.com:587 ou smtp.qq.com:465.
Indiquez votre adresse dans sender_email et le mot de passe d’application de l’étape 2 dans sender_password.

Documentation officielle ↗

Obligatoire: smtp_server, sender_email, sender_password, to
Facultatif: smtp_port (587 par défaut), smtp_ssl (auto / implicit / starttls / none), use_tls, cc, bcc, subject, body, format (text / html / markdown)

subject et body prennent en charge les modèles {{variables}} ; les variables proviennent de la sortie d’un nœud précédent. La plupart des fournisseurs exigent un mot de passe d’application plutôt que votre mot de passe de connexion.

Erreurs courantes

Échec de l’authentification : sender_password contient votre mot de passe de connexion. Utilisez plutôt un mot de passe d’application ou un code d’autorisation.
Délai de connexion dépassé ou échec de négociation : le port et le chiffrement ne correspondent pas. Le port 465 utilise TLS implicite et le port 587 STARTTLS ; avec smtp_ssl réglé sur auto, le mode adapté est choisi selon le port, il est donc rarement nécessaire de le modifier.
« Adresse non publique » : le serveur SMTP pointe vers une adresse interne ou locale (cas fréquent avec les serveurs de messagerie internes) et est bloqué pour des raisons de sécurité. Utilisez un serveur SMTP accessible depuis l’Internet public.
Le champ to doit contenir au moins un destinataire ; séparez les adresses multiples par des virgules.

SQLite

Étapes de configuration

Aucun compte ni mot de passe n’est nécessaire : le fichier de base de données se trouve dans votre propre répertoire de données.
Indiquez uniquement un nom de fichier dans database_path, par exemple orders.db. Le fichier est créé s’il n’existe pas.

Documentation officielle ↗

Obligatoire: database_path, sql
Facultatif: params, operation (select / insert / update / delete / execute), return_type (dict par défaut), timeout

database_path n’a besoin que d’un nom de fichier (par ex. orders.db) : le fichier est automatiquement placé dans votre propre répertoire de données. Utilisez des espaces réservés ? dans SQL et indiquez les valeurs dans params.

Erreurs courantes

« no such table » : une faute dans le nom du fichier ne produit pas d’erreur fichier introuvable. Une nouvelle base vide est créée à la place, donc la table n’existe pas. Vérifiez d’abord le nom du fichier.
database_path doit contenir uniquement un nom de fichier. La base reste dans votre propre répertoire de données et ne peut pas accéder à d’autres fichiers.
Utilisez des espaces réservés ? et indiquez les valeurs dans params.

MySQL

Étapes de configuration

Préparez l’hôte, le port (3306 par défaut), l’utilisateur, le mot de passe et le nom de la base de données.
Créez un compte dédié à cette connexion dans la base de données ; s’il ne doit exécuter que des requêtes, accordez-lui uniquement le privilège SELECT.
Vérifiez que la base est accessible depuis l’Internet public : le pare-feu ou le groupe de sécurité de votre fournisseur cloud doit autoriser ce port.

Documentation officielle ↗

Obligatoire: host, user, password, database, sql
Facultatif: port (3306 par défaut), ssl (disabled / required / verify), params, read_only (activé par défaut), max_rows (1000 par défaut), timeout

Utilisez des espaces réservés %s dans SQL et indiquez les valeurs dans params (un signe % littéral doit être écrit %% lorsque params est utilisé). Le mode lecture seule est activé par défaut : désactivez read_only pour écrire. Pour les nœuds en lecture seule, utilisez un compte disposant uniquement du privilège SELECT. Une seule instruction est exécutée à la fois et seules les adresses publiques sont accessibles.

Erreurs courantes

« Adresse non publique » : l’hôte est une adresse interne (10.x, 172.16–31.x, 192.168.x, 127.0.0.1). Le connecteur ne peut accéder qu’aux adresses publiques ; la base doit donc disposer d’un point de terminaison public.
Les écritures sont refusées : read_only est activé par défaut et la requête est exécutée dans une transaction en lecture seule. Désactivez read_only si vous devez réellement écrire et vérifiez que le compte dispose des droits d’écriture.
Les résultats sont incomplets : 1 000 lignes au maximum sont renvoyées par défaut (max_rows peut aller jusqu’à 10 000). Les lignes supplémentaires sont coupées et le résultat est marqué comme tronqué.
Une seule instruction SQL est exécutée à la fois. Utilisez des espaces réservés %s et transmettez les valeurs dans params ; ne concaténez pas les valeurs à la chaîne SQL.
Délai de connexion dépassé : le pare-feu ou le groupe de sécurité n’autorise probablement pas le port.

Webhook

Étapes de configuration

Préparez une URL publique qui accepte les requêtes POST et indiquez-la dans webhook_url.
Si le destinataire doit vérifier que la requête provient de votre workflow, convenez d’un secret et indiquez-le dans secret_key.
Côté réception : chaque requête contient X-Webhook-Timestamp ; si secret_key est défini, elle contient aussi X-Webhook-Signature, le HMAC-SHA256 hexadécimal de (timestamp + "." + raw_body) calculé avec ce secret.

Obligatoire: webhook_url
Facultatif: secret_key, verify_signature, event_types, retry_count, timeout

Lorsque secret_key est défini, les requêtes contiennent un en-tête X-Webhook-Signature (HMAC-SHA256) que le destinataire peut vérifier.

Erreurs courantes

« Tester la connexion » envoie réellement un événement de type ping au destinataire.
Une réponse 4xx ou 500, ou un délai d’attente dépassé, ne déclenche pas de nouvelle tentative (le destinataire a peut-être déjà traité la requête). Les nouvelles tentatives ne concernent que les codes 429, 502, 503, 504 et les connexions qui n’ont jamais été établies.
« Adresse non publique » : l’URL de réception est interne ou locale.
Si event_types est vide, tous les événements sont transmis. Dès qu’il contient des valeurs, les événements dont event_type ne figure pas dans la liste sont ignorés.

Restriction de sécurité : HTTP, DingTalk, WeCom, Feishu, Slack, Teams, e-mail, MySQL et webhook ne peuvent accéder qu’à des adresses publiques (les adresses internes comme 127.0.0.1, 10.x et 192.168.x sont refusées) ; SQLite ne peut accéder qu’à votre propre répertoire de données.

Clés API

Les clés API permettent à des scripts et à d’autres systèmes d’appeler l’API, par exemple pour lancer un workflow à partir d’un script planifié. Créez une clé dans l’application, sous Compte → Clés API. La clé complète n’est affichée qu’une seule fois : enregistrez-la immédiatement. Ensuite, la liste n’en montre que les premiers caractères pour l’identifier. Limites : 1 pour Free, 5 pour Pro, un nombre illimité pour Business et Enterprise (seules les clés non révoquées sont comptabilisées).

curl -X POST https://app.opengency.ai/api/executions/workflows/<工作流 ID>/execute \
  -H "Authorization: Bearer ofk_…" \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"order_id": 7}}'

Une clé dispose des mêmes autorisations que le compte qui l’a créée. Les exécutions lancées avec elle sont indiquées comme « API » dans le journal, avec les premiers caractères de la clé.
La gestion des clés API, le changement de mot de passe et la suppression du compte nécessitent le mot de passe du compte ; une clé API ne peut effectuer aucune de ces opérations.
La révocation d’une clé prend effet immédiatement (les requêtes renvoient 401). Le changement de mot de passe ne révoque pas les clés existantes. Si vous pensez qu’une clé a été divulguée, révoquez-la individuellement.
Conservez les clés uniquement côté serveur. Ne les placez jamais dans le code Web côté client et ne les partagez pas dans une conversation.

Questions fréquentes

Pourquoi mon nœud HTTP indique-t-il « adresse non publique » ?: L’adresse cible est interne ou locale et a été bloquée par mesure de sécurité. Utilisez une adresse accessible publiquement.
Puis-je recevoir une notification en cas d’échec d’un workflow ?: Oui, avec toutes les formules. Dans Compte → Notifications d’échec, choisissez votre adresse e-mail de compte ou une connexion enregistrée à DingTalk, WeCom, Feishu ou par e-mail. Les échecs survenant dans un intervalle d’environ 10 minutes sont regroupés dans un seul message, qui indique le nombre d’échecs par workflow, le nœud concerné et un lien vers les détails. Les exécutions annulées manuellement ne déclenchent pas de notification.
Les workflows peuvent-ils boucler ?: Pas pour le moment : les workflows ne peuvent pas former de cycle. Si vous essayez, le problème sera signalé à l’enregistrement.
Les workflows peuvent-ils s’exécuter selon un calendrier ?: Oui. Dans l’éditeur, choisissez « Planifié » comme déclencheur, sélectionnez une fréquence (toutes les N minutes, toutes les heures, chaque jour ou chaque semaine) ou saisissez une expression cron, puis choisissez un fuseau horaire. Enregistrez le workflow, puis activez l’interrupteur « Activé » sur sa page de détails. Free permet d’avoir un workflow planifié actif à la fois ; Pro en autorise 10.