Service Manager REST API
- Resources managed by the Service Manager REST API
- Notes
- Best Practice
- Security and license system
- Access the Service Manager REST API
- List of Service Manager REST API methods
- Procedures
- HTTP status codes
- REST API Conventions
Update Click to see the history of updates.
- Management of Service Manager REST API rights access for each external table on the platform (tables prefixed by E_)
- 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
- New methods:
- Create a supplier, Update a supplier, View a list of suppliers, View a supplier
- Download a ticket attachment
- 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
- 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
- New methods: Update asset attribute, Link attribute and asset
- 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
- 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
- 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.
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
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
|
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
- View an asset method ==> GET /assets/{asset_id}
- Update an asset method ==> PUT /assets/{asset_id}
- 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.
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.
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
- Via Token authentication dedicated to the Service Manager REST API (authentication method Service Manager (Access Token)) using an access token.
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
- 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.
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.
4. Save your modifications.
HTTP status codes
StatusHeader
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 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. The |
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)" } } |