ServiceGrid Article - APIs in Cisco ServiceGrid

From DocWiki

Jump to: navigation, search

Contents

Overview

This article provides information about the APIs used in RESTful service for Cisco ServiceGrid application.

APIs used in Cisco ServiceGrid

The following APIs are used in the Cisco ServiceGrid application:

  • OAuth
  • Call Services
    • Push Call and Pull Call
  • Tickets Services
    • Enhancements in Ticket APIs
    • Ticket History API
    • Ticket Events API
  • Get Attachements
  • Post Attachments
  • Adding Extended Fields to Tickets
  • Assigning Technicians to Queues
  • Rest APIs

OAuth

This API is used to provide the Cisco ServiceGrid Customers with the state-of-the-art authentication using the server-to-server OAuth2 authentication method. However, the Customers need to have basic authentication by using their username and password, in order to obtain the OAuth2 authentication token.

The OAuth2 authentication token is obtained through the /ws/rest/oauth/token endpoint using "grant_type=client_credentials" as a query parameter. With OAuth2 authentication, the Customers can read or update tickets for which they have permissions.

The following two methods are used in OAuth API to obtain the OAuth2 authentication:

Method
API endpoint
Description
Support in ServiceGrid
Get
/oauth/authorize
This method is used to obtain the authorization code
Currently not supported. We only support the client credential workflow at the moment.
Post
/oauth/token

This method is used to obtain the access token from the ServiceGrid OAuth Server for authenticating various services. This token and token type must be sent as an Authentication Header.

Only client credential workflow via basic authentication is supported.











For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Call Services

This resource provides a new way of accessing the existing converter and queuing processes. It uses the following POST methods for an event-based asynchronous exchange of tickets (calls).

A message in JSON format is accepted by push/Call and returned by pull/Call The message is converted and further handled as an XML message. It can be sent to host:port/ws/rest/v1/push/call or pulled from host:/port/ws/rest/v1/pull/call. This Rest /JOSN based API service works with basic authentication.

Push Call and Pull Call

Push Call

This asynchronous operation will enqueue a call update/creation. The outcome of the operation will be communicated on a different channel depending on your customization.

Method
API endpoint
Description
Post
/v1/push/call
This method sends new tickets or changed tickets to ServiceGrid.






Example for test push:

cat putcall.json | curl -X POST --user 'user:password' -H "Content-Type: application/json" -d @- -i 'localhost:8080/ws/json/v1/push/call'

putcall.json:
 {
   "Calls": 
     {
      "Description": "Testticket with JSON", 
      "SPCallID": "INC123456"
     },
   "Contracts": 
     {
      "ShortName": "Contract"
     },
   "ContractElements":
     {
      "ShortName": "ContractElement"
     },
   "CallStates": 
     { 
      "ShortName": "INC01"
     }
 }

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Pull Call

This asynchronous operation allows you to pull open and update messages from ServiceGrid using JSON as a message format.

Method
API endpoint
Description
Post
/v1/pull/call

This method is used to retrieve new tickets or changed tickets from ServiceGrid






Example for test pull:

curl -X POST --user 'username:password' -i 'localhost:8080/ws/json/v1/pull/call'

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Tickets Services

This is a new resource of REST services using GET, POST and PATCH methods will allow you to push and pull create and update messages from ServiceGrid and will work with basic user authentication. All synchronous requests will go straight to the database, so it is not necessary to configure any inbound or outbound triggers. This means that no transformation (example: field mappings or business logic) of the JSON messages can be performed within ServiceGrid.

The following methods are used in this API:

Method
API endpoint
Description
Post
/v1/tickets/

A new ticket can be created with this Rest API with the method POST. All ticket attributes are available through this Rest API create operation.

Get
/v1/tickets/

This method is used to list all tickets. The list may be filtered with query parameters. There are some example parameters added to the API Documentation.

/v1/tickets/{id}

This method is used to fetch detailed data of a ticket from ServiceGrid with an id parameter of the resource tickets.

Patch
/v1/tickets/{id}

The HTTP Patch using the HTTP PATCH operations add, remove, replace, copy and move to update tickets using the Rest API.
















For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Enhancements in Ticket APIs

From release 8.0, all Tickets APIs are enhanced with the ability to filter date ranges on appropriate date fields. The date range filters such as “from” and “to” time intervals are defined for all GET and PATCH
methods. This new feature allows queries that can specify a range up to a date, from a certain date, or the range between two values.

