Configuring Change Management Approvals

MSX platform provides an approval process for configuration change requests made by a user. If there is a change request on MSX, the request (including the Entity ID, Entity CR date, Context source path, and url) is forwarded to ServiceNow through the Change Request service.


Note

Only tenants with a ServiceNow account can use this functionality.

The following are some examples of the types of change requests on MSX that can use the approval functionality from ServiceNow:

  • Device configuration applied through template application.

  • Removal of a device from MSX management.

  • Add, Update, Delete of Standard Configuration definitions and values.

Before you Begin

Perform the following steps in the ServiceNow web interface:

  1. Create a MSX user group for the change approval.

  2. Create a REST message for the MSX API token. For more information, see Creating REST Message for MSX API Token in ServiceNow

  3. Create a business rule for the MSX approval and rejection process. For more information, see Creating Business Rule for Approval and Rejection Notification from ServiceNow to MSX

The following is the service change request flow from MSX to ServiceNow.

Procedure

Step 1

Ensure the change request is available on the ServiceNow web interface.

The change request from MSX is automatically created on ServiceNow when a configuration change is received from MSX. You can view the open change request on the ServiceNow service management web interface. For more information on how to view open change request, refer to the ServiceNow documentation.

Step 2

Request for Approval on the ServiceNow. For more information on how to request for an approval, refer to the ServiceNow documentation.
Step 3

Approve/Reject the change request from the ServiceNow application.

Note 

Only a user from this group can approve or reject a change request. After the user from the MSX assignment group approves the request, the request is sent to another group, the Change Advisory Board (CAB) approval group, for the final approval.

For more information on approving or rejecting a change request, refer to the ServiceNow documentation.

The state of the approved request changes to Scheduled state in the ServiceNow.
Step 4

On MSX, you can use one of the following APIs from the Change Management Service to see the status of the request.

  • GET /api/v1/changerequest/{id}/history

  • GET /api/v1/changerequest/{id}

Creating REST Message for MSX API Token in ServiceNow

Before you begin

Create a user group for the MSX change approval.

Procedure

Step 1

For detailed procedure on creating an API Token, see the ServiceNow documentation.
Step 2

For the MSX token, ensure that you update the following details while creating a new API token:

  • Name and Description

  • Endpoint as https://<msx portal fqdn>/idm/v2/token

  • In the Authentication tab, click Access Token and select the HTTP method as POST.

  • In the HTTP Request tab, enter the following details:

    • Authorization value as the custom client secret. The custome client secret value is provided while adding a new SSO client. For more information, see the section, ''Configuring SAML or Non-SAML Based SSO Client''.

    • Content-Type as application/x-www-form-urlencoded.

    • Content value in the HTTP Query Parameters section as grant_type=password&username=custom-user&password=custom-user-password.

      You can create a custom user using the Adding a User procedure.

      Note 

      Make sure the custom user has the roles assigned as either a Tenant Administrator or an Operator role.

What to do next

Create a business rule for approval or rejection notification from ServiceNow to MSX. For more information, see Creating Business Rule for Approval and Rejection Notification from ServiceNow to MSX

Creating Business Rule for Approval and Rejection Notification from ServiceNow to MSX

Before you begin

Create a REST Message for MSX API Token in ServiceNow.

Procedure

Step 1

Create two business rules for the approval and the rejection notifications. For detailed procedure on creating business rules, see the ServiceNow documentation.

Step 2

For the approval and rejection notifications to work on MSX, ensure that you update the following details when you create the business rules for approval and rejection.

  • Check the Active and Advanced check boxes.

  • Click the When to run tab and select the required options and Filter Conditions.

  • Click the Advanced tab and add the approval or reject business rule script as given below:

    Approval Business Rule Script
    var msxAPIAccessToken;

function GetMSXToken() {
	var request = new sn_ws.RESTMessageV2('MSX API Token', 'Access Token');

	var response = request.execute();
	var httpResponseStatus = response.getStatusCode();

	gs.info("Response status code is " + httpResponseStatus);
	if (httpResponseStatus == 200) {
		responseObj = response.getBody();
		var res = JSON.parse(responseObj);
		msxAPIAccessToken = res.access_token;
	} else {
		//error
		gs.log(response.getErrorCode() + "---" + response.getErrorMessage());
	}
}

