Service Manager REST API

Last modified on 2023/08/30 16:02

Update  

2023.3
  • Management of Service Manager REST API rights access for each external table on the platform (tables prefixed by E_)
2023.2
  • New methods:
    • Create a group, Update a group, View a list of groups, View a group, Add an employee to a group, Delete an employee from a group, View the list of employees in a group, View the list of groups for an employee
    • View a list of questions associated with all questionnaires, View a list of questions associated with a questionnaire, View a list of multi-section questionnaires, View a multi-section questionnaire
2023.1 - Build 2022.1.133.0.01
  • New methods:
    • Create a supplier, Update a supplier, View a list of suppliers, View a supplier
    • Download a ticket attachment
2022
  • New methods:
    • Declare CI availability, Declare CI unavailability
    • View Service Manager license key information
  • Create a ticket: New HTTP 406 status code
  • All methods: New timeout error code
Autumn 2020 - Build 2020.2.122.2
  • All methods: new search/filter option by time
  • New parameters:
    • View the URLs for ticket attachments: document parameter
    • View a list of actions: action_type_id and action_type_name parameters
    • Create a ticket action: comment parameter
    • Create a ticket: impact_id parameter
Oxygen 2.1.4 - Build 2018.1.185.5
  • New methods: Update asset attribute, Link attribute and asset
Oxygen 2.1.4 - Build 2018.1.185.2
  • New methods:
    • View a list of news articles, View a news article, Create a news article, Update a news article
    • View all attributes for a list of assets, View all attributes for an asset
  • All GET methods: new search parameters, search, null and not null
Oxygen 2.1 - Build 2018.1.181.0
  • New methods:
    • Download a ticket attachment, Delete a document
    • View a list of questionnaires, View a questionnaire
    • View a list of questions, View a question, View a list of questions with answers, View the answers to a list of questions in a ticket, View the answer to a question in a ticket, Create the answer to a question in a ticket, Update the answer to a question in a ticket
Oxygen 2.0 - Build 2018.1.169.0
  • Filter resources with a composite key

Service Manager provides REST Web services that third-party apps can use to access data.

  • The Service Manager REST API provides business functionality services with a specifically delimited scope. Open url.png See the list of methods
  • The exchange format of the Service Manager REST API is JSON.
  • Third-party apps can call a Service Manager REST API method by passing the relevant values in its parameters (Note: Each method has its own mandatory parameters). Processing is then run with Service Manager akin to an active state.

example  A Service Desk app calls the Suspend a ticket method by passing the Service Manager incident number

  Service Manager can also call the REST Web services of third-party apps to access external data. Open url.png See Configuration of REST action types

REST API: Operating principle

  • Consumers send a request to the REST API of a Web service provider.
  • The REST Web service will process the request and return the results to consumers in a data flow, usually in the widely adopted JSON format.
  • Consumers can then use the results in an app they developed.
     

REST protocol

Definition

REST (Representational State Transfer) uses the HTTP/HTTPS protocol to access resources thanks to their unique URI. It is used by Web services to perform natively supported operations, e.g. GET (read), POST (write), PUT / PATCH (update), DELETE (delete).

EndDefinition

 

Resources managed by the Service Manager REST API

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
  • Note: The JSON object called employee has two aliases that are used by the requests resource in order to manage foreign keys, i.e. submitted_by and recipient_id, in the SD_REQUEST table.
AM_EMPLOYEE
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
suppliers supplier AM_SUPPLIER

Notes

  • You can use HTTP and HTTPS protocols with the Service Manager REST API.
  • The exchange format of the Service Manager REST API is JSON.
  • Results are returned in the language of the user account used to access the Service Manager REST API.
  • PUT and PATCH are similar methods. Both are used to update specific resources.

example  Update an asset method

  • PUT /assets/{asset_id}
     or
  • PATCH /assets/{asset_id}
  • The methods used to access or modify specific resources are based on a mandatory parameter. This parameter corresponds to a field in the Service Manager database whose uniqueness is ensured.

example  Call the asset_id parameter

  • A timeout is enabled when Service Manager REST calls are made. It indicates the maximum server response time for a REST Web service request sent to a third-party service. Once this time has elapsed, the call will be interrupted and a Timeout error code will be returned, informing you that the request failed.
    • The default duration is 60 seconds.
    • You can define a time between 1 to 300 seconds. Open url.png See the procedure

Best Practice

  • To run your tests:
    • You can use the HTTP request library provided by EasyVista, containing a set of examples that can help you understand and use the Service Manager REST API and, if required, run tests in your specific Service Manager environment.
    • You can use Postman (a Chrome extension) is an excellent third-party tool for standardizing API tests, namely REST API tests.
  • To access or modify a specific resource whose parameter field value is unknown to the third-party app, use the method for accessing lists by applying the relevant search/filter options to the database fields. Next, use the URL (HREF) link provided. This contains the unique ID of each resource.

