Connecteurs de ticketing

Vaks PM · Guide d'intégration · Tickets externes · Juillet 2026

Ce que vous obtiendrez. Des personnes saisissant du temps dans leur timesheet Vaks PM sur des tickets qui vivent dans un outil externe — ServiceNow aujourd'hui — trouvés par une recherche depuis la timesheet elle-même, sans que ces tickets n'encombrent jamais vos projets.

Ce que ça fait — et ce que ça ne fait pas

Ce connecteur a une seule mission : permettre à quelqu'un d'enregistrer du temps sur un ticket qui appartient à un autre système. Il est volontairement étroit, et les limites sont le cœur du sujet.

Il n'importe pas les tickets comme des projets. Un ticket référencé devient une tâche légère dans un conteneur invisible, uniquement pour que du temps puisse s'y rattacher.
Le ticket n'apparaît que dans la timesheet. Pas dans les listes de projets, pas dans les rapports, pas dans le plan de charge ni la planification de capacité. Le temps saisi remonte, lui, dans l'export de facturation.
Il n'y a pas de synchronisation bidirectionnelle. Vaks PM n'écrit jamais vers le système de ticketing et ne change jamais le statut d'un ticket. Il lit, pour vous aider à trouver le ticket ; c'est tout.
Il est agnostique au fournisseur par conception, avec ServiceNow livré aujourd'hui. Ajouter un autre outil plus tard ne change rien à la façon dont vous saisissez du temps.
Aucune licence requise, et les agents ne peuvent jamais l'utiliser — la saisie de temps est une permission réservée aux humains.

Prérequis

Côté	Ce qu'il vous faut
ServiceNow	Un compte de service avec un accès en lecture, via la Table API, aux tables que vous voulez rendre cherchables. La lecture seule suffit — le connecteur n'écrit jamais.
Vaks PM	`org:manage` pour configurer le connecteur. Quiconque a la permission de timesheet peut ensuite saisir du temps sur des tickets.
Joignabilité	L'URL de l'instance ServiceNow doit être en HTTPS et résoluble publiquement — un ServiceNow on-premise derrière une adresse privée est refusé par le contrôle anti-SSRF.

Étape 1 — Connecter ServiceNow

Ouvrez Admin → Intégrations → External connectors, pressez Ajouter un connecteur, et choisissez ServiceNow. Les libellés de champs ci-dessous sont affichés en français dans la version actuelle :

Champ	Affiché comme	Quoi renseigner
URL de l'instance	URL de l'instance	Votre instance ServiceNow, par ex. `https://acme.service-now.com`. HTTPS uniquement.
Compte de service	Utilisateur (compte de service)	Le compte de service en lecture seule, par ex. `svc_timesheet`.
Mot de passe	Mot de passe	Son mot de passe. Chiffré at-rest, jamais réaffiché.
Tables à rechercher	Tables à rechercher	Les tables à interroger : Incidents, tâches de catalogue, tâches de changement, problèmes, ou toutes les tâches. Jusqu'à cinq sont interrogées par recherche.
Filtre de base	Filtre de base (optionnel)	Une requête ServiceNow optionnelle pour contraindre les résultats, par ex. `active=true`.

Renseignez aussi le Nom affiché présenté aux utilisateurs, et laissez Activé pour l'étape 2.

Étape 2 — Tester, puis activer

Pressez Tester. Un résultat au vert signifie que les identifiants sont acceptés et que la Table API est joignable.

Optionnel : renseignez la date d'expiration du secret. Le formulaire du connecteur a un champ optionnel Date d'expiration du secret. Si l'identifiant du compte de service tourne à échéance, renseignez-la et Vaks PM envoie un email à vos admins 14 jours avant l'expiration — pour que le connecteur ne casse pas en silence. Laissez vide si l'identifiant n'expire pas.

Un test réussi ne prouve pas la cherchabilité. Le test sonde une table système : un compte de service sans accès à vos tables métier peut donc passer le test et ne rien renvoyer ensuite en recherche. Vérifiez que le compte peut réellement lire les tables que vous avez sélectionnées — la vraie preuve est une recherche qui renvoie des résultats à l'étape 3.