Example Queries: 1

tickets/?openTimeUtc=ge=2012-01-01 12:00
or
tickets/?ge(openTimeUtc, 2012-01-01 12:00)
Both of these queries are equal and are supported. Here the 'ge' refers to greater equal,
so the above queries will filter for all tickets with a openTimeUtc value equal to and
greater than 2012-01-01 12:00
tickets/?openTimeUtc=le=2012-01-01 12:00
or
tickets/?le(openTimeUtc, 2012-01-01 12:00)
Both of these queries are equal and are supported. Here the 'le' refers to less equal, so
the above queries will filter for all tickets with a openTimeUtc values up to and equal to
2012-01-01 12:00.
tickets/?openTimeUtc=ge=2012-01-01 12:00&openTimeUtc=le=2012-02-02 12:00
or
tickets/?ge(openTimeUtc, 2012-01-01 12:00)&le(openTimeUtc,2012-02-02 12:00)
Both of these queries are equal and either syntax is supported. The above queries will
retrieve filter for all tickets with openTimeUtc values greater or equal to 2012-01-01
12:00 and less than equal to 2012-02-02 12:00.

Example Queries: 2
All characters except for "a-zA-Z0-9-._~*" (lowercase, uppercase, digits, minus, dot, underscore, tilde, asterisk) used for values in query parameterss must be url-encoded.

Created tickets with diff ExtField1 (string)... and filter for it

ExtField1=a:b
https://{host}:443/ws/rest/v1/tickets/?extended.field1=a%3Ab        ": " encoded to %3A
https://{host}:443/ws/rest/v1/ticket-events/?extended.field1=a%3Ab

ExtField1=a_b
https://{host}:443/ws/rest/v1/tickets/?extended.field1=a_b
https://{host}:443/ws/rest/v1/ticket-events/?extended.field1=a_b

Remarks=ä()@
https://{host}:443/ws/rest/v1/ticket-events/?remarks=ä%28%29%40

"remarks": "a-zA-Z0-9-._~*"
https://{host}:443/ws/rest/v1/tickets/?remarks=a-zA-Z0-9-._~*

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Ticket History API

In release 8.0, this is a new resource of the ServiceGrid REST services. This will be introduced using the GET method that will allow you to fetch all history records of one ticket or to fetch the detail of a
single history record of a ticket. This API is useful if you want to build an own user interface for ticket management based on ServiceGrid data.

The following table provides the details of this API:

Method
API endpoint
Description
Get

/v1/ticket/{ticketId}/history/

This method is used to list all history records of one ticket. The id of the ticket is defined within the resource.

/v1/ticket/{ticketId}/history/eventId

With this method, one single history record of a ticket can be pulled. Both the id of the ticket and the id of the history record (eventId) are defined within the resource.









Example request for getting all history reocrds of one ticket:

curl -i -H "Authorization: Bearer {auth-token} -H "Content-Type: application/json" -X GET https://{host}/ws/rest/v1/tickets/{ticketId}/history

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Ticket Events API

This is a new resource of the ServiceGrid REST services. This will enable the GET method to pull all new tickets and all ticket updates (“Ticket Events”) from ServiceGrid for a certain timeframe. This API
can be used if a B2B connection to a partner system is built using the REST APIs. This API enables the partner to catch all new tickets and all ticket updates that happened within the requested timeframe.

The following method is provided by this API:

Method API endpoint Description
Get /v1/ticket-events This method is used to  list all tickets and ticket updates. The list can be filtered with query parameters.


Example request for catching all events between 2015-12-23 08:10 and 08:15:

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X 
GET https://{host}/ws/rest/v1/ticket-events?limit=20&editTimeUtc=gt=2015-12-23%2008:10&editTimeUtc=le=2015-12-23%2008:15

NOTE: Spaces must be replaced with “%20”as in “2015-12-23%2008:15”, because they are not allowed within URL.

If there are more than 20 records available, you can pull the other pages using the next-link, which is provided in the link section of the response. A next-link is available as long as further records can be pulled with these filter parameters.

