Ticketing connectors

Vaks PM · Integration guide · External tickets · July 2026

What you will end up with. People logging time in their Vaks PM timesheet against tickets that live in an external tool — ServiceNow today — found by searching from within the timesheet, without those tickets ever cluttering your projects.

What it does — and what it does not

This connector has one job: let someone record time against a ticket that belongs to another system. It is deliberately narrow, and the boundaries are the point.

It does not import tickets as projects. A referenced ticket becomes a lightweight task inside an invisible container, purely so time can attach to it.
The ticket appears only in the timesheet. Not in project lists, not in reports, not in workload or capacity planning. Time logged does flow into the billing export.
There is no two-way sync. Vaks PM never writes back to the ticketing system and never changes a ticket's status. It reads, to help you find the ticket; that is all.
It is provider-agnostic by design, with ServiceNow shipping today. Adding another tool later requires no change to how you log time.
No licence required, and agents can never use it — logging time is a human-only permission.

Prerequisites

Side	What you need
ServiceNow	A service account with read access, via the Table API, to the tables you want searchable. Read-only is enough — the connector never writes.
Vaks PM	`org:manage` to configure the connector. Anyone with the timesheet permission can then log time against tickets.
Reachability	The ServiceNow instance URL must be HTTPS and publicly resolvable — an on-premises ServiceNow behind a private address is refused by the anti-SSRF check.

Step 1 — Connect ServiceNow

Open Admin → Integrations → External connectors, press Add a connector, and choose ServiceNow. The field labels below are shown in French in the current release:

Field	Shown as	What to put
Instance URL	URL de l'instance	Your ServiceNow instance, e.g. `https://acme.service-now.com`. HTTPS only.
Service account user	Utilisateur (compte de service)	The read-only service account, e.g. `svc_timesheet`.
Password	Mot de passe	Its password. Encrypted at rest, never shown again.
Tables to search	Tables à rechercher	Which tables to query: Incidents, Catalog tasks, Change tasks, Problems, or All tasks. Up to five are queried per search.
Base filter	Filtre de base (optionnel)	An optional ServiceNow query to constrain results, e.g. `active=true`.

Also set the Display name shown to users, and leave Enabled for step 2.

Step 2 — Test, then enable

Press Test. A green result means the credentials are accepted and the Table API is reachable.

Optional: set the secret expiry date. The connector form has an optional Secret expiry date field. If the service-account credential rotates on a schedule, fill it in and Vaks PM emails your admins 14 days before it lapses — so the connector does not fail silently. Leave it blank if the credential does not expire.

A passing test does not prove searchability. The test probes a system table, so a service account with no access to your business tables can still pass the test and then return nothing in search. Confirm the account can actually read the tables you selected — the real proof is a search returning results in step 3.

A connector cannot be enabled until every required field, including the stored password, is present. Once enabled, it becomes available to users in the timesheet.

Step 3 — Log time on a ticket

In the timesheet, users open Log time on a ticket. Two ways to reach a ticket:

Search — type a ticket number or words from its description; results come from the connected tool live, merged with tickets already logged locally. Pick one and it is added to the week.
Manual entry — when there is no connector, or the ticket is elsewhere: type the source tool, the ticket key, and optionally a title, link and client. This works with no connector at all.

Either way, the ticket lands in the person's timesheet with its external key shown and a link back out to the original. From then on it behaves like any task you can log time against — and stays invisible everywhere else.

Live search fails softly. If the connector has a problem, search quietly falls back to locally-known tickets rather than showing an error. So if users only ever see tickets already in Vaks PM, do not wait for an error toast — check the connector's Last test failed badge in the admin section.

Pushing tickets by API

A machine can add tickets directly — useful to pre-load a person's timesheet from an external workflow. Post to the external-tasks endpoint with an organization key scoped to time logging:

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 and key are required; the rest is optional. The call is idempotent on the (source, key) pair — re-posting updates the title and link and re-assigns rather than duplicating. assigneeEmail, which must match an active user, puts the ticket in that person's timesheet; omit it and the caller is assigned. The container project for each tool-and-client combination is created automatically the first time.

Mint the key in Admin → Integrations → API keys with the time-logging scope. There is no ticketing-specific scope — a plain organization key with that permission is what the endpoint expects.

Troubleshooting

ServiceNow test errors come back in French; they are reproduced verbatim.

Symptom	Cause & fix
Authentification refusée (401) — identifiants invalides.	Wrong user or password. Re-check the service-account credentials.
Accès refusé (403) — droits Table API insuffisants.	The account lacks Table API rights. Grant it read access.
Délai dépassé.	ServiceNow did not answer within 8 seconds. Usually transient; check the instance is reachable.
Test passes, search returns nothing	The service account can reach the system table the test probes but not your business tables. Grant read access to the tables you selected.
Users only see locally-known tickets	Live search failed silently. Check the connector's Last test failed badge and re-test.
Cannot enable the connector	A required field or the password is missing. Complete them; enabling is blocked until all are present.
On-premises ServiceNow will not connect	A private instance URL is refused by the anti-SSRF check. Only a publicly resolvable HTTPS instance is accepted.

Related: all integrations · the ticket time flows into the billing export described in the finance documentation.