function SendApproval() {
	
	GetMSXToken();

	
	request = new sn_ws.RESTMessageV2();
	request.setHttpMethod("post");
	var msxUrl = gs.getProperty('msx.baseurl');


	request.setEndpoint(msxUrl + '/changemanagement/api/v1/changerequests/'+current.number+'/approve');
	//TO Be replaced with MSX Change Request Approve
	request.setRequestHeader("Authorization", "Bearer "+ msxAPIAccessToken);
	
	//TODO:: form dynamic date and retry request
	var glideTime=new GlideDateTime();
	var formattedDate = glideTime.getDate().getDisplayValue() + "T" + glideTime.getTime().getDisplayValue() + glideTime.getTZOffset() + "Z";

	request.setRequestBody('{"details": "approving",  "modifiedBy": "serviceNowAdmin",  "modifiedOn": '+ formattedDate +'}');
	
	var response = request.execute();
	var httpResponseStatus = response.getStatusCode();

	gs.info("Response status code is " + httpResponseStatus);
	if (httpResponseStatus == 201) {
		responseObj = response.getBody();
		var res = JSON.parse(responseObj);
		
	} else {
		//error
		gs.log(response.getErrorCode() + "---" + response.getErrorMessage());
	}
	
	
}

(function executeRule(current, previous /*null when async*/) {

	SendApproval();
	

})(current, previous);

    Reject Business Rule Script

    var msxAPIAccessToken;

function GetMSXToken() {
	var request = new sn_ws.RESTMessageV2('MSX API Token', 'Access Token');

	var response = request.execute();
	var httpResponseStatus = response.getStatusCode();

	gs.info("Response status code is " + httpResponseStatus);
	if (httpResponseStatus == 200) {
		responseObj = response.getBody();
		var res = JSON.parse(responseObj);
		msxAPIAccessToken = res.access_token;
	} else {
		//error
		gs.log(response.getErrorCode() + "---" + response.getErrorMessage());
	}
}

function SendRejection() {
	
	GetMSXToken();
	
	request = new sn_ws.RESTMessageV2();
	request.setHttpMethod("post");
	var msxUrl = gs.getProperty('msx.baseurl');

	request.setEndpoint(msxUrl + '/changemanagement/api/v1/changerequests/'+current.number+'/reject');

	request.setRequestHeader("Authorization", "Bearer "+ msxAPIAccessToken);

	var glideTime=new GlideDateTime();
	var formattedDate = glideTime.getDate().getDisplayValue() + "T" + glideTime.getTime().getDisplayValue() + glideTime.getTZOffset() + "Z";

	request.setRequestBody('{"details": "rejecting",  "modifiedBy": "serviceNowAdmin",  "modifiedOn": '+ formattedDate +'}');
	
	var response = request.execute();
	var httpResponseStatus = response.getStatusCode();

	gs.info("Response status code is " + httpResponseStatus);
	if (httpResponseStatus == 201) {
		responseObj = response.getBody();
		var res = JSON.parse(responseObj);
		
	} else {
		//error
		gs.log(response.getErrorCode() + "---" + response.getErrorMessage());
	}
	
	
}

(function executeRule(current, previous /*null when async*/) {

	SendRejection();
	

})(current, previous);

Managing Billing

The Cisco MSX platform has the ability to identify, track, and report the various subscription billing activities that happen across the MSX system using Billing Services API. Using Billing Services API, inventory reports can also be generated. You can manage the billing for several items such as devices, sites, control plane, general purpose events and services.


Note

By default, the only Service Pack that has currently implemented a price/cost model using the Billing Service is SD WAN. Other Service Packs may implement this functionality in the future.

The Billing Service API also provides event-based billing capabilities for the tenants. The events that are registered from the service pack are determined as billable and monetary values are assigned by operators for different service pack-based events in the Cisco MSX. The event generation and billing calculation are scheduled as per the pre-configured interval (either monthly or yearly).

