Update   Click to see the history of updates.

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

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

EndDefinition

Resources managed by the Service Manager REST API

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.

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

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

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.  See the procedure

• Each time the Service Manager REST API is called, it is counted as one user access.  See Service Manager license usage rules

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.  See the procedure

  • Via Basic authentication using a login and password.  See the procedure

    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

• The Service Manager REST API is called in process steps such as workflows and business rules using the EasyVista REST action type.  See Configuration of REST action types

List of Service Manager REST API methods

Assets

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

• View a list of assets:  GET   /assets
• View an asset:  GET   /assets/{asset_id}

• Create an asset:  POST   /assets
• Update an asset:  PUT   /assets/{asset_id}

  Attributes

• View all attributes for a list of assets:  GET  /asset-characteristics
• View all attributes for an asset:  GET  /asset-characteristics/{asset_id}

• Link a new attribute to an asset:  POST  /assets/{asset_id}/characteristics/{characteristic_id}
• Update an asset attribute:  PUT  /assets/{asset_id}/characteristics/{characteristic_id}

  Catalogs

• View a list of asset catalog entries:  GET  /catalog-assets
• View an asset catalog entry:  GET  /catalog-assets/{catalog_id}

  Links to an asset

• View a list of links for an asset:  GET  /assets/{asset_id}/asset-links
• View an asset link:  GET  /assets/{asset_id}/asset-links/{parent_asset_id}

• Create an asset link:  POST  /assets/{asset_id}/asset-links/{parent_asset_id}
• Update an asset link:  PUT  /assets/{asset_id}/asset-links/{parent_asset_id}
• Delete an asset link:  DELETE  /assets/{asset_id}/asset-links/{parent_asset_id}

Manufacturers

• View a list of manufacturers:  GET  /manufacturers
• View a manufacturer:  GET  /manufacturers/{manufacturer_id}

Employees / Groups

 Employees

• View a list of employees:  GET   /employees
• View an employee:  GET   /employees/{employee_id}

• Create an employee:  POST   /employees
• Update an employee:  PUT   /employees/{employee_id}

 Groups

• View a list of groups  :  GET   /groups
• View a group  :  GET   /groups/{group_id}

• Create a group  :  POST   /groups
• Update a group  :  PUT   /groups/{group_id}

• View the list of employees in a group  :  GET   /groups/{group_id}/employees
• View the list of groups for an employee  :  GET   /employees/{employee_id}/groups
• Add an employee to a group  :  POST   /groups/{group_id}/employees/{employee_id}
• Delete an employee from a group  :  DELETE   /groups/{group_id}/employees/{employee_id}

Suppliers

• View a list of suppliers:  GET   /suppliers
• View a supplier:  GET   /suppliers/{supplier_id}

• Create a supplier:  POST   /suppliers
• Update a supplier:  PUT   /suppliers/{supplier_id}

SLA

• View a list of SLAs:  GET  /slas
• View an SLA:  GET  /slas/{sla_id}

Tickets

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

• View a list of tickets:  GET   /requests
• View a ticket:  GET   /requests/{rfc_number}

• View ticket comment (Comment field): GET   /requests/{rfc_number}/comment
• View a list of ticket statuses:  GET   /status

• Create a ticket:  POST   /requests
• Create a ticket task:  POST   /requests/{rfc_number}/tasks
• Update a ticket:  PUT   /requests/{rfc_number}
• Close a ticket:  PUT   /requests/{rfc_number}
• Suspend a ticket:  PUT   /requests/{rfc_number}
• Reopen a ticket:  PUT   /requests/{rfc_number}

  Catalogs

• View a list of ticket catalog entries:  GET  /catalog-requests
• View a ticket catalog entry:  GET  /catalog-requests/{catalog_id}

• View paths for a list of ticket catalog entries:  GET  /catalog-requests-paths
• View paths for a ticket catalog entry:  GET /catalog-requests-paths/{catalog_id}

  Problems

• View a list of problems linked to tickets:  GET   /problem-links
• View a list of problems linked to a ticket:  GET   /requests/{rfc_number}/problems
• View a list of tickets linked to a problem:  GET   /problems/{problems_id}/requests

  Attachments