"_links" : [ {
"rel" : "prev",
"method" : "GET",
"href" :
"https://{host}//ws/rest/v1/ticket-events?since_id=200532291&max_id=999999999&limit=20&editTimeUtc=gt=2015-12-23%2008:10&editTimeUtc=le=2015-12-23%2008:15"
}, {
"rel" : "next",
"method" : "GET",
"href" :
"https://{host}//ws/rest/v1/ticket-events?max_id=200532267&limit=20&editTimeUtc=gt=2015-12-23%2008:10&editTimeUtc=le=2015-12-23%2008:15"
}, {
"rel" : "list",
"method" : "GET",
"href" :
"https://{host}//ws/rest/v1/ticket-events?limit=20&editTimeUtc=gt=2015-12-23%2008:10&editTimeUtc=le=2015-12-23%2008:15"
} ]

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Get Attachments

Starting release 7.3, a new API is implemented for pulling attachments from a ticket.

The following methods are used in this API:

Method
Usage Format
Description
Get
v1/tickets{ticketid}attachments/

This API method allows you to pull all attachments from a ticket through a ticket ID. This GET method supports as a response, the content-type parameter “application/json” only for a base64 encoded content.

/v1/tickets{ticketid}attachments/{sattachmentId}

This API method allows you to pull only one attachment, based on the ticket ID and the attachment ID. This GET method supports as a response, the two content-types, “application/json” for a base64 encoded content and the parameter “application/octect-stream” for a raw content.












To be able to use this API, a valid access token need to be fetched through the endpoint “/ws/rest/oauth/token”.

For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Post Attachments

This is a new API introduced in release 7.3 to send or assign attachments to an existing ticket.

The following method is used in this API:

Method
Usage Format
Description
Post
v1/tickets{ticketid}attachments/

This Post method sends the attachments to an existing ticket. The content-type parameter must be defined as “application/json” to be able to transmit the attachment through a base64 encoded content.







To be able to use this API, a valid access token need to be fetched through the endpoint “ws/rest/oauth/token”. For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Adding Extended Fields to Tickets

Cisco ServiceGrid release 7.3 supports sending and receiving of extended fields for all RESTful ticket APIs.

Method
Usage Format
Description
Post
v1/tickets/

Using this Post method, the extended fields can be used in JSON format when creating a new ticket.






"extended": {

   "field1": "value1",
   "field128": "value128"
}
Method
Usage Format
Description
Patch
v1/tickets{id}/

Using this PATCH method, the extended fields can be used in JSON format when updating an existing ticket.






[{

   "op": "replace",

   "path": "/extended/field1",

   "value": "update1"

}]

To be able to use this API, a valid access token need to be fetched through the endpoint “ws/rest/oauth/token”. For more details on this API, see the Cisco ServiceGrid Rest API Documentation.

Assigning Technicians to Queues

Cisco ServiceGrid release 7.3 supports assigning technicians to a queue through all RESTful Ticket APIs.

The following method is used in the APIs:

Method
Usage Format
Description
Post
v1/tickets/

This Post method is used to create a new ticket by specifying short names of the entities like contracts, contract elements, and so on.






"queueOne": {"shortName": ""},
"queueTwo": {"shortName": ""},
"queueThree": {"shortName": ""},
"technicianOne": {"shortName": ""},
"technicianTwo": {"shortName": ""},
"technicianThree": {"shortName": ""}

To be able to use this API, a valid access token need to be fetched through the endpoint “ws/rest/oauth/token”. For more details on this API, see the Cisco ServiceGrid Rest API Documentation


Rest APIs

The Cisco ServiceGrid Release 7.2 has introduced the Rest API functionality to enable the customers to:

  • access ticket data using the Rest API,
  • send the ticket details to the Rest Service after the tickets are created or updated,
  • retrieve changed tickets from the Rest Service.

Rest API service provides two new services for the exchange of tickets:

  • Call Services
  • Ticket Services

OAuth 2.0 Authentication

ServiceGrid supports the open standard or framework for authorization “OAuth 2.0”. It is a defacto-standard to provide client applications a “secure delegated access” to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. OAuth essentially allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The client then uses the access token to access the protected resources hosted by the resource server.

Clients must use their ServiceGrid username and password for basic authentication to obtain the OAuth access token through the /ws/rest/oauth/token endpoint using “grant_type=client_credentials” as a query parameter.

NOTE: The access token obtained from the ServiceGrid OAuth Server must be used to authenticate all REST services of ServiceGrid. The obtained token together with the token type must be sent as an “Authorization Header” parameter.

Call Services