You can manage the billing cycle and price definition for services using the Billing Services API. For more information on these API, refer to the Swagger documentation that can be accessed from MSX portal > Account Settings > Swagger > Billing Services API

  • To filter the billing events by services and to define a prorated price, use Billing Events (Billing Event Controller) section of the Billing Services API.

  • To manage the pricing definition for the service pack, use Billing Prices (Billing Price Controller) section of the Billing Services API. For example, to define a price definition for a service, use POST /api/v8/prices API. 

    {
"name": "Device Price"
"description": "Pricing Details for Device Types",
"type": "Device"
"subtype": "Cisco CSR 1000V"
"source": "customer_name"
"service": "sdbranch"
"billing period": "-1/daily/monthly/yearly/minute" millis
"price": 250.0
"tenantID": "tenant id value"
}

    Where:

    1. Set the billing period attribute to:

      1. -1, to set a non-recurring/single billing instance.

      2. Monthly/yearly/minute values in milliseconds. For example, for monthly the value is 2629800000 milliseconds.

    2. Set the service value as the name of the Service Pack for which the price definition must be applied.

  • To manage a billing cycle, use the Billing Cycle (Billing Cycle Controller) section of the Billing Services API.

From the Billing/Metering category, assign the following permissions to a user to run this API.

  • Event (View)

  • Price (View and Manage)

Using this procedure, you can view the various billing activities across Cisco MSX system. To manage these billing activities, use the APIs described above.

Procedure

Step 1

Log in to the Cisco MSX portal using your credentials.
Step 2

From the left pane, choose Tenant Workspace > Billing.

The Billing window is displayed.

Step 3

Select a tenant.

Note 

Assign a service pack offer, if the tenant had not subscribed to any of the offers. For more information, see Subscribing the Service Pack Offer from Tenant Workspace.

Step 4

View the billing summary of the assigned service pack offers.

  1. Select a service pack offer to get the expanded view of the offer price and other billing events (such as create site and add device) summary for each month.

    The total billing amount of all the subscribed service offers for each month are displayed on the right pane.

    Figure 1. Billing Window

Integrating Incident Tracking System (ServiceNow) with Cisco MSX

The Cisco MSX platform provides Incident Microservice API that enables you to integrate an incident tracking system (ServiceNow) with MSX platform and extends to all the MSX tenants. Using this API, you can create, update, cancel, close, and delete an incident using the access token. While deploying MSX, incident system is also onboarded during the installation. The service providers should have a ServiceNow account to create and manage incident tickets.

The prerequisites to create tickets and change request is to configure an incident service after deploying the MSX. Using V8 configurations, multiple ServiceNow login accounts are mapped to tenants.

Sample API configurations

Create new incident

v1/incident
{
  "attributes": {
    "additionalProp1": {}
  },
  "category": "inquiry",
  "description": "string",
  "impact": "Low",
  "priority": "Planning",
  "severity": "Low",
  "state": "New",
  "subcategory": "string",
  "tenant": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "urgency": "Low"
}

V8 Configuration

{
  "clientId": "b5c011a8db00301040ecb0b86b63b7b3",
  "clientSecret": "Cisco@123",
  "domain": "dev64108.service-now.com",
  "password": "Cisco@123",
  "userName": "admin",
  "criticalEvent": true,
  "tenantId": "70ef3a35-d23e-482e-a31d-0f568cc02ab3",
  "proxy":"http://proxy.esl.cisco.com:80"
}

Note

The tenantId is optional. By default, tenantId global ServiceNow instance is mapped to a internal global tenantId.

The use cases of integrating ServiceNow with MSX are:

  • Vulnerability: To monitor or detect device vulnerability in MSX.

  • Software device compliance: To track the device software compliance in MSX.

  • MSX creates tickets automatically when any critical event log occurs.

Incident services are capable of managing tickets that are created on service now. Users can directly create an incident on the ServiceNow and later use the incident ID to track services in the MSX. It is referred to as bidirectional flow for managing incident services, change requests, and approvals.

