Service Manager REST API
Click to see the history of updates
- New methods: Create a CI unavailability ; End a CI unavailability ; View the information of the Service Manager license key
- Create a ticket: New HTTP status code, 406
- All methods: New error code, Timeout
- All methods: New search and filter option by date and by time
- View the URLs for ticket attachments: new variable called document
- View the list of actions: new variables action_type_id and action_type_name
- Create a ticket action: new variable comment
- Create a ticket: new variable impact_id
- New methods: Update an attribute of an asset ; Create a link between an attribute and an asset
- New methods: View a list of news ; View a news ; Create a news ; Update a news ; View all the attributes of a list of assets ; View all the attributes of an asset
- All GET methods: New parameters search, null, not null
- New methods: Upload a document ; 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 a response ; View responses to a list of questions of a ticket ; View the response to a question of a ticket ; Create the response to a question of a ticket ; Modify the response to a question of a ticket
- Filtering resources with a composite key
Definition
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).
EndDefinition
REST API 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 supplier and consumer of REST web services
Service Manager as supplier of REST web services
- Service Manager offers services, named as methods, thanks to its REST API. These are well-defined business functions.
See the list of methods.
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 one. 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
Service Manager as consumer of REST web services
- Service Manager can call web services provided by the REST APIs of other products in order to access external data.
example Call of the Trello REST API to access the list of projects and tasks
- The access to the data is performed using a REST action in a process (workflow or business rule). The external REST web service must be previously declared as a service.
See REST action types settings.
Notes
- 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 ( * ) |
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 |
( * ) 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:- GET /assets/{asset_id} : View an asset method
- PUT /assets/{asset_id} or PATCH /assets/{asset_id} : Update an asset method
- 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.
- 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 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 Service Manager REST API, user access is recorded.
See Service Manager license usage rules.
- 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.
See the Procedure
Access to the Service Manager REST API
- Access to the Service Manager REST API is via a Basic authentication. Login and password are required.
- The Service Manager REST API can be called through steps in the processes (workflows or business rules) using the
EasyVista service.
See REST Action Type Settings.
- Access to the Service Manager REST API methods is via a URL of format: https://{your_server}/api/v1/{your_account}/{resource_name}
- {your_server}: server URL
example https://your_company.easyvista.com - {your_account}: Service Manager account used
example 50004: Production base; 50005: Sandbox base - {resource_name}: Name of the resource called
example requests ; assets ; employees
- {your_server}: server URL
example
List of the Service Manager REST API methods
Assets
Note: The Assets term includes equipment, licenses, 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 the attributes of a list of assets : GET /asset-characteristics
- View all the attributes of an asset : GET /asset-characteristics/{asset_id}
- Create a link between an attribute and an asset : POST /assets/{asset_id}/characteristics/{characteristic_id}
- Update an attribute of an asset : PUT /assets/{asset_id}/characteristics/{characteristic_id}
Catalogs
- View a list of entries of an asset catalog : GET /catalog-assets
- View an asset catalog entry : GET /catalog-assets/{catalog_id}
Links of an asset
- View a list of links of 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
- 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}
SLAs
- View a list of SLAs : GET /slas
- View a SLA : GET /slas/{sla_id}
Tickets
Note: The Tickets term includes incidents, service requests, change requests, investment requests, problems, events.
- View a list of tickets : GET /requests
- View a ticket : GET /requests/{rfc_number}
- View the justification (comment) of a ticket : GET /requests/{rfc_number}/comment
- View the ticket status list : GET /status
- Create a ticket : POST /requests
- Create a task for a ticket : 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 entries of a ticket catalog : GET /catalog-requests
- View a ticket catalog entry : GET /catalog-requests/{catalog_id}
- View all the paths of a list of entries of a ticket catalog : GET /catalog-requests-paths
- View all the paths of a ticket catalog entry : GET /catalog-requests-paths/{catalog_id}
Problems
- View a list of problems attached to tickets : GET /problem-links
- View a list of problems attached to a ticket : GET /requests/{rfc_number}/problems
- View a list of tickets attached to a problem : GET /problems/{problems_id}/requests
Documents
- View all the URLs of documents attached to a ticket : GET /requests/{rfc_number}/documents
- Download document : GET /documents/{document_id}
- Attach documents to a ticket : POST /requests/{rfc_number}/documents
- Delete a document : DELETE /documents/{document_id}
Questions / Questionnaires
- View a list of questions : GET /questions
- View a list of questions with a response : GET /questions-result
- View a question : GET /questions/{question_id}
- View all the responses to a list of questions of a ticket : GET /questions-result/{request_id}
- View the response to a question of a ticket : GET /questions-result/{request_id}/{question_id}
- Create the response to a question of a ticket : POST /questions-result/{request_id}/{question_id}
- Update the response to a question of 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 : GET /news
- View a news : GET /news/{document_id}
- Create a news : POST /news
- Update a news : PUT /news/{document_id}
Actions
- View a list of actions : GET /actions
- Create an action for a ticket : POST /requests/{rfc_number}/actions
- Update an action : PUT /actions/{action_id}
- End one or more ongoing actions of a ticket : PUT /actions/{rfc_number}
Departments / 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 (CIs)
- View a list of CIs : GET /configuration-items
- View a CI : GET /configuration-items/{ci_id}
- Create a CI : POST /configuration-items
- Update a CI : PUT /configuration-items/{ci_id}
- Create a CI unavailability : POST /configuration-items/{ci_id}
- End a CI unavailability : PUT /configuration-items/{ci_id}
Links of a CI
- View a list of links of 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 all the links that have an impact on a CI : GET /configuration-items/{ci_id}/item-links/impacting
- View all the 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 of 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 the information of the Service Manager license key : GET /license
Procedures
Procedure_RESTAPIUserProfile
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. See the procedure.
3. Check the REST API box to give him the authorization to use the Service Manager REST API.
4. Click next to the REST API field to define the access rights to the Service Manager REST API methods.
Procedure_RESTAPIRouteSwitchs
- Check the route (or resources) boxes that the profile can have access.
Display the description of a route on hover over its label.
- For each selected route, indicate if the profile can use the HTTP method (box is checked in the dedicated column) or not (box is not checked).
- GET: Read-only acces
- POST: Write access
- PUT / PATCH: Access for update
- DELETE: Access for delete
EndProcedure_RESTAPIRouteSwitchs
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.
All multilingual data will be displayed in that user's language.
EndProcedure_RESTAPIUserProfile
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.
ManageServiceManagerRESTAPIInProcess_Result
example Create an employee
Result returned if the update is successful
Result returned if the update failed
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
Note: 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 (Success) | Request processed successfully. |
EndStatus200
Status201
201 | Created | Request processed successfully and an item created. |
EndStatus201
Status204
204 | Deleted | Request processed successfully and an item deleted. |
EndStatus204
Status400
400 | Bad Request | Request formulated incorrectly and cannot be executed correctly.
example { "error": "Nothing to update (check fieldnames)" } or for the REST call "Suspend a ticket" with the Response Content: { "error": "The request is already suspended. Operation aborted."} when a ticket is already suspended. or for the REST call "Reopen a ticket" with the Response Content: { "error": "The request is not suspended. Operation aborted."} when a ticket is not suspended. |
EndStatus400
Status401
401 | Unauthorized | Authentication process for accessing the resource is incorrect: Login/Password incorrect, Invalid session, Incorrect Service Manager account.
example { "error": "Invalid Login / Password" } |
EndStatus401
Status403
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. |
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 | Request method not authorized: not supported or not appropriate for the resource.
example { "error": "Invalid input parameter" } |
EndStatus405
Status406
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.
or From the version 2022 - Build 2022.1.109.0.03 Call of the Create a ticket method when the recipient of the ticket does not exist in the Service Manager database or if the recipient does not belong to one of the REST user's domains. |
EndStatus406
Status409
409 | Conflict | Unable to process request in the current state. Records cannot be modified or deleted. |
EndStatus409
Status413
413 | Request entity too large | Processing abandoned because the request was too large. |
EndStatus413
Status500
500 | Internal Server Error | Generic error message displayed when an unexpected condition is encountered and there is no appropriate message which is more specific.<
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 formulated incorrectly and cannot be executed correctly.
or Call of the Suspend a ticket method when a ticket is already suspended. The response { "error": "The request is already suspended. Operation aborted."} will be returned. or Call of the Reopen ticket when the ticket is not suspended. The response { "error": "The request is not suspended. Operation aborted."} will be returned. |
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/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)" } } |