example  Access a specific asset:

  • Use the View a list of assets method (GET /assets) with the search/filter options for the following fields: asset_id, employee_id, location_id, department_id.
  • Use the URL "HREF" link: "https://{your_server}/api/v1/{your_account}/assets/27590" to access the asset whose ID is 27590.

Security and license system

  • All operations performed using the Service Manager REST API require a login to access a specific domain
  • For security reasons, the use of the Service Manager REST API is exclusively restricted to a dedicated profile and user. You manage this using the REST API field in user profile management. Open url.png See the procedure

Access the Service Manager REST API

  • Access to the Service Manager REST API is secured to prevent anyone who does not need access from viewing or manipulating the data.
    This can be performed:
    AccessRESTAPI
    • Via Token authentication dedicated to the Service Manager REST API (authentication method Service Manager (Access Token)) using an access token. Open url.png See the procedure
    • Via Basic authentication using a login and password. Open url.png See the procedure

    Best Practice icon.png  We recommend that you use the authentication method Service Manager (Access Token) with a higher level of security than the Basic method which uses a login and password.

EndAccessRESTAPI
  • You can call a Service Manager REST API method using a URL in the following format.
    Replace:
    • {your_server} with the server URL
    • {your_account} with the Service Manager account used
    • {resource_name} with the resource that is called

https://{your_server}/api/v1/{your_account}}/{resource_name}

      example

https://your_company.easyvista.com/api/v1/50004/employees

https://your_company.easyvista.com/api/v1/50005/requests

List of Service Manager REST API methods

Assets

Note: The term, Assets encompasses equipment, licenses and contracts.

  Attributes

  Catalogs

  Links to an asset

Manufacturers

Employees / Groups

 Employees

 Groups

Suppliers

SLA

Tickets

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

  Catalogs

  Problems

  Attachments

Questions and Questionnaires

Problems

Known errors

News

Actions

Departments and Locations

  Departments

  Locations

Configuration items (CI)

  CI links

  • 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)

Best Practice icon.png  You can manage Service Manager REST API rights access for each external table on the platform. Open url.png See the procedure

Others

Procedures

How to define access authorization to the Service Manager REST API

Via dedicated Token authentication (creating an access token)

Best Practice icon.png  We recommend that you use the authentication method Service Manager (Access Token) with a higher level of security than the Basic method which uses a login and password.

Step 1: Create an access token

   Your profile must be authorized to access the Administration > Access Management > Access Tokens menu. Open url.png See User profiles

1. Select Administration > Access Management > Access Tokens in the menu.

2. Click + New.

3. Enter the name of the new access token and select the user authorized to use the token.

4. Click Generate.

The value of the access token will automatically be copied to the clipboard.

   You should paste the value of the access token in your text editor to store it temporarily as it will no longer be available once you close the dialog box.

          Token added.png

Step 2: Define Token authentication for the Service Manager REST API

     Open url.png See Configuration of REST action types

1. Create a new service for the Service Manager REST API by selecting Administration > REST > Services in the menu.

  • Select the Service Manager (Access Token) authentication method.
  • Paste in the Bearer Token field the value of the access token you stored in your text editor earlier.
  • Specify the URL for accessing the Service Manager REST API.

          Service for Service Manager token authentication.png

2. Create a new connection to the service by selecting Administration > REST > Connections in the menu.

  • Select the Service Manager (Access Token) authentication method.
  • Select the service you just created.
  • (optional) Enter the parameters to pass to the HTTP header, via the Key and Value fields.

          Connection for Service Manager token authentication.png

3. Create a new resource associated with the connection by selecting Administration > REST > Resources in the menu.

  • Select the service and connection you previously created.

Via Basic authentication (creating a dedicated user)

Step 1: Create a REST API profile

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

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

3. Select the REST API box to authorize the use of the Service Manager REST API.

          REST API - Dedicated user.png

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

  • Select the routes or resources authorized for the user profile.

Best Practice icon.png  Hover over the syntax of the route to display its description.
        REST API - Route switchs.png

Best Practice icon.png  Use the search area to search for a keyword both in the syntax of the route and in its description (displayed on mouseover).
        REST API - Route search via syntax.png
        REST API - Route search via description.png

  • For each selected route, specify if the user profile is authorized to use the HTTP method (box is checked in the dedicated column) or not (box is not checked).
    • GET: Read-only access
    • POST: Write access
    • PUT / PATCH: Update access
    • DELETE: Delete access
       

Step 2: Create a dedicated user authorized to run REST requests

1. Open the Employee Directory by selecting References > Directory > Employees in the menu.

2. Create a new user and assign the REST API user profile you just created.

          User - Profile REST API.png

Multilingual data will be displayed in the language of this user.
 

Step 3: Define Basic authentication for the Service Manager REST API

     Open url.png See Configuration of REST action types

1. Create a new service for the Service Manager REST API by selecting Administration > REST > Services in the menu.

  • Select the Basic authentication method.
    Service for Service Manager basic authentication.png

