Incremental and idempotent
A KV store checkpoint means every incident is collected once. Restarts and reschedules pick up where the last run stopped.
Splunk add-on · Splunkbase app 8411TOPdesk incidents in Splunk.
TOPdesk incidents in Splunk.
Splunk alerts in TOPdesk.
The Add-on for TOPdesk collects TOPdesk incidents into Splunk and creates TOPdesk incidents straight from Splunk alerts. Open source, built on Splunk's UCC framework, by Orange Insight.
How the data flows
Two directions, one add-on.
A modular input polls the TOPdesk REST API and indexes every incident as a JSON event. An alert action goes the other way and opens a ticket in TOPdesk the moment a Splunk alert fires.
TOPdesk
Service management
Incidents inputpolls every 5 minutes, incremental
Alert actioncreates incidents from alerts
Splunk
Enterprise or Cloud
01 / COLLECT
Incident collection
The TOPdesk Incidents modular input polls the incidents API on a schedule you choose and lands every incident as one JSON event with sourcetype topdesk:incident. From there it is ready for spath, dashboards, SLA reporting and correlation with the rest of your Splunk data.
- Schedule: every 5 minutes by default, or any cron expression
- Filter on status (first line, second line or all), priority P1 to P7, category and operator group, optionally open incidents only
- Incremental: a checkpoint in the KV store remembers the newest incident seen, the first run picks up the last 24 hours
- Follows TOPdesk pagination automatically
- Honours Splunk proxy settings and certificate verification, retries transient failures with backoff and stops immediately on authentication errors
02 / CREATE
Incident creation
Add the Create TOPdesk incident action to any Splunk alert, or run it ad hoc with sendalert. The ticket carries the alert data through $result.field$ tokens, so the service desk sees the host, the metric and the threshold instead of a bare notification.
- Fields: brief description, request text, caller e-mail (looked up in TOPdesk), status, priority, branch and category
- Supports $result.field$ tokens so the ticket carries the alert data
- Validates lengths and e-mail format before anything is sent
- Retries only on transient HTTP errors
- Search-head-cluster safe: settings are replicated
Getting started
Up and running in three steps.
Install from Splunkbase, add your TOPdesk credentials once, and both directions are available to every input and alert on that instance.
STEP 01
Configure credentials
On the add-on's configuration page, enter the TOPdesk base URL, the API user name and the application password. The password is stored encrypted in Splunk's credential store.
STEP 02
Create an input
Add a TOPdesk Incidents input on a heavy forwarder or single search head. Choose the interval, the filters and the target index. The first run collects the last 24 hours.
STEP 03
Add the alert action
Open any alert on the search head, add Create TOPdesk incident as a trigger action and map the fields with $result.field$ tokens. Test it ad hoc with sendalert.
Features
Built for operations, not for a demo.
Every design choice in the add-on comes from running Splunk and service desks in production: idempotent collection, secrets that stay secret and runs you can trace end to end.
Filter at the source
Status, priority, category, operator group and open-only filters are applied in the TOPdesk query, so you index what you need and nothing more.
Secrets stay secret
The application password lives encrypted in Splunk's credential store. Nothing sensitive is written to logs, and caller e-mail addresses are masked.
Proxy and certificate aware
The input honours Splunk proxy settings and certificate verification, with retries and backoff for transient failures.
Traceable runs
Every run and every alert execution writes structured log lines with a run id and request id to _internal, ending in a single JSON MONITOR summary. A Monitoring dashboard ships with the app.
Open source
Apache 2.0 licensed, built with the Splunk Add-on Builder on the UCC framework. Install it from Splunkbase, inspect it and extend it for your own fields.
Compatibility
Where it runs.
Listed on Splunkbase as app 8411. Install the input on a heavy forwarder or a single search head, and the alert action on the search head.
Splunk Enterprise9.0 through 10.6, Python 3 runtime
Splunk CloudVictoria and Classic experience
DeploymentInput on a heavy forwarder or single search head, alert action on the search head (search-head-cluster safe)
TOPdeskREST API v1, endpoint /tas/api/incidents
TOPdesk permissionsOperator account with read rights on incidents (collection) and create rights (alert action)
CIM3.x to 6.x
FrameworkSplunk Add-on Builder, UCC
LicenceApache License 2.0
Supportsupport@orangeinsight.io
TOPdesk is a registered trademark of TOPdesk B.V. The add-on is developed independently by Orange Insight and is not affiliated with or endorsed by TOPdesk.
Common questions
FAQ.
Security, proxies, Splunk Cloud and how to get help. Anything missing, mail support and we will add it here.
How are the TOPdesk credentials stored?
The application password is stored encrypted in Splunk's credential store (passwords.conf), never in plain text in a configuration file. Authentication to TOPdesk is HTTP Basic over HTTPS. Secrets never appear in log lines, and caller e-mail addresses are masked.
Does the add-on work through a proxy?
The incidents input honours Splunk's proxy settings and certificate verification, so it runs from environments that reach TOPdesk through an outbound proxy.
Does it work on Splunk Cloud?
Yes. The add-on supports Splunk Cloud on both the Victoria and Classic experience, next to Splunk Enterprise 9.0 through 10.6. On Victoria experience the input runs on the search head; on Classic experience use the inputs data manager or a heavy forwarder.
Which permissions does the TOPdesk API user need?
An operator account with an application password. For collection it needs read rights on incidents, for the alert action it needs create rights. Use a dedicated account per Splunk instance so API usage is easy to audit.
Is the add-on free to use?
Yes. The Add-on for TOPdesk is open source under the Apache License 2.0 and free to install from Splunkbase. Consultancy around it, such as dashboards, alert design or rollout support, is a separate service.
Can you help us roll it out or extend it?
Yes. We built the add-on from our own Splunk practice and can help with dashboards on TOPdesk data, alert design, SLA reporting or custom fields. Get in touch through the contact page or mail support.
Get in touch
Want TOPdesk data working in Splunk?
Whether you are rolling out the add-on, building dashboards on incident data or designing alerts that open the right tickets, we help you get there.