Service Manager REST API


REST (Representational State Transfer) is based on the HTTP protocol for accessing resources thanks to their unique URI. It is used by web services to perform various operations supported natively: GET (read), POST (write), PUT / PATCH (modify), DELETE (delete).


Operating principle

  • A consumer makes an application via a request to a REST API with a web services provider.
  • The REST web service carries out the request and returns a response to the consumer in the form of a data stream (usually JSON format, this format having become established over the years).
  • The consumer uses the response as part of an application he/she has developed.

Service Manager can be:

  • Supplier of web services thanks to its REST API.
    • The services offered, named as methods, are well-defined Service Manager business functions.

      example  Creation of a ticket, Update of an asset

    • The third-party application calls a Service Manager REST API method sending the values expected by the parameters of this method. Processing is then carried out as if Service Manager was active.

      example  A Service Desk application calls the Suspend a ticket method by sending the Service Manager incident number

  • Consumer of web services provided by the REST APIs of other products in order to access external data. Open url.png See REST action types settings.

    example  Call of the Trello REST API to access the list of projects and tasks during a workflow step

    • The external REST web service must be declared as a service (via the Administration > REST > Services menu).
    • It can then be accessed from a step in a process via a REST action.


  • The Service Manager REST API exchange format is JSON.
  • The Service Manager REST API allows to manage the following resources.
Resource JSON Object SQL Table
assets asset AM_ASSET
catalog-assets catalog-assets AM_CATALOG
catalog-requests catalog-requests SD_CATALOG
configuration-items configuration-items AM_ASSET
departments department AM_DEPARTMENT
employees employee

alias : recipient ; requestor ( * )

known-problems known-problem SD_KNOWN_PROBLEMS
locations location AM_LOCATION
manufacturers manufacturer AM_MANUFACTURER
requests request SD_REQUEST
slas sla SD_SLA
status status SD_STATUS

( * ) The employee JSON object has 2 alias which are used for the requests resource to manage the case of the foreign keys submitted_by and recipient_id of the SD_REQUEST table.

  • The methods (operations) PUT and PATCH which allow to modify a specified resource are equivalent.
  • The methods which allow to obtain a specified resource or to modify a specified resource use a mandatory parameter that corresponds to a field of the Service Manager database for which we can guarantee the uniqueness.
        example  asset_id parameter for the following methods:
  • When you wish to obtain a specified resource or to modify a specified resource for which the third-party system does not know the value of the field used as parameter, you should use the method to obtain a list by applying the desired search/filter options on the fields of the database. You can then use the link URL (HREF) provided which contains the unique identifier of each resource.
        example  To obtain a specified access:
    • You should use the View a list of assets method (GET /assets) with the possible search/filter options on the fields asset_id, employee_id, location_id, department_id.
    • Then you can use the link URL: "HREF": "https://{your_server}/api/v1/{your_account}/assets/27590" to access the asset of which the identifier is 27590.
  • Results (JSON format) are returned in the language of the user for which the account is used to access to the Service Manager REST API.

Best Practice

  • To run your tests, you shoud use:
    • The HTTP request library providing by EasyVista. It contains a set of examples which may help you understand and use the Service Manager REST API and run tests in your specific Service Manager environment if required.
    • Postman (extension of Chrome). It is an excellent third-party tool for mechanizing API tests; particularly REST API. 

Licensing and security system

  • All operations carried out with the Service Manager REST API require a login in order to access a specific domain. Each time a call is made to the API, user access is recorded.
  • For security reasons and to prevent unwanted use of the Service Manager REST API by standard users, the REST API field has been added to profile management. It allows you to define a dedicated profile and user to the API use. Open url.png See the Procedure 



How to define a dedicated user to the Service Manager REST API

Step 1: Create a REST API profile

1. Select Administration > Access Management > User Profiles in the menu.

2. Create a new profile. Open url.png See the procedure.

3. Check the REST API box to give him the authorization to use the Service Manager REST API.
         REST API - Dedicated user.png

