ServiceGrid Article - Cisco ServiceGrid Release Notes V7.2

From DocWiki

Jump to: navigation, search

Contents

Introduction

Cisco ServiceGrid is an integration platform in the cloud for IT service management. It provides a scalable, highly secure, and faster way to integrate with everyone in your service ecosystem, and also meets your business requirements. It creates operational efficiencies that save you time and money, while simplifying the formation of your ecosystem so that you can collaborate faster.
This document describes the key features associated with the ServiceGrid 7.2 Release.
This document contains the following sections:

  • Release Dates
  • System Requirements
  • New and Enhanced Features in Cisco ServiceGrid Release 7.2
  • Important Notes
  • Limitations and Restrictions
  • End-User License Agreement
  • ServiceGrid Documentation
  • Support Information

Release Dates

The Cisco ServiceGrid functions of the Release 2015 (Version 7.2) are available on July 19, 2015 to all customers using the Cisco ServiceGrid main platform (sdcall.solvedirect.com).
Release Notes 7.2 is in production on the Cisco ServiceGrid support platform from July 19, 2015. All customers running their own in-house infrastructure or using a Cisco partner infrastructure will receive the release on a later date. These updates will take place after the update of the Cisco ServiceGrid main platform. Contact your implementation partner for the date of your update.

System Requirements

Cisco ServiceGrid Online application (Portal, SD2) is a web-based application and hence is accessible using a browser. The B2B connection uses the ITSM connection capabilities of the customers.

Table 1 Browser-Policy

Browser Class

Browser

Properties

1

Mozilla Firefox

(last two major versions)

Google Chrome

(last two major versions)

Internet Explorer 11

  • Complete availability of product and application features (technician calendar, HTML-editor, and so on).
  • Graphical presentation (CSS layout).
  • No open browser-related known errors.

2

Internet Explorer 10

  • Limited availability of product and application features.
  • Limited graphical presentation (CSS Layout).
  • There may be browser-related bugs/known errors.

3

Internet Explorer 9

  • Limited availability of product and application features.
  • Highly limited graphical presentation (CSS Layout).
  • Open browser-related bugs/known errors.


The following browser versions were tested for Release 7.2 with respect to the browser classes:

  • Firefox v37, v38
  • Internet Explorer v10, v11
  • Google Chrome v42, v43

NOTE: Active SLA features should be used with the most recent versions of all browsers provided in Browser Class 1 in Table 1, and while using Internet Explorer, “compatibility mode” must be deactivated.

New and Enhanced Features in Cisco ServiceGrid Release 7.2

The following features and enhancements are provided in Cisco ServiceGrid Release 7.2:

  • Rest APIs
    • OAuth 2.0 Authentication
    • Call Services
  • Push (=putcall) a new call or a call update
  • Pull (=getCalls) a new call or a call update
    • Ticket Services
  • Create a New Ticket
  • Update an Existing Ticket
  • Get a list of Tickets
  • Get the Details of One Ticket
  • Rest Client
    •  Authentication Settings with Service Definition
    • Setting Up Re-Authentication Request
  • B2B Connections
    • ServiceGrid Standard JSON Converter
    • Custom JSON Converter
    • Platform name available for Error Messages
  • ServiceGrid Portal
    • User Specific Size of Ticket Detail Window
    • List of Values for Extended Fields
  • Technology, Subtechnology, and Problem Codes
    • Unique ID for TSP Codes
    • Pull all valid TSP codes from a REST API

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