Call services provides a new way of accessing the converter and queuing processes. It uses the following POST methods for an event-based asynchronous exchange of tickets (calls). A message in JSON format is accepted by push/Call and returned by pull/Call. In this release, the message is converted and further handled as an XML message. It can be sent to host:port/ws/rest/v1/push/call or pulled from host:/port/ws/rest/v1/pull/call. This Rest API service resource works with basic authentication.

Push (=putcall) a new call or a call update

This new API allows you to push, create and update messages to ServiceGrid using JSON as a message format.

API endpoint: host:port/ws/rest/v1/push/call

In order to use the putCall operation, an appropriate inbound trigger must be configured. This inbound trigger needs to have a communication using:

  • SDStandardJSON or CustomJsonToXmlConverter as converter and
  • HTTPS POST as communication type (HTTPDirect)

NOTE: Add a user with the permission group ‘SYS’ to the communication, which will be used for the authentication process. To create a call, a contract and a contract element must be transmitted.

Example for doing a test push of a message:

cat putcall.json | curl -X POST --user 'user:password' -H "Content-Type: application/json"-d @- -i '{host}:8080/ws/json/v1/push/call'

putcall.json:

{

"Calls": {

    "Description": "Testticket with JSON", 
    "SPCallID": "INC123456"

 },

"Contracts": {

    "ShortName": "Contract"

},

"ContractElements": {

    "ShortName": "ContractElement"

},

"CallStates": { 
    "ShortName": "INC01"

}

} 

Test push message.png


Pull (=getCalls) a new call or a call update

This API allows you to pull open and update messages from ServiceGrid using JSON as a message format.

API endpoint: host:port/ws/rest/v1/pull/call

In order to use getCall, an appropriate outbound trigger must be configured. This outboud trigger must have a communication using

  • SDStandardJSON or CustomJsonToXmlConverter as converter and
  • HTTPS POST as communication type (HTTPDirect)

NOTE: Add a user with the permission group ‘SYS’ to the communication, which will be used for the authentication process.

Example for doing a test pull of a message:

curl -X POST --user 'user:password' -i 'host:8080/ws/json/v1/'''pull'''/call'

Test pull message.png

Ticket Services

Ticket Services is a new resource of Rest services using GET, POST and PATCH methods will allow you to push and pull create and update messages from ServiceGrid and will work with basic user authentication. All synchronous requests will go straight to the database, hence it is not necessary to configure any inbound or outbound triggers. This means that no transformation (for example, field mappings or business logic) of the JSON messages can be performed within ServiceGrid.

Create a New Ticket

A new ticket can be created with this Rest API with the method POST. All ticket attributes are available through this Rest API create operation

API endpoint: host:port/ws/rest/v1/tickets

Creating ticket.png

NOTE: See online documentation at hostname/ws (Cisco ServiceGrid Rest API Documentation) for detailed information about the expected JSON format. All POST requests must be authenticated using an OAuth Bearer token in the Authorization HTTP header.

Update an Existing Ticket

ServiceGrid tickets can be updated through the Rest API using the HTTP PATCH operations such as add, remove, replace, copy and move and the JSON PATCH format.

API endpoint: host:port/ws/rest/v1/tickets/{ID}

This sample request would update the field “description” with the new value “overwrite description”.

[{ "op": "replace", "path":"/description", "value" : "overwrite description" }]

Updating ticket.png

NOTE: A list of all attributes that can be changed through PATCH is retrieved through the online API documentation which is available at hostname/ws (Cisco ServiceGrid Rest API documentation). All PATCH requests must be authenticated using an OAuth Bearer token in the Authorization HTTP header.

Get a list of Tickets

With the API method GET, a list of tickets including query parameters can be fetched from ServiceGrid.

API endpoint: host:port/ws/rest/v1/tickets?offset=0&limit=1

Ticket list.png

NOTE: v1 does not support “from-to” filters. Hence, filtering for timestamps and data fields might not be in the scope of this release. All GET requests need to be authenticated using an OAuth Bearer token in the Authorization HTTP header.

Get the Details of One Ticket

With this API method, the detailed data of a ticket can be fetched from ServiceGrid.

API endpoint: host:port/ws/rest/v1/tickets{id}

Single ticket detail.png

Date Format Enhancement

From release 8.1, an additional date format parameter has been included in all Get requests of all tickets APIs (Tickets, Ticket Events, and Ticket History). This parameter allows the specification of the date
format that would be received in the response.

The following date formats can be specified through this new parameter:
• yyyy-MM-dd HH:mm:ss
• dd-MM-yyyy HH:mm:ss
• yyyy-MM-dd HH:mm
• dd-MM-yyyy HH:mm

Sample Request for Ticket-History API with date format “yyyy-MM-dd HH:mm:ss”

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X 
GET https://{host}/ws/rest/v1/tickets/{ticketId}/history?dateFormat=dd-MM-yyyy%20HH%3Amm%3Ass


Example Response

{
"_links": [
{}
],
"tickets": [
{}
],
"acknowledgeTimeUtc": "2016-01-19 11:57:31",
"closeTimeUtc": "2016-01-21 12:15:15",

NOTE: If this parameter is not specified in the request, the default date format (yyyy-MM-dd HH:mm) is returned in the response. The URL requires encoding for characters like ‘colon’ (%3A) and space character (%20).

Support for XML Content Type

From release 8.1, XML structure is supported for all the following Rest APIs:

  • Tickets: (/v1/tickets/)
  • Ticket Events: (/v1/ticket-events/)
  • Ticket History: (/v1/tickets/{ticketId}/history/{eventId})
  • Attachments: (/v1/tickets/{ticketId}/attachments/attachmentId})
  • TSP-Codes: (/v1/tsp-codes/)

The implementation of this feature serves the following purposes:

  • POST services accept both content-types “application/json” and “application/xml” as an input content-type
  • PATCH services accept “application/json-patch+json” and “application/xml” as an inputcontent-type
  • GET services can produce “application/json” or “application/xml”

Input content-type is defined through Content-Type header sent by client. Output content-type can be requested using the Accept header. Clients can send multiple accepted content-types ordered using
“quality value” or “qvalue” parameter as specified by RFC7231.

The XML structure is similar to the one obtained from a “JsonToXML” conversion.

Samples:
List Ticket

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -H
"Accept: application/xml" -X GET https://{host}/ws/rest/v1/tickets/{ticketId}


Example Response

<?xml version="1.0" encoding="UTF-8"?>
<root type="object">
  <_links type="array">
    <___ type="object">
      <rel type="text">prev</rel>
      <method type="text">GET</method>
      <href type="text">https://{host}/ws/rest/v1/tickets/?ticketId=200532641&amp;since_id=200532641&amp;limit=25</href>
    </___>
    <___ type="object">
      <rel type="text">create</rel>
      <method type="text">POST</method>
      <href type="text">https://{host}/ws/rest/v1/tickets</href>
    </___>
    <___ type="object">
      <rel type="text">list</rel>
      <method type="text">GET</method>
      <href type="text">https://{host}/ws/rest/v1/tickets</href>
    </___>
  </_links>
  <tickets type="array">
    <___ type="object">
      <_links type="array">
        <___ type="object">
          <rel type="text">self</rel>
          <method type="text">GET</method>
          <href type="text">https://{host}/ws/rest/v1/tickets/200532641</href>
        </___>
        <___ type="object">
          <rel type="text">attachments</rel>
          <method type="text">GET</method>
          <href type="text">https://{host}/ws/rest/v1/tickets/200532641/attachments</href>
        </___>
        <___ type="object">
          <rel type="text">ticketHistory</rel>
          <method type="text">GET</method>
          <href type="text">https://{host}/ws/rest/v1/tickets/200532641/history</href>
        </___>
      </_links>
      <acknowledgeTimeUtc type="text">2016-01-19 11:57</acknowledgeTimeUtc>
      <closeTimeUtc type="text">2016-01-21 12:15</closeTimeUtc>
      <contract type="object">
        <name type="text">playground</name>
        <shortName type="text">playground</shortName>
      </contract>
      <contractElement type="object">
        <name type="text">playground</name>
        <shortName type="text">playground</shortName>
      </contractElement>
      <customer type="object">
        <organization type="object">
          <company type="object">
            <name type="text">Playground_REST</name>
            <shortName type="text">Playground_REST</shortName>
          </company>
          <name type="text">Customer</name>
          <shortName type="text">CUS</shortName>
        </organization>
      </customer>
      <description type="text">Test ticket with Ticket-Service API - description_2016</description>
      <editTimeUtc type="text">2016-01-21 12:15</editTimeUtc>
      <editor type="object">
        <firstName type="text">playground</firstName>
        <lastName type="text">admin</lastName>
        <shortName type="text">playground_admin</shortName>
      </editor>
      <eventId type="number">200532882</eventId>
      <extended type="object">
        <field1 type="text">field1Value</field1>
      </extended>
      <isClosed type="boolean">true</isClosed>
      <isTestTicket type="boolean">false</isTestTicket>
      <openTimeUtc type="text">2016-01-19 11:57</openTimeUtc>
      <provider type="object">
        <organization type="object">
          <company type="object">
            <name type="text">Playground_REST</name>
            <shortName type="text">Playground_REST</shortName>
          </company>
          <name type="text">Incidents</name>
          <shortName type="text">INC</shortName>
        </organization>
      </provider>
      <providerTicketId type="text">INC1222287382343434 </providerTicketId>
      <receiveTimeUtc type="text">2016-01-19 11:57</receiveTimeUtc>
      <recoveryTimeUtc type="text">2016-01-19 11:58</recoveryTimeUtc>
      <remarks type="text">Incident closed</remarks>
      <requestType type="object">
        <name type="text">Incident</name>
        <shortName type="text">INC</shortName>
      </requestType>
      <responseTimeUtc type="text">2016-01-19 11:58</responseTimeUtc>
      <retentionPstMinutes24 type="text">0:00</retentionPstMinutes24>
      <retentionPstMinutesSL type="text">0:00</retentionPstMinutesSL>
      <retentionTimeUtc type="text">2016-01-21 12:15</retentionTimeUtc>
      <role type="object">
        <name type="text">Service Provider</name>
        <shortName type="text">SP</shortName>
      </role>
      <solution type="text">solved</solution>
      <startSlaTimeUtc type="text">2016-01-19 11:57</startSlaTimeUtc>
      <ticketId type="number">200532641</ticketId>
      <ticketState type="object">
        <name type="text">Incident closed</name>
        <shortName type="text">INC19</shortName>
      </ticketState>
      <totalAcknowledgeMinutes type="text">0:00</totalAcknowledgeMinutes>
      <totalRecoveryMinutes type="text">0:01</totalRecoveryMinutes>
      <totalResponseMinutes type="text">0:01</totalResponseMinutes>
      <workflow type="object">
        <name type="text">Provider</name>
        <shortName type="text">Provider</shortName>
      </workflow>
    </___>
  </tickets>
</root>

New Attachment

<root type="object">
  <content type="text">YXNkZmFzZGZh</content>
  <fileName type="text">newFile.txt</fileName>
</root>

Creating Ticket

<root type="object">
<contract type="object">
    <shortName type="text">Service</shortName>
  </contract> 
  <contractElement type="object">
       <shortName type="text">SL1</shortName>
  </contractElement>
  <ticketState type="object">
    <shortName type="text">OPEN</shortName>
  </ticketState>
</root>

Updating Ticket

<root type="array">
  <___ type="object">
    <op type="text">replace</op>
    <path type="text">/remarks</path>
    <value type="text">New Remark</value>
  </___>
</root>

<root type="array">
  <___ type="object">
    <op type="text">add</op>
    <path type="text">/priority</path>
    <value type="object">
      <shortName type="text">1</shortName>
    </value>
</___>
</root>


Health Check for ServiceGrid APIs

This is a new resource of the Cisco ServiceGrid REST services. A new API is implemented in release 8.1 to perform the health check of Cisco ServiceGrid APIs.

The following method is provided by this API:

Method
API endpoint
Description
Get
/v1/health
This method can be used to check the connectivity from a partner system to Tomcat-WS of Cisco ServiceGrid






To perform this health check, a Get request can be sent without any additional authentication information. The API responds with current time stamp in the response body.

Sample Request

curl https://{host}/ws/rest/v1/health


Example Response

{
"Timestamp": "2016-04-13T14:12:28.607Z"
}


Not Operator

As of ServiceGrid 8.4, the ‘not’ operator is supported in RQL queries via the ServiceGrid REST APIs.

Examples (all equivalent):

/tickets/?editor.shortName=ne=somename
/tickets/?ne(editor.shortName,somename)



(ne = Not Equal)


Health Check API

The API endpoints for the ServiceGrid health-check REST API have been amended in releasing version 8.4:

/ws/rest/v1/health/node Run a simple health check for the current node
/ws/rest/v1/health/platform Run a platform health check
/ws/rest/v1/health/ Remains unchained, runs a simple health check (synonym for /node)


Health api.png

Support for Ordering Parameter in GET Requests

Starting from release 8.2, the Rest API supports inclusion of an additional parameter called “ordering” in the GET requests of the following Rest API endpoints:

  • Tickets ({host}/ws/rest/v1/tickets/)
  • Ticket Events ({host}/ws/rest/v1/ticket-events/)
  • Ticket History ({host}/ws/rest/v1/tickets/{ticketId}/history/)
  • Attachments ({host}/../tickets/{ticketId}/attachments/)
  • TSP-Codes ({host}/ws/rest/v1/tsp-codes/)


One of the following two values can be used in the “ordering” parameter:

  • desc—This is the default value of the “ordering” parameter. If this value is used in the “ordering” parameter, the most recent updates are displayed at the top.

Example request to Tickets API:

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X GET https://{host}/ws/rest/v1/tickets?ordering=desc

NOTE: If no values are used, the most recent updates are displayed at the top. This is similar to the result that would be displayed when ‘desc’ value is used.

  • asc—If this value is used in the “ordering” parameter, the oldest entries are displayed at the top. In addition, the “next”t and the “previous” links are logically reversed when the ordering parameter is set to have the value as ascending.

Example request to Tickets API:

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X GET https://{host}/ws/rest/v1/tickets?ordering=asc

For more details, see Cisco ServiceGrid Rest API Documentation.

Support for Ticket EventId in JSON Attachments

From release 8.2, the Ticket EventId can now be used as a filtering parameter within the GET request of the attachment APIs to filter and pull all the attachments associated with a ticket event.


Example request of attachment API:

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X GET
https://{host}/ws/rest/v1/tickets/{tickeId}/attachments?eventid={eventid}

The Ticket EventId will be displayed in the “json/xml” responses of the attachment APIs too. For more details, see Cisco ServiceGrid Rest API Documentation.

Support for PUT Method for Ticket Updates

From release 8.2, the PUT method is supported in REST API for updating the tickets. This method is used by customers, where their environment does not support the HTTP PATCH method.

curl -i -H "Authorization: Bearer {auth-token}" -H "Content-Type: application/json" -X PUT
https://{host}/ws/rest/v1/tickets/{tickeId} 

NOTE:  Customers that can support HTTP PATCH are advised to use PATCH over HTTP PUT method.

The PUT method completely replaces the resource with the given ID represented and sent in the request. There are some impacts by using this method for ticket updates:

  • Attributes that are not being sent in the resource will be deleted. This is not applicable for HTTP PATCH method.
  • If the required attributes are not sent in the request, it will lead to a failure. This is not applicable for HTTP PATCH method.

NOTE: The request structure of PUT method is similar to that of the existing HTTP POST method. For more details, see Cisco ServiceGrid Rest API Documentation

Support for Transaction Revision

This new feature allows HTTP clients to their intention of which revision of the ticket they want to update requests through the IF-MATCH header in combination with PUT or PATCH method.

The server can then check that revision and reject the update if the revision communicated through IF-MATCH is not the latest revision of the affected entity.
Example request of Tickets API via the HTTP PATCH method:

curl -I -X PATCH -H"Authorization: Bearer {auth-token}" -H "Content-Type:
application/json-patch+json" -H GET ”IF-MATCH: {eventid}
“https://{host}/ws/rest/v1/tickets/{tickeId}” -d ‘[{“op”: “replace”, “path”: “/remarks”, “value”: “if-match test”}]’

For more details, see Cisco ServiceGrid Rest API Documentation

Technology, Sub-technology, and Problem Codes

Pull all valid TSP codes from a REST API

There are already multiple ways of how SG partners can access the list of Cisco TSP codes stored in SG (mail, ftp, pull, and so on). With the release 7.2, it is now possible to pull these codes through a REST API with the method GET.

API endpoint: host:port/ws/rest/v1/tsp-codes

Use the query parameters ‘offset’ and ‘limit’, for defining the range of TSP codes user wants to access/download. The API will always deliver back all valid codes.

TSP Codes.png

NOTE: Users who are able to access the TSP Code list are defined using the CiscoPartners table.


For a complete list of Cisco ServiceGrid Articles, go to the List of Articles page.

Related Articles






Rating: 0.0/5 (0 votes cast)

Personal tools