Un connecteur ne peut pas être activé tant que chaque champ obligatoire, y compris le mot de passe stocké, n'est pas présent. Une fois activé, il devient disponible pour les utilisateurs dans la timesheet.

Étape 3 — Saisir du temps sur un ticket

Dans la timesheet, les utilisateurs ouvrent Logger du temps sur un ticket. Deux façons d'atteindre un ticket :

Recherche — saisissez un numéro de ticket ou des mots de sa description ; les résultats viennent en direct de l'outil connecté, fusionnés avec les tickets déjà saisis localement. Choisissez-en un et il est ajouté à la semaine.
Saisie manuelle — quand il n'y a pas de connecteur, ou que le ticket est ailleurs : saisissez l'outil source, la clé du ticket, et en option un titre, un lien et un client. Cela fonctionne sans aucun connecteur.

Dans les deux cas, le ticket atterrit dans la timesheet de la personne avec sa clé externe affichée et un lien de retour vers l'original. Dès lors, il se comporte comme n'importe quelle tâche sur laquelle vous pouvez saisir du temps — et reste invisible partout ailleurs.

La recherche en direct échoue en douceur. Si le connecteur a un problème, la recherche retombe discrètement sur les tickets connus localement plutôt que d'afficher une erreur. Donc si les utilisateurs ne voient jamais que des tickets déjà dans Vaks PM, n'attendez pas un message d'erreur — vérifiez le badge Dernier test en échec du connecteur dans la section d'administration.

Pousser des tickets par API

Une machine peut ajouter des tickets directement — utile pour pré-charger la timesheet d'une personne depuis un flux externe. Postez sur le point de terminaison external-tasks avec une clé d'organisation scopée à la saisie de temps :

POST /api/v1/external-tasks
Authorization: Bearer vaks_org_<your-key>
Content-Type: application/json

{
  "source": "servicenow",
  "key": "INC0042",
  "title": "Payroll export failing",
  "url": "https://acme.service-now.com/nav_to.do?uri=incident.do?sys_id=…",
  "assigneeEmail": "person@example.com"
}

source et key sont obligatoires ; le reste est optionnel. L'appel est idempotent sur le couple (source, key) — re-poster met à jour le titre et le lien et réattribue plutôt que de dupliquer. assigneeEmail, qui doit correspondre à un utilisateur actif, place le ticket dans la timesheet de cette personne ; omettez-le et l'appelant est assigné. Le projet conteneur de chaque couple outil-et-client est créé automatiquement la première fois.

Générez la clé dans Admin → Intégrations → Clés API avec le scope de saisie de temps. Il n'y a pas de scope propre au ticketing — une simple clé d'organisation portant cette permission est ce que le point de terminaison attend.

Dépannage

Les erreurs de test ServiceNow reviennent en français ; elles sont reproduites mot pour mot.

Symptôme	Cause & correctif
Authentification refusée (401) — identifiants invalides.	Mauvais utilisateur ou mot de passe. Revérifiez les identifiants du compte de service.
Accès refusé (403) — droits Table API insuffisants.	Le compte n'a pas les droits Table API. Accordez-lui un accès en lecture.
Délai dépassé.	ServiceNow n'a pas répondu en 8 secondes. Généralement passager ; vérifiez que l'instance est joignable.
Le test passe, la recherche ne renvoie rien	Le compte de service atteint la table système que sonde le test mais pas vos tables métier. Accordez un accès en lecture aux tables que vous avez sélectionnées.
Les utilisateurs ne voient que les tickets connus localement	La recherche en direct a échoué silencieusement. Vérifiez le badge Dernier test en échec du connecteur et re-testez.
Impossible d'activer le connecteur	Un champ obligatoire ou le mot de passe manque. Complétez-les ; l'activation est bloquée tant que tous ne sont pas présents.
Un ServiceNow on-premise ne se connecte pas	Une URL d'instance privée est refusée par le contrôle anti-SSRF. Seule une instance HTTPS résoluble publiquement est acceptée.

À lire aussi : toutes les intégrations · le temps des tickets remonte dans l'export de facturation décrit dans la documentation finance.