2. Create a new connection to the service by selecting Administration > REST > Connections in the menu.

  • Select the Basic authentication method.
  • Select the service you just created.
  • In the User Name Authentication / Password Authentication fields, enter the credentials of the dedicated Service Manager REST API user you previously created.

          Connection for Service Manager basic authentication.png

3. Create a new resource associated with the connection by selecting Administration > REST > Resources in the menu.

  • Select the service and connection you previously created.

How to manage access rights to _E  external tables

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

2. Select a user profile with access to the Service Manager REST API.

3. Click Wheel icon.png next to the REST API option.

          REST API - Dedicated user.png

The screen displays the list of Service Manager REST API methods as well as the list of external tables available on the platform.
         External tables - View all methods.png

4. Click Manage external tables.

The list of external tables available on the platform will appear.
         External tables - List.png

5. Select the access rights to be granted to the Service Manager REST API for each of the external tables.

  • Click Add new resource to add a new external table available on the platform.

   A message will appear when all external tables have been added.

  • Click Delete access rights icon.png to delete all access rights to an external table.

6. Click Save.

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.
ManageServiceManagerRESTAPIInProcess_Result

example  Create an employee

Result returned if the update is successful

{"HREF":"https://{your_server}/api/v1/{your_account}/employees/18445"}

Result returned if the update failed

REST step workflow failed, HTTP error code returned by the service [HTTPCODE:401] (2114) "Error http4xx"x"

How to modify the duration of the timeout

1. Open the configuration file called rest-api.ini.

2. Search for the timeout parameter.

3. Enter the required value.

  • You can specify a value from 1 to 300 seconds.
  • Only whole numbers in seconds are authorized.
  • Any value outside this range will be replaced by the default value.

          Timeout - Ini file.png

4. Save your modifications.

HTTP status codes

StatusHeader

   A Timeout error code will be returned if the server does not respond to the REST Web service request within a given time (by default 60 seconds).

Code Error Description
EndStatusHeader

 

Status200
200 OK (Successful) Request successfully processed.
EndStatus200

 

Status201
201 Created Request successfully processed and element created.
EndStatus201

 

Status204
204 Deleted Request successfully processed and element deleted.
EndStatus204

 

Status400
400 Bad Request Request could not be run correctly due to malformed syntax.

example

{
 "error": "Nothing to update (check fieldnames)"
}

or when the "Suspend a ticket" method is called but the ticket is already suspended. The response returned is: { "error": "The request is already suspended. Operation aborted."}

or when the "Reopen a ticket" method is called but the ticket is not suspended. The response returned is: { "error": "The request is not suspended. Operation aborted."}

EndStatus400

 

Status401
401 Unauthorized Incorrect authentication process for accessing the resource: Incorrect login/password, invalid session, incorrect Service Manager account.

example

{
 "error": "Invalid Login / Password"
}
EndStatus401

 

Status403
403 Forbidden Server refuses to run the request. Unlike error 401, authentication is accepted but access rights do not authorize the customer to access the resource: Users who do not have the REST API parameter enabled for their profile.
EndStatus403

 

Status404
404 Not found Resource not found: Incorrect URI, missing resource, incorrect communication with the server, rfc_number not found.

example

{
 "error": "Resource not found"
}
EndStatus404

 

Status405
405 Method not allowed Unauthorized request method, i.e. it is not supported or not appropriate for the resource.

example

{
 "error": "Invalid input parameter"
}
EndStatus405

 

Status406
406 Not acceptable Resource is not available in a format that complies with the Accept headers of the request. Note: The exchange format of the Service Manager REST API is JSON.

or

From version 2022 - Build 2022.1.109.0.03 onwards The Create a ticket method is called but the ticket recipient or requestor does not exist in the Service Manager database or does not belong to one of the domains of the REST user calling the method.

EndStatus406

 

Status409
409 Conflict Unable to process request in the current state. Records cannot be updated or deleted.
EndStatus409

 

Status413
413 Request entity too large Processing abandoned because request was too voluminous.
EndStatus413

 

Status500
500 Internal Server Error Generic error message displayed when an unexpected condition is encountered and there is no specific message associated.

example

{
 "error": "An error occured. A text message is returned in the body."
}
EndStatus500

 

Status503
503 Service unavailable Service temporarily unavailable or under maintenance. The request cannot be processed.
EndStatus503
Status590
590 Bad Request Request could not be run correctly due to malformed syntax.

or

When the Suspend a ticket method is called but the ticket is already suspended. The response returned is { "error": "The request is already suspended. Operation aborted."}

or

When the Reopen a ticket method is called but the ticket is not suspended. The response returned is { "error": "The request is not suspended. Operation aborted."}

EndStatus590

 

ConventionsAPI

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

https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag
Black and Bold Parameters used in the URL of an HTTP request which correspond to Service Manager database fields.

example   Method View an asset

https://{your_server}/api/v1/{your_account}/assets/{asset_id}
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/2016 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)"  }  }
Tags:
Powered by XWiki © EasyVista 2022