Using REST APIs to manage Spectrum Maintenance Schedules for models
search cancel

Using REST APIs to manage Spectrum Maintenance Schedules for models

book

Article ID: 196313

calendar_today

Updated On: 08-01-2024

Products

Spectrum Network Observability

Issue/Introduction

We are using REST API to manage our device maintenance schedules. What are the best practices?

How can we use APIs or command at the CLI to associate and break associations between Maintenance Schedules and models?

Environment

All supported DX NetOps Spectrum releases

Resolution

A user can utilize RESTful commands to manage Maintenance mode on devices. 

The Schedule gets created per Landscape. If there is only one Landscape in the environment, then the Landscape does not have to be defined in the initial call to create the Schedule. However, in a DSS environment, the Schedule will need to be created on the same landscape as where the model to be associated with the schedule resides. To do this, the landscapeid must be determined. This is the same as landscape_handle, except landscapeid is in decimal format, and would need to be converted to hex for landscape_handle.

In the following steps replace:

  • <scheme> with the OC Host scheme, http or https
  • <OC_Host> with the OC Host name
  • <PORT> with the configured OC access port

To find and convert the landscape ID for Maintenance Schedule creation:

  1. Use this URL with the target models model_handle to determine which Landscape it resides on. Can also be reviewed in the OC UI.
    • <scheme>://<OC_Host>:<PORT>/spectrum/restful/model/<Model_MH>?attr=0x129ac
    • Replace <Model_MH> with the target devices Model_Handle Attribute value.
  2. The returned landscapeid needs to be converted to hex. This can be scripted or use one of the many free sites available such as the following example:
    1. https://www.rapidtables.com/convert/number/decimal-to-hex.html

To create the Maintenance Schedule model we'd issue a call like this sample. It can also be created through the OC UI.

<scheme>://<OC_Host>:<PORT>/spectrum/restful/model?mtypeid=0x10456&attr=0x129ac&val=0x100000&attr=0x12bbc&val=TestSchedule&attr=0x1298f&val=16&attr=0x1298e&val=20&attr=0x12993&val=54000&attr=0x129e4&val=29&attr=0x12992&val=06&attr=0x129e3&val=120&attr=0x12994&val=6

Breaking down the Attributes and their values from that call we have the following. Set your values as needed.

  • mtypeid=0x10456 = Schedule Model Type
  • attr=0x12bbc = Schedule Name
  • attr=0x1298f = Hour
  • attr=0x1298e = Minute
  • attr=0x12993 = Duration
  • attr=0x129e4 = Day
  • attr=0x12992 = Month - (NOTE month is base-0, so Jan - 00, Feb = 01, etc)
  • attr=0x129e3 = Start Year
  • attr=0x12994 = Recurrence (1=Always, 2=Daily, 3=Weekly, 4=Monthly, 5=Yearly, 6=None)

With the Maintenance Schedule created, we need to find the model_handle of the Schedule. To find this follow these steps.

  1. Use the OC UI. Go to the Locater tab. Search for Schedules and find the Model_Handle attribute value in the target Maintenance Schedules Attributes tab.
  2. Use the SS CLI commands. As the Spectrum install owner on the SS hosting the target Maintenance Schedule and Models:
    1. Go to $SPECROOT/vnmsh
    2. Run this to connect to the Spectrum CLI:
      • "./connect"
    3. Run this to see all Maintenance Schedule models on the SS.
      • ./show models mth=0x10456
    4. Sample output:
      • [spectrum@<OC_Host> vnmsh]$ ./show models mth=0x10456
        MHandle     MName                             MTypeHnd    MTypeName
        0x1008161   Every week Mon thru Fri at 10:15  0x10456     Schedule
        0x1008160   Every month on the 1st at 10:15   0x10456     Schedule
        0x100815f   Every week Mon thru Fri at 10:10  0x10456     Schedule
        0x100815e   Every week on Tue  at 5:10 PM     0x10456     Schedule
        0x100689c   Every week Mon thru Fri from 9 A  0x10456     Schedule
        0x1005975   Every week on Mon, Tue, Wed, Thu  0x10456     Schedule
        0x1005972   Every week on Sun and Sat  at 12  0x10456     Schedule
        0x100006a   Every week Mon thru Fri from 6 A  0x10456     Schedule
        0x1000069   Every week Mon thru Fri from 8 A  0x10456     Schedule
        0x1000068   Every day from 6 PM for 13 hours  0x10456     Schedule
        0x1000067   Every day from 7 AM for 11 hours  0x10456     Schedule
        0x1000066   24/7                              0x10456     Schedule
        0x1000049   Every month on the 15th at 12 AM  0x10456     Schedule
        0x1000048   Every month on the 1st at 12 AM   0x10456     Schedule
    5. Run this to see a specific Maintenance Schedule whose name is known.
      • ./show models mth=0x10456 mname=<Name>
        • Replace <Name> with the Maintenance Schedule model name. 
      • Example for schedule named 24x7 from above sample output.
        • [spectrum@<OC_Host> vnmsh]$ ./show models mth=0x10456 mname=24/7
          MHandle     MName                             MTypeHnd    MTypeName
          0x1000066   24/7                              0x10456     Schedule