Starting Release 7.2, 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: From release 7.2, 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 (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 (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

Rest Client

Authentication Settings with Service Definition

The new capabilities allow ServiceGrid to act as a REST Client and supports following HTTP verbs (POST, PUT, GET, PATCH and DELETE).
The primary use case for these “rest client capabilities” is to fetch an authentication token from external REST service. If a token has been expired a new one can be easily automatically pulled.
It consists of the following extensions to the existing data model and user interface:

Extentions.png

  • A new field ‘AuthURL’ in the service definition allows the implementation specialist to specify the location of the authentication server. The ServiceGrid authentication URL would be, for example:

https://at1.solvedirect.com/ws/rest/oauth/token

  • A new field ‘AuthRegex’ allows you to specify how to extract the authentication data from a response received from the authentication server.
  • A new macro of the form ${auth.response.regex.n} [where n stands for the capture groups in the regex] configured as the ‘AuthTokenExtractorRegex’ allows the implementation specialist to insert the authentication adata dynamically into the final HTTP request (see example below).
  • The new response filter action ‘Auth’ can be used to instruct ServiceGrid to retry authentication on certain conditions using the existing response filter capabilities to specify the them.

Service definition edit.png

Setting Up Re-Authentication Request

To setup an OAuth2-based re-authenticated integration process, perform the following steps:

Step 1 Set up a new OB trigger (When update by) including a communication (Converter: SDStandardXSL).

Step 2 Add content template similar to the following example (see the comments in the example for details):

<SDHttpMessage>
      <!-- New authorization message element-->
      <AuthorizationMessage>
      <Headers>
          <!-- Will use basic authentication with username and password from the -->
          <!-- service definition unless specified otherwise -->
          <Parameter name="content-type">application/x-www-form-urlencoded</Parameter>
        </Headers>
        <Charset>UTF-8</Charset>
        <HttpMethod>POST</HttpMethod>
        <!-- new url suffix tag allows specification of query params -->
        <!-- as used typically in OAuth2 -->
        <UrlSuffix>?grant_type=client_credentials</UrlSuffix>
        <Message />
        </AuthorizationMessage>
     
        <Headers>
            <Parameter name="Content-Type">application/json</Parameter>
              <!-- results of applying the extractor regex are used here to authenticate the actual payload message -->
            <Parameter name="Authorization">'''''Bearer ${auth.response.regex.1}'''''</Parameter>
        </Headers>
        <Charset>UTF-8</Charset>
        <!-- Supported methods are now POST,GET, PUT and DELETE (with support for non-standard HTTP verbs coming soon-->
        <HttpMethod>GET</HttpMethod>
        <PlainTextMessage>
        </PlainTextMessage>
 </SDHttpMessage> 

Step 3 Add a Service Definition:

  • Define Rest Service URL (Example: https://at1.solvedirect.com/ws/json/v1/push/call)
  • Define the AuthUrl (Example: the ServiceGrid AuthUrl would be https://at1.solvedirect.com/ws/rest/oauth/token)
  • Define UserName/Password combination to get an access token from the external OAuth server
  • Define AuthRegex to extract the authentication data from a response received from the authentication server as the auth token. This Regex example .*”access_token”\s*:\s*”([^”]+)”.* would work for the ServiceGrid authentication server and expose the access token in the first capture group (see the macro appplication ${auth.response.regex.1) above in the template.

Step 4 Add a response filter to the service definition to handle authenticaiton failure and expiring authentication tokens. A typical filter would match on a HTTP response code 401 and would configure the new “Auth-Action”, which triggers a re-authentication attempt with the authentication server and resends the message with the newly obtained authentication data.

NOTE: Starting release 7.2, an administrator can override the target URL of the service definition with that of the SDHttpMessage. To accomplish this, the target URL can be defined within the SDHttpMessage with the new XML tag: <UrlSuffix>NewURL</UrlSuffix>.

B2B Connections

ServiceGrid Standard JSON Converter

A standard JSON format, similar to “SDStandardXML 2.0”, is introduced in the Cisco ServiceGrid release 7.2 to send ticket data in JSON format. In order to use this format within the communication, the standard “SDStandard JSON” converter must be configured.

Edit communication.png

Example of a sample JSON message:

{
    "Calls":
          {
              "Description": "Test ticket with Call-Service API - description",
              "SPCallID": "INC 12345678"
          },
      "Contracts": 
          {
              "ShortName": "Contract"
          },
       "ContractElements": 
          { 
             "ShortName": "ContractElement" 
          },
          "CallStates": 
             { 
                 "ShortName": "01"
              }
}

NOTE: Ensure that the existing system user is not used in any other communications which use an XML converter as this would cause XML parsing errors when sending JSON.

Custom JSON Converter

Starting Release 7.2, a new inbound converter “CustomJsonToXmlConverter” is available for processing the messages sent in a custom JSON format. This converter translates the JSON messages into an XML message, which can then be used for further XSL translations.

NOTE: Message with an invalid JSON format will be rejected.

To test this new converter, messages can be sent to HTTPDirectServlet using username/password and the input message is sent as a body:

The syntax is as shown below:

/ws/distinct/HTTPDirectServlet?SDUser=username&SDPassword=password

Each JSON message is converted into xml format using following rules:

  1. The root element is always called “root” (root/root).
  2. Fields are transformed into nested elements.
  3. JSON field names which are not valid xml tag names are translated into names in which each invalid character is replaced with two underscores as prefix, then ordinal value of that character and one underscore as suffix.
  4. Empty JSON names are translated into tag elements with three underscores as name.
  5. JSON array is translated into nested elements with tag name ___ (three underscores).
  6. Each xml element (including root elements) has type attribute whose value is “original type from JSON”, or there is NIL attribute with value “true” in case the original JSON field contains null values.

Example (input JSON):


JSON Format

XML Format

{
"tickets": [
{
"id": 1234,
"external_id": "9876ABC",
"partner_ticket_id": "P012",
"status": "new",
"title": "Test Ticket",
"description": "Test ticket with comment and attachment",
"severity": "04",
"impact": "Low",
"services_impacted": [],
"assignee": "Name",
"created": "2015-06-01 08:33:45",
"updated": "2015-06-01 11:13:08",
"created_by": "Customer",
"comments": [
{
"author": "Author",
"body": "This is a comment",
"created": "2015-06-01 11:13:08"
}
],
"attachments": [
{
"id": 1,
"ticket": "IFS-123",
"file": "screenshot-01.png",
"created": "2015-06-01 08:15:20"
}
]
}
]
}


<?xml version="1.0" encoding="UTF-8"?>
<root type="object">
<tickets type="array">
<___ type="object">
<id type="number">1234</id>
<external_id
type="text">9876ABC</external_id>
<partner_ticket_id
type="text">P012</partner_ticket_id>
<status type="text">new</status>
<title type="text">Test
Ticket</title>
<description type="text">Test ticket
with comment and attachment</description>
<severity type="text">04</severity>
<impact type="text">Low</impact>
<services_impacted type="array" />
<assignee type="text">Name</assignee>
<created type="text">2015-06-01
08:33:45</created>
<updated type="text">2015-06-01
11:13:08</updated>
<created_by
type="text">Customer</created_by>
<comments type="array">
<___ type="object">
<author
type="text">Author</author>
<body type="text">This is a
comment</body>
<created type="text">2015-06-01
11:13:08</created>
</___>
</comments>
<attachments type="array">
<___ type="object">
<id type="number">1</id>
<ticket
type="text">IFS-123</ticket>
<file
type="text">screenshot-01.png</file>
<created type="text">2015-06-01
08:15:20</created>
</___>
</attachments>
</___>
</tickets>
</root>


JSON examples with more special cases:


JSON Format

XML Format

{
"int" : 1,
"float" : 1.4,
"string" : "text",
"boolean" : true,
"null" : null,
"emptyArray" : [],
"emptyObject" : {},
"object" : {
"inner" : "innerValue"
},
"mixedArray":[1,2.4,"a",true,null,{},{"x":0
},[]],
"0name" : "name with digit as first
character",
"" : "empty name",
":" : "colon name",
"~!@#$" : "some invalid tagname
characters"
}


<center></center><?xml version="1.0" encoding="UTF-8"?>
<root type="object">
<int type="number">1</int>
<float type="number">1.4</float>
<string type="text">text</string>
<boolean type="boolean">true</boolean>
<null nil="true" />
<emptyArray type="array" />
<emptyObject type="object" />
<object type="object">
<inner type="text">innerValue</inner>
</object>
<mixedArray type="array">
<___ type="number">1</___>
<___ type="number">2.4</___>
<___ type="text">a</___>
<___ type="boolean">true</___>
<___ nil="true" />
<___ type="object" />
<___ type="object">
<x type="number">0</x>
</___>
<___ type="array" />
</mixedArray>
<__30_name type="text">name with digit as
first character</__30_name>
<___ type="text">empty name</___>
<__3a_ type="text">colon name</__3a_>
<__7e___21___40___23___24_
type="text">some invalid tagname
characters</__7e___21___40___23___24_>
</root>



Platform Name available for Error Messages

When using XSLT template in the “WhenErrorOccurs” trigger, the element “/SD.call/Error/SystemName” provides the access to the platform name (sdcall, sjc1, eu2-dev, ...). This parameter can be used for setting up business logic based on this value in this template.

Error messages.png

ServiceGrid Portal

User Specific Size of Ticket Detail Window

A new parameter has been added for capturing the current page size of the Cisco ServiceGrid portal. If the user is modifying the size of the ticket detail window, the new size will be retained even after a new login.

List of Values for Extended Fields

With the new release 7.2, the limitation of the field length of extended fields /ExtTableValues/[Field1-128] has been changed from 50 to 255 characters. This feature can be useful if some special fields (CI, Assignment Group, and so on) are available in the service portal through a drop-down menu and the character limit for these drop-down fields be set to 255.

Step 1 Define the table extension and the value lists.Table extention.png

Step 2 Assign this table extention to a call detail.

Assign table extention.png

Step 3 Open CallDetail within service portal.

Open Calldetail.png



Technology, Sub-technology, and Problem Codes

Unique ID for TSP Codes

The T/ST/P codes can be pulled with the new release 7.2 through REST-based service. Therefore, three additional fields have been added to this service:

  • Existing Fields:
    • TechName: former field TechnologyCode
    • SubTechName: former field SubTechnologyCode
    • ProblemCodeDescription: former field problem code
  • Additional Fields:
    • TechId: new field, the unique ID of a technology code
    • SubTechId: new field, the unique ID of a sub technology code
    • ProblemCodeName: new field, the unique key of one problem code

NOTE: By installation of this change, all existing codes are deleted and will be created in the first pull. This means that all codes will be marked as Inserted and will be sent to each partner.

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.



Important Notes

  • Cisco ServiceGrid will be deployed in the setup of all customers running their own in-house infrastructure or using a Cisco Partner infrastructure after ServiceGrid is deployed in the main platform.
  • To know about the release date of Cisco ServiceGrid 7.2 deployment in their setup, the customers need to contact their implementation partner.

Limitations and Restrictions

The following provides the limitations and restrictions in Cisco ServiceGrid Release 7.2:

  • The requirements mentioned in Browser Class 1 in “System Requirements” section provide the minimum system requirements for Cisco ServiceGrid.

End-User License Agreement

All new functions and modules are installed on the corresponding platforms. New functions and modules which are part of the general update are available to all customers of that platform. Some of the new functions and modules must have their license before they are used in customized systems.

ServiceGrid Documentation

Table 2 ServiceGrid Documentation


ServiceGrid DocWiki

ServiceGrid DocWiki manuals, Implementation Guides, and Release Notes Archive:

http://docwiki.cisco.com/wiki/ServiceGrid

ServiceGrid Support Community

Announcements, Release Notes, Support Forum, and Blog:

https://supportforums.cisco.com/community/119 33756/cisco-servicegrid


Support Information

Table 3 Support Information


Cisco Support

email: tac@cisco.com

Phone: http://www.cisco.com/en/US/support/tsd_cisco_world wide_contacts.html#telephone

Web: www.cisco.com/support

Customer/Partner Maintenance Announcements

servicegrid-support@cisco.com

Support Reference Guide

www.cisco.com/web/services/acquisitions/downloads

/solvedirect-tech-support-reference-guide.pdf


Related Articles

APIs in Cisco ServiceGrid


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

For other ServiceGrid Release Notes, go to ServiceGrid Release Notes page.


Download Link: Cisco ServiceGrid Release Notes 7.2



Rating: 0.0/5 (0 votes cast)

Personal tools