Use the Incident Microservice API for the following:

  • Provide the authentication settings that helps to establish handshake with an incident tracking system, use the Configuration Controller section of the Incident Microservice API.

  • Manage the incident, use the Incident Controller section of the Incident Microservice API.

  • Manage the change request, use the Change Requests Controller section of the Incident Microservice API.

  • Manage the approvals of the change request, use the Change Requests Approvals Controller section of the Incident Microservice API.

  • Manage several tasks involved in the change request, use the Change Requests Tasks Controller section of the Incident Microservice API.

From the Integrations, Settings, and Logs category, assign the Incidents (View and Manage) permission to a user to run this API.

For more information on this API, refer to the Swagger documentation that can be accessed from MSX portal > Account Settings > Swagger > Incident Microservice API.

Managing Device Compliance Vulnerability Using API

The Cisco MSX platform now detects and reports the software compliance vulnerabilities for both the Cisco devices and third-party software devices using the Vulnerability Service API.


Note

The Cisco Product Security Incident Response Team (PSIRT) manages the investigation and public reporting of security vulnerability information of the Cisco products and networks.

To register a product for vulnerability inspection, use the POST API in the Registration section of the Vulnerability Service API.

For more information on this API, see the Swagger documentation that can be accessed from MSX portal > Account Settings > Swagger > Vulnerability Service API.


Note

Only users with the following permissions from the Integrations, Settings, and Logs category will be able to run this API:

  • Vulnerability (View permission)

  • Vulnerability (Manage permission)

The Cisco Vulnerability Service ingests vulnerability data feed (available in the JSON format) from National Vulnerability Database (NVD) or Common Vulnerabilities and Exposures (CVE) to the Cisco MSX. The Vulnerability Service monitors the existing Cisco MSX device inventory table on a scheduled basis.

When a device is monitored for vulnerabilities, a registration is created in vulnerability service automatically, and the service will watch for vulnerabilities for those devices, publishing messages with vulnerability details that the platform uses to update the vulnerability state of devices.

You can add a device and enable compliance monitoring capability to ensures that the device that is configured to a set of standards remains in that state until it is changed. For more information about adding a device and configuring the compliance for devices, see the "Device Compliance" section in the Cisco Managed Services Accelerator (MSX) Managed Device Service Pack Documentation.

To monitor the device vulnerablity status, click Tenant Workspace > Devices. The Vulnerablity section displays the list of all the vulnerability information of the selected device. For more information, see the "Viewing Device Vulnerabilities" section in the Cisco Managed Services Accelerator (MSX) Managed Device Service Pack Documentation.

The Cisco MSX platform sends an email notification to all the tenants regarding the captured vulnerability information of the registered devices. The tenant's email addresses are stored and vulnerabilities are tracked as events in the Notification window. Update the notification services to handle the tenant-based emails. For more information, see Enabling Notifications for Events.

The Cisco MSX fetches the email address of the tenant that is available as a part of the payload and builds an email. This email will contain the list of discovered vulnerabilities of the devices with URL and severity level of the devices is also mentioned for the users to know the status of the devices.

To enable the Vulnerability Service to monitor the device vulnerability, onboard and publish the Vulnerability Service component on the Cisco MSX platform to detect and report the existing software compliance vulnerability. For more information about onboarding new services, see Onboarding and Deploying Component into Cisco MSX.

Validating the Smart Account License Using API

The tenants can log into MSX using the Cisco.com SSO credentials and select a service offer for a subscription. The Cisco MSX platform provides Licensing Service API to validate the list of smart accounts, virtual accounts, and licenses associated with the Cisco.com user's account. Only based on the authentication the users are allowed to proceed with the offer subscription process.

You can manage the configurations of the Licensing Service API as follows:

  • To manage the service configuration required for licensing and smart account, use the Configuration Controller section of the Licensing Service API.

  • To fetch the smart account list or virtual account list, use the Account Controller section of the Licensing Service API.

  • To fetch the smart account list, use the Licenses Controller section of the Licensing Service API.

From the Service, Configurations, and Devices category, assign the Licensing (View and Manage) permission to a user to run this API.

For more information on these APIs, refer to the Swagger documentation that can be accessed for MSX portal > Account Settings > Swagger > Licensing Service API.