REST API - Execute an internal query

Last modified on 2023/01/25 16:34
Contents

GET  /internalqueries

  • This method allows data in JSON format of a specified Service Manager reporting to be obtained.

Notes

      Open url.png  See Service Manager REST API Conventions.

  • If successful, an HTTP status code 200 is returned and a URL link (HREF) to the resource is provided.
     

How to quickly obtain Service Manager reporting data in JSON format?

Note: Your profile must be authorized to display the REST API URL menu.

  • Open the screen you want in List mode.
  • Click Tools icon.png in the top banner.
  • Select the Rest API Url option.
    The URL of the active page is generated and copied to the clipboard as follows:
https:~/~/{your_server}}/api/v1/{your_account}/internalqueries?queryguid={query guid id}&filterguid={filter guid id}&viewguid={view guid id}

List of parameters / fields

Mandatory parameters

You must use the parameter below in the URL.
 

Parameter Type Description / Example
queryguid string Parent request identifier (GUID)

Note: If you display in Service Manager a report that you want to use with this method, the value of this parameter should be the value of the QUERYID parameter (or QUERYGUID in some cases) in the report's URL. The value to be extracted is between %7B and %7D. Open url.png See the Examples

Optional parameters

You can use the JSON objects detailed below in the HTTP request string.
 

Parameter Type Description / Example
filterguid string Filter identifier (GUID). If not specified, the Default filter is used.

Note: If you display in Service Manager a report that you want to use with this method, the value of this parameter should be the value of the q2_f in the report's URL. The value to be extracted is between %7B and %7D. Open url.png See the Examples
viewguid string View identifier (GUID). If not specified, the Default view is used.

Note: If you display in Service Manager a report that you want to use with this method, the value of this parameter should be the value of the q2_r in the report's URL. The value to be extracted is between %7B and %7D. Open url.png See the Examples
custom_filter string Supplementary filter, allowing searching a precise record. (See the example next page). Open url.png See Example.
  • The filter needs to be an SQL query and can use the extended Service Manager functions (Example: RTZConvert).
  • To find the SQL syntax of a filter: Proceed to the Filter screen, switch into advanced mode and recopy the SQL query into a text editor.
max_rows integer Maximum number of records which the request must return, to avoid sending too many records

Examples

  • URL for the Execute an internal query methode using queryguid, filterguid, viewguid parameters

https://{your_server}}/api/v1/{your_account}/internalqueries?queryguid=F6AC1BB3-DC03-4E64-BC46-30DEDE3BD27E&filterguid=AAED4F63-76CC-4E09-8C97-2C425D4E48EF&viewguid=DD4F7938-951F-4279-953B-A6EB075FCB35&max_rows=50

  • Report's URL in Service Manager

https://{your_server}/index.php?PHPSESSID=vmpnq9f3n39jjlfjv5curg9mn3&internalurltime=1505123365&theme=%7B8C971D2C-AC44-42AC-86BC-C949A1E1466A%7D&eventName=ViewReport&QUERYID=%7BF6AC1BB3-DC03-4E64-BC46-30DEDE3BD27E%7D&CAPTION=%26lt%3BdynamicTitle%26gt%3BActive+equipment%26lt%3B%2FdynamicTitle%26gt%3B&FILTER_GUID=%7BAAED4F63-76CC-4E09-8C97-2C425D4E48EF%7D&LAYOUT_GUID=%7BDD4F7938-951F-4279-953B-A6EB075FCB35%7D&TASK_GUID=%7B2F4CDDAE-3AAF-4BF4-824A-7E0297E844F0%7D&q2_tree_id=234&q2_level=1&q2_value_selected=TGFzZXI%3D&q2_treetable=2&q2_clickfield=1&clickpage=1&q2_cnt=1&q2_f=%7BAAED4F63-76CC-4E09-8C97-2C425D4E48EF%7D&q2_r=%7BDD4F7938-951F-4279-953B-A6EB075FCB35%7D&OnChangeFilter=false&q2_filter=MjM0%7Cfdc573a242fd004f56d615c38a386195ee90e9a6

  • Application of the additional filter custom_filter  -->  Select only the beneficiary william