Last part to find is the Model_Handle for the target model to associate the Maintenance Schedule to.

  • Use the OC UI to find the model and then it's Model_Handle attribute value via the Attributes tab.
  • Use the CLI on the SS hosting the model.
    • Go to $SPECROOT/vnmsh
    • Run this to connect to the Spectrum CLI:
      • "./connect"
    • Run this to see all models on the SS for a given device.
      • ./show models mname=<ModelName>
      • Replace <ModelName> with the name of the target model.
    • Sample output for a limited set targeting only the parent device, a Rtr_Cisco Model_Type_Name (0x21000c) device.
      • [spectrum@<OC_Host> vnmsh]$ ./show models mth=0x21000c mname=Sim30253
        MHandle      MName       MTypeHnd  MTypeName
        0x1008480   Sim30253  0x21000c    Rtr_Cisco

We can now associate a Maintenance Schedule with the target model. To so we'd use the following URL.

  • This will associate device with Model_Handle 0x10000c4 to Maintenance Schedule with Model_Handle 0x1000071.
    • <scheme>://<OC_Host>:<PORT>/spectrum/restful/associations/relation/0x10034/leftmodel/0x10000c4/rightmodel/0x1000071

How to destroy the association that was created? Use the following steps in the SS CLI. This is done in the Spectrum CLI via ./connect out of $SPECROOT/vnmsh.

  1. In this lab sample ROUTER is the device model name and 24/7 is the Maintenance Schedule model name.
    1. This will list the models relationships and show the relationship it has to Maintenance Schedules.
      • The 0x10069c8 value in the command is the Model_Handle attribute value the target model is assigned.
      • [spectrum@SSHost vnmsh]$ ./show associations mh=0x10069c8
        LMHandle    LMName                            Relation                         RMHandle    RMName
        0x1000004   Universe                          Collects                         0x10069c8   ROUTER
        0x10069c8   ROUTER                       MAINT_SCHEDULE                   0x1000066   24/7
    2. This can be used with the pipe symbol to limit the results further
      • [spectrum@SSHost vnmsh]$ ./show associations mh=0x1000066 | grep ROUTER
        0x10069c8   ROUTER                       MAINT_SCHEDULE                   0x1000066   24/7
  2. We can now run a destroy command to break the relationship using that information.
    • This is done in the Spectrum CLI via ./connect out of $SPECROOT/vnmsh. 
    • Command syntax:
      •  ./destroy association rel=<RelationshipType> lmh=<LeftModlelHandle_Device_ModelHandle> rmh=<RightModlelHandle_MaintenanceSchedule_ModelHandle>
    • Sample run and output using above sample info:
      • [spectrum@SSHost vnmsh]$ ./destroy association rel=MAINT_SCHEDULE lmh=0x10069c8 rmh=0x1000066
        destroy association: are you sure ? Y
        destroy association: successful
  3. We can then confirm the relationship has been removed.
    • [spectrum@SSHost vnmsh]$ ./show associations mh=0x10069c8
      LMHandle    LMName                            Relation                         RMHandle    RMName
      0x1000004   Universe                          Collects                         0x10069c8   ROUTER
      [spectrum@SSHost vnmsh]$ ./show associations mh=0x1000066 | grep ROUTER
      [spectrum@SSHost vnmsh]$

Additional Information

Restful Web API reference documentation topic

The information here can be used in custom scripts. When using curl calls for the Spectrum URLs usernames, passwords and other flags are required. A sample URL to create the relationship would look like this.

  • Use the following:
    • curl -v -u <ValidSpecUser:<UserPassword> --insecure -X POST '<scheme>://<OC_Host>:<PORT>/spectrum/restful/associations/relation/0x10034/leftmodel/<DeviceModelHandle>/rightmodel/<MaintenanceScheduleModelHandle>'
  • Replace:
    • <ValidSpecUser:<UserPassword> with a valid user and it's password.
    • <scheme> with the OC Host scheme, http or https
    • <OC_Host> with the OC Host name
    • <PORT> with the configured OC access port
    • <DeviceModelHandle> with the target device Model_Handle attribute value.
    • <MaintenanceScheduleModelHandle> with the target Maintenance Schedule Model_Handle attribute value
Powered by Wolken Software