Application Programming Interface (API) is used to integrate various applications and facilitate sharing of data between them. The integration can be achieved with any third-party (external) applications or web services that are capable of sending the data via HTTP protocol.
With API, ServiceDesk Plus operations can be accessed from other applications or web services. In case of request operations, it provides a convenient method to raise requests (other than the default e-mail or web form) directly into ServiceDesk Plus without logging into the application. If required, you can also have an option to create your own web form for using API.
The purpose of REST API can be explained with the help of a scenario.
|
Scenario: Let's take the case of a network monitoring tool (external application) that is installed on your network. In general, when an alarm is raised by the network monitoring tool, an e-mail notification is sent as a ticket to ServiceDesk Plus application. The field values (priority, level, impact, category, and so on) should be filled by the technician manually in ServiceDesk Plus. This mechanism is time-consuming and eventually results in a dip in your helpdesk productivity chart. With REST API, you can automate this ticketing process. When an alarm is triggered, the network monitoring tool provides the field details and raises a ticket automatically in ServiceDesk Plus via HTTP protocol. The ticket ID is sent back to the network monitoring tool in order to perform any further operations over the request. When the cause for the alarm is resolved, ServiceDesk Plus will invoke an URL (callback URL) that was provided by the monitoring tool. The URL functions as a notification to the external application indicating that the ticket is resolved. If this URL (callback URL) is not provided, ServiceDesk Plus will not perform any additional operation on the ticket. When ServiceDesk Plus invokes the callback URL, the network monitoring tool can perform "any" internal operations based on the URL invocation. However, the expectation is that the application will clear the alarm (which was raised as a ticket) at their end.
Note: Please note that the callback URL is applicable only while creating and editing requests. |
The operations performed with REST API are based on the 'operation' parameter and is sent to the url via HTTP POST method. The url format is as shown below,
http://<servername>:<port number>/api/v3/<module>
Authentication to the ServiceDesk Plus application is key based i.e., an API key is sent along with the url for every operation. This key is technician based and can be generate for technicians with login privilege. The role given to the technician is also taken into consideration, so the key is valid only for the role given to the technician. Once the key is generated, the key is manually transferred to the integrated application so that the application can use the key for further API operations. If the key is invalid (key is expired or the technician login is disabled), the operation fails and an error is propagated to the integrated application.
|
Note
|
1. Please note that the administrator alone has the privilege to generate the authentication key for technicians with login permission. 2. If a login for the technician is disabled, then the API key is deleted. 3. The operations can be performed based on the Role provided to the technician. |
The authentication between ServiceDesk Plus and integrated application is through an API key. A unique key is generated for a technician with login permission in ServiceDesk Plus application.
Go to User Profile and select Generate Authtoken.
In the popup window, select the option Never Expires and then click Generate.
If you want to have an expiry date for the authtoken, you can select a time frame for the key to expire using the calendar icon 
or simply retain the same key perpetually. If a key is already generated for the technician, a Re-generate link appears.
The key in the above image is generated for an existing technician. A time frame for the key is selected which shows the date, month, year and the time (in hours and minutes) when the key will expire.
The REST API supports the following operations which can be separated into:
Operations on request: adding a new request, picking up requests, assigning requests, get requests, obtain conversations, add attachments, get request notifications, and add/edit/get resolutions.
Operations on a specific request:
editing, closing, deleting and viewing existing requests.
adding new notes to a request, editing, deleting and viewing existing notes.
adding worklog to a request, editing, deleting and viewing existing worklogs.
obtain conversations related to request
add attachments to request
add, edit, and get a resolution of a request.
pick up / assign request.
reply to request
get notifications related to a request
Technician related operations: import technician profiles (of all technicians) and assign operations to them.
Requester related operations: import requester profiles (of all requesters) and work on their requests.
Admin related operations: import specific Category/ all Categories, specific Subcategory/ all Subcategories, specific Item/ all Items, specific Status/ all Status, specific Level/ all Level(s), specific Mode/ all Modes, specific Urgency (all Urgencies), specific Priority/ all Priorities, specific Request Template/ all Request Templates, and all Support Group(s)
Servlet API is no longer supported.