custom_filter = (UPPER(AM_RECIPIENT.LAST_NAME) like UPPER('%william'))

==> Result in JSON format

{
   "HREF": "https://{your_server}/api/v1/{your_account}/internalqueries?queryguid=%7B6938436D-B024-4B9E-9815-A41C1D7C7A0E%7D&filterguid=%7B2FAC2998-B0EC-45BF-9B98-1A09B1F8C343%7D&viewguid=%7B631587D5-EED1-49C7-9252-54E08A398CDE%7D&custom_filter=UPPER%28AM_RECIPIENT.LAST_NAME%29%20like%20UPPER%28%27%25william%27%29&max_rows=3",
   "recordcount": 3,
   "previouspage": 0,
   "nextpage": 0,
   "records": [
        {
           "Creation Date": "1/9/2017 11:07:34 am",
           "Incident Number": "I181218_000003",
           "Category": "Get Help",
           "Title": "",
           "Recipient": "William",
           "Description": "",
           "Manager": "",
           "Status": "In Progress",
           "Time Status": "4",
           "Priority": "2",
           "SLA Target": "1/11/2017 11:07:34 am",
           "Cost": "70.00",
           "End Date": ""
        },
        {
           "Creation Date": "8/7/2017 11:41:47 am",
           "Incident Number": "I190124_000001",
           "Category": "Get Help",
           "Title": "",
           "Recipient": "William",
           "Description": "<p>Printer is awful</p>",
           "Manager": "",
           "Status": "In Progress",
           "Time Status": "4",
           "Priority": "2",
           "SLA Target": "8/10/2017 11:41:47 am",
           "Cost": "70.00",
           "End Date": ""
        },
        {
           "Creation Date": "10/10/2017 11:30:23 am",
           "Incident Number": "I181025_000002",
           "Category": "Get Help",
           "Title": "My desktop is broken",
           "Recipient": "William",
           "Description": "<p>My desktop is broken</p>",
           "Manager": "",
           "Status": "In Progress",
           "Time Status": "4",
           "Priority": "2",
           "SLA Target": "10/12/2017 11:30:23 am",
           "Cost": "70.00",
           "End Date": ""
        }
    ]
}
  • Generation of a filter with extended Service Manager functions

({# FILTER_DATE ('SD_REQUEST.SUBMIT_DATE_UT', 'LASTDAYS', '2') #})

Caution: In this specific case, you must replace the # caracters by %23. Otherwise an error is returned.

({%23 FILTER_DATE ('SD_REQUEST.SUBMIT_DATE_UT', 'LASTDAYS', '2') %23})

HTTP status codes for the method

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
Status200
200 OK (Success) Request processed successfully.
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"
}

Examples

Result with a status code 200 returned

{
"HREF": "https://{your_server}/api/v1/{your_account}/internalqueries?queryguid=6938436D-B024-4B9E-9815-A41C1D7C7A0E&filterguid=9194D882-B683-4744-93ED-2625C77DAFED&viewguid=B0103C62-A815-4817-B488-E241C143B366&max_rows=3",
"recordcount": 3,
"previouspage": 0,
"nextpage": 0,
"records": [
{
"Creation Date": "3/14/2008 12:00:00 am",
"Recipient": "Ernst, Walter",
"Incident Number": "040121_017763",
"Category": "Diskette Drive",
"Priority": "2",
"Status": "Reopened",
"Time Status": "4"
},
{
"Creation Date": "6/10/2009 4:16:45 pm",
"Recipient": "User",
"Incident Number": "I090610_000004",
"Category": "Desktop",
"Priority": "2",
"Status": "In progress",
"Time Status": "4"
},
{
"Creation Date": "12/26/2011 1:45:59 pm",
"Recipient": "User",
"Incident Number": "I111226_000002",
"Category": "Desktop",
"Priority": "2",
"Status": "In progress",
"Time Status": "4"
}
]
}
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