Business Critical Services(BCS) Operational Insights API

Software Track

This API gives insights into what versions of software you are advised to run and how compliant your network is. It is sub-divided in the following resources:

  • /softwareTrack/summary
  • /softwareTrack/summary/:softwareTrackId
  • /softwareTrack/members
  • /softwareTrack/softwareMaintenanceUpgradeCompliance
  • /softwareTrack/softwareMaintenanceUpgradeRecommendations

NOTE: The last two (2) are only applicable for such platforms like IOS-XR that use Software Maintenance Upgrades (SMUs) and Package Installation Envelopes (PIEs.)

Software Tracks are used to manage Cisco software environments. Many large Cisco customer networks require 10-20 different software versions. These different version requirements are normally based on unique hardware, modules, and feature requirements. They can also include availability or strategy requirements.

As a BCS customer, you can work with your Network Consulting Engineer (NCE) to define unique software areas called Software Tracks. For each track the standard software versions are identified. This is an ongoing process between customer and NCE as software needs keep changing over time. The goal of Software Tracks is to improve software reliability and reduce operational cost by optimizing the Cisco software selection.

Once these unique software areas are identified, the Software Tracks API provides a way to do device-level version compliance assessment and software risk within an identified software group.

The API identifies software version compliance within identified tracks. Compliance is obtained by running a standard or certified version within the identified software track. Organizations should strive for the highest level of version compliance possible, knowing that individual device constraints or migration possibilities exist.

Summary

This resource provides the summary of the tracks, compliance with the identified standard version, the track rating, etc.

Below is an example response:

json
Copy{
    "softwareType": "IOS XR",
    "softwareTrackCandidateVersion": "",
    "softwareTrackComments": "Created By Default on 14-OCT-17",
    "softwareTrackCompliantDeviceCount": 0,
    "softwareTrackDescription": "IOS XR",
    "softwareTrackId": 343768,
    "softwareTrackLastModifiedDate": "2019-04-15",
    "softwareTrackName": "IOS XR",
    "softwareTrackNonCompliantDeviceCount": 43,
    "softwareTrackCompliancePercent": 0.0,
    "softwareTrackFlexibleCompliancePercent": 0.0,
    "softwareTrackPrevious1PackageInstallationEnvelopeCriteria": "Ignore For Conformance",
    "softwareTrackPrevious1SoftwareMaintenanceUpdateCriteria": "Ignore For Conformance",
    "softwareTrackPrevious2PackageInstallationEnvelopeCriteria": "Require Exact Match",
    "softwareTrackPrevious2SoftwareMaintenanceUpdateCriteria": "Require Exact Match",
    "softwareTrackPreviousCompliantDeviceCount": 0,
    "softwareTrackPreviousVersion1": "",
    "softwareTrackPreviousVersion2": "",
    "softwareTrackRating": "Poor",
    "softwareTrackRecommendationDate": null,
    "softwareTrackSoftwareMaintenanceUpdateCompliancePercent": null,
    "softwareTrackStandardPackageInstallationEnvelopeCriteria": "Ignore For Conformance",
    "softwareTrackStandardSoftwareMaintenanceUpdateCount": null,
    "softwareTrackStandardSoftwareMaintenanceUpdateCriteria": "Ignore For Conformance",
    "softwareTrackStandardVersion": "6.1.3",
    "softwareTrackStatus": "Other",
    "softwareTrackTotalDeviceCount": 43,
    "softwareTrackTotalVersionCount": 24,
    "softwareTrackUpgradeReason": "Planned Maintenance"
}

In the above output we can see that this is a track for IOS XR devices. The track rating is set to Poor because none of the 43 devices are compliant with the proposed software version of 6.1.3.

Track Rating has these values:

  • Poor: less than 60% of the devices is compliant
  • Fair: between 60% - 89% of the devices are compliant
  • Good: at least 90% of the devices are compliant

Per track the API can show you up to two (2) previous recommendations. This is visible in the TrackPrevious attributes. This is important to understand the meaning of what Compliant, PreviousCompliant, and FlexibleCompliant means:

Compliant means you are running the current recommended version. PreviousCompliant means the devices are running any of the previous versions. FlexibleCompliant means you are running any of the current or previous versions.

There are also some attributes with Criteria in their name. These are only relevant for devices using SMUs or PIEs. They define the requirements for SMUs and PIEs to be compliant. Three possibilities exist for both SMUs and PIES:

  • Ignore for conformance: Any SMU or PIE can be installed. It does not affect conformance.
  • Require Exact Match: The SMUs or PIEs listed for this track are needed for conformance. Not more, not less.
  • Match but ignore extras: The SMUs or PIEs listed for this track are needed for conformance. Others may be there but do not impact conformance.

