InvGate Service Management Integration Guide

Overview

The InvGate Service Management integration connects NINA workflows to InvGate's service desk platform (formerly InvGate Service Desk), covering the complete Service Desk API v1 surface — 163 operations across 19 resources:

Ticket Management:

• Incident — Create, retrieve, update, and search requests; comments, observers, and collaborators; the full status lifecycle (cancel, reject, reopen, reassign, waiting-for states, solution accept/reject, promote to major incident); approvals; custom fields; links and related CIs
• Attribute — Priority, type, source, and status lookups for populating ticket fields
• Category — Request category listings

Organization & Users:

• User — Lookup by ID/email/username plus full administration (create, update, enable/disable, convert, password management, session tokens)
• Group / Company / Location — Membership and observer management
• Help Desk / Level — Help desk, level, and observer listings

Content & Configuration:

• Knowledge Base — Articles, categories, and attachments
• Custom Field — Field definitions and list/tree option management
• Internal Note / Time Tracking / Breaking News — Supporting service desk content
• Trigger / CI / Data Export / Workflow / System — Automation triggers, configuration items, exports, workflow deployment, and instance info

Authentication uses HTTP Basic auth with a dedicated API username/password pair generated by your InvGate instance. All resources share the same credential.

Note: InvGate ships two products with separate APIs. This integration covers Service Management (service desk/ticketing). Asset Management (formerly Insight) is a different API and is not part of this integration.

---

Credential Configuration

Authentication

Field	Description	Example
Username	API username from your InvGate instance	sd-user-xxxxxx
Password	API password paired with the username	********
Base URL	Your instance's API endpoint	https://yourcompany.cloud.invgate.net/api/v1

How to Get Your InvGate API Credentials

1. Log in to your InvGate Service Management instance as an administrator
2. Navigate to Settings → Integrations API → Credentials and copy the API username and password
3. Navigate to Settings → Integrations API → Resources and copy the Base URL (it already includes the /api/v1 path)

Notes:

• The API credentials are separate from your normal InvGate user login — UI usernames/passwords will not work against the API
• The base URL is instance-specific (https://<instance>.cloud.invgate.net/api/v1); there is no shared global endpoint

Creating a Credential in NINA

1. Navigate to Credentials → Add New Credential
2. Select integration service: InvGate Service Management
3. Auth type: Basic Authentication
4. Fill in Username, Password, and Base URL
5. Click Test Connection then Save

The connection test calls InvGate's lightweight /sd.version endpoint to verify the credentials without touching any ticket data.

---

Supported Resources and Operations

Incident

Manage service desk requests (tickets) — create, retrieve, update, search, comment, approvals, links, observers, and lifecycle transitions.

Core ticket operations

Operation	HTTP	Description	Required params
create	POST /incident	Creates a new request in the system (use setCustomField to add custom field values afterwards)	creator_id, type_id, customer_id, title, category_id, priority_id
get	GET /incident	Returns the information of the given request	id
update	PUT /incident	Change attributes of a request	id
search	GET /incidents	Lists the requests	ids
searchByStatus	GET /incidents.by.status	Lists all open requests matching the status specified by parameter	—
searchByAgent	GET /incidents.by.agent	Lists the requests from a given agent	—
searchByCustomer	GET /incidents.by.customer	Lists the open requests from a customer	—
searchByHelpdesk	GET /incidents.by.helpdesk	Lists the open requests from a help desk	—
searchByCIs	GET /incidents.by.cis	Returns all the requests linked to a CI, considering its IDs, its groups and the ID of the integration it belongs to	ci_ids, group, cis_source_id
searchBySentiment	GET /incidents.by.sentiment	Lists the open requests from a sentiment	—
searchByView	GET /incidents.by.view	Lists the requests from a view ID	view_id
searchDetailsByView	GET /incidents.details.by.view	Lists the requests with their details from a view ID	view_id
searchLastHour	GET /incidents.last.hour	Lists all the requests that were created within the last hour	—
getStatus	GET /incident.attributes.status	Lists all the status. If an ID is provided, only the one that matches the specified ID will be listed	—

Comments, observers & collaborators

Operation	HTTP	Description	Required params
addComment	POST /incident.comment	Adds a reply to a request	comment, author_id, request_id
getComments	GET /incident.comment	Gets the replies from a given request	request_id
getObservers	GET /incident.observer	Lists all the IDs of the request's observers	request_id
addObserver	POST /incident.observer	Adds a user as observer	request_id, author_id
getCollaborators	GET /incident.collaborator	Lists the collaborators IDs	request_id
addCollaborator	POST /incident.collaborator	Requests collaboration from the defined user	request_id, author_id

Lifecycle & status transitions

Operation	HTTP	Description	Required params
cancel	POST /incident.cancel	Cancel a request	request_id, author_id
reject	POST /incident.reject	Rejects a request	request_id, author_id
reopen	PUT /incident.reopen	Reopens a request	request_id
reassign	POST /incident.reassign	Reassigns a request to a help desk and/or agent	request_id, author_id, group_id
waitingForAgent	POST /incident.waitingfor.agent	Sets the agent waiting status to the request	request_id
waitingForCustomer	POST /incident.waitingfor.customer	Sets the waiting for customer status to the request	request_id
waitingForDate	POST /incident.waitingfor.date	Sets the waiting for date status to the request	request_id, timestamp
waitingForIncident	POST /incident.waitingfor.incident	Sets the request in the waiting for another request status	request_id, wait_request_id
waitingForExternalEntity	POST /incident.waitingfor.external_entity	Sets the request in the waiting for external entity status. The entity should be already linked	request_id, entity_link_id
acceptSolution	PUT /incident.solution.accept	Accepts the solution of a request	id, rating
rejectSolution	PUT /incident.solution.reject	Rejects the solution of a request	id, comment
promoteToMajorIncident	POST /incident.promote.to.major.incident	Promotes the given request to a major incident and returns the ID of the created major incident	request_id, author_id

Approvals

Operation	HTTP	Description	Required params
getApprovals	GET /incident.approval	Lists the approvals instances that the given request has	request_id
acceptApproval	PUT /incident.approval.accept	Accepts an approval	user_id, approval_id
rejectApproval	PUT /incident.approval.reject	Rejects an approval	user_id, approval_id
cancelApproval	PUT /incident.approval.cancel	Cancels an approval	user_id, approval_id
addApprovalVoter	POST /incident.approval.add_voter	Adds a voter to an approval	user_id, approval_id
getApprovalPossibleVoters	GET /incident.approval.possible_voters	Lists users that could accept or reject the approval	approval_id
listApprovalStatuses	GET /incident.approval.status	Lists the statuses of the approvals	—
listApprovalTypes	GET /incident.approval.type	Lists the available approvals types	—
listApprovalVoteStatuses	GET /incident.approval.vote_status	Lists the status of the approval votes	—
getCustomApprovals	GET /incident.custom_approval	Lists the custom approvals templates that the given request has	request_id
createCustomApproval	POST /incident.custom_approval	Requests a custom approval in the given request	request_id, author_id, approval_id
addSpontaneousApproval	POST /incident.spontaneous_approval	Creates a spontaneous approval	request_id, author_id, description, approval_user_id

Custom fields, links & related data

Operation	HTTP	Description	Required params
setCustomField	POST /incident.custom_field	Creates values for a custom field from a request. Different types of data can be sent in the values variable. No value (empty string) means erase value. When sending files, the name of the file has to be in the values array (including its extension), and the file(s) itself should be sent in the body of the request	request_id, values, custom_field_uid, author_id
patchCustomField	PATCH /incident.custom_field	Add values for a multiple custom field from a request. This only works for the custom field with type CI. It can only be sent one CI name at a time in the values variable. It must be the complete name of the CI and all the CIs that have that exact name will be added to the multiple custom field	—
deleteCustomField	DELETE /incident.custom_field	Deletes value in the associated custom field	—
getLinks	GET /incident.link	Lists all the linked requests from a given request	request_id
addLink	POST /incident.link	Links a request to another request	request_id, request_ids
relateCIByKeyword	POST /incident.relate.ci.by.keyword	Relates a request to every CI that matches a certain keyword	request_id, keyword
getLinkedCIsCounters	GET /incident.linked_cis.counters.from	Returns counters with the number of incidents of each status	from, cis_source_id
getExternalEntities	GET /incident.external_entity	Lists all the external entities linked to a request	request_id
addExternalEntity	POST /incident.external_entity	Links a request to an external entity	request_id, external_entity_id
getAttachments	GET /incident.attachment	Returns the requested attachment	id
getTasks	GET /incident.tasks	Retrieves the list of tasks linked to a specified request	request_id

Attribute

Request attribute lookups: priorities, types, sources, and statuses.

Operation	HTTP	Description	Required params
listPriorities	GET /incident.attributes.priority	Lists all the priorities, or only one if an ID its provided	—
listSources	GET /incident.attributes.source	Lists all the sources. If an ID is provided, only the one that matches the specified ID will be listed	—
listStatuses	GET /incident.attributes.status	Lists all the status. If an ID is provided, only the one that matches the specified ID will be listed	—
listTypes	GET /incident.attributes.type	Lists all the types. If an ID is provided, only the one that matches the specified ID will be listed	—

Category

List request categories.

Operation	HTTP	Description	Required params
list	GET /categories	Lists all the categories, or the required one if an ID is provided	—

Help Desk

Help desks, their levels, and observers.

Operation	HTTP	Description	Required params
addObserver	POST /helpdesks.observers	Add users as observers to a help desk	id, observer_users
deleteObserver	DELETE /helpdesks.observers	Removes observers from a help desk	—
getObservers	GET /helpdesks.observers	Returns all active help desks and their observers, or the observers for the specified help desks	—
list	GET /helpdesks	Returns all the active help desks, or one in particular	—
listWithLevels	GET /helpdesksandlevels	Returns all the help desks and levels, or one in particular	—

Level

Help desk levels and their observers.

Operation	HTTP	Description	Required params
addObserver	POST /levels.observers	Add users as observers to a help desk level	id, observer_users
deleteObserver	DELETE /levels.observers	Removes observers from a help desk level	—
getObservers	GET /levels.observers	Returns all active help desk levels and their observers, or the observers for the specified help desk levels	—
list	GET /levels	Returns all active help desks' levels, or one in particular	—

User

Users: lookup, administration, and group/company/location membership.

Operation	HTTP	Description	Required params
changePassword	PUT /user.password	Changes the password of a user	id, password
convert	POST /user.convert	Changes the user from external into internal and sends an email to the user requesting a new password	id
create	POST /user	Creates a new user	name, lastname, email
createToken	POST /user.token	Creates a new session token for the user that matches the input ID	id
delete	DELETE /user	Deletes a user	—
disable	PUT /user.disable	Disables a user	id
enable	PUT /user.enable	Enables a user	id
get	GET /user	Returns the info of a user	id
getBy	GET /user.by	Retrieves the user matching the username or email and displays some basic information about the user. At least one of the input parameters is required	—
getGroups	GET /users.groups	Returns the user's groups, companies, helpdesks and locations	ids
list	GET /users	Retrieves users and displays some basic information about them. It's possible to specify an array of user IDs in order to filter specific users; otherwise, it retrieves all users	—
listBy	GET /users.by	Retrieves users matching username, email or any of their phone numbers and displays basic information about them	—
resetPassword	POST /user.password.reset	Sends an email to the user requesting a new password	id, type
update	PUT /user	Updates the info of a user	id

Group

User groups, their members, and observers.

Operation	HTTP	Description	Required params
addObserver	POST /groups.observers	Add users as observers to a group	id, observer_users
addUser	POST /groups.users	Adds a user to a group	id, users
create	POST /groups	Creates a group of users	name
delete	DELETE /groups	Erases a group of users	—
deleteObserver	DELETE /groups.observers	Removes observers from a group	—
deleteUser	DELETE /groups.users	Removes a user from a group	—
getObservers	GET /groups.observers	Returns all active groups and their observers, or the observers for the specified groups	—
getUsers	GET /groups.users	Lists the members of a group	id
list	GET /groups	Returns all active groups of users, or one in particular if an ID or name is provided	—

Company

Companies, their members, groups, and observers.

Operation	HTTP	Description	Required params
addGroup	POST /companies.groups	Relates a users group to a company	id, groups
addObserver	POST /companies.observers	Add users as observers to a company	id, observer_users
addUser	POST /companies.users	Adds a user to a company. If the company contains groups, the users will also be added to those groups	id, users
create	POST /companies	Creates a new company	name
delete	DELETE /companies	Erases an existing company	—
deleteGroup	DELETE /companies.groups	Suppresses the relationship between a users group and a company	—
deleteObserver	DELETE /companies.observers	Removes observers from a company	—
deleteUser	DELETE /companies.users	Removes a user from a company. If the user is within a group that belongs to that company, they will also be removed from that group	—
getGroups	GET /companies.groups	Lists all the users groups related to a company	id
getObservers	GET /companies.observers	Returns all active companies and their observers, or the observers for the specified companies	—
getUsers	GET /companies.users	Lists the members of a company	id
list	GET /companies	Returns all the active companies	—
update	PUT /companies	Modifies an existing company	id

Location

Locations, their members, and observers.

Operation	HTTP	Description	Required params
addObserver	POST /locations.observers	Add users as observers to a location	id, observer_users
addUser	POST /locations.users	Adds users to a location	id, users
create	POST /locations	Creates a location	name
delete	DELETE /locations	Erases an existing location and its sublocations	—
deleteObserver	DELETE /locations.observers	Removes observers from a location	—
deleteUser	DELETE /locations.users	Removes users from a location	—
getObservers	GET /locations.observers	Returns all active locations and their observers, or the observers for the specified locations	—
getUsers	GET /locations.users	Lists the members of a location	id
list	GET /locations	Returns all active locations, or one in particular	—

Knowledge Base

Knowledge Base articles, categories, and attachments.

Operation	HTTP	Description	Required params
addArticleAttachment	POST /kb.articles.attachments	Adds attachments to an article	article_id, author_id
createArticle	POST /kb.articles	Creates an article	category_id, content, title, author_id
createCategory	POST /kb.categories	Creates a new Knowledge Base category	name
deleteArticle	DELETE /kb.articles	Deletes an article from a given ID	—
deleteArticleAttachment	DELETE /kb.articles.attachments	Deletes an attachment from an article	—
deleteCategory	DELETE /kb.categories	Deletes a Knowledge Base category	—
getArticleAttachments	GET /kb.articles.attachments	Lists the attachments from an article	article_id
getArticles	GET /kb.articles	Lists all the articles with their properties	—
getArticlesByCategory	GET /kb.articles.by.category	Lists all the articles that belong to a certain category	category_id
getArticlesByIds	GET /kb.articles.by.ids	Lists articles by ID	ids
getArticlesByKeywords	GET /kb.articles.by.keywords	Searches for articles by keywords	keywords
getCategories	GET /kb.categories	Lists all the Knowledge Base categories	—
getCategoriesByIds	GET /kb.categories.by.ids	Lists Knowledge Base categories by some given IDs	ids
updateArticle	PUT /kb.articles	Modifies an article given a certain ID	author_id, id
updateCategory	PUT /kb.categories	Modifies a Knowledge Base category	id

Custom Field

Custom field definitions and list/tree option management.

Operation	HTTP	Description	Required params
addListOption	POST /cf.field.options.list	Configures list type custom fields. If the key already exists, the previous value will be overwritten	type, uid, key_values
addTreeOption	POST /cf.field.options.tree	Adds configuration to the tree type custom fields. If the key already exists, the previous value will be overwritten	uid, name
deleteListOption	DELETE /cf.field.options.list	Erases keys from the list type custom fields configuration	—
deleteTreeOption	DELETE /cf.field.options.tree	Erases the options from the tree type custom fields and any of its children	—
getListOptions	GET /cf.field.options.list	Lists the configuration of custom fields that are a list type	uid
getTreeOptions	GET /cf.field.options.tree	Returns the structure of the tree type custom fields options. The hash is system internal, but it is used to make modifications	uid
listFieldTypes	GET /cf.fields.types	Returns a list of all the supported custom field types, with a brief description of the data type for each field	—
listFields	GET /cf.fields.all	Returns a list of all the active custom fields	—
listFieldsByCategory	GET /cf.fields.by.category	Returns a list of the custom fields related to a category ID	category_id
listSharedFields	GET /cf.fields.shared.all	Returns a list of all the active shared custom fields	—
updateTreeOption	PUT /cf.field.options.tree	Modifies the configuration of the tree type custom fields. If there is no such key, it will be added	hash, uid

Internal Note

Internal notes on requests.

Operation	HTTP	Description	Required params
create	POST /internalnotes	Creates an internal note	object_type, object_id, author_id, description, title
delete	DELETE /internalnotes	Deletes an internal note	—
get	GET /internalnotes	Lists all the internal notes, or one in particular	id
update	PUT /internalnotes	Updates the info of an internal note	id, author_id

Time Tracking

Time tracking records and categories.

Operation	HTTP	Description	Required params
create	POST /timetracking	Logs the indicated time within a request	request_id, to, user_id
delete	DELETE /timetracking	Deletes a time log entry from a request	—
get	GET /timetracking	Lists all the available time tracking records within a specific time interval or a request ID	—
listCategories	GET /timetracking.attributes.category	Lists all the time tracking categories, or the required one if an ID is provided	—

Breaking News

Breaking news announcements and their updates.

Operation	HTTP	Description	Required params
addStatusUpdate	POST /breakingnews.status	Creates a new update to the given Breaking News	id, body
create	POST /breakingnews	Creates Breaking News	body, type_id, title
get	GET /breakingnews	Returns the requested Breaking News	id
getStatusUpdates	GET /breakingnews.status	Returns the updates of the requested Breaking News	id
listAll	GET /breakingnews.all	Lists all the Breaking News	—
listStatuses	GET /breakingnews.attributes.status	Lists all the possible status for the Breaking News' and their descriptions. If an ID is provided, only one will be listed	—
listTypes	GET /breakingnews.attributes.type	Lists all the importance types of the Breaking News. If an ID its provided, only one will be listed	—
update	PUT /breakingnews	Modifies a set of Breaking News	id

Trigger

User-defined triggers and their executions.

Operation	HTTP	Description	Required params
list	GET /triggers	If no ID is specified, it returns a list with all the user defined triggers. Otherwise, it returns the trigger matching the specific trigger ID (if it exists)	—
listExecutions	GET /triggers.executions	Returns a list detailing each time that a specific trigger was executed in the last hour. If no trigger ID is provided, it returns all the times that user defined triggers were executed in the last hour	—

Configuration Item

Configuration items referenced from custom fields.

Operation	HTTP	Description	Required params
getByIds	GET /cis.by.id	Returns an array of CIs, linked through custom fields and shared custom fields, with their IDs and properties	ci_internal_ids

Data Export

Data export downloads.

Operation	HTTP	Description	Required params
get	GET /data.export	Returns the data export URL	id

Workflow

Workflow deployment and initial fields.

Operation	HTTP	Description	Required params
deploy	PUT /wf.deploy	Deploys the last version of the workflow	workflow_id
getInitialFieldsByCategory	GET /wf.initialfields.by.category	Lists the initial fields needed to create a request from a workflow	category_id

System

Instance information.

Operation	HTTP	Description	Required params
getVersion	GET /sd.version	Returns the current version of the InvGate Service Management instance	—

---

Examples

Create a Request (Incident)

{
  "integration_service": "invgate-service-management",
  "resource": "incident",
  "operation": "create",
  "parameters": {
    "creator_id": 1,
    "customer_id": 1,
    "type_id": 1,
    "title": "VPN access not working",
    "description": "User reports VPN disconnects every few minutes",
    "category_id": 1,
    "priority_id": 3
  }
}

The response includes the new request's ID as a string: {"status": "OK", "info": "Request 42 was created", "request_id": "42"}.

Get a Request

{
  "integration_service": "invgate-service-management",
  "resource": "incident",
  "operation": "get",
  "parameters": {
    "id": 42,
    "comments": true
  }
}

List Open Requests by Status

{
  "integration_service": "invgate-service-management",
  "resource": "incident",
  "operation": "searchByStatus",
  "parameters": {
    "status_id": 1,
    "limit": 20,
    "offset": 0
  }
}

Add a Comment

{
  "integration_service": "invgate-service-management",
  "resource": "incident",
  "operation": "addComment",
  "parameters": {
    "request_id": 42,
    "author_id": 1,
    "comment": "Escalating to network team",
    "customer_visible": true
  }
}

Cancel a Request

{
  "integration_service": "invgate-service-management",
  "resource": "incident",
  "operation": "cancel",
  "parameters": {
    "request_id": 42,
    "author_id": 1,
    "comment": "Duplicate of request 41"
  }
}

Find a User by Email

{
  "integration_service": "invgate-service-management",
  "resource": "user",
  "operation": "getBy",
  "parameters": {
    "email": "[email protected]"
  }
}

List Priorities (for dropdowns / ID resolution)

{
  "integration_service": "invgate-service-management",
  "resource": "attribute",
  "operation": "listPriorities",
  "parameters": {}
}

Returns the fixed 5-level scale: [{"id":1,"name":"Low"}, {"id":2,"name":"Medium"}, {"id":3,"name":"High"}, {"id":4,"name":"Urgent"}, {"id":5,"name":"Critical"}].

---

Common Workflow Patterns

Alert-to-Ticket Pipeline

1. Receive an alert from an upstream node (SIEM, EDR, monitoring)
2. getBy (user) — resolve the on-call or reporting user's ID from their email
3. create (incident) — open a request with the alert details, mapping severity to priority_id
4. addObserver — subscribe stakeholders to the new request

Ticket Triage & Status Tracking

1. searchByStatus (incident) — fetch new requests (status_id 1)
2. get — pull full details including comments for each candidate
3. reassign — route to the right help desk or agent
4. waitingForCustomer / waitingForDate — park requests pending input, or cancel / reject invalid ones

Approval-Gated Change Flow

1. createCustomApproval (incident) — attach an approval to a change request
2. getApprovalPossibleVoters — discover who can vote
3. addApprovalVoter — assign the approvers
4. Poll getApprovals and branch on the outcome; acceptSolution / rejectSolution to close the loop

Knowledge Base Sync

1. getArticlesByKeywords (knowledgeBase) — look for an existing article before creating tickets
2. createArticle — publish a remediation guide from resolved-ticket data
3. getCategories / createCategory — keep article taxonomy aligned

---

Troubleshooting

Issue	Resolution
invalid credentials (status 401) with a login-page note	The API username/password is wrong, or you used UI login credentials — copy the API pair from Settings → Integrations API → Credentials
Connection works in the browser but fails in NINA	The base URL must include /api/v1 — copy it verbatim from Settings → Integrations API → Resources
unsupported operation errors	Operation keys are camelCase (e.g. searchByStatus, waitingForAgent) — check the tables above
Create/update rejected with missing field errors	InvGate requires numeric IDs for creator_id, customer_id, category_id, type_id, priority_id — resolve them via the attribute, category, and user lookups first
Can't find a "set status" operation	InvGate has no generic status setter — use the discrete lifecycle operations (cancel, reject, reopen, waitingFor*, acceptSolution, …); read statuses via listStatuses
request_id type confusion	create returns the request ID as a string; numeric and string IDs are both accepted as inputs
waitingForDate rejects the date	Supply timestamp as a Unix epoch string (e.g. "1781251158")
Type/category IDs differ between instances	Request types and categories are instance-specific (e.g. some instances add "Change Request", "Major incident") — always resolve them via listTypes / list rather than hardcoding

---

Security Considerations

1. Protect API Credentials: Store the username/password exclusively through NINA credential management — never in workflow parameters or logs
2. Powerful Admin Operations: This integration exposes user administration (changePassword, resetPassword, createToken, disable) and workflow.deploy — restrict which workflows and users may invoke them
3. Least Privilege: If InvGate allows scoping the API user, limit it to the modules your workflows need
4. Sensitive Ticket Data: Requests often contain PII and internal infrastructure details — treat workflow outputs accordingly
5. Credential Rotation: Rotate the API password periodically and immediately after suspected exposure

---

Additional Resources

• InvGate Service Management API Developer Manual
• InvGate Service Management Product Page

Updated: 2026-06-12