Home / Getting started

Getting started


API guide for ServiceDesk Plus On-Demand

ManageEngine ServiceDesk Plus On-Demand provides an API (Application Programming Interface) using which you can integrate it with any of your existing applications such as network monitoring, intranet web applications and any other outside application. The ServiceDesk Plus On-Demand API supports XML and JSON formats and is programming language-neutral; allowing you to develop applications in a language you are familiar with.

With the ServiceDesk Plus On-Demand API, the possibilities are manifold and constrained just by the limits of our imagination. Here are some of the things you can do with our API

  • Create / Edit / Delete requests from your own website, having your own user interface.
  • Create / Edit requests from your monitoring application

Prerequisites for using your API

To use the ServiceDesk Plus On-Demand API you should have the following

  • A valid ServiceDesk Plus On-Demand account username and password
  • Get an Authtoken

Generating Authtoken

AuthToken is a token given to you after logging in to SDP On-Demand. AuthToken is the identifier using which your account is identified during API invocation. You need to generate your AuthToken only once and can continue to access ServiceDesk Plus On-Demand - API without interruption. This token has no expiry.
To generate the permanent authtoken, browse the following URL: 

https://accounts.zoho.com/apiauthtoken/create?SCOPE=SDPOnDemand/sdpodapi
You will be requested to sign in if you are not signed in already.

Sample Response

#
#Tue Nov 30 13:08:11 PST 2010
AUTHTOKEN=a8b6de25b5bf481824c9c4173c56231a
RESULT=TRUE

Remarks :
AUTHTOKEN : The permanent authtoken generated for ServiceDesk Plus On-Demand API access.
RESULT : Value is TRUE if the authtoken is generated successfully.

Invoking the API

Any of our API methods can be invoked via HTTP POST request. All parameters in the request should be form-urlencoded. For all the APIs you need to pass authtoken, scope and operation name, which are mandatory.

Mandatory parameters to be passed for all APIs

There are certain parameters that are mandatory for all API requests of ServiceDesk Plus On-Demand. They are,

authtoken The permanent authtoken used to authenticate each API request
Scope The value for this parameter is always sdpodapi
OPERATION_NAME The name of the operation


Supported formats

ServiceDesk Plus On-Demand supports both the XML and JSON formats.
The URL structure for an XML format API would be as below: https://sdpondemand.manageengine.com/api/request

The URL structure for a JSON format API would be as below: https://sdpondemand.manageengine.com/api/json/request



Formats for input and output

  The following is the format for INPUT_DATA in json and its equivalent xml format.
{
   "operation": {
      "Details": {
         "PARAMETER_NAME_1": 
"PARAMETER_VALUE_1", "PARAMETER_NAME_2":
"PARAMETER_VALUE_2", } } }
<?xml version="1.0" encoding="UTF-8"?>
<operation>  
  <Details>
    <parameter>
      <name>PARAMETER_NAME_1</name>
      <value>PARAMETER_VALUE_1</value>
    </parameter>
    <parameter>
      <name>PARAMETER_NAME_2</name>
      <value>PARAMETER_VALUE_2</value>
    </parameter>  
  </Details>
</operation>

For example, for adding a request, the following is a sample INPUT_DATA in json and xml formats :

{
   "operation": {
      "Details": {
         "URGENCY": "High",         
         "SUBJECT": "Subject of the request",
         "LEVEL": "Tier 1",         
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<operation>  
  <Details>
    <parameter>
      <name>URGENCY</name>
      <value>High</value>
    </parameter>
    <parameter>
      <name>SUBJECT</name>
      <value>Subject of the request</value>
    </parameter>  
    <parameter>
      <name>LEVEL</name>
      <value>Tier 1</value>
    </parameter>
  </Details>
</operation>

Sample Output :
The following is a sample output in json & xml formats for the worklog addition api :

{
   "operation": {
      "name": "ADD_WORKLOG",
      "result": {
         "status": "Success",
         "message": 
             "WorkLog added successfully 
                for request"
      },
      "Details": {
         "WORKLOGID": "2000000124193"
      }
   }
}
<?xml version="1.0"?>
<operation name="ADD_WORKLOG">  
  <result>
    <status>Success</status>
    <message>Work Log added successfully for request </message>
  </result>

  <Details>
    <parameter>
      <name>WORKLOGID</name>
      <value>2000000124193</value>
    </parameter>
  </Details>
</operation>

Some general rules for input and output

  1. Content type while calling the api must be application/x-www-form-urlencoded and all parameter values must be url encoded
  2. In the output, “Details” will be a JSON object or a JSON array. For returning multiple objects, JSON array will be used. For example, GET_REQUEST will contain a JSON Object in the output, whereas, GET_REQUESTS will return a JSON array in the output. Similarly, there will be single or multiple "<Details>" elements in the output xml, depending on the operation.
  3. The parameter names (inside "Details") in the INPUT_DATA are to be in UPPER case only. For e.g., you can specify "URGENCY":"High" or "PRIORITY" : "High" in the input data while adding a request.
  4. In the output, all the parameter names (inside "Details") will be returned in upper case.
  5. Date/Time field values will always be sent in Long. Input should also contain Long value for these fields

 




     RSS of this page