To see the list of PIEs and SMUs in the track, refer to the /softwareTrack/softwareMaintenanceUpgradeRecommendations endoint.

Members

This API resource provides device-level conformance details for the current and previous versions. It also gives a summary of Software Maintenance Update and Package Installation Envelope Compliance as applicable.

Below you can see an example:

json
Copy{
    "deviceId": 26364425,
    "isSoftwareTrackCompliant": false,
    "isSoftwareTrackFlexibleCompliant": false,
    "softwareTrackId": 254863,
    "softwareTrackName": "MDS 9100 Series Multilayer Fabric Switches",
    "softwareTrackPackageInstallationEnvelopeCompliance": "N/A - OS Version Non Conforming",
    "isSoftwareTrackPreviousCompliant": false,
    "softwareTrackSoftwareMaintenanceUpdateCompliance": "N/A - OS Version Non Conforming",
    "softwareTrackSoftwareMaintenanceUpdateCompliantCount": 0,
    "softwareTrackSoftwareMaintenanceUpdateExtraCount": 0,
    "softwareTrackSoftwareMaintenanceUpdateMissingCount": 0,
    "softwareTrackStandardSoftwareMaintenanceUpdateCount": null
}

We see that deviceId 26364425 is a member of the MDS 9100 Series Multilayer Fabric Switches software track with id 254863, and is not compliant with the track. For both the SMU and PIE the compliance is set to N/A - OS Version Non Conforming. This indicates that the Software Version running on the system is already non-compliant with the Standard version. Therefor the system did not do the additional compliance check for SMUs or PIEs.

Other Compliance values can be:

  • Conforming: The device is fully compliant with the software track
  • Conforming with Extras: The device is fully compliant with the software tracks, even though additional SMUs or PIEs were found
  • Non Conforming: The device is not conforming
  • Ignored for Conformance: There are no SMUs or PIEs to be evaluated so it is considered for conformance assessment
  • N/A - OS Version Non Confirming: The OS installed on the device is not the standard version. Additional SMU or PIE conformance checks are not done

Software Maintenance Upgrade Compliance

For applicable tracks, this API resource provides SMU/PIE Compliance status for each SMU/PIE on the device and the actions to be taken against each SMU/PIE on a device to achieve higher compliance.

NOTE: This resource is only applicable for such platforms like IOS-XR that use Software Maintenance Upgrades (SMUs) and Package Installation Envelopes (PIEs.)

json
Copy{
  "deviceId": 19811003,
  "softwareMaintenanceUpdatePackageInstallationEnvelopeType": "Committed",
  "softwareName": "ncs5500-isis-2.1.0.0-r652",
  "softwareRole": "PKG",
  "softwareTrackDeviceSoftwareMaintenanceUpdatePIEAction": "Add",
  "softwareTrackDeviceSoftwareMaintenanceUpdatePIECompliance": "Non-Compliant",
  "softwareTrackId": 343768,
  "softwareTrackName": "NCS5500"
}

In this example we can see device with id 19811003, as member of trackId 254863 currently not compliant to install PIE ncs5500-isis-2.1.0.0-r652. The softwareRole attribute defines whether it's a SMU or PIE. The attribute softwareTrackDeviceMaintenanceUpgradePackageInstallationEnvelopeAction defines what action is required to do with the given softwareName to achieve compliance. It can be either Add, Delete, or None. The last would mean no action is to be taken.

Software Maintenance Upgrade Recommendations

For applicable tracks, this API resource provides the information regarding SMU or PIE recommended values defined for each of Current, Previous1, and Previous2 versions.

NOTE: This resource is only applicable for such platforms like IOS-XR that use Software Maintenance Upgrades (SMUs) and Package Installation Envelopes (PIEs.)

Below you can see an example output:

json
Copy{
    "softwareName": "ncs5500-fwding-3.0.0.1-r613.CSCvc64943",
    "softwareRole": "SMU",
    "softwareTrackId": 343768,
    "softwareTrackName": "IOS XR",
    "softwareTrackRecommendationHistory": "Previous1"
},
{
    "softwareName": "ncs5500-os-support-4.0.0.1-r613.CSCvc64943",
    "softwareRole": "SMU",
    "softwareTrackId": 343768,
    "softwareTrackName": "IOS XR",
    "softwareTrackRecommendationHistory": "Previous1"
}

This output mentions that for track 343768, the Previous1 recommendation was to install two (2) SMUs with image name ncs5500-fwding-3.0.0.1-r613.CSCvc64943 and ncs5500-os-support-4.0.0.1-r613.CSCvc64943. The field softwareTrackRecommendationHistory indicates to which recommendation it belongs. If it's set to the string "Current" it means it is the version you agreed with the NCE today. If it is set to "Previous1" it means it was the previous version. "Previous2" indicates it was the one just before that.

Next