4. Click Wheel icon.png next to the REST API field to define the access rights to the Service Manager REST API methods.


         REST API - Route switchs.png

  • Check the route (or resources) boxes that the profile can have access.
  • For each selected route, indicate if the profile can use the HTTP method by switching the cursor on REST API - Route switch on icon.png, or if it can not use it by switching the cursor on REST API - Route switch off icon.png.
    • GET: read-only acces;
    • POST: write access;
    • PUT / PATCH: access for update;
    • DELETE: access for delete.

Step 2: Create a dedicated user, authorized to carry out REST requests

1. Proceed to the employee directory: select Asset Management / Operation / Transition / Extended CMDB / Projet > Directory > Employee in the menu.

2. Create a new user and assign the profile previously created.
         User - Profile REST API.png
All multilingual data will be displayed in that user's language.


How to manage the result of a REST API action in a process

    Open url.png See the procedure.

Workflows and business rule related processes can contain REST actions.

  • All Service Manager REST API methods can be called.
  • You can manage the result of the REST action, i.e. Success or Error, using internal update steps.

example  Create an employee

Result returned if the update is successful


Result returned if the update failed

Rest step workflow failed, the service send a bad http code [HTTPCODE:401] (2114) "Error http4xx"

API References

Access to REST methods

Access is via a URL of format:  

  • {your_server}: server URL
  • {your_account}: Service Manager account used
             example  50004: Production base; 50005: Sandbox base
  • {resource_name}: Name of the resource called
             example  requests ; assets ; employees


List of the REST API methods


Note: The Assets term includes equipment, licenses, contracts.



  Links of an asset





Note: The Tickets term includes incidents, service requests, change requests, investment requests, problems, events.




Questions / Questionnaires


Known errors



Departments / Locations



Configuration items (CIs)

  Links of a CI

  • Create a CI link  :  POST  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}
  • Update a CI link  :  PUT  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}
  • Delete a CI link  :  DELETE  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}

External tables (E_ tables)


HTTP status codes

Code Error Description
200 OK (Success) Request processed successfully.
201 Created Request processed successfully and an item created.
204 Deleted Request processed successfully and an item deleted.
400 Bad Request Request formulated incorrectly and cannot be executed correctly.


 "error": "Nothing to update (check fieldnames)"
401 Unauthorized Authentication process for accessing the resource is incorrect: Login/Password incorrect, Invalid session, Incorrect Service Manager account.


 "error": "Invalid Login / Password"
403 Forbidden Server refused to execute the request. Unlike error 401, authentication is accepted but access rights do not authorize the client to access the resource: The user does not have the REST API parameter enabled in their profile.
404 Not Found Resource not found: Incorrect URI, Missing resource, Incorrect communication with the server, rfc_number not found.


 "error": "Resource not found"
405 Method not allowed Request method not authorized: not supported or not appropriate for the resource.


 "error": "Invalid input parameter"
406 Not acceptable Resource not available in a format complying with the Accept headers of the request. Note: The exchange format of the Service Manager REST API is JSON.
409 Conflict Unable to process request in the current state. Records cannot be modified or deleted.
413 Request entity too large Processing abandoned because the request was too large.
500 Internal Server Error Generic error message displayed when an unexpected condition is encountered and there is no appropriate message which is more specific.<


 "error": "An error occured. A text message is returned in the body."
503 Service unavailable Service temporarily unavailable or under maintenance. The request cannot be processed.


REST API Conventions

Convention Meaning
Orange Parameters used in an HTTP request string which do not correspond to Service Manager database fields.

example   Method View a list of assets


Black and Bold Parameters used in the URL of an HTTP request which correspond to Service Manager database fields.

example   Method View an asset


Green Parameters used in the body of an HTTP request which represent JSON object names corresponding to Service Manager database fields; they allow the value of a database field to be assigned or modified.

example   Method Close an incident/request

{  "closed": {  "end_date": "11/20/2019 12:12:12",  }  }
Parameters used in the body of an HTTP request which represent JSON object names not corresponding to Service Manager database fields.

example   Method Reopen an incident/request

{  "restarted": {  "comment": "string (required)"  }  }

Last modified by Christine Daussac on 2021/04/19 15:01
Created by Administrator XWiki on 2016/11/23 10:15


Powered by XWiki ©, EasyVista 2021