• View the URLs for ticket attachments: GET   /requests/{rfc_number}/documents
• Download a ticket attachment:  GET   /requests/{rfc_number}/documents/{document_id}
• Attach documents to a ticket:  POST   /requests/{rfc_number}/documents
• Delete a ticket attachment: DELETE  /requests/{rfc_number}/documents/{document_id}

Questions and Questionnaires

• View a list of questions:  GET   /questions
• View a question:  GET   /questions/{question_id}
• View a list of questions associated with all questionnaires  :  GET   /questions-questionnaire
• View a list of questions associated with a questionnaire  :  GET   /questions-questionnaire/{questionnaire_id}

• View the answers to a list of questions in a ticket:  GET   /questions-result/{request_id}
• View the answer to a question in a ticket:  GET   /questions-result/{request_id}/{question_id}
• View a list of questions with answers:  GET   /questions-result

• Create the answer to a question in a ticket:  POST   /questions-result/{request_id}/{question_id}
• Update the answer to a question in a ticket:  PUT   /questions-result/{request_id}/{question_id}

• View a list of questionnaires:  GET   /questionnaires
• View a questionnaire:  GET   /questionnaires/{questionnaire_id}

Problems

• View a list of problems:  GET   /problems
• View a problem:  GET   /problems/{rfc_number}

Known errors

• View a list of known errors:  GET   /knownerrors
• View a known error:  GET   /knownerrors/{known_problems_id}

News

• View a list of news articles:  GET   /news
• View a news article:  GET   /news/{document_id}

• Create a news article:  POST   /news
• Update a news article:  PUT   /news/{document_id}

Actions

• View a list of actions:  GET  /actions

• Create an action:  POST   /requests/{rfc_number}/actions
• Update an action:  PUT   /actions/{action_id}
• Close one or more open actions in a ticket:  PUT   /actions/{rfc_number}

Departments and Locations

  Departments

• View a list of departments:  GET   /departments
• View a department:  GET   /departments/{department_id}

• Update a department:  PUT   /departments/{department_id}

  Locations

• View a list of locations:  GET   /locations
• View a location:  GET   /locations/{location_id}

• Update a location:  PUT   /locations/{location_id}

Configuration items (CI)

• View a list of CIs:  GET  /configuration-items
• View a CI:  GET  /configuration-items/{ci_id}

• Create a CI:  POST   /assets
• Update a CI:  PUT   /assets/{ci_id}
• Create an unavailability for a CI:  POST  /configuration-items/{ci_id}
• End an unavailability for a CI:  PUT  /configuration-items/{ci_id}

  CI links

• View a list of links for a CI:  GET  /configuration-items/{ci_id}/item-links
• View a CI link:  GET  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}

• View links impacting a CI:  GET  /configuration-items/{ci_id}/item-links/impacting
• View links impacted by a CI:  GET  /configuration-items/{ci_id}/item-links/impacted

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

• View a list of records in an external table:  GET  /E_TABLE

• Create a record in an external table:  POST  /E_TABLE
• Update a record in an external table:  PUT  /E_TABLE/{e_table_id}
• Delete a record in an external table:  DELETE  /E_TABLE/{e_table_id}

Others

• Execute an internal query:  GET   /internalqueries
• View Service Manager license key information:  GET  /license

Procedures

How to define access authorization to the Service Manager REST API

Via dedicated Token authentication (creating an access token)

Step 1: Create an access token

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.

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

      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.

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.

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.  See the procedure

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

4. Click  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.

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

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

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

      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.
  

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.

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  next to the REST API option.

The screen displays the list of Service Manager REST API methods as well as the list of external tables available on the platform.
         

4. Click Manage external tables.

The list of external tables available on the platform will appear.
         

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.

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

      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.

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.

4. Save your modifications.

HTTP status codes

StatusHeader

EndStatusHeader

Status200

EndStatus200

Status201

EndStatus201

Status204

EndStatus204

Status400

EndStatus400

Status401

EndStatus401

Status403

EndStatus403

Status404

EndStatus404

Status405

EndStatus405

Status406

EndStatus406

Status409

EndStatus409

Status413

EndStatus413

Status500

EndStatus500

Status503

EndStatus503

Status590

EndStatus590

ConventionsAPI